.TH DBG 3.SH NAMEdbg \- remote kernel debugging.SH SYNOPSIS.B "bind -b '#b' /dev".PP.B /dev/dbgctl.br.B /dev/dbglog.PP.BI "echo r >/dev/dbgctl".SH DESCRIPTION.I Dbgallows a native kernel to be debugged remotely,by means of a simple protocol, typically run on a serial port(see.IR eia (3)).The.IR acid (10.1)debugger uses the protocol for instance; see its.B -Roption..PP.I Dbguses the values of several global variables set by the kernel configuration file (see.IR conf (10.6)),all of which default values.The variables and default values are listed below:.IP.EXint dbgstart = 0;char	*dbgdata = "#t/eia0";char	*dbgctl = "#t/eia0ctl";char	*dbgctlstart = "b19200";char	*dbgctlstop = "h";char	*dbgctlflush = "f";.EE.PPDifferent values can be set by including similar declarations,with values as desired, in the.B codesection of the configuration file..I Dbguses the values as follows:.TP \w'\f5dbgctlflushxx\fP'u.PD 0.B dbgstartif non-zero, start the debugger protocol on theconfigured connection during driver initialisation (system startup);otherwise it must be started explicitly by the.B rcontrol request (see below).TP.B dbgdatadata file for the debugging connection.TP.B dbgctlcontrol file for the debugging connection.TP.B dbgctlstartcontrol request to initialise link (eg, baud rate).TP.B dbgctlstopcontrol request to hang up link.TP.B dbgctlflushcontrol request to write to flush input and output on link.PD.PP.I Dbgserves two files that control and monitor its operation..PP.B Dbgctlaccepts several textual commands; normally only.B ris needed:.TP.BI d " dbgdata"set the value of.B dbgdatato the value given as an argument.TP.BI c " dbgctl".PD 0.TP.BI i " dbgctlstart".TP.BI h " dbgctlstop".TP.BI f " dbgctlflush"set the value of the corresponding control variable to the value of the first argument.PD.TP.B rstart running the debugger protocol (not needed if.B dbgstartwas non-zero at boot).TP.B sstop running the debugger protocol; stop and flush the link.PPWhen read,.B dbgctlyields a single line showing the status of the device.RB (` running 'or.RB ` stopped ')and the current values of the debugger controlvariables listed above..PP.B Dbglogis a read-only text file containing lines representing debugger events,one per line.It is mainly useful for checking the operation of the device, or debugging new.IR acid (10.1)functions..SS Debug protocolThe protocol is subject to change.The host running the debugger and the target to be debuggedexchange 10-byte messages containing a one byte message typeand 9 bytes of data.Bytes unused by a given type are set to zero.Normally the host sends one of the T-messages below andreceives the corresponding R-message, or.BR Rerr .(These are unrelated to the T-messages and R-messages of.IR intro (5).)Exceptionally, the target sends the first message, an.B Rerrto reset the protocol, and thus the debugger is notified if the targetis rebooted during a debugging session and can reset its own state.Values, including addresses, are sometimes represented textuallyin hexadecimal, but are usually in binary as a single byte, or an array of 4 bytes,high-order byte first (big endian)..PPThe term.I processhere refers exclusively to those created directly or indirectly by.IR kproc (10.2),not to Limbo processes, which are not visible directly throughthe protocol (although it is possible to write.IR acid (10.1)functions that interact through.I dbgwith the Inferno data structures representingthe state of the Dis virtual machine).Many requests read or write the memory or state of the.IR "current process"set by the.B Tprocmessage (see below).Addresses are always 32 bits.An address below the size of.B Ureg(saved register state) for the target is interpreted as an offset within the savedstate 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..PPThe message type names used beloware assigned values by declarations in.BR /include/rdbg.h .The following messages are currently implemented:.TP \w'Tstart'u.PD 0.B Terrunused.TP.BI Rerr " reason\fR[9]\fR"The last message failed for the given.IR reason ,a text string:.BR reset ,the target or debug driver was restarted;.BR count ,bad count;.BR unk ,unknown command;.BR inval ,invalid parameter;.BR pid ,no such process;.BR unsup ,unsupported action;.BR notstop ,action requires process to be stopped first..TP.BI Tmget " addr\fR[4]\fP n\fR[1]\fP"Request.I nbytes of memory from.IR addr ;.I nmust be no greater than 9.TP.BI Rmget " data\fR[9]\fP"Return.I datarequested by.B Tmget.TP.BI Tmput " addr\fR[4]\fP n\fR[1]\fP data\fR[4]\fP"Write the first.I nbytes of.I datato memory at.IR addr ,and flush the data and instruction caches for that region;.I nmust be no greater than 4.TP.BI RmputReply to a successful.B Tmput.TP.BI Tproc " pid\fR[4]\fP"Set the current process to the one with integer process ID.I pidfor subsequent requests..TP.BI Rproc " addr\fR[8]\fP".I Addris the address in hexadecimal text of the.B Procstructure for process.I pidin the corresponding.BR Tproc ..TP.BI Tstatus " pid\fR[4]\fP"Request the status of process.I pidleaving the current process ID unchanged..TP.BI Rstatus " status\fR[9]\fP"Return the textual status of the processas a text string, currently one of:.BR Dead ,.BR Moribund ,.BR Ready ,.BR Scheding ,.BR Running ,.BR Queueing ,.BR Wakeme ,.BR Broken ,.BR Stopped ,.BR Rendezvous ,or if invalid, the state value as a hexadecimal number..TP.BI Trnote " pid\fR[4]\fP"Retrieve the note (trap status) for the given.I pid.TP.BI Rrnote " status\fR[9]\fP"Provide the textual trap.I statusfor the requested process (currently always returns null status).TP.BI Tstop " pid\fR[4]\fP"Tell the kernel to stop running process.I pidin debugging state.B Stoppedwhen it next appears in the scheduler..TP.BI RstopReply to successful.B Tstop.TP.BI TstartCancel a previous.BR Tstop ;if the process has already stopped, make it ready to run..TP.BI RstartReply to successful.B Tstart.TP.BI Tcondbreak " val\fR[4]\fP op\fR[4]\fP"If.I opis.BR d ,remove and delete the breakpoint with ID.IR val .All other operations helpcreate a conditional breakpoint, providing a possibly empty list of operationsrepresenting a conditional expression in Reverse Polish is followedby a breakpoint request,each expression element represented by a single.B Tcondbreakmessage..I Opis a single character representing an operation, with.I val(integer, address, process ID) as a parameter.The operator.B nshould appear first; it assigns thebreakpoint an ID number.I val(no greater than 255).Expression primaries are:.BI k " val,"true if process.I valis at this breakpoint;.BI b " val,"true if program counter is.IR val ;and.BI p " val,".I valas a 32-bit literal.Expression operators are:unary.B *(indirect, yielding 32-bit value);.B &(bit-wise AND);.B =(values equal);.B !(values not equal);.B a(logical AND);.B o(logical OR).Although the expression is interpreted following Reverse Polish notation,when transmitted, the.B boperation 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..TP.BI RcondbreakReply to successful.BR Tcondbreak ..TP.BI Tstartstop " pid\fR[4]\fP"If the process.I pidis not stopped, return.B Rerr.BR notstop .Otherwise, if the process is not stopped ata breakpoint, start it, and wait for it to reach a breakpointthat evaluates `true'.TP.BI Rstartstop " id\fR[1]\fP"Process has stopped at breakpoint with the given.I id.TP.BI TwaitstopUnimplemented. See.BR Tstartstop ..TP.BI RwaitstopUnused..TP.BI Tkill " pid\fR[4]\fP note\fR[5]\fP"Kill process.I pidwith the given textual.IR note .Unimplemented..TP.BI RkillReply to successful.BR Tkill .Unused..PP.SH SOURCE.B /os/port/devdbg.c.br.B /os/*/*break.c.br.B /os/*/trap.c.SH SEE ALSO.IR acid (10.1).SH BUGSThe protocol is not itself error-detecting let alone error-correcting, although that normally does notmatter for debugging evenover a serial line, provided the connection is reasonably sound.