2.4. event — Event channel

An event channel consists of a 32 bits bitmap, where each bit corresponds to an event state. If the bit is set, the event is active. Since an event only has two states, active and inactive, signalling the same event multiple times will just result in the event to be active. There is no internal counter of how “active” an event is, it’s simply active or inactive.

2.4.1. Example usage

This is a small example of writing an event from an interrupt handler to a thread.

struct event_t event;

/* The interrupt handler. */
ISR(foo)
{
    uint32_t mask;

    mask = 0x1;
    event_write_isr(&event, &mask, sizeof(mask));
}

/* The thread. */
void bar(void *arg_p)
{
    uint32_t mask;

    /* Must be called before any read from or write to the event
       channel. */
    event_init(&event);

    mask = 0x1;
    event_read(&event, &mask, sizeof(mask))

    /* Do something with the event. */
}

Source code: src/sync/event.h, src/sync/event.c

Test code: tst/sync/event/main.c

Test coverage: src/sync/event.c

Functions

int event_init(struct event_t *self_p)

Initialize given event channel.

Return
zero(0) or negative error code
Parameters
  • self_p: Event channel to initialize.

ssize_t event_read(struct event_t *self_p, void *buf_p, size_t size)

Wait for one or more events to occur in given event mask. This function blocks until at least one of the events in the event mask has been set. When the function returns, given event mask has been overwritten with the events that actually occured. Read events are automatically cleared.

Return
sizeof(mask) or negative error code.
Parameters
  • self_p: Event channel object.
  • buf_p: The mask of events to wait for. When the function returns the mask contains the events that have occured.
  • size: Size to read (always sizeof(mask)).

ssize_t event_try_read(struct event_t *self_p, void *buf_p, size_t size)

Try to read one or more events in given event mask. This function returns immediately, even if no event has occured. When the function returns, given mask has been overwritten with the events that actually occured. Read events are automatically cleared.

Return
sizeof(mask) on success, -EAGAIN if no event was read, and otherwise other negative error code.
Parameters
  • self_p: Event channel object.
  • buf_p: The mask of events to wait for. When the function returns the mask contains the events that have occured.
  • size: Size to read (always sizeof(mask)).

ssize_t event_write(struct event_t *self_p, const void *buf_p, size_t size)

Write given event(s) to given event channel.

Return
sizeof(mask) or negative error code.
Parameters
  • self_p: Event channel object.
  • buf_p: The mask of events to write.
  • size: Must always be sizeof(mask).

ssize_t event_write_isr(struct event_t *self_p, const void *buf_p, size_t size)

Write given events to the event channel from isr or with the system lock taken (see sys_lock()).

Return
sizeof(mask) or negative error code.
Parameters
  • self_p: Event channel object.
  • buf_p: The mask of events to write.
  • size: Must always be sizeof(mask).

ssize_t event_size(struct event_t *self_p)

Checks if there are events active on the event channel.

Return
one(1) is at least one event has occured, otherwise zero(0).
Parameters
  • self_p: Event channel object.

int event_clear(struct event_t *self_p, uint32_t mask)

Clear given events on the event channel.

Return
zero(0) or negative error code.
Parameters
  • self_p: Event channel object.
  • mask: The mask of events to clear.

struct event_t
#include <event.h>

Event channel.

Public Members

struct chan_t base
uint32_t mask
uint32_t reader_mask