include/portable.h (FreeRTOS)

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

/* * FreeRTOS Kernel <DEVELOPMENT BRANCH> * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * SPDX-License-Identifier: MIT * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of * the Software, and to permit persons to whom the Software is furnished to do so, * subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * * https://www.FreeRTOS.org * https://github.com/FreeRTOS * */ /*----------------------------------------------------------- * Portable layer API. Each function must be defined for each port. *----------------------------------------------------------*/ #ifndef PORTABLE_H #define PORTABLE_H /* Each FreeRTOS port has a unique portmacro.h header file. Originally a * pre-processor definition was used to ensure the pre-processor found the correct * portmacro.h file for the port being used. That scheme was deprecated in favour * of setting the compiler's include path such that it found the correct * portmacro.h file - removing the need for the constant and allowing the * portmacro.h file to be located anywhere in relation to the port being used. * Purely for reasons of backward compatibility the old method is still valid, but * to make it clear that new projects should not use it, support for the port * specific constants has been moved into the deprecated_definitions.h header * file. */ #include "deprecated_definitions.h" /* If portENTER_CRITICAL is not defined then including deprecated_definitions.h * did not result in a portmacro.h header file being included - and it should be * included here. In this case the path to the correct portmacro.h header file * must be set in the compiler's include path. */ #ifndef portENTER_CRITICAL #include "portmacro.h" #endif #if portBYTE_ALIGNMENT == 32 #define portBYTE_ALIGNMENT_MASK ( 0x001f ) #elif portBYTE_ALIGNMENT == 16 #define portBYTE_ALIGNMENT_MASK ( 0x000f ) #elif portBYTE_ALIGNMENT == 8 #define portBYTE_ALIGNMENT_MASK ( 0x0007 ) #elif portBYTE_ALIGNMENT == 4 #define portBYTE_ALIGNMENT_MASK ( 0x0003 ) #elif portBYTE_ALIGNMENT == 2 #define portBYTE_ALIGNMENT_MASK ( 0x0001 ) #elif portBYTE_ALIGNMENT == 1 #define portBYTE_ALIGNMENT_MASK ( 0x0000 ) #else /* if portBYTE_ALIGNMENT == 32 */ #error "Invalid portBYTE_ALIGNMENT definition" #endif /* if portBYTE_ALIGNMENT == 32 */ #ifndef portUSING_MPU_WRAPPERS #define portUSING_MPU_WRAPPERS 0 #endif #ifndef portNUM_CONFIGURABLE_REGIONS #define portNUM_CONFIGURABLE_REGIONS 1 #endif #ifndef portHAS_STACK_OVERFLOW_CHECKING #define portHAS_STACK_OVERFLOW_CHECKING 0 #endif #ifndef portARCH_NAME #define portARCH_NAME NULL #endif #ifndef configSTACK_DEPTH_TYPE #define configSTACK_DEPTH_TYPE StackType_t #endif #ifndef configSTACK_ALLOCATION_FROM_SEPARATE_HEAP /* Defaults to 0 for backward compatibility. */ #define configSTACK_ALLOCATION_FROM_SEPARATE_HEAP 0 #endif #include "mpu_wrappers.h" /* *INDENT-OFF* */ #ifdef __cplusplus extern "C" { #endif /* *INDENT-ON* */ /* * Setup the stack of a new task so it is ready to be placed under the * scheduler control. The registers have to be placed on the stack in * the order that the port expects to find them. * */ #if ( portUSING_MPU_WRAPPERS == 1 ) #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, StackType_t * pxEndOfStack, TaskFunction_t pxCode, void * pvParameters, BaseType_t xRunPrivileged, xMPU_SETTINGS * xMPUSettings ) PRIVILEGED_FUNCTION; #else StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, TaskFunction_t pxCode, void * pvParameters, BaseType_t xRunPrivileged, xMPU_SETTINGS * xMPUSettings ) PRIVILEGED_FUNCTION; #endif /* if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) */ #else /* if ( portUSING_MPU_WRAPPERS == 1 ) */ #if ( portHAS_STACK_OVERFLOW_CHECKING == 1 ) StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, StackType_t * pxEndOfStack, TaskFunction_t pxCode, void * pvParameters ) PRIVILEGED_FUNCTION; #else StackType_t * pxPortInitialiseStack( StackType_t * pxTopOfStack, TaskFunction_t pxCode, void * pvParameters ) PRIVILEGED_FUNCTION; #endif #endif /* if ( portUSING_MPU_WRAPPERS == 1 ) */ /* Used by heap_5.c to define the start address and size of each memory region * that together comprise the total FreeRTOS heap space. */ typedef struct HeapRegion { uint8_t * pucStartAddress; size_t xSizeInBytes; } HeapRegion_t; /* Used to pass information about the heap out of vPortGetHeapStats(). */ typedef struct xHeapStats { 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. */ size_t xSizeOfLargestFreeBlockInBytes; /* The maximum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */ size_t xSizeOfSmallestFreeBlockInBytes; /* The minimum size, in bytes, of all the free blocks within the heap at the time vPortGetHeapStats() is called. */ size_t xNumberOfFreeBlocks; /* The number of free memory blocks within the heap at the time vPortGetHeapStats() is called. */ 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. */ size_t xNumberOfSuccessfulAllocations; /* The number of calls to pvPortMalloc() that have returned a valid memory block. */ size_t xNumberOfSuccessfulFrees; /* The number of calls to vPortFree() that has successfully freed a block of memory. */ } HeapStats_t; /* * Used to define multiple heap regions for use by heap_5.c. This function * must be called before any calls to pvPortMalloc() - not creating a task, * queue, semaphore, mutex, software timer, event group, etc. will result in * pvPortMalloc being called. * * pxHeapRegions passes in an array of HeapRegion_t structures - each of which * defines a region of memory that can be used as the heap. The array is * terminated by a HeapRegions_t structure that has a size of 0. The region * with the lowest start address must appear first in the array. */ void vPortDefineHeapRegions( const HeapRegion_t * const pxHeapRegions ) PRIVILEGED_FUNCTION; /* * Returns a HeapStats_t structure filled with information about the current * heap state. */ void vPortGetHeapStats( HeapStats_t * pxHeapStats ); /* * Map to the memory management routines required for the port. */ void * pvPortMalloc( size_t xWantedSize ) PRIVILEGED_FUNCTION; void * pvPortCalloc( size_t xNum, size_t xSize ) PRIVILEGED_FUNCTION; void vPortFree( void * pv ) PRIVILEGED_FUNCTION; void vPortInitialiseBlocks( void ) PRIVILEGED_FUNCTION; size_t xPortGetFreeHeapSize( void ) PRIVILEGED_FUNCTION; size_t xPortGetMinimumEverFreeHeapSize( void ) PRIVILEGED_FUNCTION; #if ( configSTACK_ALLOCATION_FROM_SEPARATE_HEAP == 1 ) void * pvPortMallocStack( size_t xSize ) PRIVILEGED_FUNCTION; void vPortFreeStack( void * pv ) PRIVILEGED_FUNCTION; #else #define pvPortMallocStack pvPortMalloc #define vPortFreeStack vPortFree #endif /* * This function resets the internal state of the heap module. It must be called * by the application before restarting the scheduler. */ void vPortHeapResetState( void ) PRIVILEGED_FUNCTION; #if ( configUSE_MALLOC_FAILED_HOOK == 1 ) /** * task.h * @code{c} * void vApplicationMallocFailedHook( void ) * @endcode * * This hook function is called when allocation failed. */ void vApplicationMallocFailedHook( void ); #endif /* * Setup the hardware ready for the scheduler to take control. This generally * sets up a tick interrupt and sets timers for the correct tick frequency. */ BaseType_t xPortStartScheduler( void ) PRIVILEGED_FUNCTION; /* * Undo any hardware/ISR setup that was performed by xPortStartScheduler() so * the hardware is left in its original condition after the scheduler stops * executing. */ void vPortEndScheduler( void ) PRIVILEGED_FUNCTION; /* * The structures and methods of manipulating the MPU are contained within the * port layer. * * Fills the xMPUSettings structure with the memory region information * contained in xRegions. */ #if ( portUSING_MPU_WRAPPERS == 1 ) struct xMEMORY_REGION; void vPortStoreTaskMPUSettings( xMPU_SETTINGS * xMPUSettings, const struct xMEMORY_REGION * const xRegions, StackType_t * pxBottomOfStack, configSTACK_DEPTH_TYPE uxStackDepth ) PRIVILEGED_FUNCTION; #endif /** * @brief Checks if the calling task is authorized to access the given buffer. * * @param pvBuffer The buffer which the calling task wants to access. * @param ulBufferLength The length of the pvBuffer. * @param ulAccessRequested The permissions that the calling task wants. * * @return pdTRUE if the calling task is authorized to access the buffer, * pdFALSE otherwise. */ #if ( portUSING_MPU_WRAPPERS == 1 ) BaseType_t xPortIsAuthorizedToAccessBuffer( const void * pvBuffer, uint32_t ulBufferLength, uint32_t ulAccessRequested ) PRIVILEGED_FUNCTION; #endif /** * @brief Checks if the calling task is authorized to access the given kernel object. * * @param lInternalIndexOfKernelObject The index of the kernel object in the kernel * object handle pool. * * @return pdTRUE if the calling task is authorized to access the kernel object, * pdFALSE otherwise. */ #if ( ( portUSING_MPU_WRAPPERS == 1 ) && ( configUSE_MPU_WRAPPERS_V1 == 0 ) ) BaseType_t xPortIsAuthorizedToAccessKernelObject( int32_t lInternalIndexOfKernelObject ) PRIVILEGED_FUNCTION; #endif /* *INDENT-OFF* */ #ifdef __cplusplus } #endif /* *INDENT-ON* */ #endif /* PORTABLE_H */