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 */
 105
 106 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 107 /**
 108 \fn osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr)
 109 \details
 110 The function \b osEventFlagsNew creates a new event flags object that is used to send events across threads and returns the
 111 pointer to the event flags object identifier or \token{NULL} in case of an error. It can be safely called before the RTOS is
 112 started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
 113
 114 The parameter \a attr sets the event flags attributes (refer to \ref osEventFlagsAttr_t).  Default attributes will be used if
 115 set to \token{NULL}, i.e. kernel memory allocation is used for the event control block.
 116
 117 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 118
 119 <b>Code Example</b>
 120 \code
 121 #include "cmsis_os2.h"                                        // CMSIS RTOS header file
 122
 123 osEventFlagsId_t evt_id;                                      // message queue id
 124
 125 void Thread_EventSender (void *argument)
 126 {
 127   evt_id = osEventFlagsNew(NULL);
 128   while (1) {
 129     osEventFlagsSet(evt_id, FLAGS_MSK1);
 130     osThreadYield ();                                         // suspend thread
 131   }
 132 }
 133
 134 void Thread_EventReceiver (void *argument)
 135 {
 136   uint32_t  flags;
 137
 138   while (1) {
 139     flags = osEventFlagsWait (evt_id,FLAGS_MSK1,osFlagsWaitAny, osWaitForever);
 140     //handle event
 141   }
 142 }
 143 \endcode
 144 */
 145
 146 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 147 /**
 148 \fn uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags)
 149 \details
 150 The function \b osEventFlagsSet sets the event flags specified by the parameter \a flags in an event flags object specified
 151 by parameter \a ef_id. All threads waiting for the flag set will be notified to resume from \ref ThreadStates "BLOCKED" state.
 152 The function returns the event flags after setting or an error code (highest bit is set, refer to \ref flags_error_codes).
 153
 154 Possible \ref flags_error_codes return values:
 155     - \em osFlagsErrorUnknown: Unspecified error.
 156     - \em osFlagsErrorResource: Event flags object specified by parameter \a ef_id is not ready to be used.
 157     - \em osFlagsErrorParameter: Parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 158
 159 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 160
 161 <b>Code Example</b>
 162 \code
 163 #include "cmsis_os2.h"                                        // CMSIS RTOS header file
 164
 165 osEventFlagsId_t evt_id;                                      // message queue id
 166
 167 void Thread_EventSender (void *argument)
 168 {
 169   evt_id = osEventFlagsNew(NULL);
 170   while (1) {
 171     osEventFlagsSet(evt_id, FLAGS_MSK1);
 172     osThreadYield ();                                         // suspend thread
 173   }
 174 }
 175
 176 void Thread_EventReceiver (void *argument)
 177 {
 178   uint32_t  flags;
 179
 180   while (1) {
 181     flags = osEventFlagsWait (evt_id,FLAGS_MSK1,osFlagsWaitAny, osWaitForever);
 182     //handle event
 183   }
 184 }
 185 \endcode
 186 */
 187
 188 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 189 /**
 190 \fn uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags)
 191 \details
 192 The function \b osEventFlagsClear clears the event flags specified by the parameter \a flags in an event flags object
 193 specified by parameter \a ef_id. The function returns the event flags before clearing or an error code (highest bit is set,
 194 refer to \ref flags_error_codes).
 195
 196 Possible \ref flags_error_codes return values:
 197     - \em osFlagsErrorUnknown: Unspecified error.
 198     - \em osFlagsErrorResource: Event flags object specified by parameter \a ef_id is not ready to be used.
 199     - \em osFlagsErrorParameter: Parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 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
 208 The 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
 218 The function \b osEventFlagsWait suspends the execution of the currently \ref ThreadStates "RUNNING" thread until any or all event flags
 219 specified by the parameter \a flags in the event object specified by parameter \a ef_id are set. When these event flags are
 220 already set, the function returns instantly. Otherwise, the thread is put into the state \ref ThreadStates "BLOCKED".
 221
 222 The \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
 229 If \c osFlagsNoClear is set in the options \ref osEventFlagsClear can be used to clear flags manually.
 230
 231 The parameter \ref CMSIS_RTOS_TimeOutValue "timeout" represents a number of timer ticks and is an upper bound. The
 232 exact time delay depends on the actual time elapsed since the last timer tick.
 233
 234 The function returns the event flags before clearing or an error code (highest bit is set, refer to \ref flags_error_codes).
 235
 236 Possible \ref flags_error_codes return values:
 237     - \em osFlagsErrorUnknown: Unspecified error.
 238     - \em osFlagsErrorTimeout: The awaited flags has not been set during given timeout.
 239     - \em osFlagsErrorResource: Event flags object specified by parameter \a ef_id is not ready to be used.
 240     - \em osFlagsErrorParameter: Parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 241
 242 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 243
 244 \b Code \b Example
 245 \code
 246 #include "cmsis_os2.h"                                        // CMSIS RTOS header file
 247
 248 osEventFlagsId_t evt_id;                                      // message queue id
 249
 250 void Thread_EventSender (void *argument)
 251 {
 252   evt_id = osEventFlagsNew(NULL);
 253   while (1) {
 254     osEventFlagsSet(evt_id, FLAGS_MSK1);
 255     osThreadYield ();                                         // suspend thread
 256   }
 257 }
 258
 259 void Thread_EventReceiver (void *argument)
 260 {
 261   uint32_t  flags;
 262
 263   while (1) {
 264     flags = osEventFlagsWait (evt_id,FLAGS_MSK1,osFlagsWaitAny, osWaitForever);
 265     //handle event
 266   }
 267 }
 268 \endcode
 269 */
 270
 271 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 272 /**
 273 \fn osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
 274 \details
 275 The function \b osEventFlagsDelete deletes the event flags object specified by parameter \a ef_id and releases the internal
 276 memory obtained for the event flags handling. After this call, the \em ef_id is no longer valid and cannot be used. This can
 277 cause starvation of threads that are waiting for flags of this event object. The \em ef_id may be created again using the
 278 function \ref osEventFlagsNew.
 279
 280 Possible \ref osStatus_t return values:
 281  - \em osOK: the specified event flags object has been deleted.
 282  - \em osErrorISR: \b osEventFlagsDelete cannot be called from interrupt service routines.
 283  - \em osErrorParameter: the value of the parameter \a ef_id is incorrect.
 284  - \em osErrorResource: parameter \em ef_id is \token{NULL} or wrong.
 285
 286 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 287 */
 288
 289 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 290 /**
 291 \fn const char *osEventFlagsGetName (osEventFlagsId_t ef_id)
 292 \details
 293 The function \b osEventFlagsGetName returns the pointer to the name string of the event flags object identified by parameter
 294 \a ef_id or \token{NULL} in case of an error.
 295
 296 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 297
 298 <b>Code Example</b>
 299 \code
 300 void EvtFlagsGetName_example (void)  {
 301   char id;                                           // id of the event flags object
 302
 303   id = osEventFlagsGetName ();
 304   if (id == NULL) {
 305     // Failed to get the event flags object name
 306   }
 307 }
 308 \endcode
 309 */
 310
 311 /// @}
 312
 313 // these struct members must stay outside the group to avoid double entries in documentation
 314 /**
 315 \var osEventFlagsAttr_t::attr_bits
 316 \details
 317 Reserved for future use (set to '0').\n
 318 Default: \token{0}.
 319
 320 \var osEventFlagsAttr_t::cb_mem
 321 \details
 322 Pointer to a memory location for the event control block object. This can optionally be used for custom memory management systems.\n
 323 Default: \token{NULL} (uses kernel memory management).
 324
 325
 326 \var osEventFlagsAttr_t::cb_size
 327 \details
 328 The size of the memory block passed with \ref cb_mem. Must be the size of an event control block object or larger.
 329
 330 \var osEventFlagsAttr_t::name
 331 \details
 332 Pointer to a string with a human readable name of the event object.\n
 333 Default: \token{NULL}.
 334 */