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. |
|
Real-time pod descriptor. The source of all Xenomai magic. |
|
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.
Context: This routine can be called on behalf of a thread or IST context. |
|
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.
Side-effect: This routine does not call the rescheduling procedure. Context: This routine can be called on behalf of a thread or IST context. |
|
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.
Context: The caller must have a valid nanokernel context (regular or interrupt service thread). |
|
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. |
|
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.
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. |
|
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. |
|
Get the nanokernel idea of time. This service gets the nanokernel (external) clock time.
Context: This routine can be called on behalf of any context. |
|
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).
Context: This routine must be called on behalf of a context allowing immediate memory allocation requests (e.g. an init_module() routine). |
|
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().
Side-effect: This routine does not call the rescheduling procedure. Context: This routine must be called on behalf of a thread context. |
|
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. |
|
Remove a nanokernel hook. This service removes a nanokernel hook previously registered using xnpod_add_hook().
Context: This routine can be called on behalf of a thread or IST context. |
|
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.
Side-effects:
Context: This routine can be called on behalf of a thread or IST context. |
|
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.
Side-effect: This routine calls the rescheduling procedure. Context: This routine must be called on behalf of a thread context. |
|
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.
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:
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. |
|
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()).
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. |
|
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:
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:
Context: This routine can be called on behalf of a thread or IST context. |
|
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.
|
|
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.
Side-effect: This routine does not call the rescheduling procedure. Context: This routine can be called on behalf of a thread or IST context. |
|
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:
Context: This routine can be called on behalf of a thread or IST context. |
|
Default shutdown handler. Forcibly shutdowns the active pod. All existing nanokernel threads (but the root one) are terminated, and the system heap is freed.
Context: This routine must be called on behalf of the root thread (e.g. a cleanup_module() routine). |
|
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.
Side-effect: This routine calls the rescheduling procedure. Context: This routine must be called on behalf of a thread context. |
|
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.
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). |
|
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. |
|
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().
Context: This routine can be called on behalf of a thread or IST context. |
|
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.
|
|
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.
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. |
|
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. |