Fri Sep 4 18:53:57 1992 Roland H. Pesch (pesch@fowanton.cygnus.com)

	* doc/gdb.texinfo: fix shameful error of agreement reported by
	jimb@occs.cs.oberlin.edu (Jim Blandy)
	* doc/gdb.texinfo: remove old partial discussion of remote serial
	protocol (via serial debug stubs)
	* doc/gdbinv-m.m4.in, doc/gdbinv-s.m4.in: new section discussing
	use of serial debug stubs

3 files changed, 364 insertions, 49 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 3e7ed80..8902cb5 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1,6 +1,6 @@
 _dnl__                                          -*-Texinfo-*-
 _dnl__ Copyright (c) 1988 1989 1990 1991 1992 Free Software Foundation, Inc.
-_dnl__ $Id$
+_dnl__ $Id$<>_dnl__
 \input texinfo      @c -*-texinfo-*-
 @c Copyright (c) 1988 1989 1990 1991 1992 Free Software Foundation, Inc.
 @c %**start of header 
@@ -321,12 +321,12 @@ Using the new command @code{target}, you can select at runtime whether
 you are debugging local files, local processes, standalone systems over
 a serial port, realtime systems over a TCP/IP connection, etc.  The
 command @code{load} can download programs into a remote system.  Serial
-stubs are available for Motorola 680x0 and Intel 80386 remote systems;
-GDB also supports debugging realtime processes running under
+stubs are available for Motorola 680x0, Intel 80386, and Sparc remote
+systems; GDB also supports debugging realtime processes running under
 VxWorks, using SunRPC Remote Procedure Calls over TCP/IP to talk to a
-debugger stub on the target system.  Internally, GDB now uses a
-function vector to mediate access to different targets; if you need to
-add your own support for a remote protocol, this makes it much easier.
+debugger stub on the target system.  Internally, GDB now uses a function
+vector to mediate access to different targets; if you need to add your
+own support for a remote protocol, this makes it much easier.
 
 @item Watchpoints
 GDB now sports watchpoints as well as breakpoints.  You can use a
@@ -6562,46 +6562,6 @@ not specific to any particular target system) which you can use if you
 write the remote stubs---the code that will run on the remote system to
 communicate with GDB.
 
-To use the GDB remote serial protocol, the program to be debugged on
-the remote machine needs to contain a debugging stub which talks to
-GDB over the serial line.  Several working remote stubs are
-distributed with GDB; see the @file{README} file in the GDB
-distribution for more information.
-
-For details of this communication protocol, see the comments in the
-GDB source file @file{remote.c}.
-
-To start remote debugging, first run GDB and specify as an executable file
-the program that is running in the remote machine.  This tells GDB how
-to find your program's symbols and the contents of its pure text.  Then
-establish communication using the @code{target remote} command with a device
-name as an argument.  For example:
-
-@example
-target remote /dev/ttyb
-@end example
-
-@noindent
-if the serial line is connected to the device named @file{/dev/ttyb}.  This
-will stop the remote machine if it is not already stopped.
-
-Now you can use all the usual commands to examine and change data and to
-step and continue the remote program.
-
-To resume the remote program and stop debugging it, use the @code{detach}
-command.
-
-@kindex set remotedebug
-@kindex show remotedebug
-@cindex packets, reporting on stdout
-@cindex serial connections, debugging
-If you have trouble with the serial connection, you can use the command
-@code{set remotedebug}.  This makes _GDBN__ report on all packets sent
-back and forth across the serial line to the remote machine.  The
-packet-debugging information is printed on the _GDBN__ standard output
-stream.  @code{set remotedebug off} turns it off, and @code{show
-remotedebug} will show you its current state.
-
 Other remote targets may be available in your
 configuration of GDB; use @code{help targets} to list them.
 
@@ -6887,7 +6847,7 @@ complaints from being suppressed.
 Displays how many symbol complaints _GDBN__ is permitted to produce.
 @end table
 
-By default, _GDBN__ is cautious, and asks what sometimes seem to be a
+By default, _GDBN__ is cautious, and asks what sometimes seems to be a
 lot of stupid questions to confirm certain commands.  For example, if
 you try to run a program which is already running:
 
diff --git a/gdb/doc/gdbinv-m.m4.in b/gdb/doc/gdbinv-m.m4.in
index 65e446d..181530a 100644
--- a/gdb/doc/gdbinv-m.m4.in
+++ b/gdb/doc/gdbinv-m.m4.in
@@ -2,11 +2,12 @@ _dnl__								-*- Texinfo -*-
 _dnl__ Copyright (c) 1991 Free Software Foundation, Inc.
 _dnl__ This file is part of the source for the GDB manual.
 _dnl__ M4 FRAGMENT: $Id$
+* Remote Serial::               _GDBN__ remote serial protocol
 _if__(_I960__)
-* i960-Nindy Remote::		_GDBN__ with a Remote i960 (Nindy)
+* i960-Nindy Remote::		_GDBN__ with a remote i960 (Nindy)
 _fi__(_I960__)
 _if__(_AMD29K__)
-* EB29K Remote::		_GDBN__ with a Remote EB29K
+* EB29K Remote::		_GDBN__ with a remote EB29K
 _fi__(_AMD29K__)
 _if__(_VXWORKS__)
 * VxWorks Remote::		_GDBN__ and VxWorks
diff --git a/gdb/doc/gdbinv-s.m4.in b/gdb/doc/gdbinv-s.m4.in
index 18c2aff..f2f4cef 100644
--- a/gdb/doc/gdbinv-s.m4.in
+++ b/gdb/doc/gdbinv-s.m4.in
@@ -5,6 +5,360 @@ _dnl__ M4 FRAGMENT $Id$
 _dnl__ This text diverted to "Remote Debugging" section in general case;
 _dnl__ however, if we're doing a manual specifically for one of these, it
 _dnl__ belongs up front (in "Getting In and Out" chapter).
+@node Remote Serial
+@subsection The _GDBN__ remote serial protocol
+
+@cindex remote serial debugging, overview
+To debug a program running on another machine (the debugging
+@dfn{target} machine), you must first arrange for all the usual
+prerequisites for the program to run by itself.  For example, for a C
+program, you need
+
+@enumerate
+@item
+A startup routine to set up the C runtime environment; these usually
+have a name like @file{crt0}.  The startup routine may be supplied by
+your hardware supplier, or you may have to write your own.
+
+@item 
+You probably need a C subroutine library to support your program's
+subroutine calls, notably managing input and output.
+
+@item
+A way of getting your program to the other machine---for example, a
+download program.  These are often supplied by the hardware
+manufacturer, but you may have to write your own from hardware
+documentation.
+@end enumerate
+
+The next step is to arrange for your program to use a serial port to
+communicate with the machine where _GDBN__ is running (the @dfn{host}
+machine).  In general terms, the scheme looks like this:
+
+@table @emph
+@item On the host,
+_GDBN__ already understands how to use this protocol; when everything
+else is set up, you can simply use the @samp{target remote} command
+(@pxref{Targets,,Specifying a Debugging Target}).
+
+@item On the target,
+you must link with your program a few special-purpose subroutines that
+implement the _GDBN__ remote serial protocol.  The file containing these
+subroutines is called  a @dfn{debugging stub}.
+@end table
+
+The debugging stub is specific to the architecture of the remote
+machine; for example, use @file{sparc-stub.c} to debug programs on
+@sc{sparc} boards.
+
+@cindex remote serial stub list
+These working remote stubs are distributed with _GDBN__:
+
+@c FIXME! verify these...
+@table @code
+@item sparc-stub.c
+@kindex sparc-stub.c
+For @sc{sparc} architectures.
+
+@item m68-stub.c
+@kindex m68-stub.c
+For Motorola 680x0 architectures.
+
+@item i36-stub.c
+@kindex i36-stub.c
+For Intel 386 and compatible architectures.
+@end table
+
+The @file{README} file in the _GDBN__ distribution may list other
+recently added stubs.
+
+@menu
+* 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
+@end menu
+
+@node stub contents
+@subsubsection What the stub can do for you
+
+@cindex remote serial stub
+The debugging stub for your architecture supplies these three
+subroutines:
+
+@table @code
+@item handle_exception
+@kindex handle_exception
+@cindex remote serial stub, main routine
+This is the central workhorse, but your program never calls it
+explicitly---the setup code arranges for @code{handle_exception} to
+run when a trap is triggered.
+
+@code{handle_exception} takes control when your program stops during
+execution (for example, on a breakpoint), and mediates communications
+with _GDBN__ on the host machine.  This is where the communications
+protocol is implemented; @code{handle_exception} acts as the _GDBN__
+representative on the target machine; it begins by sending summary
+information on the state of your program, then continues to execute,
+retrieving and transmitting any information _GDBN__ needs, until you
+execute a _GDBN__ command that makes your program resume; at that point,
+@code{handle_exception} returns control to your own code on the target
+machine. 
+
+@item set_debug_traps
+@kindex set_debug_traps
+@cindex remote serial stub, initialization
+You must call this subroutine explicitly near the beginning of your
+program.  This is the routine that arranges to transfer control to
+@code{handle_exception} when your program stops.
+
+@item breakpoint
+@cindex @code{breakpoint} subroutine, remote
+Use this auxiliary subroutine to make your program contain a
+breakpoint.  Depending on the particular situation, this may be the only
+way for _GDBN__ to get control.  For instance, if your target
+machine has some sort of interrupt button, you won't need to call this;
+pressing the interrupt button will transfer control to
+@code{handle_exception}---in efect, to _GDBN__.  On some machines,
+simply receiving characters on the serial port may also trigger a trap;
+again, in that situation, you don't need to call @code{breakpoint} from
+your own program---simply running @samp{target remote} from the host
+_GDBN__ session will get control.  
+
+Call @code{breakpoint} if none of these is true, or if you simply want
+to make certain your program stops at a predetermined point for the
+start of your debugging session.
+
+@quotation
+@emph{Warning:} when you set a breakpoint using this subroutine, it's a
+little harder than usual to restart your program afterwards---because if
+you simply @code{continue}, you will immediately run into the line of
+your program that sets the breakpoint!
+
+To get past this, adjust the program counter manually to get past the
+current instruction before issuing the @code{continue} command.  For example,
+
+@example
+(_GDBP__) p $pc = 4+$pc
+
+FIXME!!! Stu, I suspect I don't have this quite right.  
+         Please supply the right incantation...  presumably the
+         constant depends on instruction width, BTW?
+         Sample output would be nice too, so I don't have to make
+         up a ridiculous number.         
+
+Nothing simpler works, right?  Frinstance, an ignore count on the
+continue would just keep stopping at the same place too?
+
+Whatta bout $pc++ ---does GDB know the instruction width as a "type" size?
+
+(_GDBP__) continue
+@end example
+@end quotation
+@end table
+
+@node bootstrapping
+@subsubsection What you must do for the stub
+
+@cindex remote stub, support routines
+The debugging stubs that come with _GDBN__ are set up for a particular
+chip architecture, but they have no information about the rest of your
+debugging target machine.  To allow the stub to work, you must supply
+three special low-level subroutines, and make sure one library routine
+is available.
+
+@table @code
+@item int getDebugChar()
+@kindex getDebugChar
+Write this subroutine to read a single character from the serial port.
+It may be identical to @code{getchar} for your target system; a
+different name is used to allow you to distinguish the two if you wish.
+
+@item void putDebugChar(int)
+@kindex putDebugChar
+Write this subroutine to write a single character to the serial port.
+It may be identical to @code{putchar} for your target system; a 
+different name is used to allow you to distinguish the two if you wish.
+
+@item void flush_i_cache()
+@kindex flush_i_cache
+Write this subroutine to flush the instruction cache, if any, on your
+target machine.  If there is no instruction cache, this subroutine may
+be a no-op.
+
+On target machines that have instruction caches, _GDBN__ requires this
+function to make certain that the state of your program is stable.
+
+@item void *memset(void *, int, int)
+@kindex memset
+This is the standard library function @code{memset} that sets an area of
+memory to a known value.  If you have one of the free versions of
+@code{libc.a}, @code{memset} can be found there; otherwise, you must
+either obtain it from your hardware manufacturer, or write your own.
+@end table
+
+If you do not use the GNU C compiler, you may also need other standard
+library subroutines; this will vary from one stub to another, but in
+general the stubs are likely to use any of the common library
+subroutines which @code{gcc} generates as inline code.
+
+
+@node debug session
+@subsubsection Putting it all together
+
+@cindex remote serial debugging summary
+In summary, when your program is ready to debug, you must follow these
+steps.
+
+@enumerate
+@item
+Make sure you have the supporting low-level routines:
+@code{getDebugChar}, @code{putDebugChar}, @code{flush_i_cache},
+@code{memset}.
+
+@item
+Insert these lines near the top of your program:
+
+@example
+set_debug_traps();
+breakpoint();
+@end example
+
+@item
+Compile and link together: your program, the _GDBN__ debugging stub for
+your target architecture, and the supporting subroutines.
+
+@item
+Make sure you have a serial connection between your target machine and
+the _GDBN__ host, and identify the serial port used for this on the host.
+
+@item
+Download your program to your target machine (or get it there by
+whatever means the manufacturer provides), and start it.
+
+@item
+To start remote debugging, run _GDBN__ on the host machine, and specify
+as an executable file the program that is running in the remote machine.
+This tells _GDBN__ how to find your program's symbols and the contents
+of its pure text.
+
+Then establish communication using the @code{target remote} command.
+Its argument is the name of the device you're using to control the
+target machine.  For example:
+
+@example
+target remote /dev/ttyb
+@end example
+
+@noindent
+if the serial line is connected to the device named @file{/dev/ttyb}.  
+@ignore
+@c this is from the old text, but it doesn't seem to make sense now that I've
+@c seen an example...  pesch 4sep1992
+This will stop the remote machine if it is not already stopped.
+@end ignore
+
+@end enumerate
+
+Now you can use all the usual commands to examine and change data and to
+step and continue the remote program.
+
+To resume the remote program and stop debugging it, use the @code{detach}
+command.
+
+@node protocol
+@subsubsection Outline of the communication protocol
+
+@cindex debugging stub, example
+@cindex remote stub, example
+@cindex stub example, remote debugging
+The stub files provided with _GDBN__ implement the target side of the
+communication protocol, and the _GDBN__ side is implemented in the
+_GDBN__ source file @file{remote.c}.  Normally, you can simply allow
+these subroutines to communicate, and ignore the details.  (If you're
+implementing your own stub file, you can still ignore the details: start
+with one of the existing stub files.  @file{sparc-stub.c} is the best
+organized, and therefore the easiest to read.)
+
+However, there may be occasions when you need to know something about
+the protocol---for example, if there is only one serial port to your
+target machine, you might want your program to do something special if
+it recognizes a packet meant for _GDBN__.
+
+@cindex protocol, _GDBN__ remote serial
+@cindex serial protocol, _GDBN__ remote
+@cindex remote serial protocol
+All _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 _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 (_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 the commands currently supported:
+
+@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}.
+
+@item c
+@itemx c@var{addr}
+Resume execution at the current address (or at @var{addr} if supplied).
+
+@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
+_GDBN__ signal handling commands, one of the functions of the debugging
+stub is to report CPU traps as the corresponding POSIX signal values.
+@end table
+
+@kindex set remotedebug
+@kindex show remotedebug
+@cindex packets, reporting on stdout
+@cindex serial connections, debugging
+If you have trouble with the serial connection, you can use the command
+@code{set remotedebug}.  This makes _GDBN__ report on all packets sent
+back and forth across the serial line to the remote machine.  The
+packet-debugging information is printed on the _GDBN__ standard output
+stream.  @code{set remotedebug off} turns it off, and @code{show
+remotedebug} will show you its current state.
+
+
 _if__(_I960__)
 @node i960-Nindy Remote
 @subsection _GDBN__ with a Remote i960 (Nindy)