portable.h 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223
  1. /*
  2. * FreeRTOS Kernel V10.4.4
  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. * Portable layer API. Each function must be defined for each port.
  30. *----------------------------------------------------------*/
  31. #ifndef PORTABLE_H
  32. #define PORTABLE_H
  33. /* Each FreeRTOS port has a unique portmacro.h header file. Originally a
  34. * pre-processor definition was used to ensure the pre-processor found the correct
  35. * portmacro.h file for the port being used. That scheme was deprecated in favour
  36. * of setting the compiler's include path such that it found the correct
  37. * portmacro.h file - removing the need for the constant and allowing the
  38. * portmacro.h file to be located anywhere in relation to the port being used.
  39. * Purely for reasons of backward compatibility the old method is still valid, but
  40. * to make it clear that new projects should not use it, support for the port
  41. * specific constants has been moved into the deprecated_definitions.h header
  42. * file. */
  43. #include "deprecated_definitions.h"
  44. /* If portENTER_CRITICAL is not defined then including deprecated_definitions.h
  45. * did not result in a portmacro.h header file being included - and it should be
  46. * included here. In this case the path to the correct portmacro.h header file
  47. * must be set in the compiler's include path. */
  48. #ifndef portENTER_CRITICAL
  49. #include "portmacro.h"
  50. #endif
  51. #if portBYTE_ALIGNMENT == 32
  52. #define portBYTE_ALIGNMENT_MASK ( 0x001f )
  53. #elif portBYTE_ALIGNMENT == 16
  54. #define portBYTE_ALIGNMENT_MASK ( 0x000f )
  55. #elif portBYTE_ALIGNMENT == 8
  56. #define portBYTE_ALIGNMENT_MASK ( 0x0007 )
  57. #elif portBYTE_ALIGNMENT == 4
  58. #define portBYTE_ALIGNMENT_MASK ( 0x0003 )
  59. #elif portBYTE_ALIGNMENT == 2
  60. #define portBYTE_ALIGNMENT_MASK ( 0x0001 )
  61. #elif portBYTE_ALIGNMENT == 1
  62. #define portBYTE_ALIGNMENT_MASK ( 0x0000 )
  63. #else
  64. #error "Invalid portBYTE_ALIGNMENT definition"
  65. #endif
  66. #ifndef portUSING_MPU_WRAPPERS
  67. #define portUSING_MPU_WRAPPERS 0
  68. #endif
  69. #ifndef portNUM_CONFIGURABLE_REGIONS
  70. #define portNUM_CONFIGURABLE_REGIONS 1
  71. #endif
  72. #ifndef portHAS_STACK_OVERFLOW_CHECKING
  73. #define portHAS_STACK_OVERFLOW_CHECKING 0
  74. #endif
  75. #ifndef portARCH_NAME
  76. #define portARCH_NAME NULL
  77. #endif
  78. #ifndef configSTACK_ALLOCATION_FROM_SEPARATE_HEAP
  79. /* Defaults to 0 for backward compatibility. */
  80. #define configSTACK_ALLOCATION_FROM_SEPARATE_HEAP 0
  81. #endif
  82. /* *INDENT-OFF* */
  83. #ifdef __cplusplus
  84. extern "C" {
  85. #endif
  86. /* *INDENT-ON* */
  87. #include "mpu_wrappers.h"
  88. /*
  89. * Setup the stack of a new task so it is ready to be placed under the
  90. * scheduler control. The registers have to be placed on the stack in
  91. * the order that the port expects to find them.
  92. *
  93. */
  94. #if ( portUSING_MPU_WRAPPERS == 1 )
  95. #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 )
  96. StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
  97. StackType_t * pxEndOfStack,
  98. TaskFunction_t pxCode,
  99. void * pvParameters,
  100. BaseType_t xRunPrivileged ) PRIVILEGED_FUNCTION;
  101. #else
  102. StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
  103. TaskFunction_t pxCode,
  104. void * pvParameters,
  105. BaseType_t xRunPrivileged ) PRIVILEGED_FUNCTION;
  106. #endif
  107. #else /* 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 ) PRIVILEGED_FUNCTION;
  113. #else
  114. StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack,
  115. TaskFunction_t pxCode,
  116. void * pvParameters ) PRIVILEGED_FUNCTION;
  117. #endif
  118. #endif /* if ( portUSING_MPU_WRAPPERS == 1 ) */
  119. /* Used by heap_5.c to define the start address and size of each memory region
  120. * that together comprise the total FreeRTOS heap space. */
  121. typedef struct HeapRegion
  122. {
  123. uint8_t * pucStartAddress;
  124. size_t xSizeInBytes;
  125. } HeapRegion_t;
  126. /* Used to pass information about the heap out of vPortGetHeapStats(). */
  127. typedef struct xHeapStats
  128. {
  129. 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. */
  130. size_t xSizeOfLargestFreeBlockInBytes; /* The maximum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */
  131. size_t xSizeOfSmallestFreeBlockInBytes; /* The minimum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */
  132. size_t xNumberOfFreeBlocks; /* The number of free memory blocks within the heap at the time vPortGetHeapStats() is called. */
  133. 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. */
  134. size_t xNumberOfSuccessfulAllocations; /* The number of calls to pvPortMalloc() that have returned a valid memory block. */
  135. size_t xNumberOfSuccessfulFrees; /* The number of calls to vPortFree() that has successfully freed a block of memory. */
  136. } HeapStats_t;
  137. /*
  138. * Used to define multiple heap regions for use by heap_5.c. This function
  139. * must be called before any calls to pvPortMalloc() - not creating a task,
  140. * queue, semaphore, mutex, software timer, event group, etc. will result in
  141. * pvPortMalloc being called.
  142. *
  143. * pxHeapRegions passes in an array of HeapRegion_t structures - each of which
  144. * defines a region of memory that can be used as the heap. The array is
  145. * terminated by a HeapRegions_t structure that has a size of 0. The region
  146. * with the lowest start address must appear first in the array.
  147. */
  148. void vPortDefineHeapRegions( const HeapRegion_t * const pxHeapRegions ) PRIVILEGED_FUNCTION;
  149. /*
  150. * Returns a HeapStats_t structure filled with information about the current
  151. * heap state.
  152. */
  153. void vPortGetHeapStats( HeapStats_t * pxHeapStats );
  154. /*
  155. * Map to the memory management routines required for the port.
  156. */
  157. void * pvPortMalloc( size_t xSize ) PRIVILEGED_FUNCTION;
  158. void vPortFree( void * pv ) PRIVILEGED_FUNCTION;
  159. void vPortInitialiseBlocks( void ) PRIVILEGED_FUNCTION;
  160. size_t xPortGetFreeHeapSize( void ) PRIVILEGED_FUNCTION;
  161. size_t xPortGetMinimumEverFreeHeapSize( void ) PRIVILEGED_FUNCTION;
  162. #if( configSTACK_ALLOCATION_FROM_SEPARATE_HEAP == 1 )
  163. void *pvPortMallocStack( size_t xSize ) PRIVILEGED_FUNCTION;
  164. void vPortFreeStack( void *pv ) PRIVILEGED_FUNCTION;
  165. #else
  166. #define pvPortMallocStack pvPortMalloc
  167. #define vPortFreeStack vPortFree
  168. #endif
  169. /*
  170. * Setup the hardware ready for the scheduler to take control. This generally
  171. * sets up a tick interrupt and sets timers for the correct tick frequency.
  172. */
  173. BaseType_t xPortStartScheduler( void ) PRIVILEGED_FUNCTION;
  174. /*
  175. * Undo any hardware/ISR setup that was performed by xPortStartScheduler() so
  176. * the hardware is left in its original condition after the scheduler stops
  177. * executing.
  178. */
  179. void vPortEndScheduler( void ) PRIVILEGED_FUNCTION;
  180. /*
  181. * The structures and methods of manipulating the MPU are contained within the
  182. * port layer.
  183. *
  184. * Fills the xMPUSettings structure with the memory region information
  185. * contained in xRegions.
  186. */
  187. #if ( portUSING_MPU_WRAPPERS == 1 )
  188. struct xMEMORY_REGION;
  189. void vPortStoreTaskMPUSettings( xMPU_SETTINGS * xMPUSettings,
  190. const struct xMEMORY_REGION * const xRegions,
  191. StackType_t * pxBottomOfStack,
  192. uint32_t ulStackDepth ) PRIVILEGED_FUNCTION;
  193. #endif
  194. /* *INDENT-OFF* */
  195. #ifdef __cplusplus
  196. }
  197. #endif
  198. /* *INDENT-ON* */
  199. #endif /* PORTABLE_H */