api.c File Reference

---

Detailed Description

Common scheduling function.

Author:

Paolo Mantegazza

This file is part of the RTAI project.

Note:

Copyright © 1999-2003 Paolo Mantegazza <mantegazza@aero.polimi.it>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Include dependency graph for api.c:

Functions
int	rt_get_prio (RT_TASK *task)
	Check a task priority.
int	rt_get_inher_prio (RT_TASK *task)
	Check a task priority.
int	rt_change_prio (RT_TASK *task, int priority)
	Change a task priority.
RT_TASK *	rt_whoami (void)
	Get the task pointer of the current task.
void	rt_task_yield (void)
	Yield the current task.
int	rt_task_suspend (RT_TASK *task)
	rt_task_suspend suspends execution of the task task.
int	rt_task_resume (RT_TASK *task)
	Resume a task.
int	rt_get_task_state (RT_TASK *task)
	Query task state.
void	rt_linux_use_fpu (int use_fpu_flag)
	Set indication of FPU usage.
int	rt_task_use_fpu (RT_TASK *task, int use_fpu_flag)
int	rt_task_signal_handler (RT_TASK *task, void(*handler)(void))
	Set the signal handler of a task.
int	rt_task_make_periodic_relative_ns (RT_TASK *task, RTIME start_delay, RTIME period)
	Make a task run periodically.
int	rt_task_make_periodic (RT_TASK *task, RTIME start_time, RTIME period)
	Make a task run periodically.
void	rt_task_wait_period (void)
	Wait till next period.
RTIME	next_period (void)
	Get the time a periodic task will be resumed after calling rt_task_wait_period.
void	rt_busy_sleep (int ns)
	Delay/suspend execution for a while.
void	rt_sleep (RTIME delay)
	Delay/suspend execution for a while.
void	rt_sleep_until (RTIME time)
	Delay/suspend execution for a while.
int	rt_register (unsigned long name, void *adr, int type, struct task_struct *t)
int	rt_drg_on_name (unsigned long name)
int	rt_drg_on_adr (void *adr)
unsigned long	rt_get_name (void *adr)
	Get an object name by its address.
void *	rt_get_adr (unsigned long name)
	Get an object address by its name.

---

Function Documentation

RTIME next_period (  void   )

Get the time a periodic task will be resumed after calling rt_task_wait_period. this function returns the time when the caller task will run next. Combined with the appropriate rt_get_time function() it can be used for checking the fraction of period used or any period overrun. Returns: Next period time in internal count units.

void rt_busy_sleep (  int  ns  )

Delay/suspend execution for a while. 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 so it should be used only for very short synchronization delays. On machine not having a TSC clock it can lead to many microseconds uncertain busy sleeps because of the need of reading the 8254 timer. Parameters: ns  is the number of nanoseconds to wait. See also: rt_sleep(), rt_sleep_until(). Note: A higher priority task or interrupt handler can run before the task goes to sleep, so the actual time spent in these functions may be longer than that specified.

int rt_change_prio (  RT_TASK *  task, int  priority )

Change a task priority. rt_change_prio changes the base priority of task task to prio. Recall that a task has a base native priority, assigned at its birth or by rt_change_prio(), and an actual, inherited, priority. They can be different because of priority inheritance. Parameters: task  is the affected task. priority  is the new priority, it can range within 0 < prio < RT_SCHED_LOWEST_PRIORITY. Returns: rt_change_prio returns the base priority task task had before the change. Note: To be used only with RTAI24.x.xx (FIXME).

int rt_get_inher_prio (  RT_TASK *  task  )

Check a task priority. rt_get_prio returns the base priority task task has inherited from other tasks, either blocked on resources owned by or waiting to pass a message to task task. Recall that a task has a base native priority, assigned at its birth or by rt_change_prio(), and an actual, inherited, priority. They can be different because of priority inheritance. Parameters: task  is the affected task. Returns: rt_get_inher_prio returns the priority of task task. Note: To be used only with RTAI24.x.xx.

int rt_get_prio (  RT_TASK *  task  )

Check a task priority. rt_get_prio returns the base priority of task task. Recall that a task has a base native priority, assigned at its birth or by rt_change_prio(), and an actual, inherited, priority. They can be different because of priority inheritance. Parameters: task  is the affected task. Returns: rt_get_prio returns the priority of task task. Note: To be used only with RTAI24.x.xx.

int rt_get_task_state (  RT_TASK *  task  )

Query task state. rt_get_task_state returns the state of a real time task. Parameters: task  is a pointer to the task structure. Task state is formed by the bitwise OR of one or more of the following flags: Return values: READY  Task task is ready to run (i.e. unblocked). Note that on a UniProcessor machine the currently running task is just in READY state, while on MultiProcessors can be (READY | RUNNING), see below. SUSPENDED  Task task blocked waiting for a resume. DELAYED  Task task blocked waiting for its next running period or expiration of a timeout. SEMAPHORE  Task task blocked on a semaphore, waiting for the semaphore to be signaled. SEND  Task task blocked on sending a message, receiver was not in RECEIVE state. RECEIVE  Task task blocked waiting for incoming messages, sends or rpcs. RPC  Task task blocked on a Remote Procedure Call, receiver was not in RECEIVE state. RETURN  Task task blocked waiting for a return from a Remote Procedure Call, receiver got the RPC but has not replied yet. RUNNING  Task task is running, used only for SMP schedulers. The returned task state is just an approximate 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. rt_get_task_state does not perform any check on pointer task.

void rt_linux_use_fpu (  int  use_fpu_flag  )

Set indication of FPU usage. rt_linux_use_fpu informs the scheduler that floating point arithmetic operations will be used also by foreground Linux processes, i.e. the Linux kernel itself (unlikely) and any of its processes. Parameters: use_fpu_flag  If this parameter has a nonzero value, the Floating Point Unit (FPU) context is also switched when task or the kernel becomes active. This makes task switching slower, negligibly, on all 32 bits CPUs but 386s and the oldest 486s. This flag can be set also by rt_task_init when the real time task is created. With UP and MUP schedulers care is taken to avoid useless saves/ restores of the FPU environment. Under SMP tasks can be moved from CPU to CPU so saves/restores for tasks using the FPU are always carried out. Note that by default Linux has this flag cleared. Beside by using rt_linux_use_fpu you can change the Linux FPU flag when you insmod any RTAI scheduler module by setting the LinuxFpu command line parameter of the rtai_sched module itself. Returns: 0 on success. A negative value on failure as described below: EINVAL: task does not refer to a valid task. See also: rt_linux_use_fpu().

void rt_sleep (  RTIME  delay  )

Delay/suspend execution for a while. 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. Parameters: delay  Corresponds to the time the task is going to be suspended. See also: rt_busy_sleep(), rt_sleep_until(). Note: A higher priority task or interrupt handler can run before the task goes to sleep, so the actual time spent in these functions may be longer than the the one specified.

void rt_sleep_until (  RTIME  time  )

Delay/suspend execution for a while. 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. Parameters: time  Absolute time till the task have to be suspended See also: rt_busy_sleep(), rt_sleep_until(). Note: A higher priority task or interrupt handler can run before the task goes to sleep, so the actual time spent in these functions may be longer than the the one specified.

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

Make a task run periodically. rt_task_make_periodic 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 defined through 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 nanoseconds. Parameters: task  is a pointer to the task you want to make periodic. start_time  is the absolute time to wait before the task start running, in clock ticks. period  corresponds to the period of the task, in clock ticks. Return values: 0  on success. A negative value on failure as described below: EINVAL: task does not refer to a valid task. See also: rt_task_make_periodic_relative_ns(). Recall that the term clock ticks depends on the mode in which the hard timer runs. So if the hard timer was set as periodic a clock tick will last as the period set in start_rt_timer, while if oneshot mode is used a clock tick will last as the inverse of the running frequency of the hard timer in use and irrespective of any period used in the call to start_rt_timer.

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

Make a task run periodically. 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 defined through 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 nanoseconds. Parameters: task  is a pointer to the task you want to make periodic. start_delay  is the time, to wait before the task start running, in nanoseconds. period  corresponds to the period of the task, in nanoseconds. Return values: 0  on success. A negative value on failure as described below: EINVAL: task does not refer to a valid task. Recall that the term clock ticks depends on the mode in which the hard timer runs. So if the hard timer was set as periodic a clock tick will last as the period set in start_rt_timer, while if oneshot mode is used a clock tick will last as the inverse of the running frequency of the hard timer in use and irrespective of any period used in the call to start_rt_timer.

int rt_task_resume (  RT_TASK *  task  )

Resume a task. rt_task_resume resumes execution of the task task previously suspended by rt_task_suspend(), or makes a newly created task ready to run, if it makes the task ready. Since no account is made for multiple suspend rt_task_resume unconditionally resumes any task it makes ready. Parameters: task  pointer to a task structure. Returns: 0 on success. A negative value on failure as described below: EINVAL: task does not refer to a valid task. Note: the new RTAI 24.1.xx (FIXME) development releases take into account multiple suspend and require as many rt_task_resumes as the rt_task_suspends placed on a task.

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

Set the signal handler of a task. rt_task_signal_handler installs, or changes, the signal function of a real time task. Parameters: task  is a pointer to the real time task. handler  is the entry point of the signal function. A signal handler function can be set also when the task is newly created with rt_task_init(). The 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, except at its very first scheduling. It allows you to implement whatever signal management policy you think useful, and many other things as well (FIXME). Returns: 0 on success.A negative value on failure as described below: EINVAL: task does not refer to a valid task.

int rt_task_suspend (  RT_TASK *  task  )

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. No account is made for multiple suspends, i.e. a multiply suspended task is made ready as soon as it is rt_task_resumed, thus immediately resuming its execution if it is the highest in priority. Parameters: task  pointer to a task structure. Returns: 0 on success. A negative value on failure as described below: EINVAL: task does not refer to a valid task. Note: the new RTAI 24.1.xx (FIXME) development releases take into account multiple suspend and require as many rt_task_resume() as the rt_task_suspends placed on a task.

int rt_task_use_fpu (  RT_TASK *  task, int  use_fpu_flag )

rt_task_use_fpu informs the scheduler that floating point arithmetic operations will be used by the real time task task. Parameters: task  is a pointer to the real time task. use_fpu_flag  If this parameter has a nonzero value, the Floating Point Unit (FPU) context is also switched when task or the kernel becomes active. This makes task switching slower, negligibly, on all 32 bits CPUs but 386s and the oldest 486s. This flag can be set also by rt_task_init() when the real time task is created. With UP and MUP schedulers care is taken to avoid useless saves/restores of the FPU environment. Under SMP tasks can be moved from CPU to CPU so saves/restores for tasks using the FPU are always carried out. Returns: 0 on success. A negative value on failure as described below: EINVAL: task does not refer to a valid task. See also: rt_linux_use_fpu().

void rt_task_wait_period (  void   )

Wait till next period. 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 a periodic execution by calling rt_task_make_periodic() or rt_task_make_periodic_relative_ns(). Note: The task is suspended only temporarily, i.e. it simply gives up control until the next time period.

void rt_task_yield (  void   )

Yield the current task. rt_task_yield() stops the current task and takes it at the end of the list of ready tasks having its same priority. The scheduler makes the next ready task of the same priority active. Recall that RTAI schedulers allow only higher priority tasks to preempt the execution of lower priority ones. So equal priority tasks cannot preempt each other and rt_task_yield() should be used if a user needs a cooperative time slicing among equal priority tasks. The implementation of the related policy is wholly in the hand of the user. It is believed that time slicing is too much an overhead for the most demanding real time applications, so it is left up to you.

RT_TASK* rt_whoami (  void   )

Get the task pointer of the current task. Calling rt_whoami from a task can get a pointer to its own task structure. Returns: The pointer to the current task.

---