NAME

trace – kernel tracing device.

SYNOPSIS

bind #T /dev /dev/trace /dev/tracectl

DESCRIPTION

The trace device provides a method for kernel tracing. Sections of memory (“traces”) are selected; trace events will be recorded whenever the program counter enters or leaves a function within those sections of memory. This is useful in examining how many times a function is called, with what arguments, and how much time is spent in that function.
The timestamps recorded are taken from the function, which is architecture–dependent. In the x86, for example, the timestamp will be the value of the tsc register.
The tracectl file provides information on the current configuration and allows changes to be made. The following are valid commands to be echoed into /dev/tracectl; note that all addresses can be given as offsets from KTZERO, although giving a full address will work too:
all           enables tracing for all events. During normal operation, function calls from interrupt context will be ignored; issuing an 'all' command will cause them to be recorded. The 'stop' command resets the system to default operation.
size size
resizes the trace log to 2size elements.
start         turns on tracing. Any traces that are on will now begin registering events to /dev/trace
stop          turns off tracing.
trace startaddr endaddr new name
creates a new trace between addresses startaddr and endaddr.
trace name remove
removes the specified trace
trace name on   enables the specified trace. No "hits" will be generated until the start command is given.
trace name offdisables the specified trace. No "hits" will ever occur.
watch pid
only records events from the given PID. Repeated watch commands will add to the list of PIDs. If a PID of 0 is given, the system will revert to recording all events.
Trace events are recorded in /dev/trace as 121–byte lines (including the newline). The format of an event is:
eventtype PC timestamp caller–PID arg1 arg2 arg3 arg4
The eventtype is E for an entry and X for an exit. The PC is the current program counter. The timestamp is the system cycles clock. The PID is the PID for the process originating the function call. Arguments 1 through 4 are the first four arguments of the function for a function entry; for an exit event, arg1 is the return value. If there are only two arguments to a function, for example, only arg1 and arg2 will have values, while the others will be zero.

EXAMPLE

To record all calls to a function residing in memory between 0xffffffff8016c2c6 and 0xffffffff8016c306 over the course of one second:
% bind –a '#T' /dev
% echo trace 16c2c6 16c306 new a > /dev/tracectl
% echo trace a on > /dev/tracectl
% echo start > /dev/tracectl; sleep 1; echo stop > /dev/tracectl
When that is completed, there are now events in
/dev/trace :
% cat /dev/trace
E ffffffff8016c2c6 00000096d2011acb 0000000000000057 ffffffff80a8b2d8
ffffffff80a8b2d8 ffffffff8016d446 ffffffff80a7c548
X ffffffff8016c306 00000096d2011c3c 0000000000000057 ffffffff80251b38
0000000000000000 0000000000000000 0000000000000000
...

ERRORS

When creating a new trace with the 'new' command, the specified trace name cannot exist, the start address must be less than the end address, and both addresses must be greater than KTZERO and less than etext. For the 'on', 'off', and 'remove' commands, the specified trace must exist or an error will occur.

SOURCE

/sys/src/9/port/devtrace.c
/sys/src/9/*/archtrace.c

SEE ALSO

8l(1), kprof(3), prof(1)