Event flag group services.
[Native Xenomai API.]

---

Detailed Description

An event flag group is a synchronization object represented by a long-word structure; every available bit in such word can be used to map a user-defined event flag. When a flag is set, the associated event is said to have occurred. Xenomai tasks and interrupt handlers can use event flags to signal the occurrence of events to other tasks; those tasks can either wait for the events to occur in a conjunctive manner (all awaited events must have occurred to wake up), or in a disjunctive way (at least one of the awaited events must have occurred to wake up).

Files
file	event.c
	This file is part of the Xenomai project.
Functions
int	rt_event_create (RT_EVENT *event, const char *name, unsigned long ivalue, int mode)
	Create an event group.
int	rt_event_delete (RT_EVENT *event)
	Delete an event group.
int	rt_event_signal (RT_EVENT *event, unsigned long mask)
	Post an event group.
int	rt_event_wait (RT_EVENT *event, unsigned long mask, unsigned long *mask_r, int mode, RTIME timeout)
	Pend on an event group.
int	rt_event_clear (RT_EVENT *event, unsigned long mask, unsigned long *mask_r)
	Clear an event group.
int	rt_event_inquire (RT_EVENT *event, RT_EVENT_INFO *info)
	Inquire about an event group.
int	rt_event_bind (RT_EVENT *event, const char *name, RTIME timeout)
	Bind to an event flag group.
static int	rt_event_unbind (RT_EVENT *event)
	Unbind from an event flag group.

---

Function Documentation

int rt_event_bind (  RT_EVENT *  event, const char *  name, RTIME  timeout )

Bind to an event flag group. This user-space only service retrieves the uniform descriptor of a given Xenomai event flag group identified by its symbolic name. If the event flag group does not exist on entry, this service blocks the caller until a event flag group of the given name is created. Parameters: name  A valid NULL-terminated name which identifies the event flag group to bind to. event  The address of an event flag group descriptor retrieved by the operation. Contents of this memory is undefined upon failure. timeout  The number of clock ticks to wait for the registration to occur (see note). Passing TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry. Returns: 0 is returned upon success. Otherwise: -EFAULT is returned if event or name is referencing invalid memory. -EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed. -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry. -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time. -EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked). Environments: This service can be called from: User-space task (switches to primary mode) Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation. Note: This service is sensitive to the current operation mode of the system timer, as defined by the CONFIG_XENO_OPT_TIMING_PERIOD parameter. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_event_clear (  RT_EVENT *  event, unsigned long  mask, unsigned long *  mask_r )

Clear an event group. Clears a set of flags from an event mask. Parameters: event  The descriptor address of the affected event. mask  The set of events to be cleared. mask_r  If non-NULL, mask_r is the address of a memory location which will be written upon success with the previous value of the event group before the flags are cleared. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if event is not an event group descriptor. -EIDRM is returned if event is a deleted event group descriptor. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: never.

int rt_event_create (  RT_EVENT *  event, const char *  name, unsigned long  ivalue, int  mode )

Create an event group. Event groups provide for task synchronization by allowing a set of flags (or "events") to be waited for and posted atomically. An event group contains a mask of received events; any set of bits from the event mask can be pended or posted in a single operation. Tasks can wait for a conjunctive (AND) or disjunctive (OR) set of events to occur. A task pending on an event group in conjunctive mode is woken up as soon as all awaited events are set in the event mask. A task pending on an event group in disjunctive mode is woken up as soon as any awaited event is set in the event mask. Parameters: event  The address of an event group descriptor Xenomai will use to store the event-related data. This descriptor must always be valid while the group is active therefore it must be allocated in permanent memory. name  An ASCII string standing for the symbolic name of the group. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created event group. ivalue  The initial value of the group's event mask. mode  The event group creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new group: EV_FIFO makes tasks pend in FIFO order on the event group. EV_PRIO makes tasks pend in priority order on the event group. Returns: 0 is returned upon success. Otherwise: -EEXIST is returned if the name is already in use by some registered object. -EPERM is returned if this service was called from an asynchronous context. -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the event group. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task Rescheduling: possible.

int rt_event_delete (  RT_EVENT *  event  )

Delete an event group. Destroy an event group and release all the tasks currently pending on it. An event group exists in the system since rt_event_create() has been called to create it, so this service must be called in order to destroy it afterwards. Parameters: event  The descriptor address of the affected event group. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if event is not a event group descriptor. -EIDRM is returned if event is a deleted event group descriptor. -EPERM is returned if this service was called from an asynchronous context. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task Rescheduling: possible.

int rt_event_inquire (  RT_EVENT *  event, RT_EVENT_INFO *  info )

Inquire about an event group. Return various information about the status of a specified event group. Parameters: event  The descriptor address of the inquired event group. info  The address of a structure the event group information will be written to. Returns: 0 is returned and status information is written to the structure pointed at by info upon success. Otherwise: -EINVAL is returned if event is not a event group descriptor. -EIDRM is returned if event is a deleted event group descriptor. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: never.

int rt_event_signal (  RT_EVENT *  event, unsigned long  mask )

Post an event group. Post a set of bits to the event mask. All tasks having their wait request fulfilled by the posted events are resumed. Parameters: event  The descriptor address of the affected event. mask  The set of events to be posted. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if event is not an event group descriptor. -EIDRM is returned if event is a deleted event group descriptor. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: possible.

int rt_event_unbind (  RT_EVENT *  event  )  [inline, static]

Unbind from an event flag group. This user-space only service unbinds the calling task from the event flag group object previously retrieved by a call to rt_event_bind(). Parameters: event  The address of an event flag group descriptor to unbind from. Returns: 0 is always returned. This service can be called from: User-space task. Rescheduling: never.

int rt_event_wait (  RT_EVENT *  event, unsigned long  mask, unsigned long *  mask_r, int  mode, RTIME  timeout )

Pend on an event group. Waits for one or more events on the specified event group, either in conjunctive or disjunctive mode. If the specified set of bits is not set, the calling task is blocked. The task is not resumed until the request is fulfilled. The event bits are NOT cleared from the event group when a request is satisfied; rt_event_wait() will return immediately with success for the same event mask until rt_event_clear() is called to clear those bits. Parameters: event  The descriptor address of the affected event group. mask  The set of bits to wait for. Passing zero causes this service to return immediately with a success value; the current value of the event mask is also copied to mask_r. mask_r  The value of the event mask at the time the task was readied. mode  The pend mode. The following flags can be OR'ed into this bitmask, each of them affecting the operation: EV_ANY makes the task pend in disjunctive mode (i.e. OR); this means that the request is fulfilled when at least one bit set into mask is set in the current event mask. EV_ALL makes the task pend in conjunctive mode (i.e. AND); this means that the request is fulfilled when at all bits set into mask are set in the current event mask. Parameters: timeout  The number of clock ticks to wait for fulfilling the request (see note). Passing TM_INFINITE causes the caller to block indefinitely until the request is fulfilled. Passing TM_NONBLOCK causes the service to return immediately without waiting if the request cannot be satisfied immediately. Returns: 0 is returned upon success. Otherwise: -EINVAL is returned if event is not a event group descriptor. -EIDRM is returned if event is a deleted event group descriptor, including if the deletion occurred while the caller was sleeping on it before the request has been satisfied. -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the current event mask value does not satisfy the request. -EINTR is returned if rt_task_unblock() has been called for the waiting task before the request has been satisfied. -ETIMEDOUT is returned if the request has not been satisfied within the specified amount of time. -EPERM is returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked). Environments: This service can be called from: Kernel module initialization/cleanup code or Interrupt service routine only if timeout is equal to TM_NONBLOCK. Kernel-based task User-space task (switches to primary mode) Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation. Note: This service is sensitive to the current operation mode of the system timer, as defined by the CONFIG_XENO_OPT_TIMING_PERIOD parameter. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

---