tk_ref_tsk

Reference Task Status

[C Language Interface]

ER ercd = tk_ref_tsk ( ID tskid, T_RTSK *pk_rtsk ) ;
[Parameters]

ID	tskid	Task ID


T_RTSK*	pk_rtsk	Address of packet for returning task status
[Return Parameters]

ER	ercd	Error code

pk_rtsk detail:
    VP    exinf      Extended information
    PRI   tskpri     Current task priority
    PRI   tskbpri    Base priority
    UINT  tskstat    Task state
    UW    tskwait    Wait factor
    ID    wid        Waiting object ID
    INT   wupcnt     Queued wakeup requests
    INT   suscnt     Nested suspend requests
(Other implementation-dependent parameters may be added beyond this point.)


[Error Codes]

E_OK     Normal completion
E_ID     Invalid ID number (tskid is invalid or cannot be used)
E_NOEXS  Object does not exist (the task specified in tskid does not exist)
E_PAR    Parameter error (the address of the return parameter packet cannot be used)
[Description]

Gets the state of the task specified in tskid.

tskstat takes the following values.


tskstat:	
      TTS_RUN        0x0001   RUN
      TTS_RDY        0x0002   READY
      TTS_WAI        0x0004   WAIT
      TTS_SUS        0x0008   SUSPEND
      TTS_WAS        0x000c   WAIT-SUSPEND
      TTS_DMT        0x0010   DORMANT
      TTS_NODISWAI   0x0080   Wait state disabled

Task states such as TTS_RUN and TTS_WAI are expressed by corresponding bits, which is useful when making a complex state decision (e.g., deciding that the state is one of either RUN or READY state).

Note that, of the above states, TTS_WAS is a combination of TTS_SUS and TTS_WAI, but TTS_SUS is never combined with other states (TTS_RUN, TTS_RDY, and TS_DMT). In the case of TTS_WAI (including TTS_WAS), if wait states are disabled by tk_dis_wai, TTS_NODISWAI is set. TTS_NODISWAI is never combined with states other than TTS_WAI.

When tk_ref_tsk is executed for an interrupted task from an interrupt handler, RUN (TTS_RUN) is returned as tskstat.

When tskstat is TTS_WAI (including TTS_WAS), the values of tskwait and wid are as shown in Table 4.2.

Table 4.2: Values of tskwait and wid

  • When tskstat is not TTS WAI (including TTS WAS), both tskwait and wid are 0.
  • For a task in DORMANT state, wupcnt = 0 and suscnt = 0.
  • The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when a system call is issued from a task-independent portion and tskid = TSK_SELF = 0 is specified, error code E_ID is returned.
  • When the task specified with tk_ref_tsk does not exist, error code E_NOEXS is returned.
[Additional Notes]

Even when tskid = TSK_SELF is specified in this system call, the ID of the invoking task is not known. Use tk_get_tid to find out the ID of the invoking task.

[Difference with T-Kernel]

Maximum consecutive execution time (slicetime), wait-disabled waiting factor (waitmask), permitted task exception (texmask), and occurred task event (tskevent) are deleted from T_RTSK. Non-disable wait state (TTS_NODISWAI) is deleted from the values set to tskstat, and the value concerning task event (TTW_EVn) is deleted from the values set to tskwait. This is because, in µT-Kernel, there are no functions concerning timesharing execution, wait-disabled state, task exception, and task event.

[Difference with T-Kernel 1.00.00]

tskwait, the member of T_RTSK, is of UW type instead of UINT type. In µT-Kernel, 16-bit width is sufficient for this member, but 32-bit width is required for T-Kernel. Therefore, this member is modified to UW type based on the policy that those that require 32-bit width are set to the W/UW types whose bit widths are explicitly defined.

Comments

Click here to Post a Comment