Task management services.
[Native RTAI API.]


Detailed Description

RTAI provides a set of multitasking mechanisms. The basic process object performing actions in RTAI is a task, a logically complete path of application code. Each RTAI task is an independent portion of the overall application code embodied in a C procedure, which executes on its own stack context.

The RTAI scheduler ensures that concurrent tasks are run according to one of the supported scheduling policies. Currently, the RTAI scheduler supports fixed priority-based FIFO and round-robin policies.


Files

file  task.c
 This file is part of the RTAI project.

Functions

int rt_task_create (RT_TASK *task, const char *name, int stksize, int prio, int mode)
 Create a new real-time task.
int rt_task_start (RT_TASK *task, void(*entry)(void *cookie), void *cookie)
 Start a real-time task.
int rt_task_suspend (RT_TASK *task)
 Suspend a real-time task.
int rt_task_resume (RT_TASK *task)
 Resume a real-time task.
int rt_task_delete (RT_TASK *task)
 Delete a real-time task.
int rt_task_yield (void)
 Manual round-robin.
int rt_task_set_periodic (RT_TASK *task, RTIME idate, RTIME period)
 Make a real-time task periodic.
int rt_task_wait_period (void)
 Wait for the next periodic release point.
int rt_task_set_priority (RT_TASK *task, int prio)
 Change the base priority of a real-time task.
int rt_task_sleep (RTIME delay)
 Delay the calling task (relative).
int rt_task_sleep_until (RTIME date)
 Delay the calling task (absolute).
int rt_task_unblock (RT_TASK *task)
 Unblock a real-time task.
int rt_task_inquire (RT_TASK *task, RT_TASK_INFO *info)
 Inquire about a real-time task.
int rt_task_add_hook (int type, void(*routine)(void *cookie))
 Install a task hook.
int rt_task_remove_hook (int type, void(*routine)(void *cookie))
 Remove a task hook.
int rt_task_catch (void(*handler)(rt_sigset_t))
 Install a signal handler.
int rt_task_notify (RT_TASK *task, rt_sigset_t signals)
 Send signals to a task.
int rt_task_set_mode (int clrmask, int setmask, int *mode_r)
 Change task mode bits.
RT_TASK * rt_task_self (void)
 Retrieve the current task.
int rt_task_slice (RT_TASK *task, RTIME quantum)
 Set a task's round-robin quantum.
int rt_task_bind (RT_TASK *task, const char *name)
 Bind to a real-time task.
int rt_task_unbind (RT_TASK *task)
 Unbind from a real-time task.


Function Documentation

int rt_task_add_hook int  type,
void(*)(void *cookie)  routine
 

Install a task hook.

The real-time kernel allows to register user-defined routines which get called whenever a specific scheduling event occurs. Multiple hooks can be chained for a single event type, and get called on a FIFO basis.

The scheduling is locked while a hook is executing.

Parameters:
type Defines the kind of hook to install:
  • T_HOOK_START: The user-defined routine will be called on behalf of the starter task whenever a new task starts. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the started task through the T_HOOK_DESC() macro.

  • T_HOOK_DELETE: The user-defined routine will be called on behalf of the deletor task whenever a task is deleted. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the deleted task through the T_HOOK_DESC() macro.

  • T_HOOK_SWITCH: The user-defined routine will be called on behalf of the resuming task whenever a context switch takes place. An opaque cookie is passed to the routine which can use it to retrieve the descriptor address of the task which has been switched in through the T_HOOK_DESC() macro.

Parameters:
routine The address of the user-supplied routine to call.
Returns:
0 is returned upon success. Otherwise, one of the following error codes indicates the cause of the failure:
  • -EINVAL is returned if type is incorrect.

  • -ENOMEM is returned if not enough memory is available from the system heap to add the new hook.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task

Rescheduling: never.

int rt_task_bind RT_TASK *  task,
const char *  name
 

Bind to a real-time task.

This user-space only service retrieves the ubiquitous descriptor of a given RTAI task identified by its symbolic name. If the task does not exist on entry, this service blocks the caller until a task of the given name is created.

Parameters:
name A valid NULL-terminated name which identifies the task to bind to.
task The address of a task descriptor retrieved by the operation. Contents of this memory is undefined upon failure.
Returns:
0 is returned upon success. Otherwise:
  • -EFAULT is returned if task or name is referencing invalid memory.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed.

Environments:

This service can be called from:

  • User-space task (switches to primary mode)

Rescheduling: always unless the request is immediately satisfied.

int rt_task_catch void(*)(rt_sigset_t)  handler  ) 
 

Install a signal handler.

This service installs a signal handler for the current task. Signals are discrete events tasks can receive each time they resume execution. When signals are pending upon resumption, handler is fired to process them. Signals can be sent using rt_task_notify(). A task can block the signal delivery by passing the T_NOSIG bit to rt_task_set_mode().

Calling this service implicitely unblocks the signal delivery for the caller.

Parameters:
handler The address of the user-supplied routine to fire when signals are pending for the task. This handler is passed the set of pending signals as its first and only argument.
Returns:
0 is always returned.
Environments:

This service can be called from:

  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_task_create RT_TASK *  task,
const char *  name,
int  stksize,
int  prio,
int  mode
 

Create a new real-time task.

Creates a real-time task, either running in a kernel module or in user-space depending on the caller's context.

Parameters:
task The address of a task descriptor RTAI will use to store the task-related data. This descriptor must always be valid while the task is active therefore it must be allocated in permanent memory.
The task is left in an innocuous state until it is actually started by rt_task_start().

Parameters:
name An ASCII string standing for the symbolic name of the task. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created task.
stksize The size of the stack (in bytes) for the new task. If zero is passed, a reasonable pre-defined size will be substituted. This parameter is ignored for user-space tasks.
prio The base priority of the new thread. This value must range from [1 .. 99] (inclusive) where 1 is the highest priority.
mode The task creation mode. The following flags can be OR'ed into this bitmask, each of them affecting the new task:
  • T_FPU allows the task to use the FPU whenever available on the platform. This flag is forced for user-space tasks.

  • T_SUSP causes the task to start in suspended mode. In such a case, the thread will have to be explicitely resumed using the rt_task_resume() service for its execution to actually begin.

  • T_CPU(cpuid) makes the new task affine to CPU # cpuid. CPU identifiers range from 0 to RTHAL_NR_CPUS - 1 (inclusive).

Passing T_FPU|T_CPU(1) in the mode parameter thus creates a task with FPU support enabled and which will be affine to CPU #1.

Returns:
0 is returned upon success. Otherwise:
  • -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to create or register the task.

  • -EEXIST is returned if the name is already in use by some registered object.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_task_delete RT_TASK *  task  ) 
 

Delete a real-time task.

Terminate a task and release all the real-time kernel resources it currently holds. A task exists in the system since rt_task_create() has been called to create it, so this service must be called in order to destroy it afterwards.

The DELETE hooks are called on behalf of the calling context (if any). The information stored in the task control block remains valid until all hooks have been called.

Parameters:
task The descriptor address of the affected task. If task is NULL, the current task is deleted.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EACCES is returned if task is NULL but not called from a task context.

  • -EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code only if task is non-NULL.

  • Kernel-based task
  • User-space task

Rescheduling: always if task is NULL.

int rt_task_inquire RT_TASK *  task,
RT_TASK_INFO *  info
 

Inquire about a real-time task.

Return various information about the status of a given task.

Parameters:
task The descriptor address of the inquired task. If task is NULL, the current task is inquired.
info The address of a structure the task information will be written to.
Returns:
0 is returned and status information is written to the structure pointed at by info upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EACCES is returned if task is NULL but not called from a task context.

  • -EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if task is non-NULL.

  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_task_notify RT_TASK *  task,
rt_sigset_t  signals
 

Send signals to a task.

This service sends a set of signals to a given task. A task can install a signal handler using the rt_task_catch() service to process them.

Parameters:
task The descriptor address of the affected task which must have been previously created by the rt_task_create() service.
signals The set of signals to make pending for the task. This set is OR'ed with the current set of pending signals for the task; there is no count of occurence maintained for each available signal, which is either pending or cleared.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EACCES is returned if task is NULL but not called from a task context.

  • -EIDRM is returned if task is a deleted task descriptor.

  • -ESRCH is returned if task has not set any signal handler.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if task is non-NULL.

  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_task_remove_hook int  type,
void(*)(void *cookie)  routine
 

Remove a task hook.

This service allows to remove a task hook previously registered using rt_task_add_hook().

Parameters:
type Defines the kind of hook to uninstall. Possible values are:
  • T_HOOK_START
  • T_HOOK_DELETE
  • T_HOOK_SWITCH

Parameters:
routine The address of the user-supplied routine to remove from the hook list.
Returns:
0 is returned upon success. Otherwise, one of the following error codes indicates the cause of the failure:
  • -EINVAL is returned if type is incorrect.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task

Rescheduling: never.

int rt_task_resume RT_TASK *  task  ) 
 

Resume a real-time task.

Forcibly resume the execution of a task which has been previously suspended by a call to rt_task_suspend().

The suspension nesting count is decremented so that rt_task_resume() will only resume the task if this count falls down to zero as a result of the current invocation.

Parameters:
task The descriptor address of the affected task.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: possible if the suspension nesting level falls down to zero as a result of the current invocation.

RT_TASK* rt_task_self void   ) 
 

Retrieve the current task.

Return the current task descriptor address.

Returns:
The address of the caller's task descriptor is returned upon success, or NULL if the calling context is asynchronous (i.e. not a RTAI task).
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine Those will cause a NULL return.

  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_task_set_mode int  clrmask,
int  setmask,
int *  mode_r
 

Change task mode bits.

Each RTAI task has a set of internal bits determining various operating conditions; the rt_task_set_mode() service allows to alter three of them, respectively controlling:

  • whether the task locks the rescheduling procedure,
  • whether the task undergoes a round-robin scheduling,
  • whether the task blocks the delivery of signals.

To this end, rt_task_set_mode() takes a bitmask of mode bits to clear for disabling the corresponding modes, and another one to set for enabling them. The mode bits which were previously in effect can be returned upon request.

The following bits can be part of the bitmask:

  • T_LOCK causes the current task to lock the scheduler. Clearing this bit unlocks the scheduler.

  • T_RRB causes the current task to be marked as undergoing the round-robin scheduling policy. If the task is already undergoing the round-robin scheduling policy at the time this service is called, the time quantum remains unchanged.

  • T_NOSIG disables the asynchronous signal delivery for the current task.

Normally, this service can only be called on behalf of a regular real-time task, either running in kernel or user-space. However, as a special exception, requests for setting/clearing the T_LOCK bit from asynchronous contexts are silently dropped, and the call returns successfully if no other mode bits have been specified. This is consistent with the fact that RTAI enforces a scheduler lock until the outer interrupt handler has returned.

Parameters:
clrmask A bitmask of mode bits to clear for the current task, before setmask is applied. 0 is an acceptable value which leads to a no-op.
setmask A bitmask of mode bits to set for the current task. 0 is an acceptable value which leads to a no-op.
mode_r If non-NULL, mode_r must be a pointer to a memory location which will be written upon success with the previous set of active mode bits. If NULL, the previous set of active mode bits will not be returned.
Returns:
0 is returned upon success, or -EINVAL if either setmask or clrmask specifies invalid bits.
Environments:

This service can be called from:

  • Kernel-based task
  • User-space task

Rescheduling: possible, if T_LOCK has been passed into clrmask and the calling context is a task.

int rt_task_set_periodic RT_TASK *  task,
RTIME  idate,
RTIME  period
 

Make a real-time task periodic.

Make a task periodic by programing its first release point and its period in the processor time line. Subsequent calls to rt_task_wait_period() will delay the task until the next periodic release point in the processor timeline is reached.

Parameters:
task The descriptor address of the affected task. This task is immediately delayed until the first periodic release point is reached. If task is NULL, the current task is set periodic.
idate The initial (absolute) date of the first release point, expressed in clock ticks (see note). The affected task will be delayed until this point is reached. If idate is equal to TM_NOW, the current system date is used, and no initial delay takes place.
period The period of the task, expressed in clock ticks (see note).
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EIDRM is returned if task is a deleted task descriptor.

  • -ETIMEDOUT is returned if idate is different from TM_INFINITE and represents a date in the past.

  • -EWOULDBLOCK is returned if the system timer has not been started using rt_timer_start().

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code only if task is non-NULL.

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always if the operation affects the current task and idate has not elapsed yet.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_task_set_priority RT_TASK *  task,
int  prio
 

Change the base priority of a real-time task.

Changing the base priority does not affect the priority boost the target task might have obtained as a consequence of a previous priority inheritance.

Parameters:
task The descriptor address of the affected task.
prio The new task priority. This value must range from [1 .. 99] (inclusive) where 1 is the highest priority.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor, or if prio is invalid.

  • -EACCES is returned if task is NULL but not called from a task context.

  • -EIDRM is returned if task is a deleted task descriptor.

Side-effects:

  • This service calls the rescheduling procedure.

  • Assigning the same priority to a running or ready task moves it to the end of its priority group, thus causing a manual round-robin.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if task is non-NULL.

  • Kernel-based task
  • User-space task

Rescheduling: possible if task is the current one.

int rt_task_sleep RTIME  delay  ) 
 

Delay the calling task (relative).

Delay the execution of the calling task for a number of internal clock ticks.

Parameters:
delay The number of clock ticks to wait before resuming the task (see note). Passing zero causes the task to return immediately with no delay.
Returns:
0 is returned upon success, otherwise:
  • -EINTR is returned if rt_task_unblock() has been called for the sleeping task before the sleep time has elapsed.

  • -EWOULDBLOCK is returned if the system timer is inactive.

Environments:

This service can be called from:

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always unless a null delay is given.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_task_sleep_until RTIME  date  ) 
 

Delay the calling task (absolute).

Delay the execution of the calling task until a given date is reached.

Parameters:
date The absolute date in clock ticks to wait before resuming the task (see note). Passing an already elapsed date causes the task to return immediately with no delay.
Returns:
0 is returned upon success. Otherwise:
  • -EINTR is returned if rt_task_unblock() has been called for the sleeping task before the sleep time has elapsed.

  • -ETIMEDOUT is returned if date has already elapsed.

  • -EWOULDBLOCK is returned if the system timer is inactive.

Environments:

This service can be called from:

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always unless a date in the past is given.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_task_slice RT_TASK *  task,
RTIME  quantum
 

Set a task's round-robin quantum.

Set the time credit allotted to a task undergoing the round-robin scheduling. As a side-effect, rt_task_slice() refills the current quantum of the target task.

Parameters:
task The descriptor address of the affected task. If task is NULL, the current task is considered.
quantum The round-robin quantum for the task expressed in clock ticks (see note).
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor, or if quantum is zero.

  • -EACCES is returned if task is NULL but not called from a task context.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if task is non-NULL.

  • Kernel-based task
  • User-space task

Rescheduling: never.

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_task_start RT_TASK *  task,
void(*)(void *cookie)  entry,
void *  cookie
 

Start a real-time task.

Start a (newly) created task, scheduling it for the first time. This call releases the target task from the dormant state.

The TSTART hooks are called on behalf of the calling context (if any, see rt_task_add_hook()).

Parameters:
task The descriptor address of the affected task which must have been previously created by the rt_task_create() service.
entry The address of the task's body routine. In other words, it is the task entry point.
cookie A user-defined opaque cookie the real-time kernel will pass to the emerging task as the sole argument of its entry point.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EIDRM is returned if task is a deleted task descriptor.

  • -EBUSY is returned if task is already started.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_task_suspend RT_TASK *  task  ) 
 

Suspend a real-time task.

Forcibly suspend the execution of a task. This task will not be eligible for scheduling until it is explicitly resumed by a call to rt_task_resume().

A nesting count is maintained so that rt_task_suspend() and rt_task_resume() must be used in pairs.

Parameters:
task The descriptor address of the affected task. If task is NULL, the current task is suspended.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EACCES is returned if task is NULL but not called from a task context.

  • -EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if task is non-NULL.

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always if task is NULL.

int rt_task_unbind RT_TASK *  task  )  [inline, static]
 

Unbind from a real-time task.

This user-space only service unbinds the calling task from the task object previously retrieved by a call to rt_task_bind().

Parameters:
task The address of a task descriptor to unbind from.
Returns:
0 is always returned.
This service can be called from:

  • User-space task.

Rescheduling: never.

int rt_task_unblock RT_TASK *  task  ) 
 

Unblock a real-time task.

Break the task out of any wait it is currently in. This call clears all delay and/or resource wait condition for the target task. However, rt_task_unblock() does not resume a task which has been forcibly suspended by a previous call to rt_task_suspend(). If all suspensive conditions are gone, the task becomes eligible anew for scheduling.

Parameters:
task The descriptor address of the affected task.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if task is not a task descriptor.

  • -EIDRM is returned if task is a deleted task descriptor.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine
  • Kernel-based task
  • User-space task

Rescheduling: possible.

int rt_task_wait_period void   ) 
 

Wait for the next periodic release point.

Make the current task wait for the next periodic release point in the processor time line.

Returns:
0 is returned upon success. Otherwise:

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the next periodic release point has been reached.

  • -ETIMEDOUT is returned if a timer overrun occurred, which indicates that a previous release point has been missed by the calling task.

Environments:

This service can be called from:

  • Kernel-based task
  • User-space task (switches to primary mode)

Rescheduling: always unless an overrun has been detected. In the latter case, the current task immediately returns from this service without being delayed.

int rt_task_yield void   ) 
 

Manual round-robin.

Move the current task to the end of its priority group, so that the next equal-priority task in ready state is switched in.

Environments:

This service can be called from:

  • Kernel-based task
  • User-space task

Rescheduling: always if a next equal-priority task is ready to run, otherwise, this service leads to a no-op.


Generated on Mon Dec 13 09:49:49 2004 for RTAI API by  doxygen 1.3.9.1