.TH TRACE 3 .SH NAMEtrace \- kernel tracing device..SH SYNOPSIS.B bind #T /dev.B /dev/trace.B /dev/tracectl.SH DESCRIPTIONThe trace device provides a method for kernel tracing.  Sections ofmemory (\&“traces\&”) are selected;.B trace events will be recorded whenever the program counter enters or leaves afunction within those sections of memory.  This is useful in examininghow many times a function is called, with what arguments, and how muchtime is spent in that function..PPThe timestamps recorded are taken from the.CW cycles()function, which is architecture-dependent.  In the x86, for example,the timestamp will be the value of the.B tscregister..PPThe.B tracectlfile provides information on the current configuration and allowschanges to be made.  The following are valid commands to be echoedinto.B /dev/tracectl; note that all addresses can be given as offsets from.B KTZERO, although giving a full address will work too:.PP.IP "\f5all\fP" 1.2ienables tracing for all events.  During normal operation, functioncalls from interrupt context will be ignored; issuing an.B 'all'command will cause them to be recorded. The .B 'stop'command resets the system to default operation..IP "\f5size\fP \f2size\fP" 1.2i.brresizes the trace log to .if t 2\s-2\v'-0.4m'size\v'0.4m\s+2  .if n 2^sizeelements..IP "\f5start\fP" 1.2iturns on tracing.  Any traces that are on will now begin registeringevents to.B /dev/trace.IP "\f5stop\fP" 1.2iturns off tracing..IP "\f5trace\fP \f2startaddr\fP \f2endaddr\fP \f5new\fP \f2name\fP" 1.2icreates a new trace between addresses.IR startaddrand.IR endaddr..IP "\f5trace\fP \f2name\fP \f5remove\fP" 1.2iremoves the specified trace.IP "\f5trace\fP \f2name\fP \f5on\fP" 1.2ienables the specified trace. No \&"hits\&" will be generated until the.B startcommand is given..IP "\f5trace\fP \f2name\fP \f5off\fP" 1.2idisables the specified trace. No \&"hits\&" will ever occur..IP "\f5watch\fP \f2pid\fP" 1.2i.bronly records events from the given PID. Repeated.B watchcommands will add to the list of PIDs.  If a PID of 0 is given, thesystem will revert to recording all events..PPTrace events are recorded in.B /dev/traceas 121-byte lines (including the newline). The format of an event is:.IP "\f2eventtype PC timestamp caller-PID arg1 arg2 arg3 arg4"The .IR event typeis E for an entry and X for an exit.The .IR PCis the current program counter.The.IR timestampis the system cycles clock.The .IR PIDis the PID for the process originating the function call.  Arguments 1through 4 are the first four arguments of the function for a functionentry; for an exit event,.IR arg 1is the return value.  If there are only two arguments to a function,for example, only.IR arg 1and.IR arg 2will have values, while the others will be zero. .SH EXAMPLETo record all calls to a function residing in memory between.B 0xffffffff8016c2c6and.B 0xffffffff8016c306over the course of one second:.IP.EX% 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.EE.TP 0When that is completed, there are now events in.B /dev/trace :.IP.EX% cat /dev/traceE ffffffff8016c2c6 00000096d2011acb 0000000000000057 ffffffff80a8b2d8ffffffff80a8b2d8 ffffffff8016d446 ffffffff80a7c548X ffffffff8016c306 00000096d2011c3c 0000000000000057 ffffffff80251b380000000000000000 0000000000000000 0000000000000000\&....EE.SH ERRORSWhen creating a new trace with the 'new' command, the specified tracename cannot exist, the start address must be less than the endaddress, and both addresses must be greater than KTZERO and less thanetext.  For the 'on', 'off', and 'remove' commands, the specifiedtrace must exist or an error will occur..SH SOURCE.B /sys/src/9/port/devtrace.c.br.B /sys/src/9/*/archtrace.c.SH "SEE ALSO".IR 8l (1) ,.IR kprof (3) ,.IR prof (1)