gdb/doc/remote.texi: Rewrite protocol section (draft)

[Andrew Cagney <ac131313@cygnus.com>]

FYI,

I've just checked in the attached.  While still a draft it is, at least,
more correct than old  previous doco.

	Andrew
? diffs
Index: ChangeLog
===================================================================
RCS file: /cvs/cvsfiles/devo/gdb/doc/ChangeLog,v
retrieving revision 2.313
diff -p -r2.313 ChangeLog
*** ChangeLog	1999/06/24 16:40:03	2.313
--- ChangeLog	1999/06/24 16:41:58
***************
*** 1,3 ****
--- 1,7 ----
+ Fri Jun 25 02:40:34 1999  Andrew Cagney  <cagney@b1.cygnus.com>
+ 
+ 	* remote.texi (Communication Protocol): Rewrite.
+ 
  Thu Jun 24 16:59:54 1999  Andrew Cagney  <cagney@b1.cygnus.com>
  
  	* stabs.texinfo: Fix uses of xref.
Index: remote.texi
===================================================================
RCS file: /cvs/cvsfiles/devo/gdb/doc/remote.texi,v
retrieving revision 2.30
diff -p -r2.30 remote.texi
*** remote.texi	1999/03/10 03:32:26	2.30
--- remote.texi	1999/06/24 16:42:04
*************** recently added stubs.
*** 95,101 ****
  * Stub Contents::       What the stub can do for you
  * Bootstrapping::       What you must do for the stub
  * Debug Session::       Putting it all together
! * Protocol::            Outline of the communication protocol
  * Server::		Using the `gdbserver' program
  * NetWare::		Using the `gdbserve.nlm' program
  @end menu
--- 95,101 ----
  * Stub Contents::       What the stub can do for you
  * Bootstrapping::       What you must do for the stub
  * Debug Session::       Putting it all together
! * Protocol::            Definition of the communication protocol
  * Server::		Using the `gdbserver' program
  * NetWare::		Using the `gdbserve.nlm' program
  @end menu
*************** the protocol---for example, if there is 
*** 365,443 ****
  target machine, you might want your program to do something special if
  it recognizes a packet meant for @value{GDBN}.
  
  @cindex protocol, @value{GDBN} remote serial
  @cindex serial protocol, @value{GDBN} remote
  @cindex remote serial protocol
! All @value{GDBN} commands and responses (other than acknowledgements, which
! are single characters) are sent as a packet which includes a
! checksum.  A packet is introduced with the character @samp{$}, and ends
! with the character @samp{#} followed by a two-digit checksum:
  
  @example
! $@var{packet info}#@var{checksum}
  @end example
  
  @cindex checksum, for @value{GDBN} remote
  @noindent
! @var{checksum} is computed as the modulo 256 sum of the @var{packet
! info} characters.
  
  When either the host or the target machine receives a packet, the first
! response expected is an acknowledgement: a single character, either
! @samp{+} (to indicate the package was received correctly) or @samp{-}
! (to request retransmission).
! 
! The host (@value{GDBN}) sends commands, and the target (the debugging stub
! incorporated in your program) sends data in response.  The target also
! sends data when your program stops.
  
! Command packets are distinguished by their first character, which
! identifies the kind of command.
  
! These are some of the commands currently supported (for a complete list of 
! commands, look in @file{gdb/remote.c.}):
  
! @table @code
! @item g
! Requests the values of CPU registers.
  
! @item G
! Sets the values of CPU registers.
  
! @item m@var{addr},@var{count}
! Read @var{count} bytes at location @var{addr}.
  
! @item M@var{addr},@var{count}:@dots{}
! Write @var{count} bytes at location @var{addr}.
! 
! @need 500
! @item c
! @itemx c@var{addr}
! Resume execution at the current address (or at @var{addr} if supplied).
! 
! @need 500
! @item s
! @itemx s@var{addr}
! Step the target program for one instruction, from either the current
! program counter or from @var{addr} if supplied.
! 
! @item k
! Kill the target program.
! 
! @item ?
! Report the most recent signal.  To allow you to take advantage of the
! @value{GDBN} signal handling commands, one of the functions of the debugging
! stub is to report CPU traps as the corresponding POSIX signal values.
! 
! @item T
! Allows the remote stub to send only the registers that @value{GDBN} needs
! to make a quick decision about single-stepping or conditional breakpoints.
! This eliminates the need to fetch the entire register set for each instruction
! being stepped through.
  
! @value{GDBN} now implements a write-through cache for registers and only
! re-reads the registers if the target has run.
! @end table
  
  @kindex set remotedebug
  @kindex show remotedebug
--- 365,952 ----
  target machine, you might want your program to do something special if
  it recognizes a packet meant for @value{GDBN}.
  
+ In the examples below, @samp{<-} and @samp{->} are used to indicate
+ transmitted and received data respectfully.
+ 
  @cindex protocol, @value{GDBN} remote serial
  @cindex serial protocol, @value{GDBN} remote
  @cindex remote serial protocol
! All @value{GDBN} commands and responses (other than acknowledgements)
! are sent as a @var{packet}.  A @var{packet} is introduced with the
! character @samp{$}, this is followed by an optional two-digit
! @var{sequence-id} and the character @samp{:}, the actual
! @var{packet-data}, and the terminating character @samp{#} followed by a
! two-digit @var{checksum}:
  
  @example
! @code{$}@var{packet-data}@code{#}@var{checksum}
  @end example
+ @noindent
+ or, with the optional @var{sequence-id}:
+ @example
+ @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
+ @end example
  
  @cindex checksum, for @value{GDBN} remote
+ @noindent
+ The two-digit @var{checksum} is computed as the modulo 256 sum of all
+ characters between the leading @samp{$} and the trailing @samp{#} (that
+ consisting of both the optional @var{sequence-id}@code{:} and the actual
+ @var{packet-data}).
+ 
+ @cindex sequence-id, for @value{GDBN} remote
  @noindent
! The two-digit @var{sequence-id}, when present, is returned with the
! acknowledgement.  Beyond that its meaning is poorly defined.
! @value{GDBN} is not known to output @var{sequence-id}s.
  
  When either the host or the target machine receives a packet, the first
! response expected is an acknowledgement: either @samp{+} (to indicate
! the package was received correctly) or @samp{-} (to request
! retransmission):
  
! @example
! <- @code{$}@var{packet-data}@code{#}@var{checksum}
! -> @code{+}
! @end example
! @noindent
! If the received packet included a @var{sequence-id} than that is
! appended to a positive acknowledgement:
  
! @example
! <- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum}
! -> @code{+}@var{sequence-id}
! @end example
  
! The host (@value{GDBN}) sends @var{command}s, and the target (the
! debugging stub incorporated in your program) sends a @var{response}.  In
! the case of step and continue @var{command}s, the response is only sent
! when the operation has completed (the target has again stopped).
! 
! @var{packet-data} consists of a sequence of characters with the
! exception of @samp{#} and @samp{$} (see @samp{X} packet for an
! exception). @samp{:} can not appear as the third character in a packet.
! Fields within the packet should be separated using @samp{,} and @samp{;}
! (unfortunatly some packets chose to use @samp{:}).  Except where
! otherwize noted all numbers are represented in HEX with leading zeros
! supressed.
! 
! Response @var{data} can be run-length encoded to save space.  A @samp{*}
! means that the next character is an ASCII encoding giving a repeat count
! which stands for that many repititions of the character preceding the
! @samp{*}.  The encoding is @code{n+29}, yielding a printable character
! where @code{n >=3} (which is where rle starts to win).  Don't use an
! @code{n > 126}.
  
! So:
! @example
! "@code{0* }"
! @end example
! @noindent
! means the same as "0000".
  
! The error response, returned for some packets includes a two character
! error number.  That number is not well defined.
  
! For any @var{command} not supported by the stub, an empty response
! (@samp{$#00}) should be returned.  That way it is possible to extend the
! protocol.  A newer GDB can tell if a packet is supported based on the
! response.
! 
! Below is a complete list of all currently defined @var{command}s and
! their corresponding response @var{data}:
! 
! @multitable @columnfractions .15 .30 .55
! @item Request
! @tab Packet
! @tab Description
! 
! @item extended ops
! @tab @code{!}
! @tab
! Use the extended remote protocol. Sticky -- only needs to be set once.
! The extended remote protocol support the @samp{R} packet.
! @item
! @tab reply @samp{}
! @tab
! Stubs that support the extended remote protocol return @samp{} which,
! unfortunatly, is identical to the response returned by stubs that do not
! support protocol extensions.
! 
! @item last signal
! @tab @code{?}
! @tab
! Reply the current reason for stopping.  This is the same reply as is
! generated for step or cont : @code{S}@var{AA} where @var{AA} is the
! signal number.
! 
! @item reserved
! @tab @code{a}
! @tab Reserved for future use 
! 
! @item set program arguments @strong{(reserved)}
! @tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...}
! @tab
! Initialized @samp{argv[]} array passed into program. @var{arglen}
! specifies the number of bytes in the hex encoded byte stream @var{arg}.
! @item
! @tab reply @code{OK}
! @item
! @tab reply @code{E}@var{NN}
  
! @item set baud @strong{(deprecated)}
! @tab @code{b}@var{baud}
! @tab
! Change the serial line speed to @var{baud}.  JTC: @emph{When does the
! transport layer state change?  When it's received, or after the ACK is
! transmitted.  In either case, there are problems if the command or the
! acknowlegement packet is dropped.} Stan: @emph{If people really wanted
! to add something like this, and get it working for the first time, they
! ought to modify ser-unix.c to send some kind of out-of-band message to a
! specially-setup stub and have the switch happen "in between" packets, so
! that from remote protocol's point of view, nothing actually
! happened.}
! 
! @item set breakpoint  @strong{(deprecated)}
! @tab @code{B}@var{addr},@var{mode}
! @tab
! Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a
! breakpoint at @{addr}.  @emph{This has been replaced by the @samp{Z} and
! @samp{z} packets.}
! 
! @item continue
! @tab @code{c}@var{addr}
! @tab
! @var{addr} is address to resume. If @var{addr} is omitted, resume at
! current address.
! @item
! @tab reply
! @tab see below
! 
! @item continue with signal
! @tab @code{C}@var{sig}@code{;}@var{addr}
! @tab
! Continue with signal @var{sig} (hex signal number).  If @code{;}@{addr}
! is omitted, resume at same address.
! @item
! @tab reply
! @tab see below
! 
! @item toggle debug
! @tab @code{d}
! @tab
! toggle debug flag (see 386 & 68k stubs)
! 
! @item detach
! @tab @code{D}
! @tab Reply OK.
! 
! @item reserved
! @tab @code{e}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{E}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{f}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{F}
! @tab Reserved for future use 
! 
! @item read registers
! @tab @code{g}
! @tab Read general registers.
! @item
! @tab reply @var{XX...}
! @tab
! Each byte of register data is described by two hex digits.  The bytes
! with the register are transmitted in target byte order.  The size of
! each register and their position within the @samp{g} @var{packet} is
! determined by the @var{REGISTER_RAW_SIZE} and @var{REGISTER_NAME}
! macros.
! @item
! @tab @code{E}@var{NN}
! @tab for an error.
! 
! @item write regs
! @tab @code{G}@var{XX...}
! @tab
! See @samp{g} for a description of the @var{XX...} data.
! @item
! @tab reply @code{OK}
! @tab for success
! @item
! @tab reply @code{E}@var{NN}
! @tab for an error
! 
! @item reserved
! @tab @code{h}
! @tab Reserved for future use 
! 
! @item set thread
! @tab @code{H}@var{c}@var{t...}
! @tab
! Set thread for subsequent operations.  @var{c} = @samp{c} for thread
! used in step and continue; @var{t...} can be -1 for all threads.
! @var{c} = @samp{g} for thread used in other operations.  If zero, pick a
! thread, any thread.
! @item
! @tab reply @code{OK}
! @tab for success
! @item
! @tab reply @code{E}@var{NN}
! @tab for an error
! 
! @item cycle step @strong{(reserved)}
! @tab @code{i}@var{addr}@code{,}@var{nnn}
! @tab
! Step the remote target by a single clock cycle.  If @code{,}@var{nnn} is
! present, cycle step @var{nnn} cycles.  If @var{addr} is non-empty, cycle
! step starting at address @var{addr}.
! 
! @item @strong{(reserved)}
! @tab @code{I}
! @tab
! See @samp{i} and @samp{S}.
! 
! @item reserved
! @tab @code{j}
! @tab Reserved for future use
! 
! @item reserved
! @tab @code{J}
! @tab Reserved for future use 
! 
! @item kill request
! @tab @code{k}
! @tab
! 
! @item reserved
! @tab @code{l}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{L}
! @tab Reserved for future use 
! 
! @item read memory
! @tab @code{m}@var{addr}@code{,}@var{length}
! @tab
! Read @var{length} bytes of memory starting at address @var{addr}.
! @item
! @tab reply @var{XX...}
! @tab
! @var{XX...} is mem contents. Can be fewer bytes than requested if able to
! read only part of the data.
! @item
! @tab reply @code{E}@var{NN}
! @tab @{NN} is errno
! 
! @item write mem
! @tab @code{M}@var{addr},@var{length}@code{:}@var{XX...}
! @tab
! Write @var{length} bytes of memory starting at address @var{addr}.
! @var{XX...} is the data.
! @item
! @tab reply @code{OK}
! @tab for success
! @item
! @tab reply @code{E}@var{NN}
! @tab
! for an error (this includes the case where only part of the data was
! written).
! 
! @item reserved
! @tab @code{n}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{N}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{o}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{O}
! @tab Reserved for future use 
! 
! @item read reg @strong{(reserved)}
! @tab @code{p}@var{n...}
! @tab
! See write register.
! @item
! @tab return @var{r....}
! @tab The hex encoded value of the register in target byte order.
! 
! @item write reg
! @tab @code{P}@var{n...}@code{=}@var{r...}
! @tab
! Write register @var{n...} with value @var{r...}, which contains two hex
! digits for each byte in the register (target byte order).  @emph{(Not
! supported by all stubs.)}
! @item
! @tab reply @code{OK}
! @tab for success
! @item
! @tab reply @code{E}@var{NN}
! @tab for an error
! 
! @item general query
! @tab @code{q}@var{query}
! @tab
! Request info about @var{query}. In general @value{GDBN} @var{query}'s
! have a leading upper case letter.  Custom vendor queries should use a
! leading lower case letter and a company prefix, ex: @samp{qfsf.var}.
! @var{query} may optionally be followed by a @samp{,} or @samp{;}
! separated list.  Stubs should ensure that they fully match any
! @var{query} name.
! @item
! @tab reply @{XX...}
! @tab Hex encoded data from query. The reply can not be empty.
! @item
! @tab reply @code{E}@var{NN}
! @tab error reply
! @item
! @tab reply @samp{}
! @tab Indicating an unrecognized @var{query}.
! 
! @item
! @tab @code{q}@code{C}@var{...}
! @tab
! 
! @item compute CRC of memory block
! @tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length}
! @tab
! @item
! @tab reply @code{E}@var{NN}
! @tab An error (such as memory fault)
! @item
! @tab reply @code{C}@var{CRC32}
! A 32 bit cyclic redundancy check of the specified memory region.
! 
! @item
! @tab @code{q}@code{L}@var{...}
! @tab
! 
! @item query sect offs
! @tab @code{q}@code{Offsets}
! @tab Get section offsets.
! @item
! @tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz}
! 
! @item
! @tab @code{q}@code{P}@var{...}
! @tab
! 
! @item remote command @strong{(reserved)}
! @tab @code{q}@code{Rcmd,}@var{COMMAND}
! @tab
! @var{COMMAND} (hex encoded) is passed to the local interpreter for
! execution.  @emph{Implementors should note that providing access to a
! stubs's interpreter may have security implications}.
! @item
! @tab reply @var{OUTPUT}
! @tab
! The @var{OUTPUT} (hex encoded).  Must be non-empty.
! @item
! @tab reply @samp{}
! @tab
! When @samp{qRcmd} is not recognized.
! 
! @item general set
! @tab @code{Q}@var{var}=@var{val}
! @tab
! Set value of @var{var} to @var{val}.  See @samp{q} for a discussing of
! naming conventions.
! 
! @item reset
! @tab r
! @tab reset -- see sparc stub.
! 
! @item remote restart
! @tab @code{R}@var{XX}
! @tab
! Restart the remote server. @var{XX} while needed has no clear
! definition.
! 
! @item step
! @tab @code{s}@var{addr}
! @tab
! @var{addr} is address to resume.  If @var{addr} is omitted, resume at
! same address.
! @item
! @tab reply
! @tab see below
! 
! @item step with signal
! @tab @code{S}@var{sig}@code{;}@var{addr}
! @tab
! Like @samp{C} but step not continue.
! @item
! @tab reply
! @tab see below
! 
! @item reserved
! @tab @code{t}
! @tab Reserved for future use 
! 
! @item search
! @tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM}
! @tab
! Search backwards starting at address @var{addr} for a match with pattern
! @var{PP} and mask @var{MM}.  @var{PP} and @var{MM} are 4 bytes.  Not
! supported by all stubs.  @var{addr} must be at least 3 digits.
! 
! @item thread alive
! @tab @code{T}@var{XX}
! @tab Find out if the thread XX is alive.
! @item
! @tab reply @code{OK}
! @tab thread is still alive
! @item
! @tab reply @code{E}@var{NN}
! @tab thread is dead
! 	
! @item reserved
! @tab @code{u}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{U}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{v}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{V}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{w}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{W}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{x}
! @tab Reserved for future use 
! 
! @item write mem (binary)
! @tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...}
! @tab
! @var{addr} is address, @{length} is number of bytes, @var{XX...} is
! binary data.
! @item
! @tab reply @code{OK}
! @tab for success
! @item
! @tab reply @code{E}@var{NN}
! @tab for an error
! 
! @item reserved
! @tab @code{y}
! @tab Reserved for future use 
! 
! @item reserved
! @tab @code{Y}
! @tab Reserved for future use 
! 
! @item remove break or watchpoint @strong{(reserved)}
! @tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length}
! @tab
! See @samp{Z}. @emph{Not supported by all stubs.}
! 
! @item insert break or watchpoint @strong{(reserved)}
! @tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length}
! @tab
! @var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware
! breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint,
! @samp{4} - access watchpoint; @var{addr} is address; @var{length} is in
! bytes.  For a software breakpoint, @var{length} specifies the size of
! the instruction to be patched.  For hardware breakpoints and watchpoints
! @var{length} specifies the memory region to be monitored. @emph{Not
! supported by all stubs.}
! @item
! @tab reply @code{E}@var{NN}
! @tab for an error
! @item
! @tab reply @code{OK}
! @tab for success
! @item
! @tab @samp{}
! @tab If not supported.
! 
! @item reserved
! @tab <other>
! @tab Reserved for future use 
! 
! @end multitable
! 
! In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets, there is no immediate response.  The reply comes when the machine stops:
! 
! @multitable @columnfractions .4 .6
! 
! @item @code{S}@var{AA}
! @tab @var{AA} is the signal number
! 
! @item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}
! @tab
! @var{AA} = signal number; @var{n...} = register number (hex), @var{r...}
! = register contents; @var{n...} = @samp{thread}, @var{r...} = thread
! process ID, this is a hex integer; @var{n...} = other string not
! starting with valid hex digit.  gdb should ignore this @var{n...},
! @var{r...} pair and go on to the next.  This way we can extend the
! protocol.
! 
! @item @code{W}@var{AA}
! @tab
! The process exited, and @var{AA} is the exit status.  This is only
! applicable for certains sorts of targets.
! 
! @item @code{X}@var{AA}
! @tab
! The process terminated with signal @var{AA}.
! 
! @item @strong{(obsolete)} @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb}
! @tab
! @var{AA} = signal number; @var{tttttttt} = address of symbol "_start";
! @var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss
! section. @emph{Note: only used by Cisco Systems targets.  The difference
! between this reply and the "qOffsets" query is that the 'N' packet may
! arrive spontaneously whereas the 'qOffsets' is a query initiated by the
! host debugger.}
! 
! @item @code{O}@var{XX...}
! @tab
! @var{XX...} is hex encoding of ASCII data. This can happen at any time
! while the program is running and the debugger should continue to wait
! for 'W', 'T', etc.
! 
! @end multitable
! 
! Example sequence of a target being re-started.  Notice how the restart
! does not get any direct output:
! 
! @example
! <- @code{R00}
! -> @code{+}
! @emph{target resets}
! <- @code{?}
! -> @code{+}
! -> @code{something}
! <- @code{+}
! @end example
! 
  
  @kindex set remotedebug
  @kindex show remotedebug