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