RTEMS 4.9.3 On-Line Library

Task Manager ref_tsk - Reference Task Status

RTEMS ITRON 3.0 API User's Guide

1.4.13: ref_tsk - Reference Task Status

CALLING SEQUENCE:

ER ref_tsk(
  T_RTSK *pk_rtsk,
  ID tskid
);

STATUS CODES:

E_OK - Normal Completion

E_ID - Invalid ID Number (tskid was invalid or could not be used)

E_NOEXS - Object does not exist (the task specified by tskid does not exist)

E_OACV - Object access violation (A tskid less than -4 was specified from a user task. This is implementation dependent.)

E_PAR - Parameter error (the packet address for return parameters cannot be used)

EN_OBJNO - An object number which could not be accessed on the target node is specified.

EN_CTXID - Specified an object on another node when the system call was issued from a task in dispatch disabled state or from a task-independent portion

EN_RPAR - A value outside the range supported by the requesting node and/or transmission packet format was returned as a return parameter (a value outside supported range was returned for exinf, tskpri and/or tskstat)

DESCRIPTION:

This system call refers to the state of the task specified by tskid, and returns its current priority (tskpri), its task state (tskstat), and its extended information (exinf).

Tskstat may take the following values.

tskstat:

TTS_RUN H'0...01 RUN state (currently running)
TTS_RDY H'0...02 READY state (ready to run)
TTS_WAI H'0...04 WAIT state (waiting for something)
TTS_SUS H'0...08 SUSPEND state (forcibly made to wait)
TTS_WAS H'0...0c WAIT-SUSPEND state
TTS_DMT H'0...10 DORMANT state

Since these task states are expressed by bit correspondences they are convenient when looking for OR conditions (such as whether a task is in RUN or READY state). TTS_WAS is a combination of both TTS_SUS and TTS_WAI, TTS_SUS does not combine with any of the other states (TTS_RUN, TTS_RDY or TTS_DMT).

A task may specify itself by specifying tskid = TSK_SELF = 0. Note, however, that an E_ID error will result if tskid = TSK_SELF = 0 is specified when this system call is issued from a task-independent portion.

An E_NOEXS error will result if the task specified to ref_tsk does not exist.

Tskstat will be TTS_RUN if ref_tsk is executed specifying a task which has been interrupted by an interrupt handler.

NOTES:

The values of TTS_RUN, TTS_RDY, TTS_WAI, etc. as return values for tskstat are not necessarily the same value to be entered in the TCB. The way in which task state is represented in the TCB is implementation dependent. When ref_tsk is executed, the internal representation of task state may simply be converted to the standard values TTS_RUN, TTS_RDY, TTS_WAI, etc.

Depending on the implementation, the following additional information can also be referenced in addition to exinf, tskpri and tskstat.

tskwait Reason for wait
wid Wait object ID
wupcnt Number of queued wakeup requests
suscnt Number of nested SUSPEND requests
tskatr Task attributes
task Task starting address
itskpri Initial task priority
stksz Stack size

RTEMS ITRON 3.0 API User's Guide