begriffs open source - freertos/blob - event_groups.c

   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 /* Standard includes. */
  30 #include <stdlib.h>
  31
  32 /* Defining MPU_WRAPPERS_INCLUDED_FROM_API_FILE prevents task.h from redefining
  33  * all the API functions to use the MPU wrappers.  That should only be done when
  34  * task.h is included from an application file. */
  35 #define MPU_WRAPPERS_INCLUDED_FROM_API_FILE
  36
  37 /* FreeRTOS includes. */
  38 #include "FreeRTOS.h"
  39 #include "task.h"
  40 #include "timers.h"
  41 #include "event_groups.h"
  42
  43 /* Lint e961, e750 and e9021 are suppressed as a MISRA exception justified
  44  * because the MPU ports require MPU_WRAPPERS_INCLUDED_FROM_API_FILE to be defined
  45  * for the header files above, but not in this file, in order to generate the
  46  * correct privileged Vs unprivileged linkage and placement. */
  47 #undef MPU_WRAPPERS_INCLUDED_FROM_API_FILE /*lint !e961 !e750 !e9021 See comment above. */
  48
  49 typedef struct EventGroupDef_t
  50 {
  51     EventBits_t uxEventBits;
  52     List_t xTasksWaitingForBits; /**< List of tasks waiting for a bit to be set. */
  53
  54     #if ( configUSE_TRACE_FACILITY == 1 )
  55         UBaseType_t uxEventGroupNumber;
  56     #endif
  57
  58     #if ( ( configSUPPORT_STATIC_ALLOCATION == 1 ) && ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) )
  59         uint8_t ucStaticallyAllocated; /**< Set to pdTRUE if the event group is statically allocated to ensure no attempt is made to free the memory. */
  60     #endif
  61 } EventGroup_t;
  62
  63 /*-----------------------------------------------------------*/
  64
  65 /*
  66  * Test the bits set in uxCurrentEventBits to see if the wait condition is met.
  67  * The wait condition is defined by xWaitForAllBits.  If xWaitForAllBits is
  68  * pdTRUE then the wait condition is met if all the bits set in uxBitsToWaitFor
  69  * are also set in uxCurrentEventBits.  If xWaitForAllBits is pdFALSE then the
  70  * wait condition is met if any of the bits set in uxBitsToWait for are also set
  71  * in uxCurrentEventBits.
  72  */
  73 static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
  74                                         const EventBits_t uxBitsToWaitFor,
  75                                         const BaseType_t xWaitForAllBits ) PRIVILEGED_FUNCTION;
  76
  77 /*-----------------------------------------------------------*/
  78
  79 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
  80
  81     EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t * pxEventGroupBuffer )
  82     {
  83         EventGroup_t * pxEventBits;
  84
  85         /* A StaticEventGroup_t object must be provided. */
  86         configASSERT( pxEventGroupBuffer );
  87
  88         #if ( configASSERT_DEFINED == 1 )
  89         {
  90             /* Sanity check that the size of the structure used to declare a
  91              * variable of type StaticEventGroup_t equals the size of the real
  92              * event group structure. */
  93             volatile size_t xSize = sizeof( StaticEventGroup_t );
  94             configASSERT( xSize == sizeof( EventGroup_t ) );
  95         } /*lint !e529 xSize is referenced if configASSERT() is defined. */
  96         #endif /* configASSERT_DEFINED */
  97
  98         /* The user has provided a statically allocated event group - use it. */
  99         pxEventBits = ( EventGroup_t * ) pxEventGroupBuffer; /*lint !e740 !e9087 EventGroup_t and StaticEventGroup_t are deliberately aliased for data hiding purposes and guaranteed to have the same size and alignment requirement - checked by configASSERT(). */
 100
 101         if( pxEventBits != NULL )
 102         {
 103             pxEventBits->uxEventBits = 0;
 104             vListInitialise( &( pxEventBits->xTasksWaitingForBits ) );
 105
 106             #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 107             {
 108                 /* Both static and dynamic allocation can be used, so note that
 109                  * this event group was created statically in case the event group
 110                  * is later deleted. */
 111                 pxEventBits->ucStaticallyAllocated = pdTRUE;
 112             }
 113             #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 114
 115             traceEVENT_GROUP_CREATE( pxEventBits );
 116         }
 117         else
 118         {
 119             /* xEventGroupCreateStatic should only ever be called with
 120              * pxEventGroupBuffer pointing to a pre-allocated (compile time
 121              * allocated) StaticEventGroup_t variable. */
 122             traceEVENT_GROUP_CREATE_FAILED();
 123         }
 124
 125         return pxEventBits;
 126     }
 127
 128 #endif /* configSUPPORT_STATIC_ALLOCATION */
 129 /*-----------------------------------------------------------*/
 130
 131 #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 132
 133     EventGroupHandle_t xEventGroupCreate( void )
 134     {
 135         EventGroup_t * pxEventBits;
 136
 137         /* Allocate the event group.  Justification for MISRA deviation as
 138          * follows:  pvPortMalloc() always ensures returned memory blocks are
 139          * aligned per the requirements of the MCU stack.  In this case
 140          * pvPortMalloc() must return a pointer that is guaranteed to meet the
 141          * alignment requirements of the EventGroup_t structure - which (if you
 142          * follow it through) is the alignment requirements of the TickType_t type
 143          * (EventBits_t being of TickType_t itself).  Therefore, whenever the
 144          * stack alignment requirements are greater than or equal to the
 145          * TickType_t alignment requirements the cast is safe.  In other cases,
 146          * where the natural word size of the architecture is less than
 147          * sizeof( TickType_t ), the TickType_t variables will be accessed in two
 148          * or more reads operations, and the alignment requirements is only that
 149          * of each individual read. */
 150         pxEventBits = ( EventGroup_t * ) pvPortMalloc( sizeof( EventGroup_t ) ); /*lint !e9087 !e9079 see comment above. */
 151
 152         if( pxEventBits != NULL )
 153         {
 154             pxEventBits->uxEventBits = 0;
 155             vListInitialise( &( pxEventBits->xTasksWaitingForBits ) );
 156
 157             #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 158             {
 159                 /* Both static and dynamic allocation can be used, so note this
 160                  * event group was allocated statically in case the event group is
 161                  * later deleted. */
 162                 pxEventBits->ucStaticallyAllocated = pdFALSE;
 163             }
 164             #endif /* configSUPPORT_STATIC_ALLOCATION */
 165
 166             traceEVENT_GROUP_CREATE( pxEventBits );
 167         }
 168         else
 169         {
 170             traceEVENT_GROUP_CREATE_FAILED(); /*lint !e9063 Else branch only exists to allow tracing and does not generate code if trace macros are not defined. */
 171         }
 172
 173         return pxEventBits;
 174     }
 175
 176 #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 177 /*-----------------------------------------------------------*/
 178
 179 EventBits_t xEventGroupSync( EventGroupHandle_t xEventGroup,
 180                              const EventBits_t uxBitsToSet,
 181                              const EventBits_t uxBitsToWaitFor,
 182                              TickType_t xTicksToWait )
 183 {
 184     EventBits_t uxOriginalBitValue, uxReturn;
 185     EventGroup_t * pxEventBits = xEventGroup;
 186     BaseType_t xAlreadyYielded;
 187     BaseType_t xTimeoutOccurred = pdFALSE;
 188
 189     configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
 190     configASSERT( uxBitsToWaitFor != 0 );
 191     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
 192     {
 193         configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
 194     }
 195     #endif
 196
 197     vTaskSuspendAll();
 198     {
 199         uxOriginalBitValue = pxEventBits->uxEventBits;
 200
 201         ( void ) xEventGroupSetBits( xEventGroup, uxBitsToSet );
 202
 203         if( ( ( uxOriginalBitValue | uxBitsToSet ) & uxBitsToWaitFor ) == uxBitsToWaitFor )
 204         {
 205             /* All the rendezvous bits are now set - no need to block. */
 206             uxReturn = ( uxOriginalBitValue | uxBitsToSet );
 207
 208             /* Rendezvous always clear the bits.  They will have been cleared
 209              * already unless this is the only task in the rendezvous. */
 210             pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
 211
 212             xTicksToWait = 0;
 213         }
 214         else
 215         {
 216             if( xTicksToWait != ( TickType_t ) 0 )
 217             {
 218                 traceEVENT_GROUP_SYNC_BLOCK( xEventGroup, uxBitsToSet, uxBitsToWaitFor );
 219
 220                 /* Store the bits that the calling task is waiting for in the
 221                  * task's event list item so the kernel knows when a match is
 222                  * found.  Then enter the blocked state. */
 223                 vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | eventCLEAR_EVENTS_ON_EXIT_BIT | eventWAIT_FOR_ALL_BITS ), xTicksToWait );
 224
 225                 /* This assignment is obsolete as uxReturn will get set after
 226                  * the task unblocks, but some compilers mistakenly generate a
 227                  * warning about uxReturn being returned without being set if the
 228                  * assignment is omitted. */
 229                 uxReturn = 0;
 230             }
 231             else
 232             {
 233                 /* The rendezvous bits were not set, but no block time was
 234                  * specified - just return the current event bit value. */
 235                 uxReturn = pxEventBits->uxEventBits;
 236                 xTimeoutOccurred = pdTRUE;
 237             }
 238         }
 239     }
 240     xAlreadyYielded = xTaskResumeAll();
 241
 242     if( xTicksToWait != ( TickType_t ) 0 )
 243     {
 244         if( xAlreadyYielded == pdFALSE )
 245         {
 246             #if ( configNUMBER_OF_CORES == 1 )
 247             {
 248                 portYIELD_WITHIN_API();
 249             }
 250             #else /* #if ( configNUMBER_OF_CORES == 1 ) */
 251             {
 252                 vTaskYieldWithinAPI();
 253             }
 254             #endif /* #if ( configNUMBER_OF_CORES == 1 ) */
 255         }
 256         else
 257         {
 258             mtCOVERAGE_TEST_MARKER();
 259         }
 260
 261         /* The task blocked to wait for its required bits to be set - at this
 262          * point either the required bits were set or the block time expired.  If
 263          * the required bits were set they will have been stored in the task's
 264          * event list item, and they should now be retrieved then cleared. */
 265         uxReturn = uxTaskResetEventItemValue();
 266
 267         if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
 268         {
 269             /* The task timed out, just return the current event bit value. */
 270             taskENTER_CRITICAL();
 271             {
 272                 uxReturn = pxEventBits->uxEventBits;
 273
 274                 /* Although the task got here because it timed out before the
 275                  * bits it was waiting for were set, it is possible that since it
 276                  * unblocked another task has set the bits.  If this is the case
 277                  * then it needs to clear the bits before exiting. */
 278                 if( ( uxReturn & uxBitsToWaitFor ) == uxBitsToWaitFor )
 279                 {
 280                     pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
 281                 }
 282                 else
 283                 {
 284                     mtCOVERAGE_TEST_MARKER();
 285                 }
 286             }
 287             taskEXIT_CRITICAL();
 288
 289             xTimeoutOccurred = pdTRUE;
 290         }
 291         else
 292         {
 293             /* The task unblocked because the bits were set. */
 294         }
 295
 296         /* Control bits might be set as the task had blocked should not be
 297          * returned. */
 298         uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
 299     }
 300
 301     traceEVENT_GROUP_SYNC_END( xEventGroup, uxBitsToSet, uxBitsToWaitFor, xTimeoutOccurred );
 302
 303     /* Prevent compiler warnings when trace macros are not used. */
 304     ( void ) xTimeoutOccurred;
 305
 306     return uxReturn;
 307 }
 308 /*-----------------------------------------------------------*/
 309
 310 EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
 311                                  const EventBits_t uxBitsToWaitFor,
 312                                  const BaseType_t xClearOnExit,
 313                                  const BaseType_t xWaitForAllBits,
 314                                  TickType_t xTicksToWait )
 315 {
 316     EventGroup_t * pxEventBits = xEventGroup;
 317     EventBits_t uxReturn, uxControlBits = 0;
 318     BaseType_t xWaitConditionMet, xAlreadyYielded;
 319     BaseType_t xTimeoutOccurred = pdFALSE;
 320
 321     /* Check the user is not attempting to wait on the bits used by the kernel
 322      * itself, and that at least one bit is being requested. */
 323     configASSERT( xEventGroup );
 324     configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
 325     configASSERT( uxBitsToWaitFor != 0 );
 326     #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
 327     {
 328         configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
 329     }
 330     #endif
 331
 332     vTaskSuspendAll();
 333     {
 334         const EventBits_t uxCurrentEventBits = pxEventBits->uxEventBits;
 335
 336         /* Check to see if the wait condition is already met or not. */
 337         xWaitConditionMet = prvTestWaitCondition( uxCurrentEventBits, uxBitsToWaitFor, xWaitForAllBits );
 338
 339         if( xWaitConditionMet != pdFALSE )
 340         {
 341             /* The wait condition has already been met so there is no need to
 342              * block. */
 343             uxReturn = uxCurrentEventBits;
 344             xTicksToWait = ( TickType_t ) 0;
 345
 346             /* Clear the wait bits if requested to do so. */
 347             if( xClearOnExit != pdFALSE )
 348             {
 349                 pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
 350             }
 351             else
 352             {
 353                 mtCOVERAGE_TEST_MARKER();
 354             }
 355         }
 356         else if( xTicksToWait == ( TickType_t ) 0 )
 357         {
 358             /* The wait condition has not been met, but no block time was
 359              * specified, so just return the current value. */
 360             uxReturn = uxCurrentEventBits;
 361             xTimeoutOccurred = pdTRUE;
 362         }
 363         else
 364         {
 365             /* The task is going to block to wait for its required bits to be
 366              * set.  uxControlBits are used to remember the specified behaviour of
 367              * this call to xEventGroupWaitBits() - for use when the event bits
 368              * unblock the task. */
 369             if( xClearOnExit != pdFALSE )
 370             {
 371                 uxControlBits |= eventCLEAR_EVENTS_ON_EXIT_BIT;
 372             }
 373             else
 374             {
 375                 mtCOVERAGE_TEST_MARKER();
 376             }
 377
 378             if( xWaitForAllBits != pdFALSE )
 379             {
 380                 uxControlBits |= eventWAIT_FOR_ALL_BITS;
 381             }
 382             else
 383             {
 384                 mtCOVERAGE_TEST_MARKER();
 385             }
 386
 387             /* Store the bits that the calling task is waiting for in the
 388              * task's event list item so the kernel knows when a match is
 389              * found.  Then enter the blocked state. */
 390             vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | uxControlBits ), xTicksToWait );
 391
 392             /* This is obsolete as it will get set after the task unblocks, but
 393              * some compilers mistakenly generate a warning about the variable
 394              * being returned without being set if it is not done. */
 395             uxReturn = 0;
 396
 397             traceEVENT_GROUP_WAIT_BITS_BLOCK( xEventGroup, uxBitsToWaitFor );
 398         }
 399     }
 400     xAlreadyYielded = xTaskResumeAll();
 401
 402     if( xTicksToWait != ( TickType_t ) 0 )
 403     {
 404         if( xAlreadyYielded == pdFALSE )
 405         {
 406             #if ( configNUMBER_OF_CORES == 1 )
 407             {
 408                 portYIELD_WITHIN_API();
 409             }
 410             #else /* #if ( configNUMBER_OF_CORES == 1 ) */
 411             {
 412                 vTaskYieldWithinAPI();
 413             }
 414             #endif /* #if ( configNUMBER_OF_CORES == 1 ) */
 415         }
 416         else
 417         {
 418             mtCOVERAGE_TEST_MARKER();
 419         }
 420
 421         /* The task blocked to wait for its required bits to be set - at this
 422          * point either the required bits were set or the block time expired.  If
 423          * the required bits were set they will have been stored in the task's
 424          * event list item, and they should now be retrieved then cleared. */
 425         uxReturn = uxTaskResetEventItemValue();
 426
 427         if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
 428         {
 429             taskENTER_CRITICAL();
 430             {
 431                 /* The task timed out, just return the current event bit value. */
 432                 uxReturn = pxEventBits->uxEventBits;
 433
 434                 /* It is possible that the event bits were updated between this
 435                  * task leaving the Blocked state and running again. */
 436                 if( prvTestWaitCondition( uxReturn, uxBitsToWaitFor, xWaitForAllBits ) != pdFALSE )
 437                 {
 438                     if( xClearOnExit != pdFALSE )
 439                     {
 440                         pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
 441                     }
 442                     else
 443                     {
 444                         mtCOVERAGE_TEST_MARKER();
 445                     }
 446                 }
 447                 else
 448                 {
 449                     mtCOVERAGE_TEST_MARKER();
 450                 }
 451
 452                 xTimeoutOccurred = pdTRUE;
 453             }
 454             taskEXIT_CRITICAL();
 455         }
 456         else
 457         {
 458             /* The task unblocked because the bits were set. */
 459         }
 460
 461         /* The task blocked so control bits may have been set. */
 462         uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
 463     }
 464
 465     traceEVENT_GROUP_WAIT_BITS_END( xEventGroup, uxBitsToWaitFor, xTimeoutOccurred );
 466
 467     /* Prevent compiler warnings when trace macros are not used. */
 468     ( void ) xTimeoutOccurred;
 469
 470     return uxReturn;
 471 }
 472 /*-----------------------------------------------------------*/
 473
 474 EventBits_t xEventGroupClearBits( EventGroupHandle_t xEventGroup,
 475                                   const EventBits_t uxBitsToClear )
 476 {
 477     EventGroup_t * pxEventBits = xEventGroup;
 478     EventBits_t uxReturn;
 479
 480     /* Check the user is not attempting to clear the bits used by the kernel
 481      * itself. */
 482     configASSERT( xEventGroup );
 483     configASSERT( ( uxBitsToClear & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
 484
 485     taskENTER_CRITICAL();
 486     {
 487         traceEVENT_GROUP_CLEAR_BITS( xEventGroup, uxBitsToClear );
 488
 489         /* The value returned is the event group value prior to the bits being
 490          * cleared. */
 491         uxReturn = pxEventBits->uxEventBits;
 492
 493         /* Clear the bits. */
 494         pxEventBits->uxEventBits &= ~uxBitsToClear;
 495     }
 496     taskEXIT_CRITICAL();
 497
 498     return uxReturn;
 499 }
 500 /*-----------------------------------------------------------*/
 501
 502 #if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) )
 503
 504     BaseType_t xEventGroupClearBitsFromISR( EventGroupHandle_t xEventGroup,
 505                                             const EventBits_t uxBitsToClear )
 506     {
 507         BaseType_t xReturn;
 508
 509         traceEVENT_GROUP_CLEAR_BITS_FROM_ISR( xEventGroup, uxBitsToClear );
 510         xReturn = xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL ); /*lint !e9087 Can't avoid cast to void* as a generic callback function not specific to this use case. Callback casts back to original type so safe. */
 511
 512         return xReturn;
 513     }
 514
 515 #endif /* if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) ) */
 516 /*-----------------------------------------------------------*/
 517
 518 EventBits_t xEventGroupGetBitsFromISR( EventGroupHandle_t xEventGroup )
 519 {
 520     UBaseType_t uxSavedInterruptStatus;
 521     EventGroup_t const * const pxEventBits = xEventGroup;
 522     EventBits_t uxReturn;
 523
 524     uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
 525     {
 526         uxReturn = pxEventBits->uxEventBits;
 527     }
 528     taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
 529
 530     return uxReturn;
 531 } /*lint !e818 EventGroupHandle_t is a typedef used in other functions to so can't be pointer to const. */
 532 /*-----------------------------------------------------------*/
 533
 534 EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
 535                                 const EventBits_t uxBitsToSet )
 536 {
 537     ListItem_t * pxListItem;
 538     ListItem_t * pxNext;
 539     ListItem_t const * pxListEnd;
 540     List_t const * pxList;
 541     EventBits_t uxBitsToClear = 0, uxBitsWaitedFor, uxControlBits;
 542     EventGroup_t * pxEventBits = xEventGroup;
 543     BaseType_t xMatchFound = pdFALSE;
 544
 545     /* Check the user is not attempting to set the bits used by the kernel
 546      * itself. */
 547     configASSERT( xEventGroup );
 548     configASSERT( ( uxBitsToSet & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
 549
 550     pxList = &( pxEventBits->xTasksWaitingForBits );
 551     pxListEnd = listGET_END_MARKER( pxList ); /*lint !e826 !e740 !e9087 The mini list structure is used as the list end to save RAM.  This is checked and valid. */
 552     vTaskSuspendAll();
 553     {
 554         traceEVENT_GROUP_SET_BITS( xEventGroup, uxBitsToSet );
 555
 556         pxListItem = listGET_HEAD_ENTRY( pxList );
 557
 558         /* Set the bits. */
 559         pxEventBits->uxEventBits |= uxBitsToSet;
 560
 561         /* See if the new bit value should unblock any tasks. */
 562         while( pxListItem != pxListEnd )
 563         {
 564             pxNext = listGET_NEXT( pxListItem );
 565             uxBitsWaitedFor = listGET_LIST_ITEM_VALUE( pxListItem );
 566             xMatchFound = pdFALSE;
 567
 568             /* Split the bits waited for from the control bits. */
 569             uxControlBits = uxBitsWaitedFor & eventEVENT_BITS_CONTROL_BYTES;
 570             uxBitsWaitedFor &= ~eventEVENT_BITS_CONTROL_BYTES;
 571
 572             if( ( uxControlBits & eventWAIT_FOR_ALL_BITS ) == ( EventBits_t ) 0 )
 573             {
 574                 /* Just looking for single bit being set. */
 575                 if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) != ( EventBits_t ) 0 )
 576                 {
 577                     xMatchFound = pdTRUE;
 578                 }
 579                 else
 580                 {
 581                     mtCOVERAGE_TEST_MARKER();
 582                 }
 583             }
 584             else if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) == uxBitsWaitedFor )
 585             {
 586                 /* All bits are set. */
 587                 xMatchFound = pdTRUE;
 588             }
 589             else
 590             {
 591                 /* Need all bits to be set, but not all the bits were set. */
 592             }
 593
 594             if( xMatchFound != pdFALSE )
 595             {
 596                 /* The bits match.  Should the bits be cleared on exit? */
 597                 if( ( uxControlBits & eventCLEAR_EVENTS_ON_EXIT_BIT ) != ( EventBits_t ) 0 )
 598                 {
 599                     uxBitsToClear |= uxBitsWaitedFor;
 600                 }
 601                 else
 602                 {
 603                     mtCOVERAGE_TEST_MARKER();
 604                 }
 605
 606                 /* Store the actual event flag value in the task's event list
 607                  * item before removing the task from the event list.  The
 608                  * eventUNBLOCKED_DUE_TO_BIT_SET bit is set so the task knows
 609                  * that is was unblocked due to its required bits matching, rather
 610                  * than because it timed out. */
 611                 vTaskRemoveFromUnorderedEventList( pxListItem, pxEventBits->uxEventBits | eventUNBLOCKED_DUE_TO_BIT_SET );
 612             }
 613
 614             /* Move onto the next list item.  Note pxListItem->pxNext is not
 615              * used here as the list item may have been removed from the event list
 616              * and inserted into the ready/pending reading list. */
 617             pxListItem = pxNext;
 618         }
 619
 620         /* Clear any bits that matched when the eventCLEAR_EVENTS_ON_EXIT_BIT
 621          * bit was set in the control word. */
 622         pxEventBits->uxEventBits &= ~uxBitsToClear;
 623     }
 624     ( void ) xTaskResumeAll();
 625
 626     return pxEventBits->uxEventBits;
 627 }
 628 /*-----------------------------------------------------------*/
 629
 630 void vEventGroupDelete( EventGroupHandle_t xEventGroup )
 631 {
 632     EventGroup_t * pxEventBits = xEventGroup;
 633     const List_t * pxTasksWaitingForBits;
 634
 635     configASSERT( pxEventBits );
 636
 637     pxTasksWaitingForBits = &( pxEventBits->xTasksWaitingForBits );
 638
 639     vTaskSuspendAll();
 640     {
 641         traceEVENT_GROUP_DELETE( xEventGroup );
 642
 643         while( listCURRENT_LIST_LENGTH( pxTasksWaitingForBits ) > ( UBaseType_t ) 0 )
 644         {
 645             /* Unblock the task, returning 0 as the event list is being deleted
 646              * and cannot therefore have any bits set. */
 647             configASSERT( pxTasksWaitingForBits->xListEnd.pxNext != ( const ListItem_t * ) &( pxTasksWaitingForBits->xListEnd ) );
 648             vTaskRemoveFromUnorderedEventList( pxTasksWaitingForBits->xListEnd.pxNext, eventUNBLOCKED_DUE_TO_BIT_SET );
 649         }
 650     }
 651     ( void ) xTaskResumeAll();
 652
 653     #if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 0 ) )
 654     {
 655         /* The event group can only have been allocated dynamically - free
 656          * it again. */
 657         vPortFree( pxEventBits );
 658     }
 659     #elif ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
 660     {
 661         /* The event group could have been allocated statically or
 662          * dynamically, so check before attempting to free the memory. */
 663         if( pxEventBits->ucStaticallyAllocated == ( uint8_t ) pdFALSE )
 664         {
 665             vPortFree( pxEventBits );
 666         }
 667         else
 668         {
 669             mtCOVERAGE_TEST_MARKER();
 670         }
 671     }
 672     #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 673 }
 674 /*-----------------------------------------------------------*/
 675
 676 #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
 677     BaseType_t xEventGroupGetStaticBuffer( EventGroupHandle_t xEventGroup,
 678                                            StaticEventGroup_t ** ppxEventGroupBuffer )
 679     {
 680         BaseType_t xReturn;
 681         EventGroup_t * pxEventBits = xEventGroup;
 682
 683         configASSERT( pxEventBits );
 684         configASSERT( ppxEventGroupBuffer );
 685
 686         #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
 687         {
 688             /* Check if the event group was statically allocated. */
 689             if( pxEventBits->ucStaticallyAllocated == ( uint8_t ) pdTRUE )
 690             {
 691                 *ppxEventGroupBuffer = ( StaticEventGroup_t * ) pxEventBits;
 692                 xReturn = pdTRUE;
 693             }
 694             else
 695             {
 696                 xReturn = pdFALSE;
 697             }
 698         }
 699         #else /* configSUPPORT_DYNAMIC_ALLOCATION */
 700         {
 701             /* Event group must have been statically allocated. */
 702             *ppxEventGroupBuffer = ( StaticEventGroup_t * ) pxEventBits;
 703             xReturn = pdTRUE;
 704         }
 705         #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
 706
 707         return xReturn;
 708     }
 709 #endif /* configSUPPORT_STATIC_ALLOCATION */
 710 /*-----------------------------------------------------------*/
 711
 712 /* For internal use only - execute a 'set bits' command that was pended from
 713  * an interrupt. */
 714 void vEventGroupSetBitsCallback( void * pvEventGroup,
 715                                  const uint32_t ulBitsToSet )
 716 {
 717     ( void ) xEventGroupSetBits( pvEventGroup, ( EventBits_t ) ulBitsToSet ); /*lint !e9079 Can't avoid cast to void* as a generic timer callback prototype. Callback casts back to original type so safe. */
 718 }
 719 /*-----------------------------------------------------------*/
 720
 721 /* For internal use only - execute a 'clear bits' command that was pended from
 722  * an interrupt. */
 723 void vEventGroupClearBitsCallback( void * pvEventGroup,
 724                                    const uint32_t ulBitsToClear )
 725 {
 726     ( void ) xEventGroupClearBits( pvEventGroup, ( EventBits_t ) ulBitsToClear ); /*lint !e9079 Can't avoid cast to void* as a generic timer callback prototype. Callback casts back to original type so safe. */
 727 }
 728 /*-----------------------------------------------------------*/
 729
 730 static BaseType_t prvTestWaitCondition( const EventBits_t uxCurrentEventBits,
 731                                         const EventBits_t uxBitsToWaitFor,
 732                                         const BaseType_t xWaitForAllBits )
 733 {
 734     BaseType_t xWaitConditionMet = pdFALSE;
 735
 736     if( xWaitForAllBits == pdFALSE )
 737     {
 738         /* Task only has to wait for one bit within uxBitsToWaitFor to be
 739          * set.  Is one already set? */
 740         if( ( uxCurrentEventBits & uxBitsToWaitFor ) != ( EventBits_t ) 0 )
 741         {
 742             xWaitConditionMet = pdTRUE;
 743         }
 744         else
 745         {
 746             mtCOVERAGE_TEST_MARKER();
 747         }
 748     }
 749     else
 750     {
 751         /* Task has to wait for all the bits in uxBitsToWaitFor to be set.
 752          * Are they set already? */
 753         if( ( uxCurrentEventBits & uxBitsToWaitFor ) == uxBitsToWaitFor )
 754         {
 755             xWaitConditionMet = pdTRUE;
 756         }
 757         else
 758         {
 759             mtCOVERAGE_TEST_MARKER();
 760         }
 761     }
 762
 763     return xWaitConditionMet;
 764 }
 765 /*-----------------------------------------------------------*/
 766
 767 #if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) )
 768
 769     BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
 770                                           const EventBits_t uxBitsToSet,
 771                                           BaseType_t * pxHigherPriorityTaskWoken )
 772     {
 773         BaseType_t xReturn;
 774
 775         traceEVENT_GROUP_SET_BITS_FROM_ISR( xEventGroup, uxBitsToSet );
 776         xReturn = xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken ); /*lint !e9087 Can't avoid cast to void* as a generic callback function not specific to this use case. Callback casts back to original type so safe. */
 777
 778         return xReturn;
 779     }
 780
 781 #endif /* if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) ) */
 782 /*-----------------------------------------------------------*/
 783
 784 #if ( configUSE_TRACE_FACILITY == 1 )
 785
 786     UBaseType_t uxEventGroupGetNumber( void * xEventGroup )
 787     {
 788         UBaseType_t xReturn;
 789         EventGroup_t const * pxEventBits = ( EventGroup_t * ) xEventGroup; /*lint !e9087 !e9079 EventGroupHandle_t is a pointer to an EventGroup_t, but EventGroupHandle_t is kept opaque outside of this file for data hiding purposes. */
 790
 791         if( xEventGroup == NULL )
 792         {
 793             xReturn = 0;
 794         }
 795         else
 796         {
 797             xReturn = pxEventBits->uxEventGroupNumber;
 798         }
 799
 800         return xReturn;
 801     }
 802
 803 #endif /* configUSE_TRACE_FACILITY */
 804 /*-----------------------------------------------------------*/
 805
 806 #if ( configUSE_TRACE_FACILITY == 1 )
 807
 808     void vEventGroupSetNumber( void * xEventGroup,
 809                                UBaseType_t uxEventGroupNumber )
 810     {
 811         ( ( EventGroup_t * ) xEventGroup )->uxEventGroupNumber = uxEventGroupNumber; /*lint !e9087 !e9079 EventGroupHandle_t is a pointer to an EventGroup_t, but EventGroupHandle_t is kept opaque outside of this file for data hiding purposes. */
 812     }
 813
 814 #endif /* configUSE_TRACE_FACILITY */
 815 /*-----------------------------------------------------------*/