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 after setting or an error code (highest bit is set, refer to \ref flags_error_codes).
 162
 163 Possible \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
 168 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 169
 170 <b>Code Example</b>
 171 \code
 172 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 173
 174 osEventFlagsId_t evt_id;                        // event flasg id
 175
 176 void Thread_EventSender (void *argument) {
 177
 178   while (1) {
 179     osEventFlagsSet(evt_id, 0x00000001U);
 180     osThreadYield();                            // suspend thread
 181   }
 182 }
 183 \endcode
 184 */
 185
 186 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 187 /**
 188 \fn uint32_t osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags)
 189 \details
 190 The function \b osEventFlagsClear clears the event flags specified by the parameter \a flags in an event flags object
 191 specified by parameter \a ef_id. The function returns the event flags before clearing or an error code (highest bit is set,
 192 refer to \ref flags_error_codes).
 193
 194 Possible \ref flags_error_codes return values:
 195     - \em osFlagsErrorUnknown: unspecified error.
 196     - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 197     - \em osFlagsErrorResource: the event flags object is in an invalid state.
 198
 199 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 200 */
 201
 202 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 203 /**
 204 \fn uint32_t osEventFlagsGet (osEventFlagsId_t ef_id)
 205 \details
 206 The function \b osEventFlagsGet returns the event flags currently set in an event flags object specified by parameter
 207 \a ef_id or \token{0} in case of an error.
 208
 209 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 210 */
 211
 212 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 213 /**
 214 \fn uint32_t osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout)
 215 \details
 216 The function \b osEventFlagsWait suspends the execution of the currently \ref ThreadStates "RUNNING" thread until any or all event flags
 217 specified by the parameter \a flags in the event object specified by parameter \a ef_id are set. When these event flags are
 218 already set, the function returns instantly. Otherwise, the thread is put into the state \ref ThreadStates "BLOCKED".
 219
 220 The \em options parameter specifies the wait condition:
 221 |Option              |                                                       |
 222 |--------------------|-------------------------------------------------------|
 223 |\b osFlagsWaitAny   |   Wait for any flag (default).                        |
 224 |\b osFlagsWaitAll   |   Wait for all flags.                                 |
 225 |\b osFlagsNoClear   |   Do not clear flags which have been specified to wait for.  |
 226
 227 If \c osFlagsNoClear is set in the options \ref osEventFlagsClear can be used to clear flags manually.
 228
 229 The parameter \a timeout specifies how long the system waits for event flags. While the system waits, the thread
 230 that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The parameter \ref CMSIS_RTOS_TimeOutValue
 231 "timeout" can have the following values:
 232  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 233  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the event flags become
 234    available (i.e. wait semantics).
 235  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 236
 237 The function returns the event flags before clearing or an error code (highest bit is set, refer to \ref flags_error_codes).
 238
 239 Possible \ref flags_error_codes return values:
 240     - \em osFlagsErrorUnknown: unspecified error.
 241     - \em osFlagsErrorTimeout: awaited flags have not been set in the given time.
 242     - \em osFlagsErrorResource: awaited flags have not been set when no \a timeout was specified.
 243     - \em osFlagsErrorParameter: parameter \a ef_id does not identify a valid event flags object or \em flags has highest bit set.
 244
 245 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 246 \token{0}.
 247
 248 \b Code \b Example
 249 \code
 250 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 251
 252 osEventFlagsId_t evt_id;                        // event flasg id
 253
 254 void Thread_EventReceiver (void *argument) {
 255   uint32_t flags;
 256
 257   while (1) {
 258     flags = osEventFlagsWait(evt_id, 0x00000001U, osFlagsWaitAny, osWaitForever);
 259     //handle event
 260   }
 261 }
 262 \endcode
 263 */
 264
 265 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 266 /**
 267 \fn osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
 268 \details
 269 The function \b osEventFlagsDelete deletes the event flags object specified by parameter \a ef_id and releases the internal
 270 memory obtained for the event flags handling. After this call, the \em ef_id is no longer valid and cannot be used. This can
 271 cause starvation of threads that are waiting for flags of this event object. The \em ef_id may be created again using the
 272 function \ref osEventFlagsNew.
 273
 274 Possible \ref osStatus_t return values:
 275  - \em osOK: the specified event flags object has been deleted.
 276  - \em osErrorISR: \b osEventFlagsDelete cannot be called from interrupt service routines.
 277  - \em osErrorParameter: parameter \a ef_id is \token{NULL} or invalid.
 278  - \em osErrorResource: the event flags object is in an invalid state.
 279
 280 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 281 */
 282
 283 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 284 /**
 285 \fn const char *osEventFlagsGetName (osEventFlagsId_t ef_id)
 286 \details
 287 The function \b osEventFlagsGetName returns the pointer to the name string of the event flags object identified by parameter
 288 \a ef_id or \token{NULL} in case of an error.
 289
 290 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 291
 292 <b>Code Example</b>
 293 \code
 294 #include "cmsis_os2.h"                          // CMSIS RTOS header file
 295
 296 osEventFlagsId_t evt_id;                        // event flasg id
 297
 298 void EvtFlagsGetName_example (void)  {
 299   char *name;
 300
 301   name = osEventFlagsGetName(evt_id);
 302   if (name == NULL) {
 303     // Failed to get the event flags object name
 304   }
 305 }
 306 \endcode
 307 */
 308
 309 /// @}
 310
 311 // these struct members must stay outside the group to avoid double entries in documentation
 312 /**
 313 \var osEventFlagsAttr_t::attr_bits
 314 \details
 315 Reserved for future use (must be set to '0' for future compatibility).
 316
 317 \var osEventFlagsAttr_t::cb_mem
 318 \details
 319 Pointer to a memory for the event flag control block object. Refer to \ref StaticObjectMemory for more information.
 320
 321 Default: \token{NULL} to use \ref CMSIS_RTOS_MemoryMgmt_Automatic for the event flag control block.
 322
 323 \var osEventFlagsAttr_t::cb_size
 324 \details
 325 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).
 326
 327 Default: \token{0} as the default is no memory provided with \ref cb_mem.
 328
 329 \var osEventFlagsAttr_t::name
 330 \details
 331 Pointer to a constant string with a human readable name (displayed during debugging) of the event flag object.
 332
 333 Default: \token{NULL} no name specified.
 334 */