begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_Event.txt

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