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