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

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