1 /*
2  * FreeRTOS Kernel V10.3.1
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
6  * of this software and associated documentation files (the "Software"), to deal
7  * in the Software without restriction, including without limitation the rights
8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9  * copies of the Software, and to permit persons to whom the Software is
10  * furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all 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,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21  * SOFTWARE.
22  *
23  * http://www.FreeRTOS.org
24  * http://aws.amazon.com/freertos
25  *
26  * 1 tab == 4 spaces!
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 #endif
59 
60 #if portBYTE_ALIGNMENT == 16
61 #    define portBYTE_ALIGNMENT_MASK (0x000f)
62 #endif
63 
64 #if portBYTE_ALIGNMENT == 8
65 #    define portBYTE_ALIGNMENT_MASK (0x0007)
66 #endif
67 
68 #if portBYTE_ALIGNMENT == 4
69 #    define portBYTE_ALIGNMENT_MASK (0x0003)
70 #endif
71 
72 #if portBYTE_ALIGNMENT == 2
73 #    define portBYTE_ALIGNMENT_MASK (0x0001)
74 #endif
75 
76 #if portBYTE_ALIGNMENT == 1
77 #    define portBYTE_ALIGNMENT_MASK (0x0000)
78 #endif
79 
80 #ifndef portBYTE_ALIGNMENT_MASK
81 #    error "Invalid portBYTE_ALIGNMENT definition"
82 #endif
83 
84 #ifndef portNUM_CONFIGURABLE_REGIONS
85 #    define portNUM_CONFIGURABLE_REGIONS 1
86 #endif
87 
88 #ifndef portHAS_STACK_OVERFLOW_CHECKING
89 #    define portHAS_STACK_OVERFLOW_CHECKING 0
90 #endif
91 
92 #ifndef portARCH_NAME
93 #    define portARCH_NAME NULL
94 #endif
95 
96 #ifdef __cplusplus
97 extern "C" {
98 #endif
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(
111     StackType_t *pxTopOfStack,
112     StackType_t *pxEndOfStack,
113     TaskFunction_t pxCode,
114     void *pvParameters,
115     BaseType_t xRunPrivileged) PRIVILEGED_FUNCTION;
116 #    else
117 StackType_t *pxPortInitialiseStack(
118     StackType_t *pxTopOfStack,
119     TaskFunction_t pxCode,
120     void *pvParameters,
121     BaseType_t xRunPrivileged) PRIVILEGED_FUNCTION;
122 #    endif
123 #else
124 #    if (portHAS_STACK_OVERFLOW_CHECKING == 1)
125 StackType_t *pxPortInitialiseStack(
126     StackType_t *pxTopOfStack,
127     StackType_t *pxEndOfStack,
128     TaskFunction_t pxCode,
129     void *pvParameters) PRIVILEGED_FUNCTION;
130 #    else
131 StackType_t *pxPortInitialiseStack(
132     StackType_t *pxTopOfStack,
133     TaskFunction_t pxCode,
134     void *pvParameters) PRIVILEGED_FUNCTION;
135 #    endif
136 #endif
137 
138 /* Used by heap_5.c to define the start address and size of each memory region
139 that together comprise the total FreeRTOS heap space. */
140 typedef struct HeapRegion {
141     uint8_t *pucStartAddress;
142     size_t xSizeInBytes;
143 } HeapRegion_t;
144 
145 /* Used to pass information about the heap out of vPortGetHeapStats(). */
146 typedef struct xHeapStats {
147     size_t xAvailableHeapSpaceInBytes; /* The total heap size currently
148                                           available - this is the sum of all the
149                                           free blocks, not the largest block
150                                           that can be allocated. */
151     size_t xSizeOfLargestFreeBlockInBytes; /* The maximum size, in bytes, of all
152                                               the free blocks within the heap at
153                                               the time vPortGetHeapStats() is
154                                               called. */
155     size_t xSizeOfSmallestFreeBlockInBytes; /* The minimum size, in bytes, of
156                                                all the free blocks within the
157                                                heap at the time
158                                                vPortGetHeapStats() is called. */
159     size_t
160         xNumberOfFreeBlocks; /* The number of free memory blocks within the heap
161                                 at the time vPortGetHeapStats() is called. */
162     size_t xMinimumEverFreeBytesRemaining; /* The minimum amount of total free
163                                               memory (sum of all free blocks)
164                                               there has been in the heap since
165                                               the system booted. */
166     size_t xNumberOfSuccessfulAllocations; /* The number of calls to
167                                               pvPortMalloc() that have returned
168                                               a valid memory block. */
169     size_t
170         xNumberOfSuccessfulFrees; /* The number of calls to vPortFree() that has
171                                      successfully freed a block of memory. */
172 } HeapStats_t;
173 
174 /*
175  * Used to define multiple heap regions for use by heap_5.c.  This function
176  * must be called before any calls to pvPortMalloc() - not creating a task,
177  * queue, semaphore, mutex, software timer, event group, etc. will result in
178  * pvPortMalloc being called.
179  *
180  * pxHeapRegions passes in an array of HeapRegion_t structures - each of which
181  * defines a region of memory that can be used as the heap.  The array is
182  * terminated by a HeapRegions_t structure that has a size of 0.  The region
183  * with the lowest start address must appear first in the array.
184  */
185 void vPortDefineHeapRegions(const HeapRegion_t *const pxHeapRegions)
186     PRIVILEGED_FUNCTION;
187 
188 /*
189  * Returns a HeapStats_t structure filled with information about the current
190  * heap state.
191  */
192 void vPortGetHeapStats(HeapStats_t *pxHeapStats);
193 
194 /*
195  * Map to the memory management routines required for the port.
196  */
197 void *pvPortMalloc(size_t xSize) PRIVILEGED_FUNCTION;
198 void vPortFree(void *pv) PRIVILEGED_FUNCTION;
199 void vPortInitialiseBlocks(void) PRIVILEGED_FUNCTION;
200 size_t xPortGetFreeHeapSize(void) PRIVILEGED_FUNCTION;
201 size_t xPortGetMinimumEverFreeHeapSize(void) PRIVILEGED_FUNCTION;
202 
203 /*
204  * Setup the hardware ready for the scheduler to take control.  This generally
205  * sets up a tick interrupt and sets timers for the correct tick frequency.
206  */
207 BaseType_t xPortStartScheduler(void) PRIVILEGED_FUNCTION;
208 
209 /*
210  * Undo any hardware/ISR setup that was performed by xPortStartScheduler() so
211  * the hardware is left in its original condition after the scheduler stops
212  * executing.
213  */
214 void vPortEndScheduler(void) PRIVILEGED_FUNCTION;
215 
216 /*
217  * The structures and methods of manipulating the MPU are contained within the
218  * port layer.
219  *
220  * Fills the xMPUSettings structure with the memory region information
221  * contained in xRegions.
222  */
223 #if (portUSING_MPU_WRAPPERS == 1)
224 struct xMEMORY_REGION;
225 void vPortStoreTaskMPUSettings(
226     xMPU_SETTINGS *xMPUSettings,
227     const struct xMEMORY_REGION *const xRegions,
228     StackType_t *pxBottomOfStack,
229     uint32_t ulStackDepth) PRIVILEGED_FUNCTION;
230 #endif
231 
232 #ifdef __cplusplus
233 }
234 #endif
235 
236 #endif /* PORTABLE_H */
237