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

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