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