RTAI API---task function

rt_task_init 
rt_task_init_cpuid 
rt_task_delete 
rt_task_make_periodic 
rt_task_make_periodic_relative_ns 
rt_task_wait_period 
rt_task_yield 
rt_task_suspend 
rt_task_resume 
rt_busy_sleep 
rt_sleep 
rt_sleep_until 
rt_get_task_state 
rt_whoami 
rt_task_signal_handler 
rt_set_runnable_on_cpus 
rt_set_runnable_on_cpuid 
rt_task_use_fpu 
rt_linux_use_fpu 

rt_preempt_always 

please refer to: https://www.rtai.org/userfiles/documentation/magma/html/api

******************************************************************************************************************************************************************

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

***************************************************************************************************************************************************************
NAME
rt_task_wait_period - wait till next period
SYNOPSIS
#include "rtai_sched.h"
void rt_task_wait_period (void);

DESCRIPTION
rt_task_wait_period suspends the execution of the currently running real time task until the next period is reached. The task must have been previously marked for execution with rt_task_make_periodic or rt_task_make_periodic_relative_ns. 
Note that the task is suspended only temporarily, i.e. it simply gives up control until the next time period.
**************************************************************************************************************************************************************
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.
*************************************************************************************************************************************************************
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.

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

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

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

***************************************************************************************************************************************************************

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