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 configSTACK_DEPTH_TYPE 97 #define configSTACK_DEPTH_TYPE StackType_t 98 #endif 99 100 #ifndef configSTACK_ALLOCATION_FROM_SEPARATE_HEAP 101 /* Defaults to 0 for backward compatibility. */ 102 #define configSTACK_ALLOCATION_FROM_SEPARATE_HEAP 0 103 #endif 104 105 #include "mpu_wrappers.h" 106 107 /* *INDENT-OFF* */ 108 #ifdef __cplusplus 109 extern "C" { 110 #endif 111 /* *INDENT-ON* */ 112 113 /* 114 * Setup the stack of a new task so it is ready to be placed under the 115 * scheduler control. The registers have to be placed on the stack in 116 * the order that the port expects to find them. 117 * 118 */ 119 #if ( portUSING_MPU_WRAPPERS == 1 ) 120 #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) 121 StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, 122 StackType_t * pxEndOfStack, 123 TaskFunction_t pxCode, 124 void * pvParameters, 125 BaseType_t xRunPrivileged, 126 xMPU_SETTINGS * xMPUSettings ) PRIVILEGED_FUNCTION; 127 #else 128 StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, 129 TaskFunction_t pxCode, 130 void * pvParameters, 131 BaseType_t xRunPrivileged, 132 xMPU_SETTINGS * xMPUSettings ) PRIVILEGED_FUNCTION; 133 #endif /* if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) */ 134 #else /* if ( portUSING_MPU_WRAPPERS == 1 ) */ 135 #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) 136 StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, 137 StackType_t * pxEndOfStack, 138 TaskFunction_t pxCode, 139 void * pvParameters ) PRIVILEGED_FUNCTION; 140 #else 141 StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, 142 TaskFunction_t pxCode, 143 void * pvParameters ) PRIVILEGED_FUNCTION; 144 #endif 145 #endif /* if ( portUSING_MPU_WRAPPERS == 1 ) */ 146 147 /* Used by heap_5.c to define the start address and size of each memory region 148 * that together comprise the total FreeRTOS heap space. */ 149 typedef struct HeapRegion 150 { 151 uint8_t * pucStartAddress; 152 size_t xSizeInBytes; 153 } HeapRegion_t; 154 155 /* Used to pass information about the heap out of vPortGetHeapStats(). */ 156 typedef struct xHeapStats 157 { 158 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. */ 159 size_t xSizeOfLargestFreeBlockInBytes; /* The maximum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */ 160 size_t xSizeOfSmallestFreeBlockInBytes; /* The minimum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */ 161 size_t xNumberOfFreeBlocks; /* The number of free memory blocks within the heap at the time vPortGetHeapStats() is called. */ 162 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. */ 163 size_t xNumberOfSuccessfulAllocations; /* The number of calls to pvPortMalloc() that have returned a valid memory block. */ 164 size_t xNumberOfSuccessfulFrees; /* The number of calls to vPortFree() that has successfully freed a block of memory. */ 165 } HeapStats_t; 166 167 /* 168 * Used to define multiple heap regions for use by heap_5.c. This function 169 * must be called before any calls to pvPortMalloc() - not creating a task, 170 * queue, semaphore, mutex, software timer, event group, etc. will result in 171 * pvPortMalloc being called. 172 * 173 * pxHeapRegions passes in an array of HeapRegion_t structures - each of which 174 * defines a region of memory that can be used as the heap. The array is 175 * terminated by a HeapRegions_t structure that has a size of 0. The region 176 * with the lowest start address must appear first in the array. 177 */ 178 void vPortDefineHeapRegions( const HeapRegion_t * const pxHeapRegions ) PRIVILEGED_FUNCTION; 179 180 /* 181 * Returns a HeapStats_t structure filled with information about the current 182 * heap state. 183 */ 184 void vPortGetHeapStats( HeapStats_t * pxHeapStats ); 185 186 /* 187 * Map to the memory management routines required for the port. 188 */ 189 void * pvPortMalloc( size_t xWantedSize ) PRIVILEGED_FUNCTION; 190 void * pvPortCalloc( size_t xNum, 191 size_t xSize ) PRIVILEGED_FUNCTION; 192 void vPortFree( void * pv ) PRIVILEGED_FUNCTION; 193 void vPortInitialiseBlocks( void ) PRIVILEGED_FUNCTION; 194 size_t xPortGetFreeHeapSize( void ) PRIVILEGED_FUNCTION; 195 size_t xPortGetMinimumEverFreeHeapSize( void ) PRIVILEGED_FUNCTION; 196 void xPortResetHeapMinimumEverFreeHeapSize( void ) PRIVILEGED_FUNCTION; 197 198 #if ( configSTACK_ALLOCATION_FROM_SEPARATE_HEAP == 1 ) 199 void * pvPortMallocStack( size_t xSize ) PRIVILEGED_FUNCTION; 200 void vPortFreeStack( void * pv ) PRIVILEGED_FUNCTION; 201 #else 202 #define pvPortMallocStack pvPortMalloc 203 #define vPortFreeStack vPortFree 204 #endif 205 206 /* 207 * This function resets the internal state of the heap module. It must be called 208 * by the application before restarting the scheduler. 209 */ 210 void vPortHeapResetState( void ) PRIVILEGED_FUNCTION; 211 212 #if ( configUSE_MALLOC_FAILED_HOOK == 1 ) 213 214 /** 215 * task.h 216 * @code{c} 217 * void vApplicationMallocFailedHook( void ) 218 * @endcode 219 * 220 * This hook function is called when allocation failed. 221 */ 222 void vApplicationMallocFailedHook( void ); 223 #endif 224 225 /* 226 * Setup the hardware ready for the scheduler to take control. This generally 227 * sets up a tick interrupt and sets timers for the correct tick frequency. 228 */ 229 BaseType_t xPortStartScheduler( void ) PRIVILEGED_FUNCTION; 230 231 /* 232 * Undo any hardware/ISR setup that was performed by xPortStartScheduler() so 233 * the hardware is left in its original condition after the scheduler stops 234 * executing. 235 */ 236 void vPortEndScheduler( void ) PRIVILEGED_FUNCTION; 237 238 /* 239 * The structures and methods of manipulating the MPU are contained within the 240 * port layer. 241 * 242 * Fills the xMPUSettings structure with the memory region information 243 * contained in xRegions. 244 */ 245 #if ( portUSING_MPU_WRAPPERS == 1 ) 246 struct xMEMORY_REGION; 247 void vPortStoreTaskMPUSettings( xMPU_SETTINGS * xMPUSettings, 248 const struct xMEMORY_REGION * const xRegions, 249 StackType_t * pxBottomOfStack, 250 configSTACK_DEPTH_TYPE uxStackDepth ) PRIVILEGED_FUNCTION; 251 #endif 252 253 /** 254 * @brief Checks if the calling task is authorized to access the given buffer. 255 * 256 * @param pvBuffer The buffer which the calling task wants to access. 257 * @param ulBufferLength The length of the pvBuffer. 258 * @param ulAccessRequested The permissions that the calling task wants. 259 * 260 * @return pdTRUE if the calling task is authorized to access the buffer, 261 * pdFALSE otherwise. 262 */ 263 #if ( portUSING_MPU_WRAPPERS == 1 ) 264 BaseType_t xPortIsAuthorizedToAccessBuffer( const void * pvBuffer, 265 uint32_t ulBufferLength, 266 uint32_t ulAccessRequested ) PRIVILEGED_FUNCTION; 267 #endif 268 269 /** 270 * @brief Checks if the calling task is authorized to access the given kernel object. 271 * 272 * @param lInternalIndexOfKernelObject The index of the kernel object in the kernel 273 * object handle pool. 274 * 275 * @return pdTRUE if the calling task is authorized to access the kernel object, 276 * pdFALSE otherwise. 277 */ 278 #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) ) 279 280 BaseType_t xPortIsAuthorizedToAccessKernelObject( int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION; 281 282 #endif 283 284 /* *INDENT-OFF* */ 285 #ifdef __cplusplus 286 } 287 #endif 288 /* *INDENT-ON* */ 289 290 #endif /* PORTABLE_H */ 291