From cb9d20492abeaa7623783227d9c522fb9a2a9255 Mon Sep 17 00:00:00 2001 From: Roland Pesch Date: Wed, 27 Mar 1991 01:22:25 +0000 Subject: [PATCH] (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. --- gdb/doc/gdb.texinfo | 334 +++++++++++++++++++++++--------------------- 1 file changed, 178 insertions(+), 156 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 95faf02401..b50904aa9f 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