TRACE(3) TRACE(3)
NAME
trace - kernel tracing device.
SYNOPSIS
bind #T /dev /dev/trace /dev/tracectl
DESCRIPTION
The trace device provides a method for kernel tracing. Sec-
tions 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 con-
figuration 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 2^size 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 off
Page 1 Plan 9 (printed 12/21/24)
TRACE(3) TRACE(3)
disables 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 speci-
fied 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.
Page 2 Plan 9 (printed 12/21/24)
TRACE(3) TRACE(3)
SOURCE
/sys/src/9/port/devtrace.c
/sys/src/9/*/archtrace.c
SEE ALSO
8l(1), kprof(3), prof(1)
Page 3 Plan 9 (printed 12/21/24)