Event flag group services.
[Native Xenomai API.]

Collaboration diagram for Event flag group services.:

---

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)
int	rt_event_delete (RT_EVENT *event)
int	rt_event_signal (RT_EVENT *event, unsigned long mask)
int	rt_event_wait (RT_EVENT *event, unsigned long mask, unsigned long *mask_r, int mode, RTIME timeout)
int	rt_event_clear (RT_EVENT *event, unsigned long mask, unsigned long *mask_r)
int	rt_event_inquire (RT_EVENT *event, RT_EVENT_INFO *info)
int	rt_event_bind (RT_EVENT *event, const char *name, RTIME timeout)
static int	rt_event_unbind (RT_EVENT *event)

---

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:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

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:

The timeout value will be interpreted as jiffies if the native skin is bound to a periodic time base (see CONFIG_XENO_OPT_NATIVE_PERIOD), or nanoseconds otherwise.

---