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(1000U);                                           // 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 #include "cmsis_os2.h"                          // CMSIS RTOS header file
  49
  50 /*----------------------------------------------------------------------------
  51  *  Event Flags creation & usage
  52  *---------------------------------------------------------------------------*/
  53
  54 #define FLAGS_MSK1 0x00000001U
  55
  56 osEventFlagsId_t evt_id;                        // event flags id
  57
  58 osThreadId_t tid_Thread_EventSender;            // thread id 1
  59 osThreadId_t tid_Thread_EventReceiver;          // thread id 2
  60
  61 void Thread_EventSender   (void *argument);     // thread function 1
  62 void Thread_EventReceiver (void *argument);     // thread function 2
  63
  64 int Init_Events (void) {
  65
  66   evt_id = osEventFlagsNew(NULL);
  67   if (evt_id == NULL) {
  68     ; // Event Flags object not created, handle failure
  69   }
  70
  71   tid_Thread_EventSender = osThreadNew(Thread_EventSender, NULL, NULL);
  72   if (tid_Thread_EventSender == NULL) {
  73     return(-1);
  74   }
  75   tid_Thread_EventReceiver = osThreadNew(Thread_EventReceiver, NULL, NULL);
  76   if (tid_Thread_EventReceiver == NULL) {
  77     return(-1);
  78   }
  79
  80   return(0);
  81 }
  82
  83 void Thread_EventSender (void *argument) {
  84
  85   while (1) {
  86     osEventFlagsSet(evt_id, FLAGS_MSK1);
  87     osThreadYield();                            // suspend thread
  88   }
  89 }
  90
  91 void Thread_EventReceiver (void *argument) {
  92   uint32_t flags;
  93
  94   while (1) {
  95     flags = osEventFlagsWait(evt_id, FLAGS_MSK1, osFlagsWaitAny, osWaitForever);
  96     //handle event
  97   }
  98 }
  99 \endcode
 100
 101
 102 @{
 103 */
 104 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 105 /**
 106 \typedef osEventFlagsId_t
 107 \details
 108 Returned by:
 109 - \ref osEventFlagsNew
 110 */
 111
 112 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 113 /**
 114 \struct osEventFlagsAttr_t
 115 \details
 116 Attributes to configure an event flag set.
 117
 118 Refer to \ref CMSIS_RTOS_MemoryMgmt for details about usage of
 119  - osEventFlagsAttr_t::cb_mem
 120  - osEventFlagsAttr_t::cb_size
 121 */
 122
 123 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 124 /**
 125 \fn osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr)
 126 \details
 127 The function \b osEventFlagsNew creates a new event flags object that is used to send events across threads and returns the
 128 pointer to the event flags object identifier or \token{NULL} in case of an error. It can be safely called before the RTOS is
 129 started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
 130
 131 The parameter \a attr sets the event flags attributes (refer to \ref osEventFlagsAttr_t).  Default attributes will be used if
 132 set to \token{NULL}, i.e. kernel memory allocation is used for the event control block.
 133
 134 \note Cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 135
 136 <b>Code Example</b>
 137 \code
 138 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 139
 140 osEventFlagsId_t evt_id;                        // message queue id
 141
 142 int Init_Events (void) {
 143
 144   evt_id = osEventFlagsNew(NULL);
 145   if (evt_id == NULL) {
 146     ; // Event Flags object not created, handle failure
 147     return(-1);
 148   }
 149
 150   return(0);
 151 }
 152 \endcode
 153 */
 154
 155 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 156 /**
 157 \fn uint32_t osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags)
 158 \details
 159 The function \b osEventFlagsSet sets the event flags specified by the parameter \a flags in an event flags object specified
 160 by parameter \a ef_id. All threads waiting for the flag set will be notified to resume from \ref ThreadStates "BLOCKED" state.
 161 The function returns the event flags stored in the event control block or an error code (highest bit is set, refer to
 162 \ref flags_error_codes).
 163
 164 Possible \ref flags_error_codes return values:
 165     - \em osFlagsErrorUnknown: unspecified error.
 166     - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 167     - \em osFlagsErrorResource: the event flags object is in an invalid state.
 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
 175 osEventFlagsId_t evt_id;                        // event flasg id
 176
 177 void 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
 191 The function \b osEventFlagsClear clears the event flags specified by the parameter \a flags in an event flags object
 192 specified by parameter \a ef_id. The function returns the event flags before clearing or an error code (highest bit is set,
 193 refer to \ref flags_error_codes).
 194
 195 Possible \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
 200 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 201 */
 202
 203 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 204 /**
 205 \fn uint32_t osEventFlagsGet (osEventFlagsId_t ef_id)
 206 \details
 207 The function \b osEventFlagsGet returns the event flags currently set in an event flags object specified by parameter
 208 \a ef_id or \token{0} in case of an error.
 209
 210 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 211 */
 212
 213 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 214 /**
 215 \fn uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout)
 216 \details
 217 The function \b osEventFlagsWait suspends the execution of the currently \ref ThreadStates "RUNNING" thread until any or all event flags
 218 specified by the parameter \a flags in the event object specified by parameter \a ef_id are set. When these event flags are
 219 already set, the function returns instantly. Otherwise, the thread is put into the state \ref ThreadStates "BLOCKED".
 220
 221 The \em options parameter specifies the wait condition:
 222 |Option              |                                                       |
 223 |--------------------|-------------------------------------------------------|
 224 |\b osFlagsWaitAny   |   Wait for any flag (default).                        |
 225 |\b osFlagsWaitAll   |   Wait for all flags.                                 |
 226 |\b osFlagsNoClear   |   Do not clear flags which have been specified to wait for.  |
 227
 228 If \c osFlagsNoClear is set in the options \ref osEventFlagsClear can be used to clear flags manually.
 229
 230 The parameter \a timeout specifies how long the system waits for event flags. While the system waits, the thread
 231 that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue
 232 "timeout" can have the following values:
 233  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 234  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the event flags become
 235    available (i.e. wait semantics).
 236  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 237
 238 The function returns the event flags before clearing or an error code (highest bit is set, refer to \ref flags_error_codes).
 239
 240 Possible \ref flags_error_codes return values:
 241     - \em osFlagsErrorUnknown: unspecified error.
 242     - \em osFlagsErrorTimeout: awaited flags have not been set in the given time.
 243     - \em osFlagsErrorResource: awaited flags have not been set when no \a timeout was specified.
 244     - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 245
 246 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 247 \token{0}.
 248
 249 \b Code \b Example
 250 \code
 251 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 252
 253 osEventFlagsId_t evt_id;                        // event flasg id
 254
 255 void Thread_EventReceiver (void *argument) {
 256   uint32_t flags;
 257
 258   while (1) {
 259     flags = osEventFlagsWait(evt_id, 0x00000001U, osFlagsWaitAny, osWaitForever);
 260     //handle event
 261   }
 262 }
 263 \endcode
 264 */
 265
 266 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 267 /**
 268 \fn osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
 269 \details
 270 The function \b osEventFlagsDelete deletes the event flags object specified by parameter \a ef_id and releases the internal
 271 memory obtained for the event flags handling. After this call, the \em ef_id is no longer valid and cannot be used. This can
 272 cause starvation of threads that are waiting for flags of this event object. The \em ef_id may be created again using the
 273 function \ref osEventFlagsNew.
 274
 275 Possible \ref osStatus_t return values:
 276  - \em osOK: the specified event flags object has been deleted.
 277  - \em osErrorISR: \b osEventFlagsDelete cannot be called from interrupt service routines.
 278  - \em osErrorParameter: parameter \a ef_id is \token{NULL} or invalid.
 279  - \em osErrorResource: the event flags object is in an invalid state.
 280
 281 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 282 */
 283
 284 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 285 /**
 286 \fn const char *osEventFlagsGetName (osEventFlagsId_t ef_id)
 287 \details
 288 The function \b osEventFlagsGetName returns the pointer to the name string of the event flags object identified by parameter
 289 \a ef_id or \token{NULL} in case of an error.
 290
 291 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 292
 293 <b>Code Example</b>
 294 \code
 295 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 296
 297 osEventFlagsId_t evt_id;                        // event flasg id
 298
 299 void EvtFlagsGetName_example (void)  {
 300   char *name;
 301
 302   name = osEventFlagsGetName(evt_id);
 303   if (name == NULL) {
 304     // Failed to get the event flags object name
 305   }
 306 }
 307 \endcode
 308 */
 309
 310 /// @}
 311
 312 // these struct members must stay outside the group to avoid double entries in documentation
 313 /**
 314 \var osEventFlagsAttr_t::attr_bits
 315 \details
 316 Reserved for future use (must be set to '0' for future compatibility).
 317
 318 \var osEventFlagsAttr_t::cb_mem
 319 \details
 320 Pointer to a memory for the event flag control block object. Refer to \ref StaticObjectMemory for more information.
 321
 322 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the event flag control block.
 323
 324 \var osEventFlagsAttr_t::cb_size
 325 \details
 326 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).
 327
 328 Default: \token{0} as the default is no memory provided with \ref cb_mem.
 329
 330 \var osEventFlagsAttr_t::name
 331 \details
 332 Pointer to a constant string with a human readable name (displayed during debugging) of the event flag object.
 333
 334 Default: \token{NULL} no name specified.
 335 */