begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_ThreadFlags.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== Thread Flags Management ====
   3 /**
   4 \addtogroup CMSIS_RTOS_ThreadFlagsMgmt Thread Flags
   5 \ingroup CMSIS_RTOS
   6 \brief Synchronize threads using flags.
   7 \details
   8 Thread Flags are a more specialized version of the Event Flags. See \ref CMSIS_RTOS_EventFlags.
   9 While Event Flags can be used to globally signal a number of threads, thread flags are only send to a single specific thread.
  10 Every thread instance can receive thread flags without any additional allocation of a thread flags object.
  11
  12 \note Thread flag management functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines", except
  13 for \ref osThreadFlagsSet.
  14
  15 <b>Usage Example</b>
  16
  17 The following (incomplete) code excerpt sketches the usage principals for <b>Thread Flags</b>.
  18
  19 The behavior is the following:
  20 -       app_main starts executing
  21 -       statement A sets thread flags to 0x02 (flags = 0x02 – after set)
  22 -       app_main enters delay
  23 -       execution switches to threadX
  24 -       statement B waits for flag 0x01 and blocks since flag is not set
  25 -       execution switches to app_main
  26 -       statement C sets thread flags to 0x07
  27 -       threadX wakes-up and clears flag 0x01, thread flags = 0x06, return value set to 0x07 (before clear), note: all this happens during statement C
  28 -       statement C returns with flags = 0x06
  29 -       app_main enters delay
  30 -       execution switches to threadX
  31 -       statement B returns with flagsX = 0x07
  32
  33 \code
  34 #include "cmsis_os2.h"
  35
  36 osThreadId_t tid;
  37 uint32_t     flagsX;
  38 uint32_t     flags;
  39
  40 void threadX (void *argument) {
  41
  42   osDelay(1U);
  43   for (;;) {
  44     flagsX = osThreadFlagsWait(0x0001U, osFlagsWaitAny, osWaitForever); /* B */
  45   }
  46 }
  47
  48 void app_main (void *argument) {
  49
  50   tid = osThreadNew(threadX, NULL, NULL);
  51
  52   flags = osThreadFlagsSet(tid, 0x0002U); /* A */
  53   osDelay(2U);
  54   flags = osThreadFlagsSet(tid, 0x0005U); /* C */
  55   osDelay(2U);
  56
  57   for(;;);
  58 }
  59 \endcode
  60
  61 @{
  62 */
  63
  64 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  65 /** \fn uint32_t osThreadFlagsSet (osThreadId_t thread_id, uint32_t flags )
  66 The function \b osThreadFlagsSet sets the thread flags for a thread specified by parameter \em thread_id. It returns the
  67 flags set, or an error code if highest bit is set (refer to \ref flags_error_codes). This function may
  68 be used also within interrupt service routines. Threads waiting for a flag to be set will resume from \ref ThreadStates "BLOCKED" state.
  69
  70 Possible return values:
  71 - the flags set, in case of success
  72 - \em 'osErrorParameter', if the thread specified by \a thread_id thread_id is \em NULL
  73 - \em 'osErrorParameter', if a thread specified by \a thread_id does not exist
  74 - \em 'osErrorParameter', if \em flags is not in the legal range (highest bit of \em flags is set)
  75 - \em 'osErrorResource', if the thread with \em thread_id is in state \em 'osRtxThreadInactive' or \em 'osRtxThreadTerminated'.
  76
  77
  78 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  79
  80 \b Code \b Example
  81 \code
  82 /*----------------------------------------------------------------------------
  83  *      Function 'signal_func' called from multiple threads
  84  *---------------------------------------------------------------------------*/
  85 void signal_func (osThreadId_t tid)  {
  86   osThreadFlagsSet(tid_clock, 0x0100);      /* set signal to clock thread    */
  87   osDelay(500);                             /* delay 500ms                   */
  88   osThreadFlagsSet(tid_clock, 0x0100);      /* set signal to clock thread    */
  89   osDelay(500);                             /* delay 500ms                   */
  90   osThreadFlagsSet(tid, 0x0001);            /* set signal to thread 'thread' */
  91   osDelay(500);                             /* delay 500ms                   */
  92 }
  93 \endcode
  94 */
  95
  96 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  97 /** \fn uint32_t osThreadFlagsClear (uint32_t flags)
  98 \details
  99 The function \b osThreadFlagsClear clears the specified flags for the currently running thread. It returns the
 100 flags before clearing, or an error code if highest bit is set (refer to \ref flags_error_codes).
 101
 102 Possible return values:
 103 - the flags before clearing
 104 - \em 'osError', if an unspecified error occured
 105 - \em 'osErrorParameter', if flags are not in the legal range (highest bit of \em flags set)
 106 - \em 'osErrorResource', if the thread specified by \a thread_id is in state \em 'osRtxThreadInactive' or \em 'osRtxThreadTerminated'
 107
 108 - \em 'osErrorISR', if IRQ is masked
 109
 110 - \em 'osErrorISR', if in IRQ mode.
 111
 112 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 113 */
 114
 115 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 116 /** \fn uint32_t osThreadFlagsGet (void)
 117 \details
 118 The function \b osThreadFlagsGet returns the flags currently set for the currently running thread.
 119 If called without a active and currently running thread \b osThreadFlagsGet return zero.
 120
 121 Possible return values:
 122 - the flags currently set
 123 - \em 'osErrorISR', if IRQ is masked
 124
 125 - \em 'osErrorISR', if in IRQ mode
 126
 127 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 128 */
 129
 130 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 131 /** \fn uint32_t osThreadFlagsWait (uint32_t flags, uint32_t options, uint32_t timeout)
 132 The function \b osThreadFlagsWait suspends the execution of the currently \ref ThreadStates "RUNNING" thread until any or all of the thread
 133 flags specified with the parameter \a flags are set. When these thread flags are already set, the function returns instantly.
 134 Otherwise the thread is put into the state \ref ThreadStates "BLOCKED".
 135
 136 The parameter \em options specifies the wait condition:
 137 |Option              |                                                       |
 138 |--------------------|-------------------------------------------------------|
 139 |\b osFlagsWaitAny   |   Wait for any flag (default).                        |
 140 |\b osFlagsWaitAll   |   Wait for all flags.                                 |
 141 |\b osFlagsNoClear   |   Do not clear flags which have been specified to wait for.  |
 142
 143 If \c osFlagsNoClear is set in the options \ref osThreadFlagsClear can be used to clear flags manually.
 144 Otherwise \b osThreadFlagsWait automatically clears the flags waited for.
 145
 146 The parameter \ref CMSIS_RTOS_TimeOutValue "timeout" represents a number of timer ticks and is an upper bound. The
 147 exact time delay depends on the actual time elapsed since the last timer tick.
 148
 149 The function returns the flags before clearing, or an error code if highest bit is set (refer to \ref flags_error_codes).
 150
 151 Possible return values:
 152 - the flags before clearing
 153 - \em 'osErrorParameter', if \em flags are not in the legal range
 154 - \em 'osErrorTimeout', if \em timeout > 0 and the thread is waiting for flags to be set (with options osFlagsWaitAny and osFlagsWaitAll)
 155 - \em 'osErrorResource, if \em timeout == 0 and the thread is waiting for flags to be set (with options osFlagsWaitAny and osFlagsWaitAll)
 156 - \em 'osErrorISR', if IRQ is masked
 157 - \em 'osErrorISR', if in IRQ mode.
 158
 159
 160
 161 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 162
 163 <b>Code Example</b>
 164 \code
 165 #include "cmsis_os2.h"
 166
 167 void Thread (void* arg) {
 168   ;
 169   osThreadFlagsWait (0x00000001U, osFlagsWaitAny, osWaitForever); // Wait forever until thread flag 1 is set.
 170   ;
 171   osThreadFlagsWait (0x00000003U, osFlagsWaitAny, osWaitForever); // Wait forever until either thread flag 0 or 1 is set.
 172   ;
 173   osThreadFlagsWait (0x00000003U, osFlagsWaitAll, 10); // Wait for 10 timer ticks until thread flags 0 and 1 are set. Timeout afterwards.
 174   ;
 175   osThreadFlagsWait (0x00000003U, osFlagsWaitAll | osFlagsNoClear, osWaitForever); // Same as the above, but the flags will not be cleared.
 176 }
 177 \endcode
 178 */
 179 /// @}