Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
cmsis_os.h
1 /*
2  * Copyright (c) 2013-2017 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  * $Date: 30. October 2017
21  * $Revision: V2.1.2
22  *
23  * Project: CMSIS-RTOS API
24  * Title: cmsis_os.h RTX header file
25  *
26  * Version 0.02
27  * Initial Proposal Phase
28  * Version 0.03
29  * osKernelStart added, optional feature: main started as thread
30  * osSemaphores have standard behavior
31  * osTimerCreate does not start the timer, added osTimerStart
32  * osThreadPass is renamed to osThreadYield
33  * Version 1.01
34  * Support for C++ interface
35  * - const attribute removed from the osXxxxDef_t typedefs
36  * - const attribute added to the osXxxxDef macros
37  * Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
38  * Added: osKernelInitialize
39  * Version 1.02
40  * Control functions for short timeouts in microsecond resolution:
41  * Added: osKernelSysTick, osKernelSysTickFrequency, osKernelSysTickMicroSec
42  * Removed: osSignalGet
43  * Version 2.0.0
44  * OS objects creation without macros (dynamic creation and resource allocation):
45  * - added: osXxxxNew functions which replace osXxxxCreate
46  * - added: osXxxxAttr_t structures
47  * - deprecated: osXxxxCreate functions, osXxxxDef_t structures
48  * - deprecated: osXxxxDef and osXxxx macros
49  * osStatus codes simplified and renamed to osStatus_t
50  * osEvent return structure deprecated
51  * Kernel:
52  * - added: osKernelInfo_t and osKernelGetInfo
53  * - added: osKernelState_t and osKernelGetState (replaces osKernelRunning)
54  * - added: osKernelLock, osKernelUnlock
55  * - added: osKernelSuspend, osKernelResume
56  * - added: osKernelGetTickCount, osKernelGetTickFreq
57  * - renamed osKernelSysTick to osKernelGetSysTimerCount
58  * - replaced osKernelSysTickFrequency with osKernelGetSysTimerFreq
59  * - deprecated osKernelSysTickMicroSec
60  * Thread:
61  * - extended number of thread priorities
62  * - renamed osPrioriry to osPrioriry_t
63  * - replaced osThreadCreate with osThreadNew
64  * - added: osThreadGetName
65  * - added: osThreadState_t and osThreadGetState
66  * - added: osThreadGetStackSize, osThreadGetStackSpace
67  * - added: osThreadSuspend, osThreadResume
68  * - added: osThreadJoin, osThreadDetach, osThreadExit
69  * - added: osThreadGetCount, osThreadEnumerate
70  * - added: Thread Flags (moved from Signals)
71  * Signals:
72  * - renamed osSignals to osThreadFlags (moved to Thread Flags)
73  * - changed return value of Set/Clear/Wait functions
74  * - Clear function limited to current running thread
75  * - extended Wait function (options)
76  * - added: osThreadFlagsGet
77  * Event Flags:
78  * - added new independent object for handling Event Flags
79  * Delay and Wait functions:
80  * - added: osDelayUntil
81  * - deprecated: osWait
82  * Timer:
83  * - replaced osTimerCreate with osTimerNew
84  * - added: osTimerGetName, osTimerIsRunning
85  * Mutex:
86  * - extended: attributes (Recursive, Priority Inherit, Robust)
87  * - replaced osMutexCreate with osMutexNew
88  * - renamed osMutexWait to osMutexAcquire
89  * - added: osMutexGetName, osMutexGetOwner
90  * Semaphore:
91  * - extended: maximum and initial token count
92  * - replaced osSemaphoreCreate with osSemaphoreNew
93  * - renamed osSemaphoreWait to osSemaphoreAcquire (changed return value)
94  * - added: osSemaphoreGetName, osSemaphoreGetCount
95  * Memory Pool:
96  * - using osMemoryPool prefix instead of osPool
97  * - replaced osPoolCreate with osMemoryPoolNew
98  * - extended osMemoryPoolAlloc (timeout)
99  * - added: osMemoryPoolGetName
100  * - added: osMemoryPoolGetCapacity, osMemoryPoolGetBlockSize
101  * - added: osMemoryPoolGetCount, osMemoryPoolGetSpace
102  * - added: osMemoryPoolDelete
103  * - deprecated: osPoolCAlloc
104  * Message Queue:
105  * - extended: fixed size message instead of a single 32-bit value
106  * - using osMessageQueue prefix instead of osMessage
107  * - replaced osMessageCreate with osMessageQueueNew
108  * - updated: osMessageQueuePut, osMessageQueueGet
109  * - added: osMessageQueueGetName
110  * - added: osMessageQueueGetCapacity, osMessageQueueGetMsgSize
111  * - added: osMessageQueueGetCount, osMessageQueueGetSpace
112  * - added: osMessageQueueReset, osMessageQueueDelete
113  * Mail Queue:
114  * - deprecated (superseded by extended Message Queue functionality)
115  * Version 2.1.0
116  * Support for critical and uncritical sections (nesting safe):
117  * - updated: osKernelLock, osKernelUnlock
118  * - added: osKernelRestoreLock
119  * Updated Thread and Event Flags:
120  * - changed flags parameter and return type from int32_t to uint32_t
121  * Version 2.1.1
122  * Additional functions allowed to be called from Interrupt Service Routines:
123  * - osKernelGetTickCount, osKernelGetTickFreq
124  * Changed Kernel Tick type to uint32_t:
125  * - updated: osKernelGetTickCount, osDelayUntil
126  * Version 2.1.2
127  * Additional functions allowed to be called from Interrupt Service Routines:
128  * - osKernelGetInfo, osKernelGetState
129  *---------------------------------------------------------------------------*/
130 
131 #ifndef CMSIS_OS_H_
132 #define CMSIS_OS_H_
133 
134 #define osCMSIS 0x20001U ///< API version (main[31:16].sub[15:0])
135 
136 #define osCMSIS_RTX 0x50003U ///< RTOS identification and version (main[31:16].sub[15:0])
137 
138 #define osKernelSystemId "RTX V5.3" ///< RTOS identification string
139 
140 #define osFeature_MainThread 0 ///< main thread 1=main can be thread, 0=not available
141 #define osFeature_Signals 31U ///< maximum number of Signal Flags available per thread
142 #define osFeature_Semaphore 65535U ///< maximum count for \ref osSemaphoreCreate function
143 #define osFeature_Wait 0 ///< osWait function: 1=available, 0=not available
144 #define osFeature_SysTick 1 ///< osKernelSysTick functions: 1=available, 0=not available
145 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available
146 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available
147 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available
148 
149 #if defined(__CC_ARM)
150 #define os_InRegs __value_in_regs
151 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
152 #define os_InRegs __attribute__((value_in_regs))
153 #else
154 #define os_InRegs
155 #endif
156 
157 #if (osCMSIS >= 0x20000U)
158 #include "cmsis_os2.h"
159 #else
160 #include <stdint.h>
161 #include <stddef.h>
162 #endif
163 #include "rtx_os.h"
164 
165 #ifdef __cplusplus
166 extern "C"
167 {
168 #endif
169 
170 
171 // ==== Enumerations, structures, defines ====
172 
173 /// Priority values.
174 #if (osCMSIS < 0x20000U)
175 typedef enum {
176  osPriorityIdle = -3, ///< Priority: idle (lowest)
177  osPriorityLow = -2, ///< Priority: low
178  osPriorityBelowNormal = -1, ///< Priority: below normal
179  osPriorityNormal = 0, ///< Priority: normal (default)
180  osPriorityAboveNormal = +1, ///< Priority: above normal
181  osPriorityHigh = +2, ///< Priority: high
182  osPriorityRealtime = +3, ///< Priority: realtime (highest)
183  osPriorityError = 0x84, ///< System cannot determine priority or illegal priority.
184  osPriorityReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization.
185 } osPriority;
186 #else
187 #define osPriority osPriority_t
188 #endif
189 
190 /// Entry point of a thread.
191 typedef void (*os_pthread) (void const *argument);
192 
193 /// Entry point of a timer call back function.
194 typedef void (*os_ptimer) (void const *argument);
195 
196 /// Timer type.
197 #if (osCMSIS < 0x20000U)
198 typedef enum {
199  osTimerOnce = 0, ///< One-shot timer.
200  osTimerPeriodic = 1 ///< Repeating timer.
201 } os_timer_type;
202 #else
203 #define os_timer_type osTimerType_t
204 #endif
205 
206 /// Timeout value.
207 #define osWaitForever 0xFFFFFFFFU ///< Wait forever timeout value.
208 
209 /// Status code values returned by CMSIS-RTOS functions.
210 #if (osCMSIS < 0x20000U)
211 typedef enum {
212  osOK = 0, ///< Function completed; no error or event occurred.
213  osEventSignal = 0x08, ///< Function completed; signal event occurred.
214  osEventMessage = 0x10, ///< Function completed; message event occurred.
215  osEventMail = 0x20, ///< Function completed; mail event occurred.
216  osEventTimeout = 0x40, ///< Function completed; timeout occurred.
217  osErrorParameter = 0x80, ///< Parameter error: a mandatory parameter was missing or specified an incorrect object.
218  osErrorResource = 0x81, ///< Resource not available: a specified resource was not available.
219  osErrorTimeoutResource = 0xC1, ///< Resource not available within given time: a specified resource was not available within the timeout period.
220  osErrorISR = 0x82, ///< Not allowed in ISR context: the function cannot be called from interrupt service routines.
221  osErrorISRRecursive = 0x83, ///< Function called multiple times from ISR with same object.
222  osErrorPriority = 0x84, ///< System cannot determine priority or thread has illegal priority.
223  osErrorNoMemory = 0x85, ///< System is out of memory: it was impossible to allocate or reserve memory for the operation.
224  osErrorValue = 0x86, ///< Value of a parameter is out of range.
225  osErrorOS = 0xFF, ///< Unspecified RTOS error: run-time error but no other error message fits.
226  osStatusReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization.
227 } osStatus;
228 #else
229 typedef int32_t osStatus;
230 #define osEventSignal (0x08)
231 #define osEventMessage (0x10)
232 #define osEventMail (0x20)
233 #define osEventTimeout (0x40)
234 #define osErrorOS osError
235 #define osErrorTimeoutResource osErrorTimeout
236 #define osErrorISRRecursive (-126)
237 #define osErrorValue (-127)
238 #define osErrorPriority (-128)
239 #endif
240 
241 
242 // >>> the following data type definitions may be adapted towards a specific RTOS
243 
244 /// Thread ID identifies the thread.
245 #if (osCMSIS < 0x20000U)
246 typedef void *osThreadId;
247 #else
248 #define osThreadId osThreadId_t
249 #endif
250 
251 /// Timer ID identifies the timer.
252 #if (osCMSIS < 0x20000U)
253 typedef void *osTimerId;
254 #else
255 #define osTimerId osTimerId_t
256 #endif
257 
258 /// Mutex ID identifies the mutex.
259 #if (osCMSIS < 0x20000U)
260 typedef void *osMutexId;
261 #else
262 #define osMutexId osMutexId_t
263 #endif
264 
265 /// Semaphore ID identifies the semaphore.
266 #if (osCMSIS < 0x20000U)
267 typedef void *osSemaphoreId;
268 #else
269 #define osSemaphoreId osSemaphoreId_t
270 #endif
271 
272 /// Pool ID identifies the memory pool.
273 typedef void *osPoolId;
274 
275 /// Message ID identifies the message queue.
276 typedef void *osMessageQId;
277 
278 /// Mail ID identifies the mail queue.
279 typedef void *osMailQId;
280 
281 
282 /// Thread Definition structure contains startup information of a thread.
283 #if (osCMSIS < 0x20000U)
284 typedef struct os_thread_def {
285  os_pthread pthread; ///< start address of thread function
286  osPriority tpriority; ///< initial thread priority
287  uint32_t instances; ///< maximum number of instances of that thread function
288  uint32_t stacksize; ///< stack size requirements in bytes; 0 is default stack size
289 } osThreadDef_t;
290 #else
291 typedef struct os_thread_def {
292  os_pthread pthread; ///< start address of thread function
293  osThreadAttr_t attr; ///< thread attributes
294 } osThreadDef_t;
295 #endif
296 
297 /// Timer Definition structure contains timer parameters.
298 #if (osCMSIS < 0x20000U)
299 typedef struct os_timer_def {
300  os_ptimer ptimer; ///< start address of a timer function
301 } osTimerDef_t;
302 #else
303 typedef struct os_timer_def {
304  os_ptimer ptimer; ///< start address of a timer function
305  osTimerAttr_t attr; ///< timer attributes
306 } osTimerDef_t;
307 #endif
308 
309 /// Mutex Definition structure contains setup information for a mutex.
310 #if (osCMSIS < 0x20000U)
311 typedef struct os_mutex_def {
312  uint32_t dummy; ///< dummy value
313 } osMutexDef_t;
314 #else
315 #define osMutexDef_t osMutexAttr_t
316 #endif
317 
318 /// Semaphore Definition structure contains setup information for a semaphore.
319 #if (osCMSIS < 0x20000U)
320 typedef struct os_semaphore_def {
321  uint32_t dummy; ///< dummy value
322 } osSemaphoreDef_t;
323 #else
324 #define osSemaphoreDef_t osSemaphoreAttr_t
325 #endif
326 
327 /// Definition structure for memory block allocation.
328 #if (osCMSIS < 0x20000U)
329 typedef struct os_pool_def {
330  uint32_t pool_sz; ///< number of items (elements) in the pool
331  uint32_t item_sz; ///< size of an item
332  void *pool; ///< pointer to memory for pool
333 } osPoolDef_t;
334 #else
335 typedef struct os_pool_def {
336  uint32_t pool_sz; ///< number of items (elements) in the pool
337  uint32_t item_sz; ///< size of an item
338  osMemoryPoolAttr_t attr; ///< memory pool attributes
339 } osPoolDef_t;
340 #endif
341 
342 /// Definition structure for message queue.
343 #if (osCMSIS < 0x20000U)
344 typedef struct os_messageQ_def {
345  uint32_t queue_sz; ///< number of elements in the queue
346  void *pool; ///< memory array for messages
347 } osMessageQDef_t;
348 #else
349 typedef struct os_messageQ_def {
350  uint32_t queue_sz; ///< number of elements in the queue
351  osMessageQueueAttr_t attr; ///< message queue attributes
352 } osMessageQDef_t;
353 #endif
354 
355 /// Definition structure for mail queue.
356 #if (osCMSIS < 0x20000U)
357 typedef struct os_mailQ_def {
358  uint32_t queue_sz; ///< number of elements in the queue
359  uint32_t item_sz; ///< size of an item
360  void *pool; ///< memory array for mail
361 } osMailQDef_t;
362 #else
363 typedef struct os_mailQ_def {
364  uint32_t queue_sz; ///< number of elements in the queue
365  uint32_t item_sz; ///< size of an item
366  void *mail; ///< pointer to mail
367  osMemoryPoolAttr_t mp_attr; ///< memory pool attributes
368  osMessageQueueAttr_t mq_attr; ///< message queue attributes
369 } osMailQDef_t;
370 #endif
371 
372 
373 /// Event structure contains detailed information about an event.
374 typedef struct {
375  osStatus status; ///< status code: event or error information
376  union {
377  uint32_t v; ///< message as 32-bit value
378  void *p; ///< message or mail as void pointer
379  int32_t signals; ///< signal flags
380  } value; ///< event value
381  union {
382  osMailQId mail_id; ///< mail id obtained by \ref osMailCreate
383  osMessageQId message_id; ///< message id obtained by \ref osMessageCreate
384  } def; ///< event definition
385 } osEvent;
386 
387 
388 // ==== Kernel Management Functions ====
389 
390 /// Initialize the RTOS Kernel for creating objects.
391 /// \return status code that indicates the execution status of the function.
392 #if (osCMSIS < 0x20000U)
393 osStatus osKernelInitialize (void);
394 #endif
395 
396 /// Start the RTOS Kernel scheduler.
397 /// \return status code that indicates the execution status of the function.
398 #if (osCMSIS < 0x20000U)
399 osStatus osKernelStart (void);
400 #endif
401 
402 /// Check if the RTOS kernel is already started.
403 /// \return 0 RTOS is not started, 1 RTOS is started.
404 #if (osCMSIS < 0x20000U)
405 int32_t osKernelRunning(void);
406 #endif
407 
408 #if (defined(osFeature_SysTick) && (osFeature_SysTick != 0)) // System Timer available
409 
410 /// Get the RTOS kernel system timer counter.
411 /// \return RTOS kernel system timer as 32-bit value
412 #if (osCMSIS < 0x20000U)
413 uint32_t osKernelSysTick (void);
414 #else
415 #define osKernelSysTick osKernelGetSysTimerCount
416 #endif
417 
418 /// The RTOS kernel system timer frequency in Hz.
419 /// \note Reflects the system timer setting and is typically defined in a configuration file.
420 #if (osCMSIS < 0x20000U)
421 #define osKernelSysTickFrequency 100000000
422 #endif
423 
424 /// Convert a microseconds value to a RTOS kernel system timer value.
425 /// \param microsec time value in microseconds.
426 /// \return time value normalized to the \ref osKernelSysTickFrequency
427 #if (osCMSIS < 0x20000U)
428 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
429 #else
430 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * osKernelGetSysTimerFreq()) / 1000000)
431 #endif
432 
433 #endif // System Timer available
434 
435 
436 // ==== Thread Management Functions ====
437 
438 /// Create a Thread Definition with function, priority, and stack requirements.
439 /// \param name name of the thread function.
440 /// \param priority initial priority of the thread function.
441 /// \param stacksz stack size (in bytes) requirements for the thread function.
442 #if defined (osObjectsExternal) // object is external
443 #define osThreadDef(name, priority, stacksz) \
444 extern const osThreadDef_t os_thread_def_##name
445 #else // define the object
446 #if (osCMSIS < 0x20000U)
447 #define osThreadDef(name, priority, stacksz) \
448 const osThreadDef_t os_thread_def_##name = \
449 { (name), (priority), 1, (stacksz) }
450 #else
451 #define osThreadDef(name, priority, stacksz) \
452 uint64_t os_thread_stack##name[(stacksz)?(((stacksz+7)/8)):1] __attribute__((section(".bss.os.thread.stack"))); \
453 static osRtxThread_t os_thread_cb_##name __attribute__((section(".bss.os.thread.cb"))); \
454 const osThreadDef_t os_thread_def_##name = \
455 { (name), \
456  { NULL, osThreadDetached, \
457  &os_thread_cb_##name,\
458  osRtxThreadCbSize, \
459  (stacksz) ? (&os_thread_stack##name) : NULL, \
460  8*((stacksz+7)/8), \
461  (priority), 0U, 0U } }
462 #endif
463 #endif
464 
465 /// Access a Thread definition.
466 /// \param name name of the thread definition object.
467 #define osThread(name) \
468 &os_thread_def_##name
469 
470 /// Create a thread and add it to Active Threads and set it to state READY.
471 /// \param[in] thread_def thread definition referenced with \ref osThread.
472 /// \param[in] argument pointer that is passed to the thread function as start argument.
473 /// \return thread ID for reference by other functions or NULL in case of error.
474 osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument);
475 
476 /// Return the thread ID of the current running thread.
477 /// \return thread ID for reference by other functions or NULL in case of error.
478 #if (osCMSIS < 0x20000U)
479 osThreadId osThreadGetId (void);
480 #endif
481 
482 /// Change priority of a thread.
483 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
484 /// \param[in] priority new priority value for the thread function.
485 /// \return status code that indicates the execution status of the function.
486 #if (osCMSIS < 0x20000U)
487 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
488 #endif
489 
490 /// Get current priority of a thread.
491 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
492 /// \return current priority value of the specified thread.
493 #if (osCMSIS < 0x20000U)
494 osPriority osThreadGetPriority (osThreadId thread_id);
495 #endif
496 
497 /// Pass control to next thread that is in state \b READY.
498 /// \return status code that indicates the execution status of the function.
499 #if (osCMSIS < 0x20000U)
500 osStatus osThreadYield (void);
501 #endif
502 
503 /// Terminate execution of a thread.
504 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
505 /// \return status code that indicates the execution status of the function.
506 #if (osCMSIS < 0x20000U)
507 osStatus osThreadTerminate (osThreadId thread_id);
508 #endif
509 
510 
511 // ==== Signal Management ====
512 
513 /// Set the specified Signal Flags of an active thread.
514 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
515 /// \param[in] signals specifies the signal flags of the thread that should be set.
516 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
517 int32_t osSignalSet (osThreadId thread_id, int32_t signals);
518 
519 /// Clear the specified Signal Flags of an active thread.
520 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
521 /// \param[in] signals specifies the signal flags of the thread that shall be cleared.
522 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters or call from ISR.
523 int32_t osSignalClear (osThreadId thread_id, int32_t signals);
524 
525 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread.
526 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag.
527 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
528 /// \return event flag information or error code.
529 os_InRegs osEvent osSignalWait (int32_t signals, uint32_t millisec);
530 
531 
532 // ==== Generic Wait Functions ====
533 
534 /// Wait for Timeout (Time Delay).
535 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue "time delay" value
536 /// \return status code that indicates the execution status of the function.
537 #if (osCMSIS < 0x20000U)
538 osStatus osDelay (uint32_t millisec);
539 #endif
540 
541 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available
542 
543 /// Wait for Signal, Message, Mail, or Timeout.
544 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
545 /// \return event that contains signal, message, or mail information or error code.
546 os_InRegs osEvent osWait (uint32_t millisec);
547 
548 #endif // Generic Wait available
549 
550 
551 // ==== Timer Management Functions ====
552 
553 /// Define a Timer object.
554 /// \param name name of the timer object.
555 /// \param function name of the timer call back function.
556 #if defined (osObjectsExternal) // object is external
557 #define osTimerDef(name, function) \
558 extern const osTimerDef_t os_timer_def_##name
559 #else // define the object
560 #if (osCMSIS < 0x20000U)
561 #define osTimerDef(name, function) \
562 const osTimerDef_t os_timer_def_##name = { (function) }
563 #else
564 #define osTimerDef(name, function) \
565 static osRtxTimer_t os_timer_cb_##name __attribute__((section(".bss.os.timer.cb"))); \
566 const osTimerDef_t os_timer_def_##name = \
567 { (function), { NULL, 0U, (&os_timer_cb_##name), osRtxTimerCbSize } }
568 #endif
569 #endif
570 
571 /// Access a Timer definition.
572 /// \param name name of the timer object.
573 #define osTimer(name) \
574 &os_timer_def_##name
575 
576 /// Create and Initialize a timer.
577 /// \param[in] timer_def timer object referenced with \ref osTimer.
578 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
579 /// \param[in] argument argument to the timer call back function.
580 /// \return timer ID for reference by other functions or NULL in case of error.
581 osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument);
582 
583 /// Start or restart a timer.
584 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate.
585 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue "time delay" value of the timer.
586 /// \return status code that indicates the execution status of the function.
587 #if (osCMSIS < 0x20000U)
588 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
589 #endif
590 
591 /// Stop a timer.
592 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate.
593 /// \return status code that indicates the execution status of the function.
594 #if (osCMSIS < 0x20000U)
595 osStatus osTimerStop (osTimerId timer_id);
596 #endif
597 
598 /// Delete a timer.
599 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate.
600 /// \return status code that indicates the execution status of the function.
601 #if (osCMSIS < 0x20000U)
602 osStatus osTimerDelete (osTimerId timer_id);
603 #endif
604 
605 
606 // ==== Mutex Management Functions ====
607 
608 /// Define a Mutex.
609 /// \param name name of the mutex object.
610 #if defined (osObjectsExternal) // object is external
611 #define osMutexDef(name) \
612 extern const osMutexDef_t os_mutex_def_##name
613 #else // define the object
614 #if (osCMSIS < 0x20000U)
615 #define osMutexDef(name) \
616 const osMutexDef_t os_mutex_def_##name = { 0 }
617 #else
618 #define osMutexDef(name) \
619 static osRtxMutex_t os_mutex_cb_##name __attribute__((section(".bss.os.mutex.cb"))); \
620 const osMutexDef_t os_mutex_def_##name = \
621 { NULL, osMutexRecursive | osMutexPrioInherit | osMutexRobust, (&os_mutex_cb_##name), osRtxMutexCbSize }
622 #endif
623 #endif
624 
625 /// Access a Mutex definition.
626 /// \param name name of the mutex object.
627 #define osMutex(name) \
628 &os_mutex_def_##name
629 
630 /// Create and Initialize a Mutex object.
631 /// \param[in] mutex_def mutex definition referenced with \ref osMutex.
632 /// \return mutex ID for reference by other functions or NULL in case of error.
633 osMutexId osMutexCreate (const osMutexDef_t *mutex_def);
634 
635 /// Wait until a Mutex becomes available.
636 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate.
637 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
638 /// \return status code that indicates the execution status of the function.
639 #if (osCMSIS < 0x20000U)
640 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
641 #else
642 #define osMutexWait osMutexAcquire
643 #endif
644 
645 /// Release a Mutex that was obtained by \ref osMutexWait.
646 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate.
647 /// \return status code that indicates the execution status of the function.
648 #if (osCMSIS < 0x20000U)
649 osStatus osMutexRelease (osMutexId mutex_id);
650 #endif
651 
652 /// Delete a Mutex object.
653 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate.
654 /// \return status code that indicates the execution status of the function.
655 #if (osCMSIS < 0x20000U)
656 osStatus osMutexDelete (osMutexId mutex_id);
657 #endif
658 
659 
660 // ==== Semaphore Management Functions ====
661 
662 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0U)) // Semaphore available
663 
664 /// Define a Semaphore object.
665 /// \param name name of the semaphore object.
666 #if defined (osObjectsExternal) // object is external
667 #define osSemaphoreDef(name) \
668 extern const osSemaphoreDef_t os_semaphore_def_##name
669 #else // define the object
670 #if (osCMSIS < 0x20000U)
671 #define osSemaphoreDef(name) \
672 const osSemaphoreDef_t os_semaphore_def_##name = { 0 }
673 #else
674 #define osSemaphoreDef(name) \
675 static osRtxSemaphore_t os_semaphore_cb_##name __attribute__((section(".bss.os.semaphore.cb"))); \
676 const osSemaphoreDef_t os_semaphore_def_##name = \
677 { NULL, 0U, (&os_semaphore_cb_##name), osRtxSemaphoreCbSize }
678 #endif
679 #endif
680 
681 /// Access a Semaphore definition.
682 /// \param name name of the semaphore object.
683 #define osSemaphore(name) \
684 &os_semaphore_def_##name
685 
686 /// Create and Initialize a Semaphore object.
687 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore.
688 /// \param[in] count maximum and initial number of available tokens.
689 /// \return semaphore ID for reference by other functions or NULL in case of error.
690 osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count);
691 
692 /// Wait until a Semaphore token becomes available.
693 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate.
694 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
695 /// \return number of available tokens, or -1 in case of incorrect parameters.
696 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
697 
698 /// Release a Semaphore token.
699 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate.
700 /// \return status code that indicates the execution status of the function.
701 #if (osCMSIS < 0x20000U)
702 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
703 #endif
704 
705 /// Delete a Semaphore object.
706 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphoreCreate.
707 /// \return status code that indicates the execution status of the function.
708 #if (osCMSIS < 0x20000U)
709 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id);
710 #endif
711 
712 #endif // Semaphore available
713 
714 
715 // ==== Memory Pool Management Functions ====
716 
717 #if (defined(osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool available
718 
719 /// \brief Define a Memory Pool.
720 /// \param name name of the memory pool.
721 /// \param no maximum number of blocks (objects) in the memory pool.
722 /// \param type data type of a single block (object).
723 #if defined (osObjectsExternal) // object is external
724 #define osPoolDef(name, no, type) \
725 extern const osPoolDef_t os_pool_def_##name
726 #else // define the object
727 #if (osCMSIS < 0x20000U)
728 #define osPoolDef(name, no, type) \
729 const osPoolDef_t os_pool_def_##name = \
730 { (no), sizeof(type), NULL }
731 #else
732 #define osPoolDef(name, no, type) \
733 static osRtxMemoryPool_t os_mp_cb_##name __attribute__((section(".bss.os.mempool.cb"))); \
734 static uint32_t os_mp_data_##name[osRtxMemoryPoolMemSize((no),sizeof(type))/4] __attribute__((section(".bss.os.mempool.mem"))); \
735 const osPoolDef_t os_pool_def_##name = \
736 { (no), sizeof(type), \
737  { NULL, 0U, (&os_mp_cb_##name), osRtxMemoryPoolCbSize, \
738  (&os_mp_data_##name), sizeof(os_mp_data_##name) } }
739 #endif
740 #endif
741 
742 /// \brief Access a Memory Pool definition.
743 /// \param name name of the memory pool
744 #define osPool(name) \
745 &os_pool_def_##name
746 
747 /// Create and Initialize a Memory Pool object.
748 /// \param[in] pool_def memory pool definition referenced with \ref osPool.
749 /// \return memory pool ID for reference by other functions or NULL in case of error.
750 osPoolId osPoolCreate (const osPoolDef_t *pool_def);
751 
752 /// Allocate a memory block from a Memory Pool.
753 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate.
754 /// \return address of the allocated memory block or NULL in case of no memory available.
755 void *osPoolAlloc (osPoolId pool_id);
756 
757 /// Allocate a memory block from a Memory Pool and set memory block to zero.
758 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate.
759 /// \return address of the allocated memory block or NULL in case of no memory available.
760 void *osPoolCAlloc (osPoolId pool_id);
761 
762 /// Return an allocated memory block back to a Memory Pool.
763 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate.
764 /// \param[in] block address of the allocated memory block to be returned to the memory pool.
765 /// \return status code that indicates the execution status of the function.
766 osStatus osPoolFree (osPoolId pool_id, void *block);
767 
768 #endif // Memory Pool available
769 
770 
771 // ==== Message Queue Management Functions ====
772 
773 #if (defined(osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queue available
774 
775 /// \brief Create a Message Queue Definition.
776 /// \param name name of the queue.
777 /// \param queue_sz maximum number of messages in the queue.
778 /// \param type data type of a single message element (for debugger).
779 #if defined (osObjectsExternal) // object is external
780 #define osMessageQDef(name, queue_sz, type) \
781 extern const osMessageQDef_t os_messageQ_def_##name
782 #else // define the object
783 #if (osCMSIS < 0x20000U)
784 #define osMessageQDef(name, queue_sz, type) \
785 const osMessageQDef_t os_messageQ_def_##name = \
786 { (queue_sz), NULL }
787 #else
788 #define osMessageQDef(name, queue_sz, type) \
789 static osRtxMessageQueue_t os_mq_cb_##name __attribute__((section(".bss.os.msgqueue.cb"))); \
790 static uint32_t os_mq_data_##name[osRtxMessageQueueMemSize((queue_sz),sizeof(uint32_t))/4] __attribute__((section(".bss.os.msgqueue.mem"))); \
791 const osMessageQDef_t os_messageQ_def_##name = \
792 { (queue_sz), \
793  { NULL, 0U, (&os_mq_cb_##name), osRtxMessageQueueCbSize, \
794  (&os_mq_data_##name), sizeof(os_mq_data_##name) } }
795 #endif
796 #endif
797 
798 /// \brief Access a Message Queue Definition.
799 /// \param name name of the queue
800 #define osMessageQ(name) \
801 &os_messageQ_def_##name
802 
803 /// Create and Initialize a Message Queue object.
804 /// \param[in] queue_def message queue definition referenced with \ref osMessageQ.
805 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
806 /// \return message queue ID for reference by other functions or NULL in case of error.
807 osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id);
808 
809 /// Put a Message to a Queue.
810 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate.
811 /// \param[in] info message information.
812 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
813 /// \return status code that indicates the execution status of the function.
814 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
815 
816 /// Get a Message from a Queue or timeout if Queue is empty.
817 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate.
818 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
819 /// \return event information that includes status code.
820 os_InRegs osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
821 
822 #endif // Message Queue available
823 
824 
825 // ==== Mail Queue Management Functions ====
826 
827 #if (defined(osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queue available
828 
829 /// \brief Create a Mail Queue Definition.
830 /// \param name name of the queue.
831 /// \param queue_sz maximum number of mails in the queue.
832 /// \param type data type of a single mail element.
833 #if defined (osObjectsExternal) // object is external
834 #define osMailQDef(name, queue_sz, type) \
835 extern const osMailQDef_t os_mailQ_def_##name
836 #else // define the object
837 #if (osCMSIS < 0x20000U)
838 #define osMailQDef(name, queue_sz, type) \
839 const osMailQDef_t os_mailQ_def_##name = \
840 { (queue_sz), sizeof(type), NULL }
841 #else
842 #define osMailQDef(name, queue_sz, type) \
843 static void *os_mail_p_##name[2] __attribute__((section(".bss.os"))); \
844 static osRtxMemoryPool_t os_mail_mp_cb_##name __attribute__((section(".bss.os.mempool.cb"))); \
845 static osRtxMessageQueue_t os_mail_mq_cb_##name __attribute__((section(".bss.os.msgqueue.cb"))); \
846 static uint32_t os_mail_mp_data_##name[osRtxMemoryPoolMemSize ((queue_sz),sizeof(type) )/4] __attribute__((section(".bss.os.mempool.mem"))); \
847 static uint32_t os_mail_mq_data_##name[osRtxMessageQueueMemSize((queue_sz),sizeof(void*))/4] __attribute__((section(".bss.os.msgqueue.mem"))); \
848 const osMailQDef_t os_mailQ_def_##name = \
849 { (queue_sz), sizeof(type), (&os_mail_p_##name), \
850  { NULL, 0U, (&os_mail_mp_cb_##name), osRtxMemoryPoolCbSize, \
851  (&os_mail_mp_data_##name), sizeof(os_mail_mp_data_##name) }, \
852  { NULL, 0U, (&os_mail_mq_cb_##name), osRtxMessageQueueCbSize, \
853  (&os_mail_mq_data_##name), sizeof(os_mail_mq_data_##name) } }
854 #endif
855 #endif
856 
857 /// \brief Access a Mail Queue Definition.
858 /// \param name name of the queue
859 #define osMailQ(name) \
860 &os_mailQ_def_##name
861 
862 /// Create and Initialize a Mail Queue object.
863 /// \param[in] queue_def mail queue definition referenced with \ref osMailQ.
864 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
865 /// \return mail queue ID for reference by other functions or NULL in case of error.
866 osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id);
867 
868 /// Allocate a memory block for mail from a mail memory pool.
869 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
870 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
871 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
872 void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
873 
874 /// Allocate a memory block for mail from a mail memory pool and set memory block to zero.
875 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
876 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out
877 /// \return pointer to memory block that can be filled with mail or NULL in case of error.
878 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
879 
880 /// Put a Mail into a Queue.
881 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
882 /// \param[in] mail pointer to memory with mail to put into a queue.
883 /// \return status code that indicates the execution status of the function.
884 osStatus osMailPut (osMailQId queue_id, const void *mail);
885 
886 /// Get a Mail from a Queue or timeout if Queue is empty.
887 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
888 /// \param[in] millisec \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
889 /// \return event information that includes status code.
890 os_InRegs osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
891 
892 /// Free a memory block by returning it to a mail memory pool.
893 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
894 /// \param[in] mail pointer to memory block that was obtained with \ref osMailGet.
895 /// \return status code that indicates the execution status of the function.
896 osStatus osMailFree (osMailQId queue_id, void *mail);
897 
898 #endif // Mail Queue available
899 
900 
901 #ifdef __cplusplus
902 }
903 #endif
904 
905 #endif // CMSIS_OS_H_
os_pool_def::item_sz
uint32_t item_sz
size of an item
Definition: cmsis_os.h:337
osEvent::v
uint32_t v
message as 32-bit value
Definition: cmsis_os.h:377
os_timer_def
Timer Definition structure contains timer parameters.
Definition: cmsis_os.h:303
os_thread_def
Thread Definition structure contains startup information of a thread.
Definition: cmsis_os.h:291
os_mailQ_def::mail
void * mail
pointer to mail
Definition: cmsis_os.h:366
osThreadAttr_t
Attributes structure for thread.
Definition: cmsis_os2.h:240
os_pool_def::attr
osMemoryPoolAttr_t attr
memory pool attributes
Definition: cmsis_os.h:338
osEvent::signals
int32_t signals
signal flags
Definition: cmsis_os.h:379
os_mailQ_def
Definition structure for mail queue.
Definition: cmsis_os.h:363
os_mailQ_def::item_sz
uint32_t item_sz
size of an item
Definition: cmsis_os.h:365
os_pool_def::pool_sz
uint32_t pool_sz
number of items (elements) in the pool
Definition: cmsis_os.h:336
os_timer_def::attr
osTimerAttr_t attr
timer attributes
Definition: cmsis_os.h:305
osMemoryPoolAttr_t
Attributes structure for memory pool.
Definition: cmsis_os2.h:285
info
The key size.
Definition: kvstore_global_api.h:38
os_thread_def::pthread
os_pthread pthread
start address of thread function
Definition: cmsis_os.h:292
osMessageQueueAttr_t
Attributes structure for message queue.
Definition: cmsis_os2.h:295
osEvent::p
void * p
message or mail as void pointer
Definition: cmsis_os.h:378
osEvent::mail_id
osMailQId mail_id
mail id obtained by osMailCreate
Definition: cmsis_os.h:382
os_messageQ_def
Definition structure for message queue.
Definition: cmsis_os.h:349
osEvent::status
osStatus status
status code: event or error information
Definition: cmsis_os.h:375
osEvent
Event structure contains detailed information about an event.
Definition: cmsis_os.h:374
os_messageQ_def::attr
osMessageQueueAttr_t attr
message queue attributes
Definition: cmsis_os.h:351
osTimerAttr_t
Attributes structure for timer.
Definition: cmsis_os2.h:253
os_mailQ_def::mq_attr
osMessageQueueAttr_t mq_attr
message queue attributes
Definition: cmsis_os.h:368
osEvent::message_id
osMessageQId message_id
message id obtained by osMessageCreate
Definition: cmsis_os.h:383
os_timer_def::ptimer
os_ptimer ptimer
start address of a timer function
Definition: cmsis_os.h:304
os_messageQ_def::queue_sz
uint32_t queue_sz
number of elements in the queue
Definition: cmsis_os.h:350
os_mailQ_def::mp_attr
osMemoryPoolAttr_t mp_attr
memory pool attributes
Definition: cmsis_os.h:367
os_mailQ_def::queue_sz
uint32_t queue_sz
number of elements in the queue
Definition: cmsis_os.h:364
os_pool_def
Definition structure for memory block allocation.
Definition: cmsis_os.h:335
os_thread_def::attr
osThreadAttr_t attr
thread attributes
Definition: cmsis_os.h:293
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.