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