(1) bring in material on 29K from 2.8.1.2 branch;

    first stab at updating it for "target amd-eb" rather than "attach".
(2) some minor massaging for @smallbook format.

1 files changed, 178 insertions, 156 deletions

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 95faf02..b50904a 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -33,11 +33,11 @@ except that the section entitled ``GNU General Public License'' may be
 included in a translation approved by the author instead of in the
 original English.
 @end ifinfo
-@c @smallbook
+@smallbook
 @setchapternewpage odd
-@settitle Using GDB (v3.94)
+@settitle Using GDB (v4.0)
 @iftex
-@finalout
+@c @finalout
 @end iftex
 @titlepage
 @title{Using GDB}
@@ -45,7 +45,7 @@ original English.
 @sp 1
 @c Maybe crank this up to "Fourth Edition" when released at FSF
 @c @subtitle Third Edition---GDB version 4.0
-@subtitle GDB version 3.94
+@subtitle GDB version 4.0
 @subtitle January 1991
 @author{Richard M. Stallman}
 @author{(Revised by Roland Pesch for Cygnus Support)}
@@ -113,6 +113,7 @@ GDB can be used to debug programs written in C and C++.  Pascal support
 is being implemented, and Fortran support will be added when a GNU
 Fortran compiler is written.
 
+@node Free Software,,,
 @unnumberedsec Free Software
 GDB is Free Software, protected by the GNU General Public License (GPL).
 The GPL gives you the freedom to copy or adapt a licensed
@@ -128,129 +129,8 @@ from anyone else.
 
 For full details, @pxref{License}.
 
-@menu
-* New Features::		New Features in GDB version 3.94
-* Invocation::			Starting GDB
-* User Interface::		GDB Commands and Displays
-* Files::			Specifying GDB's Files
-* Compilation::			Compiling Your Program for Debugging
-* Targets::			Specifying a Debugging Target 
-* Running::			Running Your Program Under GDB
-* Stopping::			Stopping and Continuing
-* Stack::			Examining the Stack
-* Source::			Examining Source Files
-* Data::			Examining Data
-* Symbols::			Examining the Symbol Table
-* Altering::			Altering Execution
-* Sequences::			Canned Sequences of Commands
-* Emacs::			Using GDB under GNU Emacs
-* Remote::			Remote Debugging
-* GDB Bugs::			Reporting Bugs in GDB
-* Installing GDB::		Installing GDB
-* License::			GNU GENERAL PUBLIC LICENSE
-* Commands::			Command Index
-* Concepts::			Index
-
- --- The Detailed Node Listing ---
-
-Starting GDB
-
-* File Options::		File-specifying Options and Arguments
-* Mode Options::		Mode Options
-* Remote i960-Nindy::		Starting GDB with a Remote Intel 960 (Nindy)
-
-Specifying a Debugging Target 
-
-* Active Targets::		Active Targets
-* Target Commands::		Commands for Managing Targets
-
-Running Your Program Under GDB
-
-* Arguments::			Specifying the arguments for your program.
-* Environment::			Specifying the environment for your program.
-* Working Directory::		Specifying the working directory for giving
-                       to your program when it is run.
-* Input/Output::		Specifying the program's standard input and output.
-* Attach::			Debugging a process started outside GDB.
-* Kill Process::		Getting rid of the child process running your program.
-
-Stopping and Continuing
-
-* Signals::			Fatal signals in your program just stop it;
-                 then you can use GDB to see what is going on.
-* Breakpoints::			Breakpoints let you stop your program when it
-                 reaches a specified point in the code.
-                 an expression changes.
-* Continuing::			Resuming execution until the next signal or breakpoint.
-* Stepping::			Stepping runs the program a short distance and
-                 then stops it wherever it has come to.
-
-Breakpoints
-
-* Set Breaks::			How to establish breakpoints.
-* Exception Handling::		How GDB supports exception handling for C++.
-* Delete Breaks::		How to remove breakpoints no longer needed.
-* Disabling::			How to disable breakpoints (turn them off temporarily).
-* Conditions::			Making extra conditions on whether to stop.
-* Break Commands::		Commands to be executed at a breakpoint.
-* Error in Breakpoints::	
-
-Examining the Stack
-
-* Frames::			Explanation of stack frames and terminology.
-* Backtrace::			Summarizing many frames at once.
-* Selection::			How to select a stack frame.
-* Frame Info::			Information on a Frame
-
-Examining Source Files
-
-* List::			Using the @samp{list} command to print source files.
-* Search::			Commands for searching source files.
-* Source Path::			Specifying the directories to search for source files.
-
-Examining Data
-
-* Expressions::			Expressions that can be computed and printed.
-* Variables::			Using your program's variables in expressions.
-* Arrays::			Examining part of memory as an array.
-* Format options::		Controlling how structures and arrays are printed.
-* Output formats::		Specifying formats for printing values.
-* Auto Display::		Printing certain expressions whenever program stops.
-* Value History::		Referring to values previously printed.
-* Convenience Vars::		Giving names to values for future reference.
-* Registers::			Referring to and storing in machine registers.
-
-Output formats
-
-* Memory::			Examining Memory
-
-Altering Execution
-
-* Assignment::			Altering variable values or memory contents.
-* Jumping::			Altering control flow.
-* Signaling::			Making signals happen in the program.
-* Returning::			Making a function return prematurely.
-* Calling::			Calling functions from your program
-
-Canned Sequences of Commands
-
-* Define::			User-defined commands.
-* Command Files::		Command files.
-* Output::			Controlled output commands useful in
-                   user-defined commands and command files.
-
-Remote Debugging
-
-* Remote Commands::		Commands used to start and finish remote debugging.
-
-Reporting Bugs in GDB
-
-* Bug Criteria::		Have You Found a Bug?
-* Bug Reporting::		How to Report Bugs
-@end menu
-
 @node New Features, Invocation, Top, Top
-@unnumbered New Features in GDB version 3.94
+@unnumbered New Features in GDB version 4.0
 
 @itemize @bullet
 @item
@@ -307,7 +187,7 @@ endian MIPS machines, Motorola 88k, Sun 386i, and Sun 3 running SunOS
 29k, Intel 960, and Wind River's VxWorks.
 
 @item
-SHARED LIBRARIES: GDB 3.94 supports SunOS shared libraries.
+SHARED LIBRARIES: GDB 4.0 supports SunOS shared libraries.
 
 @item
 WORK IN PROGRESS: kernel debugging for BSD and Mach systems; Tahoe and
@@ -332,27 +212,20 @@ or you can start with both an executable program and a core file specified:
 gdb program core
 @end example
 
-You can get more detailed control over how GDB starts up using a number
-of command-line options.
+You can get more detailed control over how GDB starts up using some of
+the command-line options.
 
 All the options and command line arguments given are processed
 in sequential order.  The order makes a difference when the
 @samp{-x} option is used.  
 
-@menu
-* File Options::		File-specifying Options and Arguments
-* Mode Options::		Mode Options
-* Remote i960-Nindy::		Starting GDB with a Remote Intel 960 (Nindy)
-@end menu
-
 @node File Options, Mode Options, Invocation, Invocation
 @section File-specifying Options and Arguments
 
-As shown in the example, any arguments other
-than options specify an executable file and core file; that is, the
-first argument encountered with no associated option flag is equivalent
-to a @samp{-se} option, and the second, if any, is equivalent to a
-@samp{-c} option.
+As shown above, any arguments other than options specify an executable
+file and core file; that is, the first argument encountered with no
+associated option flag is equivalent to a @samp{-se} option, and the
+second, if any, is equivalent to a @samp{-c} option.
 
 @table @code
 @item -s @var{file}
@@ -423,8 +296,8 @@ Set the line speed (baud rate or bps) of any serial interface used by
 GDB for remote debugging.
 @end table
 
-@node Remote i960-Nindy,  , Mode Options, Invocation
-@section Starting GDB with a Remote Intel 960 (Nindy)
+@node i960-Nindy Remote,,,
+@section GDB with a Remote Intel 960 (Nindy)
 
 ``Nindy'' is the name of a Rom Monitor program for Intel 960 target
 systems.  When GDB is configured to control a remote Intel 960 using
@@ -494,6 +367,144 @@ requires; it only works with a few boards.
 The standard @samp{-b} option controls the line speed used on the serial
 port. 
 
+@node AMD29K Remote,,,
+@section Starting GDB with a Remote AMD 29K
+
+@cindex EB29K board
+@cindex running 29K programs
+@cindex 29K
+
+To use GDB from a Unix system to run programs on an EB29K
+board in a PC, you must first connect a serial cable between the PC
+and a serial port on the Unix system.  In the following, we assume
+you've hooked the cable between the PC's @samp{COM1} port and
+@samp{/dev/ttya} on the Unix system.
+
+@node PC Comms (EB29K),,,
+@subsection PC Communications Setup
+The next step is to set up the PC's port, by doing something like the
+following in DOS on the PC:
+@example
+C> MODE com1:9600,n,8,1,none
+@end example
+@noindent
+This example---run on an MS DOS 4.0 system---sets the PC port to 9600
+bps, no parity, eight data bits, one stop bit, and no ``retry'' action;
+you must match the communications parameters when establishing the Unix
+end of the connection as well.
+@c FIXME: Who knows what this "no retry action" crud from the DOS manual may
+@c       mean?  It's optional; leave it out? ---pesch@cygnus.com, 25feb91 
+
+To give control of the PC to the Unix side of the serial line, type
+the following at the DOS console:
+@example
+C> CTTY com1
+@end example
+@noindent
+(Later, if you wish to return control to the DOS console, you can use
+the command @samp{CTTY con}---but you must send it over the device that
+had control, in our example over the @samp{com1} serial line).
+
+@node Unix Comms (EB29K),,,
+@subsection Unix Communications Setup
+From the Unix host, use a communications program such as @code{tip} or
+@code{cu} to communicate with the PC; for example,
+@example
+cu -s 9600 -l /dev/ttya
+@end example
+@noindent
+The @code{cu} options shown specify, respectively, the linespeed and the
+serial port to use.  If you use @code{tip} instead, the corresponding
+parameters must be entered in the ``remote'' descriptions file used by
+@code{tip}---normally the system table @file{/etc/remote}.
+@c FIXME: What if anything needs doing to match the "n,8,1,none" part of
+@c the DOS side's comms setup?  cu can support -o (odd
+@c parity), -e (even parity)---apparently no settings for no parity or
+@c for character size.  Taken from stty maybe...?  John points out tip
+@c can set these as internal variables, eg ~s parity=none; man stty
+@c suggests that it *might* work to stty these options with stdin or
+@c stdout redirected... is it worth experimenting?  Maybe if the literal
+@c combinations of things typed here don't work? ---pesch@cygnus.com, 25feb91
+
+@node EBMON,,,
+@subsection Using EBMON
+@kindex EBMON
+Using the @samp{tip} or @samp{cu} connection, change the DOS working
+directory to the directory containing a copy of your 29K program, then
+start the PC program @samp{EBMON} (an EB29K control program supplied
+with your board by AMD):
+@example
+C> CD g:\usr\joe\work29k
+C> EBMON
+@end example
+@c FIXME: insert EBMON banner display here.  ---pesch@cygnus.com, 25feb91
+
+Then close the @code{cu} or @code{tip} connection (by typing @samp{~.}
+for example).  @code{EBMON} will keep running, ready for GDB to take
+over.
+
+@node 29K Program,,,
+@subsection Your 29K Program
+For this example, we've assumed what is probably the most convenient
+way to make sure the same 29K program is on both the PC and the Unix
+system: a PC/NFS connection that establishes ``drive'' @code{g:} on the
+PC as a file system on the Unix host.  If you don't have PC/NFS or
+something similar connecting the two systems, you must arrange some
+other way---perhaps floppy-disk transfer---of getting the 29K program
+from the Unix system to the PC; GDB will @emph{not} download it over the
+serial line.
+
+@node gdb-EB29K
+@subsection EB29K cross-debugging
+Finally, @code{cd} to the directory containing an image of your 29K
+program on the Unix system, and start GDB---specifying as argument the
+name of your 29K program:
+@example
+cd /usr/joe/work29k
+gdb myfoo
+@end example
+Now you can use the @code{target} command:
+@example
+target amd-eb /dev/ttya 9600 MYFOO
+@end example
+@c FIXME: test above 'target amd-eb' as spelled, with caps!  caps are meant to
+@c emphasize that this is the name as seen by DOS (since I think DOS is
+@c single-minded about case of letters).  ---pesch@cygnus.com, 25feb91
+
+@noindent
+In this example, we've assumed your program is in a file called
+@samp{myfoo}.  Note that the filename given as the last argument to
+@samp{target amd-eb} should be the name of the program as it appears to DOS.
+In our example it is simply @samp{MYFOO}, but in general it can include
+a DOS path, and depending on your transfer mechanism may not resemble
+the name on the Unix side.
+
+At this point, you can set any breakpoints you wish; when you're ready
+to see your program run on the 29K board, use the GDB command
+@example
+run
+@end example
+
+To stop debugging the remote program, use the GDB @samp{detach}
+command.  
+
+To return control of the PC to its console, use @code{tip} or @code{cu}
+once again, after your GDB session has concluded, to attach to
+@code{EBMON}.  You can then type the command @samp{q} to shut down
+@code{EBMON}, returning control to the DOS command-line interpreter.
+Type @samp{CTTY con} to return command input to the main DOS console,
+and type @samp{~.} to leave @code{tip} or @code{cu}.
+
+@node Remote Log,  , Remote Commands, Remote
+@subsection Remote Log
+@kindex eb.log
+@cindex log file for EB29K
+The GDB @code{target amd-eb} command creates a file @file{eb.log} in the
+current working directory, to help debug problems with the connection.
+@file{eb.log} records all the output from @code{EBMON}, including echoes
+of the commands sent to it.  Running @samp{tail -f} on this file in
+another window often helps to debug trouble with @code{EBMON}, or
+unexpected events on the PC side of the connection.
 
 @node User Interface, Files, Invocation, Top
 @chapter GDB Commands and Displays
@@ -1103,7 +1114,7 @@ Print the names of the shared libraries which are currently loaded.
 
 
 @node Compilation, Targets, Files, Top
-@chapter Compiling Your Program for Debugging
+@chapter Compiling for Debugging
 
 In order to debug a program effectively, you need to ask for debugging
 information when you compile it.  This debugging information is stored
@@ -1156,7 +1167,7 @@ A @dfn{target} is an interface between the debugger and a particular
 kind of file or process.  
 
 Often, you will be able to run GDB in the same host environment as the
-program you are debugging; in that case, the debugging target is
+program you are debugging; in that case, the debugging target can just be
 specified as a side effect of the @samp{file} or @samp{core} commands.
 When you need more flexibility---for example, running GDB on a
 physically separate host, controlling standalone systems over a
@@ -1228,12 +1239,6 @@ Here are some common targets (available, or not, depending on GDB
 configuration):
 
 @table @code
-@item target remote @var{dev}
-@kindex target remote
-Remote serial target in gdb-specific protocol.  The argument @var{dev}
-specifies what serial device to use for the connection (e.g.
-@code{/dev/ttya}).
-
 @item target exec @var{prog}
 @kindex target exec
 An executable file.  @samp{target exec @var{prog}} is the same as
@@ -1244,6 +1249,21 @@ An executable file.  @samp{target exec @var{prog}} is the same as
 A core dump file.  @samp{target core @var{filename}} is the same as
 @samp{core-file @var{filename}}.
 
+@item target remote @var{dev}
+@kindex target remote
+Remote serial target in gdb-specific protocol.  The argument @var{dev}
+specifies what serial device to use for the connection (e.g.
+@code{/dev/ttya}).
+
+@item target amd-eb @var{dev} @var{speed} @var{PROG}
+@kindex target amd-eb
+@cindex AMD EB29K
+Remote PC-resident AMD EB29K board, attached over serial lines.
+@var{dev} is the serial device, as for @samp{target remote};
+@samp{speed} allows you to specify the linespeed; and @var{PROG} is the
+name of the program to be debugged, as it appears to DOS on the PC.
+@xref{AMD29K Remote}.
+
 @item target nindy @var{devicename}
 @kindex target nindy
 An Intel 960 board controlled by a Nindy Monitor.  @var{devicename} is
@@ -1261,7 +1281,7 @@ Different targets are available on different configurations of GDB; your
 configuration may have more or fewer targets.
 
 @node Running, Stopping, Targets, Top
-@chapter Running Your Program Under GDB
+@chapter Running Programs Under GDB
 
 @cindex running
 @kindex run
@@ -1785,7 +1805,7 @@ program.  There is nothing silly or meaningless about this.  When the
 breakpoints are conditional, this is even useful (@pxref{Conditions}).
 
 @node Exception Handling, Delete Breaks, Set Breaks, Breakpoints
-@subsection Breakpoints and Exception Handling
+@subsection Breakpoints and Exceptions
 @cindex exception handlers
 
 Some languages, such as GNU C++, implement exception handling.  GDB
@@ -1846,8 +1866,8 @@ You cannot interactively install an exception handler.
 @node Delete Breaks, Disabling, Exception Handling, Breakpoints
 @subsection Deleting Breakpoints
 
-@cindex clearing breakpoints and watchpoints
-@cindex deleting breakpoints and watchpoints
+@cindex clearing breakpoints, watchpoints
+@cindex deleting breakpoints, watchpoints
 It is often necessary to eliminate a breakpoint once it has done its job
 and you no longer want the program to stop there.  This is called
 @dfn{deleting} the breakpoint.  A breakpoint that has been deleted no
@@ -2147,8 +2167,10 @@ nontrivial conditions for performing the side effects, the operators
 @samp{&&}, @samp{||} and @samp{?@dots{}:} may be useful.
 
 @node Error in Breakpoints,  , Break Commands, Breakpoints
-@subsection ``Cannot Insert Breakpoints'' Error
+@subsection ``Cannot Insert Breakpoints''
 
+@c FIXME: "cannot insert breakpoints" error, v unclear.  
+@c        Q in pending mail to Gilmore. ---pesch@cygnus.com, 26mar91
 Under some operating systems, breakpoints cannot be used in a program if
 any other process is running that program.  In this situation,
 attempting to run or continue a program with a breakpoint will cause GDB
@@ -4815,7 +4837,7 @@ ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
 @end ifinfo
 
 @page
-@unnumberedsec How to Apply These Terms to Your New Programs
+@unnumberedsec Applying These Terms to Your New Programs
 
   If you develop a new program, and you want it to be of the greatest
 possible use to humanity, the best way to achieve this is to make it