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