Task creation and management

Detailed Description

This group of functions provides routines to create, delete, and manipulate the state of tasks.


Defines

#define TIROS_MIN_CTXT_SZ   TRPORT_MIN_CTXT_SZ

Typedefs

typedef void(*) taskfunc_t (void *)

Functions

tid_t os_task_create (taskfunc_t func, osptr_t param, osword_t *stack, osword_t stacksize, tid_t priority)
tid_t os_self_tid (void)
int8_t os_prio_set (tid_t task, tid_t prio)
tid_t os_prio_get (tid_t task, uint8_t options)
int8_t os_task_del (tid_t task)
int8_t os_task_suspend (tid_t task)
int8_t os_task_resume (tid_t task)

Define Documentation

#define TIROS_MIN_CTXT_SZ   TRPORT_MIN_CTXT_SZ

Minimum amount of space is oswwords (not bytes).

Definition at line 423 of file tiros.h.

Typedef Documentation

typedef void(* ) taskfunc_t(void *)

Task Prototype.

This specifies the form of the function that begins a task.

Definition at line 428 of file tiros.h.

Function Documentation

tid_t os_task_create ( taskfunc_t  func,
osptr_t  param,
osword_t *  stack,
osword_t  stacksize,
tid_t  priority 
)

Create a task.

Calling Context:

  1. Before os_start().
  2. From within a task.
  3. From an ISR.

  #define TASK1_STKSZ  (TIROS_MIN_CTXT_SZ  + 64)  // 64 words more than min
  osword_t task1_stk[TASK1_STKSZ]; 
  void task1(void *arg)
  {
  //  Task does something. never exits 
  }
  
  void main(void)
  {
    tid_t t1_tid;
    tid_t idle_tid; 
    int arg_to_pass_to_task1
    os_init();
    t1_tid = os_task_create(task1, (osptr_t) arg_to_pass_to_task1,
                            task1_stk, TASK1_STKSZ, TASK1_PRIO);
   
    if (t1_tid == ILLEGAL_ELEM) {
      error("task1 error");
    }  
              .
              .
              .
              

    os_start();     
  }
Parameters:
func Function pointer to the task.
param The parameter to be passed to the task.
stack Pointer to the stack to be used.
stacksize Size of the stack. NOTE: This is specified in osword_t not in bytes. This is so that the stack is not misaligned. Use the TIROS_MIN_CTXT_SZ value to help in sizing the stack appropriately.
priority Task priority.
Returns:
ID of the task created or ILLEGAL_ELEM if call failed. This happens if there are no TCBs or if a task is already allocated to the priority level.

tid_t os_self_tid ( void   ) 

A task's self identification.

Calling Context:

  1. From within a task.
  2. From an ISR.

Returns:
Return the task id or ILLEGAL_ELEM if called from an ISR.

int8_t os_prio_set ( tid_t  task,
tid_t  prio 
)

Set the priority of a task.

This modifies the base priority of a task. The function returns SUCCESS if the priority change was successful OR if the current priority of the task is the same as the desired priority. When the default priority ceiling algorithm is used for mutual exclusion, the priority of a task holding a mutex cannot be changed. Attempting this returns ERR_WOULDBLOCK_MUTEX

Calling Context:

  1. From within a task.
  2. From an ISR.

Parameters:
task ID of the task to have a priority change.
prio New priority.
Returns:
{SUCCESS, ERR_NOSUCHTASK, ERR_PRIO_IN_USE, ERR_WOULDBLOCK_MUTEX }.

tid_t os_prio_get ( tid_t  task,
uint8_t  options 
)

Get the priority of a task.

Parameters:
task ID of the task whose priority is queried.
options Get either the real or effective priority. If O_EFFECTIVE_PRIO is specified, then the effective priority is returned.
Calling Context:
  1. Before os_start().
  2. From within a task.
  3. From an ISR.

Parameters:
task ID of the task
options [ O_EFFECTIVE_PRIO ]
Returns:
ILLEGAL_ELEM if failed or the task priority

int8_t os_task_del ( tid_t  task  ) 

Delete a task.

A task can be deleted if it is not in possession of any mutexes. A task can also delete itself.

Calling Context:

  1. From within a task.
  2. From an ISR.

Parameters:
task Task to be deleted. This can be the current task.
Returns:
{SUCCESS, ERR_NOSUCHTASK, ERR_TASKBLOCKED}.

int8_t os_task_suspend ( tid_t  task  ) 

Suspend a task.

A task can only be suspended if it is not holding any mutexes. This is by design: If a task holding a mutex were to be suspended, it could result in a priority inversion or starvation. A task can also suspend itself. In this case, it will only resume running after some other task resumes it (

See also:
os_task_resume). When the task resumes, it returns SUCCESS (not ERR_RESUMED), since this is the intended operation.
Calling Context:
  1. From within a task.
  2. From an ISR.

Parameters:
task Task to be suspended.
Returns:
{SUCCESS, ERR_NOSUCHTASK, ERR_TASKBLOCKED} .

int8_t os_task_resume ( tid_t  task  ) 

Resume a task.

This call can be used to forcibly resume: 1) a task that is waiting on a lock, 2) one that has been suspended, 3) one that is sleeping. The effect of this call is to make the designated task ready for running. Note: a task that is sleeping may be woken up earlier than its sleeptime, explicitly by the resume command. Similarly, a task that is waiting on a lock will be forcibly readied and scheduled even before its timeout expires. If a task is already in the ready queue, then it is not altered.

Calling Context:

  1. From within a task.
  2. From an ISR.

Parameters:
task Task to be resumed.
Returns:
{SUCCESS, ERR_NOSUCHTASK }.

TiROS User Manual: Last Updated on Fri Jul 20 10:52:24 2007