1 /* 2 * Copyright (c) 2013-2021 Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Licensed under the Apache License, Version 2.0 (the License); you may 7 * not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 14 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 * 18 * ----------------------------------------------------------------------------- 19 * 20 * Project: CMSIS-RTOS RTX 21 * Title: RTX OS definitions 22 * 23 * ----------------------------------------------------------------------------- 24 */ 25 26 #ifndef RTX_OS_H_ 27 #define RTX_OS_H_ 28 29 #include <stdint.h> 30 #include <stddef.h> 31 #include "cmsis_os2.h" 32 #include "rtx_def.h" 33 34 #ifdef __cplusplus 35 extern "C" 36 { 37 #endif 38 39 40 /// Kernel Information 41 #define osRtxVersionAPI 20010003 ///< API version (2.1.3) 42 #define osRtxVersionKernel 50050003 ///< Kernel version (5.5.3) 43 #define osRtxKernelId "RTX V5.5.3" ///< Kernel identification string 44 45 46 // ==== Common definitions ==== 47 48 /// Object Identifier definitions 49 #define osRtxIdInvalid 0x00U 50 #define osRtxIdThread 0xF1U 51 #define osRtxIdTimer 0xF2U 52 #define osRtxIdEventFlags 0xF3U 53 #define osRtxIdMutex 0xF5U 54 #define osRtxIdSemaphore 0xF6U 55 #define osRtxIdMemoryPool 0xF7U 56 #define osRtxIdMessage 0xF9U 57 #define osRtxIdMessageQueue 0xFAU 58 59 /// Object Flags definitions 60 #define osRtxFlagSystemObject 0x01U 61 #define osRtxFlagSystemMemory 0x02U 62 63 64 // ==== Kernel definitions ==== 65 66 /// Kernel State definitions 67 #define osRtxKernelInactive ((uint8_t)osKernelInactive) 68 #define osRtxKernelReady ((uint8_t)osKernelReady) 69 #define osRtxKernelRunning ((uint8_t)osKernelRunning) 70 #define osRtxKernelLocked ((uint8_t)osKernelLocked) 71 #define osRtxKernelSuspended ((uint8_t)osKernelSuspended) 72 73 74 // ==== Thread definitions ==== 75 76 /// Thread State definitions (extending osThreadState) 77 #define osRtxThreadStateMask 0x0FU 78 79 #define osRtxThreadInactive ((uint8_t)osThreadInactive) 80 #define osRtxThreadReady ((uint8_t)osThreadReady) 81 #define osRtxThreadRunning ((uint8_t)osThreadRunning) 82 #define osRtxThreadBlocked ((uint8_t)osThreadBlocked) 83 #define osRtxThreadTerminated ((uint8_t)osThreadTerminated) 84 85 #define osRtxThreadWaitingDelay ((uint8_t)(osRtxThreadBlocked | 0x10U)) 86 #define osRtxThreadWaitingJoin ((uint8_t)(osRtxThreadBlocked | 0x20U)) 87 #define osRtxThreadWaitingThreadFlags ((uint8_t)(osRtxThreadBlocked | 0x30U)) 88 #define osRtxThreadWaitingEventFlags ((uint8_t)(osRtxThreadBlocked | 0x40U)) 89 #define osRtxThreadWaitingMutex ((uint8_t)(osRtxThreadBlocked | 0x50U)) 90 #define osRtxThreadWaitingSemaphore ((uint8_t)(osRtxThreadBlocked | 0x60U)) 91 #define osRtxThreadWaitingMemoryPool ((uint8_t)(osRtxThreadBlocked | 0x70U)) 92 #define osRtxThreadWaitingMessageGet ((uint8_t)(osRtxThreadBlocked | 0x80U)) 93 #define osRtxThreadWaitingMessagePut ((uint8_t)(osRtxThreadBlocked | 0x90U)) 94 95 /// Thread Flags definitions 96 #define osRtxThreadFlagDefStack 0x10U ///< Default Stack flag 97 98 /// Stack Marker definitions 99 #define osRtxStackMagicWord 0xE25A2EA5U ///< Stack Magic Word (Stack Base) 100 #define osRtxStackFillPattern 0xCCCCCCCCU ///< Stack Fill Pattern 101 102 /// Thread Control Block 103 typedef struct osRtxThread_s { 104 uint8_t id; ///< Object Identifier 105 uint8_t state; ///< Object State 106 uint8_t flags; ///< Object Flags 107 uint8_t attr; ///< Object Attributes 108 const char *name; ///< Object Name 109 struct osRtxThread_s *thread_next; ///< Link pointer to next Thread in Object list 110 struct osRtxThread_s *thread_prev; ///< Link pointer to previous Thread in Object list 111 struct osRtxThread_s *delay_next; ///< Link pointer to next Thread in Delay list 112 struct osRtxThread_s *delay_prev; ///< Link pointer to previous Thread in Delay list 113 struct osRtxThread_s *thread_join; ///< Thread waiting to Join 114 uint32_t delay; ///< Delay Time/Round Robin Time Tick 115 int8_t priority; ///< Thread Priority 116 int8_t priority_base; ///< Base Priority 117 uint8_t stack_frame; ///< Stack Frame (EXC_RETURN[7..0]) 118 uint8_t flags_options; ///< Thread/Event Flags Options 119 uint32_t wait_flags; ///< Waiting Thread/Event Flags 120 uint32_t thread_flags; ///< Thread Flags 121 struct osRtxMutex_s *mutex_list; ///< Link pointer to list of owned Mutexes 122 void *stack_mem; ///< Stack Memory 123 uint32_t stack_size; ///< Stack Size 124 uint32_t sp; ///< Current Stack Pointer 125 uint32_t thread_addr; ///< Thread entry address 126 uint32_t tz_memory; ///< TrustZone Memory Identifier 127 #ifdef RTX_TF_M_EXTENSION 128 uint32_t tz_module; ///< TrustZone Module Identifier 129 #endif 130 } osRtxThread_t; 131 132 133 // ==== Timer definitions ==== 134 135 /// Timer State definitions 136 #define osRtxTimerInactive 0x00U ///< Timer Inactive 137 #define osRtxTimerStopped 0x01U ///< Timer Stopped 138 #define osRtxTimerRunning 0x02U ///< Timer Running 139 140 /// Timer Type definitions 141 #define osRtxTimerPeriodic ((uint8_t)osTimerPeriodic) 142 143 /// Timer Function Information 144 typedef struct { 145 osTimerFunc_t func; ///< Function Pointer 146 void *arg; ///< Function Argument 147 } osRtxTimerFinfo_t; 148 149 /// Timer Control Block 150 typedef struct osRtxTimer_s { 151 uint8_t id; ///< Object Identifier 152 uint8_t state; ///< Object State 153 uint8_t flags; ///< Object Flags 154 uint8_t type; ///< Timer Type (Periodic/One-shot) 155 const char *name; ///< Object Name 156 struct osRtxTimer_s *prev; ///< Pointer to previous active Timer 157 struct osRtxTimer_s *next; ///< Pointer to next active Timer 158 uint32_t tick; ///< Timer current Tick 159 uint32_t load; ///< Timer Load value 160 osRtxTimerFinfo_t finfo; ///< Timer Function Info 161 } osRtxTimer_t; 162 163 164 // ==== Event Flags definitions ==== 165 166 /// Event Flags Control Block 167 typedef struct { 168 uint8_t id; ///< Object Identifier 169 uint8_t reserved_state; ///< Object State (not used) 170 uint8_t flags; ///< Object Flags 171 uint8_t reserved; 172 const char *name; ///< Object Name 173 osRtxThread_t *thread_list; ///< Waiting Threads List 174 uint32_t event_flags; ///< Event Flags 175 } osRtxEventFlags_t; 176 177 178 // ==== Mutex definitions ==== 179 180 /// Mutex Control Block 181 typedef struct osRtxMutex_s { 182 uint8_t id; ///< Object Identifier 183 uint8_t reserved_state; ///< Object State (not used) 184 uint8_t flags; ///< Object Flags 185 uint8_t attr; ///< Object Attributes 186 const char *name; ///< Object Name 187 osRtxThread_t *thread_list; ///< Waiting Threads List 188 osRtxThread_t *owner_thread; ///< Owner Thread 189 struct osRtxMutex_s *owner_prev; ///< Pointer to previous owned Mutex 190 struct osRtxMutex_s *owner_next; ///< Pointer to next owned Mutex 191 uint8_t lock; ///< Lock counter 192 uint8_t padding[3]; 193 } osRtxMutex_t; 194 195 196 // ==== Semaphore definitions ==== 197 198 /// Semaphore Control Block 199 typedef struct { 200 uint8_t id; ///< Object Identifier 201 uint8_t reserved_state; ///< Object State (not used) 202 uint8_t flags; ///< Object Flags 203 uint8_t reserved; 204 const char *name; ///< Object Name 205 osRtxThread_t *thread_list; ///< Waiting Threads List 206 uint16_t tokens; ///< Current number of tokens 207 uint16_t max_tokens; ///< Maximum number of tokens 208 } osRtxSemaphore_t; 209 210 211 // ==== Memory Pool definitions ==== 212 213 /// Memory Pool Information 214 typedef struct { 215 uint32_t max_blocks; ///< Maximum number of Blocks 216 uint32_t used_blocks; ///< Number of used Blocks 217 uint32_t block_size; ///< Block Size 218 void *block_base; ///< Block Memory Base Address 219 void *block_lim; ///< Block Memory Limit Address 220 void *block_free; ///< First free Block Address 221 } osRtxMpInfo_t; 222 223 /// Memory Pool Control Block 224 typedef struct { 225 uint8_t id; ///< Object Identifier 226 uint8_t reserved_state; ///< Object State (not used) 227 uint8_t flags; ///< Object Flags 228 uint8_t reserved; 229 const char *name; ///< Object Name 230 osRtxThread_t *thread_list; ///< Waiting Threads List 231 osRtxMpInfo_t mp_info; ///< Memory Pool Info 232 } osRtxMemoryPool_t; 233 234 235 // ==== Message Queue definitions ==== 236 237 /// Message Control Block 238 typedef struct osRtxMessage_s { 239 uint8_t id; ///< Object Identifier 240 uint8_t reserved_state; ///< Object State (not used) 241 uint8_t flags; ///< Object Flags 242 uint8_t priority; ///< Message Priority 243 struct osRtxMessage_s *prev; ///< Pointer to previous Message 244 struct osRtxMessage_s *next; ///< Pointer to next Message 245 } osRtxMessage_t; 246 247 /// Message Queue Control Block 248 typedef struct { 249 uint8_t id; ///< Object Identifier 250 uint8_t reserved_state; ///< Object State (not used) 251 uint8_t flags; ///< Object Flags 252 uint8_t reserved; 253 const char *name; ///< Object Name 254 osRtxThread_t *thread_list; ///< Waiting Threads List 255 osRtxMpInfo_t mp_info; ///< Memory Pool Info 256 uint32_t msg_size; ///< Message Size 257 uint32_t msg_count; ///< Number of queued Messages 258 osRtxMessage_t *msg_first; ///< Pointer to first Message 259 osRtxMessage_t *msg_last; ///< Pointer to last Message 260 } osRtxMessageQueue_t; 261 262 263 // ==== Generic Object definitions ==== 264 265 /// Generic Object Control Block 266 typedef struct { 267 uint8_t id; ///< Object Identifier 268 uint8_t state; ///< Object State 269 uint8_t flags; ///< Object Flags 270 uint8_t reserved; 271 const char *name; ///< Object Name 272 osRtxThread_t *thread_list; ///< Threads List 273 } osRtxObject_t; 274 275 276 // ==== OS Runtime Information definitions ==== 277 278 /// OS Runtime Information structure 279 typedef struct { 280 const char *os_id; ///< OS Identification 281 uint32_t version; ///< OS Version 282 struct { ///< Kernel Info 283 uint8_t state; ///< State 284 volatile uint8_t blocked; ///< Blocked 285 uint8_t pendSV; ///< Pending SV 286 uint8_t reserved; 287 uint32_t tick; ///< Tick counter 288 } kernel; 289 int32_t tick_irqn; ///< Tick Timer IRQ Number 290 struct { ///< Thread Info 291 struct { ///< Thread Run Info 292 osRtxThread_t *curr; ///< Current running Thread 293 osRtxThread_t *next; ///< Next Thread to Run 294 } run; 295 osRtxObject_t ready; ///< Ready List Object 296 osRtxThread_t *idle; ///< Idle Thread 297 osRtxThread_t *delay_list; ///< Delay List 298 osRtxThread_t *wait_list; ///< Wait List (no Timeout) 299 osRtxThread_t *terminate_list; ///< Terminate Thread List 300 uint32_t reserved; 301 struct { ///< Thread Round Robin Info 302 osRtxThread_t *thread; ///< Round Robin Thread 303 uint32_t timeout; ///< Round Robin Timeout 304 } robin; 305 } thread; 306 struct { ///< Timer Info 307 osRtxTimer_t *list; ///< Active Timer List 308 osRtxThread_t *thread; ///< Timer Thread 309 osRtxMessageQueue_t *mq; ///< Timer Message Queue 310 void (*tick)(void); ///< Timer Tick Function 311 } timer; 312 struct { ///< ISR Post Processing Queue 313 uint16_t max; ///< Maximum Items 314 uint16_t cnt; ///< Item Count 315 uint16_t in; ///< Incoming Item Index 316 uint16_t out; ///< Outgoing Item Index 317 void **data; ///< Queue Data 318 } isr_queue; 319 struct { ///< ISR Post Processing functions 320 void (*thread)(osRtxThread_t*); ///< Thread Post Processing function 321 void (*event_flags)(osRtxEventFlags_t*); ///< Event Flags Post Processing function 322 void (*semaphore)(osRtxSemaphore_t*); ///< Semaphore Post Processing function 323 void (*memory_pool)(osRtxMemoryPool_t*); ///< Memory Pool Post Processing function 324 void (*message)(osRtxMessage_t*); ///< Message Post Processing function 325 } post_process; 326 struct { ///< Memory Pools (Variable Block Size) 327 void *stack; ///< Stack Memory 328 void *mp_data; ///< Memory Pool Data Memory 329 void *mq_data; ///< Message Queue Data Memory 330 void *common; ///< Common Memory 331 } mem; 332 struct { ///< Memory Pools (Fixed Block Size) 333 osRtxMpInfo_t *stack; ///< Stack for Threads 334 osRtxMpInfo_t *thread; ///< Thread Control Blocks 335 osRtxMpInfo_t *timer; ///< Timer Control Blocks 336 osRtxMpInfo_t *event_flags; ///< Event Flags Control Blocks 337 osRtxMpInfo_t *mutex; ///< Mutex Control Blocks 338 osRtxMpInfo_t *semaphore; ///< Semaphore Control Blocks 339 osRtxMpInfo_t *memory_pool; ///< Memory Pool Control Blocks 340 osRtxMpInfo_t *message_queue; ///< Message Queue Control Blocks 341 } mpi; 342 } osRtxInfo_t; 343 344 extern osRtxInfo_t osRtxInfo; ///< OS Runtime Information 345 346 /// OS Runtime Object Memory Usage structure 347 typedef struct { 348 uint32_t cnt_alloc; ///< Counter for alloc 349 uint32_t cnt_free; ///< Counter for free 350 uint32_t max_used; ///< Maximum used 351 } osRtxObjectMemUsage_t; 352 353 /// OS Runtime Object Memory Usage variables 354 extern osRtxObjectMemUsage_t osRtxThreadMemUsage; 355 extern osRtxObjectMemUsage_t osRtxTimerMemUsage; 356 extern osRtxObjectMemUsage_t osRtxEventFlagsMemUsage; 357 extern osRtxObjectMemUsage_t osRtxMutexMemUsage; 358 extern osRtxObjectMemUsage_t osRtxSemaphoreMemUsage; 359 extern osRtxObjectMemUsage_t osRtxMemoryPoolMemUsage; 360 extern osRtxObjectMemUsage_t osRtxMessageQueueMemUsage; 361 362 363 // ==== OS API definitions ==== 364 365 // Object Limits definitions 366 #define osRtxThreadFlagsLimit 31U ///< number of Thread Flags available per thread 367 #define osRtxEventFlagsLimit 31U ///< number of Event Flags available per object 368 #define osRtxMutexLockLimit 255U ///< maximum number of recursive mutex locks 369 #define osRtxSemaphoreTokenLimit 65535U ///< maximum number of tokens per semaphore 370 371 // Control Block sizes 372 #define osRtxThreadCbSize sizeof(osRtxThread_t) 373 #define osRtxTimerCbSize sizeof(osRtxTimer_t) 374 #define osRtxEventFlagsCbSize sizeof(osRtxEventFlags_t) 375 #define osRtxMutexCbSize sizeof(osRtxMutex_t) 376 #define osRtxSemaphoreCbSize sizeof(osRtxSemaphore_t) 377 #define osRtxMemoryPoolCbSize sizeof(osRtxMemoryPool_t) 378 #define osRtxMessageQueueCbSize sizeof(osRtxMessageQueue_t) 379 380 /// Memory size in bytes for Memory Pool storage. 381 /// \param block_count maximum number of memory blocks in memory pool. 382 /// \param block_size memory block size in bytes. 383 #define osRtxMemoryPoolMemSize(block_count, block_size) \ 384 (4*(block_count)*(((block_size)+3)/4)) 385 386 /// Memory size in bytes for Message Queue storage. 387 /// \param msg_count maximum number of messages in queue. 388 /// \param msg_size maximum message size in bytes. 389 #define osRtxMessageQueueMemSize(msg_count, msg_size) \ 390 (4*(msg_count)*(3+(((msg_size)+3)/4))) 391 392 393 // ==== OS External Functions ==== 394 395 // OS Error Codes 396 #define osRtxErrorStackUnderflow 1U ///< \deprecated Superseded by \ref osRtxErrorStackOverflow. 397 #define osRtxErrorStackOverflow 1U ///< Stack overflow, i.e. stack pointer below its lower memory limit for descending stacks. 398 #define osRtxErrorISRQueueOverflow 2U ///< ISR Queue overflow detected when inserting object. 399 #define osRtxErrorTimerQueueOverflow 3U ///< User Timer Callback Queue overflow detected for timer. 400 #define osRtxErrorClibSpace 4U ///< Standard C/C++ library libspace not available: increase \c OS_THREAD_LIBSPACE_NUM. 401 #define osRtxErrorClibMutex 5U ///< Standard C/C++ library mutex initialization failed. 402 403 /// OS Error Callback function 404 extern uint32_t osRtxErrorNotify (uint32_t code, void *object_id); 405 extern uint32_t osRtxKernelErrorNotify (uint32_t code, void *object_id); 406 407 /// OS Idle Thread 408 extern void osRtxIdleThread (void *argument); 409 410 /// OS Exception handlers 411 extern void SVC_Handler (void); 412 extern void PendSV_Handler (void); 413 extern void SysTick_Handler (void); 414 415 /// OS Trusted Firmware M Extension 416 #ifdef RTX_TF_M_EXTENSION 417 extern uint32_t osRtxTzGetModuleId (void); 418 #endif 419 420 421 // ==== OS External Configuration ==== 422 423 /// OS Configuration flags 424 #define osRtxConfigPrivilegedMode (1UL<<0) ///< Threads in Privileged mode 425 #define osRtxConfigStackCheck (1UL<<1) ///< Stack overrun checking 426 #define osRtxConfigStackWatermark (1UL<<2) ///< Stack usage Watermark 427 428 /// OS Configuration structure 429 typedef struct { 430 uint32_t flags; ///< OS Configuration Flags 431 uint32_t tick_freq; ///< Kernel Tick Frequency 432 uint32_t robin_timeout; ///< Round Robin Timeout Tick 433 struct { ///< ISR Post Processing Queue 434 void **data; ///< Queue Data 435 uint16_t max; ///< Maximum Items 436 uint16_t padding; 437 } isr_queue; 438 struct { ///< Memory Pools (Variable Block Size) 439 void *stack_addr; ///< Stack Memory Address 440 uint32_t stack_size; ///< Stack Memory Size 441 void *mp_data_addr; ///< Memory Pool Memory Address 442 uint32_t mp_data_size; ///< Memory Pool Memory Size 443 void *mq_data_addr; ///< Message Queue Data Memory Address 444 uint32_t mq_data_size; ///< Message Queue Data Memory Size 445 void *common_addr; ///< Common Memory Address 446 uint32_t common_size; ///< Common Memory Size 447 } mem; 448 struct { ///< Memory Pools (Fixed Block Size) 449 osRtxMpInfo_t *stack; ///< Stack for Threads 450 osRtxMpInfo_t *thread; ///< Thread Control Blocks 451 osRtxMpInfo_t *timer; ///< Timer Control Blocks 452 osRtxMpInfo_t *event_flags; ///< Event Flags Control Blocks 453 osRtxMpInfo_t *mutex; ///< Mutex Control Blocks 454 osRtxMpInfo_t *semaphore; ///< Semaphore Control Blocks 455 osRtxMpInfo_t *memory_pool; ///< Memory Pool Control Blocks 456 osRtxMpInfo_t *message_queue; ///< Message Queue Control Blocks 457 } mpi; 458 uint32_t thread_stack_size; ///< Default Thread Stack Size 459 const 460 osThreadAttr_t *idle_thread_attr; ///< Idle Thread Attributes 461 const 462 osThreadAttr_t *timer_thread_attr; ///< Timer Thread Attributes 463 void (*timer_thread)(void *); ///< Timer Thread Function 464 int32_t (*timer_setup)(void); ///< Timer Setup Function 465 const 466 osMessageQueueAttr_t *timer_mq_attr; ///< Timer Message Queue Attributes 467 uint32_t timer_mq_mcnt; ///< Timer Message Queue maximum Messages 468 } osRtxConfig_t; 469 470 extern const osRtxConfig_t osRtxConfig; ///< OS Configuration 471 472 473 #ifdef __cplusplus 474 } 475 #endif 476 477 #endif // RTX_OS_H_ 478
