T-Kernel/DS Functions
This chapter describes details of the functions provided by T-Kernel Debugger Support (T-Kernel/DS).
T-Kernel/DS provides functions enabling a debugger to reference T-Kernel internal states and run a trace. The functions provided by T-Kernel/DS are only for debugger use and not for use by applications or other programs.
 | Overall Note and Supplement |
|---|---|
|
Kernel Internal State Acquisition Functions
Kernel internal state reference functions are functions for enabling a debugger to get T-Kernel internal states. They include functions for getting a list of objects, getting task precedence, getting the order in which tasks are queued, getting the status of objects, system, and task registers, and getting time.
td_lst_tsk - Reference Task ID List
Error Code
None
Description
Gets the list of the IDs of the currently used tasks, and puts in list up to nent IDs. The number of the used tasks is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_lst_sem - Reference Semaphore ID List
Error Code
None
Description
Gets the list of the IDs of the currently used semaphores, and puts in list up to nent IDs. The number of the used semaphores is passed in the return code. If return code > nent, this means not all semaphore IDs could be retrieved.
td_lst_flg - Reference Event Flag ID List
Error Code
None
Description
Gets the list of the IDs of the currently used event flags, and puts in list up to nent IDs. The number of the used event flags is passed in the return code. If return code > nent, this means not all event flag IDs could be retrieved.
td_lst_mbx - Reference Mailbox ID List
Error Code
None
Description
Gets the list of the IDs of the currently used mailboxes, and puts in list up to nent IDs. The number of the used mailboxes is passed in the return code. If return code > nent, this means not all mailbox IDs could be retrieved.
td_lst_mtx - Reference Mutex ID List
Error Code
None
Description
Gets the list of the IDs of the currently used mutexes, and puts in list up to nent IDs. The number of the used mutexes is passed in the return code. If return code > nent, this means not all mutex IDs could be retrieved.
td_lst_mbf - Reference Message Buffer ID List
Error Code
None
Description
Gets the list of the IDs of the currently used message buffers, and puts in list up to nent IDs. The number of the used message buffers is passed in the return code. If return code > nent, this means not all message buffer IDs could be retrieved.
td_lst_por - Reference Rendezvous Port ID List
Error Code
None
Description
Gets the list of the IDs of the currently used rendezvous ports, and puts in list up to nent IDs. The number of the used rendezvous ports is passed in the return code. If return code > nent, this means not all rendezvous port IDs could be retrieved.
td_lst_mpf - Reference Fixed-size Memory Pool ID List
Error Code
None
Description
Gets the list of the IDs of the currently used fixed-size memory pools, and puts in list up to nent IDs. The number of the used fixed-size memory pools is passed in the return code. If return code > nent, this means not all fixed-size memory pool IDs could be retrieved.
td_lst_mpl - Reference Variable-size Memory Pool ID List
Error Code
None
Description
Gets the list of the IDs of the currently used variable-size memory pools, and puts in list up to nent IDs. The number of the used variable-size memory pools is passed in the return code. If return code > nent, this means not all variable-size memory pool IDs could be retrieved.
td_lst_cyc - Reference Cyclic Handler ID List
Error Code
None
Description
Gets the list of the IDs of the currently used cyclic handlers, and puts in list up to nent IDs. The number of the used cyclic handlers is passed in the return code. If return code > nent, this means not all cyclic handler IDs could be retrieved.
td_lst_alm - Reference Alarm Handler ID List
Error Code
None
Description
Gets the list of the IDs of the currently used alarm handlers, and puts in list up to nent IDs. The number of the used alarm handlers is passed in the return code. If return code > nent, this means not all alarm handler IDs could be retrieved.
td_lst_ssy - Reference Subsystem ID List
Error Code
None
Description
Gets the list of the IDs of the currently used subsystems, and puts in list up to nent IDs. The number of the used subsystems is passed in the return code. If return code > nent, this means not all subsystem IDs could be retrieved.
td_rdy_que - Reference Task Precedence
Description
Gets a list of IDs of the tasks in a run state (READY state or RUNNING state) whose task priority is pri, arranged in the order from the highest to the lowest precedence.
This function stores in list up to nent task IDs, arranged in the order of precedence starting from the highest-precedence task ID at the head of the list.
The number of tasks in a run state with priority pri is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_sem_que - Reference Semaphore Queue
Description
Gets the list of the IDs of the queued tasks waiting for a semaphore specified in semid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the semaphore queue. The number of the tasks in the semaphore queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_flg_que - Reference Event Flag Queue
Description
Gets the list of the IDs of the queued tasks waiting for an event flag specified in flgid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the event flag queue. The number of the tasks in the event flag queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_mbx_que - Reference Mailbox Queue
Description
Gets the list of the IDs of the queued tasks waiting for a mailbox specified in mbxid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the mailbox queue. The number of the tasks in the mailbox queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_mtx_que - Reference Mutex Queue
Description
Gets the list of the IDs of the queued tasks waiting for a mutex specified in mtxid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the mutex queue. The number of the tasks in the mutex queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_smbf_que - Reference Message Buffer Send Queue
Description
Gets the list of the IDs of the queued tasks waiting for sending a message to a message buffer specified in mbfid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the message buffer send queue. The number of the tasks in the message buffer send queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_rmbf_que - Reference Message Buffer Receive Queue
Description
Gets the list of the IDs of the queued tasks waiting for receiving a message from a message buffer specified in mbfid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the message buffer receive queue. The number of the tasks in the message buffer receive queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_cal_que - Reference Call Queue
Description
Gets the list of the IDs of the queued tasks waiting for rendezvous call at a port specified in porid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the rendezvous call queue. The number of the tasks in the rendezvous call queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_acp_que - Reference Accept Queue
Description
Gets the list of the IDs of the queued tasks waiting for rendezvous acceptance at a port specified in porid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the rendezvous acceptance queue. The number of the tasks in the rendezvous acceptance queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_mpf_que - Reference Fixed-size Memory Pool Queue
Description
Gets the list of the IDs of the queued tasks waiting for allocation in a fixed-size memory pool specified in mpfid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the fixed-size memory pool queue. The number of the tasks in the fixed-size memory pool queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_mpl_que - Reference Variable-size Memory Pool Queue
Description
Gets the list of the IDs of the queued tasks waiting for allocation in a variable-size memory pool specified in mplid. This function stores in list up to nent task IDs, arranged in the order in which tasks are queued, starting from the first task in the variable-size memory pool queue. The number of the tasks in the variable-size memory pool queue is passed in the return code. If return code > nent, this means not all task IDs could be retrieved.
td_ref_tsk - Reference Task Status
Return Parameter
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 States |
| 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 |
| FP |
task
| Task Start Address | Task start address |
| INT |
stksz
| User Stack Size | User stack size (in bytes) |
| INT |
sstksz
| System Stack Size | System stack size (in bytes) |
| void* |
istack
| Initial User Stack Pointer | User stack pointer initial value |
| void* |
isstack
| Initial System Stack Pointer | System stack pointer initial value |
Description
Gets the state of the task designated in tskid. This function is similar to tk_ref_tsk(), with the task start address and stack information added to the state information obtained.
The stack area extends from the stack pointer initial value toward the low addresses for the number of bytes designated as the stack size.
istack-stksz≦ user stack area <istackisstack-sstksz≦ system stack area <isstack
Note that the stack pointer initial value (istack, isstack) is not the same as its current position. The stack area may be used even before a task is started. Calling td_get_reg() gets the stack pointer current position.
slicetime in the task status information (TD_RTSK) returns a value rounded to milliseconds. To know the value in microseconds, call td_ref_tsk_u.
td_ref_tsk_u - Reference Task Status (Microseconds)
Return Parameter
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 States |
| 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 |
| FP |
task
| Task Start Address | Task start address |
| INT |
stksz
| User Stack Size | User stack size (in bytes) |
| INT |
sstksz
| System Stack Size | System stack size (in bytes) |
| void* |
istack
| Initial User Stack Pointer | User stack pointer initial value |
| void* |
isstack
| Initial System Stack Pointer | System stack pointer initial value |
Description
This system call takes slicetime_u in 64-bit microseconds instead of the return parameter slicetime of td_ref_tsk.
The specification of this system call is same as that of td_ref_tsk, except that a field in the return parameter is replaced with slicetime_u. For more details, see the description of td_ref_tsk.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
td_ref_tex - Reference Task Exception Status
Return Parameter
pk_rtex Detail:
Description
Gets the task exception status. This is similar to tk_ref_tex().
td_ref_sem - Reference Semaphore Status
Return Parameter
rsem Detail:
Description
References the semaphore status. This is similar to tk_ref_sem().
td_ref_flg - Reference Event Flag Status
Return Parameter
rflg Detail:
Description
References the event flag status. This is similar to tk_ref_flg().
td_ref_mbx - Reference Mailbox Status
Return Parameter
rmbx Detail:
Description
References the mailbox status. This is similar to tk_ref_mbx().
td_ref_mtx - Refer Mutex Status
Return Parameter
rmtx Detail:
Description
References the mutex status. This is similar to tk_ref_mtx().
td_ref_mbf - Reference Message Buffer Status
Return Parameter
rmbf Detail:
| void* |
exinf
| Extended Information | Extended information |
| ID |
wtsk
| Wait Task Information | Receive wait task ID |
| ID |
stsk
| Send Task Information | Send wait task ID |
| INT |
msgsz
| Message Size | Size of the next message to be received (in bytes) |
| INT |
frbufsz
| Free Buffer Size | Free buffer size (in bytes) |
| INT |
maxmsz
| Maximum Message Size | Maximum message size (in bytes) |
Description
References the message buffer status. This is similar to tk_ref_mbf().
td_ref_por - Reference Port Status
Return Parameter
rpor Detail:
| void* |
exinf
| Extended Information | Extended information |
| ID |
wtsk
| Wait Task Information | Call waiting task ID |
| ID |
atsk
| Accept Task Information | Accept waiting task ID |
| INT |
maxcmsz
| Maximum Call Message Size | Maximum call message size (in bytes) |
| INT |
maxrmsz
| Maximum Reply Message Size | Maximum reply message size (in bytes) |
Description
References the rendezvous port status. This is similar to tk_ref_por().
td_ref_mpf - Reference Fixed-size Memory Pool Status
Return Parameter
rmpf Detail:
Description
References the fixed-size memory pool status. This is similar to tk_ref_mpf().
td_ref_mpl - Reference Variable-size Memory Pool Status
Return Parameter
rmpl Detail:
Description
References the variable-size memory pool status. This is similar to tk_ref_mpl().
td_ref_cyc - Reference Cyclic Handler Status
Return Parameter
rcyc Detail:
Description
References the cyclic handler status. This is similar to tk_ref_cyc().
The time remaining lfttim returned in the cyclic handler status information (TD_RCYC) obtained by td_ref_cyc is a value rounded to milliseconds. To know the value in microseconds, call td_ref_cyc_u.
td_ref_cyc_u - Reference Cyclic Handler Status (Microseconds)
Return Parameter
rcyc_u Detail:
Description
This system call takes 64-bit lfttim_u in microseconds instead of the return parameter lfttim of td_ref_cyc.
The specification of this system call is same as that of td_ref_cyc, except that the return parameter is replaced with lfttim_u. For more details, see the description of td_ref_cyc.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
td_ref_alm - Reference Alarm Handler Status
Return Parameter
ralm Detail:
Description
References the alarm handler status. This is similar to tk_ref_alm().
The time remaining lfttim returned in the alarm handler status information (TD_RALM) obtained by td_ref_alm is a value rounded to milliseconds. To know the value in microseconds, call td_ref_alm_u.
td_ref_alm_u - Reference Alarm Handler Status (Microseconds)
Return Parameter
ralm_u Detail:
Description
This system call takes 64-bit lfttim_u in microseconds instead of the return parameter lfttim of td_ref_alm.
The specification of this system call is same as that of td_ref_alm, except that the return parameter is replaced with lfttim_u. For more details, see the description of td_ref_alm.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
td_ref_sys - Reference System Status
Return Parameter
pk_rsys Detail:
Description
Gets the system status. This is similar to tk_ref_sys().
td_ref_ssy - Reference Subsystem Status
Return Parameter
rssy Detail:
Description
References the subsystem status. This is similar to tk_ref_ssy().
td_inf_tsk - Reference Task Statistics
Return Parameter
pk_itsk Detail:
Description
Gets task statistics. This is similar to tk_inf_tsk(). If clr = TRUE (≠ 0), the cumulative information is reset (cleared to 0) after the information is obtained.
stime and utime in the task statistics (TD_ITSK) return values rounded to milliseconds. To know the value in microseconds, call td_inf_tsk_u.
td_inf_tsk_u - Reference Task Statistics (Microseconds)
Return Parameter
itsk_u Detail:
Description
This system call takes 64-bit stime_u and utime_u in microseconds instead of the return parameters stime and utime of td_inf_tsk.
The specification of this system call is same as that of td_inf_tsk, except that the return parameters are replaced with stime_u and utime_u. For more details, see the description of td_inf_tsk.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
td_get_reg - Get Task Register
Parameter
| ID |
tskid
| Task ID | Target task ID (TSK_SELF cannot be specified) |
| 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 |
Return Parameter
The contents of T_REGS, T_EIT, and T_CREGS are defined for each CPU and implementation.
Description
Gets the register values of the task designated in tskid. This is similar to tk_get_reg.
Registers cannot be referenced for the task currently in RUNNING state. Except when a task-independent portion is executing, the current RUNNING state task is the invoking task.
If NULL is set in pk_regs, pk_eit, or pk_cregs, the corresponding registers are not referenced.
The contents of T_REGS, T_EIT, and T_CREGS are implementation-dependent.
td_set_reg - Set Task Registers
Parameter
| ID |
tskid
| Task ID | Target task ID (TSK_SELF cannot be specified) |
| 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.
Description
Sets registers of the task designated in tskid. This is similar to tk_set_reg.
Registers cannot be set for the task currently in RUNNING state. Except when a task-independent portion is executing, the current RUNNING state task is the invoking task.
If NULL is set in pk_regs, pk_eit, or pk_cregs, the corresponding registers are not set.
The contents of T_REGS, T_EIT, and T_CREGS are implementation-dependent.
td_get_tim - Get System Time
Return Parameter
| ER |
ercd
| Error Code | Error code |
| SYSTIM |
tim
| Time | Current time (in milliseconds) |
| UINT |
ofs
| Offset |
Elapsed time from tim (nanoseconds) |
tim Detail:
Description
Gets the current time as total elapsed milliseconds since 0:00:00 (GMT), January 1, 1985. The value returned in tim is the same as that obtained by tk_get_tim(). tim is the resolution of timer interrupt intervals (cycles), but even more precise time information is obtained in ofs as the elapsed time from tim in nanoseconds. The resolution of ofs is implementation-dependent, but generally is the resolution of hardware timer.
Since tim is a cumulative time counted based on timer interrupts, in some cases time is not refreshed, when a timer interrupt cycle arrives while interrupts are disabled and the timer interrupt handler is not started (is delayed). In such cases, the time as updated by the previous timer interrupt is returned in tim, and the elapsed time from the previous timer interrupt is returned in ofs. Accordingly, in some cases ofs will be longer than the timer interrupt cycle. The length of elapsed time that can be measured by ofs depends on the hardware, but preferably it should be possible to measure at least up to twice the timer interrupt cycle (0 ≦ ofs < twice the timer interrupt cycle).
Note that the time returned in tim and ofs is the time at some point between the calling of and return from td_get_tim(). It is neither the time at which td_get_tim() was called nor the time of return from td_get_tim(). In order to obtain more accurate information, this function should be called in interrupts disabled state.
td_get_tim_u - Get System Time (Microseconds)
Description
This system call takes 64-bit tim_u in microseconds instead of the return parameter tim of td_get_tim.
The specification of this system call is same as that of td_get_tim, except that the return parameter is replaced with tim_u. For more details, see the description of td_get_tim.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
td_get_otm - Get Operating Time
Return Parameter
| ER |
ercd
| Error Code | Error code |
| SYSTIM |
tim
| Time | Operating time (ms) |
| UINT |
ofs
| Offset |
Elapsed time from tim (nanoseconds) |
tim Detail:
Description
Gets the system operating time (uptime, as elapsed milliseconds since the system was booted). The value returned in tim is the same as that obtained by tk_get_otm. tim is the resolution of timer interrupt intervals (cycles), but even more precise time information is obtained in ofs as the elapsed time from tim in nanoseconds. The resolution of ofs is implementation-dependent, but generally is the resolution of hardware timer.
Since tim is a cumulative time counted based on timer interrupts, in some cases time is not refreshed, when a timer interrupt cycle arrives while interrupts are disabled and the timer interrupt handler is not started (is delayed). In such cases, the time as updated by the previous timer interrupt is returned in tim, and the elapsed time from the previous timer interrupt is returned in ofs. Accordingly, in some cases ofs will be longer than the timer interrupt cycle. The length of elapsed time that can be measured by ofs depends on the hardware, but preferably it should be possible to measure at least up to twice the timer interrupt cycle (0 ≦ ofs < twice the timer interrupt cycle).
Note that the time returned in tim and ofs is the time at some point between the calling of and return from td_get_otm(). It is neither the time at which td_get_otm() was called nor the time of return from td_get_otm(). In order to obtain more accurate information, this function should be called in interrupts disabled state.
td_get_otm_u - Get Operating Time (Microseconds)
Description
This system call takes 64-bit tim_u in microseconds instead of the return parameter tim of td_get_otm.
The specification of this system call is same as that of td_get_otm, except that the return parameter is replaced with tim_u. For more details, see the description of td_get_otm.
Difference from T-Kernel 1.0
This system call was added in T-Kernel 2.0.
td_ref_dsname - Refer to DS Object Name
Return Parameter
dsnameDetail:DS object name, set at object creation or by td_set_dsname()
Description
References the DS object name (dsname), which is set at object creation. The object is specified by object type (type) and object ID (id).
Object types (type) are as follows:
| TN_TSK | 0x01 | Task |
| TN_SEM | 0x02 | Semaphore |
| TN_FLG | 0x03 | Event Flag |
| TN_MBX | 0x04 | Mailbox |
| TN_MBF | 0x05 | Message Buffer |
| TN_POR | 0x06 | Rendezvous Port |
| TN_MTX | 0x07 | Mutex |
| TN_MPL | 0x08 | Variable-size Memory Pool |
| TN_MPF | 0x09 | Fixed-size Memory Pool |
| TN_CYC | 0x0a | Cyclic Handler |
| TN_ALM | 0x0b | Alarm Handler |
DS object name is valid if TA_DSNAME is set as object attribute. If DS object name is changed by td_set_dsname(), then td_ref_dsname() references the new name.
DS object name needs to satisfy the following conditions:
- Available characters (UB)
a to z, A to Z, 0 to 9
- Name length
8-byte (filled with NULL for shorter name)
However, character code range is not checked by T-Kernel.
td_set_dsname - Set DS Object Name
Description
Re-sets DS object name (dsname), which is set at object creation. The object is specified by object type (type) and object ID (id).
Object types (type) are as same as that of td_ref_dsname() .
DS object name needs to satisfy the following conditions:
- Available characters (UB)
a to z, A to Z, 0 to 9
- Name length
8-byte (filled with NULL for shorter name)
However, character code range is not checked by T-Kernel.
DS object name is valid if TA_DSNAME is set as object attribute. td_set_dsname() returns E_OBJ error if TA_DSNAME attribute is not specified.