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

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