μT-Kernel 2.0 Specification
Prev	μT-Kernel/DS Functions	Next

Trace Functions

Trace functions are functions for enabling a debugger to trace program execution. Execution trace is performed by setting hook routines.

Return from a hook routine must be made after states have returned to where they were when the hook routine was called. Restoring of registers, however, can be done in accordance with the C language function saving rules.
In a hook routine, limitations on states must not be loosened to make them less restrictive than when the routine was called. For example, if the hook routine was called during interrupts disabled state, interrupts must not be enabled.
A hook routine was called at protection level 0.
A hook routine inherits the stack at the time of the hook. Using too much stack may therefore cause a stack overflow. The extent to which the stack can be used is not definite, since it differs with the situation at the time of the hook. Switching to a separate stack in the hook routine is a safer option.

td_hok_svc - Define System Call/Extended SVC Hook Routine

C Language Interface

#include <tk/dbgspt.h>

ER ercd = td_hok_svc (CONST TD_HSVC *hsvc );

Parameter

CONST TD_HSVC* hsvc SVC Hook Routine Hook routine definition information

hsvc Detail:

FP	`enter`	Hook Routine before Calling	Hook routine before calling
FP	`leave`	Hook Routine after Calling	Hook routine after calling

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_DBGSPT Support μT-Kernel/DS

Description

Sets hook routines before and after the issuing of a system call or extended SVC. Setting NULL in hsvc cancels a hook routine.

The target of trace functions are the system calls of μT-Kernel/OS (tk_〜) and extended SVCs. Note, however, generally speaking tk_ret_int is not the target of trace function. This is implementation-dependent.

System calls of μT-Kernel/DS (td_〜) are not the target of trace functions.

A hook routine runs as a quasi-task portion of the task that called a system call or extended SVC for which a hook routine is set. Therefore, for example, the invoking task in a hook routine is the same as the task that invoked the system call or extended SVC.

Since task dispatching and interrupts can occur inside system call processing, enter() and leave() are not necessarily called in succession as a pair in every case. If a system call is one that does not return, leave() will not be called.

void *enter (FN fncd , TD_CALINF *calinf , ... );

fncd

Function Codes

< 0 System call

≧ 0 Extended SVC

TD_CALINF* calinf Caller information

... Parameters (variable number)

Return Any value passed to leave()

typedef struct td_calinf {
      Information to determine the caller for the system call or extended SVC;
      it is preferable to include the information for the stack back-trace.
      The contents are implementation-dependent,
      but generally consist of register values such as stack pointer and program counter.
} TD_CALINF;

enter is called right before a system call or extended SVC.

The value passed in the return code is passed transparently to the corresponding leave(). This makes it possible to pair enter() and leave() calls or to pass any other information.

exinf = enter(fncd, &calinf, ... )
ret = system call or extended SVC execution
leave(fncd , ret, exinf)

For system call
The parameters are the same as the system call parameters.
Example 1. tk_wai_sem(ID semid, INT cnt, TMO tmout)
```
enter(TFN_WAI_SEM, &calinf, semid, cnt, tmout)
```

For extended SVC

The parameters are as in the packet passed to the extended SVC handler.

fncd is likewise the same as that passed to the extended SVC handler.

enter (FN fncd , TD_CALINF *calinf , void *pk_para );

void leave (FN fncd , INT ret , void *exinf );

FN	`fncd`	Function Codes
INT	`ret`	Return code of the system call or extended SVC
void*	`exinf`	Any value returned by `enter()`

enter is called right after returning from a system call or extended SVC.

When a hook routine is set after a system call or extended SVC is called (while the system call or extended SVC is executing), in some cases leave() only may be called without calling enter() . In such a case NULL is passed in exinf.

If, on the other hand, a hook routine is canceled after a system call or extended SVC is called, there may be cases when enter() is called but not leave().

Difference from μT-Kernel 1.0

With the introduction of service profile, this API can be used when the profile permits it.

td_hok_dsp - Define Task Dispatch Hook Routine

C Language Interface

#include <tk/dbgspt.h>

ER ercd = td_hok_dsp (CONST TD_HDSP *hdsp );

Parameter

CONST TD_HDSP* hdsp Dispatcher Hook Routine Hook routine definition information

hdsp Detail:

FP	`exec`	Hook Routine when Execution Starts	Hook routine when execution starts
FP	`stop`	Hook Routine when Execution Stops	Hook routine when execution stops

Return Parameter

ER ercd Error Code Error code

Error Code

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

TK_SUPPORT_TASKSPACE It is possible to acquire (lsid) information of task space

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_DBGSPT Support μT-Kernel/DS

Description

Sets hook routines in the task dispatcher. Setting NULL in hdsp cancels a hook routine.

A hook routine is called while dispatching is disabled. A hook routine shall not invoke system calls of μT-Kernel/OS (tk_〜) and extended SVCs. A hook routine can invoke system calls of μT-Kernel/DS (td_〜).

void exec (ID tskid , INT lsid );

ID	`tskid`		Task ID of the started or resumed task
INT	`lsid`		Logical space ID of the task designated in `tskid`

exec() is called when the designated task starts execution or resumes. At the time exec() is called, the task designated in tskid is already in RUNNING state and logical space has been switched. However, execution of the tskid task program code occurs after the return from exec().

void stop (ID tskid , INT lsid , UINT tskstat );

ID	`tskid`	Task ID of the executed or stopped task
INT	`lsid`	Logical space ID of the task designated in `tskid`
UINT	`tskstat`	State of the task designated in `tskid`

stop() is called when the designated task executes or stops. tskstat indicates the task state after stopping, as one of the following states:

`TTS_RDY`	READY state
`TTS_WAI`	WAITING state
`TTS_SUS`	SUSPENDED state
`TTS_WAS`	WAITING-SUSPENDED state
`TTS_DMT`	DORMANT state
0	NON-EXISTENT state

At the time stop() is called, the task designated in tskid has already entered the state indicated in tskstat. The logical space is indeterminate.

If service profile item, TK_SUPPORT_TASKSPACE is set to be ineffective, the value of lsid passed to each routine is indeterminate.

Difference from μT-Kernel 1.0

With the introduction of service profile, this API can be used when the profile permits it.

td_hok_int - Define Interrupt Handler Hook Routine

C Language Interface

#include <tk/dbgspt.h>

ER ercd = td_hok_int (CONST TD_HINT *hint );

Parameter

CONST TD_HINT* hint Interrupt Handler Hook Routine Hook routine definition information

hint Detail:

FP	`enter`	Hook Routine before Calling Handler	Hook routine before calling handler
FP	`leave`	Hook Routine after Calling Handler	Hook routine after calling handler

Return Parameter

ER ercd Error Code Error code

Error Code

None.

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	YES

Related Service Profile Items

Only when all the service profile items below are set to be effective, this system call can be used.

TK_SUPPORT_DBGSPT Support μT-Kernel/DS

Description

Sets hook routines before and after an interrupt handler is called. Hook routine setting cannot be done individually for different exception or interrupt factors. One pair of hook routines is set in common for all exception and interrupt factors.

Setting hint to NULL cancels the hook routines.

The hook routines are called as task-independent portion (part of the interrupt handler). Accordingly, the hook routines can call only those system calls that can be invoked from a task-independent portion.

Note that hook routines can be set only for interrupt handlers defined by tk_def_int with the TA_HLNG attribute. A TA_ASM attribute interrupt handler cannot be hooked by a hook routine. Hooking of a TA_ASM attribute interrupt handler is possible only by directly manipulating the exception/interrupt vector table. The actual methods are implementation-dependent.

void *enter (UINT intno );

void *leave (UINT intno );

UINT intno Interrupt number

Parameters passed to enter() and leave() are the same as those of exception handler and interrupt handler. Depending on the implementation, other information about the interrupt may be passed in addition to intno.

A hook routine is called as follows from a high-level language support routine.

enter(intno);
inthdr(intno); /* Interrupt or exception handler */
leave(intno);

enter() is called in interrupts disabled state, and interrupts must not be enabled. Since leave() assumes the status on return from inthdr(), the interrupts disabled or enabled status is indeterminate.

enter() can obtain the same amount of information which the function inthdr() can obtain. If the function inthdr() cannot obtain a piece of information, that information cannot be acquired by enter(). either. The specification guarantees that enter() and inthdr() can access information by means of intno, but whether other information can be acquired is implementation dependent. Note that during the execution of the function leave(), the states such as interrupt mask status may have changed, it may be impossible to obtain the same amount of information obtained by enter() or inthdr().

Difference from μT-Kernel 1.0

With the introduction of service profile, this API can be used when the profile permits it.