begriffs open source - freertos/blob - include/event_groups.h

   1 /*
   2  * FreeRTOS Kernel V10.4.3 LTS Patch 3
   3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
   6  * this software and associated documentation files (the "Software"), to deal in
   7  * the Software without restriction, including without limitation the rights to
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
   9  * the Software, and to permit persons to whom the Software is furnished to do so,
  10  * subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be included in all
  13  * copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  21  *
  22  * https://www.FreeRTOS.org
  23  * https://github.com/FreeRTOS
  24  *
  25  */
  26
  27 #ifndef EVENT_GROUPS_H
  28 #define EVENT_GROUPS_H
  29
  30 #ifndef INC_FREERTOS_H
  31     #error "include FreeRTOS.h" must appear in source files before "include event_groups.h"
  32 #endif
  33
  34 /* FreeRTOS includes. */
  35 #include "timers.h"
  36
  37 /* *INDENT-OFF* */
  38 #ifdef __cplusplus
  39     extern "C" {
  40 #endif
  41 /* *INDENT-ON* */
  42
  43 /**
  44  * An event group is a collection of bits to which an application can assign a
  45  * meaning.  For example, an application may create an event group to convey
  46  * the status of various CAN bus related events in which bit 0 might mean "A CAN
  47  * message has been received and is ready for processing", bit 1 might mean "The
  48  * application has queued a message that is ready for sending onto the CAN
  49  * network", and bit 2 might mean "It is time to send a SYNC message onto the
  50  * CAN network" etc.  A task can then test the bit values to see which events
  51  * are active, and optionally enter the Blocked state to wait for a specified
  52  * bit or a group of specified bits to be active.  To continue the CAN bus
  53  * example, a CAN controlling task can enter the Blocked state (and therefore
  54  * not consume any processing time) until either bit 0, bit 1 or bit 2 are
  55  * active, at which time the bit that was actually active would inform the task
  56  * which action it had to take (process a received message, send a message, or
  57  * send a SYNC).
  58  *
  59  * The event groups implementation contains intelligence to avoid race
  60  * conditions that would otherwise occur were an application to use a simple
  61  * variable for the same purpose.  This is particularly important with respect
  62  * to when a bit within an event group is to be cleared, and when bits have to
  63  * be set and then tested atomically - as is the case where event groups are
  64  * used to create a synchronisation point between multiple tasks (a
  65  * 'rendezvous').
  66  *
  67  * \defgroup EventGroup
  68  */
  69
  70
  71
  72 /**
  73  * event_groups.h
  74  *
  75  * Type by which event groups are referenced.  For example, a call to
  76  * xEventGroupCreate() returns an EventGroupHandle_t variable that can then
  77  * be used as a parameter to other event group functions.
  78  *
  79  * \defgroup EventGroupHandle_t EventGroupHandle_t
  80  * \ingroup EventGroup
  81  */
  82 struct EventGroupDef_t;
  83 typedef struct EventGroupDef_t   * EventGroupHandle_t;
  84
  85 /*
  86  * The type that holds event bits always matches TickType_t - therefore the
  87  * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1,
  88  * 32 bits if set to 0.
  89  *
  90  * \defgroup EventBits_t EventBits_t
  91  * \ingroup EventGroup
  92  */
  93 typedef TickType_t               EventBits_t;
  94
  95 /**
  96  * event_groups.h
  97  * <pre>
  98  * EventGroupHandle_t xEventGroupCreate( void );
  99  * </pre>
 100  *
 101  * Create a new event group.
 102  *
 103  * Internally, within the FreeRTOS implementation, event groups use a [small]
 104  * block of memory, in which the event group's structure is stored.  If an event
 105  * groups is created using xEventGropuCreate() then the required memory is
 106  * automatically dynamically allocated inside the xEventGroupCreate() function.
 107  * (see https://www.FreeRTOS.org/a00111.html).  If an event group is created
 108  * using xEventGropuCreateStatic() then the application writer must instead
 109  * provide the memory that will get used by the event group.
 110  * xEventGroupCreateStatic() therefore allows an event group to be created
 111  * without using any dynamic memory allocation.
 112  *
 113  * Although event groups are not related to ticks, for internal implementation
 114  * reasons the number of bits available for use in an event group is dependent
 115  * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.  If
 116  * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
 117  * 0 to bit 7).  If configUSE_16_BIT_TICKS is set to 0 then each event group has
 118  * 24 usable bits (bit 0 to bit 23).  The EventBits_t type is used to store
 119  * event bits within an event group.
 120  *
 121  * @return If the event group was created then a handle to the event group is
 122  * returned.  If there was insufficient FreeRTOS heap available to create the
 123  * event group then NULL is returned.  See https://www.FreeRTOS.org/a00111.html
 124  *
 125  * Example usage:
 126  * <pre>
 127  *  // Declare a variable to hold the created event group.
 128  *  EventGroupHandle_t xCreatedEventGroup;
 129  *
 130  *  // Attempt to create the event group.
 131  *  xCreatedEventGroup = xEventGroupCreate();
 132  *
 133  *  // Was the event group created successfully?
 134  *  if( xCreatedEventGroup == NULL )
 135  *  {
 136  *      // The event group was not created because there was insufficient
 137  *      // FreeRTOS heap available.
 138  *  }
 139  *  else
 140  *  {
 141  *      // The event group was created.
 142  *  }
 143  * </pre>
 144  * \defgroup xEventGroupCreate xEventGroupCreate
 145  * \ingroup EventGroup
 146  */
 147 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 148     EventGroupHandle_t xEventGroupCreate( void ) PRIVILEGED_FUNCTION;
 149 #endif
 150
 151 /**
 152  * event_groups.h
 153  * <pre>
 154  * EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer );
 155  * </pre>
 156  *
 157  * Create a new event group.
 158  *
 159  * Internally, within the FreeRTOS implementation, event groups use a [small]
 160  * block of memory, in which the event group's structure is stored.  If an event
 161  * groups is created using xEventGropuCreate() then the required memory is
 162  * automatically dynamically allocated inside the xEventGroupCreate() function.
 163  * (see https://www.FreeRTOS.org/a00111.html).  If an event group is created
 164  * using xEventGropuCreateStatic() then the application writer must instead
 165  * provide the memory that will get used by the event group.
 166  * xEventGroupCreateStatic() therefore allows an event group to be created
 167  * without using any dynamic memory allocation.
 168  *
 169  * Although event groups are not related to ticks, for internal implementation
 170  * reasons the number of bits available for use in an event group is dependent
 171  * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.  If
 172  * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
 173  * 0 to bit 7).  If configUSE_16_BIT_TICKS is set to 0 then each event group has
 174  * 24 usable bits (bit 0 to bit 23).  The EventBits_t type is used to store
 175  * event bits within an event group.
 176  *
 177  * @param pxEventGroupBuffer pxEventGroupBuffer must point to a variable of type
 178  * StaticEventGroup_t, which will be then be used to hold the event group's data
 179  * structures, removing the need for the memory to be allocated dynamically.
 180  *
 181  * @return If the event group was created then a handle to the event group is
 182  * returned.  If pxEventGroupBuffer was NULL then NULL is returned.
 183  *
 184  * Example usage:
 185  * <pre>
 186  *  // StaticEventGroup_t is a publicly accessible structure that has the same
 187  *  // size and alignment requirements as the real event group structure.  It is
 188  *  // provided as a mechanism for applications to know the size of the event
 189  *  // group (which is dependent on the architecture and configuration file
 190  *  // settings) without breaking the strict data hiding policy by exposing the
 191  *  // real event group internals.  This StaticEventGroup_t variable is passed
 192  *  // into the xSemaphoreCreateEventGroupStatic() function and is used to store
 193  *  // the event group's data structures
 194  *  StaticEventGroup_t xEventGroupBuffer;
 195  *
 196  *  // Create the event group without dynamically allocating any memory.
 197  *  xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
 198  * </pre>
 199  */
 200 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 201     EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t * pxEventGroupBuffer ) PRIVILEGED_FUNCTION;
 202 #endif
 203
 204 /**
 205  * event_groups.h
 206  * <pre>
 207  *  EventBits_t xEventGroupWaitBits(    EventGroupHandle_t xEventGroup,
 208  *                                      const EventBits_t uxBitsToWaitFor,
 209  *                                      const BaseType_t xClearOnExit,
 210  *                                      const BaseType_t xWaitForAllBits,
 211  *                                      const TickType_t xTicksToWait );
 212  * </pre>
 213  *
 214  * [Potentially] block to wait for one or more bits to be set within a
 215  * previously created event group.
 216  *
 217  * This function cannot be called from an interrupt.
 218  *
 219  * @param xEventGroup The event group in which the bits are being tested.  The
 220  * event group must have previously been created using a call to
 221  * xEventGroupCreate().
 222  *
 223  * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
 224  * inside the event group.  For example, to wait for bit 0 and/or bit 2 set
 225  * uxBitsToWaitFor to 0x05.  To wait for bits 0 and/or bit 1 and/or bit 2 set
 226  * uxBitsToWaitFor to 0x07.  Etc.
 227  *
 228  * @param xClearOnExit If xClearOnExit is set to pdTRUE then any bits within
 229  * uxBitsToWaitFor that are set within the event group will be cleared before
 230  * xEventGroupWaitBits() returns if the wait condition was met (if the function
 231  * returns for a reason other than a timeout).  If xClearOnExit is set to
 232  * pdFALSE then the bits set in the event group are not altered when the call to
 233  * xEventGroupWaitBits() returns.
 234  *
 235  * @param xWaitForAllBits If xWaitForAllBits is set to pdTRUE then
 236  * xEventGroupWaitBits() will return when either all the bits in uxBitsToWaitFor
 237  * are set or the specified block time expires.  If xWaitForAllBits is set to
 238  * pdFALSE then xEventGroupWaitBits() will return when any one of the bits set
 239  * in uxBitsToWaitFor is set or the specified block time expires.  The block
 240  * time is specified by the xTicksToWait parameter.
 241  *
 242  * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
 243  * for one/all (depending on the xWaitForAllBits value) of the bits specified by
 244  * uxBitsToWaitFor to become set.
 245  *
 246  * @return The value of the event group at the time either the bits being waited
 247  * for became set, or the block time expired.  Test the return value to know
 248  * which bits were set.  If xEventGroupWaitBits() returned because its timeout
 249  * expired then not all the bits being waited for will be set.  If
 250  * xEventGroupWaitBits() returned because the bits it was waiting for were set
 251  * then the returned value is the event group value before any bits were
 252  * automatically cleared in the case that xClearOnExit parameter was set to
 253  * pdTRUE.
 254  *
 255  * Example usage:
 256  * <pre>
 257  #define BIT_0 ( 1 << 0 )
 258  #define BIT_4 ( 1 << 4 )
 259  *
 260  * void aFunction( EventGroupHandle_t xEventGroup )
 261  * {
 262  * EventBits_t uxBits;
 263  * const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
 264  *
 265  *      // Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
 266  *      // the event group.  Clear the bits before exiting.
 267  *      uxBits = xEventGroupWaitBits(
 268  *                  xEventGroup,    // The event group being tested.
 269  *                  BIT_0 | BIT_4,  // The bits within the event group to wait for.
 270  *                  pdTRUE,         // BIT_0 and BIT_4 should be cleared before returning.
 271  *                  pdFALSE,        // Don't wait for both bits, either bit will do.
 272  *                  xTicksToWait ); // Wait a maximum of 100ms for either bit to be set.
 273  *
 274  *      if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
 275  *      {
 276  *          // xEventGroupWaitBits() returned because both bits were set.
 277  *      }
 278  *      else if( ( uxBits & BIT_0 ) != 0 )
 279  *      {
 280  *          // xEventGroupWaitBits() returned because just BIT_0 was set.
 281  *      }
 282  *      else if( ( uxBits & BIT_4 ) != 0 )
 283  *      {
 284  *          // xEventGroupWaitBits() returned because just BIT_4 was set.
 285  *      }
 286  *      else
 287  *      {
 288  *          // xEventGroupWaitBits() returned because xTicksToWait ticks passed
 289  *          // without either BIT_0 or BIT_4 becoming set.
 290  *      }
 291  * }
 292  * </pre>
 293  * \defgroup xEventGroupWaitBits xEventGroupWaitBits
 294  * \ingroup EventGroup
 295  */
 296 EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
 297                                  const EventBits_t uxBitsToWaitFor,
 298                                  const BaseType_t xClearOnExit,
 299                                  const BaseType_t xWaitForAllBits,
 300                                  TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 301
 302 /**
 303  * event_groups.h
 304  * <pre>
 305  *  EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear );
 306  * </pre>
 307  *
 308  * Clear bits within an event group.  This function cannot be called from an
 309  * interrupt.
 310  *
 311  * @param xEventGroup The event group in which the bits are to be cleared.
 312  *
 313  * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear
 314  * in the event group.  For example, to clear bit 3 only, set uxBitsToClear to
 315  * 0x08.  To clear bit 3 and bit 0 set uxBitsToClear to 0x09.
 316  *
 317  * @return The value of the event group before the specified bits were cleared.
 318  *
 319  * Example usage:
 320  * <pre>
 321  #define BIT_0 ( 1 << 0 )
 322  #define BIT_4 ( 1 << 4 )
 323  *
 324  * void aFunction( EventGroupHandle_t xEventGroup )
 325  * {
 326  * EventBits_t uxBits;
 327  *
 328  *      // Clear bit 0 and bit 4 in xEventGroup.
 329  *      uxBits = xEventGroupClearBits(
 330  *                              xEventGroup,    // The event group being updated.
 331  *                              BIT_0 | BIT_4 );// The bits being cleared.
 332  *
 333  *      if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
 334  *      {
 335  *          // Both bit 0 and bit 4 were set before xEventGroupClearBits() was
 336  *          // called.  Both will now be clear (not set).
 337  *      }
 338  *      else if( ( uxBits & BIT_0 ) != 0 )
 339  *      {
 340  *          // Bit 0 was set before xEventGroupClearBits() was called.  It will
 341  *          // now be clear.
 342  *      }
 343  *      else if( ( uxBits & BIT_4 ) != 0 )
 344  *      {
 345  *          // Bit 4 was set before xEventGroupClearBits() was called.  It will
 346  *          // now be clear.
 347  *      }
 348  *      else
 349  *      {
 350  *          // Neither bit 0 nor bit 4 were set in the first place.
 351  *      }
 352  * }
 353  * </pre>
 354  * \defgroup xEventGroupClearBits xEventGroupClearBits
 355  * \ingroup EventGroup
 356  */
 357 EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
 358                                   const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
 359
 360 /**
 361  * event_groups.h
 362  * <pre>
 363  *  BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
 364  * </pre>
 365  *
 366  * A version of xEventGroupClearBits() that can be called from an interrupt.
 367  *
 368  * Setting bits in an event group is not a deterministic operation because there
 369  * are an unknown number of tasks that may be waiting for the bit or bits being
 370  * set.  FreeRTOS does not allow nondeterministic operations to be performed
 371  * while interrupts are disabled, so protects event groups that are accessed
 372  * from tasks by suspending the scheduler rather than disabling interrupts.  As
 373  * a result event groups cannot be accessed directly from an interrupt service
 374  * routine.  Therefore xEventGroupClearBitsFromISR() sends a message to the
 375  * timer task to have the clear operation performed in the context of the timer
 376  * task.
 377  *
 378  * @param xEventGroup The event group in which the bits are to be cleared.
 379  *
 380  * @param uxBitsToClear A bitwise value that indicates the bit or bits to clear.
 381  * For example, to clear bit 3 only, set uxBitsToClear to 0x08.  To clear bit 3
 382  * and bit 0 set uxBitsToClear to 0x09.
 383  *
 384  * @return If the request to execute the function was posted successfully then
 385  * pdPASS is returned, otherwise pdFALSE is returned.  pdFALSE will be returned
 386  * if the timer service queue was full.
 387  *
 388  * Example usage:
 389  * <pre>
 390  #define BIT_0 ( 1 << 0 )
 391  #define BIT_4 ( 1 << 4 )
 392  *
 393  * // An event group which it is assumed has already been created by a call to
 394  * // xEventGroupCreate().
 395  * EventGroupHandle_t xEventGroup;
 396  *
 397  * void anInterruptHandler( void )
 398  * {
 399  *      // Clear bit 0 and bit 4 in xEventGroup.
 400  *      xResult = xEventGroupClearBitsFromISR(
 401  *                          xEventGroup,     // The event group being updated.
 402  *                          BIT_0 | BIT_4 ); // The bits being set.
 403  *
 404  *      if( xResult == pdPASS )
 405  *      {
 406  *          // The message was posted successfully.
 407  *      }
 408  * }
 409  * </pre>
 410  * \defgroup xEventGroupClearBitsFromISR xEventGroupClearBitsFromISR
 411  * \ingroup EventGroup
 412  */
 413 #if ( configUSE_TRACE_FACILITY == 1 )
 414     BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup,
 415                                             const EventBits_t uxBitsToClear ) PRIVILEGED_FUNCTION;
 416 #else
 417     #define xEventGroupClearBitsFromISR( xEventGroup, uxBitsToClear ) \
 418     xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL )
 419 #endif
 420
 421 /**
 422  * event_groups.h
 423  * <pre>
 424  *  EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
 425  * </pre>
 426  *
 427  * Set bits within an event group.
 428  * This function cannot be called from an interrupt.  xEventGroupSetBitsFromISR()
 429  * is a version that can be called from an interrupt.
 430  *
 431  * Setting bits in an event group will automatically unblock tasks that are
 432  * blocked waiting for the bits.
 433  *
 434  * @param xEventGroup The event group in which the bits are to be set.
 435  *
 436  * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
 437  * For example, to set bit 3 only, set uxBitsToSet to 0x08.  To set bit 3
 438  * and bit 0 set uxBitsToSet to 0x09.
 439  *
 440  * @return The value of the event group at the time the call to
 441  * xEventGroupSetBits() returns.  There are two reasons why the returned value
 442  * might have the bits specified by the uxBitsToSet parameter cleared.  First,
 443  * if setting a bit results in a task that was waiting for the bit leaving the
 444  * blocked state then it is possible the bit will be cleared automatically
 445  * (see the xClearBitOnExit parameter of xEventGroupWaitBits()).  Second, any
 446  * unblocked (or otherwise Ready state) task that has a priority above that of
 447  * the task that called xEventGroupSetBits() will execute and may change the
 448  * event group value before the call to xEventGroupSetBits() returns.
 449  *
 450  * Example usage:
 451  * <pre>
 452  #define BIT_0 ( 1 << 0 )
 453  #define BIT_4 ( 1 << 4 )
 454  *
 455  * void aFunction( EventGroupHandle_t xEventGroup )
 456  * {
 457  * EventBits_t uxBits;
 458  *
 459  *      // Set bit 0 and bit 4 in xEventGroup.
 460  *      uxBits = xEventGroupSetBits(
 461  *                          xEventGroup,    // The event group being updated.
 462  *                          BIT_0 | BIT_4 );// The bits being set.
 463  *
 464  *      if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
 465  *      {
 466  *          // Both bit 0 and bit 4 remained set when the function returned.
 467  *      }
 468  *      else if( ( uxBits & BIT_0 ) != 0 )
 469  *      {
 470  *          // Bit 0 remained set when the function returned, but bit 4 was
 471  *          // cleared.  It might be that bit 4 was cleared automatically as a
 472  *          // task that was waiting for bit 4 was removed from the Blocked
 473  *          // state.
 474  *      }
 475  *      else if( ( uxBits & BIT_4 ) != 0 )
 476  *      {
 477  *          // Bit 4 remained set when the function returned, but bit 0 was
 478  *          // cleared.  It might be that bit 0 was cleared automatically as a
 479  *          // task that was waiting for bit 0 was removed from the Blocked
 480  *          // state.
 481  *      }
 482  *      else
 483  *      {
 484  *          // Neither bit 0 nor bit 4 remained set.  It might be that a task
 485  *          // was waiting for both of the bits to be set, and the bits were
 486  *          // cleared as the task left the Blocked state.
 487  *      }
 488  * }
 489  * </pre>
 490  * \defgroup xEventGroupSetBits xEventGroupSetBits
 491  * \ingroup EventGroup
 492  */
 493 EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
 494                                 const EventBits_t uxBitsToSet ) PRIVILEGED_FUNCTION;
 495
 496 /**
 497  * event_groups.h
 498  * <pre>
 499  *  BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken );
 500  * </pre>
 501  *
 502  * A version of xEventGroupSetBits() that can be called from an interrupt.
 503  *
 504  * Setting bits in an event group is not a deterministic operation because there
 505  * are an unknown number of tasks that may be waiting for the bit or bits being
 506  * set.  FreeRTOS does not allow nondeterministic operations to be performed in
 507  * interrupts or from critical sections.  Therefore xEventGroupSetBitsFromISR()
 508  * sends a message to the timer task to have the set operation performed in the
 509  * context of the timer task - where a scheduler lock is used in place of a
 510  * critical section.
 511  *
 512  * @param xEventGroup The event group in which the bits are to be set.
 513  *
 514  * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
 515  * For example, to set bit 3 only, set uxBitsToSet to 0x08.  To set bit 3
 516  * and bit 0 set uxBitsToSet to 0x09.
 517  *
 518  * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
 519  * will result in a message being sent to the timer daemon task.  If the
 520  * priority of the timer daemon task is higher than the priority of the
 521  * currently running task (the task the interrupt interrupted) then
 522  * *pxHigherPriorityTaskWoken will be set to pdTRUE by
 523  * xEventGroupSetBitsFromISR(), indicating that a context switch should be
 524  * requested before the interrupt exits.  For that reason
 525  * *pxHigherPriorityTaskWoken must be initialised to pdFALSE.  See the
 526  * example code below.
 527  *
 528  * @return If the request to execute the function was posted successfully then
 529  * pdPASS is returned, otherwise pdFALSE is returned.  pdFALSE will be returned
 530  * if the timer service queue was full.
 531  *
 532  * Example usage:
 533  * <pre>
 534  #define BIT_0 ( 1 << 0 )
 535  #define BIT_4 ( 1 << 4 )
 536  *
 537  * // An event group which it is assumed has already been created by a call to
 538  * // xEventGroupCreate().
 539  * EventGroupHandle_t xEventGroup;
 540  *
 541  * void anInterruptHandler( void )
 542  * {
 543  * BaseType_t xHigherPriorityTaskWoken, xResult;
 544  *
 545  *      // xHigherPriorityTaskWoken must be initialised to pdFALSE.
 546  *      xHigherPriorityTaskWoken = pdFALSE;
 547  *
 548  *      // Set bit 0 and bit 4 in xEventGroup.
 549  *      xResult = xEventGroupSetBitsFromISR(
 550  *                          xEventGroup,    // The event group being updated.
 551  *                          BIT_0 | BIT_4   // The bits being set.
 552  *                          &xHigherPriorityTaskWoken );
 553  *
 554  *      // Was the message posted successfully?
 555  *      if( xResult == pdPASS )
 556  *      {
 557  *          // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
 558  *          // switch should be requested.  The macro used is port specific and
 559  *          // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
 560  *          // refer to the documentation page for the port being used.
 561  *          portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
 562  *      }
 563  * }
 564  * </pre>
 565  * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
 566  * \ingroup EventGroup
 567  */
 568 #if ( configUSE_TRACE_FACILITY == 1 )
 569     BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
 570                                           const EventBits_t uxBitsToSet,
 571                                           BaseType_t * pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
 572 #else
 573     #define xEventGroupSetBitsFromISR( xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken ) \
 574     xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken )
 575 #endif
 576
 577 /**
 578  * event_groups.h
 579  * <pre>
 580  *  EventBits_t xEventGroupSync(    EventGroupHandle_t xEventGroup,
 581  *                                  const EventBits_t uxBitsToSet,
 582  *                                  const EventBits_t uxBitsToWaitFor,
 583  *                                  TickType_t xTicksToWait );
 584  * </pre>
 585  *
 586  * Atomically set bits within an event group, then wait for a combination of
 587  * bits to be set within the same event group.  This functionality is typically
 588  * used to synchronise multiple tasks, where each task has to wait for the other
 589  * tasks to reach a synchronisation point before proceeding.
 590  *
 591  * This function cannot be used from an interrupt.
 592  *
 593  * The function will return before its block time expires if the bits specified
 594  * by the uxBitsToWait parameter are set, or become set within that time.  In
 595  * this case all the bits specified by uxBitsToWait will be automatically
 596  * cleared before the function returns.
 597  *
 598  * @param xEventGroup The event group in which the bits are being tested.  The
 599  * event group must have previously been created using a call to
 600  * xEventGroupCreate().
 601  *
 602  * @param uxBitsToSet The bits to set in the event group before determining
 603  * if, and possibly waiting for, all the bits specified by the uxBitsToWait
 604  * parameter are set.
 605  *
 606  * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
 607  * inside the event group.  For example, to wait for bit 0 and bit 2 set
 608  * uxBitsToWaitFor to 0x05.  To wait for bits 0 and bit 1 and bit 2 set
 609  * uxBitsToWaitFor to 0x07.  Etc.
 610  *
 611  * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
 612  * for all of the bits specified by uxBitsToWaitFor to become set.
 613  *
 614  * @return The value of the event group at the time either the bits being waited
 615  * for became set, or the block time expired.  Test the return value to know
 616  * which bits were set.  If xEventGroupSync() returned because its timeout
 617  * expired then not all the bits being waited for will be set.  If
 618  * xEventGroupSync() returned because all the bits it was waiting for were
 619  * set then the returned value is the event group value before any bits were
 620  * automatically cleared.
 621  *
 622  * Example usage:
 623  * <pre>
 624  * // Bits used by the three tasks.
 625  #define TASK_0_BIT     ( 1 << 0 )
 626  #define TASK_1_BIT     ( 1 << 1 )
 627  #define TASK_2_BIT     ( 1 << 2 )
 628  *
 629  #define ALL_SYNC_BITS ( TASK_0_BIT | TASK_1_BIT | TASK_2_BIT )
 630  *
 631  * // Use an event group to synchronise three tasks.  It is assumed this event
 632  * // group has already been created elsewhere.
 633  * EventGroupHandle_t xEventBits;
 634  *
 635  * void vTask0( void *pvParameters )
 636  * {
 637  * EventBits_t uxReturn;
 638  * TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
 639  *
 640  *   for( ;; )
 641  *   {
 642  *      // Perform task functionality here.
 643  *
 644  *      // Set bit 0 in the event flag to note this task has reached the
 645  *      // sync point.  The other two tasks will set the other two bits defined
 646  *      // by ALL_SYNC_BITS.  All three tasks have reached the synchronisation
 647  *      // point when all the ALL_SYNC_BITS are set.  Wait a maximum of 100ms
 648  *      // for this to happen.
 649  *      uxReturn = xEventGroupSync( xEventBits, TASK_0_BIT, ALL_SYNC_BITS, xTicksToWait );
 650  *
 651  *      if( ( uxReturn & ALL_SYNC_BITS ) == ALL_SYNC_BITS )
 652  *      {
 653  *          // All three tasks reached the synchronisation point before the call
 654  *          // to xEventGroupSync() timed out.
 655  *      }
 656  *  }
 657  * }
 658  *
 659  * void vTask1( void *pvParameters )
 660  * {
 661  *   for( ;; )
 662  *   {
 663  *      // Perform task functionality here.
 664  *
 665  *      // Set bit 1 in the event flag to note this task has reached the
 666  *      // synchronisation point.  The other two tasks will set the other two
 667  *      // bits defined by ALL_SYNC_BITS.  All three tasks have reached the
 668  *      // synchronisation point when all the ALL_SYNC_BITS are set.  Wait
 669  *      // indefinitely for this to happen.
 670  *      xEventGroupSync( xEventBits, TASK_1_BIT, ALL_SYNC_BITS, portMAX_DELAY );
 671  *
 672  *      // xEventGroupSync() was called with an indefinite block time, so
 673  *      // this task will only reach here if the synchronisation was made by all
 674  *      // three tasks, so there is no need to test the return value.
 675  *   }
 676  * }
 677  *
 678  * void vTask2( void *pvParameters )
 679  * {
 680  *   for( ;; )
 681  *   {
 682  *      // Perform task functionality here.
 683  *
 684  *      // Set bit 2 in the event flag to note this task has reached the
 685  *      // synchronisation point.  The other two tasks will set the other two
 686  *      // bits defined by ALL_SYNC_BITS.  All three tasks have reached the
 687  *      // synchronisation point when all the ALL_SYNC_BITS are set.  Wait
 688  *      // indefinitely for this to happen.
 689  *      xEventGroupSync( xEventBits, TASK_2_BIT, ALL_SYNC_BITS, portMAX_DELAY );
 690  *
 691  *      // xEventGroupSync() was called with an indefinite block time, so
 692  *      // this task will only reach here if the synchronisation was made by all
 693  *      // three tasks, so there is no need to test the return value.
 694  *  }
 695  * }
 696  *
 697  * </pre>
 698  * \defgroup xEventGroupSync xEventGroupSync
 699  * \ingroup EventGroup
 700  */
 701 EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
 702                              const EventBits_t uxBitsToSet,
 703                              const EventBits_t uxBitsToWaitFor,
 704                              TickType_t xTicksToWait ) PRIVILEGED_FUNCTION;
 705
 706
 707 /**
 708  * event_groups.h
 709  * <pre>
 710  *  EventBits_t xEventGroupGetBits( EventGroupHandle_t xEventGroup );
 711  * </pre>
 712  *
 713  * Returns the current value of the bits in an event group.  This function
 714  * cannot be used from an interrupt.
 715  *
 716  * @param xEventGroup The event group being queried.
 717  *
 718  * @return The event group bits at the time xEventGroupGetBits() was called.
 719  *
 720  * \defgroup xEventGroupGetBits xEventGroupGetBits
 721  * \ingroup EventGroup
 722  */
 723 #define xEventGroupGetBits( xEventGroup )    xEventGroupClearBits( xEventGroup, 0 )
 724
 725 /**
 726  * event_groups.h
 727  * <pre>
 728  *  EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup );
 729  * </pre>
 730  *
 731  * A version of xEventGroupGetBits() that can be called from an ISR.
 732  *
 733  * @param xEventGroup The event group being queried.
 734  *
 735  * @return The event group bits at the time xEventGroupGetBitsFromISR() was called.
 736  *
 737  * \defgroup xEventGroupGetBitsFromISR xEventGroupGetBitsFromISR
 738  * \ingroup EventGroup
 739  */
 740 EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
 741
 742 /**
 743  * event_groups.h
 744  * <pre>
 745  *  void xEventGroupDelete( EventGroupHandle_t xEventGroup );
 746  * </pre>
 747  *
 748  * Delete an event group that was previously created by a call to
 749  * xEventGroupCreate().  Tasks that are blocked on the event group will be
 750  * unblocked and obtain 0 as the event group's value.
 751  *
 752  * @param xEventGroup The event group being deleted.
 753  */
 754 void vEventGroupDelete( EventGroupHandle_t xEventGroup ) PRIVILEGED_FUNCTION;
 755
 756 /* For internal use only. */
 757 void vEventGroupSetBitsCallback( void * pvEventGroup,
 758                                  const uint32_t ulBitsToSet ) PRIVILEGED_FUNCTION;
 759 void vEventGroupClearBitsCallback( void * pvEventGroup,
 760                                    const uint32_t ulBitsToClear ) PRIVILEGED_FUNCTION;
 761
 762
 763 #if ( configUSE_TRACE_FACILITY == 1 )
 764     UBaseType_t uxEventGroupGetNumber( void * xEventGroup ) PRIVILEGED_FUNCTION;
 765     void vEventGroupSetNumber( void * xEventGroup,
 766                                UBaseType_t uxEventGroupNumber ) PRIVILEGED_FUNCTION;
 767 #endif
 768
 769 /* *INDENT-OFF* */
 770 #ifdef __cplusplus
 771     }
 772 #endif
 773 /* *INDENT-ON* */
 774
 775 #endif /* EVENT_GROUPS_H */