source: S-port/trunk/Drivers/CMSIS/RTOS/Template/cmsis_os.h

Last change on this file was 1, checked in by AlexLir, 3 years ago
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.