EU1KY AA FW
cmsis_os.h
Go to the documentation of this file.
1 /* ----------------------------------------------------------------------
2  * $Date: 5. February 2013
3  * $Revision: V1.02
4  *
5  * Project: CMSIS-RTOS API
6  * Title: cmsis_os.h template header file
7  *
8  * Version 0.02
9  * Initial Proposal Phase
10  * Version 0.03
11  * osKernelStart added, optional feature: main started as thread
12  * osSemaphores have standard behavior
13  * osTimerCreate does not start the timer, added osTimerStart
14  * osThreadPass is renamed to osThreadYield
15  * Version 1.01
16  * Support for C++ interface
17  * - const attribute removed from the osXxxxDef_t typedef's
18  * - const attribute added to the osXxxxDef macros
19  * Added: osTimerDelete, osMutexDelete, osSemaphoreDelete
20  * Added: osKernelInitialize
21  * Version 1.02
22  * Control functions for short timeouts in microsecond resolution:
23  * Added: osKernelSysTick, osKernelSysTickFrequency, osKernelSysTickMicroSec
24  * Removed: osSignalGet
25  *----------------------------------------------------------------------------
26  *
27  * Copyright (c) 2013 ARM LIMITED
28  * All rights reserved.
29  * Redistribution and use in source and binary forms, with or without
30  * modification, are permitted provided that the following conditions are met:
31  * - Redistributions of source code must retain the above copyright
32  * notice, this list of conditions and the following disclaimer.
33  * - Redistributions in binary form must reproduce the above copyright
34  * notice, this list of conditions and the following disclaimer in the
35  * documentation and/or other materials provided with the distribution.
36  * - Neither the name of ARM nor the names of its contributors may be used
37  * to endorse or promote products derived from this software without
38  * specific prior written permission.
39  *
40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
41  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
43  * ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
44  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
45  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
46  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
47  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
48  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
50  * POSSIBILITY OF SUCH DAMAGE.
51  *---------------------------------------------------------------------------*/
52 
53 
54 #ifndef _CMSIS_OS_H
55 #define _CMSIS_OS_H
56 
58 #define osCMSIS 0x10002
59 
60 #define osCMSIS_KERNEL 0x10000
62 
63 #define osKernelSystemId "KERNEL V1.00"
65 
66 #define osFeature_MainThread 1
68 #define osFeature_Pool 1
69 #define osFeature_MailQ 1
70 #define osFeature_MessageQ 1
71 #define osFeature_Signals 8
72 #define osFeature_Semaphore 30
73 #define osFeature_Wait 1
74 #define osFeature_SysTick 1
75 
76 #include <stdint.h>
77 #include <stddef.h>
78 
79 #ifdef __cplusplus
80 extern "C"
81 {
82 #endif
83 
84 
85 // ==== Enumeration, structures, defines ====
86 
89 typedef enum {
98 } osPriority;
99 
102 #define osWaitForever 0xFFFFFFFF
103 
104 typedef enum {
107  osOK = 0,
108  osEventSignal = 0x08,
109  osEventMessage = 0x10,
110  osEventMail = 0x20,
111  osEventTimeout = 0x40,
115  osErrorISR = 0x82,
119  osErrorValue = 0x86,
120  osErrorOS = 0xFF,
121  os_status_reserved = 0x7FFFFFFF
122 } osStatus;
123 
124 
127 typedef enum {
130 } os_timer_type;
131 
134 typedef void (*os_pthread) (void const *argument);
135 
138 typedef void (*os_ptimer) (void const *argument);
139 
140 // >>> the following data type definitions may shall adapted towards a specific RTOS
141 
144 typedef struct os_thread_cb *osThreadId;
145 
148 typedef struct os_timer_cb *osTimerId;
149 
152 typedef struct os_mutex_cb *osMutexId;
153 
156 typedef struct os_semaphore_cb *osSemaphoreId;
157 
160 typedef struct os_pool_cb *osPoolId;
161 
164 typedef struct os_messageQ_cb *osMessageQId;
165 
168 typedef struct os_mailQ_cb *osMailQId;
169 
170 
173 typedef struct os_thread_def {
176  uint32_t instances;
177  uint32_t stacksize;
178 } osThreadDef_t;
179 
182 typedef struct os_timer_def {
184 } osTimerDef_t;
185 
188 typedef struct os_mutex_def {
189  uint32_t dummy;
190 } osMutexDef_t;
191 
194 typedef struct os_semaphore_def {
195  uint32_t dummy;
197 
200 typedef struct os_pool_def {
201  uint32_t pool_sz;
202  uint32_t item_sz;
203  void *pool;
204 } osPoolDef_t;
205 
208 typedef struct os_messageQ_def {
209  uint32_t queue_sz;
210  uint32_t item_sz;
211  void *pool;
213 
216 typedef struct os_mailQ_def {
217  uint32_t queue_sz;
218  uint32_t item_sz;
219  void *pool;
220 } osMailQDef_t;
221 
225 typedef struct {
227  union {
228  uint32_t v;
229  void *p;
230  int32_t signals;
231  } value;
232  union {
233  osMailQId mail_id;
234  osMessageQId message_id;
235  } def;
236 } osEvent;
237 
238 
239 // ==== Kernel Control Functions ====
240 
245 
249 osStatus osKernelStart (void);
250 
254 int32_t osKernelRunning(void);
255 
256 #if (defined (osFeature_SysTick) && (osFeature_SysTick != 0)) // System Timer available
257 
261 uint32_t osKernelSysTick (void);
262 
265 #define osKernelSysTickFrequency 100000000
266 
270 #define osKernelSysTickMicroSec(microsec) (((uint64_t)microsec * (osKernelSysTickFrequency)) / 1000000)
271 
272 #endif // System Timer available
273 
274 // ==== Thread Management ====
275 
283 #if defined (osObjectsExternal) // object is external
284 #define osThreadDef(name, priority, instances, stacksz) \
285 extern const osThreadDef_t os_thread_def_##name
286 #else // define the object
287 #define osThreadDef(name, priority, instances, stacksz) \
288 const osThreadDef_t os_thread_def_##name = \
289 { (name), (priority), (instances), (stacksz) }
290 #endif
291 
296 #define osThread(name) \
297 &os_thread_def_##name
298 
304 osThreadId osThreadCreate (const osThreadDef_t *thread_def, void *argument);
305 
309 osThreadId osThreadGetId (void);
310 
315 osStatus osThreadTerminate (osThreadId thread_id);
316 
320 osStatus osThreadYield (void);
321 
327 osStatus osThreadSetPriority (osThreadId thread_id, osPriority priority);
328 
333 osPriority osThreadGetPriority (osThreadId thread_id);
334 
335 
336 // ==== Generic Wait Functions ====
337 
341 osStatus osDelay (uint32_t millisec);
342 
343 #if (defined (osFeature_Wait) && (osFeature_Wait != 0)) // Generic Wait available
344 
349 osEvent osWait (uint32_t millisec);
350 
351 #endif // Generic Wait available
352 
353 
354 // ==== Timer Management Functions ====
360 #if defined (osObjectsExternal) // object is external
361 #define osTimerDef(name, function) \
362 extern const osTimerDef_t os_timer_def_##name
363 #else // define the object
364 #define osTimerDef(name, function) \
365 const osTimerDef_t os_timer_def_##name = \
366 { (function) }
367 #endif
368 
373 #define osTimer(name) \
374 &os_timer_def_##name
375 
382 osTimerId osTimerCreate (const osTimerDef_t *timer_def, os_timer_type type, void *argument);
383 
389 osStatus osTimerStart (osTimerId timer_id, uint32_t millisec);
390 
395 osStatus osTimerStop (osTimerId timer_id);
396 
401 osStatus osTimerDelete (osTimerId timer_id);
402 
403 
404 // ==== Signal Management ====
405 
411 int32_t osSignalSet (osThreadId thread_id, int32_t signals);
412 
418 int32_t osSignalClear (osThreadId thread_id, int32_t signals);
419 
425 osEvent osSignalWait (int32_t signals, uint32_t millisec);
426 
427 
428 // ==== Mutex Management ====
429 
434 #if defined (osObjectsExternal) // object is external
435 #define osMutexDef(name) \
436 extern const osMutexDef_t os_mutex_def_##name
437 #else // define the object
438 #define osMutexDef(name) \
439 const osMutexDef_t os_mutex_def_##name = { 0 }
440 #endif
441 
446 #define osMutex(name) \
447 &os_mutex_def_##name
448 
453 osMutexId osMutexCreate (const osMutexDef_t *mutex_def);
454 
460 osStatus osMutexWait (osMutexId mutex_id, uint32_t millisec);
461 
466 osStatus osMutexRelease (osMutexId mutex_id);
467 
472 osStatus osMutexDelete (osMutexId mutex_id);
473 
474 
475 // ==== Semaphore Management Functions ====
476 
477 #if (defined (osFeature_Semaphore) && (osFeature_Semaphore != 0)) // Semaphore available
478 
483 #if defined (osObjectsExternal) // object is external
484 #define osSemaphoreDef(name) \
485 extern const osSemaphoreDef_t os_semaphore_def_##name
486 #else // define the object
487 #define osSemaphoreDef(name) \
488 const osSemaphoreDef_t os_semaphore_def_##name = { 0 }
489 #endif
490 
495 #define osSemaphore(name) \
496 &os_semaphore_def_##name
497 
503 osSemaphoreId osSemaphoreCreate (const osSemaphoreDef_t *semaphore_def, int32_t count);
504 
510 int32_t osSemaphoreWait (osSemaphoreId semaphore_id, uint32_t millisec);
511 
516 osStatus osSemaphoreRelease (osSemaphoreId semaphore_id);
517 
522 osStatus osSemaphoreDelete (osSemaphoreId semaphore_id);
523 
524 #endif // Semaphore available
525 
526 
527 // ==== Memory Pool Management Functions ====
528 
529 #if (defined (osFeature_Pool) && (osFeature_Pool != 0)) // Memory Pool Management available
530 
537 #if defined (osObjectsExternal) // object is external
538 #define osPoolDef(name, no, type) \
539 extern const osPoolDef_t os_pool_def_##name
540 #else // define the object
541 #define osPoolDef(name, no, type) \
542 const osPoolDef_t os_pool_def_##name = \
543 { (no), sizeof(type), NULL }
544 #endif
545 
550 #define osPool(name) \
551 &os_pool_def_##name
552 
557 osPoolId osPoolCreate (const osPoolDef_t *pool_def);
558 
563 void *osPoolAlloc (osPoolId pool_id);
564 
569 void *osPoolCAlloc (osPoolId pool_id);
570 
576 osStatus osPoolFree (osPoolId pool_id, void *block);
577 
578 #endif // Memory Pool Management available
579 
580 
581 // ==== Message Queue Management Functions ====
582 
583 #if (defined (osFeature_MessageQ) && (osFeature_MessageQ != 0)) // Message Queues available
584 
591 #if defined (osObjectsExternal) // object is external
592 #define osMessageQDef(name, queue_sz, type) \
593 extern const osMessageQDef_t os_messageQ_def_##name
594 #else // define the object
595 #define osMessageQDef(name, queue_sz, type) \
596 const osMessageQDef_t os_messageQ_def_##name = \
597 { (queue_sz), sizeof (type) }
598 #endif
599 
604 #define osMessageQ(name) \
605 &os_messageQ_def_##name
606 
612 osMessageQId osMessageCreate (const osMessageQDef_t *queue_def, osThreadId thread_id);
613 
620 osStatus osMessagePut (osMessageQId queue_id, uint32_t info, uint32_t millisec);
621 
627 osEvent osMessageGet (osMessageQId queue_id, uint32_t millisec);
628 
629 #endif // Message Queues available
630 
631 
632 // ==== Mail Queue Management Functions ====
633 
634 #if (defined (osFeature_MailQ) && (osFeature_MailQ != 0)) // Mail Queues available
635 
642 #if defined (osObjectsExternal) // object is external
643 #define osMailQDef(name, queue_sz, type) \
644 extern const osMailQDef_t os_mailQ_def_##name
645 #else // define the object
646 #define osMailQDef(name, queue_sz, type) \
647 const osMailQDef_t os_mailQ_def_##name = \
648 { (queue_sz), sizeof (type) }
649 #endif
650 
655 #define osMailQ(name) \
656 &os_mailQ_def_##name
657 
663 osMailQId osMailCreate (const osMailQDef_t *queue_def, osThreadId thread_id);
664 
670 void *osMailAlloc (osMailQId queue_id, uint32_t millisec);
671 
677 void *osMailCAlloc (osMailQId queue_id, uint32_t millisec);
678 
684 osStatus osMailPut (osMailQId queue_id, void *mail);
685 
691 osEvent osMailGet (osMailQId queue_id, uint32_t millisec);
692 
698 osStatus osMailFree (osMailQId queue_id, void *mail);
699 
700 #endif // Mail Queues available
701 
702 
703 #ifdef __cplusplus
704 }
705 #endif
706 
707 #endif // _CMSIS_OS_H
uint32_t queue_sz
number of elements in the queue
Definition: cmsis_os.h:217
osStatus osThreadSetPriority(osThreadId thread_id, osPriority priority)
osMailQId mail_id
mail id obtained by osMailCreate
Definition: cmsis_os.h:233
Definition: cmsis_os.h:182
resource not available: a specified resource was not available.
Definition: cmsis_os.h:113
Definition: cmsis_os.h:173
struct os_mailQ_cb * osMailQId
Definition: cmsis_os.h:168
function completed; signal event occurred.
Definition: cmsis_os.h:108
static uint32_t value
Definition: num_keypad.c:27
osStatus osSemaphoreDelete(osSemaphoreId semaphore_id)
struct os_thread_def osThreadDef_t
Definition: cmsis_os.h:188
priority: below normal
Definition: cmsis_os.h:92
system cannot determine priority or thread has illegal priority.
Definition: cmsis_os.h:117
Definition: cmsis_os.h:225
value of a parameter is out of range.
Definition: cmsis_os.h:119
system is out of memory: it was impossible to allocate or reserve memory for the operation.
Definition: cmsis_os.h:118
void(* os_pthread)(void const *argument)
Definition: cmsis_os.h:134
function completed; no error or event occurred.
Definition: cmsis_os.h:107
priority: low
Definition: cmsis_os.h:91
priority: realtime (highest)
Definition: cmsis_os.h:96
uint32_t item_sz
size of an item
Definition: cmsis_os.h:202
function completed; message event occurred.
Definition: cmsis_os.h:109
osStatus osThreadTerminate(osThreadId thread_id)
uint32_t instances
maximum number of instances of that thread function
Definition: cmsis_os.h:176
uint32_t v
message as 32-bit value
Definition: cmsis_os.h:228
struct os_semaphore_cb * osSemaphoreId
Definition: cmsis_os.h:156
struct os_mailQ_def osMailQDef_t
osStatus osMailPut(osMailQId queue_id, void *mail)
one-shot timer
Definition: cmsis_os.h:128
osStatus osKernelInitialize(void)
uint32_t stacksize
stack size requirements in bytes; 0 is default stack size
Definition: cmsis_os.h:177
unspecified RTOS error: run-time error but no other error message fits.
Definition: cmsis_os.h:120
parameter error: a mandatory parameter was missing or specified an incorrect object.
Definition: cmsis_os.h:112
osMessageQId message_id
message id obtained by osMessageCreate
Definition: cmsis_os.h:234
osMessageQId osMessageCreate(const osMessageQDef_t *queue_def, osThreadId thread_id)
void * osPoolCAlloc(osPoolId pool_id)
struct os_mutex_def osMutexDef_t
priority: high
Definition: cmsis_os.h:95
void * osMailAlloc(osMailQId queue_id, uint32_t millisec)
struct os_messageQ_def osMessageQDef_t
int32_t signals
signal flags
Definition: cmsis_os.h:230
uint32_t queue_sz
number of elements in the queue
Definition: cmsis_os.h:209
osStatus osMutexRelease(osMutexId mutex_id)
uint32_t osKernelSysTick(void)
struct os_thread_cb * osThreadId
Definition: cmsis_os.h:144
int32_t osKernelRunning(void)
int32_t osSignalClear(osThreadId thread_id, int32_t signals)
struct os_timer_cb * osTimerId
Definition: cmsis_os.h:148
osStatus osDelay(uint32_t millisec)
priority: normal (default)
Definition: cmsis_os.h:93
void * pool
memory array for mail
Definition: cmsis_os.h:219
osStatus osMutexWait(osMutexId mutex_id, uint32_t millisec)
struct os_mutex_cb * osMutexId
Definition: cmsis_os.h:152
osMailQId osMailCreate(const osMailQDef_t *queue_def, osThreadId thread_id)
repeating timer
Definition: cmsis_os.h:129
void * osPoolAlloc(osPoolId pool_id)
osStatus osMailFree(osMailQId queue_id, void *mail)
uint32_t dummy
dummy value.
Definition: cmsis_os.h:195
os_pthread pthread
start address of thread function
Definition: cmsis_os.h:174
uint32_t dummy
dummy value.
Definition: cmsis_os.h:189
struct os_timer_def osTimerDef_t
osStatus status
status code: event or error information
Definition: cmsis_os.h:226
osStatus osMessagePut(osMessageQId queue_id, uint32_t info, uint32_t millisec)
function completed; timeout occurred.
Definition: cmsis_os.h:111
struct os_pool_cb * osPoolId
Definition: cmsis_os.h:160
void * pool
memory array for messages
Definition: cmsis_os.h:211
not allowed in ISR context: the function cannot be called from interrupt service routines.
Definition: cmsis_os.h:115
priority: idle (lowest)
Definition: cmsis_os.h:90
osPriority osThreadGetPriority(osThreadId thread_id)
resource not available within given time: a specified resource was not available within the timeout p...
Definition: cmsis_os.h:114
osStatus osTimerStart(osTimerId timer_id, uint32_t millisec)
int32_t osSignalSet(osThreadId thread_id, int32_t signals)
priority: above normal
Definition: cmsis_os.h:94
osThreadId osThreadCreate(const osThreadDef_t *thread_def, void *argument)
osSemaphoreId osSemaphoreCreate(const osSemaphoreDef_t *semaphore_def, int32_t count)
Definition: cmsis_os.h:194
osEvent osMessageGet(osMessageQId queue_id, uint32_t millisec)
osEvent osSignalWait(int32_t signals, uint32_t millisec)
void * p
message or mail as void pointer
Definition: cmsis_os.h:229
osStatus osTimerDelete(osTimerId timer_id)
Definition: cmsis_os.h:200
osMutexId osMutexCreate(const osMutexDef_t *mutex_def)
osStatus osMutexDelete(osMutexId mutex_id)
uint32_t item_sz
size of an item
Definition: cmsis_os.h:210
int32_t osSemaphoreWait(osSemaphoreId semaphore_id, uint32_t millisec)
void * osMailCAlloc(osMailQId queue_id, uint32_t millisec)
struct os_messageQ_cb * osMessageQId
Definition: cmsis_os.h:164
uint32_t pool_sz
number of items (elements) in the pool
Definition: cmsis_os.h:201
prevent from enum down-size compiler optimization.
Definition: cmsis_os.h:121
osTimerId osTimerCreate(const osTimerDef_t *timer_def, os_timer_type type, void *argument)
struct os_pool_def osPoolDef_t
osEvent osMailGet(osMailQId queue_id, uint32_t millisec)
void * pool
pointer to memory for pool
Definition: cmsis_os.h:203
void(* os_ptimer)(void const *argument)
Definition: cmsis_os.h:138
osPriority tpriority
initial thread priority
Definition: cmsis_os.h:175
osStatus osTimerStop(osTimerId timer_id)
osEvent osWait(uint32_t millisec)
osThreadId osThreadGetId(void)
struct os_semaphore_def osSemaphoreDef_t
os_ptimer ptimer
start address of a timer function
Definition: cmsis_os.h:183
osStatus osSemaphoreRelease(osSemaphoreId semaphore_id)
osStatus
Definition: cmsis_os.h:106
osStatus osThreadYield(void)
uint32_t item_sz
size of an item
Definition: cmsis_os.h:218
function called multiple times from ISR with same object.
Definition: cmsis_os.h:116
void(Delete(void))
Definition: mainwnd.c:359
osStatus osKernelStart(void)
function completed; mail event occurred.
Definition: cmsis_os.h:110
osPoolId osPoolCreate(const osPoolDef_t *pool_def)
Definition: cmsis_os.h:208
Definition: cmsis_os.h:216
osPriority
Definition: cmsis_os.h:89
os_timer_type
Definition: cmsis_os.h:127
osStatus osPoolFree(osPoolId pool_id, void *block)
system cannot determine priority or thread has illegal priority
Definition: cmsis_os.h:97