Real-time pod services.
[Xenomai scheduler.]


Detailed Description

Real-time pod services.


Files

file  pod.c
 Real-time pod services.

file  pod.h
 Real-time pod interface header.


Data Structures

struct  xnpod
 Real-time pod descriptor. More...

struct  xnsched
 Scheduling information structure. More...


Typedefs

typedef xnsched xnsched_t
 Scheduling information structure.

typedef xnpod xnpod_t
 Real-time pod descriptor.


Functions

void xnpod_schedule_runnable (xnthread_t *thread, int flags)
 Hidden rescheduling procedure - INTERNAL.

int xnpod_init (xnpod_t *pod, int minpri, int maxpri, xnflags_t flags)
 Initialize a new pod.

void xnpod_stop_timer (void)
 Stop the periodic timer.

void xnpod_shutdown (int xtype)
 Default shutdown handler.

int xnpod_init_thread (xnthread_t *thread, const char *name, int prio, xnflags_t flags, unsigned stacksize, void *adcookie, unsigned magic)
 Initialize a new thread.

void xnpod_start_thread (xnthread_t *thread, xnflags_t mode, int imask, void(*entry)(void *cookie), void *cookie)
 Initial start of a newly created thread.

xnflags_t xnpod_set_thread_mode (xnthread_t *thread, xnflags_t clrmask, xnflags_t setmask)
 Change a thread's control mode.

void xnpod_resume_thread (xnthread_t *thread, xnflags_t mask)
 Resume a thread.

void xnpod_unblock_thread (xnthread_t *thread)
 Unblock a thread.

void xnpod_renice_thread (xnthread_t *thread, int prio)
 Change the base priority of a thread.

void xnpod_rotate_readyq (int prio)
 Rotate a priority level in the ready queue.

void xnpod_activate_rr (xnticks_t quantum)
 Globally activate the round-robin scheduling.

void xnpod_deactivate_rr (void)
 Globally deactivate the round-robin scheduling.

void xnpod_set_time (xnticks_t newtime)
 Set the nanokernel idea of time.

xnticks_t xnpod_get_time (void)
 Get the nanokernel idea of time.

int xnpod_add_hook (int type, void(*routine)(xnthread_t *))
 Install a nanokernel hook.

int xnpod_remove_hook (int type, void(*routine)(xnthread_t *))
 Remove a nanokernel hook.

void xnpod_preempt_current_thread (void)
 Preempts the current thread - INTERNAL.

void xnpod_restart_thread (xnthread_t *thread, xnmutex_t *imutex)
 Restart a thread.

void xnpod_delete_thread (xnthread_t *thread, xnmutex_t *imutex)
 Delete a thread.

int xnpod_suspend_thread (xnthread_t *thread, xnflags_t mask, xnticks_t timeout, xnsynch_t *wchan, xnmutex_t *imutex)
 Suspend a thread.

void xnpod_dispatch_signals (void)
 Deliver pending asynchronous signals to the running thread - INTERNAL.

void xnpod_welcome_thread (xnthread_t *thread)
 Thread prologue - INTERNAL.

void xnpod_schedule (xnmutex_t *imutex)
 Rescheduling procedure entry point.

int xnpod_trap_fault (void *fltinfo)
 Default fault handler.

int xnpod_start_timer (u_long nstick, xnist_t tickhandler)
 Start the system timer.

void xnpod_announce_tick (xnintr_t *intr, int hits)
 Announce a new clock tick.


Typedef Documentation

typedef struct xnpod xnpod_t
 

Real-time pod descriptor.

The source of all Xenomai magic.


Function Documentation

void xnpod_activate_rr xnticks_t  quantum  ) 
 

Globally activate the round-robin scheduling.

This service activates the round-robin scheduling for all threads which have the XNRRB flag set in their status mask (see xnpod_set_thread_mode()). Each of them will run for the given time quantum, then preempted and moved at the end of its priority group in the ready queue. This process is repeated until the round-robin scheduling is disabled for those threads.

Parameters:
quantum The time credit which will be given to each rr-enabled thread (in ticks).
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine can be called on behalf of a thread or IST context.

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

Install a nanokernel hook.

The nanokernel 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:
XN_OK is returned on success. Otherwise, one of the following error codes indicates the cause of the failure:
  • XNERR_PARAM is returned if type is incorrect.

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

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

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_announce_tick xnintr_t *  intr,
int  hits
 

Announce a new clock tick.

This is the default service routine for clock ticks which performs the necessary housekeeping chores for time-related services managed by the nanokernel. In a way or another, this routine must be called to announce each incoming clock tick to the nanokernel.

Parameters:
intr The descriptor address of the interrupt object underlying the timer interrupt.
hits The number of pending interrupt hits to process in a row.
Side-effect: Since this routine manages the round-robin scheduling, the running thread (which has been preempted by the timer interrupt) can be switched out as a result of its time credit being exhausted. The nanokernel always calls the rescheduling procedure after the outer interrupt has been processed.

Context: The caller must have a valid nanokernel context (regular or interrupt service thread).

void xnpod_deactivate_rr void   ) 
 

Globally deactivate the round-robin scheduling.

This service deactivates the round-robin scheduling for all threads which have the XNRRB flag set in their status mask (see xnpod_set_thread_mode()).

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

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_delete_thread xnthread_t *  thread,
xnmutex_t *  imutex
 

Delete a thread.

Terminates a thread and releases all the nanokernel 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.
imutex The address of an interface mutex currently held by the caller which will be subject to a lock-breaking preemption if the current thread is deleted. This parameter only makes sense for self-deleting threads. Passing NULL when no lock-breaking preemption is required is valid. See xnpod_schedule() for more on lock-breaking preemption points.
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.

Side-effect: This routine calls the rescheduling procedure.

Context: This routine must be called on behalf of a thread context.

void xnpod_dispatch_signals void   )  [static]
 

Deliver pending asynchronous signals to the running thread - INTERNAL.

This internal routine checks for the presence of asynchronous signals directed to the running thread, and attempt to start the asynchronous service routine (ASR) if any.

xnticks_t xnpod_get_time void   ) 
 

Get the nanokernel idea of time.

This service gets the nanokernel (external) clock time.

Returns:
The current nanokernel time (in ticks) if the underlying time source runs in periodic mode, or the CPU tick count if the aperiodic mode is in effect, or no timer is running.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine can be called on behalf of any context.

int xnpod_init xnpod_t pod,
int  minpri,
int  maxpri,
xnflags_t  flags
 

Initialize a new pod.

Initializes a new pod which can subsequently be used to start real-time activities. Once a pod is active, real-time APIs can be stacked over. There can only be a single pod active in the host environment. Such environment can be confined to a process though (e.g. MVM or POSIX layers), or expand to the whole system (e.g. Adeos or RTAI).

Parameters:
pod The address of a pod descriptor Xenomai will use to store the pod-specific data. This descriptor must always be valid while the pod is active therefore it must be allocated in permanent memory.
minpri The value of the lowest priority level which is valid for threads created on behalf of this pod.
maxpri The value of the highest priority level which is valid for threads created on behalf of this pod.
flags A set of creation flags affecting the operation. The only defined flag is XNDREORD (Disable REORDering), which tells the nanokernel that the (xnsynch_t) pend queue should not be reordered whenever the priority of a blocked thread it holds is changed. If this flag is not specified, changing the priority of a blocked thread using xnpod_renice_thread() will cause the pended queue to be reordered according to the new priority level, provided the synchronization object makes the waiters wait by priority order on the awaited resource (XNSYNCH_PRIO).
minpri might be numerically higher than maxpri if the upper real-time interface exhibits a reverse priority scheme. For instance, some APIs may define a range like minpri=255, maxpri=0 specifying that thread priorities increase as the priority level decreases numerically.

Context: This routine must be called on behalf of a context allowing immediate memory allocation requests (e.g. an init_module() routine).

int xnpod_init_thread xnthread_t *  thread,
const char *  name,
int  prio,
xnflags_t  flags,
unsigned  stacksize,
void *  adcookie,
unsigned  magic
 

Initialize a new thread.

Initializes a new thread attached to the active pod. The thread is left in an innocuous mode until it is actually started by xnpod_start_thread().

Parameters:
thread The address of a thread descriptor Xenomai 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.
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 nanokernel for issuing human-readable diagnostic messages, so it is usually a good idea to provide a sensible value here. The MVM layer even uses this name intensively to identify threads in the debugging GUI it provides. However, passing NULL is always legal and means "anonymous".
prio The base priority of the new thread. This value must range from [minpri .. maxpri] (inclusive) as specified when calling the xnpod_init() service.
flags A set of creation flags affecting the operation. The only defined flag available to the upper interfaces is XNFPU (enable FPU), which tells the nanokernel that the new thread will use the floating-point unit. In such a case, the nanokernel 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 Xenomai 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 nanokernel will use a reasonable pre-defined size depending on the underlying real-time control layer.
adcookie An architecture-dependent cookie. The caller should pass the XNARCH_THREAD_COOKIE value defined for all real-time control layers in their respective interface file. This system-defined cookie must not be confused with the user-defined thread cookie passed to the xnpod_start_thread() service.
magic A magic cookie each skin can define to unambiguously identify threads created in their realm. This value is copied as-is to the "magic" field of the thread struct. 0 is a conventional value for "no magic".
Returns:
XN_OK is returned on success. Otherwise, one of the following error codes indicates the cause of the failure:
  • XNERR_PARAM is returned if flags has invalid bits set.

  • XNERR_NOMEM is returned if thread is NULL or 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.

Context: This routine must be called on behalf of a thread context.

void xnpod_preempt_current_thread void   )  [inline, static]
 

Preempts the current thread - INTERNAL.

Preempts the running thread (because a more prioritary thread has just been readied). The thread is re-inserted at the front of its priority group in the ready thread queue.

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

Remove a nanokernel hook.

This service removes a nanokernel 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:
XN_OK is returned on success. Otherwise, XNERR_PARAM is returned if type is incorrect or if the routine has never been registered before.
Side-effect: This routine does not call the rescheduling procedure.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_renice_thread xnthread_t *  thread,
int  prio
 

Change the base priority of a thread.

Changes the base priority of a thread. If the XNDREORD flag has not been passed to xnpod_init() and the reniced thread is currently blocked waiting in priority-pending mode (XNSYNCH_PRIO) for a synchronization object to be signaled, the nanokernel will attempt to reorder the object's pend queue so that it reflects the new sleeper's priority.

Parameters:
thread The descriptor address of the affected thread.
prio The new thread priority.
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* change the thread.cprio field by hand, unless the thread is known to be in an innocuous state (e.g. dormant).

Side-effects:

  • This service does not call the rescheduling procedure but may affect the ready queue.

  • Assigning the same priority to a running or ready thread moves it at the end of the ready queue, thus might cause a manual round-robin effect.

  • If the reniced thread is a user-space shadow, propagate the request to the mated Linux task.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_restart_thread xnthread_t *  thread,
xnmutex_t *  imutex
 

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.
imutex The address of an interface mutex currently held by the caller which will be subject to a lock-breaking preemption if the current thread restarts itself. Passing NULL when no lock-breaking preemption is required is valid. See xnpod_schedule() for more on lock-breaking preemption points.
Self-restarting a thread is allowed. However, restarting the root thread is not.

Side-effect: This routine calls the rescheduling procedure.

Context: This routine must be called on behalf of a thread context.

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.

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

Side-effect: This service does not call the rescheduling procedure but may affect the ready queue.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_rotate_readyq int  prio  ) 
 

Rotate a priority level in the ready queue.

The thread at the head of the ready queue of the given priority level is moved to the end of this queue. Therefore, the execution of threads having the same priority is switched. Round-robin scheduling policies may be implemented by periodically issuing this call in a given period of time. It should be noted that the nanokernel already provides a built-in round-robin mode though (see xnpod_activate_rr()).

Parameters:
prio The priority level to rotate. if XNPOD_RUNPRI is given, the running thread priority is used to rotate the queue.
The priority level which is considered is always the base priority of a thread, not the possibly PIP-boosted current priority value. Specifying a priority level with no thread on it is harmless, and will simply lead to a null-effect.

Side-effect: This service does not call the rescheduling procedure but affects the ready queue.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_schedule xnmutex_t *  imutex  ) 
 

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 nanokernel 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() actually switches threads if:

  • the running thread has been blocked or deleted.
  • or, the running thread has become less prioritary than the first ready to run thread.
  • or, the running thread does not lead no more the ready threads (round-robin).
  • or, a real-time thread became ready to run, ending the scheduler idle state (i.e. The root thread was running so far).

Parameters:
imutex The address of an interface mutex currently held by the caller which will be subject to a lock-breaking preemption before the current thread is actually switched out. The corresponding kernel mutex will be automatically reacquired by the nanokernel when the thread is eventually switched in again, before xnpod_schedule() returns to its caller. Passing NULL when no lock-breaking preemption is required is valid. See below.
The nanokernel 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 more prioritary 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.

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 explicitely issue xnpod_schedule() after such operations.

Lock-breaking preemption is a mean by which a thread who holds a nanokernel mutex (i.e. xnmutex_t) can rely on xnpod_schedule() to release such mutex and switch in another thread atomically. The incoming thread can then grab this mutex while the initial holder is suspended. The nanokernel automatically reacquires the mutex on behalf of the initial holder when it eventually resumes execution. This is a desirable feature which provides a simple and safe way for the upper interfaces to deal with scheduling points inside critical sections. Since the aforementioned mutex is usually defined by a client real-time interface to protect from races when concurrent threads access its internal data structures, it is dubbed the "interface mutex" in the Xenomai documentation.

The rescheduling procedure always leads to a null-effect if the scheduler is locked (XNLOCK bit set in the status mask of the running thread), or if it is called on behalf of an interrupt service thread. (ISVC threads have a separate internal rescheduling procedure named xnpod_schedule_runnable()).

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

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

  • This call may affect the ready queue and switch thread contexts.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_schedule_runnable xnthread_t *  thread,
int  flags
 

Hidden rescheduling procedure - INTERNAL.

This internal routine should NEVER be used directly by the upper interfaces. It reinserts the given thread into the ready queue then switches to the most prioritary runnable thread. It must be called interrupts off.

Parameters:
thread The descriptor address of the thread to reinsert into the ready queue.
flags A bitmask composed as follows:
  • XNPOD_SCHEDLIFO causes the target thread to be inserted at front of its priority group in the ready queue. Otherwise, the FIFO ordering is applied.

  • XNPOD_NOSWITCH reorders the ready queue without switching contexts. This feature is used by the nanokernel mutex code to preserve the atomicity of some operations.

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

  • XNRRB causes the thread to be marked as undergoing the round-robin scheduling policy. The contents of the thread.rrperiod field determines the time quantum (in ticks) allowed for its next slice. If the thread is already undergoing the round-robin scheduling policy at the time this service is called, the time quantum remains unchanged.

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

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

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_set_time xnticks_t  newtime  ) 
 

Set the nanokernel idea of time.

The nanokernel tracks the current time as a monotonously increasing count of ticks announced by the timer source since the epoch. The epoch is initially defined by the time the nanokernel has started. This service changes the epoch. Running timers use a different time base thus are not affected by this operation. The nanokernel time is only accounted when the system timer runs in periodic mode.

Side-effect:

  • This routine does not call the rescheduling procedure.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_shutdown int  xtype  ) 
 

Default shutdown handler.

Forcibly shutdowns the active pod. All existing nanokernel 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 nanokernel. Zero is always interpreted as a successful return.
The nanokernel will not call this routine directly but rather use the routine pointed at by the pod.svctable.shutdown member in the service table. This allows upper interfaces to interpose their own shutdown handlers so that they have their word before any action is taken. Usually, the interface-defined handlers should end up calling xnpod_shutdown() after their own housekeeping chores have been carried out.

Context: This routine must be called on behalf of the root thread (e.g. a cleanup_module() routine).

void xnpod_start_thread xnthread_t *  thread,
xnflags_t  mode,
int  imask,
void(*  entry)(void *cookie),
void *  cookie
 

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.
mode The initial thread mode. The following flags can be part of this bitmask, each of them affecting the nanokernel 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.

  • XNRRB causes the thread to be marked as undergoing the round-robin scheduling policy at startup. The contents of the thread.rrperiod field determines the time quantum (in ticks) allowed for its next slice.

  • 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 explicitely resumed using the xnpod_resume_thread() service for its execution to actually begin.

Parameters:
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. cli()). Conversely, a zero value should always mark a fully preemptible state regarding interrupts (i.e. sti()).
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 nanokernel 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).

Side-effect: This routine calls the rescheduling procedure.

Context: This routine must be called on behalf of a thread context.

int xnpod_start_timer u_long  nstick,
xnist_t  handler
 

Start the system timer.

The nanokernel needs a time source to provide the time-related services to the upper interfaces. xnpod_start_timer() tunes the timer hardware so that a user-defined routine is called according to a given frequency. On architectures that provide a oneshot-programmable time source, the system timer can operate whether in aperiodic or periodic mode. Using the aperiodic mode still allows to run periodic nanokernel timers over it: the underlying hardware will simply be reprogrammed after each tick by the timer manager using the appropriate interval value (see xntimer_start()).

The time interval that elapses between two consecutive invocations of the handler is called a tick.

Parameters:
nstick The timer period in nanoseconds. XNPOD_DEFAULT_TICK can be used to set this value according to the arch-dependent settings. If this parameter is equal to XNPOD_APERIODIC_TICK, the underlying hardware timer is set to operate in oneshot-programmable mode. In this mode, timing accuracy is higher - since it is not rounded to a constant time slice - at the expense of a lesser efficicency when many timers are simultaneously active. The aperiodic mode gives better results in configuration involving a few threads requesting timing services over different time scales that cannot be easily expressed as multiples of a single base tick, or would lead to a waste of high frequency periodical ticks.
handler The address of the interrupt service thread which will process each incoming tick. XNPOD_DEFAULT_TICKHANDLER can be passed to use the system-defined entry point (i.e. xnpod_announce_tick()). In any case, a user-supplied handler should end up calling xnpod_announce_tick() to inform the nanokernel of the incoming tick.
Returns:
XN_OK is returned on success. Otherwise:

  • XNERR_PARAM is returned if an invalid null tick handler has been passed, or if the timer precision cannot represent the duration of a single host tick.

  • XNERR_NOSYS is returned if the underlying architecture does not support the requested aperiodic timing, or 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.

Context: This routine must be called on behalf of a context allowing immediate memory allocation requests (e.g. an init_module() routine).

void xnpod_stop_timer void   ) 
 

Stop the periodic timer.

Stops the periodic timer previously started by a call to xnpod_start_timer().

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

Context: This routine can be called on behalf of a thread or IST context.

int xnpod_suspend_thread xnthread_t *  thread,
xnflags_t  mask,
xnticks_t  timeout,
xnsynch_t *  wchan,
xnmutex_t *  imutex
 

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. The wchan parameter should not be significant when using this suspension condition. 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.

  • 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 suspension mode should not be used directly by the upper interface, but rather through the xnsynch_sleep_on() call.

Parameters:
timeout The timeout which may be used to limit the time the thread pends for a resource. This value is a wait time given in ticks. Passing XN_INFINITE specifies an unbounded wait. All other values are used to initialize a watchdog timer.
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.
imutex The address of an interface mutex currently held by the caller which will be subject to a lock-breaking preemption before the current thread is actually switched out. The corresponding kernel mutex will be automatically reacquired by the nanokernel when the suspended thread is eventually resumed, before xnpod_suspend_thread() returns to its caller. This parameter only makes sense for self-suspending threads. Passing NULL when no lock-breaking preemption is required is valid. See xnpod_schedule() for more on lock-breaking preemption points.
Returns:
Returns true if a thread switch took place as a result of this call, false otherwise.
Side-effect: A rescheduling immediately occurs if the caller self-suspends, in which case true is always returned.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_trap_fault void *  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 handler stored into the service table (svctable.faulthandler) is invoked and the fault is not propagated to the host system. Otherwise, the fault is unhandled by the nanokernel 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.

void 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, XNFROZEN nor the XNDORMANT suspensive conditions.

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

Side-effect: This service does not call the rescheduling procedure but may affect the ready queue.

Context: This routine can be called on behalf of a thread or IST context.

void xnpod_welcome_thread xnthread_t *  thread  ) 
 

Thread prologue - INTERNAL.

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.


Generated on Sat Jul 24 19:36:22 2004 for RTAI API by doxygen 1.3.4