diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index bf181a3c23..aa3f517083 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -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. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 49bd76af11..7eb6c5bab4 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -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 diff --git a/gdb/doc/remote.texi b/gdb/doc/remote.texi index a1a75deb4a..26611a8c10 100644 --- a/gdb/doc/remote.texi +++ b/gdb/doc/remote.texi @@ -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