This chapter describes details of the system calls provided by T-Kernel Operating System (T-Kernel/OS).
Task management functions are functions that directly manipulate or reference task states. Functions are provided for creating and deleting a task, for task starting and exit, changing task priority, and referencing task state. A task is an object identified by an ID number called a task ID. Task states and scheduling rules are explained in the Section called Task States and Scheduling Rules in the Chapter called T-Kernel Concepts.
For control of execution order, a task has a base priority and current priority. When simply "task priority" is mentioned, this means the current priority. The base priority of a task is initialized to the startup priority when a task is started. If the mutex function is not used, the task current priority is always identical to its base priority. For this reason, the current priority immediately after a task is started is the task startup priority. When the mutex function is used, the current priority is set as discussed in the Section called Mutex.
The kernel does not perform processing for freeing of resources acquired by a task (semaphore resources, memory blocks, etc.) upon task exit, other than mutex unlocking. Freeing of task resources is the responsibility of the application.
pk_ctsk Detail:
| void* |
exinf
| Extended Information | Extended information |
| ATR |
tskatr
| Task Attribute | Task attribute |
| FP |
task
| Task Start Address | Task start address |
| PRI |
itskpri
| Initial Task Priority | Initial task priority |
| INT |
stksz
| Stack Size | Stack size (in bytes) |
| INT |
sstksz
| System Stack Size | System stack size (in bytes) |
| void* |
stkptr
| User Stack Pointer | User stack pointer |
| void* |
uatb
| Address of Task Space Page Table | Task space page table |
| INT |
lsid
| Logical Space ID | Logical space ID |
| ID |
resid
| Resource ID | Resource ID |
| UB |
dsname[8]
| DS Object name | DS object name |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
| E_NOMEM | Insufficient memory (memory for control block or user stack cannot be allocated) |
| E_LIMIT | Number of tasks exceeds the system limit |
| E_RSATR | Reserved attribute (tskatr is invalid or cannot be used), or the specified coprocessor does not exist |
| E_NOSPT | Unsupported function (when TA_USERSTACK or TA_TASKSPACE is not supported) |
| E_PAR | Parameter error |
| E_ID | Invalid resource ID (resid) |
| E_NOCOP | The specified coprocessor cannot be used (not installed, or abnormal operation detected) |
Creates a task, assigning to it a task ID number. This system call allocates a TCB (Task Control Block) to the created task and initializes it based on itskpri, task, stksz and other parameters.
After the task is created, it is initially in DORMANT state.
itskpri specifies the initial priority at the time the task is started. Task priority values are specified from 1 to 140, with the smaller numbers indicating higher priority.
exinf can be used freely by the user to insert miscellaneous information about the task. The information set here is passed to the task as startup parameter information and can be referred to by calling tk_ref_tsk. If a larger area is needed for indicating user information, or if the information may need to be changed after the task is created, this can be done by allocating separate memory for this purpose and putting the memory packet address in exinf. The kernel pays no attention to the contents of exinf.
tskatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute part of tskatr is as follows.
tskatr := (TA_ASM || TA_HLNG) | [TA_SSTKSZ] | [TA_USERSTACK] | [TA_TASKSPACE] | [TA_RESID] | [TA_DSNAME] | (TA_RNG0 || TA_RNG1 || TA_RNG2 || TA_RNG3) | [TA_COP0] | [TA_COP1] | [TA_COP2] | [TA_COP3] | [TA_FPU]
| TA_ASM | Indicates that the task is written in assembly language |
| TA_HLNG | Indicates that the task is written in high-level language |
| TA_SSTKSZ | Specifies the system stack size |
| TA_USERSTACK | Points to the user stack |
| TA_TASKSPACE | Points to the task space |
| TA_RESID | Specifies the resource group to which the task belongs |
| TA_DSNAME | Specifies DS object name |
| TA_RNGn | Indicates that the task runs at protection level n |
| TA_COPn | Specifies use of the nth coprocessor (including floating point coprocessor or DSP) |
| TA_FPU | Specifies use of a floating point coprocessor (when a coprocessor specified in TA_COPn is a general-purpose FPU particularly for floating point processing and not dependent on the CPU) |
The function for specifying implementation-dependent attributes can be used, for example, to specify that a task is subject to debugging. One use of the remaining system attribute fields is for indicating multiprocessor attributes in the future.
#define TA_ASM 0x00000000 /* Task in Assembly Language */ #define TA_HLNG 0x00000001 /* Task in High-level language */ #define TA_SSTKSZ 0x00000002 /* System stack size */ #define TA_USERSTACK 0x00000004 /* User stack pointer */ #define TA_TASKSPACE 0x00000008 /* Task space */ #define TA_RESID 0x00000010 /* Task resource group */ #define TA_DSNAME 0x00000040 /* DS object name */ #define TA_RNG0 0x00000000 /* Run at protection level 0 */ #define TA_RNG1 0x00000100 /* Run at protection level 1 */ #define TA_RNG2 0x00000200 /* Run at protection level 2 */ #define TA_RNG3 0x00000300 /* Run at protection level 3 */ #define TA_COP0 0x00001000 /* Use ID=0 coprocessor */ #define TA_COP1 0x00002000 /* Use ID=1 coprocessor */ #define TA_COP2 0x00004000 /* Use ID=2 coprocessor */ #define TA_COP3 0x00008000 /* Use ID=3 coprocessor */
When TA_HLNG is specified, starting the task jumps to the task address not directly but by going through a high-level language environment configuration program (high-level language support routine). The task takes the following form in this case.
void task( INT stacd, void *exinf )
{
/*
(processing)
*/
tk_ext_tsk(); or tk_exd_tsk(); /* Exit task */
}The startup parameters passed to the task include the task startup code stacd specified in tk_sta_tsk, and the extended information exinf specified in tk_cre_tsk.
The task cannot (must not) be terminated by a simple return from the function, otherwise the operation will be indeterminate (implementation-dependent).
The form of the task when the TA_ASM attribute is specified in implementation-dependent, but stacd and exinf must be passed as startup parameters.
The task runs at the protection level specified in the TA_RNGn attribute. When a system call or extended SVC is called, the protection level goes to 0, then goes back to its original level upon return from the system call or extended SVC.
Each task has two stack areas, a system stack and user stack. The user stack is used at the protection level specified in TA_RNGn while the system stack is used at protection level 0. When the calling of a system call or extended SVC causes the protection level to change, the stack is also switched.
Note that a task running at TA_RNG0 does not switch protection levels, so there is no stack switching either. When TA_RNG0 is specified, the combined total of the user stack size and system stack size is the size of one stack, employed as both a user stack and system stack.
When TA_SSTKSZ is specified, sstksz is valid. If TA_SSTKSZ is not specified, sstksz is ignored and the default size applies.
When TA_USERSTACK is specified, stkptr is valid. In this case a user stack is not provided by the OS, but must be allocated by the caller. stksz must be set to 0. If TA_USERSTACK is not specified, stkptr is ignored. Note that if TA_RNG0 is set, TA_USERSTACK cannot be specified. E_PAR occurs if TA_RNG0 and TA_USERSTACK are specified at the same time.
When TA_TASKSPACE is specified, uatb and lsid are valid and are set as task space. If TA_TASKSPACE is not specified, uatb and lsid are ignored and task space is undefined. During the time task space is undefined, only system space can be accessed; access to task (user) space is not allowed. Irrespective of TA_TASKSPACE specification, task space can be changed after a task is created. Note that when task space is changed, in no case does it revert to the task space set at task creation, even when the task returns to DORMANT state, but the task always uses the most recently set task space.
When TA_RESID is specified, resid is valid and its resource group (see the Section called Subsystem Management Functions) is specified as the resource group to which the task belongs. If TA_RESID is not specified, resid is ignored and the task belongs to the system resource group. Note that if the resource group of a task is changed, in no case does it revert to the resource group set at task creation, even when the task returns to DORMANT state, but the task always retains the most recently set resource group (See tk_cre_res).
When TA_DSNAME is specified, dsname is valid and specifies the DS object name. DS object name is used to identify objects by debugger, and it is handled only by T-Kernel/DS API, td_ref_dsname and td_set_dsname. For more details, see the description of td_ref_dsname and td_set_dsname. If TA_DSNAME is not specified, dsname is ignored. Then td_ref_dsname and td_set_dsname return E_OBJ error.
A task runs either at the protection level set in TA_RNGn or at protection level 0. For example, a task for which TA_RNG3 is specified in no case runs at protection level 1 or 2.
In a system with separate interrupt stack, interrupt handlers also use the system stack. An interrupt handler runs at protection level 0.
The system stack default size is decided taking into account the amount taken up by system call execution and, in a system with separate interrupt stack, the amount used by interrupt handlers.
The system stack is system space resident memory used at protection level 0. If TA_USERSTACK is not specified, the user stack is system space resident memory used at the protection level specified in the TA_RNGn attribute. If TA_USERSTACK is specified, the user stack memory attributes are as specified by the caller of this system call. Task space may be made nonresident memory.
The definition of TA_COPn is dependent on the CPU and other hardware and is not portable.
TA_FPU is provided as a portable notation method only for the definition in TA_COPn of a floating point coprocessor. If, for example, the floating point coprocessor is TA_COP0, then TA_FPU = TA_COP0. If there is no particular need to specify the use of a coprocessor for floating point operations, TA_FPU = 0 is set.
Even in a system without an MMU, for the sake of portability all attributes including TA_RNGn must be accepted. It is possible, for example, to handle all TA_RNGn as equivalent to TA_RNG0, but error must not be returned.
In the case of TA_USERSTACK and TA_TASKSPACE, however, E_NOSPT may be returned, since there are many implementations where these cannot be supported without an MMU.
Deletes the task specified in tskid.
This system call changes the state of the task specified in tskid from DORMANT state to NONEXISTENT state (no longer exists in the system), releasing the TCB and stack area that were assigned to the task. The task ID number is also released. When this system call is issued for a task not in DORMANT state, error code E_OBJ is returned.
This system call cannot specify the invoking task. If the invoking task is specified, error code E_OBJ is returned since the invoking task is not in DORMANT state. The invoking task is deleted not by this system call but by the tk_exd_tsk system call.
Starts the task specified in tskid. This system call changes the state of the specified task from DORMANT state to READY state.
Parameters to be passed to the task when it starts can be set in stacd. These parameters can be referred to from the started task, enabling use of this feature for simple message passing.
The task priority when it starts is the task startup priority (itskpri) specified when the started task was created.
Start requests by this system call are not queued. If this system call is issued while the target task is in a state other than DORMANT state, the system call is ignored and error code E_OBJ is returned to the calling task.
None
Does not return to the context issuing the system call.
The following kind of error may be detected, but no return is made to the context issuing the system call even if the error is detected. For this reason the error code cannot be passed directly as a system call return parameter. The behavior in case an error occurs is implementation-dependent.
Exits the invoking task normally and changes its state to DORMANT state.
When a task terminates by tk_ext_tsk, the resources acquired by the task up to that time (memory blocks, semaphores, etc.) are not automatically freed. The user is responsible for releasing such resources before the task exits.
tk_ext_tsk is a system call that does not return to the context from which it was called. Even if an error code is returned when an error of some kind is detected, normally no error checking is performed in the context from which the system call was invoked, leaving the possibility that the program will behave in an unexpected manner. For this reason these system calls do not return even if error is detected.
As a rule, the task priority and other information included in the TCB is reset when the task returns to DORMANT state. If, for example, the task priority is changed by tk_chg_pri and later terminated by tk_ext_tsk, the task priority reverts to the startup priority (itskpri) specified by tk_cre_tsk at startup. It does not keep the task priority in effect at the time tk_ext_tsk was executed.
System calls that do not return to the calling context are those named tk_ret_??? or tk_ext_??? (tk_exd_???).
None
Does not return to the context issuing the system call.
The following kind of error may be detected, but no return is made to the context issuing the system call even if the error is detected. For this reason the error code cannot be passed directly as a system call return parameter. The behavior in case an error occurs is implementation-dependent.
Terminates the invoking task normally and also deletes it. This system call changes the state of the invoking task to NON-EXISTENT state (no longer exists in the system).
When a task terminates by tk_exd_tsk, the resources acquired by the task up to that time (memory blocks, semaphores, etc.) are not automatically freed. The user is responsible for releasing such resources before the task exits.
tk_exd_tsk is a system call that does not return to the context from which it was called. Even if an error code is returned when an error of some kind is detected, normally no error checking is performed in the context from which the system call was invoked, leaving the possibility that the program will behave in an unexpected manner. For this reason these system calls do not return even if error is detected.
Forcibly terminates the task specified in tskid. This system call changes the state of the target task specified in tskid to DORMANT state.
Even if the target task was in the waiting state (including SUSPENDED state), the waiting state is released and the task is terminated. If the target task was in some kind of queue (semaphore wait, etc.), executing tk_ter_tsk results in its removal from the queue.
This system call cannot specify the invoking task. If the invoking task is specified, error code E_OBJ is returned.
The relationships between target task states and the results of executing tk_ter_tsk are summarized in Table 1.
Table 1. Target Task State and Execution Result (tk_ter_tsk)
| Target Task State |
tk_ter_tsk ercd Return Value
| (processing) |
|---|---|---|
| Run state (RUNNING or READY) (not for invoking task) | E_OK | Forced termination |
| Running state (RUNNING) (invoking task) | E_OBJ | No operation |
| Waiting state (WAITING) | E_OK | Forced termination |
| Suspended state (SUSPENDED) | E_OK | Forced termination |
| Waiting-suspended state (WAITING-SUSPENDED) | E_OK | Forced termination |
| Dormant state (DORMANT) | E_OBJ | No operation |
| Non-existent state (NON-EXISTENT) | E_NOEXS | No operation |
When a task is terminated by tk_ter_tsk, the resources acquired by the task up to that time (memory blocks, semaphores, etc.) are not automatically freed. The user is responsible for releasing such resources before the task is terminated.
As a rule, the task priority and other information included in the TCB is reset when the task returns to DORMANT state. If, for example, the task priority is changed by tk_chg_pri and later terminated by tk_ter_tsk, the task priority reverts to the startup priority (itskpri) that is specified by tk_cre_tsk at startup. The task priority at task termination by tk_ter_tsk is not used after the task is restarted by tk_sta_tsk.
Forcible termination of another task is intended for use only by a debugger or a few other tasks closely related to the OS. As a rule, this system call is not to be used by ordinary applications or middleware, for the following reason.
Forced termination occurs regardless of the running state of the target task. If, for example, a task were forcibly terminated while the task was calling a middleware function, the task would terminate right while the middleware was executing. If such a situation were allowed, normal operation of the middleware could not be guaranteed.
This is an example of how task termination should not be allowed when the task status (what it is executing) is unknown. Ordinary applications therefore must not use the forcible termination function.
Changes the base priority of the task specified in tskid to the value specified in tskpri. The current priority of the task also changes as a result.
Task priority values are specified from 1 to 140, with the smaller numbers indicating higher priority.
When TSK_SELF (= 0) is specified in tskid, the invoking task is the target task. Note, however, that when tskid=TSK_SELF is specified in a system call issued from a task-independent portion, error code E_ID is returned. When TPRI_INI (= 0) is specified as tskpri, the target task base priority is changed to the initial priority when the task was started (itskpri).
A priority changed by this system call remains valid until the task is terminated. When the task reverts to DORMANT state, the task priority before its exit is discarded, with the task again assigned to the initial priority when the task was started (itskpri). However, the priority changed in DORMANT state is valid. The next time the task is started, it has the new initial priority.
If as a result of this system call execution the target task current priority matches the base priority (this condition is always met when the mutex function is not used), processing is as follows.
If the target task is in a run state, the task precedence changes according to its priority. The target task has the lowest precedence among tasks of the same priority after the change.
If the target task is in some kind of priority-based queue, the order in that queue changes in accordance with the new task priority. Among tasks of the same priority after the change, the target task is queued at the end.
If the target task has locked a TA_CEILING attribute mutex or is waiting for a lock, and the base priority specified in tskpri is higher than any of the ceiling priorities, error code E_ILUSE is returned.
In some cases when this system call results in a change in the queued order of the target task in a task priority-based queue, it may be necessary to release the wait state of another task waiting in that queue (in a message buffer send queue, or in a queue waiting to acquire a variable-size memory pool).
In some cases when this system call results in a base priority change while the target task is waiting for a mutex lock with TA_INHERIT dynamic priority inheritance processing may be necessary.
When a mutex function is not used and the system call is issued specifying the invoking task as the target task, setting the new priority to the base priority of the invoking task, the order of execution of the invoking task becomes the lowest among tasks of the same priority. This system call can therefore be used to relinquish execution privilege.
Changes the slice time of the task specified in tskid to the value specified in slicetime.
The slice time function is used for round robin scheduling of tasks. When a task runs continuously for the length of time specified in slicetime or longer, its precedence is switched to the lowest among tasks of the same priority, automatically yielding the execution privilege to the next task.
Setting slicetime = 0 indicates unlimited time, and the task does not automatically yield execution privilege. When a task is created, by default it is set to slicetime = 0.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid = TSK_SELF = 0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
The slice time as changed by this system call remains valid until the task is terminated. When the task reverts to DORMANT state, the slice time before termination is discarded, and the value at the time of task creation (slicetime = 0) is assigned. However, the slice time changed in DORMANT state is valid. The next time the task is started, the new slice time is applied.
The time duration while execution privilege is preempted by a higher-priority task does not count in the continuous run time; moreover, even if execution privilege is preempted by a higher-priority task, the run time is not regarded as disrupted. In other words, the time duration while execution privilege is preempted by a higher-priority task is ignored for the purposes of counting run time.
If the specified task is the only one running at its priority, the slice time is effectively meaningless and the task runs continuously.
If a task of slicetime = 0 is included in tasks of the same priority, as soon as that task obtains execution right, round robin scheduling is stopped.
The method of counting run time is implementation-dependent, but does not need to be especially precise. In fact, applications should not expect very high precision.
This system call takes 64-bit slicetime_u in microseconds instead of the parameter slicetime of tk_chg_slt.
The specification of this system call is same as that of tk_chg_slt, except that the parameter is replaced with slicetime_u. For more details, see the description of tk_chg_slt.
This system call was added in T-Kernel 2.0.
pk_tskspc Detail:
Gets the current task space information for the task specified in tskid.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid = TSK_SELF = 0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
The precise meaning of pk_tskspc (uatb, lsid) is implementation-dependent, but the above definitions should be followed as much as possible.
pk_tskspc Detail:
Sets the task space of the task specified in tskid.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid = TSK_SELF = 0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
The kernel is not responsible for handling the side-effects of task space changes. If, for example, a task space is changed while a task is using it for its execution, the task may hang or encounter other problems. The caller is responsible for avoiding such problems.
The accuracy of pk_tskspc (uatb, lsid) is implementation-dependent, but the above definitions should be followed as much as possible.
Returns the resource group to which the task specified in tskid currently belongs.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid = TSK_SELF = 0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
For details of resource group, see the Section called Subsystem Management Functions.
If a resource group is deleted, this system call may return the Resource ID of the deleted resource group. Whether or not an error code (E_OBJ) is returned is implementation-dependent(See tk_cre_res and tk_del_res).
This system call is used by a subsystem. The subsystem recognizes the process by the resource ID. However, the resource ID cannot be specified when the application issues an extended SVC to make the subsystem. For this reason, the subsystem uses this system call to obtain the resource ID.
Changes the current resource group of the task specified in tskid to the resource group specified in resid. The Resource ID of the old resource group before the change is passed in a return parameter.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid = TSK_SELF = 0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
For details of resource group, see the Section called Subsystem Management Functions.
In some cases error is not returned even if resid was previously deleted. Whether or not an error code (E_NOEXS) is returned is implementation-dependent. In principle it is the responsibility of the caller not to specify a deleted resource group.
| ID |
tskid
| Task ID | Task ID |
| T_REGS* |
pk_regs
| Packet of Registers | Pointer to the area to return the general register values |
| T_EIT* |
pk_eit
| Packet of EIT Registers | Pointer to the area to return the values of registers saved when an exception occurs |
| T_CREGS* |
pk_cregs
| Packet of Control Registers | Pointer to the area to return the control register values |
The contents of T_REGS, T_EIT, and T_CREGS are defined for each CPU and implementation.
Gets the current register contents of the task specified in tskid.
If NULL is set in pk_regs, pk_eit, or pk_cregs, the corresponding registers are not referenced.
The referenced register values are not necessarily the values at the time the task portion was executing.
If this system call is issued for the invoking task, error code E_OBJ is returned.
In principle, all registers in the task context can be referenced. This includes not only physical CPU registers but also those treated by the kernel as virtual registers.
| ID |
tskid
| Task ID | Task ID |
| CONST T_REGS* |
pk_regs
| Packet of Registers | General registers |
| CONST T_EIT* |
pk_eit
| Packet of EIT Registers | Registers saved when EIT occurs |
| CONST T_CREGS* |
pk_cregs
| Packet of Control Registers | Control registers |
The contents of T_REGS, T_EIT, and T_CREGS are defined for each CPU and implementation.
| 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_OBJ | Invalid object state (called for the invoking task) |
| E_CTX | Context error (called from task-independent portion) |
| E_PAR | Invalid register value (implementation-dependent) |
Sets the current register contents of the task specified in tskid.
If NULL is set in pk_regs, pk_eit, or pk_cregs, the corresponding registers are not set.
The set register values are not necessarily the values while the task portion is executing. The kernel is not responsible for handling the side-effects of register value changes.
It is possible, however, that some registers or register bits cannot be changed if the kernel does not allow such changes.(Implementation-dependent)
If this system call is issued for the invoking task, error code E_OBJ is returned.
pk_copregs Detail:
| T_COP0REG |
cop0
| Coprocessor Number 0 Register | Coprocessor number 0 register |
| T_COP1REG |
cop1
| Coprocessor Number 1 Register | Coprocessor number 1 register |
| T_COP2REG |
cop2
| Coprocessor Number 2 Register | Coprocessor number 2 register |
| T_COP3REG |
cop3
| Coprocessor Number 3 Register | Coprocessor number 3 register |
The contents of T_COPnREG are defined for each CPU and implementation.
| 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_OBJ | Invalid object state (called for the invoking task) |
| E_CTX | Context error (called from task-independent portion) |
| E_PAR | Parameter error (copno is invalid or the specified coprocessor does not exist) |
Gets the current contents of the register specified in copno of the task specified in tskid.
The referenced register values are not necessarily the values at the time the task portion was executing.
If this system call is issued for the invoking task, error code E_OBJ is returned.
In principle, all registers in the task context can be referenced. This includes not only physical CPU registers but also those treated by the kernel as virtual registers.
| ID |
tskid
| Task ID | Task ID |
| INT |
copno
| Coprocessor Number | Coprocessor number (0 to 3) |
| CONST T_COPREGS* |
pk_copregs
| Packet of Coprocessor Registers | Coprocessor register |
pk_copregs Detail:
| 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_OBJ | Invalid object state (called for the invoking task) |
| E_CTX | Context error (called from task-independent portion) |
| E_PAR | Parameter error (copno is invalid or the specified coprocessor does not exist), or the set register value is invalid (implementation-dependent) |
Sets the contents of the register specified in copno of the task specified in tskid.
The set register values are not necessarily the values while the task portion is executing. The kernel is not responsible for handling the side-effects of register value changes.
It is possible, however, that some registers or register bits cannot be changed if the kernel does not allow such changes.(Implementation-dependent)
If this system call is issued for the invoking task, error code E_OBJ is returned.
pk_itsk Detail:
Gets statistical information for the task specified in tskid.
If clr=TRUE≠0, the cumulative information is reset (cleared to 0) after getting the information.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid = TSK_SELF = 0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
stime and utime in the task statistics (T_ITSK) return values rounded to milliseconds. To know the value in microseconds, call tk_inf_tsk_u.
The system-level run time is accumulated while the task runs at TA_RNG0, and the user-level run time is accumulated while the task runs at protection levels other than TA_RNG0. The execution time of a task created to run at TA_RNG0 is therefore counted entirely as system-level run time.
The method of counting run time is implementation-dependent, but does not need to be especially precise. In fact, applications should not expect very high precision.
pk_itsk_u Detail:
This system call takes 64-bit stime_u and utime_u in microseconds instead of the return parameters stime and utime of tk_inf_tsk.
The specification of this system call is same as that of tk_inf_tsk, except that the return parameters are replaced with stime_u and utime_u. For more details, see the description of tk_inf_tsk.
This system call was added in T-Kernel 2.0.
pk_rtsk Detail:
| void* |
exinf
| Extended Information | Extended information |
| PRI |
tskpri
| Task Priority | Current priority |
| PRI |
tskbpri
| Task Base Priority | Base priority |
| UINT |
tskstat
| Task State | Task State |
| UINT |
tskwait
| Task Wait Factor | Wait factor |
| ID |
wid
| Waiting Object ID | Waiting object ID |
| INT |
wupcnt
| Wakeup Count | Wakeup request queuing count |
| INT |
suscnt
| Suspend Count | Suspend request nesting count |
| RELTIM |
slicetime
| Slice Time | Maximum continuous run time (in ms) |
| UINT |
waitmask
| Wait Mask | Disabled wait factors |
| UINT |
texmask
| Task Exception Mask | Allowed task exceptions |
| UINT |
tskevent
| Task Event | Raised task event |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
Gets the state of the task specified in tskid.
tskstat takes the following values.
| TTS_RUN | 0x0001 | RUNNING state |
| TTS_RDY | 0x0002 | READY state |
| TTS_WAI | 0x0004 | WAITING state |
| TTS_SUS | 0x0008 | SUSPENDED state |
| TTS_WAS | 0x000c | WAITING-SUSPENDED state |
| TTS_DMT | 0x0010 | DORMANT state |
| TTS_NODISWAI | 0x0080 | Disabling of wait by tk_dis_wai is prohibited |
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 RUNNING 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, TTS_DMT).
In the case of TTS_WAI (including TTS_WAS), disabling of wait by the tk_dis_wai is prohibited, 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, RUNNING (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 2.
Table 2.
Values of tskwait and wid
tskwait
| Value | Description |
wid
|
|---|---|---|---|
| TTW_SLP | 0x00000001 | Wait caused by tk_slp_tsk | 0 |
| TTW_DLY | 0x00000002 | Wait caused by tk_dly_tsk | 0 |
| TTW_SEM | 0x00000004 | Wait caused by tk_wai_sem | semid
|
| TTW_FLG | 0x00000008 | Wait caused by tk_wai_flg | flgid
|
| TTW_MBX | 0x00000040 | Wait caused by tk_rcv_mbx | mbxid
|
| TTW_MTX | 0x00000080 | Wait caused by tk_loc_mtx | mtxid
|
| TTW_SMBF | 0x00000100 | Wait caused by tk_snd_mbf | mbfid
|
| TTW_RMBF | 0x00000200 | Wait caused by tk_rcv_mbf | mbfid
|
| TTW_CAL | 0x00000400 | Wait on rendezvous call | porid
|
| TTW_ACP | 0x00000800 | Wait for rendezvous acceptance | porid
|
| TTW_RDV | 0x00001000 | Wait for rendezvous completion | 0 |
| (TTW_CAL | TTW_RDV) | 0x00001400 | Wait on rendezvous call or wait for rendezvous completion | 0 |
| TTW_MPF | 0x00002000 | Wait caused by tk_get_mpf | mpfid
|
| TTW_MPL | 0x00004000 | Wait caused by tk_get_mpl | mplid
|
| TTW_EV1 | 0x00010000 | Wait for task event #1 | 0 |
| TTW_EV2 | 0x00020000 | Wait for task event #2 | 0 |
| TTW_EV3 | 0x00040000 | Wait for task event #3 | 0 |
| TTW_EV4 | 0x00080000 | Wait for task event #4 | 0 |
| TTW_EV5 | 0x00100000 | Wait for task event #5 | 0 |
| TTW_EV6 | 0x00200000 | Wait for task event #6 | 0 |
| TTW_EV7 | 0x00400000 | Wait for task event #7 | 0 |
| TTW_EV8 | 0x00800000 | Wait for task event #8 | 0 |
When tskstat is not TTS_WAI (including TTS_WAS), both tskwait and wid are 0.
waitmask is the same bit array as tskwait.
For a task in DORMANT state, wupcnt = 0, suscnt = 0, and tskevent = 0.
The invoking task can be specified by setting tskid = TSK_SELF = 0. Note, however, that when tskid=TSK_SELF=0 is specified in a system call issued from a task-independent portion, error code E_ID is returned.
When the task specified with tk_ref_tsk does not exist, error code E_NOEXS is returned.
slicetime in the task status information (T_RTSK) returns a value rounded to milliseconds. To know the value in microseconds, call tk_ref_tsk_u.
Even when tskid = TSK_SELF is specified with 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.
pk_rtsk_u Detail:
| void* |
exinf
| Extended Information | Extended information |
| PRI |
tskpri
| Task Priority | Current priority |
| PRI |
tskbpri
| Task Base Priority | Base priority |
| UINT |
tskstat
| Task State | Task State |
| UINT |
tskwait
| Task Wait Factor | Wait factor |
| ID |
wid
| Waiting Object ID | Waiting object ID |
| INT |
wupcnt
| Wakeup Count | Wakeup request queuing count |
| INT |
suscnt
| Suspend Count | Suspend request nesting count |
| RELTIM_U |
slicetime_u
| Slice Time | Maximum continuous run time (in microseconds) |
| UINT |
waitmask
| Wait Mask | Disabled wait factors |
| UINT |
texmask
| Task Exception Mask | Allowed task exceptions |
| UINT |
tskevent
| Task Event | Raised task event |
| (Other implementation-dependent parameters may be added beyond this point.) | |||
This system call takes 64-bit slicetime_u in microseconds instead of the return parameter slicetime of tk_ref_tsk.
The specification of this system call is same as that of tk_ref_tsk, except that the return parameter is replaced with slicetime_u. For more details, see the description of tk_ref_tsk.
This system call was added in T-Kernel 2.0.