source: trunk/fw_g473rct/Drivers/CMSIS/RTOS2/Template/cmsis_os.h

Last change on this file was 20, checked in by f.jahn, 5 days ago

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