task.html

A tutorial on RT-Linux

</dt><dd>
#include "rtai_sched.h"
<p>
<B>void rt_busy_sleep (int </B><I>nanosecs</I><B>);</B>
<p>
<B>void rt_sleep (RTIME </B><I>delay</I><B>);</B>
<p>
<B>void rt_sleep_until (RTIME </B><I>time</I><B>);</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
<b>rt_busy_sleep</b> 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.
<br>
<I>nanosecs</I> is the number of nanoseconds to wait.
<p>
<b>rt_sleep</b> suspends execution of the caller task for a
time of <I>delay</I> internal count units. During this time the
CPU is used by other tasks.
<p>
<b>rt_sleep_until</b> is similar to <b>rt_sleep</b> but the
parameter <I>time</I> is the absolute time till the task have to
be suspended. If the given time is already passed this call has no effect.
<p>
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.
</dd></dl>

<dl><dt>
<H3>NOTE</H3>
</dt><dd>
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.
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>
<HR ALIGN=LEFT SIZE=1 NOSHADE WIDTH="100%">
<!-- -------------------------------------------------------- -->

<A NAME="rt_get_task_state"></A>

<dl><dt>
<H3>NAME</H3>
</dt><dd>
rt_get_task_state - query task state
</dd></dl>

<dl><dt>
<H3>SYNOPSIS</H3>
</dt><dd>
#include "rtai_sched.h"
<p>
<B>int rt_get_task_state (RT_TASK *</B><I>task</I><B>);</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
<b>rt_get_task_state</b> returns the state of a real time task.
<BR>
<I>task</I> is a pointer to the task structure.
<p>
</dd></dl>

<dl><dt>
<H3>RETURN VALUE</H3>
</dt><dd>
Task state is formed by the bitwise OR of one or more of the following
flags:
	<dl><dt>
	READY
	</dt><dd>
	Task <i>task</i> is ready to run (i.e. unblocked).
	</dd></dl>
	<dl><dt>
	SUSPENDED
	</dt><dd>
	Task <i>task</i>  is suspended.
	</dd></dl>
	<dl><dt>
	DELAYED
	</dt><dd>
	Task <i>task</i> waits for its next running period or expiration
	of a timeout.
	</dd></dl>
	<dl><dt>
	SEMAPHORE
	</dt><dd>
	Task <i>task</i> is blocked on a semaphore.
	</dd></dl>
	<dl><dt>
	SEND
	</dt><dd>
	Task <i>task</i> sent a message and waits for the receiver task.
	</dd></dl>
	<dl><dt>
	RECEIVE
	</dt><dd>
	Task <i>task</i> waits for an incoming message.
	</dd></dl>
	<dl><dt>
	RPC
	</dt><dd>
	Task <i>task</i> sent a Remote Procedure Call and the receiver
	was not get it yet.
	</dd></dl>
	<dl><dt>
	RETURN
	</dt><dd>
	Task <i>task</i> waits for reply to a Remote Procedure Call.
	</dd></dl>
<p>
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.
</dd></dl>

<dl><dt>
<H3>BUGS</H3>
</dt><dd>
<b>rt_get_task_state</b> does not perform any check on pointer <i>task</i>.
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>
<HR ALIGN=LEFT SIZE=1 NOSHADE WIDTH="100%">
<!-- -------------------------------------------------------- -->


<A NAME="rt_whoami"></A>
<dl><dt>
<H3>NAME</H3>
</dt><dd>
rt_whoami - get the task pointer of the current task
</dd></dl>

<dl><dt>
<H3>SYNOPSIS</H3>
</dt><dd>
#include "rtai_sched.h"
<p>
<B>RT_TASK *rt_whoami (void);</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
Calling <b>rt_whoami</b> a task can get a pointer to its own
task structure.
</dd></dl>

<dl><dt>
<H3>RETURN VALUE</H3>
</dt><dd>
The pointer to the current task is returned.
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>
<HR ALIGN=LEFT SIZE=1 NOSHADE WIDTH="100%">
<!-- -------------------------------------------------------- -->

<A NAME="rt_task_signal_handler"></A>
<dl><dt>
<H3>NAME</H3>
</dt><dd>
rt_task_signal_handler - set the signal handler of a task
</dd></dl>

<dl><dt>
<H3>SYNOPSIS</H3>
</dt><dd>
#include "rtai_sched.h"
<p>
<B>void rt_task_signal_handler (RT_TASK *</B><I>task</I><B>,
	void (*</B><I>handler</I><B>)(void));</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
<b>rt_task_signal_handler</b> installs or changes the signal function
of a real time task.
<BR>
<I>task</I> is a pointer to the real time task
<BR>
<I>handler</I> is the entry point of the signal function.
<BR>
Signal handler function can be set also when the task is
newly created with <b>rt_task_init</b>. 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.
</dd></dl>

<dl><dt>
<H3>RETURN VALUE</H3>
</dt><dd>
On success 0 is returned.
On failure a negative value is returned as described below.
</dd></dl>

<dl><dt>
<H3>ERRORS</H3>
</dt><dd>
	<dl><dt>
	-EINVAL
	</dt><dd>
	<I>task</I> does not refer to a valid task.
	</dd></dl>
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>
<HR ALIGN=LEFT SIZE=1 NOSHADE WIDTH="100%">
<!-- -------------------------------------------------------- -->

<A NAME="rt_set_runnable_on_cpus"></A>
<A NAME="rt_set_runnable_on_cpuid"></A>
<dl><dt>
<H3>NAME</H3>
</dt><dd>
rt_set_runnable_on_cpus, rt_set_runnable_on_cpuid - assign CPUs to a task
</dd></dl>

<dl><dt>
<H3>SYNOPSIS</H3>
</dt><dd>
#include "rtai_sched.h"
<p>
<B>void rt_set_runnable_on_cpus (RT_TASK *</B><I>task</I><B>,
	unsigned int </B><I>cpu_mask</I><B>);</B>
<p>
<B>void rt_set_runnable_on_cpuid (RT_TASK *</B><I>task</I><B>,
	unsigned int </B><I>cpuid</I><B>);</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
<b>rt_set_runnable_on_cpus</b>, <b>rt_set_runnable_on_cpuid</b> select
one or more CPUs which are allowed to run task <I>task</I>.
<b>rt_set_runnable_on_cpuid</b> assigns task to a specific CPU however
<b>rt_set_runnable_on_cpus</b> magically selects one CPU from the given
set which task <I>task</I> will run on.
<br>
Bit&lt;n&gt; of <I>cpu_mask</I> enables CPU&lt;n&gt;.
<p>
If no CPU selected by <I>cpu_mask</I> or <I>cpuid</I> is available,
both functions choose a possible CPU automagically.
<p>
Note: This call has no effect on uniprocessor systems.
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>
<HR ALIGN=LEFT SIZE=1 NOSHADE WIDTH="100%">
<!-- -------------------------------------------------------- -->

<A NAME="rt_task_use_fpu"></A>
<A NAME="rt_linux_use_fpu"></A>
<dl><dt>
<H3>NAME</H3>
</dt><dd>
rt_task_use_fpu, rt_linux_use_fpu - set indication of FPU usage
</dd></dl>

<dl><dt>
<H3>SYNOPSIS</H3>
</dt><dd>
#include "rtai_sched.h"
<p>
<B>int rt_task_use_fpu (RT_TASK* </B><I>task</I><B>,
	int </B><I>use_fpu_flag</I><B>);</B>
<p>
<B>void rt_linux_use_fpu (int </B><I>use_fpu_flag</I><B>);</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
<b>rt_task_use_fpu</b> informs the scheduler that floating point
arithmetic operations will be used by the real time task <I>task</I>.
<p>
<b>rt_linux_use_fpu</b> informs the scheduler that floating point
arithmetic operations will be used the background task (i.e.
the Linux kernel itself and <em>all of its processes</em>!).
<p>
If <I>use_fpu_flag</I> has nonzero value, FPU context is also switched
when <i>task</i> or the kernel became active. This makes task switching slower.
<p>
Initial value of this flag is set by <b>rt_task_init</b> when the
real time task is created. By default Linux "task" has this flag cleared.
It can be set with <b>LinuxFpu</b> command line parameter of the
<b>rtai_sched</b> module.
</dd></dl>

<dl><dt>
<H3>RETURN VALUE</H3>
</dt><dd>
On success 0 is returned.
On failure a negative value is returned as described below.
</dd></dl>

<dl><dt>
<H3>ERRORS</H3>
</dt><dd>
	<dl><dt>
	-EINVAL
	</dt><dd>
	<I>task</I> does not refer to a valid task.
	</dd></dl>
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>
<HR ALIGN=LEFT SIZE=1 NOSHADE WIDTH="100%">
<!-- -------------------------------------------------------- -->

<A NAME="rt_preempt_always"></A>
<A NAME="rt_preempt_always_cpuid"></A>
<dl><dt>
<H3>NAME</H3>
</dt><dd>
rt_preempt_always, rt_preempt_always_cpuid - enable hard preemption
</dd></dl>

<dl><dt>
<H3>SYNOPSIS</H3>
</dt><dd>
#include "rtai_sched.h"
<p>
<B>void rt_preempt_always (int </B><I>yes_no</I><B>);</B>
<p>
<B>void rt_preempt_always_cpuid (int </B><I>yes_no</I><B>,
	unsigned int</b><i>cpu_id</i><b>);</B>
</dd></dl>

<dl><dt>
<H3>DESCRIPTION</H3>
</dt><dd>
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.
<p>
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.
<p>
Initial value of this flag can be set with <b>PreemptAlways</b>
command line parameter of the <b>rtai_sched</b> module.
<p>
Note: currently the booth functions are equal, parameter <i>cpu_id</i>
is ignored.
</dd></dl>

<p align=right><A HREF="manual.html#task">[return to index]</A></p>

</BODY>
</HTML>