begriffs open source - freertos/blob - include/portable.h

   1 /*
   2  * FreeRTOS Kernel <DEVELOPMENT BRANCH>
   3  * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
   4  *
   5  * SPDX-License-Identifier: MIT
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy of
   8  * this software and associated documentation files (the "Software"), to deal in
   9  * the Software without restriction, including without limitation the rights to
  10  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  11  * the Software, and to permit persons to whom the Software is furnished to do so,
  12  * subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in all
  15  * copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  19  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  20  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  21  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  22  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  *
  24  * https://www.FreeRTOS.org
  25  * https://github.com/FreeRTOS
  26  *
  27  */
  28
  29 /*-----------------------------------------------------------
  30 * Portable layer API.  Each function must be defined for each port.
  31 *----------------------------------------------------------*/
  32
  33 #ifndef PORTABLE_H
  34 #define PORTABLE_H
  35
  36 /* Each FreeRTOS port has a unique portmacro.h header file.  Originally a
  37  * pre-processor definition was used to ensure the pre-processor found the correct
  38  * portmacro.h file for the port being used.  That scheme was deprecated in favour
  39  * of setting the compiler's include path such that it found the correct
  40  * portmacro.h file - removing the need for the constant and allowing the
  41  * portmacro.h file to be located anywhere in relation to the port being used.
  42  * Purely for reasons of backward compatibility the old method is still valid, but
  43  * to make it clear that new projects should not use it, support for the port
  44  * specific constants has been moved into the deprecated_definitions.h header
  45  * file. */
  46 #include "deprecated_definitions.h"
  47
  48 /* If portENTER_CRITICAL is not defined then including deprecated_definitions.h
  49  * did not result in a portmacro.h header file being included - and it should be
  50  * included here.  In this case the path to the correct portmacro.h header file
  51  * must be set in the compiler's include path. */
  52 #ifndef portENTER_CRITICAL
  53     #include "portmacro.h"
  54 #endif
  55
  56 #if portBYTE_ALIGNMENT == 32
  57     #define portBYTE_ALIGNMENT_MASK    ( 0x001f )
  58 #elif portBYTE_ALIGNMENT == 16
  59     #define portBYTE_ALIGNMENT_MASK    ( 0x000f )
  60 #elif portBYTE_ALIGNMENT == 8
  61     #define portBYTE_ALIGNMENT_MASK    ( 0x0007 )
  62 #elif portBYTE_ALIGNMENT == 4
  63     #define portBYTE_ALIGNMENT_MASK    ( 0x0003 )
  64 #elif portBYTE_ALIGNMENT == 2
  65     #define portBYTE_ALIGNMENT_MASK    ( 0x0001 )
  66 #elif portBYTE_ALIGNMENT == 1
  67     #define portBYTE_ALIGNMENT_MASK    ( 0x0000 )
  68 #else /* if portBYTE_ALIGNMENT == 32 */
  69     #error "Invalid portBYTE_ALIGNMENT definition"
  70 #endif /* if portBYTE_ALIGNMENT == 32 */
  71
  72 #ifndef portUSING_MPU_WRAPPERS
  73     #define portUSING_MPU_WRAPPERS    0
  74 #endif
  75
  76 #ifndef portNUM_CONFIGURABLE_REGIONS
  77     #define portNUM_CONFIGURABLE_REGIONS    1
  78 #endif
  79
  80 #ifndef portHAS_STACK_OVERFLOW_CHECKING
  81     #define portHAS_STACK_OVERFLOW_CHECKING    0
  82 #endif
  83
  84 #ifndef portARCH_NAME
  85     #define portARCH_NAME    NULL
  86 #endif
  87
  88 #ifndef portBASE_TYPE_ENTER_CRITICAL
  89     #define portBASE_TYPE_ENTER_CRITICAL()    taskENTER_CRITICAL()
  90 #endif
  91
  92 #ifndef portBASE_TYPE_EXIT_CRITICAL
  93     #define portBASE_TYPE_EXIT_CRITICAL()    taskEXIT_CRITICAL()
  94 #endif
  95
  96 #ifndef portGET_CURRENT_TOP_OF_STACK
  97     #define portGET_CURRENT_TOP_OF_STACK( pxCurrentTopOfStack )    { pxCurrentTopOfStack = ( StackType_t * ) pxCurrentTCB->pxTopOfStack; }
  98 #endif
  99
 100 #ifndef configSTACK_DEPTH_TYPE
 101     #define configSTACK_DEPTH_TYPE    StackType_t
 102 #endif
 103
 104 #ifndef configSTACK_ALLOCATION_FROM_SEPARATE_HEAP
 105     /* Defaults to 0 for backward compatibility. */
 106     #define configSTACK_ALLOCATION_FROM_SEPARATE_HEAP    0
 107 #endif
 108
 109 #include "mpu_wrappers.h"
 110
 111 /* *INDENT-OFF* */
 112 #ifdef __cplusplus
 113     extern "C" {
 114 #endif
 115 /* *INDENT-ON* */
 116
 117 /*
 118  * Setup the stack of a new task so it is ready to be placed under the
 119  * scheduler control.  The registers have to be placed on the stack in
 120  * the order that the port expects to find them.
 121  *
 122  */
 123 #if ( portUSING_MPU_WRAPPERS == 1 )
 124     #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 )
 125         StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
 126                                              StackType_t * pxEndOfStack,
 127                                              TaskFunction_t pxCode,
 128                                              void * pvParameters,
 129                                              BaseType_t xRunPrivileged,
 130                                              xMPU_SETTINGS * xMPUSettings ) PRIVILEGED_FUNCTION;
 131     #else
 132         StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
 133                                              TaskFunction_t pxCode,
 134                                              void * pvParameters,
 135                                              BaseType_t xRunPrivileged,
 136                                              xMPU_SETTINGS * xMPUSettings ) PRIVILEGED_FUNCTION;
 137     #endif /* if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) */
 138 #else /* if ( portUSING_MPU_WRAPPERS == 1 ) */
 139     #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 )
 140         StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
 141                                              StackType_t * pxEndOfStack,
 142                                              TaskFunction_t pxCode,
 143                                              void * pvParameters ) PRIVILEGED_FUNCTION;
 144     #else
 145         StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
 146                                              TaskFunction_t pxCode,
 147                                              void * pvParameters ) PRIVILEGED_FUNCTION;
 148     #endif
 149 #endif /* if ( portUSING_MPU_WRAPPERS == 1 ) */
 150
 151 /* Used by heap_5.c to define the start address and size of each memory region
 152  * that together comprise the total FreeRTOS heap space. */
 153 typedef struct HeapRegion
 154 {
 155     uint8_t * pucStartAddress;
 156     size_t xSizeInBytes;
 157 } HeapRegion_t;
 158
 159 /* Used to pass information about the heap out of vPortGetHeapStats(). */
 160 typedef struct xHeapStats
 161 {
 162     size_t xAvailableHeapSpaceInBytes;      /* The total heap size currently available - this is the sum of all the free blocks, not the largest block that can be allocated. */
 163     size_t xSizeOfLargestFreeBlockInBytes;  /* The maximum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */
 164     size_t xSizeOfSmallestFreeBlockInBytes; /* The minimum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */
 165     size_t xNumberOfFreeBlocks;             /* The number of free memory blocks within the heap at the time vPortGetHeapStats() is called. */
 166     size_t xMinimumEverFreeBytesRemaining;  /* The minimum amount of total free memory (sum of all free blocks) there has been in the heap since the system booted. */
 167     size_t xNumberOfSuccessfulAllocations;  /* The number of calls to pvPortMalloc() that have returned a valid memory block. */
 168     size_t xNumberOfSuccessfulFrees;        /* The number of calls to vPortFree() that has successfully freed a block of memory. */
 169 } HeapStats_t;
 170
 171 /*
 172  * Used to define multiple heap regions for use by heap_5.c.  This function
 173  * must be called before any calls to pvPortMalloc() - not creating a task,
 174  * queue, semaphore, mutex, software timer, event group, etc. will result in
 175  * pvPortMalloc being called.
 176  *
 177  * pxHeapRegions passes in an array of HeapRegion_t structures - each of which
 178  * defines a region of memory that can be used as the heap.  The array is
 179  * terminated by a HeapRegions_t structure that has a size of 0.  The region
 180  * with the lowest start address must appear first in the array.
 181  */
 182 void vPortDefineHeapRegions( const HeapRegion_t * const pxHeapRegions ) PRIVILEGED_FUNCTION;
 183
 184 /*
 185  * Returns a HeapStats_t structure filled with information about the current
 186  * heap state.
 187  */
 188 void vPortGetHeapStats( HeapStats_t * pxHeapStats );
 189
 190 /*
 191  * Map to the memory management routines required for the port.
 192  */
 193 void * pvPortMalloc( size_t xWantedSize ) PRIVILEGED_FUNCTION;
 194 void * pvPortCalloc( size_t xNum,
 195                      size_t xSize ) PRIVILEGED_FUNCTION;
 196 void vPortFree( void * pv ) PRIVILEGED_FUNCTION;
 197 void vPortInitialiseBlocks( void ) PRIVILEGED_FUNCTION;
 198 size_t xPortGetFreeHeapSize( void ) PRIVILEGED_FUNCTION;
 199 size_t xPortGetMinimumEverFreeHeapSize( void ) PRIVILEGED_FUNCTION;
 200 void xPortResetHeapMinimumEverFreeHeapSize( void ) PRIVILEGED_FUNCTION;
 201
 202 #if ( configSTACK_ALLOCATION_FROM_SEPARATE_HEAP == 1 )
 203     void * pvPortMallocStack( size_t xSize ) PRIVILEGED_FUNCTION;
 204     void vPortFreeStack( void * pv ) PRIVILEGED_FUNCTION;
 205 #else
 206     #define pvPortMallocStack    pvPortMalloc
 207     #define vPortFreeStack       vPortFree
 208 #endif
 209
 210 /*
 211  * This function resets the internal state of the heap module. It must be called
 212  * by the application before restarting the scheduler.
 213  */
 214 void vPortHeapResetState( void ) PRIVILEGED_FUNCTION;
 215
 216 #if ( configUSE_MALLOC_FAILED_HOOK == 1 )
 217
 218 /**
 219  * task.h
 220  * @code{c}
 221  * void vApplicationMallocFailedHook( void )
 222  * @endcode
 223  *
 224  * This hook function is called when allocation failed.
 225  */
 226     void vApplicationMallocFailedHook( void );
 227 #endif
 228
 229 /*
 230  * Setup the hardware ready for the scheduler to take control.  This generally
 231  * sets up a tick interrupt and sets timers for the correct tick frequency.
 232  */
 233 BaseType_t xPortStartScheduler( void ) PRIVILEGED_FUNCTION;
 234
 235 /*
 236  * Undo any hardware/ISR setup that was performed by xPortStartScheduler() so
 237  * the hardware is left in its original condition after the scheduler stops
 238  * executing.
 239  */
 240 void vPortEndScheduler( void ) PRIVILEGED_FUNCTION;
 241
 242 /*
 243  * The structures and methods of manipulating the MPU are contained within the
 244  * port layer.
 245  *
 246  * Fills the xMPUSettings structure with the memory region information
 247  * contained in xRegions.
 248  */
 249 #if ( portUSING_MPU_WRAPPERS == 1 )
 250     struct xMEMORY_REGION;
 251     void vPortStoreTaskMPUSettings( xMPU_SETTINGS * xMPUSettings,
 252                                     const struct xMEMORY_REGION * const xRegions,
 253                                     StackType_t * pxBottomOfStack,
 254                                     configSTACK_DEPTH_TYPE uxStackDepth ) PRIVILEGED_FUNCTION;
 255 #endif
 256
 257 /**
 258  * @brief Checks if the calling task is authorized to access the given buffer.
 259  *
 260  * @param pvBuffer The buffer which the calling task wants to access.
 261  * @param ulBufferLength The length of the pvBuffer.
 262  * @param ulAccessRequested The permissions that the calling task wants.
 263  *
 264  * @return pdTRUE if the calling task is authorized to access the buffer,
 265  *         pdFALSE otherwise.
 266  */
 267 #if ( portUSING_MPU_WRAPPERS == 1 )
 268     BaseType_t xPortIsAuthorizedToAccessBuffer( const void * pvBuffer,
 269                                                 uint32_t ulBufferLength,
 270                                                 uint32_t ulAccessRequested ) PRIVILEGED_FUNCTION;
 271 #endif
 272
 273 /**
 274  * @brief Checks if the calling task is authorized to access the given kernel object.
 275  *
 276  * @param lInternalIndexOfKernelObject The index of the kernel object in the kernel
 277  *                                     object handle pool.
 278  *
 279  * @return pdTRUE if the calling task is authorized to access the kernel object,
 280  *         pdFALSE otherwise.
 281  */
 282 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) )
 283
 284     BaseType_t xPortIsAuthorizedToAccessKernelObject( int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION;
 285
 286 #endif
 287
 288 /* *INDENT-OFF* */
 289 #ifdef __cplusplus
 290     }
 291 #endif
 292 /* *INDENT-ON* */
 293
 294 #endif /* PORTABLE_H */