Event group functions

FreeRTOS/event_groups.c

@@ -0,0 +1,180 @@
+/*
+ * FreeRTOS Kernel V10.4.6
+ * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ *
+ */
+
+/* Standard includes. */
+#include <stdlib.h>
+
+/* FreeRTOS includes. */
+#include "FreeRTOS.h"
+#include "event_groups.h"
+
+typedef struct EventGroupDef_t
+{
+    struct rt_event event;
+} EventGroup_t;
+
+static volatile rt_uint8_t event_index = 0;
+
+/*-----------------------------------------------------------*/
+
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+
+    EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t * pxEventGroupBuffer )
+    {
+        char name[RT_NAME_MAX] = {0};
+
+        /* A StaticEventGroup_t object must be provided. */
+        configASSERT( pxEventGroupBuffer );
+
+        rt_snprintf( name, RT_NAME_MAX, "event%02d", event_index++ );
+        rt_event_init( ( rt_event_t ) pxEventGroupBuffer, name, RT_IPC_FLAG_PRIO );
+
+        return ( EventGroupHandle_t ) pxEventGroupBuffer;
+    }
+
+#endif /* configSUPPORT_STATIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
+#if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
+
+    EventGroupHandle_t xEventGroupCreate( void )
+    {
+        EventGroup_t * pxEventBits;
+        char name[RT_NAME_MAX] = {0};
+
+        rt_snprintf( name, RT_NAME_MAX, "event%02d", event_index++ );
+        pxEventBits = ( EventGroup_t * ) rt_event_create( name, RT_IPC_FLAG_PRIO );
+
+        return pxEventBits;
+    }
+
+#endif /* configSUPPORT_DYNAMIC_ALLOCATION */
+/*-----------------------------------------------------------*/
+
+EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
+                                 const EventBits_t uxBitsToWaitFor,
+                                 const BaseType_t xClearOnExit,
+                                 const BaseType_t xWaitForAllBits,
+                                 TickType_t xTicksToWait )
+{
+    rt_event_t event = ( rt_event_t ) xEventGroup;
+    rt_uint8_t option = 0;
+    rt_uint32_t recved;
+    rt_base_t level;
+    rt_err_t err;
+
+    /* Check the user is not attempting to wait on the bits used by the kernel
+     * itself, and that at least one bit is being requested. */
+    configASSERT( xEventGroup );
+    configASSERT( uxBitsToWaitFor != 0 );
+    #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
+        {
+            configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
+        }
+    #endif
+
+    if ( xWaitForAllBits != pdFALSE )
+    {
+        option |= RT_EVENT_FLAG_AND;
+    }
+    else
+    {
+        option |= RT_EVENT_FLAG_OR;
+    }
+    if ( xClearOnExit != pdFALSE )
+    {
+        option |= RT_EVENT_FLAG_CLEAR;
+    }
+    err = rt_event_recv( event, ( rt_uint32_t ) uxBitsToWaitFor, option, ( rt_int32_t ) xTicksToWait, &recved );
+
+    if ( err != RT_EOK )
+    {
+        level = rt_hw_interrupt_disable();
+        recved = event->set;
+        rt_hw_interrupt_enable(level);
+    }
+
+    return ( EventBits_t ) recved;
+}
+/*-----------------------------------------------------------*/
+
+EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
+                                const EventBits_t uxBitsToSet )
+{
+    rt_event_t event = ( rt_event_t ) xEventGroup;
+
+    configASSERT( xEventGroup );
+
+    rt_event_send( event, ( rt_uint32_t ) uxBitsToSet);
+
+    return event->set;
+}
+/*-----------------------------------------------------------*/
+
+void vEventGroupDelete( EventGroupHandle_t xEventGroup )
+{
+    rt_event_t event = ( rt_event_t ) xEventGroup;
+
+    configASSERT( xEventGroup );
+
+#if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
+    if ( rt_object_is_systemobject( ( rt_object_t ) event ) )
+#endif
+    {
+    #if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+        rt_event_detach( event );
+    #endif
+#if ( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
+    }
+    else
+    {
+#endif
+    #if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
+        rt_event_delete( event );
+    #endif
+    }
+}
+/*-----------------------------------------------------------*/
+
+#if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) )
+
+    BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
+                                          const EventBits_t uxBitsToSet,
+                                          BaseType_t * pxHigherPriorityTaskWoken )
+    {
+        xEventGroupSetBits( xEventGroup, uxBitsToSet );
+        if ( pxHigherPriorityTaskWoken != NULL)
+        {
+            pxHigherPriorityTaskWoken = pdFALSE;
+        }
+
+        return pdPASS;
+    }
+
+#endif /* if ( ( configUSE_TRACE_FACILITY == 1 ) && ( INCLUDE_xTimerPendFunctionCall == 1 ) && ( configUSE_TIMERS == 1 ) ) */
+/*-----------------------------------------------------------*/

FreeRTOS/include/FreeRTOS.h

@@ -1147,6 +1147,11 @@ typedef struct
     } ipc_obj;
 } StaticSemaphore_t;
 
+typedef struct xSTATIC_EVENT_GROUP
+{
+    struct rt_event event;
+} StaticEventGroup_t;
+
 /* *INDENT-OFF* */
 #ifdef __cplusplus
     }

FreeRTOS/include/event_groups.h

@@ -0,0 +1,472 @@
+/*
+ * FreeRTOS Kernel V10.4.6
+ * Copyright (C) 2021 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * https://www.FreeRTOS.org
+ * https://github.com/FreeRTOS
+ *
+ */
+
+#ifndef EVENT_GROUPS_H
+#define EVENT_GROUPS_H
+
+#ifndef INC_FREERTOS_H
+    #error "include FreeRTOS.h" must appear in source files before "include event_groups.h"
+#endif
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+    extern "C" {
+#endif
+/* *INDENT-ON* */
+
+/**
+ * An event group is a collection of bits to which an application can assign a
+ * meaning.  For example, an application may create an event group to convey
+ * the status of various CAN bus related events in which bit 0 might mean "A CAN
+ * message has been received and is ready for processing", bit 1 might mean "The
+ * application has queued a message that is ready for sending onto the CAN
+ * network", and bit 2 might mean "It is time to send a SYNC message onto the
+ * CAN network" etc.  A task can then test the bit values to see which events
+ * are active, and optionally enter the Blocked state to wait for a specified
+ * bit or a group of specified bits to be active.  To continue the CAN bus
+ * example, a CAN controlling task can enter the Blocked state (and therefore
+ * not consume any processing time) until either bit 0, bit 1 or bit 2 are
+ * active, at which time the bit that was actually active would inform the task
+ * which action it had to take (process a received message, send a message, or
+ * send a SYNC).
+ *
+ * The event groups implementation contains intelligence to avoid race
+ * conditions that would otherwise occur were an application to use a simple
+ * variable for the same purpose.  This is particularly important with respect
+ * to when a bit within an event group is to be cleared, and when bits have to
+ * be set and then tested atomically - as is the case where event groups are
+ * used to create a synchronisation point between multiple tasks (a
+ * 'rendezvous').
+ *
+ * \defgroup EventGroup
+ */
+
+
+
+/**
+ * event_groups.h
+ *
+ * Type by which event groups are referenced.  For example, a call to
+ * xEventGroupCreate() returns an EventGroupHandle_t variable that can then
+ * be used as a parameter to other event group functions.
+ *
+ * \defgroup EventGroupHandle_t EventGroupHandle_t
+ * \ingroup EventGroup
+ */
+struct EventGroupDef_t;
+typedef struct EventGroupDef_t   * EventGroupHandle_t;
+
+/*
+ * The type that holds event bits always matches TickType_t - therefore the
+ * number of bits it holds is set by configUSE_16_BIT_TICKS (16 bits if set to 1,
+ * 32 bits if set to 0.
+ *
+ * \defgroup EventBits_t EventBits_t
+ * \ingroup EventGroup
+ */
+typedef TickType_t               EventBits_t;
+
+/**
+ * event_groups.h
+ * @code{c}
+ * EventGroupHandle_t xEventGroupCreate( void );
+ * @endcode
+ *
+ * Create a new event group.
+ *
+ * Internally, within the FreeRTOS implementation, event groups use a [small]
+ * block of memory, in which the event group's structure is stored.  If an event
+ * groups is created using xEventGroupCreate() then the required memory is
+ * automatically dynamically allocated inside the xEventGroupCreate() function.
+ * (see https://www.FreeRTOS.org/a00111.html).  If an event group is created
+ * using xEventGroupCreateStatic() then the application writer must instead
+ * provide the memory that will get used by the event group.
+ * xEventGroupCreateStatic() therefore allows an event group to be created
+ * without using any dynamic memory allocation.
+ *
+ * Although event groups are not related to ticks, for internal implementation
+ * reasons the number of bits available for use in an event group is dependent
+ * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.  If
+ * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
+ * 0 to bit 7).  If configUSE_16_BIT_TICKS is set to 0 then each event group has
+ * 24 usable bits (bit 0 to bit 23).  The EventBits_t type is used to store
+ * event bits within an event group.
+ *
+ * @return If the event group was created then a handle to the event group is
+ * returned.  If there was insufficient FreeRTOS heap available to create the
+ * event group then NULL is returned.  See https://www.FreeRTOS.org/a00111.html
+ *
+ * Example usage:
+ * @code{c}
+ *  // Declare a variable to hold the created event group.
+ *  EventGroupHandle_t xCreatedEventGroup;
+ *
+ *  // Attempt to create the event group.
+ *  xCreatedEventGroup = xEventGroupCreate();
+ *
+ *  // Was the event group created successfully?
+ *  if( xCreatedEventGroup == NULL )
+ *  {
+ *      // The event group was not created because there was insufficient
+ *      // FreeRTOS heap available.
+ *  }
+ *  else
+ *  {
+ *      // The event group was created.
+ *  }
+ * @endcode
+ * \defgroup xEventGroupCreate xEventGroupCreate
+ * \ingroup EventGroup
+ */
+#if ( configSUPPORT_DYNAMIC_ALLOCATION == 1 )
+    EventGroupHandle_t xEventGroupCreate( void );
+#endif
+
+/**
+ * event_groups.h
+ * @code{c}
+ * EventGroupHandle_t xEventGroupCreateStatic( EventGroupHandle_t * pxEventGroupBuffer );
+ * @endcode
+ *
+ * Create a new event group.
+ *
+ * Internally, within the FreeRTOS implementation, event groups use a [small]
+ * block of memory, in which the event group's structure is stored.  If an event
+ * groups is created using xEventGroupCreate() then the required memory is
+ * automatically dynamically allocated inside the xEventGroupCreate() function.
+ * (see https://www.FreeRTOS.org/a00111.html).  If an event group is created
+ * using xEventGroupCreateStatic() then the application writer must instead
+ * provide the memory that will get used by the event group.
+ * xEventGroupCreateStatic() therefore allows an event group to be created
+ * without using any dynamic memory allocation.
+ *
+ * Although event groups are not related to ticks, for internal implementation
+ * reasons the number of bits available for use in an event group is dependent
+ * on the configUSE_16_BIT_TICKS setting in FreeRTOSConfig.h.  If
+ * configUSE_16_BIT_TICKS is 1 then each event group contains 8 usable bits (bit
+ * 0 to bit 7).  If configUSE_16_BIT_TICKS is set to 0 then each event group has
+ * 24 usable bits (bit 0 to bit 23).  The EventBits_t type is used to store
+ * event bits within an event group.
+ *
+ * @param pxEventGroupBuffer pxEventGroupBuffer must point to a variable of type
+ * StaticEventGroup_t, which will be then be used to hold the event group's data
+ * structures, removing the need for the memory to be allocated dynamically.
+ *
+ * @return If the event group was created then a handle to the event group is
+ * returned.  If pxEventGroupBuffer was NULL then NULL is returned.
+ *
+ * Example usage:
+ * @code{c}
+ *  // StaticEventGroup_t is a publicly accessible structure that has the same
+ *  // size and alignment requirements as the real event group structure.  It is
+ *  // provided as a mechanism for applications to know the size of the event
+ *  // group (which is dependent on the architecture and configuration file
+ *  // settings) without breaking the strict data hiding policy by exposing the
+ *  // real event group internals.  This StaticEventGroup_t variable is passed
+ *  // into the xSemaphoreCreateEventGroupStatic() function and is used to store
+ *  // the event group's data structures
+ *  StaticEventGroup_t xEventGroupBuffer;
+ *
+ *  // Create the event group without dynamically allocating any memory.
+ *  xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
+ * @endcode
+ */
+#if ( configSUPPORT_STATIC_ALLOCATION == 1 )
+    EventGroupHandle_t xEventGroupCreateStatic( StaticEventGroup_t * pxEventGroupBuffer );
+#endif
+
+/**
+ * event_groups.h
+ * @code{c}
+ *  EventBits_t xEventGroupWaitBits(    EventGroupHandle_t xEventGroup,
+ *                                      const EventBits_t uxBitsToWaitFor,
+ *                                      const BaseType_t xClearOnExit,
+ *                                      const BaseType_t xWaitForAllBits,
+ *                                      const TickType_t xTicksToWait );
+ * @endcode
+ *
+ * [Potentially] block to wait for one or more bits to be set within a
+ * previously created event group.
+ *
+ * This function cannot be called from an interrupt.
+ *
+ * @param xEventGroup The event group in which the bits are being tested.  The
+ * event group must have previously been created using a call to
+ * xEventGroupCreate().
+ *
+ * @param uxBitsToWaitFor A bitwise value that indicates the bit or bits to test
+ * inside the event group.  For example, to wait for bit 0 and/or bit 2 set
+ * uxBitsToWaitFor to 0x05.  To wait for bits 0 and/or bit 1 and/or bit 2 set
+ * uxBitsToWaitFor to 0x07.  Etc.
+ *
+ * @param xClearOnExit If xClearOnExit is set to pdTRUE then any bits within
+ * uxBitsToWaitFor that are set within the event group will be cleared before
+ * xEventGroupWaitBits() returns if the wait condition was met (if the function
+ * returns for a reason other than a timeout).  If xClearOnExit is set to
+ * pdFALSE then the bits set in the event group are not altered when the call to
+ * xEventGroupWaitBits() returns.
+ *
+ * @param xWaitForAllBits If xWaitForAllBits is set to pdTRUE then
+ * xEventGroupWaitBits() will return when either all the bits in uxBitsToWaitFor
+ * are set or the specified block time expires.  If xWaitForAllBits is set to
+ * pdFALSE then xEventGroupWaitBits() will return when any one of the bits set
+ * in uxBitsToWaitFor is set or the specified block time expires.  The block
+ * time is specified by the xTicksToWait parameter.
+ *
+ * @param xTicksToWait The maximum amount of time (specified in 'ticks') to wait
+ * for one/all (depending on the xWaitForAllBits value) of the bits specified by
+ * uxBitsToWaitFor to become set.
+ *
+ * @return The value of the event group at the time either the bits being waited
+ * for became set, or the block time expired.  Test the return value to know
+ * which bits were set.  If xEventGroupWaitBits() returned because its timeout
+ * expired then not all the bits being waited for will be set.  If
+ * xEventGroupWaitBits() returned because the bits it was waiting for were set
+ * then the returned value is the event group value before any bits were
+ * automatically cleared in the case that xClearOnExit parameter was set to
+ * pdTRUE.
+ *
+ * Example usage:
+ * @code{c}
+ * #define BIT_0 ( 1 << 0 )
+ * #define BIT_4 ( 1 << 4 )
+ *
+ * void aFunction( EventGroupHandle_t xEventGroup )
+ * {
+ * EventBits_t uxBits;
+ * const TickType_t xTicksToWait = 100 / portTICK_PERIOD_MS;
+ *
+ *      // Wait a maximum of 100ms for either bit 0 or bit 4 to be set within
+ *      // the event group.  Clear the bits before exiting.
+ *      uxBits = xEventGroupWaitBits(
+ *                  xEventGroup,    // The event group being tested.
+ *                  BIT_0 | BIT_4,  // The bits within the event group to wait for.
+ *                  pdTRUE,         // BIT_0 and BIT_4 should be cleared before returning.
+ *                  pdFALSE,        // Don't wait for both bits, either bit will do.
+ *                  xTicksToWait ); // Wait a maximum of 100ms for either bit to be set.
+ *
+ *      if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
+ *      {
+ *          // xEventGroupWaitBits() returned because both bits were set.
+ *      }
+ *      else if( ( uxBits & BIT_0 ) != 0 )
+ *      {
+ *          // xEventGroupWaitBits() returned because just BIT_0 was set.
+ *      }
+ *      else if( ( uxBits & BIT_4 ) != 0 )
+ *      {
+ *          // xEventGroupWaitBits() returned because just BIT_4 was set.
+ *      }
+ *      else
+ *      {
+ *          // xEventGroupWaitBits() returned because xTicksToWait ticks passed
+ *          // without either BIT_0 or BIT_4 becoming set.
+ *      }
+ * }
+ * @endcode
+ * \defgroup xEventGroupWaitBits xEventGroupWaitBits
+ * \ingroup EventGroup
+ */
+EventBits_t xEventGroupWaitBits( EventGroupHandle_t xEventGroup,
+                                 const EventBits_t uxBitsToWaitFor,
+                                 const BaseType_t xClearOnExit,
+                                 const BaseType_t xWaitForAllBits,
+                                 TickType_t xTicksToWait );
+
+/**
+ * event_groups.h
+ * @code{c}
+ *  EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet );
+ * @endcode
+ *
+ * Set bits within an event group.
+ * This function cannot be called from an interrupt.  xEventGroupSetBitsFromISR()
+ * is a version that can be called from an interrupt.
+ *
+ * Setting bits in an event group will automatically unblock tasks that are
+ * blocked waiting for the bits.
+ *
+ * @param xEventGroup The event group in which the bits are to be set.
+ *
+ * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
+ * For example, to set bit 3 only, set uxBitsToSet to 0x08.  To set bit 3
+ * and bit 0 set uxBitsToSet to 0x09.
+ *
+ * @return The value of the event group at the time the call to
+ * xEventGroupSetBits() returns.  There are two reasons why the returned value
+ * might have the bits specified by the uxBitsToSet parameter cleared.  First,
+ * if setting a bit results in a task that was waiting for the bit leaving the
+ * blocked state then it is possible the bit will be cleared automatically
+ * (see the xClearBitOnExit parameter of xEventGroupWaitBits()).  Second, any
+ * unblocked (or otherwise Ready state) task that has a priority above that of
+ * the task that called xEventGroupSetBits() will execute and may change the
+ * event group value before the call to xEventGroupSetBits() returns.
+ *
+ * Example usage:
+ * @code{c}
+ * #define BIT_0 ( 1 << 0 )
+ * #define BIT_4 ( 1 << 4 )
+ *
+ * void aFunction( EventGroupHandle_t xEventGroup )
+ * {
+ * EventBits_t uxBits;
+ *
+ *      // Set bit 0 and bit 4 in xEventGroup.
+ *      uxBits = xEventGroupSetBits(
+ *                          xEventGroup,    // The event group being updated.
+ *                          BIT_0 | BIT_4 );// The bits being set.
+ *
+ *      if( ( uxBits & ( BIT_0 | BIT_4 ) ) == ( BIT_0 | BIT_4 ) )
+ *      {
+ *          // Both bit 0 and bit 4 remained set when the function returned.
+ *      }
+ *      else if( ( uxBits & BIT_0 ) != 0 )
+ *      {
+ *          // Bit 0 remained set when the function returned, but bit 4 was
+ *          // cleared.  It might be that bit 4 was cleared automatically as a
+ *          // task that was waiting for bit 4 was removed from the Blocked
+ *          // state.
+ *      }
+ *      else if( ( uxBits & BIT_4 ) != 0 )
+ *      {
+ *          // Bit 4 remained set when the function returned, but bit 0 was
+ *          // cleared.  It might be that bit 0 was cleared automatically as a
+ *          // task that was waiting for bit 0 was removed from the Blocked
+ *          // state.
+ *      }
+ *      else
+ *      {
+ *          // Neither bit 0 nor bit 4 remained set.  It might be that a task
+ *          // was waiting for both of the bits to be set, and the bits were
+ *          // cleared as the task left the Blocked state.
+ *      }
+ * }
+ * @endcode
+ * \defgroup xEventGroupSetBits xEventGroupSetBits
+ * \ingroup EventGroup
+ */
+EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
+                                const EventBits_t uxBitsToSet );
+
+/**
+ * event_groups.h
+ * @code{c}
+ *  BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, BaseType_t *pxHigherPriorityTaskWoken );
+ * @endcode
+ *
+ * A version of xEventGroupSetBits() that can be called from an interrupt.
+ *
+ * Setting bits in an event group is not a deterministic operation because there
+ * are an unknown number of tasks that may be waiting for the bit or bits being
+ * set.  FreeRTOS does not allow nondeterministic operations to be performed in
+ * interrupts or from critical sections.  Therefore xEventGroupSetBitsFromISR()
+ * sends a message to the timer task to have the set operation performed in the
+ * context of the timer task - where a scheduler lock is used in place of a
+ * critical section.
+ *
+ * @param xEventGroup The event group in which the bits are to be set.
+ *
+ * @param uxBitsToSet A bitwise value that indicates the bit or bits to set.
+ * For example, to set bit 3 only, set uxBitsToSet to 0x08.  To set bit 3
+ * and bit 0 set uxBitsToSet to 0x09.
+ *
+ * @param pxHigherPriorityTaskWoken As mentioned above, calling this function
+ * will result in a message being sent to the timer daemon task.  If the
+ * priority of the timer daemon task is higher than the priority of the
+ * currently running task (the task the interrupt interrupted) then
+ * *pxHigherPriorityTaskWoken will be set to pdTRUE by
+ * xEventGroupSetBitsFromISR(), indicating that a context switch should be
+ * requested before the interrupt exits.  For that reason
+ * *pxHigherPriorityTaskWoken must be initialised to pdFALSE.  See the
+ * example code below.
+ *
+ * @return If the request to execute the function was posted successfully then
+ * pdPASS is returned, otherwise pdFALSE is returned.  pdFALSE will be returned
+ * if the timer service queue was full.
+ *
+ * Example usage:
+ * @code{c}
+ * #define BIT_0 ( 1 << 0 )
+ * #define BIT_4 ( 1 << 4 )
+ *
+ * // An event group which it is assumed has already been created by a call to
+ * // xEventGroupCreate().
+ * EventGroupHandle_t xEventGroup;
+ *
+ * void anInterruptHandler( void )
+ * {
+ * BaseType_t xHigherPriorityTaskWoken, xResult;
+ *
+ *      // xHigherPriorityTaskWoken must be initialised to pdFALSE.
+ *      xHigherPriorityTaskWoken = pdFALSE;
+ *
+ *      // Set bit 0 and bit 4 in xEventGroup.
+ *      xResult = xEventGroupSetBitsFromISR(
+ *                          xEventGroup,    // The event group being updated.
+ *                          BIT_0 | BIT_4   // The bits being set.
+ *                          &xHigherPriorityTaskWoken );
+ *
+ *      // Was the message posted successfully?
+ *      if( xResult == pdPASS )
+ *      {
+ *          // If xHigherPriorityTaskWoken is now set to pdTRUE then a context
+ *          // switch should be requested.  The macro used is port specific and
+ *          // will be either portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() -
+ *          // refer to the documentation page for the port being used.
+ *          portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
+ *      }
+ * }
+ * @endcode
+ * \defgroup xEventGroupSetBitsFromISR xEventGroupSetBitsFromISR
+ * \ingroup EventGroup
+ */
+BaseType_t xEventGroupSetBitsFromISR( EventGroupHandle_t xEventGroup,
+                                      const EventBits_t uxBitsToSet,
+                                      BaseType_t * pxHigherPriorityTaskWoken );
+
+/**
+ * event_groups.h
+ * @code{c}
+ *  void xEventGroupDelete( EventGroupHandle_t xEventGroup );
+ * @endcode
+ *
+ * Delete an event group that was previously created by a call to
+ * xEventGroupCreate().  Tasks that are blocked on the event group will be
+ * unblocked and obtain 0 as the event group's value.
+ *
+ * @param xEventGroup The event group being deleted.
+ */
+void vEventGroupDelete( EventGroupHandle_t xEventGroup );
+
+/* *INDENT-OFF* */
+#ifdef __cplusplus
+    }
+#endif
+/* *INDENT-ON* */
+
+#endif /* EVENT_GROUPS_H */

test/test_event_group_dynamic.c

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2006-2022, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2018-08-24     yangjie      the first version
+ * 2020-10-17     Meco Man     translate to English comment
+ */
+
+/*
+ * Demo: event group
+ *
+ * This demo demonstrates dynamically creating an event group and using it to send events between two tasks.
+ *
+ */
+
+#include <FreeRTOS.h>
+#include <event_groups.h>
+#include <task.h>
+
+#define TASK_PRIORITY         8
+#define BIT_0                 ( 1 << 0 )
+#define BIT_4                 ( 1 << 4 )
+
+/* mutex handler */
+static EventGroupHandle_t xEventGroup = NULL;
+static TaskHandle_t TaskHandle1 = NULL;
+static TaskHandle_t TaskHandle2 = NULL;
+
+static void vTask1Code(void *pvParameters)
+{
+    while (1)
+    {
+        EventBits_t uxBits;
+        // Wait for either bit 0 or bit 4, clear bit before return
+        uxBits = xEventGroupWaitBits(xEventGroup, BIT_0 | BIT_4, pdTRUE, pdFALSE, portMAX_DELAY);
+        if ((uxBits & BIT_0) != 0)
+        {
+            rt_kprintf("Task 1 received bit 0\n");
+        }
+        if ((uxBits & BIT_4) != 0)
+        {
+            rt_kprintf("Task 1 received bit 4\n");
+        }
+    }
+}
+
+static void vTask2Code(void * pvParameters)
+{
+    while (1)
+    {
+        rt_kprintf("Task 2 send bit 0\n");
+        xEventGroupSetBits(xEventGroup, BIT_0);
+        vTaskDelay(pdMS_TO_TICKS(1000));
+        rt_kprintf("Task 2 send bit 4\n");
+        xEventGroupSetBits(xEventGroup, BIT_4);
+        vTaskDelay(pdMS_TO_TICKS(1000));
+    }
+}
+
+int event_group_dynamic(void)
+{
+    xEventGroup = xEventGroupCreate();
+    xEventGroupDelete(xEventGroup);
+    xEventGroup = xEventGroupCreate();
+    if (xEventGroup == NULL)
+    {
+        rt_kprintf("create event group failed.\n");
+        return -1;
+    }
+    xTaskCreate( vTask1Code, "Task1", configMINIMAL_STACK_SIZE, NULL, TASK_PRIORITY - 1, &TaskHandle1 );
+    if (TaskHandle1 == NULL)
+    {
+        rt_kprintf("Create task 1 failed\n");
+        return -1;
+    }
+    xTaskCreate( vTask2Code, "Task2", configMINIMAL_STACK_SIZE, NULL, TASK_PRIORITY, &TaskHandle2 );
+    if (TaskHandle2 == NULL)
+    {
+        rt_kprintf("Create task 2 failed\n");
+        return -1;
+    }
+
+    return 0;
+}
+
+MSH_CMD_EXPORT(event_group_dynamic, event group sample);

test/test_event_group_static.c

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2006-2022, RT-Thread Development Team
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Change Logs:
+ * Date           Author       Notes
+ * 2018-08-24     yangjie      the first version
+ * 2020-10-17     Meco Man     translate to English comment
+ */
+
+/*
+ * Demo: event group
+ *
+ * This demo demonstrates statically creating an event group and using it to send events between two tasks.
+ *
+ */
+
+#include <FreeRTOS.h>
+#include <event_groups.h>
+#include <task.h>
+
+#define TASK_PRIORITY         8
+#define BIT_0                 ( 1 << 0 )
+#define BIT_4                 ( 1 << 4 )
+
+static EventGroupHandle_t xEventGroup = NULL;
+static StaticEventGroup_t xEventGroupBuffer;
+static TaskHandle_t TaskHandle1 = NULL;
+static TaskHandle_t TaskHandle2 = NULL;
+
+static void vTask1Code(void *pvParameters)
+{
+    while (1)
+    {
+        EventBits_t uxBits;
+        // Wait for both bit 0 and bit 4, clear bit before return
+        uxBits = xEventGroupWaitBits(xEventGroup, BIT_0 | BIT_4, pdTRUE, pdTRUE, portMAX_DELAY);
+        if ((uxBits & BIT_0) != 0)
+        {
+            rt_kprintf("Task 1 received bit 0\n");
+        }
+        if ((uxBits & BIT_4) != 0)
+        {
+            rt_kprintf("Task 1 received bit 4\n");
+        }
+    }
+}
+
+static void vTask2Code(void * pvParameters)
+{
+    while (1)
+    {
+        rt_kprintf("Task 2 send bit 0\n");
+        xEventGroupSetBits(xEventGroup, BIT_0);
+        vTaskDelay(pdMS_TO_TICKS(1000));
+        rt_kprintf("Task 2 send bit 4\n");
+        xEventGroupSetBits(xEventGroup, BIT_4);
+        vTaskDelay(pdMS_TO_TICKS(1000));
+    }
+}
+
+int event_group_static(void)
+{
+    xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
+    xEventGroupDelete(xEventGroup);
+    xEventGroup = xEventGroupCreateStatic( &xEventGroupBuffer );
+    if (xEventGroup == NULL)
+    {
+        rt_kprintf("create event group failed.\n");
+        return -1;
+    }
+    xTaskCreate( vTask1Code, "Task1", configMINIMAL_STACK_SIZE, NULL, TASK_PRIORITY - 1, &TaskHandle1 );
+    if (TaskHandle1 == NULL)
+    {
+        rt_kprintf("Create task 1 failed\n");
+        return -1;
+    }
+    xTaskCreate( vTask2Code, "Task2", configMINIMAL_STACK_SIZE, NULL, TASK_PRIORITY, &TaskHandle2 );
+    if (TaskHandle2 == NULL)
+    {
+        rt_kprintf("Create task 2 failed\n");
+        return -1;
+    }
+
+    return 0;
+}
+
+MSH_CMD_EXPORT(event_group_static, event group sample);