Task functions
[RTAI schedulers modules]


Files

file  sched_up.c
 Scheduling function for uni-processor.


Functions

int rt_task_init (RT_TASK *task, void(*rt_thread)(int), int data, int stack_size, int priority, int uses_fpu, void(*signal)(void))
int rt_task_init_cpuid (RT_TASK *task, void(*rt_thread)(int), int data, int stack_size, int priority, int uses_fpu, void(*signal)(void), unsigned int cpuid)
void rt_set_runnable_on_cpus (RT_TASK *task, unsigned long run_on_cpus)
 Assign CPUs to a task.

void rt_set_runnable_on_cpuid (RT_TASK *task, unsigned int cpuid)
 Assign CPUs to a task.

void rt_sched_lock (void)
 Lock the scheduling of tasks.

void rt_sched_unlock (void)
 Unlock the scheduling of tasks.

int rt_task_delete (RT_TASK *task)
void rt_preempt_always (int yes_no)
 Enable hard preemption.

void rt_preempt_always_cpuid (int yes_no, unsigned int cpuid)
 Enable hard preemption.


Function Documentation

void rt_preempt_always int  yes_no  ) 
 

Enable hard preemption.

In the oneshot mode the next timer expiration is programmed after a timer shot by choosing among the timed tasks the one with a priority higher than the task chosen to run as current, with the constraint of always assuring a correct Linux timing. In such a view there is no need to fire the timer immediately. In fact it can happen that the current task can be so fast to get suspended and rerun before the one that was devised to time the next shot when it was made running. In such a view RTAI schedulers try to shoot only when strictly needed. This minimizes the number of slow setups of the 8254 timer used with UP and 8254 based SMP schedulers. While such a policy minimizes the number of actual shots, greatly enhancing efficiency, it can be unsuitable when an application has to be guarded against undesired program loops or other unpredicted error causes. Calling these functions with a nonzero value assures that a timed high priority preempting task is always programmed to be fired while another task is currently running. The default is no immediate preemption in oneshot mode, i.e. firing of the next shot programmed only when strictly needed to satisfy tasks timings.

Note:
With UP and SMP schedulers there is always only a timing source so that cpu_idinrt_preempt_always_cpuid is not used. With the MUP scheduler you have an independent timer for each CPU, so rt_preempt_always applies to all the CPUs while rt_preempt_always_cpuid should be used when preemption is to be forced only on a specific CPU.

void rt_preempt_always_cpuid int  yes_no,
unsigned int  cpuid
 

Enable hard preemption.

In the oneshot mode the next timer expiration is programmed after a timer shot by choosing among the timed tasks the one with a priority higher than the task chosen to run as current, with the constraint of always assuring a correct Linux timing. In such a view there is no need to fire the timer immediately. In fact it can happen that the current task can be so fast to get suspended and rerun before the one that was devised to time the next shot when it was made running. In such a view RTAI schedulers try to shoot only when strictly needed. This minimizes the number of slow setups of the 8254 timer used with UP and 8254 based SMP schedulers. While such a policy minimizes the number of actual shots, greatly enhancing efficiency, it can be unsuitable when an application has to be guarded against undesired program loops or other unpredicted error causes. Calling these functions with a nonzero value assures that a timed high priority preempting task is always programmed to be fired while another task is currently running. The default is no immediate preemption in oneshot mode, i.e. firing of the next shot programmed only when strictly needed to satisfy tasks timings.

Note:
With UP and SMP schedulers there is always only a timing source so that cpu_idinrt_preempt_always_cpuid is not used. With the MUP scheduler you have an independent timer for each CPU, so rt_preempt_always applies to all the CPUs while rt_preempt_always_cpuid should be used when preemption is to be forced only on a specific CPU.

void rt_sched_lock void   ) 
 

Lock the scheduling of tasks.

rt_sched_lock, lock on the CPU on which they are called, any scheduler activity, thus preventing a higher priority task to preempt a lower priority one. They can be nested, provided unlocks are paired to locks in reversed order. It can be used for synchronization access to data among tasks. Note however that under MP the lock is active only for the CPU on which it has been issued, so it cannot be used to avoid races with tasks that can run on any other available CPU. Interrupts are not affected by such calls. Any task that needs rescheduling while a scheduler lock is in placewill be only at the issuing of the last unlock

Note:
To be used only with RTAI24.x.xx.
See also: rt_sched_unlock().

void rt_sched_unlock void   ) 
 

Unlock the scheduling of tasks.

rt_sched_unlock, unlock on the CPU on which they are called, any scheduler activity, thus preventing a higher priority task to preempt a lower priority one. They can be nested, provided unlocks are paired to locks in reversed order. It can be used for synchronization access to data among tasks. Note however that under MP the lock is active only for the CPU on which it has been issued, so it cannot be used to avoid races with tasks that can run on any other available CPU. Interrupts are not affected by such calls. Any task that needs rescheduling while a scheduler lock is in placewill be only at the issuing of the last unlock

Note:
To be used only with RTAI24.x.xx.
See also: rt_sched_unlock().

void rt_set_runnable_on_cpuid RT_TASK *  task,
unsigned int  cpuid
 

Assign CPUs to a task.

rt_set_runnable_on_cpuid select one or more CPUs which are allowed to run task task.

rt_set_runnable_on_cpuid assigns a task to a single specific CPU. If no CPU, as selected by cpu_mask or cpuid, is available, both functions choose a possible CPU automatically, following the same rule as above.

Note:
This call has no effect on UniProcessor (UP) systems.
See also: rt_set_runnable_on_cpus().

void rt_set_runnable_on_cpus RT_TASK *  task,
unsigned long  runnable_on_cpus
 

Assign CPUs to a task.

rt_set_runnable_on_cpus selects one or more CPUs which are allowed to run task task. rt_set_runnable_on_cpus behaves differently for MUP and SMP schedulers. Under the SMP scheduler bit<n> of cpu_mask enables the task to run on CPU<n>. Under the MUP scheduler it selects the CPU with less running tasks among those allowed by cpu_mask. Recall that with MUP a task must be bounded to run on a single CPU. If no CPU, as selected by cpu_mask or cpuid, is available, both functions choose a possible CPU automatically, following the same rule as above.

Note:
This call has no effect on UniProcessor (UP) systems.
See also: rt_set_runnable_on_cpuid().

int rt_task_delete RT_TASK *  task  ) 
 

Delete a real time task.

rt_task_delete deletes a real time task previously created by rt_task_init() or rt_task_init_cpuid().

Parameters:
task is the pointer to the task structure. If task task was waiting on a queue, i.e. semaphore, mailbox, etc, it is removed from such a queue and messaging tasks pending on its message queue are unblocked with an error return.
Returns:
0 on success. A negative value on failure as described below:
  • EINVAL: task does not refer to a valid task.

int rt_task_init RT_TASK *  task,
void(*  rt_thread)(int),
int  data,
int  stack_size,
int  priority,
int  uses_fpu,
void(*  signal)(void)
 

Creates a new real time task.

The newly created real time task is initially in a suspend state. It can be made active by calling: rt_task_make_periodic, rt_task_make_periodic_relative_ns, rt_task_resume.

When used with the MUP scheduler rt_task_init automatically selects which CPU the task will run on, while with the SMP scheduler the task defaults to using any of the available CPUs. This assignment may be changed by calling rt_set_runnable_on_cpus.

Parameters:
task is a pointer to an RT_TASK type structure whose space must be provided by the application. It must be kept during the whole lifetime of the real time task.
rt_thread is the entry point of the task function.
data The parent task can pass a single integer value data to the new task being created. Recall that an appropriately type casting allows data to be a pointer to whatever data structure one would like to pass to the task, so you can indirectly pass whatever you want to the task.
stack_size is the size of the stack to be used by the new task. In sizing it, recall to make room for any real time interrupt handler, as real time interrupts run on the stack of the task they interrupt. So try to avoid being too sparing.
priority is the priority to be given to the task. The highest priority is 0, while the lowest is RT_SCHED_LOWEST_PRIORITY.
uses_fpu is a flag. A nonzero value indicates that the task will use the floating point unit.
signal is a function that is called, within the task environment and with interrupts disabled, when the task becomes the current running task after a context switch. Note however that signal is not called at the very first scheduling of the task. Such a function can be assigned and/or changed dynamically whenever needed (see function rt_task_signal_handler.)
Returns:
0 on success. A negative value on failure as described below:
  • EINVAL: task structure pointed by task is already in use;
  • ENOMEM: stack_size bytes could not be allocated for the stack.
See also: rt_task_init_cpuid().

int rt_task_init_cpuid RT_TASK *  task,
void(*  rt_thread)(int),
int  data,
int  stack_size,
int  priority,
int  uses_fpu,
void(*  signal)(void),
unsigned int  cpuid
 

Creates a new real time task and assigns it to a single specific CPU.

The newly created real time task is initially in a suspend state. It can be made active by calling: rt_task_make_periodic, rt_task_make_periodic_relative_ns, rt_task_resume.

When used with the MUP scheduler rt_task_init automatically selects which CPU the task will run on, while with the SMP scheduler the task defaults to using any of the available CPUs. This assignment may be changed by calling rt_set_runnable_on_cpus or rt_set_runnable_on_cpuid. If cpuid is invalid rt_task_init_cpuid falls back to automatic CPU selection.

Whatever scheduler is used on multiprocessor systems rt_task_init_cpuid allows to create a task and assign it to a single specific CPU cpuid from its very beginning, without any need to call rt_set_runnable_on_cpuid later on.

Parameters:
task is a pointer to an RT_TASK type structure whose space must be provided by the application. It must be kept during the whole lifetime of the real time task.
rt_thread is the entry point of the task function.
data The parent task can pass a single integer value data to the new task being created. Recall that an appropriately type casting allows data to be a pointer to whatever data structure one would like to pass to the task, so you can indirectly pass whatever you want to the task.
stack_size is the size of the stack to be used by the new task. In sizing it recall to make room for any real time interrupt handler, as real time interrupts run on the stack of the task they interrupt. So try to avoid being too sparing.
priority is the priority to be given to the task. The highest priority is 0, while the lowest is RT_SCHED_LOWEST_PRIORITY.
uses_fpu is a flag. A nonzero value indicates that the task will use the floating point unit.
signal is a function that is called, within the task environment and with interrupts disabled, when the task becomes the current running task after a context switch. Note however that signal is not called at the very first scheduling of the task. Such a function can be assigned and/or changed dynamically whenever needed (see function rt_task_signal_handler.)
cpuid FIXME
Returns:
0 on success. A negative value on failure as described below:
  • EINVAL: task structure pointed by task is already in use;
  • ENOMEM: stack_size bytes could not be allocated for the stack.
See also: rt_task_init().


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