espressif/binutils-gdb
1
0
Fork 0
mirror of https://github.com/espressif/binutils-gdb.git synced 2025-06-23 03:29:47 +08:00
Code Issues Packages Projects 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
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) Fri Nov 12 16:10:58 1993 Jim Kingdon (kingdon@lioth.cygnus.com)
* stabs.texinfo (Nested Symbols): New node. * 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 @ifclear CONLY
You can use @value{GDBN} to debug programs written in C or C++. For 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 @ifset MOD2
@c I use "MOD2" as a "miscellaneous languages" flag here. According to @c "MOD2" used as a "miscellaneous languages" flag here.
@c a comment in all-cfg.texi, there should be separate flags for chill @c This is acceptable while there is no real doc for Chill and Pascal.
@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.
Support for Modula-2 and Chill is partial. For information on Modula-2, 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 Debugging pascal programs which use sets, subranges, file variables, or nested
functions will not currently work. @value{GDBN} does not support functions does not currently work. @value{GDBN} does not support
entering expressions, printing values, etc. using Pascal syntax. entering expressions, printing values, etc. using Pascal syntax.
@end ifset @end ifset
@ifset FORTRAN @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 GDB 4 can debug programs and core files that use SunOS, SVR4, or IBM RS/6000
shared libraries. shared libraries.
@item Threads
On some systems, GDB 4 has facilities to debug multi-thread programs.
@item Reference Card @item Reference Card
GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting GDB 4 has a reference card. @xref{Formatting Documentation,,Formatting
the Documentation}, for instructions about how to print it. 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 variables). On the other hand, each thread has its own registers and
execution stack, and perhaps private memory. 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: programs:
@itemize @bullet @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 included GDB's numeric thread handle, so you could just go to that
@c thread without first checking `info threads'. @c thread without first checking `info threads'.
Whenever @value{GDBN} detects a new thread in your program, it displays 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 the target system's identification for the thread with a message in the
@var{systag}]}. @var{systag} is a thread identifier whose form varies form @samp{[New @var{systag}]}. @var{systag} is a thread identifier
depending on the particular system. For example, on LynxOS, you might whose form varies depending on the particular system. For example, on
see LynxOS, you might see
@example @example
[New process 35 thread 27] [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): program. @value{GDBN} displays for each thread (in this order):
@enumerate @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 @item the current stack frame summary for that thread
@end enumerate @end enumerate
@ -1929,6 +1929,7 @@ For example,
@table @code @table @code
@item thread @var{threadno} @item thread @var{threadno}
@kindex thread @var{threadno}
Make thread number @var{threadno} the current thread. The command Make thread number @var{threadno} the current thread. The command
argument @var{threadno} is the internal @value{GDBN} thread number, as argument @var{threadno} is the internal @value{GDBN} thread number, as
shown in the first field of the @samp{info threads} display. 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 @xref{Thread Stops,,Stopping and starting multi-thread programs}, for
more information about how @value{GDBN} behaves when you stop and start more information about how @value{GDBN} behaves when you stop and start
programs with multiple threads. programs with multiple threads.
@xref{Set Watchpoints,,Setting watchpoints}, for information about
watchpoints in programs with multiple threads.
@end ifclear @end ifclear
@node Stopping @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. breakpoints on all threads, or on a particular thread.
@table @code @table @code
@cindex br @cindex breakpoints and threads
@cindex thread breakpoints
@kindex break @dots{} thread @var{threadno} @kindex break @dots{} thread @var{threadno}
@item break @var{linespec} thread @var{threadno} @item break @var{linespec} thread @var{threadno}
@itemx break @var{linespec} thread @var{threadno} if @dots{} @itemx break @var{linespec} thread @var{threadno} if @dots{}
Use the qualifier @samp{thread @var{threadno}} with a breakpoint command 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 to specify that you only want @value{GDBN} to stop the program when a
particular thread reaches this breakpoint. @var{threadno} is one of particular thread reaches this breakpoint. @var{threadno} is one of the
GDB's numeric thread identifiers, shown in the first column of numeric thread identifiers assigned by @value{GDBN}, shown in the first
the @samp{info threads} display. 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.
If you do not specify @samp{thread @var{threadno}} when you set a If you do not specify @samp{thread @var{threadno}} when you set a
breakpoint, the breakpoint applies to @emph{all} threads of your breakpoint, the breakpoint applies to @emph{all} threads of your
program. 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 @end table
@cindex stopped threads @cindex stopped threads
@ -3079,11 +3088,12 @@ executing. @emph{This is true even when single-stepping} with commands
like @code{step} or @code{next}. like @code{step} or @code{next}.
In particular, @value{GDBN} cannot single-step all threads in lockstep. In particular, @value{GDBN} cannot single-step all threads in lockstep.
Since thread scheduling is up to your host operating system, rather than Since thread scheduling is up to your debugging target's operating
controlled by @value{GDBN}, other threads may execute more than one system (not controlled by @value{GDBN}), other threads may
statement while the current thread completes a single step. execute more than one statement while the current thread completes a
Moreover, in general other threads stop in the middle of a statement, single step. Moreover, in general other threads stop in the middle of a
rather than at a clean statement boundary, when the program stops. statement, rather than at a clean statement boundary, when the program
stops.
You might even find your program stopped in another thread after You might even find your program stopped in another thread after
continuing or even single-stepping. This happens whenever some other continuing or even single-stepping. This happens whenever some other
@ -5242,14 +5252,15 @@ together.
@kindex g++ @kindex g++
@cindex GNU C++ @cindex GNU C++
The C++ debugging facilities are jointly implemented by the GNU C++ The C++ debugging facilities are jointly implemented by the GNU C++
compiler and @value{GDBN}. Therefore, to debug your C++ code effectively, compiler and @value{GDBN}. Therefore, to debug your C++ code
you must compile your C++ programs with the GNU C++ compiler, effectively, you must compile your C++ programs with the GNU C++
@code{g++}. Also, you must be using the stabs debugging format; see the compiler, @code{g++}.
documentation for the GNU C++ compiler for more information on how to
select that format.
In particular, cfront based compilers such as Sun's C++ are not fully For best results when debugging C++ programs, use the stabs debugging
supported. 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 @end ifclear
@ifset CONLY @ifset CONLY
@node C @node C
@ -6821,9 +6832,10 @@ target is @dots{}}''
@end ifset @end ifset
The file is loaded at whatever address is specified in the executable. 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 For some object file formats, you can specify the load address when you
the address and so it won't necessarily match the address you gave to link the program; for other formats, like a.out, the object file format
the linker. specifies a fixed address.
@c FIXME! This would be a good place for an xref to the GNU linker doc.
@ifset VXWORKS @ifset VXWORKS
On VxWorks, @code{load} will dynamically link @var{filename} on the 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. different name is used to allow you to distinguish the two if you wish.
@end table @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 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 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 for it to stop when it receives a @code{^C} (@samp{\003}, the control-C
return the proper status to GDB probably requires changes to the character). That is the character which @value{GDBN} uses to tell the
standard stub; one quick and dirty way is to just execute a breakpoint remote system to stop.
instruction. @value{GDBN} will return a SIGTRAP instead of a SIGINT).
That is the character which @value{GDBN} uses to tell the remote system Getting the debugging target to return the proper status to @value{GDBN}
to stop. 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: 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 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 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}. 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 @value{GDBN} and @code{gdbserver} communicate via either a serial line
or a TCP connection, using the standard @value{GDBN} remote serial or a TCP connection, using the standard @value{GDBN} remote serial
protocol. protocol.
@table @emph @table @emph
@item On the target, @item On the target machine,
you need to have a copy of the program you want to debug. 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 @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 strip the program if necessary to save space. @value{GDBN} on the host
system does all the symbol handling. 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 the name of your program; and the arguments for your program. The
syntax is: syntax is:
@ -465,7 +474,7 @@ target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ]
@end smallexample @end smallexample
@var{comm} is either a device name (to use a serial line) or a TCP @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 @samp{foo.txt} and communicate with @value{GDBN} over the serial port
@file{/dev/com1}: @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. 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 (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 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 TCP ports already in use on the target system (for example, @code{23} is
port number that conflicts with another service, @code{gdbserver} prints reserved for @code{telnet}).@footnote{If you choose a port number that
an error message and exits.} You must use the same port number with the conflicts with another service, @code{gdbserver} prints an error message
host @value{GDBN} @code{target remote} command. and exits.} You must use the same port number with the host @value{GDBN}
@code{target remote} command.
@item On the host, @item On the @value{GDBN} host machine,
you need an unstripped copy of your program, since you need an unstripped copy of your program, since @value{GDBN} needs
@value{GDBN} needs symbols and debugging information. Start up symbols and debugging information. Start up @value{GDBN} as usual,
@value{GDBN} as usual, using the name of the local copy of your program using the name of the local copy of your program as the first argument.
as the first argument. (You may also need the (You may also need the @w{@samp{--baud}} option if the serial line is
@samp{--baud} option if the serial line is running at anything other than 9600 bps.) running at anything other than 9600 bps.) After that, use @code{target
After that, use @code{target remote} to establish communications with @code{gdbserver}. Its argument is either remote} to establish communications with @code{gdbserver}. Its argument
a device name (usually a serial device, like @file{/dev/ttyb}), or a TCP is either a device name (usually a serial device, like
port descriptof in the form @code{@var{host}:@var{PORT}}. For example: @file{/dev/ttyb}), or a TCP port descriptor in the form
@code{@var{host}:@var{PORT}}. For example:
@smallexample @smallexample
(@value{GDBP}) target remote /dev/ttyb (@value{GDBP}) target remote /dev/ttyb
@ -515,7 +526,7 @@ communicates with the server via serial line @file{/dev/ttyb}, and
@end smallexample @end smallexample
@noindent @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 For TCP connections, you must start up @code{gdbserver} prior to using
the @code{target remote} command. Otherwise you may get an error whose the @code{target remote} command. Otherwise you may get an error whose
text depends on the host system, but which usually looks something like 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 MIPS board attached to a serial line. This is available when
you configure @value{GDBN} with @samp{--target=mips-idt-ecoff}. 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} @kindex target mips @var{port}
To run a program on the board, start up @code{@value{GDBP}} with the 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 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 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. 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 For example, this sequence connects to the target board through a serial
serial line managed by a terminal concentrator), using the syntax port, and loads and runs a program called @var{prog} through the
@code{@var{hostname}:@var{portnumber}}. 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 @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! For this to be useful, you must know something about the MIPS
@c FIXME...protocol. Where is it described? @c FIXME...protocol. Where is it described?
You can see some debugging information about communications with the board You can see some debugging information about communications with the board
by setting the @code{remotedebug} variable. If you set it to 1 using by setting the @code{remotedebug} variable. If you set it to @code{1} using
@samp{set remotedebug 1} every packet will be displayed. If you set it @samp{set remotedebug 1}, every packet is displayed. If you set it
to 2 every character will be displayed. You can check the current value to @code{2}, every character is displayed. You can check the current value
at any time with the command @samp{show remotedebug}. 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{timeout}, MIPS protocol
@cindex @code{retransmit-timeout}, MIPS protocol @cindex @code{retransmit-timeout}, MIPS protocol
@kindex set timeout @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 You can inspect both values with @code{show timeout} and @code{show
retransmit-timeout}. (These commands are @emph{only} available when retransmit-timeout}. (These commands are @emph{only} available when
@value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.) @value{GDBN} is configured for @samp{--target=mips-idt-ecoff}.)
@end table
@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 ifset @end ifset
@ifset SIMS @ifset SIMS