Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
cmsis_os2.h
1 /*
2  * Copyright (c) 2013-2018 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: 18. June 2018
21  * $Revision: V2.1.3
22  *
23  * Project: CMSIS-RTOS2 API
24  * Title: cmsis_os2.h header file
25  *
26  * Version 2.1.3
27  * Additional functions allowed to be called from Interrupt Service Routines:
28  * - osThreadGetId
29  * Version 2.1.2
30  * Additional functions allowed to be called from Interrupt Service Routines:
31  * - osKernelGetInfo, osKernelGetState
32  * Version 2.1.1
33  * Additional functions allowed to be called from Interrupt Service Routines:
34  * - osKernelGetTickCount, osKernelGetTickFreq
35  * Changed Kernel Tick type to uint32_t:
36  * - updated: osKernelGetTickCount, osDelayUntil
37  * Version 2.1.0
38  * Support for critical and uncritical sections (nesting safe):
39  * - updated: osKernelLock, osKernelUnlock
40  * - added: osKernelRestoreLock
41  * Updated Thread and Event Flags:
42  * - changed flags parameter and return type from int32_t to uint32_t
43  * Version 2.0.0
44  * Initial Release
45  *---------------------------------------------------------------------------*/
46 
47 #ifndef CMSIS_OS2_H_
48 #define CMSIS_OS2_H_
49 
50 #ifndef __NO_RETURN
51 #if defined(__CC_ARM)
52 #define __NO_RETURN __declspec(noreturn)
53 #elif defined(__ARMCC_VERSION) && (__ARMCC_VERSION >= 6010050)
54 #define __NO_RETURN __attribute__((__noreturn__))
55 #elif defined(__GNUC__)
56 #define __NO_RETURN __attribute__((__noreturn__))
57 #elif defined(__ICCARM__)
58 #define __NO_RETURN __noreturn
59 #else
60 #define __NO_RETURN
61 #endif
62 #endif
63 
64 #include <stdint.h>
65 #include <stddef.h>
66 
67 #ifdef __cplusplus
68 extern "C"
69 {
70 #endif
71 
72 
73 // ==== Enumerations, structures, defines ====
74 
75 /// Version information.
76 typedef struct {
77  uint32_t api; ///< API version (major.minor.rev: mmnnnrrrr dec).
78  uint32_t kernel; ///< Kernel version (major.minor.rev: mmnnnrrrr dec).
79 } osVersion_t;
80 
81 /// Kernel state.
82 typedef enum {
83  osKernelInactive = 0, ///< Inactive.
84  osKernelReady = 1, ///< Ready.
85  osKernelRunning = 2, ///< Running.
86  osKernelLocked = 3, ///< Locked.
87  osKernelSuspended = 4, ///< Suspended.
88  osKernelError = -1, ///< Error.
89  osKernelReserved = 0x7FFFFFFFU ///< Prevents enum down-size compiler optimization.
90 } osKernelState_t;
91 
92 /// Thread state.
93 typedef enum {
94  osThreadInactive = 0, ///< Inactive.
95  osThreadReady = 1, ///< Ready.
96  osThreadRunning = 2, ///< Running.
97  osThreadBlocked = 3, ///< Blocked.
98  osThreadTerminated = 4, ///< Terminated.
99  osThreadError = -1, ///< Error.
100  osThreadReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization.
101 } osThreadState_t;
102 
103 /// Priority values.
104 typedef enum {
105  osPriorityNone = 0, ///< No priority (not initialized).
106  osPriorityIdle = 1, ///< Reserved for Idle thread.
107  osPriorityLow = 8, ///< Priority: low
108  osPriorityLow1 = 8+1, ///< Priority: low + 1
109  osPriorityLow2 = 8+2, ///< Priority: low + 2
110  osPriorityLow3 = 8+3, ///< Priority: low + 3
111  osPriorityLow4 = 8+4, ///< Priority: low + 4
112  osPriorityLow5 = 8+5, ///< Priority: low + 5
113  osPriorityLow6 = 8+6, ///< Priority: low + 6
114  osPriorityLow7 = 8+7, ///< Priority: low + 7
115  osPriorityBelowNormal = 16, ///< Priority: below normal
116  osPriorityBelowNormal1 = 16+1, ///< Priority: below normal + 1
117  osPriorityBelowNormal2 = 16+2, ///< Priority: below normal + 2
118  osPriorityBelowNormal3 = 16+3, ///< Priority: below normal + 3
119  osPriorityBelowNormal4 = 16+4, ///< Priority: below normal + 4
120  osPriorityBelowNormal5 = 16+5, ///< Priority: below normal + 5
121  osPriorityBelowNormal6 = 16+6, ///< Priority: below normal + 6
122  osPriorityBelowNormal7 = 16+7, ///< Priority: below normal + 7
123  osPriorityNormal = 24, ///< Priority: normal
124  osPriorityNormal1 = 24+1, ///< Priority: normal + 1
125  osPriorityNormal2 = 24+2, ///< Priority: normal + 2
126  osPriorityNormal3 = 24+3, ///< Priority: normal + 3
127  osPriorityNormal4 = 24+4, ///< Priority: normal + 4
128  osPriorityNormal5 = 24+5, ///< Priority: normal + 5
129  osPriorityNormal6 = 24+6, ///< Priority: normal + 6
130  osPriorityNormal7 = 24+7, ///< Priority: normal + 7
131  osPriorityAboveNormal = 32, ///< Priority: above normal
132  osPriorityAboveNormal1 = 32+1, ///< Priority: above normal + 1
133  osPriorityAboveNormal2 = 32+2, ///< Priority: above normal + 2
134  osPriorityAboveNormal3 = 32+3, ///< Priority: above normal + 3
135  osPriorityAboveNormal4 = 32+4, ///< Priority: above normal + 4
136  osPriorityAboveNormal5 = 32+5, ///< Priority: above normal + 5
137  osPriorityAboveNormal6 = 32+6, ///< Priority: above normal + 6
138  osPriorityAboveNormal7 = 32+7, ///< Priority: above normal + 7
139  osPriorityHigh = 40, ///< Priority: high
140  osPriorityHigh1 = 40+1, ///< Priority: high + 1
141  osPriorityHigh2 = 40+2, ///< Priority: high + 2
142  osPriorityHigh3 = 40+3, ///< Priority: high + 3
143  osPriorityHigh4 = 40+4, ///< Priority: high + 4
144  osPriorityHigh5 = 40+5, ///< Priority: high + 5
145  osPriorityHigh6 = 40+6, ///< Priority: high + 6
146  osPriorityHigh7 = 40+7, ///< Priority: high + 7
147  osPriorityRealtime = 48, ///< Priority: realtime
148  osPriorityRealtime1 = 48+1, ///< Priority: realtime + 1
149  osPriorityRealtime2 = 48+2, ///< Priority: realtime + 2
150  osPriorityRealtime3 = 48+3, ///< Priority: realtime + 3
151  osPriorityRealtime4 = 48+4, ///< Priority: realtime + 4
152  osPriorityRealtime5 = 48+5, ///< Priority: realtime + 5
153  osPriorityRealtime6 = 48+6, ///< Priority: realtime + 6
154  osPriorityRealtime7 = 48+7, ///< Priority: realtime + 7
155  osPriorityISR = 56, ///< Reserved for ISR deferred thread.
156  osPriorityError = -1, ///< System cannot determine priority or illegal priority.
157  osPriorityReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization.
158 } osPriority_t;
159 
160 /// Entry point of a thread.
161 typedef void (*osThreadFunc_t) (void *argument);
162 
163 /// Timer callback function.
164 typedef void (*osTimerFunc_t) (void *argument);
165 
166 /// Timer type.
167 typedef enum {
168  osTimerOnce = 0, ///< One-shot timer.
169  osTimerPeriodic = 1 ///< Repeating timer.
170 } osTimerType_t;
171 
172 // Timeout value.
173 #define osWaitForever 0xFFFFFFFFU ///< Wait forever timeout value.
174 
175 // Flags options (\ref osThreadFlagsWait and \ref osEventFlagsWait).
176 #define osFlagsWaitAny 0x00000000U ///< Wait for any flag (default).
177 #define osFlagsWaitAll 0x00000001U ///< Wait for all flags.
178 #define osFlagsNoClear 0x00000002U ///< Do not clear flags which have been specified to wait for.
179 
180 // Flags errors (returned by osThreadFlagsXxxx and osEventFlagsXxxx).
181 #define osFlagsError 0x80000000U ///< Error indicator.
182 #define osFlagsErrorUnknown 0xFFFFFFFFU ///< osError (-1).
183 #define osFlagsErrorTimeout 0xFFFFFFFEU ///< osErrorTimeout (-2).
184 #define osFlagsErrorResource 0xFFFFFFFDU ///< osErrorResource (-3).
185 #define osFlagsErrorParameter 0xFFFFFFFCU ///< osErrorParameter (-4).
186 #define osFlagsErrorISR 0xFFFFFFFAU ///< osErrorISR (-6).
187 
188 // Thread attributes (attr_bits in \ref osThreadAttr_t).
189 #define osThreadDetached 0x00000000U ///< Thread created in detached mode (default)
190 #define osThreadJoinable 0x00000001U ///< Thread created in joinable mode
191 
192 // Mutex attributes (attr_bits in \ref osMutexAttr_t).
193 #define osMutexRecursive 0x00000001U ///< Recursive mutex.
194 #define osMutexPrioInherit 0x00000002U ///< Priority inherit protocol.
195 #define osMutexRobust 0x00000008U ///< Robust mutex.
196 
197 /// Status code values returned by CMSIS-RTOS functions.
198 typedef enum {
199  osOK = 0, ///< Operation completed successfully.
200  osError = -1, ///< Unspecified RTOS error: run-time error but no other error message fits.
201  osErrorTimeout = -2, ///< Operation not completed within the timeout period.
202  osErrorResource = -3, ///< Resource not available.
203  osErrorParameter = -4, ///< Parameter error.
204  osErrorNoMemory = -5, ///< System is out of memory: it was impossible to allocate or reserve memory for the operation.
205  osErrorISR = -6, ///< Not allowed in ISR context: the function cannot be called from interrupt service routines.
206  osStatusReserved = 0x7FFFFFFF ///< Prevents enum down-size compiler optimization.
207 } osStatus_t;
208 
209 
210 /// \details Thread ID identifies the thread.
211 typedef void *osThreadId_t;
212 
213 /// \details Timer ID identifies the timer.
214 typedef void *osTimerId_t;
215 
216 /// \details Event Flags ID identifies the event flags.
217 typedef void *osEventFlagsId_t;
218 
219 /// \details Mutex ID identifies the mutex.
220 typedef void *osMutexId_t;
221 
222 /// \details Semaphore ID identifies the semaphore.
223 typedef void *osSemaphoreId_t;
224 
225 /// \details Memory Pool ID identifies the memory pool.
226 typedef void *osMemoryPoolId_t;
227 
228 /// \details Message Queue ID identifies the message queue.
229 typedef void *osMessageQueueId_t;
230 
231 
232 #ifndef TZ_MODULEID_T
233 #define TZ_MODULEID_T
234 /// \details Data type that identifies secure software modules called by a process.
235 typedef uint32_t TZ_ModuleId_t;
236 #endif
237 
238 
239 /// Attributes structure for thread.
240 typedef struct {
241  const char *name; ///< name of the thread
242  uint32_t attr_bits; ///< attribute bits
243  void *cb_mem; ///< memory for control block
244  uint32_t cb_size; ///< size of provided memory for control block
245  void *stack_mem; ///< memory for stack
246  uint32_t stack_size; ///< size of stack
247  osPriority_t priority; ///< initial thread priority (default: osPriorityNormal)
248  TZ_ModuleId_t tz_module; ///< TrustZone module identifier
249  uint32_t reserved; ///< reserved (must be 0)
250 } osThreadAttr_t;
251 
252 /// Attributes structure for timer.
253 typedef struct {
254  const char *name; ///< name of the timer
255  uint32_t attr_bits; ///< attribute bits
256  void *cb_mem; ///< memory for control block
257  uint32_t cb_size; ///< size of provided memory for control block
258 } osTimerAttr_t;
259 
260 /// Attributes structure for event flags.
261 typedef struct {
262  const char *name; ///< name of the event flags
263  uint32_t attr_bits; ///< attribute bits
264  void *cb_mem; ///< memory for control block
265  uint32_t cb_size; ///< size of provided memory for control block
266 } osEventFlagsAttr_t;
267 
268 /// Attributes structure for mutex.
269 typedef struct {
270  const char *name; ///< name of the mutex
271  uint32_t attr_bits; ///< attribute bits
272  void *cb_mem; ///< memory for control block
273  uint32_t cb_size; ///< size of provided memory for control block
274 } osMutexAttr_t;
275 
276 /// Attributes structure for semaphore.
277 typedef struct {
278  const char *name; ///< name of the semaphore
279  uint32_t attr_bits; ///< attribute bits
280  void *cb_mem; ///< memory for control block
281  uint32_t cb_size; ///< size of provided memory for control block
282 } osSemaphoreAttr_t;
283 
284 /// Attributes structure for memory pool.
285 typedef struct {
286  const char *name; ///< name of the memory pool
287  uint32_t attr_bits; ///< attribute bits
288  void *cb_mem; ///< memory for control block
289  uint32_t cb_size; ///< size of provided memory for control block
290  void *mp_mem; ///< memory for data storage
291  uint32_t mp_size; ///< size of provided memory for data storage
292 } osMemoryPoolAttr_t;
293 
294 /// Attributes structure for message queue.
295 typedef struct {
296  const char *name; ///< name of the message queue
297  uint32_t attr_bits; ///< attribute bits
298  void *cb_mem; ///< memory for control block
299  uint32_t cb_size; ///< size of provided memory for control block
300  void *mq_mem; ///< memory for data storage
301  uint32_t mq_size; ///< size of provided memory for data storage
302 } osMessageQueueAttr_t;
303 
304 
305 // ==== Kernel Management Functions ====
306 
307 /// Initialize the RTOS Kernel.
308 /// \return status code that indicates the execution status of the function.
309 osStatus_t osKernelInitialize (void);
310 
311 /// Get RTOS Kernel Information.
312 /// \param[out] version pointer to buffer for retrieving version information.
313 /// \param[out] id_buf pointer to buffer for retrieving kernel identification string.
314 /// \param[in] id_size size of buffer for kernel identification string.
315 /// \return status code that indicates the execution status of the function.
316 osStatus_t osKernelGetInfo (osVersion_t *version, char *id_buf, uint32_t id_size);
317 
318 /// Get the current RTOS Kernel state.
319 /// \return current RTOS Kernel state.
320 osKernelState_t osKernelGetState (void);
321 
322 /// Start the RTOS Kernel scheduler.
323 /// \return status code that indicates the execution status of the function.
324 osStatus_t osKernelStart (void);
325 
326 /// Lock the RTOS Kernel scheduler.
327 /// \return previous lock state (1 - locked, 0 - not locked, error code if negative).
328 int32_t osKernelLock (void);
329 
330 /// Unlock the RTOS Kernel scheduler.
331 /// \return previous lock state (1 - locked, 0 - not locked, error code if negative).
332 int32_t osKernelUnlock (void);
333 
334 /// Restore the RTOS Kernel scheduler lock state.
335 /// \param[in] lock lock state obtained by \ref osKernelLock or \ref osKernelUnlock.
336 /// \return new lock state (1 - locked, 0 - not locked, error code if negative).
337 int32_t osKernelRestoreLock (int32_t lock);
338 
339 /// Suspend the RTOS Kernel scheduler.
340 /// \return time in ticks, for how long the system can sleep or power-down.
341 uint32_t osKernelSuspend (void);
342 
343 /// Resume the RTOS Kernel scheduler.
344 /// \param[in] sleep_ticks time in ticks for how long the system was in sleep or power-down mode.
345 void osKernelResume (uint32_t sleep_ticks);
346 
347 /// Get the RTOS kernel tick count.
348 /// \return RTOS kernel current tick count.
349 uint32_t osKernelGetTickCount (void);
350 
351 /// Get the RTOS kernel tick frequency.
352 /// \return frequency of the kernel tick in hertz, i.e. kernel ticks per second.
353 uint32_t osKernelGetTickFreq (void);
354 
355 /// Get the RTOS kernel system timer count.
356 /// \return RTOS kernel current system timer count as 32-bit value.
357 uint32_t osKernelGetSysTimerCount (void);
358 
359 /// Get the RTOS kernel system timer frequency.
360 /// \return frequency of the system timer in hertz, i.e. timer ticks per second.
361 uint32_t osKernelGetSysTimerFreq (void);
362 
363 
364 // ==== Thread Management Functions ====
365 
366 /// Create a thread and add it to Active Threads.
367 /// \param[in] func thread function.
368 /// \param[in] argument pointer that is passed to the thread function as start argument.
369 /// \param[in] attr thread attributes; NULL: default values.
370 /// \return thread ID for reference by other functions or NULL in case of error.
371 osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);
372 
373 /// Get name of a thread.
374 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
375 /// \return name as null-terminated string.
376 const char *osThreadGetName (osThreadId_t thread_id);
377 
378 /// Return the thread ID of the current running thread.
379 /// \return thread ID for reference by other functions or NULL in case of error.
380 osThreadId_t osThreadGetId (void);
381 
382 /// Get current thread state of a thread.
383 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
384 /// \return current thread state of the specified thread.
385 osThreadState_t osThreadGetState (osThreadId_t thread_id);
386 
387 /// Get stack size of a thread.
388 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
389 /// \return stack size in bytes.
390 uint32_t osThreadGetStackSize (osThreadId_t thread_id);
391 
392 /// Get available stack space of a thread based on stack watermark recording during execution.
393 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
394 /// \return remaining stack space in bytes.
395 uint32_t osThreadGetStackSpace (osThreadId_t thread_id);
396 
397 /// Change priority of a thread.
398 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
399 /// \param[in] priority new priority value for the thread function.
400 /// \return status code that indicates the execution status of the function.
401 osStatus_t osThreadSetPriority (osThreadId_t thread_id, osPriority_t priority);
402 
403 /// Get current priority of a thread.
404 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
405 /// \return current priority value of the specified thread.
406 osPriority_t osThreadGetPriority (osThreadId_t thread_id);
407 
408 /// Pass control to next thread that is in state \b READY.
409 /// \return status code that indicates the execution status of the function.
410 osStatus_t osThreadYield (void);
411 
412 /// Suspend execution of a thread.
413 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
414 /// \return status code that indicates the execution status of the function.
415 osStatus_t osThreadSuspend (osThreadId_t thread_id);
416 
417 /// Resume execution of a thread.
418 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
419 /// \return status code that indicates the execution status of the function.
420 osStatus_t osThreadResume (osThreadId_t thread_id);
421 
422 /// Detach a thread (thread storage can be reclaimed when thread terminates).
423 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
424 /// \return status code that indicates the execution status of the function.
425 osStatus_t osThreadDetach (osThreadId_t thread_id);
426 
427 /// Wait for specified thread to terminate.
428 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
429 /// \return status code that indicates the execution status of the function.
430 osStatus_t osThreadJoin (osThreadId_t thread_id);
431 
432 /// Terminate execution of current running thread.
433 __NO_RETURN void osThreadExit (void);
434 
435 /// Terminate execution of a thread.
436 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
437 /// \return status code that indicates the execution status of the function.
438 osStatus_t osThreadTerminate (osThreadId_t thread_id);
439 
440 /// Get number of active threads.
441 /// \return number of active threads.
442 uint32_t osThreadGetCount (void);
443 
444 /// Enumerate active threads.
445 /// \param[out] thread_array pointer to array for retrieving thread IDs.
446 /// \param[in] array_items maximum number of items in array for retrieving thread IDs.
447 /// \return number of enumerated threads.
448 uint32_t osThreadEnumerate (osThreadId_t *thread_array, uint32_t array_items);
449 
450 
451 // ==== Thread Flags Functions ====
452 
453 /// Set the specified Thread Flags of a thread.
454 /// \param[in] thread_id thread ID obtained by \ref osThreadNew or \ref osThreadGetId.
455 /// \param[in] flags specifies the flags of the thread that shall be set.
456 /// \return thread flags after setting or error code if highest bit set.
457 uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags);
458 
459 /// Clear the specified Thread Flags of current running thread.
460 /// \param[in] flags specifies the flags of the thread that shall be cleared.
461 /// \return thread flags before clearing or error code if highest bit set.
462 uint32_t osThreadFlagsClear (uint32_t flags);
463 
464 /// Get the current Thread Flags of current running thread.
465 /// \return current thread flags.
466 uint32_t osThreadFlagsGet (void);
467 
468 /// Wait for one or more Thread Flags of the current running thread to become signaled.
469 /// \param[in] flags specifies the flags to wait for.
470 /// \param[in] options specifies flags options (osFlagsXxxx).
471 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
472 /// \return thread flags before clearing or error code if highest bit set.
473 uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout);
474 
475 
476 // ==== Generic Wait Functions ====
477 
478 /// Wait for Timeout (Time Delay).
479 /// \param[in] ticks \ref CMSIS_RTOS_TimeOutValue "time ticks" value
480 /// \return status code that indicates the execution status of the function.
481 osStatus_t osDelay (uint32_t ticks);
482 
483 /// Wait until specified time.
484 /// \param[in] ticks absolute time in ticks
485 /// \return status code that indicates the execution status of the function.
486 osStatus_t osDelayUntil (uint32_t ticks);
487 
488 
489 // ==== Timer Management Functions ====
490 
491 /// Create and Initialize a timer.
492 /// \param[in] func function pointer to callback function.
493 /// \param[in] type \ref osTimerOnce for one-shot or \ref osTimerPeriodic for periodic behavior.
494 /// \param[in] argument argument to the timer callback function.
495 /// \param[in] attr timer attributes; NULL: default values.
496 /// \return timer ID for reference by other functions or NULL in case of error.
497 osTimerId_t osTimerNew (osTimerFunc_t func, osTimerType_t type, void *argument, const osTimerAttr_t *attr);
498 
499 /// Get name of a timer.
500 /// \param[in] timer_id timer ID obtained by \ref osTimerNew.
501 /// \return name as null-terminated string.
502 const char *osTimerGetName (osTimerId_t timer_id);
503 
504 /// Start or restart a timer.
505 /// \param[in] timer_id timer ID obtained by \ref osTimerNew.
506 /// \param[in] ticks \ref CMSIS_RTOS_TimeOutValue "time ticks" value of the timer.
507 /// \return status code that indicates the execution status of the function.
508 osStatus_t osTimerStart (osTimerId_t timer_id, uint32_t ticks);
509 
510 /// Stop a timer.
511 /// \param[in] timer_id timer ID obtained by \ref osTimerNew.
512 /// \return status code that indicates the execution status of the function.
513 osStatus_t osTimerStop (osTimerId_t timer_id);
514 
515 /// Check if a timer is running.
516 /// \param[in] timer_id timer ID obtained by \ref osTimerNew.
517 /// \return 0 not running, 1 running.
518 uint32_t osTimerIsRunning (osTimerId_t timer_id);
519 
520 /// Delete a timer.
521 /// \param[in] timer_id timer ID obtained by \ref osTimerNew.
522 /// \return status code that indicates the execution status of the function.
523 osStatus_t osTimerDelete (osTimerId_t timer_id);
524 
525 
526 // ==== Event Flags Management Functions ====
527 
528 /// Create and Initialize an Event Flags object.
529 /// \param[in] attr event flags attributes; NULL: default values.
530 /// \return event flags ID for reference by other functions or NULL in case of error.
531 osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr);
532 
533 /// Get name of an Event Flags object.
534 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew.
535 /// \return name as null-terminated string.
536 const char *osEventFlagsGetName (osEventFlagsId_t ef_id);
537 
538 /// Set the specified Event Flags.
539 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew.
540 /// \param[in] flags specifies the flags that shall be set.
541 /// \return event flags after setting or error code if highest bit set.
542 uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags);
543 
544 /// Clear the specified Event Flags.
545 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew.
546 /// \param[in] flags specifies the flags that shall be cleared.
547 /// \return event flags before clearing or error code if highest bit set.
548 uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags);
549 
550 /// Get the current Event Flags.
551 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew.
552 /// \return current event flags.
553 uint32_t osEventFlagsGet (osEventFlagsId_t ef_id);
554 
555 /// Wait for one or more Event Flags to become signaled.
556 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew.
557 /// \param[in] flags specifies the flags to wait for.
558 /// \param[in] options specifies flags options (osFlagsXxxx).
559 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
560 /// \return event flags before clearing or error code if highest bit set.
561 uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout);
562 
563 /// Delete an Event Flags object.
564 /// \param[in] ef_id event flags ID obtained by \ref osEventFlagsNew.
565 /// \return status code that indicates the execution status of the function.
566 osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id);
567 
568 
569 // ==== Mutex Management Functions ====
570 
571 /// Create and Initialize a Mutex object.
572 /// \param[in] attr mutex attributes; NULL: default values.
573 /// \return mutex ID for reference by other functions or NULL in case of error.
574 osMutexId_t osMutexNew (const osMutexAttr_t *attr);
575 
576 /// Get name of a Mutex object.
577 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew.
578 /// \return name as null-terminated string.
579 const char *osMutexGetName (osMutexId_t mutex_id);
580 
581 /// Acquire a Mutex or timeout if it is locked.
582 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew.
583 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
584 /// \return status code that indicates the execution status of the function.
585 osStatus_t osMutexAcquire (osMutexId_t mutex_id, uint32_t timeout);
586 
587 /// Release a Mutex that was acquired by \ref osMutexAcquire.
588 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew.
589 /// \return status code that indicates the execution status of the function.
590 osStatus_t osMutexRelease (osMutexId_t mutex_id);
591 
592 /// Get Thread which owns a Mutex object.
593 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew.
594 /// \return thread ID of owner thread or NULL when mutex was not acquired.
595 osThreadId_t osMutexGetOwner (osMutexId_t mutex_id);
596 
597 /// Delete a Mutex object.
598 /// \param[in] mutex_id mutex ID obtained by \ref osMutexNew.
599 /// \return status code that indicates the execution status of the function.
600 osStatus_t osMutexDelete (osMutexId_t mutex_id);
601 
602 
603 // ==== Semaphore Management Functions ====
604 
605 /// Create and Initialize a Semaphore object.
606 /// \param[in] max_count maximum number of available tokens.
607 /// \param[in] initial_count initial number of available tokens.
608 /// \param[in] attr semaphore attributes; NULL: default values.
609 /// \return semaphore ID for reference by other functions or NULL in case of error.
610 osSemaphoreId_t osSemaphoreNew (uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t *attr);
611 
612 /// Get name of a Semaphore object.
613 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew.
614 /// \return name as null-terminated string.
615 const char *osSemaphoreGetName (osSemaphoreId_t semaphore_id);
616 
617 /// Acquire a Semaphore token or timeout if no tokens are available.
618 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew.
619 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
620 /// \return status code that indicates the execution status of the function.
621 osStatus_t osSemaphoreAcquire (osSemaphoreId_t semaphore_id, uint32_t timeout);
622 
623 /// Release a Semaphore token up to the initial maximum count.
624 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew.
625 /// \return status code that indicates the execution status of the function.
626 osStatus_t osSemaphoreRelease (osSemaphoreId_t semaphore_id);
627 
628 /// Get current Semaphore token count.
629 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew.
630 /// \return number of tokens available.
631 uint32_t osSemaphoreGetCount (osSemaphoreId_t semaphore_id);
632 
633 /// Delete a Semaphore object.
634 /// \param[in] semaphore_id semaphore ID obtained by \ref osSemaphoreNew.
635 /// \return status code that indicates the execution status of the function.
636 osStatus_t osSemaphoreDelete (osSemaphoreId_t semaphore_id);
637 
638 
639 // ==== Memory Pool Management Functions ====
640 
641 /// Create and Initialize a Memory Pool object.
642 /// \param[in] block_count maximum number of memory blocks in memory pool.
643 /// \param[in] block_size memory block size in bytes.
644 /// \param[in] attr memory pool attributes; NULL: default values.
645 /// \return memory pool ID for reference by other functions or NULL in case of error.
646 osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr);
647 
648 /// Get name of a Memory Pool object.
649 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
650 /// \return name as null-terminated string.
651 const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id);
652 
653 /// Allocate a memory block from a Memory Pool.
654 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
655 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
656 /// \return address of the allocated memory block or NULL in case of no memory is available.
657 void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout);
658 
659 /// Return an allocated memory block back to a Memory Pool.
660 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
661 /// \param[in] block address of the allocated memory block to be returned to the memory pool.
662 /// \return status code that indicates the execution status of the function.
663 osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block);
664 
665 /// Get maximum number of memory blocks in a Memory Pool.
666 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
667 /// \return maximum number of memory blocks.
668 uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id);
669 
670 /// Get memory block size in a Memory Pool.
671 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
672 /// \return memory block size in bytes.
673 uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id);
674 
675 /// Get number of memory blocks used in a Memory Pool.
676 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
677 /// \return number of memory blocks used.
678 uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id);
679 
680 /// Get number of memory blocks available in a Memory Pool.
681 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
682 /// \return number of memory blocks available.
683 uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id);
684 
685 /// Delete a Memory Pool object.
686 /// \param[in] mp_id memory pool ID obtained by \ref osMemoryPoolNew.
687 /// \return status code that indicates the execution status of the function.
688 osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id);
689 
690 
691 // ==== Message Queue Management Functions ====
692 
693 /// Create and Initialize a Message Queue object.
694 /// \param[in] msg_count maximum number of messages in queue.
695 /// \param[in] msg_size maximum message size in bytes.
696 /// \param[in] attr message queue attributes; NULL: default values.
697 /// \return message queue ID for reference by other functions or NULL in case of error.
698 osMessageQueueId_t osMessageQueueNew (uint32_t msg_count, uint32_t msg_size, const osMessageQueueAttr_t *attr);
699 
700 /// Get name of a Message Queue object.
701 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
702 /// \return name as null-terminated string.
703 const char *osMessageQueueGetName (osMessageQueueId_t mq_id);
704 
705 /// Put a Message into a Queue or timeout if Queue is full.
706 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
707 /// \param[in] msg_ptr pointer to buffer with message to put into a queue.
708 /// \param[in] msg_prio message priority.
709 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
710 /// \return status code that indicates the execution status of the function.
711 osStatus_t osMessageQueuePut (osMessageQueueId_t mq_id, const void *msg_ptr, uint8_t msg_prio, uint32_t timeout);
712 
713 /// Get a Message from a Queue or timeout if Queue is empty.
714 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
715 /// \param[out] msg_ptr pointer to buffer for message to get from a queue.
716 /// \param[out] msg_prio pointer to buffer for message priority or NULL.
717 /// \param[in] timeout \ref CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.
718 /// \return status code that indicates the execution status of the function.
719 osStatus_t osMessageQueueGet (osMessageQueueId_t mq_id, void *msg_ptr, uint8_t *msg_prio, uint32_t timeout);
720 
721 /// Get maximum number of messages in a Message Queue.
722 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
723 /// \return maximum number of messages.
724 uint32_t osMessageQueueGetCapacity (osMessageQueueId_t mq_id);
725 
726 /// Get maximum message size in a Memory Pool.
727 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
728 /// \return maximum message size in bytes.
729 uint32_t osMessageQueueGetMsgSize (osMessageQueueId_t mq_id);
730 
731 /// Get number of queued messages in a Message Queue.
732 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
733 /// \return number of queued messages.
734 uint32_t osMessageQueueGetCount (osMessageQueueId_t mq_id);
735 
736 /// Get number of available slots for messages in a Message Queue.
737 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
738 /// \return number of available slots for messages.
739 uint32_t osMessageQueueGetSpace (osMessageQueueId_t mq_id);
740 
741 /// Reset a Message Queue to initial empty state.
742 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
743 /// \return status code that indicates the execution status of the function.
744 osStatus_t osMessageQueueReset (osMessageQueueId_t mq_id);
745 
746 /// Delete a Message Queue object.
747 /// \param[in] mq_id message queue ID obtained by \ref osMessageQueueNew.
748 /// \return status code that indicates the execution status of the function.
749 osStatus_t osMessageQueueDelete (osMessageQueueId_t mq_id);
750 
751 
752 #ifdef __cplusplus
753 }
754 #endif
755 
756 #endif // CMSIS_OS2_H_
osMemoryPoolAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:287
osThreadAttr_t::tz_module
TZ_ModuleId_t tz_module
TrustZone module identifier.
Definition: cmsis_os2.h:248
osSemaphoreAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:280
osVersion_t::api
uint32_t api
API version (major.minor.rev: mmnnnrrrr dec).
Definition: cmsis_os2.h:77
osThreadAttr_t
Attributes structure for thread.
Definition: cmsis_os2.h:240
osThreadAttr_t::stack_size
uint32_t stack_size
size of stack
Definition: cmsis_os2.h:246
osSemaphoreAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:279
osEventFlagsAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:265
osTimerAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:257
osMemoryPoolAttr_t
Attributes structure for memory pool.
Definition: cmsis_os2.h:285
osThreadAttr_t::stack_mem
void * stack_mem
memory for stack
Definition: cmsis_os2.h:245
osMessageQueueAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:297
osMemoryPoolAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:288
osEventFlagsAttr_t::name
const char * name
name of the event flags
Definition: cmsis_os2.h:262
osEventFlagsAttr_t
Attributes structure for event flags.
Definition: cmsis_os2.h:261
osTimerAttr_t::name
const char * name
name of the timer
Definition: cmsis_os2.h:254
osMessageQueueAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:298
osMessageQueueAttr_t
Attributes structure for message queue.
Definition: cmsis_os2.h:295
osMemoryPoolAttr_t::mp_mem
void * mp_mem
memory for data storage
Definition: cmsis_os2.h:290
osTimerAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:256
osSemaphoreAttr_t::name
const char * name
name of the semaphore
Definition: cmsis_os2.h:278
osMemoryPoolAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:289
osMemoryPoolAttr_t::name
const char * name
name of the memory pool
Definition: cmsis_os2.h:286
osTimerAttr_t
Attributes structure for timer.
Definition: cmsis_os2.h:253
osEventFlagsAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:264
osMutexAttr_t::name
const char * name
name of the mutex
Definition: cmsis_os2.h:270
osThreadAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:242
osMutexAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:271
osSemaphoreAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:281
osVersion_t::kernel
uint32_t kernel
Kernel version (major.minor.rev: mmnnnrrrr dec).
Definition: cmsis_os2.h:78
osSemaphoreAttr_t
Attributes structure for semaphore.
Definition: cmsis_os2.h:277
osThreadAttr_t::priority
osPriority_t priority
initial thread priority (default: osPriorityNormal)
Definition: cmsis_os2.h:247
osVersion_t
Version information.
Definition: cmsis_os2.h:76
osThreadAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:244
osMutexAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:272
osThreadAttr_t::cb_mem
void * cb_mem
memory for control block
Definition: cmsis_os2.h:243
osTimerAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:255
osThreadAttr_t::name
const char * name
name of the thread
Definition: cmsis_os2.h:241
osMessageQueueAttr_t::mq_size
uint32_t mq_size
size of provided memory for data storage
Definition: cmsis_os2.h:301
osEventFlagsAttr_t::attr_bits
uint32_t attr_bits
attribute bits
Definition: cmsis_os2.h:263
osMutexAttr_t
Attributes structure for mutex.
Definition: cmsis_os2.h:269
osMessageQueueAttr_t::name
const char * name
name of the message queue
Definition: cmsis_os2.h:296
osMessageQueueAttr_t::mq_mem
void * mq_mem
memory for data storage
Definition: cmsis_os2.h:300
osThreadAttr_t::reserved
uint32_t reserved
reserved (must be 0)
Definition: cmsis_os2.h:249
osMemoryPoolAttr_t::mp_size
uint32_t mp_size
size of provided memory for data storage
Definition: cmsis_os2.h:291
osMessageQueueAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:299
osMutexAttr_t::cb_size
uint32_t cb_size
size of provided memory for control block
Definition: cmsis_os2.h:273
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.