Xenomai  3.0.5
Synchronisation Services
Collaboration diagram for Synchronisation Services:

Modules

 Big dual kernel lock
 
 Spinlock with preemption deactivation
 
 Event Services
 
 Semaphore Services
 
 Mutex services
 

Functions

void rtdm_waitqueue_init (struct rtdm_waitqueue *wq)
 Initialize a RTDM wait queue. More...
 
void rtdm_waitqueue_destroy (struct rtdm_waitqueue *wq)
 Deletes a RTDM wait queue. More...
 
 rtdm_timedwait_condition_locked (struct rtdm_wait_queue *wq, C_expr condition, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
 Timed sleep on a locked waitqueue until a condition gets true. More...
 
 rtdm_wait_condition_locked (struct rtdm_wait_queue *wq, C_expr condition)
 Sleep on a locked waitqueue until a condition gets true. More...
 
 rtdm_timedwait_condition (struct rtdm_wait_queue *wq, C_expr condition, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
 Timed sleep on a waitqueue until a condition gets true. More...
 
void rtdm_timedwait (struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
 Timed sleep on a waitqueue unconditionally. More...
 
void rtdm_timedwait_locked (struct rtdm_wait_queue *wq, nanosecs_rel_t timeout, rtdm_toseq_t *toseq)
 Timed sleep on a locked waitqueue unconditionally. More...
 
 rtdm_wait_condition (struct rtdm_wait_queue *wq, C_expr condition)
 Sleep on a waitqueue until a condition gets true. More...
 
void rtdm_wait (struct rtdm_wait_queue *wq)
 Sleep on a waitqueue unconditionally. More...
 
void rtdm_wait_locked (struct rtdm_wait_queue *wq)
 Sleep on a locked waitqueue unconditionally. More...
 
void rtdm_waitqueue_lock (struct rtdm_wait_queue *wq, rtdm_lockctx_t context)
 Lock a waitqueue. More...
 
void rtdm_waitqueue_unlock (struct rtdm_wait_queue *wq, rtdm_lockctx_t context)
 Unlock a waitqueue. More...
 
void rtdm_waitqueue_signal (struct rtdm_wait_queue *wq)
 Signal a waitqueue. More...
 
void rtdm_waitqueue_broadcast (struct rtdm_wait_queue *wq)
 Broadcast a waitqueue. More...
 
void rtdm_waitqueue_flush (struct rtdm_wait_queue *wq)
 Flush a waitqueue. More...
 
void rtdm_waitqueue_wakeup (struct rtdm_wait_queue *wq, rtdm_task_t waiter)
 Signal a particular waiter on a waitqueue. More...
 
 rtdm_for_each_waiter (rtdm_task_t pos, struct rtdm_wait_queue *wq)
 Simple iterator for waitqueues. More...
 
 rtdm_for_each_waiter_safe (rtdm_task_t pos, rtdm_task_t tmp, struct rtdm_wait_queue *wq)
 Safe iterator for waitqueues. More...
 

RTDM_SELECTTYPE_xxx

Event types select can bind to

enum  rtdm_selecttype { RTDM_SELECTTYPE_READ = XNSELECT_READ, RTDM_SELECTTYPE_WRITE = XNSELECT_WRITE, RTDM_SELECTTYPE_EXCEPT = XNSELECT_EXCEPT }
 

Timeout Sequence Management

void rtdm_toseq_init (rtdm_toseq_t *timeout_seq, nanosecs_rel_t timeout)
 Initialise a timeout sequence. More...
 

Detailed Description

Enumeration Type Documentation

◆ rtdm_selecttype

Enumerator
RTDM_SELECTTYPE_READ 

Select input data availability events.

RTDM_SELECTTYPE_WRITE 

Select ouput buffer availability events.

RTDM_SELECTTYPE_EXCEPT 

Select exceptional events.

Function Documentation

◆ rtdm_for_each_waiter()

rtdm_for_each_waiter ( rtdm_task_t  pos,
struct rtdm_wait_queue *  wq 
)

Simple iterator for waitqueues.

This construct traverses the wait list of a given waitqueue wq, assigning each RTDM task pointer to the cursor variable pos, which must be of type rtdm_task_t.

wq must have been locked by a call to rtdm_waitqueue_lock() prior to traversing its wait list.

Parameters
poscursor variable holding a pointer to the RTDM task being fetched.
wqwaitqueue to scan.
Note
The waitqueue should not be signaled, broadcast or flushed during the traversal, unless the loop is aborted immediately after. Should multiple waiters be readied while iterating, the safe form rtdm_for_each_waiter_safe() must be used for traversal instead.
Tags
unrestricted

◆ rtdm_for_each_waiter_safe()

rtdm_for_each_waiter_safe ( rtdm_task_t  pos,
rtdm_task_t  tmp,
struct rtdm_wait_queue *  wq 
)

Safe iterator for waitqueues.

This construct traverses the wait list of a given waitqueue wq, assigning each RTDM task pointer to the cursor variable pos, which must be of type rtdm_task_t.

Unlike with rtdm_for_each_waiter(), the waitqueue may be signaled, broadcast or flushed during the traversal.

wq must have been locked by a call to rtdm_waitqueue_lock() prior to traversing its wait list.

Parameters
poscursor variable holding a pointer to the RTDM task being fetched.
tmptemporary cursor variable.
wqwaitqueue to scan.
Tags
unrestricted

◆ rtdm_timedwait()

void rtdm_timedwait ( struct rtdm_wait_queue *  wq,
nanosecs_rel_t  timeout,
rtdm_toseq_t *  toseq 
)

Timed sleep on a waitqueue unconditionally.

The calling task is put to sleep until the waitqueue is signaled by either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or flushed by a call to rtdm_waitqueue_flush(), or a timeout occurs.

Parameters
wqwaitqueue to wait on.
timeoutrelative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]toseqhandle of a timeout sequence as returned by rtdm_toseq_init() or NULL.
Returns
0 on success, otherwise:
  • -EINTR is returned if the waitqueue has been flushed, or the calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
  • -ETIMEDOUT is returned if the if the request has not been satisfied within the specified amount of time.
Note
Passing RTDM_TIMEOUT_NONE to timeout makes no sense for such service, and might cause unexpected behavior.
Tags
primary-only, might-switch

◆ rtdm_timedwait_condition()

rtdm_timedwait_condition ( struct rtdm_wait_queue *  wq,
C_expr  condition,
nanosecs_rel_t  timeout,
rtdm_toseq_t *  toseq 
)

Timed sleep on a waitqueue until a condition gets true.

The calling task is put to sleep until condition evaluates to true or a timeout occurs. The condition is checked each time the waitqueue wq is signaled.

Parameters
wqwaitqueue to wait on.
conditionC expression for the event to wait for.
timeoutrelative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]toseqhandle of a timeout sequence as returned by rtdm_toseq_init() or NULL.
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
  • -ETIMEDOUT is returned if the if the request has not been satisfied within the specified amount of time.
Note
rtdm_waitqueue_signal() has to be called after changing any variable that could change the result of the wait condition.
Passing RTDM_TIMEOUT_NONE to timeout makes no sense for such service, and might cause unexpected behavior.
Tags
primary-only, might-switch

◆ rtdm_timedwait_condition_locked()

rtdm_timedwait_condition_locked ( struct rtdm_wait_queue *  wq,
C_expr  condition,
nanosecs_rel_t  timeout,
rtdm_toseq_t *  toseq 
)

Timed sleep on a locked waitqueue until a condition gets true.

The calling task is put to sleep until condition evaluates to true or a timeout occurs. The condition is checked each time the waitqueue wq is signaled.

The waitqueue must have been locked by a call to rtdm_waitqueue_lock() prior to calling this service.

Parameters
wqlocked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
conditionC expression for the event to wait for.
timeoutrelative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]toseqhandle of a timeout sequence as returned by rtdm_toseq_init() or NULL.
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
  • -ETIMEDOUT is returned if the if the request has not been satisfied within the specified amount of time.
Note
rtdm_waitqueue_signal() has to be called after changing any variable that could change the result of the wait condition.
Passing RTDM_TIMEOUT_NONE to timeout makes no sense for such service, and might cause unexpected behavior.
Tags
primary-only, might-switch

◆ rtdm_timedwait_locked()

void rtdm_timedwait_locked ( struct rtdm_wait_queue *  wq,
nanosecs_rel_t  timeout,
rtdm_toseq_t *  toseq 
)

Timed sleep on a locked waitqueue unconditionally.

The calling task is put to sleep until the waitqueue is signaled by either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or flushed by a call to rtdm_waitqueue_flush(), or a timeout occurs.

The waitqueue must have been locked by a call to rtdm_waitqueue_lock() prior to calling this service.

Parameters
wqlocked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
timeoutrelative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]toseqhandle of a timeout sequence as returned by rtdm_toseq_init() or NULL.
Returns
0 on success, otherwise:
  • -EINTR is returned if the waitqueue has been flushed, or the calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
  • -ETIMEDOUT is returned if the if the request has not been satisfied within the specified amount of time.
Note
Passing RTDM_TIMEOUT_NONE to timeout makes no sense for such service, and might cause unexpected behavior.
Tags
primary-only, might-switch

◆ rtdm_toseq_init()

void rtdm_toseq_init ( rtdm_toseq_t *  timeout_seq,
nanosecs_rel_t  timeout 
)

Initialise a timeout sequence.

This service initialises a timeout sequence handle according to the given timeout value. Timeout sequences allow to maintain a continuous timeout across multiple calls of blocking synchronisation services. A typical application scenario is given below.

Parameters
[in,out]timeout_seqTimeout sequence handle
[in]timeoutRelative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values

Application Scenario:

int device_service_routine(...)
{
rtdm_toseq_t timeout_seq;
...
rtdm_toseq_init(&timeout_seq, timeout);
...
while (received < requested) {
ret = rtdm_event_timedwait(&data_available, timeout, &timeout_seq);
if (ret < 0) // including -ETIMEDOUT
break;
// receive some data
...
}
...
}

Using a timeout sequence in such a scenario avoids that the user-provided relative timeout is restarted on every call to rtdm_event_timedwait(), potentially causing an overall delay that is larger than specified by timeout. Moreover, all functions supporting timeout sequences also interpret special timeout values (infinite and non-blocking), disburdening the driver developer from handling them separately.

Tags
task-unrestricted

◆ rtdm_wait()

void rtdm_wait ( struct rtdm_wait_queue *  wq)

Sleep on a waitqueue unconditionally.

The calling task is put to sleep until the waitqueue is signaled by either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or flushed by a call to rtdm_waitqueue_flush().

Parameters
wqwaitqueue to wait on.
Returns
0 on success, otherwise:
  • -EINTR is returned if the waitqueue has been flushed, or the calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
Tags
primary-only, might-switch

◆ rtdm_wait_condition()

rtdm_wait_condition ( struct rtdm_wait_queue *  wq,
C_expr  condition 
)

Sleep on a waitqueue until a condition gets true.

The calling task is put to sleep until condition evaluates to true. The condition is checked each time the waitqueue wq is signaled.

Parameters
wqwaitqueue to wait on
conditionC expression for the event to wait for.
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
Note
rtdm_waitqueue_signal() has to be called after changing any variable that could change the result of the wait condition.
Tags
primary-only, might-switch

◆ rtdm_wait_condition_locked()

rtdm_wait_condition_locked ( struct rtdm_wait_queue *  wq,
C_expr  condition 
)

Sleep on a locked waitqueue until a condition gets true.

The calling task is put to sleep until condition evaluates to true. The condition is checked each time the waitqueue wq is signaled.

The waitqueue must have been locked by a call to rtdm_waitqueue_lock() prior to calling this service.

Parameters
wqlocked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
conditionC expression for the event to wait for.
Returns
0 on success, otherwise:
  • -EINTR is returned if calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
Note
rtdm_waitqueue_signal() has to be called after changing any variable that could change the result of the wait condition.
Tags
primary-only, might-switch

◆ rtdm_wait_locked()

void rtdm_wait_locked ( struct rtdm_wait_queue *  wq)

Sleep on a locked waitqueue unconditionally.

The calling task is put to sleep until the waitqueue is signaled by either rtdm_waitqueue_signal() or rtdm_waitqueue_broadcast(), or flushed by a call to rtdm_waitqueue_flush().

The waitqueue must have been locked by a call to rtdm_waitqueue_lock() prior to calling this service.

Parameters
wqlocked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
Returns
0 on success, otherwise:
  • -EINTR is returned if the waitqueue has been flushed, or the calling task has received a Linux signal or has been forcibly unblocked by a call to rtdm_task_unblock().
Tags
primary-only, might-switch

◆ rtdm_waitqueue_broadcast()

void rtdm_waitqueue_broadcast ( struct rtdm_wait_queue *  wq)

Broadcast a waitqueue.

Broadcast the waitqueue wq, waking up all waiters. Each readied task may assume to have received the wake up event.

Parameters
wqwaitqueue to broadcast.
Returns
non-zero if at least one task has been readied as a result of this call, zero otherwise.
Tags
unrestricted, might-switch

◆ rtdm_waitqueue_destroy()

void rtdm_waitqueue_destroy ( struct rtdm_waitqueue *  wq)

Deletes a RTDM wait queue.

Dismantles a wait queue structure, releasing all resources attached to it.

Parameters
wqwaitqueue to delete.
Tags
task-unrestricted

◆ rtdm_waitqueue_flush()

void rtdm_waitqueue_flush ( struct rtdm_wait_queue *  wq)

Flush a waitqueue.

Flushes the waitqueue wq, unblocking all waiters with an error status (-EINTR).

Parameters
wqwaitqueue to flush.
Returns
non-zero if at least one task has been readied as a result of this call, zero otherwise.
Tags
unrestricted, might-switch

◆ rtdm_waitqueue_init()

void rtdm_waitqueue_init ( struct rtdm_waitqueue *  wq)

Initialize a RTDM wait queue.

Sets up a wait queue structure for further use.

Parameters
wqwaitqueue to initialize.
Tags
task-unrestricted

◆ rtdm_waitqueue_lock()

void rtdm_waitqueue_lock ( struct rtdm_wait_queue *  wq,
rtdm_lockctx_t  context 
)

Lock a waitqueue.

Acquires the lock on the waitqueue wq.

Parameters
wqwaitqueue to lock.
contextname of local variable to store the context in.
Note
Recursive locking might lead to unexpected behavior, including lock up.
Tags
unrestricted

◆ rtdm_waitqueue_signal()

void rtdm_waitqueue_signal ( struct rtdm_wait_queue *  wq)

Signal a waitqueue.

Signals the waitqueue wq, waking up a single waiter (if any).

Parameters
wqwaitqueue to signal.
Returns
non-zero if a task has been readied as a result of this call, zero otherwise.
Tags
unrestricted, might-switch

◆ rtdm_waitqueue_unlock()

void rtdm_waitqueue_unlock ( struct rtdm_wait_queue *  wq,
rtdm_lockctx_t  context 
)

Unlock a waitqueue.

Releases the lock on the waitqueue wq.

Parameters
wqwaitqueue to unlock.
contextname of local variable to retrieve the context from.
Tags
unrestricted

◆ rtdm_waitqueue_wakeup()

void rtdm_waitqueue_wakeup ( struct rtdm_wait_queue *  wq,
rtdm_task_t  waiter 
)

Signal a particular waiter on a waitqueue.

Signals the waitqueue wq, waking up waiter waiter only, which must be currently sleeping on the waitqueue.

Parameters
wqwaitqueue to signal.
waiterRTDM task to wake up.
Tags
unrestricted, might-switch