NAME

rt_task_init, rt_task_init_cpuid - create a new real time task

SYNOPSIS

#include "rtai_sched.h"

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);

DESCRIPTION

rt_task_init and rt_task_init_cpuid create a real time task.
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 and cannot be an automatic variable.
rt_thread is the entry point of the task function. The parent task can pass a single integer value data to the new task.
stack_size is the size of the stack to be used by the new task, and priority is the priority to be given the task. The highest priority is 0, while the lowest is RT_LOWEST_PRIORITY.
uses_fpu is a flag. 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.

The newly created real time task is initially in a suspend state. It is can be made active either with rt_task_make_periodic, rt_task_make_periodic_relative_ns or rt_task_resume.

On multiprocessor systems rt_task_init_cpuid assigns task to a specific CPU cpuid. rt_task_init automatically selects which CPU will the task run on. 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.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

Task structure pointed by task is already in use.

-ENOMEM

stack_size bytes could not be allocated for the stack.

[return to index]

NAME

rt_task_delete - delete a real time task

SYNOPSIS

#include "rtai_sched.h"

int rt_task_delete (RT_TASK *task);

DESCRIPTION

rt_task_delete deletes a real time task previously created by rt_task_init or rt_task_init_cpuid.
task is the pointer to the task structure.
If task task was waiting for a semaphore it is removed from the semaphore waiting queue else any other task blocked on message exchange with task is unvlocked.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

task does not refer to a valid task.

[return to index]

NAME

rt_task_make_periodic, rt_task_make_periodic_relative_ns - make a task run periodically

SYNOPSIS

#include "rtai_sched.h"

int rt_task_make_periodic (RT_TASK *task, RTIME start_time, RTIME period);

int rt_task_make_periodic_relative_ns (RT_TASK *task, RTIME start_delay, RTIME period);

DESCRIPTION

rt_task_make_periodic and rt_task_make_periodic_relative_ns mark the task task, previously created with rt_task_init, as suitable for a periodic execution, with period period, when rt_task_wait_period is called.
The time of first execution is given by start_time or start_delay. start_time is an absolute value measured in clock ticks. start_delay is relative to the current time and measured in nanosecs.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

task does not refer to a valid task.

[return to index]

[return to index]

NAME

rt_task_yield - yield the current task

SYNOPSIS

#include "rtai_sched.h"

void rt_task_yield (void);

DESCRIPTION

rt_task_yield stops the current task and takes it at the end of the list of ready tasks, with the same priority. The scheduler makes the next ready task of the same priority active.

[return to index]

NAME

rt_task_suspend - suspend a task

SYNOPSIS

#include "rtai_sched.h"

int rt_task_suspend (RT_TASK *task);

DESCRIPTION

rt_task_suspend suspends execution of the task task. It will not be executed until a call to rt_task_resume or rt_task_make_periodic is made.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

task does not refer to a valid task.

[return to index]

NAME

rt_task_resume - resume a task

SYNOPSIS

#include "rtai_sched.h"

int rt_task_resume (RT_TASK *task);

DESCRIPTION

rt_task_resume resumes execution of the task task previously suspended by rt_task_suspend or makes a newly created task ready to run.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

task does not refer to a valid task.

[return to index]

NAME

rt_busy_sleep, rt_sleep, rt_sleep_until - delay/suspend execution for a while

SYNOPSIS

#include "rtai_sched.h"

void rt_busy_sleep (int nanosecs);

void rt_sleep (RTIME delay);

void rt_sleep_until (RTIME time);

DESCRIPTION

rt_busy_sleep delays the execution of the caller task without giving back the control to the scheduler. This function burns away CPU cycles in a busy wait loop It may be used for very short synchronization delays only.
nanosecs is the number of nanoseconds to wait.

rt_sleep suspends execution of the caller task for a time of delay internal count units. During this time the CPU is used by other tasks.

rt_sleep_until is similar to rt_sleep but the parameter time is the absolute time till the task have to be suspended. If the given time is already passed this call has no effect.

Note: a higher priority task or interrupt handler can run during wait so the actual time spent in these functions may be longer than the specified.

NOTE

A higher priority task or interrupt handler can run during wait so the actual time spent in these functions may be longer than the specified.

[return to index]

NAME

rt_get_task_state - query task state

SYNOPSIS

#include "rtai_sched.h"

int rt_get_task_state (RT_TASK *task);

DESCRIPTION

rt_get_task_state returns the state of a real time task.
task is a pointer to the task structure.

RETURN VALUE

Task state is formed by the bitwise OR of one or more of the following flags:

READY

Task task is ready to run (i.e. unblocked).

SUSPENDED

Task task is suspended.

DELAYED

Task task waits for its next running period or expiration of a timeout.

SEMAPHORE

Task task is blocked on a semaphore.

SEND

Task task sent a message and waits for the receiver task.

RECEIVE

Task task waits for an incoming message.

RPC

Task task sent a Remote Procedure Call and the receiver was not get it yet.

RETURN

Task task waits for reply to a Remote Procedure Call.

Note: the returned task state is just an approximative information. Timer and other hardware interrupts may cause a change in the state of the queried task before the caller could evaluate the returned value. Caller should disable interrupts if it wants reliable info about an other task.

BUGS

rt_get_task_state does not perform any check on pointer task.

[return to index]

NAME

rt_whoami - get the task pointer of the current task

SYNOPSIS

#include "rtai_sched.h"

RT_TASK *rt_whoami (void);

DESCRIPTION

Calling rt_whoami a task can get a pointer to its own task structure.

RETURN VALUE

The pointer to the current task is returned.

[return to index]

NAME

rt_task_signal_handler - set the signal handler of a task

SYNOPSIS

#include "rtai_sched.h"

void rt_task_signal_handler (RT_TASK *task, void (*handler)(void));

DESCRIPTION

rt_task_signal_handler installs or changes the signal function of a real time task.
task is a pointer to the real time task
handler is the entry point of the signal function.
Signal handler function can be set also when the task is newly created with rt_task_init. Signal handler is a function called within the task environment and with interrupts disabled, when the task becomes the current running task after a context switch.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

task does not refer to a valid task.

[return to index]

NAME

rt_set_runnable_on_cpus, rt_set_runnable_on_cpuid - assign CPUs to a task

SYNOPSIS

#include "rtai_sched.h"

void rt_set_runnable_on_cpus (RT_TASK *task, unsigned int cpu_mask);

void rt_set_runnable_on_cpuid (RT_TASK *task, unsigned int cpuid);

DESCRIPTION

rt_set_runnable_on_cpus, rt_set_runnable_on_cpuid select one or more CPUs which are allowed to run task task. rt_set_runnable_on_cpuid assigns task to a specific CPU however rt_set_runnable_on_cpus magically selects one CPU from the given set which task task will run on.
Bit<n> of cpu_mask enables CPU<n>.

If no CPU selected by cpu_mask or cpuid is available, both functions choose a possible CPU automagically.

Note: This call has no effect on uniprocessor systems.

[return to index]

NAME

rt_task_use_fpu, rt_linux_use_fpu - set indication of FPU usage

SYNOPSIS

#include "rtai_sched.h"

int rt_task_use_fpu (RT_TASK* task, int use_fpu_flag);

void rt_linux_use_fpu (int use_fpu_flag);

DESCRIPTION

rt_task_use_fpu informs the scheduler that floating point arithmetic operations will be used by the real time task task.

rt_linux_use_fpu informs the scheduler that floating point arithmetic operations will be used the background task (i.e. the Linux kernel itself and all of its processes!).

If use_fpu_flag has nonzero value, FPU context is also switched when task or the kernel became active. This makes task switching slower.

Initial value of this flag is set by rt_task_init when the real time task is created. By default Linux "task" has this flag cleared. It can be set with LinuxFpu command line parameter of the rtai_sched module.

RETURN VALUE

On success 0 is returned. On failure a negative value is returned as described below.

ERRORS

-EINVAL

task does not refer to a valid task.

[return to index]

NAME

rt_preempt_always, rt_preempt_always_cpuid - enable hard preemption

SYNOPSIS

#include "rtai_sched.h"

void rt_preempt_always (int yes_no);

void rt_preempt_always_cpuid (int yes_no, unsigned intcpu_id);

DESCRIPTION

In the oneshot mode a timed task is made active/current at the expiration of the timer shot. The next timer expiration is programmed by choosing among the timed tasks the one with a priority higher than the current after the current has released the CPU, always assuring the Linux timing. While this policy minimizes the programming of the oneshot mode, enhancing efficiency, it can be unsuitable when a task has to be guarded against looping by watch dog task with high priority value, as in such a case the latter as no chance of running.

Calling these functions with nonzero value assures that a timed high priority preempting task is always programmed to be fired while another task is current. The default is no immediate preemption in oneshot mode, firing of the next shot programmed only after the current task releases the CPU.

Initial value of this flag can be set with PreemptAlways command line parameter of the rtai_sched module.

Note: currently the booth functions are equal, parameter cpu_id is ignored.

[return to index]