Collaboration diagram for Task Services:

Typedefs
typedef void(*	rtdm_task_proc_t) (void *arg)
	Real-time task procedure. More...

Functions
int	rtdm_task_init (rtdm_task_t task, const char name, rtdm_task_proc_t task_proc, void *arg, int priority, nanosecs_rel_t period)
	Initialise and start a real-time task. More...

void	rtdm_task_destroy (rtdm_task_t *task)
	Destroy a real-time task. More...

int	rtdm_task_should_stop (void)
	Check for pending termination request. More...

void	rtdm_task_set_priority (rtdm_task_t *task, int priority)
	Adjust real-time task priority. More...

int	rtdm_task_set_period (rtdm_task_t *task, nanosecs_abs_t start_date, nanosecs_rel_t period)
	Adjust real-time task period. More...

int	rtdm_task_wait_period (unsigned long *overruns_r)
	Wait on next real-time task period. More...

int	rtdm_task_unblock (rtdm_task_t *task)
	Activate a blocked real-time task. More...

rtdm_task_t *	rtdm_task_current (void)
	Get current real-time task. More...

int	rtdm_task_sleep (nanosecs_rel_t delay)
	Sleep a specified amount of time. More...

int	rtdm_task_sleep_until (nanosecs_abs_t wakeup_time)
	Sleep until a specified absolute time. More...

int	rtdm_task_sleep_abs (nanosecs_abs_t wakeup_time, enum rtdm_timer_mode mode)
	Sleep until a specified absolute time. More...

int	rtdm_task_busy_wait (bool condition, nanosecs_rel_t spin_ns, nanosecs_rel_t sleep_ns)
	Safe busy waiting. More...

void	rtdm_wait_prepare (struct rtdm_wait_context *wc)
	Register wait context. More...

void	rtdm_wait_complete (struct rtdm_wait_context *wc)
	Mark completion for a wait context. More...

int	rtdm_wait_is_completed (struct rtdm_wait_context *wc)
	Test completion of a wait context. More...

void	rtdm_task_join (rtdm_task_t *task)
	Wait on a real-time task to terminate. More...

void	rtdm_task_busy_sleep (nanosecs_rel_t delay)
	Busy-wait a specified amount of time. More...

Task Priority Range
Maximum and minimum task priorities
#define	RTDM_TASK_LOWEST_PRIORITY 0

#define	RTDM_TASK_HIGHEST_PRIORITY 99

Task Priority Modification
Raise or lower task priorities by one level
#define	RTDM_TASK_RAISE_PRIORITY (+1)

#define	RTDM_TASK_LOWER_PRIORITY (-1)

Detailed Description

Typedef Documentation

◆ rtdm_task_proc_t

typedef void(* rtdm_task_proc_t) (void *arg)

Real-time task procedure.

Parameters

[in,out] arg argument as passed to rtdm_task_init()

Function Documentation

◆ rtdm_task_busy_sleep()

void rtdm_task_busy_sleep ( nanosecs_rel_t delay )

Busy-wait a specified amount of time.

This service does not schedule out the caller, but rather spins in a tight loop, burning CPU cycles until the timeout elapses.

Parameters

[in] delay Delay in nanoseconds. Note that a zero delay does not have the meaning of RTDM_TIMEOUT_INFINITE here.

Note: The caller must not be migratable to different CPUs while executing this service. Otherwise, the actual delay will be undefined.

Tags: unrestricted

◆ rtdm_task_busy_wait()

int rtdm_task_busy_wait	(	bool	condition,
		nanosecs_rel_t	spin_ns,
		nanosecs_rel_t	sleep_ns
	)

Safe busy waiting.

This service alternates active spinning and sleeping within a wait loop, until a condition is satisfied. While sleeping, a task is scheduled out and does not consume any CPU time.

rtdm_task_busy_wait() is particularly useful for waiting for a state change reading an I/O register, which usually happens shortly after the wait starts, without incurring the adverse effects of long busy waiting if it doesn't.

Parameters

[in]	condition	The C expression to be tested for detecting completion.
[in]	spin_ns	The time to spin on condition before sleeping, expressed as a count of nanoseconds.
[in]	sleep_ns	The time to sleep for before spinning again, expressed as a count of nanoseconds.

Returns: 0 on success if condition is satisfied, otherwise:

-EINTR is returned if the calling task has been unblocked by a Linux signal or explicitly via rtdm_task_unblock().
-EPERM may be returned if an illegal invocation environment is detected.

Tags: primary-only, might-switch

◆ rtdm_task_current()

rtdm_task_t* rtdm_task_current ( void )

Get current real-time task.

Returns: Pointer to task handle

Tags: mode-unrestricted

◆ rtdm_task_destroy()

void rtdm_task_destroy ( rtdm_task_t * task )

Destroy a real-time task.

This call sends a termination request to task, then waits for it to exit. All RTDM task should check for pending termination requests by calling rtdm_task_should_stop() from their work loop.

If task is current, rtdm_task_destroy() terminates the current context, and does not return to the caller.

Parameters

[in,out] task Task handle as returned by rtdm_task_init()

Note: Passing the same task handle to RTDM services after the completion of this function is not allowed.

Tags: secondary-only, might-switch

◆ rtdm_task_init()

int rtdm_task_init	(	rtdm_task_t *	task,
		const char *	name,
		rtdm_task_proc_t	task_proc,
		void *	arg,
		int	priority,
		nanosecs_rel_t	period
	)

Initialise and start a real-time task.

After initialising a task, the task handle remains valid and can be passed to RTDM services until either rtdm_task_destroy() or rtdm_task_join() was invoked.

Parameters

[in,out]	task	Task handle
[in]	name	Optional task name
[in]	task_proc	Procedure to be executed by the task
[in]	arg	Custom argument passed to `task_proc()` on entry
[in]	priority	Priority of the task, see also Task Priority Range
[in]	period	Period in nanoseconds of a cyclic task, 0 for non-cyclic mode. Waiting for the first and subsequent periodic events is done using rtdm_task_wait_period().

Returns: 0 on success, otherwise negative error code

Tags: secondary-only, might-switch

◆ rtdm_task_join()

void rtdm_task_join ( rtdm_task_t * task )

Wait on a real-time task to terminate.

Parameters

[in,out] task Task handle as returned by rtdm_task_init()

Note: Passing the same task handle to RTDM services after the completion of this function is not allowed.; This service does not trigger the termination of the targeted task. The user has to take of this, otherwise rtdm_task_join() will never return.

Tags: mode-unrestricted

References xnthread_join().

◆ rtdm_task_set_period()

int rtdm_task_set_period	(	rtdm_task_t *	task,
		nanosecs_abs_t	start_date,
		nanosecs_rel_t	period
	)

Adjust real-time task period.

Parameters

[in,out]	task	Task handle as returned by rtdm_task_init(), or NULL for referring to the current RTDM task or Cobalt thread.
[in]	start_date	The initial (absolute) date of the first release point, expressed in nanoseconds. task will be delayed by the first call to rtdm_task_wait_period() until this point is reached. If start_date is zero, the first release point is set to period nanoseconds after the current date.
[in]	period	New period in nanoseconds of a cyclic task, zero to disable cyclic mode for task.

Tags: task-unrestricted

◆ rtdm_task_set_priority()

void rtdm_task_set_priority	(	rtdm_task_t *	task,
		int	priority
	)

Adjust real-time task priority.

Parameters

[in,out]	task	Task handle as returned by rtdm_task_init()
[in]	priority	New priority of the task, see also Task Priority Range

Tags: task-unrestricted, might-switch

◆ rtdm_task_should_stop()

int rtdm_task_should_stop ( void )

Check for pending termination request.

Check whether a termination request was received by the current RTDM task. Termination requests are sent by calling rtdm_task_destroy().

Returns: Non-zero indicates that a termination request is pending, in which case the caller should wrap up and exit.

Tags: rtdm-task, might-switch

◆ rtdm_task_sleep()

int rtdm_task_sleep ( nanosecs_rel_t delay )

Sleep a specified amount of time.

Parameters

[in] delay Delay in nanoseconds, see RTDM_TIMEOUT_xxx for special values.

Returns: 0 on success, otherwise:

-EINTR is returned if calling task has been unblock by a signal or explicitly via rtdm_task_unblock().
-EPERM may be returned if an illegal invocation environment is detected.

Tags: primary-only, might-switch

◆ rtdm_task_sleep_abs()

int rtdm_task_sleep_abs	(	nanosecs_abs_t	wakeup_time,
		enum rtdm_timer_mode	mode
	)

Sleep until a specified absolute time.

Parameters

[in]	wakeup_time	Absolute timeout in nanoseconds
[in]	mode	Selects the timer mode, see RTDM_TIMERMODE_xxx for details

Returns: 0 on success, otherwise:

-EINTR is returned if calling task has been unblock by a signal or explicitly via rtdm_task_unblock().
-EPERM may be returned if an illegal invocation environment is detected.
-EINVAL is returned if an invalid parameter was passed.

Tags: primary-only, might-switch

◆ rtdm_task_sleep_until()

int rtdm_task_sleep_until ( nanosecs_abs_t wakeup_time )

Sleep until a specified absolute time.

Deprecated:: Use rtdm_task_sleep_abs instead!

Parameters

[in] wakeup_time Absolute timeout in nanoseconds

Returns: 0 on success, otherwise:

-EINTR is returned if calling task has been unblock by a signal or explicitly via rtdm_task_unblock().
-EPERM may be returned if an illegal invocation environment is detected.

Tags: primary-only, might-switch

◆ rtdm_task_unblock()

int rtdm_task_unblock ( rtdm_task_t * task )

Activate a blocked real-time task.

Returns: Non-zero is returned if the task was actually unblocked from a pending wait state, 0 otherwise.

Tags: unrestricted, might-switch

◆ rtdm_task_wait_period()

int rtdm_task_wait_period ( unsigned long * overruns_r )

Wait on next real-time task period.

Parameters

[in] overruns_r Address of a long word receiving the count of overruns if -ETIMEDOUT is returned, or NULL if the caller don't need that information.

Returns: 0 on success, otherwise:

-EINVAL is returned if calling task is not in periodic mode.
-ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point has been missed by the calling task.

Tags: primary-only, might-switch

◆ rtdm_wait_complete()

void rtdm_wait_complete ( struct rtdm_wait_context * wc )

Mark completion for a wait context.

rtdm_complete_wait() marks a wait context as completed, so that rtdm_wait_is_completed() returns true for such context.

Parameters

wc	Wait context to complete.

◆ rtdm_wait_is_completed()

int rtdm_wait_is_completed ( struct rtdm_wait_context * wc )

Test completion of a wait context.

rtdm_wait_is_completed() returns true if rtdm_complete_wait() was called for wc. The completion mark is reset each time rtdm_wait_prepare() is called for a wait context.

Parameters

wc	Wait context to check for completion.

Returns: non-zero/true if rtdm_wait_complete() was called for wc, zero otherwise.

◆ rtdm_wait_prepare()

void rtdm_wait_prepare ( struct rtdm_wait_context * wc )

Register wait context.

rtdm_wait_prepare() registers a wait context structure for the caller, which can be later retrieved by a call to rtdm_wait_get_context(). This call is normally issued before the current task blocks on a wait object, waiting for some (producer) code to wake it up. Arbitrary data can be exchanged between both sites via the wait context structure, which is allocated by the waiter (consumer) side.

wc is the address of an anchor object which is commonly embedded into a larger structure with arbitrary contents, which needs to be shared between the consumer (waiter) and the producer for implementing the wait code.

A typical implementation pattern for the wait side is:

struct rtdm_waitqueue wq;
struct some_wait_context {
   int input_value;
   int output_value;
   struct rtdm_wait_context wc;
} wait_context;
wait_context.input_value = 42;
rtdm_wait_prepare(&wait_context);
ret = rtdm_wait_condition(&wq, rtdm_wait_is_completed(&wait_context));
if (ret)
    goto wait_failed;
handle_event(wait_context.output_value);

On the producer side, the implementation would look like:

struct rtdm_waitqueue wq;
struct some_wait_context {
   int input_value;
   int output_value;
   struct rtdm_wait_context wc;
} *wait_context_ptr;
struct rtdm_wait_context *wc;
rtdm_task_t *task;
rtdm_for_each_waiter(task, &wq) {
   wc = rtdm_wait_get_context(task);
   wait_context_ptr = container_of(wc, struct some_wait_context, wc);
   wait_context_ptr->output_value = 12;
}
rtdm_waitqueue_broadcast(&wq);

Parameters

wc	Wait context to register.

Typedefs

Functions

Task Priority Range

Task Priority Modification

Detailed Description

Typedef Documentation

◆ rtdm_task_proc_t

Function Documentation

◆ rtdm_task_busy_sleep()

◆ rtdm_task_busy_wait()

◆ rtdm_task_current()

◆ rtdm_task_destroy()

◆ rtdm_task_init()

◆ rtdm_task_join()

◆ rtdm_task_set_period()

◆ rtdm_task_set_priority()

◆ rtdm_task_should_stop()

◆ rtdm_task_sleep()

◆ rtdm_task_sleep_abs()

◆ rtdm_task_sleep_until()

◆ rtdm_task_unblock()

◆ rtdm_task_wait_period()

◆ rtdm_wait_complete()

◆ rtdm_wait_is_completed()

◆ rtdm_wait_prepare()