darkkirb/old-cross-binutils
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
first stab at updating it for "target amd-eb" rather than "attach".
(2) some minor massaging for @smallbook format.
This commit is contained in:
Roland Pesch 1991-03-27 01:22:25 +00:00
parent 94bb8edc7f
commit cb9d20492a
1 changed files with 178 additions and 156 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

334
gdb/doc/gdb.texinfo
View file

@ -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