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

enum 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

pos	cursor variable holding a pointer to the RTDM task being fetched.
wq	waitqueue 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

pos	cursor variable holding a pointer to the RTDM task being fetched.
tmp	temporary cursor variable.
wq	waitqueue 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

	wq	waitqueue to wait on.
	timeout	relative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]	toseq	handle 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

	wq	waitqueue to wait on.
	condition	C expression for the event to wait for.
	timeout	relative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]	toseq	handle 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

	wq	locked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
	condition	C expression for the event to wait for.
	timeout	relative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]	toseq	handle 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

	wq	locked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
	timeout	relative timeout in nanoseconds, see RTDM_TIMEOUT_xxx for special values.
[in,out]	toseq	handle 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_seq	Timeout sequence handle
[in]	timeout	Relative 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

wq	waitqueue 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

wq	waitqueue to wait on
condition	C 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

wq	locked waitqueue to wait on. The waitqueue lock is dropped when sleeping, then reacquired before this service returns to the caller.
condition	C 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

wq	locked 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

wq	waitqueue 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

wq	waitqueue 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

wq	waitqueue 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

wq	waitqueue 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

wq	waitqueue to lock.
context	name 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

wq	waitqueue 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

wq	waitqueue to unlock.
context	name 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

wq	waitqueue to signal.
waiter	RTDM task to wake up.

Tags: unrestricted, might-switch

Modules

Functions

RTDM_SELECTTYPE_xxx

Timeout Sequence Management

Detailed Description

Enumeration Type Documentation

◆ rtdm_selecttype

Function Documentation

◆ rtdm_for_each_waiter()

◆ rtdm_for_each_waiter_safe()

◆ rtdm_timedwait()

◆ rtdm_timedwait_condition()

◆ rtdm_timedwait_condition_locked()

◆ rtdm_timedwait_locked()

◆ rtdm_toseq_init()

◆ rtdm_wait()

◆ rtdm_wait_condition()

◆ rtdm_wait_condition_locked()

◆ rtdm_wait_locked()

◆ rtdm_waitqueue_broadcast()

◆ rtdm_waitqueue_destroy()

◆ rtdm_waitqueue_flush()

◆ rtdm_waitqueue_init()

◆ rtdm_waitqueue_lock()

◆ rtdm_waitqueue_signal()

◆ rtdm_waitqueue_unlock()

◆ rtdm_waitqueue_wakeup()