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 4/19/21)

     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 4/19/21)

     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 4/19/21)