event_groups.h File Reference

#include "timers.h"

Go to the source code of this file.

Macros
#define	xEventGroupClearBitsFromISR(xEventGroup, uxBitsToClear)   xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL )
#define	xEventGroupSetBitsFromISR(xEventGroup, uxBitsToSet, pxHigherPriorityTaskWoken)   xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken )
#define	xEventGroupGetBits(xEventGroup)   xEventGroupClearBits( xEventGroup, 0 )

Typedefs
typedef void *	EventGroupHandle_t
typedef TickType_t	EventBits_t

Functions
PRIVILEGED_FUNCTION EventBits_t	xEventGroupWaitBits (EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToWaitFor, const BaseType_t xClearOnExit, const BaseType_t xWaitForAllBits, TickType_t xTicksToWait)
PRIVILEGED_FUNCTION EventBits_t	xEventGroupClearBits (EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToClear)
PRIVILEGED_FUNCTION EventBits_t	xEventGroupSetBits (EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet)
PRIVILEGED_FUNCTION EventBits_t	xEventGroupSync (EventGroupHandle_t xEventGroup, const EventBits_t uxBitsToSet, const EventBits_t uxBitsToWaitFor, TickType_t xTicksToWait)
PRIVILEGED_FUNCTION EventBits_t	xEventGroupGetBitsFromISR (EventGroupHandle_t xEventGroup)
PRIVILEGED_FUNCTION void	vEventGroupDelete (EventGroupHandle_t xEventGroup)
PRIVILEGED_FUNCTION void	vEventGroupSetBitsCallback (void *pvEventGroup, const uint32_t ulBitsToSet)
PRIVILEGED_FUNCTION void	vEventGroupClearBitsCallback (void *pvEventGroup, const uint32_t ulBitsToClear)

Macro Definition Documentation

xEventGroupClearBitsFromISR

#define xEventGroupClearBitsFromISR	(		xEventGroup,
			uxBitsToClear
	)		xTimerPendFunctionCallFromISR( vEventGroupClearBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToClear, NULL )

xEventGroupSetBitsFromISR

#define xEventGroupSetBitsFromISR	(		xEventGroup,
			uxBitsToSet,
			pxHigherPriorityTaskWoken
	)		xTimerPendFunctionCallFromISR( vEventGroupSetBitsCallback, ( void * ) xEventGroup, ( uint32_t ) uxBitsToSet, pxHigherPriorityTaskWoken )

xEventGroupGetBits

#define xEventGroupGetBits

(

xEventGroup

)

xEventGroupClearBits( xEventGroup, 0 )

Typedef Documentation

EventGroupHandle_t

typedef void* EventGroupHandle_t

EventBits_t

typedef TickType_t EventBits_t

Function Documentation

xEventGroupWaitBits()

PRIVILEGED_FUNCTION EventBits_t xEventGroupWaitBits	(	EventGroupHandle_t	xEventGroup,
		const EventBits_t	uxBitsToWaitFor,
		const BaseType_t	xClearOnExit,
		const BaseType_t	xWaitForAllBits,
		TickType_t	xTicksToWait
	)

{
EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
EventBits_t uxReturn, uxControlBits = 0;
BaseType_t xWaitConditionMet, xAlreadyYielded;
BaseType_t xTimeoutOccurred = pdFALSE;
 
    /* 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 & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
    configASSERT( uxBitsToWaitFor != 0 );
    #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
    {
        configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
    }
    #endif
 
    vTaskSuspendAll();
    {
        const EventBits_t uxCurrentEventBits = pxEventBits->uxEventBits;
 
        /* Check to see if the wait condition is already met or not. */
        xWaitConditionMet = prvTestWaitCondition( uxCurrentEventBits, uxBitsToWaitFor, xWaitForAllBits );
 
        if( xWaitConditionMet != pdFALSE )
        {
            /* The wait condition has already been met so there is no need to
            block. */
            uxReturn = uxCurrentEventBits;
            xTicksToWait = ( TickType_t ) 0;
 
            /* Clear the wait bits if requested to do so. */
            if( xClearOnExit != pdFALSE )
            {
                pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
            }
            else
            {
                mtCOVERAGE_TEST_MARKER();
            }
        }
        else if( xTicksToWait == ( TickType_t ) 0 )
        {
            /* The wait condition has not been met, but no block time was
            specified, so just return the current value. */
            uxReturn = uxCurrentEventBits;
        }
        else
        {
            /* The task is going to block to wait for its required bits to be
            set.  uxControlBits are used to remember the specified behaviour of
            this call to xEventGroupWaitBits() - for use when the event bits
            unblock the task. */
            if( xClearOnExit != pdFALSE )
            {
                uxControlBits |= eventCLEAR_EVENTS_ON_EXIT_BIT;
            }
            else
            {
                mtCOVERAGE_TEST_MARKER();
            }
 
            if( xWaitForAllBits != pdFALSE )
            {
                uxControlBits |= eventWAIT_FOR_ALL_BITS;
            }
            else
            {
                mtCOVERAGE_TEST_MARKER();
            }
 
            /* Store the bits that the calling task is waiting for in the
            task's event list item so the kernel knows when a match is
            found.  Then enter the blocked state. */
            vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | uxControlBits ), xTicksToWait );
 
            /* This is obsolete as it will get set after the task unblocks, but
            some compilers mistakenly generate a warning about the variable
            being returned without being set if it is not done. */
            uxReturn = 0;
 
            traceEVENT_GROUP_WAIT_BITS_BLOCK( xEventGroup, uxBitsToWaitFor );
        }
    }
    xAlreadyYielded = xTaskResumeAll();
 
    if( xTicksToWait != ( TickType_t ) 0 )
    {
        if( xAlreadyYielded == pdFALSE )
        {
            portYIELD_WITHIN_API();
        }
        else
        {
            mtCOVERAGE_TEST_MARKER();
        }
 
        /* The task blocked to wait for its required bits to be set - at this
        point either the required bits were set or the block time expired.  If
        the required bits were set they will have been stored in the task's
        event list item, and they should now be retrieved then cleared. */
        uxReturn = uxTaskResetEventItemValue();
 
        if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
        {
            taskENTER_CRITICAL();
            {
                /* The task timed out, just return the current event bit value. */
                uxReturn = pxEventBits->uxEventBits;
 
                /* It is possible that the event bits were updated between this
                task leaving the Blocked state and running again. */
                if( prvTestWaitCondition( uxReturn, uxBitsToWaitFor, xWaitForAllBits ) != pdFALSE )
                {
                    if( xClearOnExit != pdFALSE )
                    {
                        pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
                    }
                    else
                    {
                        mtCOVERAGE_TEST_MARKER();
                    }
                }
                else
                {
                    mtCOVERAGE_TEST_MARKER();
                }
            }
            taskEXIT_CRITICAL();
 
            /* Prevent compiler warnings when trace macros are not used. */
            xTimeoutOccurred = pdFALSE;
        }
        else
        {
            /* The task unblocked because the bits were set. */
        }
 
        /* The task blocked so control bits may have been set. */
        uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
    }
    traceEVENT_GROUP_WAIT_BITS_END( xEventGroup, uxBitsToWaitFor, xTimeoutOccurred );
 
    return uxReturn;
}

Here is the call graph for this function:

xEventGroupClearBits()

PRIVILEGED_FUNCTION EventBits_t xEventGroupClearBits	(	EventGroupHandle_t	xEventGroup,
		const EventBits_t	uxBitsToClear
	)

{
EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
EventBits_t uxReturn;
 
    /* Check the user is not attempting to clear the bits used by the kernel
    itself. */
    configASSERT( xEventGroup );
    configASSERT( ( uxBitsToClear & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
 
    taskENTER_CRITICAL();
    {
        traceEVENT_GROUP_CLEAR_BITS( xEventGroup, uxBitsToClear );
 
        /* The value returned is the event group value prior to the bits being
        cleared. */
        uxReturn = pxEventBits->uxEventBits;
 
        /* Clear the bits. */
        pxEventBits->uxEventBits &= ~uxBitsToClear;
    }
    taskEXIT_CRITICAL();
 
    return uxReturn;
}

Here is the caller graph for this function:

xEventGroupSetBits()

PRIVILEGED_FUNCTION EventBits_t xEventGroupSetBits	(	EventGroupHandle_t	xEventGroup,
		const EventBits_t	uxBitsToSet
	)

{
ListItem_t *pxListItem, *pxNext;
ListItem_t const *pxListEnd;
List_t *pxList;
EventBits_t uxBitsToClear = 0, uxBitsWaitedFor, uxControlBits;
EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
BaseType_t xMatchFound = pdFALSE;
 
    /* Check the user is not attempting to set the bits used by the kernel
    itself. */
    configASSERT( xEventGroup );
    configASSERT( ( uxBitsToSet & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
 
    pxList = &( pxEventBits->xTasksWaitingForBits );
    pxListEnd = listGET_END_MARKER( pxList ); /*lint !e826 !e740 The mini list structure is used as the list end to save RAM.  This is checked and valid. */
    vTaskSuspendAll();
    {
        traceEVENT_GROUP_SET_BITS( xEventGroup, uxBitsToSet );
 
        pxListItem = listGET_HEAD_ENTRY( pxList );
 
        /* Set the bits. */
        pxEventBits->uxEventBits |= uxBitsToSet;
 
        /* See if the new bit value should unblock any tasks. */
        while( pxListItem != pxListEnd )
        {
            pxNext = listGET_NEXT( pxListItem );
            uxBitsWaitedFor = listGET_LIST_ITEM_VALUE( pxListItem );
            xMatchFound = pdFALSE;
 
            /* Split the bits waited for from the control bits. */
            uxControlBits = uxBitsWaitedFor & eventEVENT_BITS_CONTROL_BYTES;
            uxBitsWaitedFor &= ~eventEVENT_BITS_CONTROL_BYTES;
 
            if( ( uxControlBits & eventWAIT_FOR_ALL_BITS ) == ( EventBits_t ) 0 )
            {
                /* Just looking for single bit being set. */
                if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) != ( EventBits_t ) 0 )
                {
                    xMatchFound = pdTRUE;
                }
                else
                {
                    mtCOVERAGE_TEST_MARKER();
                }
            }
            else if( ( uxBitsWaitedFor & pxEventBits->uxEventBits ) == uxBitsWaitedFor )
            {
                /* All bits are set. */
                xMatchFound = pdTRUE;
            }
            else
            {
                /* Need all bits to be set, but not all the bits were set. */
            }
 
            if( xMatchFound != pdFALSE )
            {
                /* The bits match.  Should the bits be cleared on exit? */
                if( ( uxControlBits & eventCLEAR_EVENTS_ON_EXIT_BIT ) != ( EventBits_t ) 0 )
                {
                    uxBitsToClear |= uxBitsWaitedFor;
                }
                else
                {
                    mtCOVERAGE_TEST_MARKER();
                }
 
                /* Store the actual event flag value in the task's event list
                item before removing the task from the event list.  The
                eventUNBLOCKED_DUE_TO_BIT_SET bit is set so the task knows
                that is was unblocked due to its required bits matching, rather
                than because it timed out. */
                ( void ) xTaskRemoveFromUnorderedEventList( pxListItem, pxEventBits->uxEventBits | eventUNBLOCKED_DUE_TO_BIT_SET );
            }
 
            /* Move onto the next list item.  Note pxListItem->pxNext is not
            used here as the list item may have been removed from the event list
            and inserted into the ready/pending reading list. */
            pxListItem = pxNext;
        }
 
        /* Clear any bits that matched when the eventCLEAR_EVENTS_ON_EXIT_BIT
        bit was set in the control word. */
        pxEventBits->uxEventBits &= ~uxBitsToClear;
    }
    ( void ) xTaskResumeAll();
 
    return pxEventBits->uxEventBits;
}

Here is the call graph for this function:

Here is the caller graph for this function:

xEventGroupSync()

PRIVILEGED_FUNCTION EventBits_t xEventGroupSync	(	EventGroupHandle_t	xEventGroup,
		const EventBits_t	uxBitsToSet,
		const EventBits_t	uxBitsToWaitFor,
		TickType_t	xTicksToWait
	)

{
EventBits_t uxOriginalBitValue, uxReturn;
EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
BaseType_t xAlreadyYielded;
BaseType_t xTimeoutOccurred = pdFALSE;
 
    configASSERT( ( uxBitsToWaitFor & eventEVENT_BITS_CONTROL_BYTES ) == 0 );
    configASSERT( uxBitsToWaitFor != 0 );
    #if ( ( INCLUDE_xTaskGetSchedulerState == 1 ) || ( configUSE_TIMERS == 1 ) )
    {
        configASSERT( !( ( xTaskGetSchedulerState() == taskSCHEDULER_SUSPENDED ) && ( xTicksToWait != 0 ) ) );
    }
    #endif
 
    vTaskSuspendAll();
    {
        uxOriginalBitValue = pxEventBits->uxEventBits;
 
        ( void ) xEventGroupSetBits( xEventGroup, uxBitsToSet );
 
        if( ( ( uxOriginalBitValue | uxBitsToSet ) & uxBitsToWaitFor ) == uxBitsToWaitFor )
        {
            /* All the rendezvous bits are now set - no need to block. */
            uxReturn = ( uxOriginalBitValue | uxBitsToSet );
 
            /* Rendezvous always clear the bits.  They will have been cleared
            already unless this is the only task in the rendezvous. */
            pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
 
            xTicksToWait = 0;
        }
        else
        {
            if( xTicksToWait != ( TickType_t ) 0 )
            {
                traceEVENT_GROUP_SYNC_BLOCK( xEventGroup, uxBitsToSet, uxBitsToWaitFor );
 
                /* Store the bits that the calling task is waiting for in the
                task's event list item so the kernel knows when a match is
                found.  Then enter the blocked state. */
                vTaskPlaceOnUnorderedEventList( &( pxEventBits->xTasksWaitingForBits ), ( uxBitsToWaitFor | eventCLEAR_EVENTS_ON_EXIT_BIT | eventWAIT_FOR_ALL_BITS ), xTicksToWait );
 
                /* This assignment is obsolete as uxReturn will get set after
                the task unblocks, but some compilers mistakenly generate a
                warning about uxReturn being returned without being set if the
                assignment is omitted. */
                uxReturn = 0;
            }
            else
            {
                /* The rendezvous bits were not set, but no block time was
                specified - just return the current event bit value. */
                uxReturn = pxEventBits->uxEventBits;
            }
        }
    }
    xAlreadyYielded = xTaskResumeAll();
 
    if( xTicksToWait != ( TickType_t ) 0 )
    {
        if( xAlreadyYielded == pdFALSE )
        {
            portYIELD_WITHIN_API();
        }
        else
        {
            mtCOVERAGE_TEST_MARKER();
        }
 
        /* The task blocked to wait for its required bits to be set - at this
        point either the required bits were set or the block time expired.  If
        the required bits were set they will have been stored in the task's
        event list item, and they should now be retrieved then cleared. */
        uxReturn = uxTaskResetEventItemValue();
 
        if( ( uxReturn & eventUNBLOCKED_DUE_TO_BIT_SET ) == ( EventBits_t ) 0 )
        {
            /* The task timed out, just return the current event bit value. */
            taskENTER_CRITICAL();
            {
                uxReturn = pxEventBits->uxEventBits;
 
                /* Although the task got here because it timed out before the
                bits it was waiting for were set, it is possible that since it
                unblocked another task has set the bits.  If this is the case
                then it needs to clear the bits before exiting. */
                if( ( uxReturn & uxBitsToWaitFor ) == uxBitsToWaitFor )
                {
                    pxEventBits->uxEventBits &= ~uxBitsToWaitFor;
                }
                else
                {
                    mtCOVERAGE_TEST_MARKER();
                }
            }
            taskEXIT_CRITICAL();
 
            xTimeoutOccurred = pdTRUE;
        }
        else
        {
            /* The task unblocked because the bits were set. */
        }
 
        /* Control bits might be set as the task had blocked should not be
        returned. */
        uxReturn &= ~eventEVENT_BITS_CONTROL_BYTES;
    }
 
    traceEVENT_GROUP_SYNC_END( xEventGroup, uxBitsToSet, uxBitsToWaitFor, xTimeoutOccurred );
 
    return uxReturn;
}

Here is the call graph for this function:

xEventGroupGetBitsFromISR()

PRIVILEGED_FUNCTION EventBits_t xEventGroupGetBitsFromISR

(

EventGroupHandle_t

xEventGroup

)

{
UBaseType_t uxSavedInterruptStatus;
EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
EventBits_t uxReturn;
 
    uxSavedInterruptStatus = portSET_INTERRUPT_MASK_FROM_ISR();
    {
        uxReturn = pxEventBits->uxEventBits;
    }
    portCLEAR_INTERRUPT_MASK_FROM_ISR( uxSavedInterruptStatus );
 
    return uxReturn;
}

vEventGroupDelete()

PRIVILEGED_FUNCTION void vEventGroupDelete

(

EventGroupHandle_t

xEventGroup

)

event_groups.h

   void xEventGroupDelete( EventGroupHandle_t xEventGroup );

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.

Parameters

xEventGroup

The event group being deleted.

{
EventGroup_t *pxEventBits = ( EventGroup_t * ) xEventGroup;
const List_t *pxTasksWaitingForBits = &( pxEventBits->xTasksWaitingForBits );
 
    vTaskSuspendAll();
    {
        traceEVENT_GROUP_DELETE( xEventGroup );
 
        while( listCURRENT_LIST_LENGTH( pxTasksWaitingForBits ) > ( UBaseType_t ) 0 )
        {
            /* Unblock the task, returning 0 as the event list is being deleted
            and cannot therefore have any bits set. */
            configASSERT( pxTasksWaitingForBits->xListEnd.pxNext != ( ListItem_t * ) &( pxTasksWaitingForBits->xListEnd ) );
            ( void ) xTaskRemoveFromUnorderedEventList( pxTasksWaitingForBits->xListEnd.pxNext, eventUNBLOCKED_DUE_TO_BIT_SET );
        }
 
        #if( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 0 ) )
        {
            /* The event group can only have been allocated dynamically - free
            it again. */
            vPortFree( pxEventBits );
        }
        #elif( ( configSUPPORT_DYNAMIC_ALLOCATION == 1 ) && ( configSUPPORT_STATIC_ALLOCATION == 1 ) )
        {
            /* The event group could have been allocated statically or
            dynamically, so check before attempting to free the memory. */
            if( pxEventBits->ucStaticallyAllocated == ( uint8_t ) pdFALSE )
            {
                vPortFree( pxEventBits );
            }
            else
            {
                mtCOVERAGE_TEST_MARKER();
            }
        }
        #endif /* configSUPPORT_DYNAMIC_ALLOCATION */
    }
    ( void ) xTaskResumeAll();
}

Here is the call graph for this function:

vEventGroupSetBitsCallback()

PRIVILEGED_FUNCTION void vEventGroupSetBitsCallback	(	void *	pvEventGroup,
		const uint32_t	ulBitsToSet
	)

{
    ( void ) xEventGroupSetBits( pvEventGroup, ( EventBits_t ) ulBitsToSet );
}

Here is the call graph for this function:

vEventGroupClearBitsCallback()

PRIVILEGED_FUNCTION void vEventGroupClearBitsCallback	(	void *	pvEventGroup,
		const uint32_t	ulBitsToClear
	)

{
    ( void ) xEventGroupClearBits( pvEventGroup, ( EventBits_t ) ulBitsToClear );
}

Here is the call graph for this function: