CMSIS2000  0.0.7
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
cmsis_os.h
Go to the documentation of this file.
1 /* ----------------------------------------------------------------------
2  * Copyright (C) 2012 ARM Limited. All rights reserved.
3  *
4  * $Date: 5. March 2012
5  * $Revision: V0.03
6  *
7  * Project: CMSIS-RTOS API
8  * Title: cmsis_os.h template header file
9  *
10  * Version 0.02
11  * Initial Proposal Phase
12  * Version 0.03
13  * osKernelStart added, optional feature: main started as thread
14  * osSemaphores have standard behaviour
15  * osTimerCreate does not start the timer, added osTimerStart
16  * osThreadPass is renamed to osThreadYield
17  * -------------------------------------------------------------------- */
18 
19 /**
20 \page cmsis_os_h Header File Template: cmsis_os.h
21 
22 The file \b cmsis_os.h is a template header file for a CMSIS-RTOS compliant Real-Time Operating System (RTOS).
23 Each RTOS that is compliant with CMSIS-RTOS shall provide a specific \b cmsis_os.h header file that represents
24 its implementation.
25 
26 The file cmsis_os.h contains:
27  - CMSIS-RTOS API function definitions
28  - struct definitions for parameters and return types
29  - status and priority values used by CMSIS-RTOS API functions
30  - macros for defining threads and other kernel objects
31 
32 
33 <b>Name conventions and header file modifications</b>
34 
35 All definitions are prefixed with \b os to give an unique name space for CMSIS-RTOS functions.
36 Definitions that are prefixed \b os_ are not used in the application code but local to this header file.
37 All definitions and functions that belong to a module are grouped and have a common prefix, i.e. \b osThread.
38 
39 Definitions that are marked with <b>CAN BE CHANGED</b> can be adapted towards the needs of the actual CMSIS-RTOS implementation.
40 These definitions can be specific to the underlying RTOS kernel.
41 
42 Definitions that are marked with <b>MUST REMAIN UNCHANGED</b> cannot be altered. Otherwise the CMSIS-RTOS implementation is no longer
43 compliant to the standard. Note that some functions are optional and need not to be provided by every CMSIS-RTOS implementation.
44 
45 
46 <b>Function calls from interrupt service routines</b>
47 
48 The following CMSIS-RTOS functions can be called from threads and interrupt service routines (ISR):
49  - \ref osSignalSet
50  - \ref osSemaphoreRelease
51  - \ref osPoolAlloc, \ref osPoolCAlloc, \ref osPoolFree
52  - \ref osMessagePut, \ref osMessageGet
53  - \ref osMailAlloc, \ref osMailCAlloc, \ref osMailGet, \ref osMailPut, \ref osMailFree
54 
55 Functions that cannot be called from an ISR are verifying the interrupt status and return in case that they are called
56 from an ISR context the status code \b osErrorISR. In some implementations this condition might be caught using the HARD FAULT vector.
57 
58 Some CMSIS-RTOS implementations support CMSIS-RTOS function calls from multiple ISR at the same time.
59 If this is impossible, the CMSIS-RTOS rejects calls by nested ISR functions with the status code \b osErrorISRRecursive.
60 
61 
62 <b>Define and reference object definitions</b>
63 
64 With <b>\#define osObjectsExternal</b> objects are defined as external symbols. This allows to create a consistent header file
65 that is used troughtout a project as shown below:
66 
67 <i>Header File</i>
68 \code
69 #include <cmsis_os.h> // CMSIS RTOS header file
70 
71 // Thread definition
72 extern void thread_sample (void const *argument); // function prototype
73 osThreadDef (thread_sample, osPriorityBelowNormal, 1, 100);
74 
75 // Pool definition
76 osPoolDef(MyPool, 10, long);
77 \endcode
78 
79 
80 This header file defines all objects when included in a C/C++ source file. When <b>\#define osObjectsExternal</b> is
81 present before the header file, the objects are defined as external symbols. A single consistent header file can therefore be
82 used throughout the whole project.
83 
84 <i>Example</i>
85 \code
86 #include "osObjects.h" // Definition of the CMSIS-RTOS objects
87 \endcode
88 
89 \code
90 #define osObjectExternal // Objects will be defined as external symbols
91 #include "osObjects.h" // Reference to the CMSIS-RTOS objects
92 \endcode
93 
94 */
95 
96 #ifndef _CMSIS_OS_H
97 #define _CMSIS_OS_H
98 
99 /// \note MUST REMAIN UNCHANGED: \b osCMSIS identifies the CMSIS-RTOS API version
100 #define osCMSIS 0x00003 ///< API version (main [31:16] .sub [15:0])
101 
102 /// \note CAN BE CHANGED: \b osCMSIS_KERNEL identifies the underlaying RTOS kernel and version number.
103 #define osCMSIS_KERNEL 0x10000 ///< RTOS identification and version (main [31:16] .sub [15:0])
104 
105 /// \note MUST REMAIN UNCHANGED: \b osKernelSystemId shall be consistent in every CMSIS-RTOS.
106 #define osKernelSystemId "KERNEL V1.00" ///< RTOS identification string
107 
108 /// \note MUST REMAIN UNCHANGED: \b osFeature_xxx shall be consistent in every CMSIS-RTOS.
109 #define osFeature_MainThread 1 ///< main thread 1=main can be thread, 0=not available
110 #define osFeature_Pool 1 ///< Memory Pools: 1=available, 0=not available
111 #define osFeature_MailQ 1 ///< Mail Queues: 1=available, 0=not available
112 #define osFeature_MessageQ 1 ///< Message Queues: 1=available, 0=not available
113 #define osFeature_Signals 8 ///< maximum number of Signal Flags available per thread
114 #define osFeature_Semaphore 30 ///< maximum count for SemaphoreInit function
115 #define osFeature_Wait 1 ///< osWait function: 1=available, 0=not available
116 
117 #include <stdint.h>
118 #include <stddef.h>
119 
120 #ifdef __cplusplus
121 extern "C"
122 {
123 #endif
124 
125 
126 // ==== Enumeration, structures, defines ====
127 
128 /// Priority used for thread control.
129 /// \note MUST REMAIN UNCHANGED: \b osPriority shall be consistent in every CMSIS-RTOS.
130 typedef enum {
131  osPriorityIdle = -3, ///< priority: idle (lowest)
132  osPriorityLow = -2, ///< priority: low
133  osPriorityBelowNormal = -1, ///< priority: below normal
134  osPriorityNormal = 0, ///< priority: normal (default)
135  osPriorityAboveNormal = +1, ///< priority: above normal
136  osPriorityHigh = +2, ///< priority: high
137  osPriorityRealtime = +3, ///< priority: realtime (highest)
138  osPriorityError = 0x84 ///< system cannot determine priority or thread has illegal priority
139 } osPriority;
140 
141 /// Timeout value
142 /// \note MUST REMAIN UNCHANGED: \b osWaitForever shall be consistent in every CMSIS-RTOS.
143 #define osWaitForever 0xFFFFFFFF ///< wait forever timeout value
144 
145 /// Status code values returned by CMSIS-RTOS functions
146 /// \note MUST REMAIN UNCHANGED: \b osStatus shall be consistent in every CMSIS-RTOS.
147 typedef enum {
148  osOK = 0, ///< function completed; no event occurred.
149  osEventSignal = 0x08, ///< function completed; signal event occurred.
150  osEventMessage = 0x10, ///< function completed; message event occurred.
151  osEventMail = 0x20, ///< function completed; mail event occurred.
152  osEventTimeout = 0x40, ///< function completed; timeout occurred.
153  osErrorParameter = 0x80, ///< parameter error: a mandatory parameter was missing or specified an incorrect object.
154  osErrorResource = 0x81, ///< resource not available: a specified resource was not available.
155  osErrorTimeoutResource = 0xC1, ///< resource not available within given time: a specified resource was not available within the timeout period.
156  osErrorISR = 0x82, ///< not allowed in ISR context: the function cannot be called from interrupt service routines.
157  osErrorISRRecursive = 0x83, ///< function called multiple times from ISR with same object.
158  osErrorPriority = 0x84, ///< system cannot determine priority or thread has illegal priority.
159  osErrorNoMemory = 0x85, ///< system is out of memory: it was impossible to allocate or reserve memory for the operation.
160  osErrorValue = 0x86, ///< value of a parameter is out of range.
161  osErrorOS = 0xFF, ///< unspecified RTOS error: run-time error but no other error message fits.
162  os_status_reserved = 0x7FFFFFFF ///< prevent from enum down-size compiler optimization.
163 } osStatus;
164 
165 
166 /// Timer type value for the timer definition
167 /// \note MUST REMAIN UNCHANGED: \b os_timer_type shall be consistent in every CMSIS-RTOS.
168 typedef enum {
169  osTimerOnce = 0, ///< one-shot timer
170  osTimerPeriodic = 1 ///< repeating timer
171 } os_timer_type;
172 
173 /// Entry point of a thread.
174 /// \note MUST REMAIN UNCHANGED: \b os_pthread shall be consistent in every CMSIS-RTOS.
175 typedef void (*os_pthread) (void const *argument);
176 
177 /// Entry point of a timer call back function.
178 /// \note MUST REMAIN UNCHANGED: \b os_ptimer shall be consistent in every CMSIS-RTOS.
179 typedef void (*os_ptimer) (void const *argument);
180 
181 // >>> the following data type definitions may shall adapted towards a specific RTOS
182 
183 /// Thread ID identifies the thread (pointer to a thread control block).
184 /// \note CAN BE CHANGED: \b os_thread_cb is implementation specific in every CMSIS-RTOS.
185 typedef struct os_thread_cb *osThreadId;
186 
187 /// Timer ID identifies the timer (pointer to a timer control block).
188 /// \note CAN BE CHANGED: \b os_timer_cb is implementation specific in every CMSIS-RTOS.
189 typedef struct os_timer_cb *osTimerId;
190 
191 /// Mutex ID identifies the mutex (pointer to a mutex control block).
192 /// \note CAN BE CHANGED: \b os_mutex_cb is implementation specific in every CMSIS-RTOS.
193 typedef struct os_mutex_cb *osMutexId;
194 
195 /// Semaphore ID identifies the semaphore (pointer to a semaphore control block).
196 /// \note CAN BE CHANGED: \b os_semaphore_cb is implementation specific in every CMSIS-RTOS.
197 typedef struct os_semaphore_cb *osSemaphoreId;
198 
199 /// Pool ID identifies the memory pool (pointer to a memory pool control block).
200 /// \note CAN BE CHANGED: \b os_pool_cb is implementation specific in every CMSIS-RTOS.
201 typedef struct os_pool_cb *osPoolId;
202 
203 /// Message ID identifies the message queue (pointer to a message queue control block).
204 /// \note CAN BE CHANGED: \b os_messageQ_cb is implementation specific in every CMSIS-RTOS.
205 typedef struct os_messageQ_cb *osMessageQId;
206 
207 /// Mail ID identifies the mail queue (pointer to a mail queue control block).
208 /// \note CAN BE CHANGED: \b os_mailQ_cb is implementation specific in every CMSIS-RTOS.
209 typedef struct os_mailQ_cb *osMailQId;
210 
211 
212 /// Thread Definition structure contains startup information of a thread.
213 /// \note CAN BE CHANGED: \b os_thread_def is implementation specific in every CMSIS-RTOS.
214 typedef const struct os_thread_def {
215  os_pthread pthread; ///< start address of thread function
216  osPriority tpriority; ///< initial thread priority
217  uint32_t instances; ///< maximum number of instances of that thread function
218  uint32_t stacksize; ///< stack size requirements in bytes; 0 is default stack size
219 } osThreadDef_t;
220 
221 /// Timer Definition structure contains timer parameters.
222 /// \note CAN BE CHANGED: \b os_timer_def is implementation specific in every CMSIS-RTOS.
223 typedef const struct os_timer_def {
224  os_ptimer ptimer; ///< start address of a timer function
225 } osTimerDef_t;
226 
227 /// Mutex Definition structure contains setup information for a mutex.
228 /// \note CAN BE CHANGED: \b os_mutex_def is implementation specific in every CMSIS-RTOS.
229 typedef const struct os_mutex_def {
230  uint32_t dummy; ///< dummy value.
231 } osMutexDef_t;
232 
233 /// Semaphore Definition structure contains setup information for a semaphore.
234 /// \note CAN BE CHANGED: \b os_semaphore_def is implementation specific in every CMSIS-RTOS.
235 typedef const struct os_semaphore_def {
236  uint32_t dummy; ///< dummy value.
237 } osSemaphoreDef_t;
238 
239 /// Definition structure for memory block allocation
240 /// \note CAN BE CHANGED: \b os_pool_def is implementation specific in every CMSIS-RTOS.
241 typedef const struct os_pool_def {
242  uint32_t pool_sz; ///< number of items (elements) in the pool
243  uint32_t item_sz; ///< size of an item
244  void *pool; ///< pointer to memory for pool
245 } osPoolDef_t;
246 
247 /// Definition structure for message queue
248 /// \note CAN BE CHANGED: \b os_messageQ_def is implementation specific in every CMSIS-RTOS.
249 typedef const struct os_messageQ_def {
250  uint32_t queue_sz; ///< number of elements in the queue
251  uint32_t item_sz; ///< size of an item
252  void *pool; ///< memory array for messages
253 } osMessageQDef_t;
254 
255 /// Definition structure for mail queue
256 /// \note CAN BE CHANGED: \b os_mailQ_def is implementation specific in every CMSIS-RTOS.
257 typedef const struct os_mailQ_def {
258  uint32_t queue_sz; ///< number of elements in the queue
259  uint32_t item_sz; ///< size of an item
260  void *pool; ///< memory array for mail
261 } osMailQDef_t;
262 
263 /// Event structure contains detailed information about an event.
264 /// \note MUST REMAIN UNCHANGED: \b os_event shall be consistent in every CMSIS-RTOS.
265 /// However the struct may be extended at the end.
266 typedef struct {
267  osStatus status; ///< status code: event or error information
268  union {
269  uint32_t v; ///< message as 32-bit value
270  void *p; ///< message or mail as void pointer
271  int32_t signals; ///< signal flags
272  } value; ///< event value
273  union {
274  osMailQId mail_id; ///< mail id obtained by \ref osMailCreate
275  osMessageQId message_id; ///< message id obtained by \ref osMessageCreate
276  } def; ///< event definition
277 } osEvent;
278 
279 
280 // ==== Kernel Control Functions ====
281 
282 /// Start the RTOS Kernel with executing the specified thread.
283 /// \param[in] thread_def thread definition referenced with \ref osThread.
284 /// \param[in] argument pointer that is passed to the thread function as start argument.
285 /// \return status code that indicates the execution status of the function.
286 /// \note MUST REMAIN UNCHANGED: \b osKernelStart shall be consistent in every CMSIS-RTOS.
287 osStatus osKernelStart (osThreadDef_t *thread_def, void *argument);
288 
289 /// Check if the RTOS kernel is already started.
290 /// \note MUST REMAIN UNCHANGED: \b osKernelRunning shall be consistent in every CMSIS-RTOS.
291 /// \return 0 RTOS is not started, 1 RTOS is started.
292 int32_t osKernelRunning(void);
293 
294 
295 // ==== Thread Management ====
296 
297 /// Create a Thread Definition with function, priority, and stack requirements.
298 /// \param name name of the thread function.
299 /// \param priority initial priority of the thread function.
300 /// \param instances number of possible thread instances.
301 /// \param stacksz stack size (in bytes) requirements for the thread function.
302 /// \note CAN BE CHANGED: The parameters to \b osThreadDef shall be consistent but the
303 /// macro body is implementation specific in every CMSIS-RTOS.
304 #if defined (osObjectsExternal) // object is external
305 #define osThreadDef(name, priority, instances, stacksz) \
306 extern osThreadDef_t os_thread_def_##name
307 #else // define the object
308 #define osThreadDef(name, priority, instances, stacksz) \
309 osThreadDef_t os_thread_def_##name = \
310 { (name), (priority), (instances), (stacksz) }
311 #endif
312 
313 /// Access a Thread defintion.
314 /// \param name name of the thread definition object.
315 /// \note CAN BE CHANGED: The parameter to \b osThread shall be consistent but the
316 /// macro body is implementation specific in every CMSIS-RTOS.
317 #define osThread(name) \
318 &os_thread_def_##name
319 
320 
321 /// Create a thread and add it to Active Threads and set it to state READY.
322 /// \param[in] thread_def thread definition referenced with \ref osThread.
323 /// \param[in] argument pointer that is passed to the thread function as start argument.
324 /// \return thread ID for reference by other functions or NULL in case of error.
325 /// \note MUST REMAIN UNCHANGED: \b osThreadCreate shall be consistent in every CMSIS-RTOS.
326 osThreadId osThreadCreate (osThreadDef_t *thread_def, void *argument);
327 
328 /// Return the thread ID of the current running thread.
329 /// \return thread ID for reference by other functions or NULL in case of error.
330 /// \note MUST REMAIN UNCHANGED: \b osThreadGetId shall be consistent in every CMSIS-RTOS.
331 osThreadId osThreadGetId (void);
332 
333 /// Terminate execution of a thread and remove it from Active Threads.
334 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
335 /// \return status code that indicates the execution status of the function.
336 /// \note MUST REMAIN UNCHANGED: \b osThreadTerminate shall be consistent in every CMSIS-RTOS.
337 osStatus osThreadTerminate (osThreadId thread_id);
338 
339 /// Pass control to next thread that is in state \b READY.
340 /// \return status code that indicates the execution status of the function.
341 /// \note MUST REMAIN UNCHANGED: \b osThreadYield shall be consistent in every CMSIS-RTOS.
342 osStatus osThreadYield (void);
343 
344 /// Change priority of an active thread.
345 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
346 /// \param[in] priority new priority value for the thread function.
347 /// \return status code that indicates the execution status of the function.
348 /// \note MUST REMAIN UNCHANGED: \b osThreadSetPriority shall be consistent in every CMSIS-RTOS.
349 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
350 
351 /// Get current priority of an active thread.
352 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
353 /// \return current priority value of the thread function.
354 /// \note MUST REMAIN UNCHANGED: \b osThreadGetPriority shall be consistent in every CMSIS-RTOS.
355 osPriority osThreadGetPriority (osThreadId thread_id);
356 
357 
358 
359 // ==== Generic Wait Functions ====
360 
361 /// Wait for Timeout (Time Delay)
362 /// \param[in] millisec time delay value
363 /// \return status code that indicates the execution status of the function.
364 osStatus osDelay (uint32_t millisec);
365 
366 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available
367 
368 /// Wait for Signal, Message, Mail, or Timeout
369 /// \param[in] millisec timeout value or 0 in case of no time-out
370 /// \return event that contains signal, message, or mail information or error code.
371 /// \note MUST REMAIN UNCHANGED: \b osWait shall be consistent in every CMSIS-RTOS.
372 osEvent osWait (uint32_t millisec);
373 
374 #endif // Generic Wait available
375 
376 
377 // ==== Timer Management Functions ====
378 /// Define a Timer object.
379 /// \param name name of the timer object.
380 /// \param function name of the timer call back function.
381 /// \note CAN BE CHANGED: The parameter to \b osTimerDef shall be consistent but the
382 /// macro body is implementation specific in every CMSIS-RTOS.
383 #if defined (osObjectsExternal) // object is external
384 #define osTimerDef(name, function) \
385 extern osTimerDef_t os_timer_def_##name
386 #else // define the object
387 #define osTimerDef(name, function) \
388 osTimerDef_t os_timer_def_##name = \
389 { (function) }
390 #endif
391 
392 /// Access a Timer definition.
393 /// \param name name of the timer object.
394 /// \note CAN BE CHANGED: The parameter to \b osTimer shall be consistent but the
395 /// macro body is implementation specific in every CMSIS-RTOS.
396 #define osTimer(name) \
397 &os_timer_def_##name
398 
399 /// Create a timer.
400 /// \param[in] timer_def timer object referenced with \ref osTimer.
401 /// \param[in] type osTimerOnce for one-shot or osTimerPeriodic for periodic behavior.
402 /// \param[in] argument argument to the timer call back function.
403 /// \return timer ID for reference by other functions or NULL in case of error.
404 /// \note MUST REMAIN UNCHANGED: \b osTimerCreate shall be consistent in every CMSIS-RTOS.
405 osTimerId osTimerCreate (osTimerDef_t *timer_def, os_timer_type type, void *argument);
406 
407 /// Start or restart a timer.
408 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate.
409 /// \param[in] millisec time delay value of the timer.
410 /// \return status code that indicates the execution status of the function.
411 /// \note MUST REMAIN UNCHANGED: \b osTimerStart shall be consistent in every CMSIS-RTOS.
412 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
413 
414 /// Stop the timer.
415 /// \param[in] timer_id timer ID obtained by \ref osTimerCreate.
416 /// \return status code that indicates the execution status of the function.
417 /// \note MUST REMAIN UNCHANGED: \b osTimerStop shall be consistent in every CMSIS-RTOS.
418 osStatus osTimerStop (osTimerId timer_id);
419 
420 
421 // ==== Signal Management ====
422 
423 /// Set the specified Signal Flags of an active thread.
424 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
425 /// \param[in] signal specifies the signal flags of the thread that should be set.
426 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
427 /// \note MUST REMAIN UNCHANGED: \b osSignalSet shall be consistent in every CMSIS-RTOS.
428 int32_t osSignalSet (osThreadId thread_id, int32_t signal);
429 
430 /// Clear the specified Signal Flags of an active thread.
431 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
432 /// \param[in] signal specifies the signal flags of the thread that shall be cleared.
433 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
434 /// \note MUST REMAIN UNCHANGED: \b osSignalClear shall be consistent in every CMSIS-RTOS.
435 int32_t osSignalClear (osThreadId thread_id, int32_t signal);
436 
437 /// Get Signal Flags status of an active thread.
438 /// \param[in] thread_id thread ID obtained by \ref osThreadCreate or \ref osThreadGetId.
439 /// \return previous signal flags of the specified thread or 0x80000000 in case of incorrect parameters.
440 /// \note MUST REMAIN UNCHANGED: \b osSignalGet shall be consistent in every CMSIS-RTOS.
441 int32_t osSignalGet (osThreadId thread_id);
442 
443 /// Wait for one or more Signal Flags to become signaled for the current \b RUNNING thread.
444 /// \param[in] signals wait until all specified signal flags set or 0 for any single signal flag.
445 /// \param[in] millisec timeout value or 0 in case of no time-out.
446 /// \return event flag information or error code.
447 /// \note MUST REMAIN UNCHANGED: \b osSignalWait shall be consistent in every CMSIS-RTOS.
448 osEvent osSignalWait (int32_t signals, uint32_t millisec);
449 
450 
451 // ==== Mutex Management ====
452 
453 /// Define a Mutex.
454 /// \param name name of the mutex object.
455 /// \note CAN BE CHANGED: The parameter to \b osMutexDef shall be consistent but the
456 /// macro body is implementation specific in every CMSIS-RTOS.
457 #if defined (osObjectsExternal) // object is external
458 #define osMutexDef(name) \
459 extern osMutexDef_t os_mutex_def_##name
460 #else // define the object
461 #define osMutexDef(name) \
462 osMutexDef_t os_mutex_def_##name = { 0 }
463 #endif
464 
465 /// Access a Mutex defintion.
466 /// \param name name of the mutex object.
467 /// \note CAN BE CHANGED: The parameter to \b osMutex shall be consistent but the
468 /// macro body is implementation specific in every CMSIS-RTOS.
469 #define osMutex(name) \
470 &os_mutex_def_##name
471 
472 /// Create and Initialize a Mutex object
473 /// \param[in] mutex_def mutex definition referenced with \ref osMutex.
474 /// \return mutex ID for reference by other functions or NULL in case of error.
475 /// \note MUST REMAIN UNCHANGED: \b osMutexCreate shall be consistent in every CMSIS-RTOS.
476 osMutexId osMutexCreate (osMutexDef_t *mutex_def);
477 
478 /// Wait until a Mutex becomes available
479 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate.
480 /// \param[in] millisec timeout value or 0 in case of no time-out.
481 /// \return status code that indicates the execution status of the function.
482 /// \note MUST REMAIN UNCHANGED: \b osMutexWait shall be consistent in every CMSIS-RTOS.
483 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
484 
485 /// Release a Mutex that was obtained by \ref osMutexWait
486 /// \param[in] mutex_id mutex ID obtained by \ref osMutexCreate.
487 /// \return status code that indicates the execution status of the function.
488 /// \note MUST REMAIN UNCHANGED: \b osMutexRelease shall be consistent in every CMSIS-RTOS.
489 osStatus osMutexRelease (osMutexId mutex_id);
490 
491 
492 // ==== Semaphore Management Functions ====
493 
494 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0)) // Semaphore available
495 
496 /// Define a Semaphore object.
497 /// \param name name of the semaphore object.
498 /// \note CAN BE CHANGED: The parameter to \b osSemaphoreDef shall be consistent but the
499 /// macro body is implementation specific in every CMSIS-RTOS.
500 #if defined (osObjectsExternal) // object is external
501 #define osSemaphoreDef(name) \
502 extern osSemaphoreDef_t os_semaphore_def_##name
503 #else // define the object
504 #define osSemaphoreDef(name) \
505 osSemaphoreDef_t os_semaphore_def_##name = { 0 }
506 #endif
507 
508 /// Access a Semaphore definition.
509 /// \param name name of the semaphore object.
510 /// \note CAN BE CHANGED: The parameter to \b osSemaphore shall be consistent but the
511 /// macro body is implementation specific in every CMSIS-RTOS.
512 #define osSemaphore(name) \
513 &os_semaphore_def_##name
514 
515 /// Create and Initialize a Semaphore object used for managing resources
516 /// \param[in] semaphore_def semaphore definition referenced with \ref osSemaphore.
517 /// \param[in] count number of available resources.
518 /// \return semaphore ID for reference by other functions or NULL in case of error.
519 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreCreate shall be consistent in every CMSIS-RTOS.
520 osSemaphoreId osSemaphoreCreate (osSemaphoreDef_t *semaphore_def, int32_t count);
521 
522 /// Wait until a Semaphore token becomes available
523 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphore.
524 /// \param[in] millisec timeout value or 0 in case of no time-out.
525 /// \return number of available tokens, or -1 in case of incorrect parameters.
526 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreWait shall be consistent in every CMSIS-RTOS.
527 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
528 
529 /// Release a Semaphore token
530 /// \param[in] semaphore_id semaphore object referenced with \ref osSemaphore.
531 /// \return status code that indicates the execution status of the function.
532 /// \note MUST REMAIN UNCHANGED: \b osSemaphoreRelease shall be consistent in every CMSIS-RTOS.
533 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
534 
535 #endif // Semaphore available
536 
537 // ==== Memory Pool Management Functions ====
538 
539 #if (defined (osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool Management available
540 
541 /// \brief Define a Memory Pool.
542 /// \param name name of the memory pool.
543 /// \param no maximum number of objects (elements) in the memory pool.
544 /// \param type data type of a single object (element).
545 /// \note CAN BE CHANGED: The parameter to \b osPoolDef shall be consistent but the
546 /// macro body is implementation specific in every CMSIS-RTOS.
547 #if defined (osObjectsExternal) // object is external
548 #define osPoolDef(name, no, type) \
549 extern osPoolDef_t os_pool_def_##name
550 #else // define the object
551 #define osPoolDef(name, no, type) \
552 osPoolDef_t os_pool_def_##name = \
553 { (no), sizeof(type), NULL }
554 #endif
555 
556 /// \brief Access a Memory Pool definition.
557 /// \param name name of the memory pool
558 /// \note CAN BE CHANGED: The parameter to \b osPool shall be consistent but the
559 /// macro body is implementation specific in every CMSIS-RTOS.
560 #define osPool(name) \
561 &os_pool_def_##name
562 
563 /// Create and Initialize a memory pool
564 /// \param[in] pool_def memory pool definition referenced with \ref osPool.
565 /// \return memory pool ID for reference by other functions or NULL in case of error.
566 /// \note MUST REMAIN UNCHANGED: \b osPoolCreate shall be consistent in every CMSIS-RTOS.
567 osPoolId osPoolCreate (osPoolDef_t *pool_def);
568 
569 /// Allocate a memory block from a memory pool
570 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate.
571 /// \return address of the allocated memory block or NULL in case of no memory available.
572 /// \note MUST REMAIN UNCHANGED: \b osPoolAlloc shall be consistent in every CMSIS-RTOS.
573 void *osPoolAlloc (osPoolId pool_id);
574 
575 /// Allocate a memory block from a memory pool and set memory block to zero
576 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate.
577 /// \return address of the allocated memory block or NULL in case of no memory available.
578 /// \note MUST REMAIN UNCHANGED: \b osPoolCAlloc shall be consistent in every CMSIS-RTOS.
579 void *osPoolCAlloc (osPoolId pool_id);
580 
581 /// Return an allocated memory block back to a specific memory pool
582 /// \param[in] pool_id memory pool ID obtain referenced with \ref osPoolCreate.
583 /// \param[in] block address of the allocated memory block that is returned to the memory pool.
584 /// \return status code that indicates the execution status of the function.
585 /// \note MUST REMAIN UNCHANGED: \b osPoolFree shall be consistent in every CMSIS-RTOS.
586 osStatus osPoolFree (osPoolId pool_id, void *block);
587 
588 #endif // Memory Pool Management available
589 
590 
591 // ==== Message Queue Management Functions ====
592 
593 #if (defined (osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queues available
594 
595 /// \brief Create a Message Queue Definition.
596 /// \param name name of the queue.
597 /// \param queue_sz maximum number of messages in the queue.
598 /// \param type data type of a single message element (for debugger).
599 /// \note CAN BE CHANGED: The parameter to \b osMessageQDef shall be consistent but the
600 /// macro body is implementation specific in every CMSIS-RTOS.
601 #if defined (osObjectsExternal) // object is external
602 #define osMessageQDef(name, queue_sz, type) \
603 extern osMessageQDef_t os_messageQ_def_##name
604 #else // define the object
605 #define osMessageQDef(name, queue_sz, type) \
606 osMessageQDef_t os_messageQ_def_##name = \
607 { (queue_sz), sizeof (type) }
608 #endif
609 
610 /// \brief Access a Message Queue Definition.
611 /// \param name name of the queue
612 /// \note CAN BE CHANGED: The parameter to \b osMessageQ shall be consistent but the
613 /// macro body is implementation specific in every CMSIS-RTOS.
614 #define osMessageQ(name) \
615 &os_messageQ_def_##name
616 
617 /// Create and Initialize a Message Queue.
618 /// \param[in] queue_def queue definition referenced with \ref osMessageQ.
619 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
620 /// \return message queue ID for reference by other functions or NULL in case of error.
621 /// \note MUST REMAIN UNCHANGED: \b osMessageCreate shall be consistent in every CMSIS-RTOS.
622 osMessageQId osMessageCreate (osMessageQDef_t *queue_def, osThreadId thread_id);
623 
624 /// Put a Message to a Queue.
625 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate.
626 /// \param[in] info message information.
627 /// \param[in] millisec timeout value or 0 in case of no time-out.
628 /// \return status code that indicates the execution status of the function.
629 /// \note MUST REMAIN UNCHANGED: \b osMessagePut shall be consistent in every CMSIS-RTOS.
630 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
631 
632 /// Get a Message or Wait for a Message from a Queue.
633 /// \param[in] queue_id message queue ID obtained with \ref osMessageCreate.
634 /// \param[in] millisec timeout value or 0 in case of no time-out.
635 /// \return event information that includes status code.
636 /// \note MUST REMAIN UNCHANGED: \b osMessageGet shall be consistent in every CMSIS-RTOS.
637 osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
638 
639 #endif // Message Queues available
640 
641 
642 // ==== Mail Queue Management Functions ====
643 
644 #if (defined (osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queues available
645 
646 /// \brief Create a Mail Queue Definition
647 /// \param name name of the queue
648 /// \param queue_sz maximum number of messages in queue
649 /// \param type data type of a single message element
650 /// \note CAN BE CHANGED: The parameter to \b osMailQDef shall be consistent but the
651 /// macro body is implementation specific in every CMSIS-RTOS.
652 #if defined (osObjectsExternal) // object is external
653 #define osMailQDef(name, queue_sz, type) \
654 extern osMailQDef_t os_mailQ_def_##name
655 #else // define the object
656 #define osMailQDef(name, queue_sz, type) \
657 osMailQDef_t os_mailQ_def_##name = \
658 { (queue_sz), sizeof (type) }
659 #endif
660 
661 /// \brief Access a Mail Queue Definition
662 /// \param name name of the queue
663 /// \note CAN BE CHANGED: The parameter to \b osMailQ shall be consistent but the
664 /// macro body is implementation specific in every CMSIS-RTOS.
665 #define osMailQ(name) \
666 &os_mailQ_def_##name
667 
668 /// Create and Initialize mail queue
669 /// \param[in] queue_def reference to the mail queue definition obtain with \ref osMailQ
670 /// \param[in] thread_id thread ID (obtained by \ref osThreadCreate or \ref osThreadGetId) or NULL.
671 /// \return mail queue ID for reference by other functions or NULL in case of error.
672 /// \note MUST REMAIN UNCHANGED: \b osMailCreate shall be consistent in every CMSIS-RTOS.
673 osMailQId osMailCreate (osMailQDef_t *queue_def, osThreadId thread_id);
674 
675 /// Allocate a memory block from a mail
676 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
677 /// \param[in] millisec timeout value or 0 in case of no time-out
678 /// \return pointer to memory block that can be filled with mail or NULL in case error.
679 /// \note MUST REMAIN UNCHANGED: \b osMailAlloc shall be consistent in every CMSIS-RTOS.
680 void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
681 
682 /// Allocate a memory block from a mail and set memory block to zero
683 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
684 /// \param[in] millisec timeout value or 0 in case of no time-out
685 /// \return pointer to memory block that can shall filled with mail or NULL in case error.
686 /// \note MUST REMAIN UNCHANGED: \b osMailCAlloc shall be consistent in every CMSIS-RTOS.
687 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
688 
689 /// Put a mail to a queue
690 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
691 /// \param[in] mail memory block previously allocated with \ref osMailAlloc or \ref osMailCAlloc.
692 /// \return status code that indicates the execution status of the function.
693 /// \note MUST REMAIN UNCHANGED: \b osMailPut shall be consistent in every CMSIS-RTOS.
694 osStatus osMailPut (osMailQId queue_id, void *mail);
695 
696 /// Get a mail from a queue
697 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
698 /// \param[in] millisec timeout value or 0 in case of no time-out
699 /// \return event that contains mail information or error code.
700 /// \note MUST REMAIN UNCHANGED: \b osMailGet shall be consistent in every CMSIS-RTOS.
701 osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
702 
703 /// Free a memory block from a mail
704 /// \param[in] queue_id mail queue ID obtained with \ref osMailCreate.
705 /// \param[in] mail pointer to the memory block that was obtained with \ref osMailGet.
706 /// \return status code that indicates the execution status of the function.
707 /// \note MUST REMAIN UNCHANGED: \b osMailFree shall be consistent in every CMSIS-RTOS.
708 osStatus osMailFree (osMailQId queue_id, void *mail);
709 
710 #endif // Mail Queues available
711 
712 
713 #ifdef __cplusplus
714 }
715 #endif
716 
717 #endif // _CMSIS_OS_H