Collaboration diagram for Thread services:

Modules
	Thread runtime statistics

	Thread state flags
	Bits reporting permanent or transient states of threads.

	Thread information flags
	Bits reporting events notified to threads.

Functions
static struct xnthread *	xnthread_current (void)
	Retrieve the current Cobalt core TCB. More...

static struct xnthread *	xnthread_from_task (struct task_struct *p)
	Retrieve the Cobalt core TCB attached to a Linux task. More...

static void	xnthread_test_cancel (void)
	Introduce a thread cancellation point. More...

int	xnthread_init (struct xnthread thread, const struct xnthread_init_attr attr, struct xnsched_class sched_class, const union xnsched_policy_param sched_param)
	Initialize a new thread. More...

int	xnthread_start (struct xnthread thread, const struct xnthread_start_attr attr)
	Start a newly created thread. More...

int	xnthread_set_mode (int clrmask, int setmask)
	Change control mode of the current thread. More...

void	xnthread_suspend (struct xnthread thread, int mask, xnticks_t timeout, xntmode_t timeout_mode, struct xnsynch wchan)
	Suspend a thread. More...

void	xnthread_resume (struct xnthread *thread, int mask)
	Resume a thread. More...

int	xnthread_unblock (struct xnthread *thread)
	Unblock a thread. More...

int	xnthread_set_periodic (struct xnthread *thread, xnticks_t idate, xntmode_t timeout_mode, xnticks_t period)
	Make a thread periodic. More...

int	xnthread_wait_period (unsigned long *overruns_r)
	Wait for the next periodic release point. More...

int	xnthread_set_slice (struct xnthread *thread, xnticks_t quantum)
	Set thread time-slicing information. More...

void	xnthread_cancel (struct xnthread *thread)
	Cancel a thread. More...

int	xnthread_join (struct xnthread *thread, bool uninterruptible)
	Join with a terminated thread. More...

int	xnthread_harden (void)
	Migrate a Linux task to the Xenomai domain. More...

void	xnthread_relax (int notify, int reason)
	Switch a shadow thread back to the Linux domain. More...

int	xnthread_map (struct xnthread thread, struct completion done)
	Create a shadow thread context over a kernel task. More...

int	xnthread_set_schedparam (struct xnthread thread, struct xnsched_class sched_class, const union xnsched_policy_param *sched_param)
	Change the base scheduling parameters of a thread. More...

Detailed Description

Function Documentation

◆ xnthread_cancel()

void xnthread_cancel ( struct xnthread * thread )

Cancel a thread.

Request cancellation of a thread. This service forces thread to exit from any blocking call, then to switch to secondary mode. thread will terminate as soon as it reaches a cancellation point. Cancellation points are defined for the following situations:

thread self-cancels by a call to xnthread_cancel().
thread invokes a Linux syscall (user-space shadow only).
thread receives a Linux signal (user-space shadow only).
thread unblocks from a Xenomai syscall (user-space shadow only).
thread attempts to block on a Xenomai syscall (user-space shadow only).
thread explicitly calls xnthread_test_cancel().

Parameters

thread The descriptor address of the thread to terminate.

Tags: task-unrestricted, might-switch

Note: In addition to the common actions taken upon cancellation, a thread which belongs to the SCHED_WEAK class is sent a regular SIGTERM signal.

◆ xnthread_current()

struct xnthread * xnthread_current ( void )

inlinestatic

Retrieve the current Cobalt core TCB.

Returns the address of the current Cobalt core thread descriptor, or NULL if running over a regular Linux task. This call is not affected by the current runtime mode of the core thread.

Note: The returned value may differ from xnsched_current_thread() called from the same context, since the latter returns the root thread descriptor for the current CPU if the caller is running in secondary mode.

Tags: unrestricted

◆ xnthread_from_task()

struct xnthread * xnthread_from_task ( struct task_struct * p )

inlinestatic

Retrieve the Cobalt core TCB attached to a Linux task.

Returns the address of the Cobalt core thread descriptor attached to the Linux task p, or NULL if p is a regular Linux task. This call is not affected by the current runtime mode of the core thread.

Tags: unrestricted

◆ xnthread_harden()

int xnthread_harden ( void )

Migrate a Linux task to the Xenomai domain.

This service causes the transition of "current" from the Linux domain to Xenomai. The shadow will resume in the Xenomai domain as returning from schedule().

Tags: secondary-only, might-switch

◆ xnthread_init()

int xnthread_init	(	struct xnthread *	thread,
		const struct xnthread_init_attr *	attr,
		struct xnsched_class *	sched_class,
		const union xnsched_policy_param *	sched_param
	)

Initialize a new thread.

Initializes a new thread. The thread is left dormant until it is actually started by xnthread_start().

Parameters

thread The address of a thread descriptor Cobalt will use to store the thread-specific data. This descriptor must always be valid while the thread is active therefore it must be allocated in permanent memory.

Warning: Some architectures may require the descriptor to be properly aligned in memory; this is an additional reason for descriptors not to be laid in the program stack where alignement constraints might not always be satisfied.

Parameters

attr	A pointer to an attribute block describing the initial properties of the new thread. Members of this structure are defined as follows:

name: An ASCII string standing for the symbolic name of the thread. This name is copied to a safe place into the thread descriptor. This name might be used in various situations by Cobalt for issuing human-readable diagnostic messages, so it is usually a good idea to provide a sensible value here. NULL is fine though and means "anonymous".
flags: A set of creation flags affecting the operation. The following flags can be part of this bitmask:
- XNSUSP creates the thread in a suspended state. In such a case, the thread shall be explicitly resumed using the xnthread_resume() service for its execution to actually begin, additionally to issuing xnthread_start() for it. This flag can also be specified when invoking xnthread_start() as a starting mode.
XNUSER shall be set if thread will be mapped over an existing user-space task. Otherwise, a new kernel host task is created, then paired with the new Xenomai thread.
XNFPU (enable FPU) tells Cobalt that the new thread may use the floating-point unit. XNFPU is implicitly assumed for user-space threads even if not set in flags.
affinity: The processor affinity of this thread. Passing CPU_MASK_ALL means "any cpu" from the allowed core affinity mask (cobalt_cpu_affinity). Passing an empty set is invalid.

Parameters

sched_class	The initial scheduling class the new thread should be assigned to.
sched_param	The initial scheduling parameters to set for the new thread; sched_param must be valid within the context of sched_class.

Returns: 0 is returned on success. Otherwise, the following error code indicates the cause of the failure:

-EINVAL is returned if attr->flags has invalid bits set, or attr->affinity is invalid (e.g. empty).

Tags: secondary-only

References XNFPU, XNSUSP, and XNUSER.

◆ xnthread_join()

int xnthread_join	(	struct xnthread *	thread,
		bool	uninterruptible
	)

Join with a terminated thread.

This service waits for thread to terminate after a call to xnthread_cancel(). If that thread has already terminated or is dormant at the time of the call, then xnthread_join() returns immediately.

xnthread_join() adapts to the calling context (primary or secondary), switching to secondary mode if needed for the duration of the wait. Upon return, the original runtime mode is restored, unless a Linux signal is pending.

Parameters

thread	The descriptor address of the thread to join with.
uninterruptible	Boolean telling whether the service should wait for completion uninterruptible.

Returns: 0 is returned on success. Otherwise, the following error codes indicate the cause of the failure:

-EDEADLK is returned if the current thread attempts to join itself.
-EINTR is returned if the current thread was unblocked while waiting for thread to terminate.
-EBUSY indicates that another thread is already waiting for thread to terminate.

Tags: task-unrestricted, might-switch

◆ xnthread_map()

int xnthread_map	(	struct xnthread *	thread,
		struct completion *	done
	)

Create a shadow thread context over a kernel task.

This call maps a Cobalt core thread to the "current" Linux task running in kernel space. The priority and scheduling class of the underlying Linux task are not affected; it is assumed that the caller did set them appropriately before issuing the shadow mapping request.

This call immediately moves the calling kernel thread to the Xenomai domain.

Parameters

thread	The descriptor address of the new shadow thread to be mapped to "current". This descriptor must have been previously initialized by a call to xnthread_init().
done	A completion object to be signaled when thread is fully mapped over the current Linux context, waiting for xnthread_start().

Returns: 0 is returned on success. Otherwise:

-ERESTARTSYS is returned if the current Linux task has received a signal, thus preventing the final migration to the Xenomai domain (i.e. in order to process the signal in the Linux domain). This error should not be considered as fatal.
-EPERM is returned if the shadow thread has been killed before the current task had a chance to return to the caller. In such a case, the real-time mapping operation has failed globally, and no Xenomai resource remains attached to it.
-EINVAL is returned if the thread control block bears the XNUSER bit.
-EBUSY is returned if either the current Linux task or the associated shadow thread is already involved in a shadow mapping.

Tags: secondary-only, might-switch

◆ xnthread_relax()

void xnthread_relax	(	int	notify,
		int	reason
	)

Switch a shadow thread back to the Linux domain.

This service yields the control of the running shadow back to Linux. This is obtained by suspending the shadow and scheduling a wake up call for the mated user task inside the Linux domain. The Linux task will resume on return from xnthread_suspend() on behalf of the root thread.

Parameters

notify	A boolean flag indicating whether threads monitored from secondary mode switches should be sent a SIGDEBUG signal. For instance, some internal operations like task exit should not trigger such signal.
reason	The reason to report along with the SIGDEBUG signal.

Tags: primary-only, might-switch

Note: "current" is valid here since the shadow runs with the properties of the Linux task.

◆ xnthread_resume()

void xnthread_resume	(	struct xnthread *	thread,
		int	mask
	)

Resume a thread.

Resumes the execution of a thread previously suspended by one or more calls to xnthread_suspend(). This call removes a suspensive condition affecting the target thread. When all suspensive conditions are gone, the thread is left in a READY state at which point it becomes eligible anew for scheduling.

Parameters

thread	The descriptor address of the resumed thread.
mask	The suspension mask specifying the suspensive condition to remove from the thread's wait mask. Possible values usable by the caller are:

XNSUSP. This flag removes the explicit suspension condition. This condition might be additive to the XNPEND condition.
XNDELAY. This flag removes the counted delay wait condition.
XNPEND. This flag removes the resource wait condition. If a watchdog is armed, it is automatically disarmed by this call. Unlike the two previous conditions, only the current thread can set this condition for itself, i.e. no thread can force another one to pend on a resource.

When the thread is eventually resumed by one or more calls to xnthread_resume(), the caller of xnthread_suspend() in the awakened thread that suspended itself should check for the following bits in its own information mask to determine what caused its wake up:

XNRMID means that the caller must assume that the pended synchronization object has been destroyed (see xnsynch_flush()).
XNTIMEO means that the delay elapsed, or the watchdog went off before the corresponding synchronization object was signaled.
XNBREAK means that the wait has been forcibly broken by a call to xnthread_unblock().

Tags: unrestricted, might-switch

◆ xnthread_set_mode()

int xnthread_set_mode	(	int	clrmask,
		int	setmask
	)

Change control mode of the current thread.

Change the control mode of the current thread. The control mode affects several behaviours of the Cobalt core regarding this thread.

Parameters

clrmask	Clears the corresponding bits from the control mode before setmask is applied. The scheduler lock held by the current thread can be forcibly released by passing the XNLOCK bit in this mask. In this case, the lock nesting count is also reset to zero.
setmask	The new thread mode. The following flags may be set in this bitmask:

XNLOCK makes the current thread non-preemptible by other threads. Unless XNTRAPLB is also set for the thread, the latter may still block, dropping the lock temporarily, in which case, the lock will be reacquired automatically when the thread resumes execution.
XNWARN enables debugging notifications for the current thread. A SIGDEBUG (Linux-originated) signal is sent when the following atypical or abnormal behavior is detected:
- the current thread switches to secondary mode. Such notification comes in handy for detecting spurious relaxes.
- CONFIG_XENO_OPT_DEBUG_MUTEX_RELAXED is enabled in the kernel configuration, and the current thread is sleeping on a Cobalt mutex currently owned by a thread running in secondary mode, which reveals a priority inversion.
- the current thread is about to sleep while holding a Cobalt mutex, and CONFIG_XENO_OPT_DEBUG_MUTEX_SLEEP is enabled in the kernel configuration. Blocking for acquiring a mutex does not trigger such a signal though.
- the current thread has both XNTRAPLB and XNLOCK set, and attempts to block on a Cobalt service, which would cause a lock break.
XNTRAPLB disallows breaking the scheduler lock. In the default case, a thread which holds the scheduler lock is allowed to drop it temporarily for sleeping. If this mode bit is set, such thread would return immediately with XNBREAK set from xnthread_suspend(). If XNWARN is set for the current thread, SIGDEBUG is sent in addition to raising the break condition.

Tags: primary-only, might-switch

Note: Setting clrmask and setmask to zero leads to a nop, in which case xnthread_set_mode() returns the current mode.

◆ xnthread_set_periodic()

int xnthread_set_periodic	(	struct xnthread *	thread,
		xnticks_t	idate,
		xntmode_t	timeout_mode,
		xnticks_t	period
	)

Make a thread periodic.

Make a thread periodic by programming its first release point and its period in the processor time line. Subsequent calls to xnthread_wait_period() will delay the thread until the next periodic release point in the processor timeline is reached.

Parameters

thread	The core thread to make periodic. If NULL, the current thread is assumed.
idate	The initial (absolute) date of the first release point, expressed in nanoseconds. The affected thread will be delayed by the first call to xnthread_wait_period() until this point is reached. If idate is equal to XN_INFINITE, the first release point is set to period nanoseconds after the current date. In the latter case, timeout_mode is not considered and can have any valid value.
timeout_mode	The mode of the idate parameter. It can either be set to XN_ABSOLUTE or XN_REALTIME with idate different from XN_INFINITE (see also xntimer_start()).
period	The period of the thread, expressed in nanoseconds. As a side-effect, passing XN_INFINITE attempts to stop the thread's periodic timer; in the latter case, the routine always exits succesfully, regardless of the previous state of this timer.

Returns: 0 is returned upon success. Otherwise:

-ETIMEDOUT is returned idate is different from XN_INFINITE and represents a date in the past.
-EINVAL is returned if period is different from XN_INFINITE but shorter than the scheduling latency value for the target system, as available from /proc/xenomai/latency. -EINVAL is also returned if timeout_mode is not compatible with idate, such as XN_RELATIVE with idate different from XN_INFINITE.
-EPERM is returned if thread is NULL, but the caller is not a Xenomai thread.

Tags: task-unrestricted

◆ xnthread_set_schedparam()

int xnthread_set_schedparam	(	struct xnthread *	thread,
		struct xnsched_class *	sched_class,
		const union xnsched_policy_param *	sched_param
	)

Change the base scheduling parameters of a thread.

Changes the base scheduling policy and paramaters of a thread. If the thread is currently blocked, waiting in priority-pending mode (XNSYNCH_PRIO) for a synchronization object to be signaled, Cobalt will attempt to reorder the object's wait queue so that it reflects the new sleeper's priority, unless the XNSYNCH_DREORD flag has been set for the pended object.

Parameters

thread	The descriptor address of the affected thread. See note.
sched_class	The new scheduling class the thread should be assigned to.
sched_param	The scheduling parameters to set for the thread; sched_param must be valid within the context of sched_class.

It is absolutely required to use this service to change a thread priority, in order to have all the needed housekeeping chores correctly performed. i.e. Do not call xnsched_set_policy() directly or worse, change the thread.cprio field by hand in any case.

Returns: 0 is returned on success. Otherwise, a negative error code indicates the cause of a failure that happened in the scheduling class implementation for sched_class. Invalid parameters passed into sched_param are common causes of error.

Side effects

This service does not call the rescheduling procedure but may affect the state of the run queue for the previous and new scheduling classes.
Assigning the same scheduling class and parameters to a running or ready thread moves it to the end of the run queue, thus causing a manual round-robin, except if a priority boost is undergoing.

Tags: task-unregistred

Note: The changes only apply to the Xenomai scheduling parameters for thread. There is no propagation/translation of such changes to the Linux scheduler for the task mated to the Xenomai target thread.

◆ xnthread_set_slice()

int xnthread_set_slice	(	struct xnthread *	thread,
		xnticks_t	quantum
	)

Set thread time-slicing information.

Update the time-slicing information for a given thread. This service enables or disables round-robin scheduling for the thread, depending on the value of quantum. By default, times-slicing is disabled for a new thread initialized by a call to xnthread_init().

Parameters

thread	The descriptor address of the affected thread.
quantum	The time quantum assigned to the thread expressed in nanoseconds. If quantum is different from XN_INFINITE, the time-slice for the thread is set to that value and its current time credit is refilled (i.e. the thread is given a full time-slice to run next). Otherwise, if quantum equals XN_INFINITE, time-slicing is stopped for that thread.

Returns: 0 is returned upon success. Otherwise, -EINVAL is returned if quantum is not XN_INFINITE and:

the base scheduling class of the target thread does not support time-slicing,
quantum is smaller than the master clock gravity for a user thread, which denotes a spurious value.

Tags: task-unrestricted

◆ xnthread_start()

int xnthread_start	(	struct xnthread *	thread,
		const struct xnthread_start_attr *	attr
	)

Start a newly created thread.

Starts a (newly) created thread, scheduling it for the first time. This call releases the target thread from the XNDORMANT state. This service also sets the initial mode for the new thread.

Parameters

thread	The descriptor address of the started thread which must have been previously initialized by a call to xnthread_init().
attr	A pointer to an attribute block describing the execution properties of the new thread. Members of this structure are defined as follows:

mode: The initial thread mode. The following flags can be part of this bitmask:
- XNLOCK causes the thread to lock the scheduler when it starts. The target thread will have to call the xnsched_unlock() service to unlock the scheduler. A non-preemptible thread may still block, in which case, the lock is reasserted when the thread is scheduled back in.
- XNSUSP makes the thread start in a suspended state. In such a case, the thread will have to be explicitly resumed using the xnthread_resume() service for its execution to actually begin.
entry: The address of the thread's body routine. In other words, it is the thread entry point.
cookie: A user-defined opaque cookie Cobalt will pass to the emerging thread as the sole argument of its entry point.

Return values

0	if thread could be started ;
-EBUSY	if thread was not dormant or stopped ;

Tags: task-unrestricted, might-switch

◆ xnthread_suspend()

void xnthread_suspend	(	struct xnthread *	thread,
		int	mask,
		xnticks_t	timeout,
		xntmode_t	timeout_mode,
		struct xnsynch *	wchan
	)

Suspend a thread.

Suspends the execution of a thread according to a given suspensive condition. This thread will not be eligible for scheduling until it all the pending suspensive conditions set by this service are removed by one or more calls to xnthread_resume().

Parameters

thread	The descriptor address of the suspended thread.
mask	The suspension mask specifying the suspensive condition to add to the thread's wait mask. Possible values usable by the caller are:

XNSUSP. This flag forcibly suspends a thread, regardless of any resource to wait for. A reverse call to xnthread_resume() specifying the XNSUSP bit must be issued to remove this condition, which is cumulative with other suspension bits.wchan should be NULL when using this suspending mode.
XNDELAY. This flags denotes a counted delay wait (in ticks) which duration is defined by the value of the timeout parameter.
XNPEND. This flag denotes a wait for a synchronization object to be signaled. The wchan argument must points to this object. A timeout value can be passed to bound the wait. This suspending mode should not be used directly by the client interface, but rather through the xnsynch_sleep_on() call.

Parameters

timeout The timeout which may be used to limit the time the thread pends on a resource. This value is a wait time given in nanoseconds. It can either be relative, absolute monotonic, or absolute adjustable depending on timeout_mode.

Passing XN_INFINITE and setting timeout_mode to XN_RELATIVE specifies an unbounded wait. All other values are used to initialize a watchdog timer. If the current operation mode of the system timer is oneshot and timeout elapses before xnthread_suspend() has completed, then the target thread will not be suspended, and this routine leads to a null effect.

Parameters

timeout_mode	The mode of the timeout parameter. It can either be set to XN_RELATIVE, XN_ABSOLUTE, or XN_REALTIME (see also xntimer_start()).
wchan	The address of a pended resource. This parameter is used internally by the synchronization object implementation code to specify on which object the suspended thread pends. NULL is a legitimate value when this parameter does not apply to the current suspending mode (e.g. XNSUSP).

Note: If the target thread has received a Linux-originated signal, then this service immediately exits without suspending the thread, but raises the XNBREAK condition in its information mask.

Tags: unrestricted, might-switch

◆ xnthread_test_cancel()

void xnthread_test_cancel ( void )

inlinestatic

Introduce a thread cancellation point.

Terminates the current thread if a cancellation request is pending for it, i.e. if xnthread_cancel() was called.

Tags: mode-unrestricted

◆ xnthread_unblock()

int xnthread_unblock ( struct xnthread * thread )

Unblock a thread.

Breaks the thread out of any wait it is currently in. This call removes the XNDELAY and XNPEND suspensive conditions previously put by xnthread_suspend() on the target thread. If all suspensive conditions are gone, the thread is left in a READY state at which point it becomes eligible anew for scheduling.

Parameters

thread The descriptor address of the unblocked thread.

This call neither releases the thread from the XNSUSP, XNRELAX, XNDORMANT or XNHELD suspensive conditions.

When the thread resumes execution, the XNBREAK bit is set in the unblocked thread's information mask. Unblocking a non-blocked thread is perfectly harmless.

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

Tags: unrestricted, might-switch

◆ xnthread_wait_period()

int xnthread_wait_period ( unsigned long * overruns_r )

Wait for the next periodic release point.

Make the current thread wait for the next periodic release point in the processor time line.

Parameters

overruns_r If non-NULL, overruns_r must be a pointer to a memory location which will be written with the count of pending overruns. This value is copied only when xnthread_wait_period() returns -ETIMEDOUT or success; the memory location remains unmodified otherwise. If NULL, this count will never be copied back.

Returns: 0 is returned upon success; if overruns_r is valid, zero is copied to the pointed memory location. Otherwise:

-EWOULDBLOCK is returned if xnthread_set_periodic() has not previously been called for the calling thread.
-EINTR is returned if xnthread_unblock() has been called for the waiting thread before the next periodic release point has been reached. In this case, the overrun counter is reset too.
-ETIMEDOUT is returned if the timer has overrun, which indicates that one or more previous release points have been missed by the calling thread. If overruns_r is valid, the count of pending overruns is copied to the pointed memory location.

Tags: primary-only, might-switch

Modules

Functions

Detailed Description

Function Documentation

◆ xnthread_cancel()

◆ xnthread_current()

◆ xnthread_from_task()

◆ xnthread_harden()

◆ xnthread_init()

◆ xnthread_join()

◆ xnthread_map()

◆ xnthread_relax()

◆ xnthread_resume()

◆ xnthread_set_mode()

◆ xnthread_set_periodic()

◆ xnthread_set_schedparam()

◆ xnthread_set_slice()

◆ xnthread_start()

◆ xnthread_suspend()

◆ xnthread_test_cancel()

◆ xnthread_unblock()

◆ xnthread_wait_period()