Bit-based event signaling between tasks and ISRs. More...

Collaboration diagram for Event Group:

Macros
#define	OVE_EG_WAIT_ALL 0x01
	Wait flag: block until ALL requested bits are set simultaneously.

#define	OVE_EG_CLEAR_ON_EXIT 0x02
	Wait flag: atomically clear the matched bits on return.

Functions
int	ove_eventgroup_init (ove_eventgroup_t eg, ove_eventgroup_storage_t storage)
	Initialise an event group using caller-provided static storage.

void	ove_eventgroup_deinit (ove_eventgroup_t eg)
	Deinitialise a statically-allocated event group.

int	ove_eventgroup_create (ove_eventgroup_t *eg)
	Allocate and initialise a heap-backed event group.

void	ove_eventgroup_destroy (ove_eventgroup_t eg)
	Destroy a heap-allocated event group.

ove_eventbits_t	ove_eventgroup_set_bits (ove_eventgroup_t eg, ove_eventbits_t bits)
	Set one or more bits in the event group from task context.

ove_eventbits_t	ove_eventgroup_clear_bits (ove_eventgroup_t eg, ove_eventbits_t bits)
	Clear one or more bits in the event group.

int	ove_eventgroup_wait_bits (ove_eventgroup_t eg, ove_eventbits_t bits, uint32_t flags, uint64_t timeout_ns, ove_eventbits_t *result)
	Block until one or all of the requested bits are set.

static int	ove_eventgroup_wait_bits_until (ove_eventgroup_t eg, ove_eventbits_t bits, uint32_t flags, uint64_t deadline_ns, ove_eventbits_t *result)
	Deadline-based variant of ove_eventgroup_wait_bits.

ove_eventbits_t	ove_eventgroup_set_bits_from_isr (ove_eventgroup_t eg, ove_eventbits_t bits)
	Set bits in the event group from an ISR.

ove_eventbits_t	ove_eventgroup_get_bits (ove_eventgroup_t eg)
	Read the current bit value of the event group without blocking.

int	ove_eventgroup_set_notify (ove_eventgroup_t eg, ove_notify_cb cb, void *user_data)
	Register a notify callback fired after every successful set of one or more bits. See `set_notify` family across primitives.

Detailed Description

Bit-based event signaling between tasks and ISRs.

An event group holds a set of binary flags (bits) that tasks can set, clear, and wait on. Multiple tasks may block on the same event group simultaneously, each specifying its own combination of bits and wait semantics via the OVE_EG_WAIT_ALL and OVE_EG_CLEAR_ON_EXIT flags.

Two allocation strategies are supported:

_create() / _destroy() — heap-allocated. Available only when OVE_HEAP_EVENTGROUP is defined (i.e. CONFIG_OVE_ZERO_HEAP is not set).
_init() / _deinit() — caller-supplied storage. Available in both modes. See OVE_EVENTGROUP_DEFINE_STATIC for a one-step static helper.

Note: Requires CONFIG_OVE_EVENTGROUP.

Macro Definition Documentation

◆ OVE_EG_WAIT_ALL

#define OVE_EG_WAIT_ALL 0x01

Wait flag: block until ALL requested bits are set simultaneously.

When passed to ove_eventgroup_wait_bits, the call blocks until every bit in the bits mask is set at the same time. Without this flag the call unblocks when ANY one of the requested bits becomes set.

◆ OVE_EG_CLEAR_ON_EXIT

#define OVE_EG_CLEAR_ON_EXIT 0x02

Wait flag: atomically clear the matched bits on return.

When passed to ove_eventgroup_wait_bits, the bits that satisfied the wait condition are cleared atomically before the function returns. This avoids a separate ove_eventgroup_clear_bits call and prevents races when multiple tasks share an event group.

Function Documentation

◆ ove_eventgroup_init()

int ove_eventgroup_init	(	ove_eventgroup_t *	eg,
		ove_eventgroup_storage_t *	storage
	)

Initialise an event group using caller-provided static storage.

All bits in the new event group are cleared. The caller must ensure that storage remains valid for the lifetime of the event group.

Parameters

[out]	eg	Receives the initialised event group handle.
[in]	storage	Pointer to statically-allocated event group storage.

Returns: OVE_OK on success, negative error code on failure.

Note: Requires CONFIG_OVE_EVENTGROUP.

◆ ove_eventgroup_deinit()

void ove_eventgroup_deinit ( ove_eventgroup_t eg )

Deinitialise a statically-allocated event group.

Releases all RTOS resources associated with eg. Any tasks still blocked in ove_eventgroup_wait_bits will be unblocked with an error.

Parameters

[in] eg Event group handle returned by ove_eventgroup_init.

Note: Requires CONFIG_OVE_EVENTGROUP.

◆ ove_eventgroup_create()

int ove_eventgroup_create ( ove_eventgroup_t * eg )

Allocate and initialise a heap-backed event group.

All bits in the new event group are cleared.

Parameters

[out] eg Receives the created event group handle.

Returns: OVE_OK on success, negative error code on failure.

Note: Requires CONFIG_OVE_EVENTGROUP and OVE_HEAP_EVENTGROUP.

◆ ove_eventgroup_destroy()

void ove_eventgroup_destroy ( ove_eventgroup_t eg )

Destroy a heap-allocated event group.

Frees the event group and all associated resources. Must only be called on handles obtained from ove_eventgroup_create.

Parameters

[in] eg Event group handle returned by ove_eventgroup_create.

Note: Requires CONFIG_OVE_EVENTGROUP and OVE_HEAP_EVENTGROUP.

◆ ove_eventgroup_set_bits()

ove_eventbits_t ove_eventgroup_set_bits	(	ove_eventgroup_t	eg,
		ove_eventbits_t	bits
	)

Set one or more bits in the event group from task context.

Atomically ORs bits into the current event group value. Any tasks blocked in ove_eventgroup_wait_bits whose wait conditions are now satisfied will be unblocked.

Parameters

[in]	eg	Event group handle.
[in]	bits	Bitmask of bits to set.

Returns: The value of the event group immediately after the set operation, before any waiting tasks have had the chance to clear bits.

Note: Must not be called from an ISR; use ove_eventgroup_set_bits_from_isr.

◆ ove_eventgroup_clear_bits()

ove_eventbits_t ove_eventgroup_clear_bits	(	ove_eventgroup_t	eg,
		ove_eventbits_t	bits
	)

Clear one or more bits in the event group.

Atomically ANDs the complement of bits into the current event group value. Clearing bits will not unblock any waiting tasks.

Parameters

[in]	eg	Event group handle.
[in]	bits	Bitmask of bits to clear.

Returns: The value of the event group as it was before the clear operation (matches FreeRTOS xEventGroupClearBits, which every backend wraps or mirrors).

◆ ove_eventgroup_wait_bits()

int ove_eventgroup_wait_bits	(	ove_eventgroup_t	eg,
		ove_eventbits_t	bits,
		uint32_t	flags,
		uint64_t	timeout_ns,
		ove_eventbits_t *	result
	)

Block until one or all of the requested bits are set.

Waits for the bit pattern described by bits and flags. The behavior is controlled by flags:

OVE_EG_WAIT_ALL — require all bits in bits to be set simultaneously.
OVE_EG_CLEAR_ON_EXIT — clear the matching bits atomically on return.

On success the event bits at the time of the condition being met are written to result.

Parameters

[in]	eg	Event group handle.
[in]	bits	Bitmask of bits to wait for.
[in]	flags	Combination of `OVE_EG_WAIT_ALL` and/or `OVE_EG_CLEAR_ON_EXIT`; pass 0 for defaults.
[in]	timeout_ns	Maximum wait time in nanoseconds; 0 for non-blocking.
[out]	result	Receives the event bits value that satisfied the wait, or `NULL` if not needed.

Returns: OVE_OK if the wait condition was met, OVE_ERR_TIMEOUT on timeout, negative error code on failure.

◆ ove_eventgroup_wait_bits_until()

static int ove_eventgroup_wait_bits_until	(	ove_eventgroup_t	eg,
		ove_eventbits_t	bits,
		uint32_t	flags,
		uint64_t	deadline_ns,
		ove_eventbits_t *	result
	)

inlinestatic

Deadline-based variant of ove_eventgroup_wait_bits.

Equivalent to calling ove_eventgroup_wait_bits with the time remaining until deadline_ns (a steady-clock value from ove_time_now_steady_ns). Pass OVE_WAIT_FOREVER for an indefinite block.

Parameters

[in]	eg	Event group handle.
[in]	bits	Bitmask of bits to wait for.
[in]	flags	Combination of `OVE_EG_WAIT_ALL` and/or `OVE_EG_CLEAR_ON_EXIT`.
[in]	deadline_ns	Absolute deadline against ove_time_now_steady_ns, or `OVE_WAIT_FOREVER`.
[out]	result	Receives the event bits value that satisfied the wait, or `NULL` if not needed.

Returns: OVE_OK on success, OVE_ERR_TIMEOUT on deadline expiry, negative error code on failure.

◆ ove_eventgroup_set_bits_from_isr()

ove_eventbits_t ove_eventgroup_set_bits_from_isr	(	ove_eventgroup_t	eg,
		ove_eventbits_t	bits
	)

Set bits in the event group from an ISR.

ISR-safe variant of ove_eventgroup_set_bits. A context switch to a higher-priority task that was unblocked may be requested by the underlying RTOS after this call returns.

Parameters

[in]	eg	Event group handle.
[in]	bits	Bitmask of bits to set.

Returns: The value of the event group at the time of the call (before any pending context switch).

◆ ove_eventgroup_get_bits()

ove_eventbits_t ove_eventgroup_get_bits ( ove_eventgroup_t eg )

Read the current bit value of the event group without blocking.

Returns a snapshot of the event group's bit pattern at the time of the call. The value may change immediately after the call returns.

Parameters

[in] eg Event group handle.

Returns: Current event bits value.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ OVE_EG_WAIT_ALL

◆ OVE_EG_CLEAR_ON_EXIT

Function Documentation

◆ ove_eventgroup_init()

◆ ove_eventgroup_deinit()

◆ ove_eventgroup_create()

◆ ove_eventgroup_destroy()

◆ ove_eventgroup_set_bits()

◆ ove_eventgroup_clear_bits()

◆ ove_eventgroup_wait_bits()

◆ ove_eventgroup_wait_bits_until()

◆ ove_eventgroup_set_bits_from_isr()

◆ ove_eventgroup_get_bits()