![]() |
Files | |
file | pod.h |
Real-time pod interface header. | |
file | pod.c |
Real-time pod services. | |
Data Structures | |
struct | xnsched_t |
Scheduling information structure. More... | |
struct | xnpod |
Real-time pod descriptor. More... | |
Functions | |
void | xnpod_schedule_runnable (xnthread_t *thread, int flags) |
Hidden rescheduling procedure. | |
int | xnpod_init (xnpod_t *pod, int loprio, int hiprio, xnflags_t flags) |
Initialize a new pod. | |
int | xnpod_start_timer (u_long nstick, xnisr_t tickhandler) |
Start the system timer. | |
void | xnpod_stop_timer (void) |
Stop the system timer. | |
int | xnpod_reset_timer (void) |
Reset the system timer. | |
void | xnpod_shutdown (int xtype) |
Shutdown the current pod. | |
int | xnpod_init_thread (xnthread_t *thread, const char *name, int prio, xnflags_t flags, unsigned stacksize) |
Initialize a new thread. | |
int | xnpod_start_thread (xnthread_t *thread, xnflags_t mode, int imask, xnarch_cpumask_t affinity, void(*entry)(void *cookie), void *cookie) |
Initial start of a newly created 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_resume_thread (xnthread_t *thread, xnflags_t mask) |
Resume a thread. | |
int | 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. | |
int | xnpod_migrate_thread (int cpu) |
void | xnpod_rotate_readyq (int prio) |
Rotate a priority level in the ready queue. | |
void | xnpod_schedule (void) |
Rescheduling procedure entry point. | |
void | xnpod_dispatch_signals (void) |
Deliver pending asynchronous signals to the running thread. | |
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 nucleus idea of time. | |
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) |
xnticks_t | xnpod_get_time (void) |
Get the nucleus idea of time. | |
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_suspend_thread (xnthread_t *thread, xnflags_t mask, xnticks_t timeout, xnsynch_t *wchan) |
Suspend a thread. | |
void | xnpod_welcome_thread (xnthread_t *thread, int imask) |
Thread prologue. | |
static void | xnpod_preempt_current_thread (xnsched_t *sched) |
Preempts the current thread. | |
int | xnpod_trap_fault (void *fltinfo) |
Default fault handler. | |
int | xnpod_announce_tick (xnintr_t *intr) |
Announce a new clock tick. |
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.
thread | The descriptor address of the terminated thread. |
Environments:
This service can be called from:
Rescheduling: possible if the current thread self-deletes.
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 to the end of its priority group in the ready queue. This process is repeated until the round-robin scheduling is disabled for those threads.
quantum | The time credit which will be given to each rr-enabled thread (in ticks). |
This service can be called from:
Rescheduling: never.
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.
type | Defines the kind of hook to install: |
routine | The address of the user-supplied routine to call. |
Environments:
This service can be called from:
Rescheduling: never.
int xnpod_announce_tick | ( | xnintr_t * | intr | ) |
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 nucleus. In a way or another, this routine must be called to announce each incoming clock tick to the nucleus.
intr | The descriptor address of the interrupt object associated to the timer interrupt. |
This service can be called from:
Rescheduling: possible.
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()).
Environments:
This service can be called from:
Rescheduling: never.
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.
thread | The descriptor address of the terminated thread. |
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:
Rescheduling: possible if the current thread self-deletes.
void xnpod_dispatch_signals | ( | void | ) |
Deliver pending asynchronous signals to the running thread.
For internal use only.
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.
xnticks_t xnpod_get_time | ( | void | ) |
Get the nucleus idea of time.
This service gets the nucleus (external) clock time.
This service can be called from:
Rescheduling: never.
int xnpod_init | ( | xnpod_t * | pod, | |
int | loprio, | |||
int | hiprio, | |||
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 (e.g. simulator or UVM), or expand machine-wide (e.g. Adeos).
pod | The address of a pod descriptor the nucleus 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. | |
loprio | The value of the lowest priority level which is valid for threads created on behalf of this pod. | |
hiprio | 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 XNREUSE, which tells the nucleus that a pre-existing pod exhibiting the same properties as the one which is being registered may be reused. In such a case, the call returns successfully, keeping the active pod unmodified. |
Environments:
This service can be called from:
int xnpod_init_thread | ( | xnthread_t * | thread, | |
const char * | name, | |||
int | prio, | |||
xnflags_t | flags, | |||
unsigned | stacksize | |||
) |
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().
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. |
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". | |
prio | The base priority of the new thread. This value must range from [loprio .. hiprio] (inclusive) as specified when calling the xnpod_init() service. | |
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: |
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. |
Side-effect: This routine does not call the rescheduling procedure.
Environments:
This service can be called from:
Rescheduling: never.
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.
cpu | The destination CPU. |
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. |
void xnpod_preempt_current_thread | ( | xnsched_t * | sched | ) | [inline, static] |
Preempts the current thread.
For internal use only.
Preempts the running thread (because a higher priority thread has just been readied). The thread is re-inserted to the front of its priority group in the ready thread queue. Must be called with nklock locked, interrupts off.
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().
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. |
This service can be called from:
Rescheduling: never.
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 reniced 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.
thread | The descriptor address of the affected thread. | |
prio | The new thread priority. |
Side-effects:
Environments:
This service can be called from:
Rescheduling: never.
int xnpod_reset_timer | ( | void | ) |
Reset the system timer.
Reset the system timer to its default setup. The default setup data are obtained, by order of priority, from:
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:
Rescheduling: never.
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.
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:
Rescheduling: possible.
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.
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: |
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:
Environments:
This service can be called from:
Rescheduling: never.
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 nucleus already provides a built-in round-robin mode though (see xnpod_activate_rr()).
prio | The priority level to rotate. if XNPOD_RUNPRIO is given, the running thread priority is used to rotate the queue. |
Environments:
This service can be called from:
Rescheduling: never.
void xnpod_schedule | ( | void | ) |
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() actually switches threads if:
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 explicitely 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:
Environments:
This service can be called from:
void xnpod_schedule_runnable | ( | xnthread_t * | thread, | |
int | flags | |||
) |
Hidden rescheduling procedure.
For internal use only.
This internal routine should NEVER be used directly by the client interfaces. It reinserts the given thread into the ready queue then switches to the highest priority runnable thread. It must be called with nklock locked, interrupts off.
thread | The descriptor address of the thread to reinsert into the ready queue. | |
flags | A bitmask composed as follows: |
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.
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: |
Environments:
This service can be called from:
Rescheduling: never, therefore, the caller should reschedule if XNLOCK has been passed into clrmask.
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.
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. |
Environments:
This service can be called from:
Rescheduling: possible if the operation affects the current thread and idate has not elapsed yet.
void xnpod_set_time | ( | xnticks_t | newtime | ) |
Set the nucleus idea of time.
The nucleus tracks the current time as a monotonously increasing count of ticks announced by the timer source since the epoch. The epoch is initially the same as the underlying architecture system time. This service changes the epoch. Running timers use a different time base thus are not affected by this operation.
Environments:
This service can be called from:
Rescheduling: never.
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.
xtype | An exit code passed to the host environment who started the nucleus. Zero is always interpreted as a successful return. |
Environments:
This service can be called from:
Rescheduling: never.
int xnpod_start_thread | ( | xnthread_t * | thread, | |
xnflags_t | mode, | |||
int | imask, | |||
xnarch_cpumask_t | affinity, | |||
void(*)(void *cookie) | entry, | |||
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.
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 nucleus behaviour regarding the started thread: |
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()). | |
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. |
0 | if thread could be started ; | |
-EBUSY | if thread was already started ; | |
-EINVAL | if the value of affinity is invalid. |
This service can be called from:
Rescheduling: possible.
int xnpod_start_timer | ( | u_long | nstick, | |
xnisr_t | tickhandler | |||
) |
Start the system timer.
The nucleus 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 either in aperiodic or periodic mode. Using the aperiodic mode still allows to run periodic timings 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.
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 XN_APERIODIC_TICK, the underlying hardware timer is set to operate in oneshot-programming mode. In this mode, timing accuracy is higher - since it is not rounded to a constant time slice. The aperiodic mode gives better results in configuration involving 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. | |
tickhandler | The address of the tick handler 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 nucleus of the incoming tick. |
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:
Rescheduling: never.
void xnpod_stop_timer | ( | void | ) |
Stop the system timer.
Stops the system timer previously started by a call to xnpod_start_timer().
Environments:
This service can be called from:
Rescheduling: never.
void xnpod_suspend_thread | ( | xnthread_t * | thread, | |
xnflags_t | mask, | |||
xnticks_t | timeout, | |||
xnsynch_t * | 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().
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: |
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 (see note). Passing XN_INFINITE specifies an unbounded wait. All other values are used to initialize a watchdog timer. If the current operation mode 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. | |
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). |
This service can be called from:
Rescheduling: possible if the current thread suspends itself.
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 nucleus and simply propagated.
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. |
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.
thread | The descriptor address of the unblocked thread. |
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.
This service can be called from:
Rescheduling: never.
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.
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. |
Environments:
This service can be called from:
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.
void xnpod_welcome_thread | ( | xnthread_t * | thread, | |
int | imask | |||
) |
Thread prologue.
For internal use only.
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.