Collaboration diagram for Real-time pod services.:

Data Structures
struct	xnpod
	Real-time pod descriptor. More...
Files
file	pod.h
	Real-time pod interface header.
file	pod.c
	Real-time pod services.
Functions
int	xnpod_init (void)
	Initialize the core pod.
int	xnpod_enable_timesource (void)
	Activate the core time source.
void	xnpod_disable_timesource (void)
	Stop the core time source.
void	xnpod_shutdown (int xtype)
	Shutdown the current pod.
int	xnpod_init_thread (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.
int	xnpod_start_thread (xnthread_t thread, const struct xnthread_start_attr attr)
	Initial start of a newly created thread.
void	xnpod_stop_thread (xnthread_t *thread)
	Stop a thread.
void	xnpod_restart_thread (xnthread_t *thread)
	Restart a thread.
void	xnpod_delete_thread (xnthread_t *thread)
	Delete a thread.
void	xnpod_abort_thread (xnthread_t *thread)
	Abort a thread.
xnflags_t	xnpod_set_thread_mode (xnthread_t *thread, xnflags_t clrmask, xnflags_t setmask)
	Change a thread's control mode.
void	xnpod_suspend_thread (xnthread_t thread, xnflags_t mask, xnticks_t timeout, xntmode_t timeout_mode, struct xnsynch wchan)
	Suspend a thread.
void	xnpod_resume_thread (xnthread_t *thread, xnflags_t mask)
	Resume a thread.
int	xnpod_unblock_thread (xnthread_t *thread)
	Unblock a thread.
int	xnpod_set_thread_schedparam (struct xnthread thread, struct xnsched_class sched_class, const union xnsched_policy_param *sched_param)
	Change the base scheduling parameters of a thread.
int	xnpod_migrate_thread (int cpu)
	Migrate the current thread.
void	xnpod_dispatch_signals (void)
	Deliver pending asynchronous signals to the running thread.
static void	xnpod_schedule (void)
	Rescheduling procedure entry point.
int	xnpod_set_thread_periodic (xnthread_t *thread, xnticks_t idate, xnticks_t period)
	Make a thread periodic.
int	xnpod_wait_thread_period (unsigned long *overruns_r)
	Wait for the next periodic release point.
int	xnpod_set_thread_tslice (struct xnthread *thread, xnticks_t quantum)
	Set thread time-slicing information.
int	xnpod_add_hook (int type, void(routine)(xnthread_t ))
	Install a nucleus hook.
int	xnpod_remove_hook (int type, void(routine)(xnthread_t ))
	Remove a nucleus hook.
void	xnpod_welcome_thread (xnthread_t *thread, int imask)
	Thread prologue.
int	xnpod_trap_fault (xnarch_fltinfo_t *fltinfo)
	Default fault handler.

Detailed Description

Real-time pod services.

Function Documentation

void xnpod_abort_thread ( xnthread_t * thread )

Abort a thread.

Unconditionally terminates a thread and releases all the nucleus resources it currently holds, regardless of whether the target thread is currently active in kernel or user-space. xnpod_abort_thread() should be reserved for use by skin cleanup routines; xnpod_delete_thread() should be preferred as the common method for removing threads from a running system.

Parameters:

thread The descriptor address of the terminated thread.

This service forces a call to xnpod_delete_thread() for the target thread.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible if the current thread self-deletes.

References XNABORT, XNDORMANT, xnpod_delete_thread(), and xnpod_suspend_thread().

int xnpod_add_hook	(	int	type,
		void()(xnthread_t )	routine
	)

Install a nucleus hook.

The nucleus allows to register user-defined routines which get called whenever a specific scheduling event occurs. Multiple hooks can be chained for a single event type, and get called on a FIFO basis.

The scheduling is locked while a hook is executing.

Parameters:

type	Defines the kind of hook to install:

XNHOOK_THREAD_START: The user-defined routine will be called on behalf of the starter thread whenever a new thread starts. The descriptor address of the started thread is passed to the routine.

XNHOOK_THREAD_DELETE: The user-defined routine will be called on behalf of the deletor thread whenever a thread is deleted. The descriptor address of the deleted thread is passed to the routine.

XNHOOK_THREAD_SWITCH: The user-defined routine will be called on behalf of the resuming thread whenever a context switch takes place. The descriptor address of the thread which has been switched out is passed to the routine.

Parameters:

routine The address of the user-supplied routine to call.

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

-EINVAL is returned if type is incorrect.

-ENOMEM is returned if not enough memory is available from the system heap to add the new hook.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: never.

Referenced by rt_task_add_hook().

void xnpod_delete_thread ( xnthread_t * thread )

Delete a thread.

Terminates a thread and releases all the nucleus resources it currently holds. A thread exists in the system since xnpod_init_thread() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:

thread The descriptor address of the terminated thread.

The target thread's resources may not be immediately removed if this is an active shadow thread running in user-space. In such a case, the mated Linux task is sent a termination signal instead, and the actual deletion is deferred until the task exit event is called.

The DELETE hooks are called on behalf of the calling context (if any). The information stored in the thread control block remains valid until all hooks have been called.

Self-terminating a thread is allowed. In such a case, this service does not return to the caller.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible if the current thread self-deletes.

References xnsched::curr, xnsched::status, XNABORT, XNCANPND, XNDEFCAN, XNDORMANT, XNMIGRATE, XNPEND, xnpod_schedule(), xnpod_unblock_thread(), XNREADY, XNROOT, xnselector_destroy(), xnsynch_forget_sleeper(), xnsynch_release_all_ownerships(), xntimer_destroy(), and XNZOMBIE.

Referenced by rt_task_create(), rt_task_delete(), rtdm_task_init(), xnpod_abort_thread(), and xnpod_shutdown().

void xnpod_disable_timesource ( void )

Stop the core time source.

Releases the hardware timer, and deactivates the master time base.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
User-space task in secondary mode

Rescheduling: never.

References xntimer_freeze().

Referenced by xnpod_shutdown().

void xnpod_dispatch_signals ( void )

Deliver pending asynchronous signals to the running thread.

This internal routine checks for the presence of asynchronous signals directed to the running thread, and attempts to start the asynchronous service routine (ASR) if any. Called with nklock locked, interrupts off.

References XNASDI.

Referenced by xnpod_welcome_thread(), and xnshadow_harden().

int xnpod_enable_timesource ( void )

Activate the core time source.

Xenomai implements the notion of time base, by which software timers that belong to different skins may be clocked separately according to distinct frequencies, or aperiodically. In the periodic case, delays and timeouts are given in counts of ticks; the duration of a tick is specified by the time base. In the aperiodic case, timings are directly specified in nanoseconds.

Only a single aperiodic (i.e. tick-less) time base may exist in the system, and the nucleus provides for it through the nktbase object. All skins depending on aperiodic timings should bind to the latter, also known as the master time base. Skins depending on periodic timings may create and bind to their own time base. Such a periodic time base is managed as a slave object of the master one. A cascading software timer, which is fired by the master time base according to the appropriate frequency, triggers in turn the update process of the associated slave time base, which eventually fires the elapsed software timers controlled by the latter.

Xenomai always controls the underlying hardware timer in a tick-less fashion, also known as the oneshot mode. The xnpod_enable_timesource() service configures the timer chip as needed, and activates the master time base.

Returns:: 0 is returned on success. Otherwise:

-ENODEV is returned if a failure occurred while configuring the hardware timer.

-ENOSYS is returned if no active pod exists.

Side-effect: A host timing service is started in order to relay the canonical periodical tick to the underlying architecture, regardless of the frequency used for Xenomai's system tick. This routine does not call the rescheduling procedure.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
User-space task in secondary mode

Rescheduling: never.

Note:: Built-in support for periodic timing depends on CONFIG_XENO_OPT_TIMING_PERIODIC.

References xnsched::htimer, xnintr_init(), and xntimer_start().

Referenced by xnpod_init().

int xnpod_init ( void )

Initialize the core pod.

Initializes the core interface pod which can subsequently be used to start real-time activities. Once the core pod is active, real-time skins can be stacked over. There can only be a single core pod active in the host environment. Such environment can be confined to a process (e.g. simulator), or expand machine-wide (e.g. I-pipe).

Returns:: 0 is returned on success. Otherwise:

-ENOMEM is returned if the memory manager fails to initialize.

Environments:

This service can be called from:

Kernel module initialization code

References xnpod::refcnt, xnsched::rootcb, xnpod::sched, xnpod::status, xnpod::tdeleteq, xnpod::threadq, xnpod::timerlck, xnpod::tsliced, xnpod::tslicer, xnpod::tstartq, xnpod::tswitchq, xnheap_destroy(), xnheap_init(), xnheap_set_label(), xnpod_enable_timesource(), xnpod_shutdown(), and xntimer_init().

int xnpod_init_thread	(	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 attached to the active pod. The thread is left in an innocuous state until it is actually started by xnpod_start_thread().

Parameters:

thread The address of a thread descriptor the nucleus 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 the nucleus for issuing human-readable diagnostic messages, so it is usually a good idea to provide a sensible value here. The simulator even uses this name intensively to identify threads in the debugging GUI it provides. However, passing NULL here is always legal and means "anonymous".

tbase: The time base descriptor to refer to for all timed operations issued by the new thread. See xntbase_alloc() for detailed explanations about time bases.

flags: A set of creation flags affecting the operation. The following flags can be part of this bitmask, each of them affecting the nucleus behaviour regarding the created thread:

XNSUSP creates the thread in a suspended state. In such a case, the thread will have to be explicitly resumed using the xnpod_resume_thread() service for its execution to actually begin, additionally to issuing xnpod_start_thread() for it. This flag can also be specified when invoking xnpod_start_thread() as a starting mode.

XNFPU (enable FPU) tells the nucleus that the new thread will use the floating-point unit. In such a case, the nucleus will handle the FPU context save/restore ops upon thread switches at the expense of a few additional cycles per context switch. By default, a thread is not expected to use the FPU. This flag is simply ignored when the nucleus runs on behalf of a userspace-based real-time control layer since the FPU management is always active if present.

stacksize: The size of the stack (in bytes) for the new thread. If zero is passed, the nucleus will use a reasonable pre-defined size depending on the underlying real-time control layer.

ops: A pointer to a structure defining the class-level operations available for this thread. Fields from this structure must have been set appropriately by the caller.

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, one of the following error codes indicates the cause of the failure:

-EINVAL is returned if attr->flags has invalid bits set.

-ENOMEM is returned if not enough memory is available from the system heap to create the new thread's stack.

Side-effect: This routine does not call the rescheduling procedure.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: never.

References XNDORMANT, XNFPU, xnpod_suspend_thread(), XNSHADOW, and XNSUSP.

Referenced by pthread_create(), rt_task_create(), and rtdm_task_init().

int xnpod_migrate_thread ( int cpu )

Migrate the current thread.

This call makes the current thread migrate to another CPU if its affinity allows it.

Parameters:

cpu	The destination CPU.

Return values:

0	if the thread could migrate ;
-EPERM	if the calling context is asynchronous, or the current thread affinity forbids this migration ;
-EBUSY	if the scheduler is locked.

References xnpod_schedule().

int xnpod_remove_hook	(	int	type,
		void()(xnthread_t )	routine
	)

Remove a nucleus hook.

This service removes a nucleus hook previously registered using xnpod_add_hook().

Parameters:

type	Defines the kind of hook to remove among XNHOOK_THREAD_START, XNHOOK_THREAD_DELETE and XNHOOK_THREAD_SWITCH.
routine	The address of the user-supplied routine to remove.

Returns:: 0 is returned on success. Otherwise, -EINVAL is returned if type is incorrect or if the routine has never been registered before.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: never.

Referenced by rt_task_remove_hook().

void xnpod_restart_thread ( xnthread_t * thread )

Restart a thread.

Restarts a previously started thread. The thread is first terminated then respawned using the same information that prevailed when it was first started, including the mode bits and interrupt mask initially passed to the xnpod_start_thread() service. As a consequence of this call, the thread entry point is rerun.

Parameters:

thread The descriptor address of the affected thread which must have been previously started by the xnpod_start_thread() service.

Self-restarting a thread is allowed. However, restarting the root thread is not. Restarting a thread which was never started once leads to a null-effect.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task

Rescheduling: possible.

References xnpod_schedule(), XNRESTART, XNROOT, XNSHADOW, and XNSTARTED.

void xnpod_resume_thread	(	xnthread_t *	thread,
		xnflags_t	mask
	)

Resume a thread.

Resumes the execution of a thread previously suspended by one or more calls to xnpod_suspend_thread(). 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 xnpod_resume_thread(), the caller of xnpod_suspend_thread() 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 xnpod_unblock_thread().

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task
User-space task

Rescheduling: never.

References xnsched::curr, XNDELAY, XNHELD, XNPEND, XNREADY, xnsynch_forget_sleeper(), and xntimer_stop().

Referenced by rt_task_resume(), xnpod_start_thread(), xnpod_unblock_thread(), xnsynch_flush(), xnsynch_release(), xnsynch_wakeup_one_sleeper(), and xnsynch_wakeup_this_sleeper().

void xnpod_schedule ( void ) [inline, static]

Rescheduling procedure entry point.

This is the central rescheduling routine which should be called to validate and apply changes which have previously been made to the nucleus scheduling state, such as suspending, resuming or changing the priority of threads. This call first determines if a thread switch should take place, and performs it as needed. xnpod_schedule() schedules out the current thread if:

the current thread is now blocked or deleted.
a runnable thread from a higher priority scheduling class is waiting for the CPU.
the current thread does not lead the runnable threads from its own scheduling class (e.g. round-robin in the RT class).

The nucleus implements a lazy rescheduling scheme so that most of the services affecting the threads state MUST be followed by a call to the rescheduling procedure for the new scheduling state to be applied. In other words, multiple changes on the scheduler state can be done in a row, waking threads up, blocking others, without being immediately translated into the corresponding context switches, like it would be necessary would it appear that a higher priority thread than the current one became runnable for instance. When all changes have been applied, the rescheduling procedure is then called to consider those changes, and possibly replace the current thread by another one.

As a notable exception to the previous principle however, every action which ends up suspending or deleting the current thread begets an immediate call to the rescheduling procedure on behalf of the service causing the state transition. For instance, self-suspension, self-destruction, or sleeping on a synchronization object automatically leads to a call to the rescheduling procedure, therefore the caller does not need to explicitly issue xnpod_schedule() after such operations.

The rescheduling procedure always leads to a null-effect if it is called on behalf of an ISR or callout. Any outstanding scheduler lock held by the outgoing thread will be restored when the thread is scheduled back in.

Calling this procedure with no applicable context switch pending is harmless and simply leads to a null-effect.

Side-effects:

If an asynchronous service routine exists, the pending asynchronous signals are delivered to a resuming thread or on behalf of the caller before it returns from the procedure if no context switch has taken place. This behaviour can be disabled by setting the XNASDI flag in the thread's status mask by calling xnpod_set_thread_mode().

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine, although this leads to a no-op.
Kernel-based task
User-space task

Note:: The switch hooks are called on behalf of the resuming thread.

References xnsched::lflags, and xnsched::status.

Referenced by pthread_cancel(), pthread_cond_broadcast(), pthread_cond_signal(), pthread_detach(), pthread_join(), pthread_kill(), pthread_mutex_unlock(), pthread_set_mode_np(), pthread_setschedparam(), pthread_setschedparam_ex(), pthread_sigmask(), pthread_sigqueue_np(), rt_alarm_delete(), rt_buffer_clear(), rt_buffer_delete(), rt_cond_broadcast(), rt_cond_delete(), rt_cond_signal(), rt_event_delete(), rt_event_signal(), rt_heap_free(), rt_intr_delete(), rt_mutex_delete(), rt_mutex_release(), rt_queue_send(), rt_sem_broadcast(), rt_sem_delete(), rt_sem_v(), rt_task_catch(), rt_task_notify(), rt_task_reply(), rt_task_resume(), rt_task_set_mode(), rt_task_set_priority(), rt_task_unblock(), rtdm_event_signal(), rtdm_sem_up(), sem_post(), xnpod_delete_thread(), xnpod_migrate_thread(), xnpod_restart_thread(), xnpod_shutdown(), xnpod_start_thread(), xnpod_stop_thread(), xnpod_suspend_thread(), xnregistry_enter(), xnregistry_put(), xnselect_bind(), and xnselect_destroy().

xnflags_t xnpod_set_thread_mode	(	xnthread_t *	thread,
		xnflags_t	clrmask,
		xnflags_t	setmask
	)

Change a thread's control mode.

Change the control mode of a given thread. The control mode affects the behaviour of the nucleus regarding the specified thread.

Parameters:

thread	The descriptor address of the affected thread.
clrmask	Clears the corresponding bits from the control field 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 can be part of this bitmask, each of them affecting the nucleus behaviour regarding the thread:

XNLOCK causes the thread to lock the scheduler. The target thread will have to call the xnpod_unlock_sched() service to unlock the scheduler or clear the XNLOCK bit forcibly using this service. A non-preemptible thread may still block, in which case, the lock is reasserted when the thread is scheduled back in.

XNASDI disables the asynchronous signal handling for this thread. See xnpod_schedule() for more on this.

XNRPIOFF disables thread priority coupling between Xenomai and Linux schedulers. This bit prevents the root Linux thread from inheriting the priority of the running shadow Xenomai thread. Use CONFIG_XENO_OPT_RPIOFF to globally disable priority coupling.

Environments:

This service can be called from:

Kernel-based task
User-space task in primary mode.

Rescheduling: never, therefore, the caller should reschedule if XNLOCK has been passed into clrmask.

References XNLOCK.

Referenced by pthread_set_mode_np(), and rt_task_set_mode().

int xnpod_set_thread_periodic	(	xnthread_t *	thread,
		xnticks_t	idate,
		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 xnpod_wait_thread_period() will delay the thread until the next periodic release point in the processor timeline is reached.

Parameters:

thread	The descriptor address of the affected thread. This thread is immediately delayed until the first periodic release point is reached.
idate	The initial (absolute) date of the first release point, expressed in clock ticks (see note). The affected thread will be delayed until this point is reached. If idate is equal to XN_INFINITE, the current system date is used, and no initial delay takes place.
period	The period of the thread, expressed in clock ticks (see note). 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.

-EWOULDBLOCK is returned if the relevant time base has not been initialized by a call to xnpod_init_timebase().

-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.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible if the operation affects the current thread and idate has not elapsed yet.

Note:: The idate and period values will be interpreted as jiffies if thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.

References XNDELAY, xnpod_suspend_thread(), xntimer_start(), and xntimer_stop().

Referenced by pthread_make_periodic_np(), rt_task_set_periodic(), and rtdm_task_init().

int xnpod_set_thread_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, the nucleus 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.
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 runnable 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 runnable queue, thus causing a manual round-robin.

If the thread is a user-space shadow, this call propagates the request to the mated Linux task.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task
User-space task

Rescheduling: never.

Referenced by pthread_setschedparam(), pthread_setschedparam_ex(), and rt_task_set_priority().

int xnpod_set_thread_tslice	(	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 xnpod_init_thread().

Parameters:

thread	The descriptor address of the affected thread.
quantum	The time quantum assigned to the thread expressed in time-slicing ticks (see note). 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 the base scheduling class of the target thread does not support time-slicing.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: never.

Note:: If thread is bound to a periodic timebase, quantum represents the number of periodic ticks in that timebase. Otherwise, if thread is bound to the master time base, a full time-slice will last: quantum * CONFIG_XENO_OPT_TIMING_VIRTICK.

References XNRRB, xntimer_start(), and xntimer_stop().

Referenced by pthread_create(), pthread_setschedparam(), pthread_setschedparam_ex(), and rt_task_slice().

void xnpod_shutdown ( int xtype )

Shutdown the current pod.

Forcibly shutdowns the active pod. All existing nucleus threads (but the root one) are terminated, and the system heap is freed.

Parameters:

xtype An exit code passed to the host environment who started the nucleus. Zero is always interpreted as a successful return.

The nucleus never calls this routine directly. Skins should provide their own shutdown handlers which end up calling xnpod_shutdown() after their own housekeeping chores have been carried out.

Environments:

This service can be called from:

Kernel module initialization/cleanup code

Rescheduling: never.

References xnheap_destroy(), xnpod_delete_thread(), xnpod_disable_timesource(), xnpod_schedule(), XNROOT, and xntimer_destroy().

Referenced by xnpod_init().

int xnpod_start_thread	(	xnthread_t *	thread,
		const struct xnthread_start_attr *	attr
	)

Initial start of 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 and interrupt mask for the new thread.

Parameters:

thread	The descriptor address of the affected thread which must have been previously initialized by the xnpod_init_thread() service.
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, each of them affecting the nucleus behaviour regarding the started thread:

XNLOCK causes the thread to lock the scheduler when it starts. The target thread will have to call the xnpod_unlock_sched() 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.

XNASDI disables the asynchronous signal handling for this thread. See xnpod_schedule() for more on this.

XNSUSP makes the thread start in a suspended state. In such a case, the thread will have to be explicitly resumed using the xnpod_resume_thread() service for its execution to actually begin.

imask: The interrupt mask that should be asserted when the thread starts. The processor interrupt state will be set to the given value when the thread starts running. The interpretation of this value might be different across real-time layers, but a non-zero value should always mark an interrupt masking in effect (e.g. local_irq_disable()). Conversely, a zero value should always mark a fully preemptible state regarding interrupts (e.g. local_irq_enable()).

affinity: The processor affinity of this thread. Passing XNPOD_ALL_CPUS or an empty affinity set means "any cpu".

entry: The address of the thread's body routine. In other words, it is the thread entry point.

cookie: A user-defined opaque cookie the nucleus will pass to the emerging thread as the sole argument of its entry point.

The START hooks are called on behalf of the calling context (if any).

Return values:

0	if thread could be started ;
-EBUSY	if thread was not dormant or stopped ;
-EINVAL	if the value of attr->affinity is invalid.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible.

References XNDORMANT, xnpod_resume_thread(), xnpod_schedule(), XNREADY, XNSHADOW, XNSTARTED, and XNSUSP.

Referenced by pthread_create(), rt_task_start(), rtdm_task_init(), and xnshadow_map().

void xnpod_stop_thread ( xnthread_t * thread )

Stop a thread.

Stop a previously started thread. The thread is put back into the dormant state; however, it is not deleted from the system.

Parameters:

thread The descriptor address of the affected thread which must have been previously started by the xnpod_start_thread() service.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: possible.

References XNDORMANT, xnpod_schedule(), xnpod_suspend_thread(), and XNROOT.

void xnpod_suspend_thread	(	xnthread_t *	thread,
		xnflags_t	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 xnpod_resume_thread().

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 xnpod_resume_thread() 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 ticks (see note). 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 xnpod_suspend_thread() has completed, then the target thread will not be suspended, and this routine leads to a null effect.
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 is a shadow which has received a Linux-originated signal, then this service immediately exits without suspending the thread, but raises the XNBREAK condition in its information mask.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task
User-space task

Rescheduling: possible if the current thread suspends itself.

Note:: The timeout value will be interpreted as jiffies if thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.

References xnsched::curr, XNBREAK, XNDELAY, XNDORMANT, XNHELD, XNKICKED, xnpod_schedule(), XNREADY, XNRELAX, XNRMID, XNROBBED, XNROOT, XNSHADOW, XNSUSP, xnsynch_forget_sleeper(), XNTIMEO, xntimer_start(), and XNWAKEN.

Referenced by clock_nanosleep(), rt_task_sleep(), rt_task_sleep_until(), rt_task_suspend(), xnpod_abort_thread(), xnpod_init_thread(), xnpod_set_thread_periodic(), xnpod_stop_thread(), xnpod_trap_fault(), xnpod_wait_thread_period(), xnshadow_map(), xnshadow_relax(), xnsynch_acquire(), and xnsynch_sleep_on().

void xnpod_trap_fault ( xnarch_fltinfo_t * fltinfo )

Default fault handler.

This is the default handler which is called whenever an uncontrolled exception or fault is caught. If the fault is caught on behalf of a real-time thread, the fault is not propagated to the host system. Otherwise, the fault is unhandled by the nucleus and simply propagated.

Parameters:

fltinfo An opaque pointer to the arch-specific buffer describing the fault. The actual layout is defined by the xnarch_fltinfo_t type in each arch-dependent layer file.

References xnpod_suspend_thread(), xnshadow_relax(), and XNSUSP.

int xnpod_unblock_thread ( xnthread_t * 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 xnpod_suspend_thread() 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.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Interrupt service routine
Kernel-based task
User-space task

Rescheduling: never.

References XNBREAK, XNDELAY, XNPEND, and xnpod_resume_thread().

Referenced by pthread_cancel(), rt_task_reply(), rt_task_unblock(), xnpod_delete_thread(), and xnshadow_mark_sig().

int xnpod_wait_thread_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 xnpod_wait_thread_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 xnpod_set_thread_periodic() has not previously been called for the calling thread.

-EINTR is returned if xnpod_unblock_thread() 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.

Environments:

This service can be called from:

Kernel module initialization/cleanup code
Kernel-based task
User-space task

Rescheduling: always, unless the current release point has already been reached. In the latter case, the current thread immediately returns from this service without being delayed.

References XNBREAK, XNDELAY, xnpod_suspend_thread(), and xntimer_get_overruns().

Referenced by pthread_wait_np(), and rt_task_wait_period().

void xnpod_welcome_thread	(	xnthread_t *	thread,
		int	imask
	)

Thread prologue.

This internal routine is called on behalf of a (re)starting thread's prologue before the user entry point is invoked. This call is reserved for internal housekeeping chores and cannot be inlined.

Entered with nklock locked, irqs off.

References XNLOCK, xnpod_dispatch_signals(), and XNRESTART.

Data Structures

Files

Functions

Detailed Description

Function Documentation