OpenE2K/binutils-gdb
12
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

* gdb.texinfo (New Features): mention threads.

Browse Source 
(Summary, C): fix xrefs in newly contributed text.
	(Threads): index entries, clarifications, example
	(passim): minor typos fixed, phrasing improvements

	* remote.texi (Bootstrapping): rephrase text on ^C and add index
	entries; (Server): explain use of gdbserver w/real-time systems,
	add example of conflicting TCP port; (MIPS Remote) break up
	running text into table, highlighting commands, and add example.
This commit is contained in:
Roland Pesch 1993-11-29 02:43:47 +00:00
parent 6e4eda3368
commit 22b5dba55e
3 changed files with 156 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
gdb/doc/ChangeLog
View File

@ -1,3 +1,19 @@
Sun Nov 28 18:06:25 1993 Roland H. Pesch (pesch@fowanton.cygnus.com)
* gdb.texinfo (New Features): mention threads.
(Summary, C): fix xrefs in newly contributed text.
(Threads): index entries, clarifications, example
(passim): minor typos fixed, phrasing improvements
* remote.texi (Bootstrapping): rephrase text on ^C and add index
entries; (Server): explain use of gdbserver w/real-time systems,
add example of conflicting TCP port; (MIPS Remote) break up
running text into table, highlighting commands, and add example.
Wed Nov 24 14:15:56 1993 Roland H. Pesch (pesch@fowanton.cygnus.com)
* refcard.tex: avoid bad linebreaks even when REFEDITS=psrc.sed
Fri Nov 12 16:10:58 1993 Jim Kingdon (kingdon@lioth.cygnus.com)
* stabs.texinfo (Nested Symbols): New node.

90
gdb/doc/gdb.texinfo
View File

@ -209,19 +209,16 @@ effects of one bug and go on to learn about another.
@ifclear CONLY
You can use @value{GDBN} to debug programs written in C or C++. For
more information, @xref{C}.
more information, see @ref{C,,C and C++}.
@ifset MOD2
@c I use "MOD2" as a "miscellaneous languages" flag here. According to
@c a comment in all-cfg.texi, there should be separate flags for chill
@c and Pascal, but that seems kind of silly since we only mention them
@c in passing--IMHO the manual should be configurable as little as we
@c can get away with -kingdon.
@c "MOD2" used as a "miscellaneous languages" flag here.
@c This is acceptable while there is no real doc for Chill and Pascal.
Support for Modula-2 and Chill is partial. For information on Modula-2,
@xref{Modula-2}; there is no further documentation on Chill yet.
see @ref{Modula-2,,Modula-2}; there is no further documentation on Chill yet.
Pascal programs which use sets, subranges, file variables, or nested
functions will not currently work. @value{GDBN} does not support
Debugging pascal programs which use sets, subranges, file variables, or nested
functions does not currently work. @value{GDBN} does not support
entering expressions, printing values, etc. using Pascal syntax.
@end ifset
@ifset FORTRAN
@ -418,6 +415,9 @@ of your program, and the latter refer to the state of GDB itself.
GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
shared libraries.
@item Threads
On some systems, GDB 4 has facilities to debug multi-thread programs.
@item Reference Card
GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
the Documentation}, for instructions about how to print it.
@ -1828,7 +1828,7 @@ address space (that is, they can all examine and modify the same
variables). On the other hand, each thread has its own registers and
execution stack, and perhaps private memory.
@value{GDBN} provides several facilities for debugging multi-thread
@value{GDBN} provides these facilities for debugging multi-thread
programs:
@itemize @bullet
@ -1870,10 +1870,10 @@ program information from the perspective of the current thread.
@c included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'.
Whenever @value{GDBN} detects a new thread in your program, it displays
the system's identification for it with a message in the form @samp{[New
@var{systag}]}. @var{systag} is a thread identifier whose form varies
depending on the particular system. For example, on LynxOS, you might
see
the target system's identification for the thread with a message in the
form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
whose form varies depending on the particular system. For example, on
LynxOS, you might see
@example
[New process 35 thread 27]
@ -1904,9 +1904,9 @@ Display a summary of all threads currently in your
program. @value{GDBN} displays for each thread (in this order):
@enumerate
@item the @value{GDBN} thread number
@item the thread number assigned by @value{GDBN}
@item the system's @var{systag} thread identifier
@item the target system's thread identifier (@var{systag})
@item the current stack frame summary for that thread
@end enumerate
@ -1929,6 +1929,7 @@ For example,
@table @code
@item thread @var{threadno}
@kindex thread @var{threadno}
Make thread number @var{threadno} the current thread. The command
argument @var{threadno} is the internal @value{GDBN} thread number, as
shown in the first field of the @samp{info threads} display.
@ -1960,6 +1961,9 @@ thread.
@xref{Thread Stops,,Stopping and starting multi-thread programs}, for
more information about how @value{GDBN} behaves when you stop and start
programs with multiple threads.
@xref{Set Watchpoints,,Setting watchpoints}, for information about
watchpoints in programs with multiple threads.
@end ifclear
@node Stopping
@ -3045,23 +3049,28 @@ programs with multiple threads}), you can choose whether to set
breakpoints on all threads, or on a particular thread.
@table @code
@cindex br
@cindex breakpoints and threads
@cindex thread breakpoints
@kindex break @dots{} thread @var{threadno}
@item break @var{linespec} thread @var{threadno}
@itemx break @var{linespec} thread @var{threadno} if @dots{}
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command
to specify that you only want @value{GDBN} to stop the program when a
particular thread reaches this breakpoint. @var{threadno} is one of
GDB's numeric thread identifiers, shown in the first column of
the @samp{info threads} display.
You can use the @code{thread} qualifier on conditional breakpoints as
well; in this case, place @samp{thread @var{threadno}} before the
breakpoint condition.
particular thread reaches this breakpoint. @var{threadno} is one of the
numeric thread identifiers assigned by @value{GDBN}, shown in the first
column of the @samp{info threads} display.
If you do not specify @samp{thread @var{threadno}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your
program.
You can use the @code{thread} qualifier on conditional breakpoints as
well; in this case, place @samp{thread @var{threadno}} before the
breakpoint condition, like this:
@smallexample
(gdb) break frik.c:13 thread 28 if bartab > lim
@end smallexample
@end table
@cindex stopped threads
@ -3079,11 +3088,12 @@ executing. @emph{This is true even when single-stepping} with commands
like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your host operating system, rather than
controlled by @value{GDBN}, other threads may execute more than one
statement while the current thread completes a single step.
Moreover, in general other threads stop in the middle of a statement,
rather than at a clean statement boundary, when the program stops.
Since thread scheduling is up to your debugging target's operating
system (not controlled by @value{GDBN}), other threads may
execute more than one statement while the current thread completes a
single step. Moreover, in general other threads stop in the middle of a
statement, rather than at a clean statement boundary, when the program
stops.
You might even find your program stopped in another thread after
continuing or even single-stepping. This happens whenever some other
@ -5242,14 +5252,15 @@ together.
@kindex g++
@cindex GNU C++
The C++ debugging facilities are jointly implemented by the GNU C++
compiler and @value{GDBN}. Therefore, to debug your C++ code effectively,
you must compile your C++ programs with the GNU C++ compiler,
@code{g++}. Also, you must be using the stabs debugging format; see the
documentation for the GNU C++ compiler for more information on how to
select that format.
compiler and @value{GDBN}. Therefore, to debug your C++ code
effectively, you must compile your C++ programs with the GNU C++
compiler, @code{g++}.
In particular, cfront based compilers such as Sun's C++ are not fully
supported.
For best results when debugging C++ programs, use the stabs debugging
format. You can select that format explicitly with the @code{g++}
command-line options @samp{-gstabs} or @samp{-gstabs+}. See
@ref{Debugging Options,,Options for Debugging Your Program or GNU CC,
gcc.info, Using GNU CC}, for more information.
@end ifclear
@ifset CONLY
@node C
@ -6821,9 +6832,10 @@ target is @dots{}}''
@end ifset
The file is loaded at whatever address is specified in the executable.
For some object file formats, like a.out, the object file format fixes
the address and so it won't necessarily match the address you gave to
the linker.
For some object file formats, you can specify the load address when you
link the program; for other formats, like a.out, the object file format
specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
@ifset VXWORKS
On VxWorks, @code{load} will dynamically link @var{filename} on the

128
gdb/doc/remote.texi
View File

@ -168,14 +168,18 @@ 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.
@end table
@cindex control C, and remote debugging
@cindex interrupting remote targets
If you want @value{GDBN} to be able to stop your program while it is
running, you need to use an interrupt-driven serial driver, and arrange
for it to stop when it receives a control C character (getting it to
return the proper status to GDB probably requires changes to the
standard stub; one quick and dirty way is to just execute a breakpoint
instruction. @value{GDBN} will return a SIGTRAP instead of a SIGINT).
That is the character which @value{GDBN} uses to tell the remote system
to stop.
for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
character). That is the character which @value{GDBN} uses to tell the
remote system to stop.
Getting the debugging target to return the proper status to @value{GDBN}
probably requires changes to the standard stub; one quick and dirty way
is to just execute a breakpoint instruction (the ``dirty'' part is that
@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}).
Other routines you need to supply are:
@ -444,19 +448,24 @@ that @value{GDBN} itself does. In fact, a system that can run
because it is a much smaller program than @value{GDBN} itself. It is
also easier to port than all of @value{GDBN}, so you may be able to get
started more quickly on a new system by using @code{gdbserver}.
Finally, if you develop code for real-time systems, you may find that
the tradeoffs involved in real-time operation make it more convenient to
do as much development work as possible on another system, for example
by cross-compiling. You can use @code{gdbserver} to make a similar
choice for debugging.
@value{GDBN} and @code{gdbserver} communicate via either a serial line
or a TCP connection, using the standard @value{GDBN} remote serial
protocol.
@table @emph
@item On the target,
@item On the target machine,
you need to have a copy of the program you want to debug.
@code{gdbserver} does not need your program's symbol table, so you can
strip the program if necessary to save space. @value{GDBN} on the host
system does all the symbol handling.
To use the server, you must tell it how to communicate with @value{GDB};
To use the server, you must tell it how to communicate with @value{GDBN};
the name of your program; and the arguments for your program. The
syntax is:
@ -465,7 +474,7 @@ target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
@end smallexample
@var{comm} is either a device name (to use a serial line) or a TCP
hostname and portnumber. For example, to debug emacs with the argument
hostname and portnumber. For example, to debug Emacs with the argument
@samp{foo.txt} and communicate with @value{GDBN} over the serial port
@file{/dev/com1}:
@ -488,20 +497,22 @@ TCP. The @samp{host:2345} argument means that @code{gdbserver} is to
expect a TCP connection from machine @samp{host} to local TCP port 2345.
(Currently, the @samp{host} part is ignored.) You can choose any number
you want for the port number as long as it does not conflict with any
TCP ports already in use on the target system.@footnote{If you choose a
port number that conflicts with another service, @code{gdbserver} prints
an error message and exits.} You must use the same port number with the
host @value{GDBN} @code{target remote} command.
TCP ports already in use on the target system (for example, @code{23} is
reserved for @code{telnet}).@footnote{If you choose a port number that
conflicts with another service, @code{gdbserver} prints an error message
and exits.} You must use the same port number with the host @value{GDBN}
@code{target remote} command.
@item On the host,
you need an unstripped copy of your program, since
@value{GDBN} needs symbols and debugging information. Start up
@value{GDBN} as usual, using the name of the local copy of your program
as the first argument. (You may also need the
@samp{--baud} option if the serial line is running at anything other than 9600 bps.)
After that, use @code{target remote} to establish communications with @code{gdbserver}. Its argument is either
a device name (usually a serial device, like @file{/dev/ttyb}), or a TCP
port descriptof in the form @code{@var{host}:@var{PORT}}. For example:
@item On the @value{GDBN} host machine,
you need an unstripped copy of your program, since @value{GDBN} needs
symbols and debugging information. Start up @value{GDBN} as usual,
using the name of the local copy of your program as the first argument.
(You may also need the @w{@samp{--baud}} option if the serial line is
running at anything other than 9600 bps.) After that, use @code{target
remote} to establish communications with @code{gdbserver}. Its argument
is either a device name (usually a serial device, like
@file{/dev/ttyb}), or a TCP port descriptor in the form
@code{@var{host}:@var{PORT}}. For example:
@smallexample
(@value{GDBP}) target remote /dev/ttyb
@ -515,7 +526,7 @@ communicates with the server via serial line @file{/dev/ttyb}, and
@end smallexample
@noindent
communicates via a TCP connection to port 2345 on host @file{the-target}.
communicates via a TCP connection to port 2345 on host @w{@file{the-target}}.
For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like
@ -1177,6 +1188,11 @@ development board as a ``normal exit'' of your program.
MIPS board attached to a serial line. This is available when
you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}.
@noindent
Use these @value{GDBN} commands to specify the connection to your target board:
@table @code
@item target mips @var{port}
@kindex target mips @var{port}
To run a program on the board, start up @code{@value{GDBP}} with the
name of your program as the argument. To connect to the board, use the
@ -1185,19 +1201,62 @@ the serial port connected to the board. If the program has not already
been downloaded to the board, you may use the @code{load} command to
download it. You can then use all the usual @value{GDBN} commands.
You can also specify @var{port} as a TCP connection (for instance, to a
serial line managed by a terminal concentrator), using the syntax
@code{@var{hostname}:@var{portnumber}}.
For example, this sequence connects to the target board through a serial
port, and loads and runs a program called @var{prog} through the
debugger:
@example
host$ @value{GDBP} @var{prog}
GDB is free software and @dots{}
(gdb) target mips /dev/ttyb
(gdb) load @var{prog}
(gdb) run
@end example
@item target mips @var{hostname}:@var{portnumber}
On some @value{GDBN} host configurations, you can specify a TCP
connection (for instance, to a serial line managed by a terminal
concentrator) instead of a serial port, using the syntax
@samp{@var{hostname}:@var{portnumber}}.
@end table
@noindent
@value{GDBN} also supports these special commands for MIPS targets:
@table @code
@item set mipsfpu off
@itemx show mipsfpu
@kindex set mipsfpu off
@kindex show mipsfpu
@cindex MIPS remote floating point
@cindex floating point, MIPS remote
If your target board does not support the MIPS floating point
coprocessor, you should use the command @samp{set mipsfpu off} (if you
need this, you may wish to put the command in your @value{GDBINIT}
file). This tells @value{GDBN} how to find the return value of
functions which return floating point values. It also allows
@value{GDBN} to avoid saving the floating point registers when calling
functions on the board. (As usual, you can inquire about the
@code{mipsfpu} variable with @samp{show mipsfpu}.)
@item set remotedebug @var{n}
@itemx show remotedebug
@kindex set remotedebug
@kindex show remotedebug
@cindex @code{remotedebug}, MIPS protocol
@cindex MIPS @code{remotedebug} protocol
@c FIXME! For this to be useful, you must know something about the MIPS
@c FIXME...protocol. Where is it described?
You can see some debugging information about communications with the board
by setting the @code{remotedebug} variable. If you set it to 1 using
@samp{set remotedebug 1} every packet will be displayed. If you set it
to 2 every character will be displayed. You can check the current value
by setting the @code{remotedebug} variable. If you set it to @code{1} using
@samp{set remotedebug 1}, every packet is displayed. If you set it
to @code{2}, every character is displayed. You can check the current value
at any time with the command @samp{show remotedebug}.
@item set timeout @var{seconds}
@itemx set retransmit-timeout @var{seconds}
@itemx show timeout
@itemx show retransmit-timeout
@cindex @code{timeout}, MIPS protocol
@cindex @code{retransmit-timeout}, MIPS protocol
@kindex set timeout
@ -1212,16 +1271,7 @@ retransmit-timeout @var{seconds}} command. The default is 3 seconds.
You can inspect both values with @code{show timeout} and @code{show
retransmit-timeout}. (These commands are @emph{only} available when
@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
@kindex set mipsfpu off
@cindex MIPS remote floating point
@cindex floating point, MIPS remote
If your target board does not support the MIPS floating point
coprocessor, you should use the command @samp{set mipsfpu off} (you may
wish to put this in your @value{GDBINIT} file). This tells @value{GDBN}
how to find the return value of functions which return floating point
values. It also allows @value{GDBN} to avoid saving the floating point
registers when calling functions on the board.
@end table
@end ifset
@ifset SIMS