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

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, uint32_t timeout_ms, ove_eventbits_t *result)
	Block until one or all of the requested bits are set.

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.

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() — unified API that works in both heap and zero-heap mode. In zero-heap mode these are macros that generate per-call-site static storage.
_init() / _deinit() — explicit storage control with caller-supplied buffers. Use when creating objects in loops, arrays, or structs.

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 immediately after the clear operation.

◆ ove_eventgroup_wait_bits()

int ove_eventgroup_wait_bits	(	ove_eventgroup_t	eg,
		ove_eventbits_t	bits,
		uint32_t	flags,
		uint32_t	timeout_ms,
		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_ms	Maximum wait time in milliseconds; 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_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_set_bits_from_isr()

◆ ove_eventgroup_get_bits()