DBG(3)                                                     DBG(3)

     NAME
          dbg - remote kernel debugging

     SYNOPSIS
          bind -b '#b' /dev

          /dev/dbgctl
          /dev/dbglog

          echo r >/dev/dbgctl

     DESCRIPTION
          Dbg allows a native kernel to be debugged remotely, by means
          of a simple protocol, typically run on a serial port (see
          eia(3)). The acid(10.1) debugger uses the protocol for
          instance; see its -R option.

          Dbg uses the values of several global variables set by the
          kernel configuration file (see conf(10.6)), all of which
          default values.  The variables and default values are listed
          below:

               int dbgstart = 0;
               char *dbgdata = "#t/eia0";
               char *dbgctl = "#t/eia0ctl";
               char *dbgctlstart = "b19200";
               char *dbgctlstop = "h";
               char *dbgctlflush = "f";

          Different values can be set by including similar declara-
          tions, with values as desired, in the code section of the
          configuration file.  Dbg uses the values as follows:

          dbgstart     if non-zero, start the debugger protocol on the
                       configured connection during driver initialisa-
                       tion (system startup); otherwise it must be
                       started explicitly by the r control request
                       (see below)
          dbgdata      data file for the debugging connection
          dbgctl       control file for the debugging connection
          dbgctlstart  control request to initialise link (eg, baud
                       rate)
          dbgctlstop   control request to hang up link
          dbgctlflush  control request to write to flush input and
                       output on link

          Dbg serves two files that control and monitor its operation.

          Dbgctl accepts several textual commands; normally only r is
          needed:

     Page 1                       Plan 9             (printed 3/29/24)

     DBG(3)                                                     DBG(3)

          d dbgdata
               set the value of dbgdata to the value given as an argu-
               ment

          c dbgctl
          i dbgctlstart
          h dbgctlstop
          f dbgctlflush
               set the value of the corresponding control variable to
               the value of the first argument

          r    start running the debugger protocol (not needed if
               dbgstart was non-zero at boot)

          s    stop running the debugger protocol; stop and flush the
               link

          When read, dbgctl yields a single line showing the status of
          the device (`running' or `stopped') and the current values
          of the debugger control variables listed above.

          Dbglog is a read-only text file containing lines represent-
          ing debugger events, one per line.  It is mainly useful for
          checking the operation of the device, or debugging new
          acid(10.1) functions.

        Debug protocol
          The protocol is subject to change.  The host running the
          debugger and the target to be debugged exchange 10-byte mes-
          sages containing a one byte message type and 9 bytes of
          data.  Bytes unused by a given type are set to zero.  Nor-
          mally the host sends one of the T-messages below and
          receives the corresponding R-message, or Rerr.  (These are
          unrelated to the T-messages and R-messages of intro(5).)
          Exceptionally, the target sends the first message, an Rerr
          to reset the protocol, and thus the debugger is notified if
          the target is rebooted during a debugging session and can
          reset its own state.  Values, including addresses, are some-
          times represented textually in hexadecimal, but are usually
          in binary as a single byte, or an array of 4 bytes, high-
          order byte first (big endian).

          The term process here refers exclusively to those created
          directly or indirectly by kproc(10.2), not to Limbo pro-
          cesses, which are not visible directly through the protocol
          (although it is possible to write acid(10.1) functions that
          interact through dbg with the Inferno data structures repre-
          senting the state of the Dis virtual machine).  Many
          requests read or write the memory or state of the current
          process set by the Tproc message (see below).  Addresses are
          always 32 bits.  An address below the size of Ureg (saved
          register state) for the target is interpreted as an offset

     Page 2                       Plan 9             (printed 3/29/24)

     DBG(3)                                                     DBG(3)

          within the saved state for the current process.  Otherwise
          it refers to an address in kernel virtual memory.  Currently
          in native Inferno all processes share the same address
          space.

          The message type names used below are assigned values by
          declarations in /include/rdbg.h.  The following messages are
          currently implemented:

          Terr  unused
          Rerr reason[9]
                The last message failed for the given reason, a text
                string: reset, the target or debug driver was res-
                tarted; count, bad count; unk, unknown command; inval,
                invalid parameter; pid, no such process; unsup, unsup-
                ported action; notstop, action requires process to be
                stopped first.
          Tmget addr[4] n[1]
                Request n bytes of memory from addr; n must be no
                greater than 9
          Rmget data[9]
                Return data requested by Tmget
          Tmput addr[4] n[1] data[4]
                Write the first n bytes of data to memory at addr, and
                flush the data and instruction caches for that region;
                n must be no greater than 4
          Rmput Reply to a successful Tmput
          Tproc pid[4]
                Set the current process to the one with integer pro-
                cess ID pid for subsequent requests.
          Rproc addr[8]
                Addr is the address in hexadecimal text of the Proc
                structure for process pid in the corresponding Tproc.
          Tstatus pid[4]
                Request the status of process pid leaving the current
                process ID unchanged.
          Rstatus status[9]
                Return the textual status of the process as a text
                string, currently one of: Dead, Moribund, Ready,
                Scheding, Running, Queueing, Wakeme, Broken, Stopped,
                Rendezvous, or if invalid, the state value as a hex-
                adecimal number.
          Trnote pid[4]
                Retrieve the note (trap status) for the given pid
          Rrnote status[9]
                Provide the textual trap status for the requested pro-
                cess (currently always returns null status)
          Tstop pid[4]
                Tell the kernel to stop running process pid in debug-
                ging state Stopped when it next appears in the sched-
                uler.
          Rstop Reply to successful Tstop

     Page 3                       Plan 9             (printed 3/29/24)

     DBG(3)                                                     DBG(3)

          Tstart
                Cancel a previous Tstop; if the process has already
                stopped, make it ready to run.
          Rstart
                Reply to successful Tstart
          Tcondbreak val[4] op[4]
                If op is d, remove and delete the breakpoint with ID
                val. All other operations help create a conditional
                breakpoint, providing a possibly empty list of opera-
                tions representing a conditional expression in Reverse
                Polish is followed by a breakpoint request, each
                expression element represented by a single Tcondbreak
                message.  Op is a single character representing an
                operation, with val (integer, address, process ID) as
                a parameter.  The operator n should appear first; it
                assigns the breakpoint an ID number val (no greater
                than 255).  Expression primaries are: k val, true if
                process val is at this breakpoint; b val, true if pro-
                gram counter is val; and p val, val as a 32-bit lit-
                eral.  Expression operators are: unary * (indirect,
                yielding 32-bit value); & (bit-wise AND); = (values
                equal); ! (values not equal); a (logical AND); o (log-
                ical OR).  Although the expression is interpreted fol-
                lowing Reverse Polish notation, when transmitted, the
                b operation is sent last (to mark the end of the
                sequence and create the breakpoint), but is moved to
                the start of the expression before evaluation.
          Rcondbreak
                Reply to successful Tcondbreak.
          Tstartstop pid[4]
                If the process pid is not stopped, return Rerr
                notstop.  Otherwise, if the process is not stopped at
                a breakpoint, start it, and wait for it to reach a
                breakpoint that evaluates `true'
          Rstartstop id[1]
                Process has stopped at breakpoint with the given id
          Twaitstop
                Unimplemented. See Tstartstop.
          Rwaitstop
                Unused.
          Tkill pid[4] note[5]
                Kill process pid with the given textual note. Unimple-
                mented.
          Rkill Reply to successful Tkill.  Unused.
     SOURCE
          /os/port/devdbg.c
          /os/*/*break.c
          /os/*/trap.c

     SEE ALSO
          acid(10.1)

     Page 4                       Plan 9             (printed 3/29/24)

     DBG(3)                                                     DBG(3)

     BUGS
          The protocol is not itself error-detecting let alone error-
          correcting, although that normally does not matter for
          debugging even over a serial line, provided the connection
          is reasonably sound.

     Page 5                       Plan 9             (printed 3/29/24)