1
2
3/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
4//  ==== Event Flag Management ====
5/**
6\addtogroup CMSIS_RTOS_EventFlags Event Flags
7\ingroup CMSIS_RTOS
8\brief Synchronize threads using event flags.
9\details
10The event flags management functions in CMSIS-RTOS allow you to control or wait for event flags. Each signal has up to 31
11event flags.
12
13A thread
14- can wait for event flags to be set (using \ref osEventFlagsWait). Using this function, it enters the
15  \ref ThreadStates "BLOCKED" state.
16- may set one or more flags in any other given thread (using \ref osEventFlagsSet).
17- may clear its own signals or the signals of other threads (using \ref osEventFlagsClear).
18
19When a thread wakes up and resumes execution, its signal flags are automatically cleared (unless event flags option
20\ref osFlagsNoClear is specified).
21
22\note The functions \ref osEventFlagsSet, \ref osEventFlagsClear, \ref osEventFlagsGet, and \ref osEventFlagsWait can be
23called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
24
25Working with Events
26--------------------
27Here is a simple example that shows how two thread can communicate with each others using event flags:
28
29\image html simple_signal.png "Simple event communication"
30
31The following steps are required to use event flags:
32-# In the thread that is supposed to send an event with id sig1_id, call the set function:
33\code
34osDelay(1000U);                                           // wait for 1 second
35osEventFlagsSet(sig1_id, 0x0001U);                        // set the flag 0x0001U for event sig1_id
36\endcode
37-# In another thread (or threads) that are supposed to wait for the event, call the wait function:
38\code
39osEventFlagsWait(sig1_id, 0x0001U, NULL, osWaitForever);  // wait forever for any flag
40\endcode
41
42<b>Code Example</b>
43\code
44#include "cmsis_os2.h"                          // CMSIS RTOS header file
45
46/*----------------------------------------------------------------------------
47 *  Event Flags creation & usage
48 *---------------------------------------------------------------------------*/
49
50#define FLAGS_MSK1 0x00000001U
51
52osEventFlagsId_t evt_id;                        // event flags id
53
54osThreadId_t tid_Thread_EventSender;            // thread id 1
55osThreadId_t tid_Thread_EventReceiver;          // thread id 2
56
57void Thread_EventSender   (void *argument);     // thread function 1
58void Thread_EventReceiver (void *argument);     // thread function 2
59
60int Init_Events (void) {
61
62  evt_id = osEventFlagsNew(NULL);
63  if (evt_id == NULL) {
64    ; // Event Flags object not created, handle failure
65  }
66
67  tid_Thread_EventSender = osThreadNew(Thread_EventSender, NULL, NULL);
68  if (tid_Thread_EventSender == NULL) {
69    return(-1);
70  }
71  tid_Thread_EventReceiver = osThreadNew(Thread_EventReceiver, NULL, NULL);
72  if (tid_Thread_EventReceiver == NULL) {
73    return(-1);
74  }
75
76  return(0);
77}
78
79void Thread_EventSender (void *argument) {
80
81  while (1) {
82    osEventFlagsSet(evt_id, FLAGS_MSK1);
83    osThreadYield();                            // suspend thread
84  }
85}
86
87void Thread_EventReceiver (void *argument) {
88  uint32_t flags;
89
90  while (1) {
91    flags = osEventFlagsWait(evt_id, FLAGS_MSK1, osFlagsWaitAny, osWaitForever);
92    //handle event
93  }
94}
95\endcode
96
97
98@{
99*/
100/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
101/**
102\typedef osEventFlagsId_t
103\details
104Returned by:
105- \ref osEventFlagsNew
106*/
107
108/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
109/**
110\struct osEventFlagsAttr_t
111\details
112Attributes to configure an event flag set.
113
114Refer to \ref CMSIS_RTOS_MemoryMgmt for details about usage of
115 - osEventFlagsAttr_t::cb_mem
116 - osEventFlagsAttr_t::cb_size
117*/
118
119/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
120/**
121\fn osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr)
122\details
123The function \b osEventFlagsNew creates a new event flags object that is used to send events across threads and returns the
124pointer to the event flags object identifier or \token{NULL} in case of an error. It can be safely called before the RTOS is
125started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
126
127The parameter \a attr sets the event flags attributes (refer to \ref osEventFlagsAttr_t).  Default attributes will be used if
128set to \token{NULL}, i.e. kernel memory allocation is used for the event control block.
129
130\note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
131
132<b>Code Example</b>
133\code
134#include "cmsis_os2.h"                          // CMSIS RTOS header file
135
136osEventFlagsId_t evt_id;                        // event flags id
137
138int Init_Events (void) {
139
140  evt_id = osEventFlagsNew(NULL);
141  if (evt_id == NULL) {
142    ; // Event Flags object not created, handle failure
143    return(-1);
144  }
145
146  return(0);
147}
148\endcode
149*/
150
151/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
152/**
153\fn uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags)
154\details
155The function \b osEventFlagsSet sets the event flags specified by the parameter \a flags in an event flags object specified
156by parameter \a ef_id.
157
158The threads with highest priority waiting for the flag(s) set will be notified to resume from \ref ThreadStates "BLOCKED" state.
159The function returns the event flags stored in the event control block or an error code (highest bit is set, refer to
160\ref flags_error_codes). Further threads may be wakened in priority order when the option \b osFlagsNoClear is given to the
161\ref osEventFlagsWait call.
162
163Possible \ref flags_error_codes return values:
164    - \em osFlagsErrorUnknown: unspecified error.
165    - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
166    - \em osFlagsErrorResource: the event flags object is in an invalid state.
167    - \em osFlagsErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified event flags object.
168
169\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
170
171<b>Code Example</b>
172\code
173#include "cmsis_os2.h"                          // CMSIS RTOS header file
174
175osEventFlagsId_t evt_id;                        // event flags id
176
177void Thread_EventSender (void *argument) {
178
179  while (1) {
180    osEventFlagsSet(evt_id, 0x00000001U);
181    osThreadYield();                            // suspend thread
182  }
183}
184\endcode
185*/
186
187/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
188/**
189\fn uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags)
190\details
191The function \b osEventFlagsClear clears the event flags specified by the parameter \a flags in an event flags object
192specified by parameter \a ef_id. The function returns the event flags before clearing or an error code (highest bit is set,
193refer to \ref flags_error_codes).
194
195Possible \ref flags_error_codes return values:
196    - \em osFlagsErrorUnknown: unspecified error.
197    - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
198    - \em osFlagsErrorResource: the event flags object is in an invalid state.
199    - \em osFlagsErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified event flags object.
200
201\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
202*/
203
204/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
205/**
206\fn uint32_t osEventFlagsGet (osEventFlagsId_t ef_id)
207\details
208The function \b osEventFlagsGet returns the event flags currently set in an event flags object specified by parameter
209\a ef_id or \token{0} in case of an error.
210
211\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
212*/
213
214/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
215/**
216\fn uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout)
217\details
218The function \b osEventFlagsWait suspends the execution of the currently \ref ThreadStates "RUNNING" thread until any or all event flags
219specified by the parameter \a flags in the event object specified by parameter \a ef_id are set. When these event flags are
220already set, the function returns instantly. Otherwise, the thread is put into the state \ref ThreadStates "BLOCKED".
221
222The \em options parameter specifies the wait condition:
223|Option              |                                                       |
224|--------------------|-------------------------------------------------------|
225|\b osFlagsWaitAny   |   Wait for any flag (default).                        |
226|\b osFlagsWaitAll   |   Wait for all flags.                                 |
227|\b osFlagsNoClear   |   Do not clear flags which have been specified to wait for.  |
228
229If \c osFlagsNoClear is set in the options \ref osEventFlagsClear can be used to clear flags manually.
230
231The parameter \a timeout specifies how long the system waits for event flags. While the system waits, the thread
232that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue
233"timeout" can have the following values:
234 - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
235 - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the event flags become
236   available (i.e. wait semantics).
237 - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
238
239The function returns the event flags before clearing or an error code (highest bit is set, refer to \ref flags_error_codes).
240
241Possible \ref flags_error_codes return values:
242    - \em osFlagsErrorUnknown: unspecified error.
243    - \em osFlagsErrorTimeout: awaited flags have not been set in the given time.
244    - \em osFlagsErrorResource: awaited flags have not been set when no \a timeout was specified.
245    - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
246    - \em osFlagsErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified event flags object.
247
248\note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
249\token{0}.
250
251\b Code \b Example
252\code
253#include "cmsis_os2.h"                          // CMSIS RTOS header file
254
255osEventFlagsId_t evt_id;                        // event flags id
256
257void Thread_EventReceiver (void *argument) {
258  uint32_t flags;
259
260  while (1) {
261    flags = osEventFlagsWait(evt_id, 0x00000001U, osFlagsWaitAny, osWaitForever);
262    //handle event
263  }
264}
265\endcode
266*/
267
268/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
269/**
270\fn osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
271\details
272The function \b osEventFlagsDelete deletes the event flags object specified by parameter \a ef_id and releases the internal
273memory obtained for the event flags handling. After this call, the \em ef_id is no longer valid and cannot be used. This can
274cause starvation of threads that are waiting for flags of this event object. The \em ef_id may be created again using the
275function \ref osEventFlagsNew.
276
277Possible \ref osStatus_t return values:
278 - \em osOK: the specified event flags object has been deleted.
279 - \em osErrorISR: \b osEventFlagsDelete cannot be called from interrupt service routines.
280 - \em osErrorParameter: parameter \a ef_id is \token{NULL} or invalid.
281 - \em osErrorResource: the event flags object is in an invalid state.
282 - \em osFlagsErrorSafetyClass: the calling thread safety class is lower than the safety class of the specified event flags object.
283
284\note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
285*/
286
287/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
288/**
289\fn const char *osEventFlagsGetName (osEventFlagsId_t ef_id)
290\details
291The function \b osEventFlagsGetName returns the pointer to the name string of the event flags object identified by parameter
292\a ef_id or \token{NULL} in case of an error.
293
294\note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
295
296<b>Code Example</b>
297\code
298#include "cmsis_os2.h"                          // CMSIS RTOS header file
299
300osEventFlagsId_t evt_id;                        // event flags id
301
302void EvtFlagsGetName_example (void)  {
303  char *name;
304
305  name = osEventFlagsGetName(evt_id);
306  if (name == NULL) {
307    // Failed to get the event flags object name
308  }
309}
310\endcode
311*/
312
313/// @}
314
315// these struct members must stay outside the group to avoid double entries in documentation
316/**
317\var osEventFlagsAttr_t::attr_bits
318\details
319Reserved for future use (must be set to '0' for future compatibility).
320
321\var osEventFlagsAttr_t::cb_mem
322\details
323Pointer to a memory for the event flag control block object. Refer to \ref CMSIS_RTOS_MemoryMgmt_Manual for more information.
324
325Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the event flag control block.
326
327\var osEventFlagsAttr_t::cb_size
328\details
329The size (in bytes) of memory block passed with \ref cb_mem. Required value depends on the underlying kernel implementation.
330
331Default: \token{0} as the default is no memory provided with \ref cb_mem.
332
333\var osEventFlagsAttr_t::name
334\details
335Pointer to a constant string with a human readable name (displayed during debugging) of the event flag object.
336
337Default: \token{NULL} no name specified.
338*/
339