Real-time shadow services.

Collaboration diagram for Real-time shadow services.:

Files
file	shadow.c
	Real-time shadow services.
Functions
int	xnshadow_mark_sig (xnthread_t *thread, unsigned muxid)
	Mark the per-thread per-skin signal condition for the skin whose muxid is muxid.
void	xnshadow_clear_sig (xnthread_t *thread, unsigned muxid)
	Clear the per-thrad per-skin signal condition.
int	xnshadow_harden (void)
	Migrate a Linux task to the Xenomai domain.
void	xnshadow_relax (int notify, int reason)
	Switch a shadow thread back to the Linux domain.
int	xnshadow_map (xnthread_t *thread, xncompletion_t __user *u_completion, unsigned long __user *u_mode)
	Create a shadow thread context.
xnshadow_ppd_t *	xnshadow_ppd_get (unsigned muxid)
	Return the per-process data attached to the calling process.

---

Detailed Description

Real-time shadow services.

---

Function Documentation

void xnshadow_clear_sig	(	xnthread_t *	thread,
		unsigned	muxid
	)

Clear the per-thrad per-skin signal condition.

Called with nklock locked irqs off.

Parameters:

thread	the target thrad
muxid

int xnshadow_harden

(

void

)

Migrate a Linux task to the Xenomai domain.

This service causes the transition of "current" from the Linux domain to Xenomai. This is obtained by asking the gatekeeper to resume the shadow mated with "current" then triggering the rescheduling procedure in the Xenomai domain. The shadow will resume in the Xenomai domain as returning from schedule().

Environments:

This service can be called from:

• User-space thread operating in secondary (i.e. relaxed) mode.

Rescheduling: always.

References XNATOMIC, and xnpod_dispatch_signals().

Referenced by xnshadow_map().

int xnshadow_map	(	xnthread_t *	thread,
		xncompletion_t __user *	u_completion,
		unsigned long __user *	u_mode
	)

Create a shadow thread context.

This call maps a nucleus thread to the "current" Linux task. The priority and scheduling class of the underlying Linux task are not affected; it is assumed that the interface library did set them appropriately before issuing the shadow mapping request.

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 xnpod_init_thread().
u_completion	is the address of an optional completion descriptor aimed at synchronizing our parent thread with us. If non-NULL, the information xnshadow_map() will store into the completion block will be later used to wake up the parent thread when the current shadow has been initialized. In the latter case, the new shadow thread is left in a dormant state (XNDORMANT) after its creation, leading to the suspension of "current" in the Linux domain, only processing signals. Otherwise, the shadow thread is immediately started and "current" immediately resumes in the Xenomai domain from this service.
	u_mode is the address of a mode variable in user space that will reflect the current thread mode (primary or secondary). The nucleus will try to update the variable before switching to secondary or after switching from primary mode.

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 does not bear the XNSHADOW bit.

• -EBUSY is returned if either the current Linux task or the associated shadow thread is already involved in a shadow mapping.

Environments:

This service can be called from:

• Regular user-space process.

Rescheduling: always.

References XNMAPPED, xnpod_start_thread(), xnpod_suspend_thread(), XNPRIOSET, XNRELAX, XNSHADOW, and xnshadow_harden().

int xnshadow_mark_sig	(	xnthread_t *	thread,
		unsigned	muxid
	)

Mark the per-thread per-skin signal condition for the skin whose muxid is muxid.

Parameters:

thread	the target thread;
muxid	the muxid of the skin for which the signal is marked pending.

Returns:

whether rescheduling is needed.

References XNMAPPED, and xnpod_unblock_thread().

xnshadow_ppd_t* xnshadow_ppd_get

(

unsigned

muxid

)

Return the per-process data attached to the calling process.

This service returns the per-process data attached to the calling process for the skin whose muxid is muxid. It must be called with nklock locked, irqs off.

See xnshadow_register_interface() documentation for information on the way to attach a per-process data to a process.

Parameters:

muxid

the skin muxid.

Returns:

the per-process data if the current context is a user-space process;

NULL otherwise.

void xnshadow_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 xnpod_suspend_thread() 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.

Environments:

This service can be called from:

• User-space thread operating in primary (i.e. harden) mode.

Rescheduling: always.

Note:

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

References XNAFFSET, xnpod_suspend_thread(), XNPRIOSET, XNRELAX, XNROOT, and XNTRAPSW.

Referenced by pthread_set_mode_np(), and xnpod_trap_fault().