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 Create events using flags.
   9 \details
  10 Events are used to trigger execution states between threads. The event flag management functions in CMSIS-RTOS allow you to control or wait for event flags. Each signal has up to 31 event flags (int32_t flags provides 31 bits).
  11
  12 A thread
  13 - can wait for event flags to be set (using \ref osEventFlagsGet). Using this function, it enters the
  14   \ref ThreadStates "BLOCKED" state. The \ref osEventFlagsGet parameter \a flags defines the signals that are required to put the thread back into \b READY state.
  15 - may set one or more flags in any other given thread (using \ref osEventFlagsSet).
  16 - may clear its own signals or the signals of other threads (using \ref osEventFlagsClear).
  17
  18 When a thread wakes up and resumes execution, its signal flags are automatically cleared.
  19
  20 Working with Events
  21 --------------------
  22 Here is a simple example that shows how two thread can communicate with each others using event flags:
  23
  24 \image html simple_signal.png "Simple event communication"
  25
  26 The following steps are required to use signals:
  27 -# In the thread that is supposed to send  a event with id sig1_id, call the wait function:
  28 \code
  29 osEventFlagsSet (sig1_id, 0x0001); //
  30 \endcode
  31 -# In another thread (or threads) that are supposed wait for the event:
  32 \code
  33 osEventFlagsGet (sig1_id, 0x0001, NULL, osWaitForever);    // set the signal 0x0001 for thread tid_thread1
  34 osDelay (1000);                       // wait for 1 second
  35 \endcode
  36
  37 @{
  38 */
  39 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  40 /**
  41 \typedef osEventFlagsId_t
  42 \details
  43
  44 */
  45 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  46 /**
  47 \struct osEventFlagsAttr_t
  48 \details
  49
  50 */
  51 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  52 /**
  53 \fn osEventFlagsId_t osEventFlagsNew (const osEventFlagsAttr_t *attr)
  54 \details
  55 Create and initialize a Event Flag object that is used to send events across threads.
  56
  57 <b>Code Example</b>
  58 \code{.c}
  59 #include "cmsis_os2.h"
  60
  61 osEventId_tId_t event_id;
  62
  63 void CreateEvent (void)  {
  64
  65   event_id = osEventFlagsNew(NULL);
  66   if (event_id != NULL)  {
  67     // Event object created
  68   }
  69 }
  70 \endcode
  71 */
  72 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  73 /**
  74 \fn int32_t osEventFlagsSet (osEventFlagsId_t ef_id, int32_t flags)
  75 \details
  76 Set the event flags in an event flags object. This function may be used also within interrupt service routines.
  77 All threads waiting for the flag set will be notified to resume from BLOCKED state.
  78
  79 \note \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" can call this function.
  80
  81 <b>Code Example</b>
  82 \code{.c}
  83 void Thread_2 (void *arg);
  84
  85 static void EX_Signal_1 (void)  {
  86   int32_t      signals;
  87   osThreadId_t thread_id;
  88
  89   thread_id = osThreadCreate  (Thread_2, NULL, NULL);
  90   signals   = osEventFlagsSet (event_id, 0x00000005);         // Send signals to the created thread
  91 }
  92 \endcode
  93 */
  94 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  95 /**
  96 \fn int32_t osEventFlagsClear (osEventFlagsId_t ef_id, int32_t flags)
  97 \details
  98 Clear the event flags of an event flags object.
  99 */
 100 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 101 /**
 102 \fn int32_t osEventFlagsGet (osEventFlagsId_t ef_id)
 103 \details
 104 Return the event flags currently set in an event flags object.
 105 */
 106 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 107 /**
 108 \fn int32_t osEventFlagsWait (osEventFlagsId_t ef_id, int32_t flags, uint32_t options, uint32_t timeout)
 109 \details
 110 Suspend the execution of the current \b RUNNING thread until any or all specified event flags with the parameter \a flags are set.
 111 The \em options parameter specifies the wait condition.
 112
 113 |Option              |                                                                                                       |
 114 |--------------------|-------------------------------------------------------|
 115 |\b osFlagsWaitAny   |   Wait for any flag (default).                        |
 116 |\b osFlagsWaitAll   |   Wait for all flags.                                 |
 117 |\b osFlagsNoClear   |   Do not clear flags which have been specified to wait for.  |
 118
 119 If osFlagsNoClear is set in the options \ref osEventFlagsClear can be used to clear flags manually.
 120
 121 When these event flags are already set, the function returns instantly. Otherwise the thread is put into the state \b BLOCKED.
 122
 123 */
 124 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 125 /**
 126 \fn osStatus_t osEventFlagsDelete (osEventFlagsId_t ef_id)
 127 \details
 128 Delete an event flag object.  The function releases internal memory obtained for event flags handling.  After this call the \em ef_id is no longer valid and cannot be used. The \em ef_id may be created again using the function \ref osEventFlagsNew.
 129 This can cause starvation of threads that are waiting for flags of this event object.
 130 */
 131 /// @}
 132
 133 // these struct members must stay outside the group to avoid double entries in documentation
 134 /**
 135 \var osEventFlagsAttr_t::attr_bits
 136 \details
 137 No attributes available.
 138
 139 \var osEventFlagsAttr_t::cb_mem
 140 \details
 141 Pointer to a memory location for the event object. This can optionally be used for custom memory management systems.
 142 Specify \token{NULL} to use the kernel memory management.
 143
 144
 145 \var osEventFlagsAttr_t::cb_size
 146 \details
 147 The size of the memory block passed with \ref cb_mem. Must be the size of an event object or larger.
 148
 149 \var osEventFlagsAttr_t::name
 150 \details
 151 String with a human readable name of the event object.
 152
 153 */