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