Task management services.
[Native RTAI API.]


Detailed Description

Task management services.


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.


Function Documentation

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

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:
  • RT_HOOK_TSTART: 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 RT_HOOK_TASKPTR() macro.

  • RT_HOOK_TDELETE: 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 RT_HOOK_TASKPTR() macro.

  • RT_HOOK_TSWITCH: 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 RT_HOOK_TASKPTR() 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.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

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

Create a new real-time task.

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

  • T_CPU(cpuid) makes the new task affine to CPU # cpuid. CPU identifiers range from 0 to CONFIG_RTAI_HW_NRCPUS - 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.

Context: This routine can be called on behalf of a task or from the initialization code.

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, or if task is NULL but not called from a task context.

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

Side-effect: This routine calls the rescheduling procedure if the current task self-deletes.

Context: This routine can always be called on behalf of a task. It can also be called on behalf of the initialization code provided task is non-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, or if task is NULL but not called from a task context.

  • -EIDRM is returned if task is a deleted task descriptor.
Context: This routine can always be called on behalf of a task. It can also be called on behalf of an interrupt context or from the initialization code provided task is non-NULL.

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.

Side-effect: This routine calls the rescheduling procedure if the suspension nesting level falls down to zero as a result of the current invocation.

Context: This routine can be called on behalf of a task, interrupt context, or from the initialization code.

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.
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 has already elapsed.

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

Side-effect: This routine calls the rescheduling procedure if the operation affects the current task and idate has not elapsed yet.

Context: This routine can always be called on behalf of a task. It can also be called on behalf of the initialization code provided task is non-NULL.

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 expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in 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.

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

Context: This routine can always be called on behalf of a task. It can also be called on behalf of an interrupt context or from the initialization code provided task is non-NULL.

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.

Side-effect: This routine calls the rescheduling procedure unless a null delay is given.

Context: This routine can be called on behalf of a task.

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 expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in 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.

Side-effect: This routine calls the rescheduling procedure unless an already elapsed date is given.

Context: This routine can be called on behalf of a task.

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 expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in nanoseconds.

int rt_task_start RT_TASK *  task,
void(*  entry)(void *cookie),
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 START 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.

Side-effect: This routine calls the rescheduling procedure.

Context: This routine can be called on behalf of a task context or from the initialization code.

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, or if task is NULL but not called from a task context.

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

Side-effect: This routine calls the rescheduling procedure if the current task suspends itself.

Context: This routine can always be called on behalf of a task. It can also be called on behalf of an interrupt context or from the initialization code provided task is non-NULL.

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.

Side-effects: This service calls the rescheduling procedure.

Context: This routine can be called on behalf of a task, interrupt context or from the initialization code.

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.

Side-effect: This routine calls the rescheduling procedure unless an overrun has been detected. In the latter case, the current task immediately returns from this service without being delayed.

Context: This routine can be called on behalf of a task.

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.

Side-effect: This routine calls the rescheduling procedure.

Context: This routine can be called on behalf of a task.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8