Event

Features Supported

  • APIs to construct and destruct Events

  • APIs to set, get or clear bits and wait for bits

Features NOT Supported

  • These APIs are not implemented for NO RTOS. Error will be returned if these APIs called using NO RTOS.

Important Usage Guidelines

  • EventP_waitBits should not be called within ISR context. It can be called from task context.

  • Setting or clearing the Event bits is a non-deterministic operation and FreeRTOS does not allow non-deterministic operations to be performed in interrupts or from critical sections. If EventP_setBits or EventP_clearBits is called from an ISR, a message is sent to RTOS daemon task to perform the operation in the context of daemon task. If the set or clear operation is required to be completed immediately, then the priority of RTOS daemon task must be higher than the priority of task waiting for the Event bits. The priority of RTOS daemon task is set by the configTIMER_TASK_PRIORITY in FreeRTOSConfig.h file.

  • The actual current value of Event bits returned from EventP_waitBits and EventP_getBits can be different from returned value if an interrupt or a higher priority task modifies the value between the calling task leaving blocked state and exiting this API.

Example Usage

Include the below file to access the APIs


//! [include]
#include <kernel/dpl/EventP.h>
#include <kernel/dpl/DebugP.h>
//! [include]

//! [define]
/* Event objects, typically these are global's */
EventP_Object gMyEvent;

Example usage to define an Event:

/* Event bit mask upto 24 bits */
#define EVENT_BIT_PING (0x000001u)
#define EVENT_BIT_PONG (0x000002u)
//! [define]

void create(void *args)
{
    int32_t status;
//! [create]
    status = EventP_construct(&gMyEvent);
    DebugP_assert(SystemP_SUCCESS == status);
//! [create]
}

Example usage to create an Event:

void task1(void *args)
{
    int32_t status;
    uint32_t eventBits;

    /* Set PING bit from task1 */
    status = EventP_setBits(&gMyEvent, EVENT_BIT_PING);
    DebugP_assert(SystemP_SUCCESS == status);

    /* Reading the Event Bits */
    status = EventP_getBits(&gMyEvent, &eventBits);
    DebugP_assert(SystemP_SUCCESS == status);

    /* Wait for PONG but to be set from task2. PING bit was already set */

Example usage to set and wait for bits across two tasks:

    DebugP_assert(SystemP_SUCCESS == status);

    /* Clearing the PING and PONG bits */
    status = EventP_clearBits(&gMyEvent, (EVENT_BIT_PING | EVENT_BIT_PONG));
    DebugP_assert(SystemP_SUCCESS == status);
}
//! [task1]


//! [task2]
void task2(void *args)
{
    int32_t status;
    uint32_t eventBits;

API Reference

Defines

EventP_OBJECT_SIZE_MAX

Max size of Event object across no-RTOS and all OS’s.

Functions

int32_t EventP_construct(EventP_Object *obj)

Create an Event object.

Parameters:

obj – [out] Created Event object

Returns:

SystemP_SUCCESS on success, SystemP_FAILURE on error

void EventP_destruct(EventP_Object *obj)

Cleanup, delete, destruct an Event object.

Parameters:

obj – [in] Event object

int32_t EventP_waitBits(EventP_Object *obj, uint32_t bitsToWaitFor, uint8_t clearOnExit, uint8_t waitForAll, uint32_t timeToWaitInTicks, uint32_t *eventBits)

Read the Event bits, after optionally waiting for a bit or multiple bits to be set.

Note

This function should not be called from an interrupt.

Note

The actual current value of Event bits can be different from returned value if an interrupt or a higher priority task modifies the value between the calling task leaving blocked state and exiting this API.

Parameters:

  • obj – [in] Event object

  • bitsToWaitFor – [in] Bitwise value indicating the bits to be tested

  • clearOnExit –

    [in] If this parameter is 1, then any bits set in the value passed in bitsToWaitFor will be cleared before this API returns. If there is a time-out based on timeToWaitInTicks parameter, it will not be cleared.

    If this parameter is 0, then none of the bits are altered.

  • waitForAll –

    [in] This parameter is used to specify if the test of bits should be logical AND or logical OR.

    If this parameter is 1, then this API will return when ALL the bits set in bitsToWaitFor are set in the Event bits, or if there is a time-out.

    If this parameter is 0, then this API will return when ANY of the bits set in bitsToWaitFor is set in the Event bits, or if there is a time-out.

  • timeToWaitInTicks – [in] Amount of time to wait for one or all bits from bitsToWaitFor to be set, in units of system ticks (see KERNEL_DPL_CLOCK_PAGE)

  • eventBits – [out]Value of the Event bits when the bits being waited for were set, or the time-out occured.

Returns:

SystemP_SUCCESS on success or time-out

Returns:

SystemP_FAILURE on failure.

int32_t EventP_setBits(EventP_Object *obj, uint32_t bitsToSet)

Setting a bit or multiple bits in the Event bits.

Parameters:

  • obj – [in] Event object

  • bitsToSet – [in] Bitwise value indicating the bits to be set

Returns:

SystemP_SUCCESS on success

Returns:

SystemP_FAILURE on failure

int32_t EventP_clearBits(EventP_Object *obj, uint32_t bitsToClear)

Clear a bit or multiple bits in the Event bits.

Parameters:

  • obj – [in] Event object

  • bitsToClear – [in] Bitwise value indicating the bits to be cleared

Returns:

SystemP_SUCCESS on success

Returns:

SystemP_FAILURE on failure

int32_t EventP_getBits(EventP_Object *obj, uint32_t *eventBits)

Getting the current value of Event bits.

Note

The actual current value of Event bits can be different from returned value if an interrupt or a higher priority task modifies the value between the calling task leaving blocked state and exiting this API.

Parameters:

  • obj – [in] Event object

  • eventBits – [out]Value of the Event bits when the bits being waited for were set, or the time-out occured.

Returns:

SystemP_SUCCESS on success.

Returns:

SystemP_FAILURE on failure.

struct EventP_Object
#include <EventP.h>

Opaque Event object used with the Event APIs.

Public Members

uintptr_t rsv[EventP_OBJECT_SIZE_MAX / sizeof(uint32_t)]

reserved, should NOT be modified by end users