diff options
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 26 | ||||
| -rw-r--r-- | gdb/doc/Makefile.in | 27 | ||||
| -rw-r--r-- | gdb/doc/gdbint.texinfo | 144 | ||||
| -rw-r--r-- | gdb/doc/remote.texi | 649 | ||||
| -rw-r--r-- | gdb/doc/stabs.texinfo | 4 |
5 files changed, 793 insertions, 57 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 11124c7..10e4ef7 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,29 @@ +Fri Jun 25 11:47:06 1999 Andrew Cagney <cagney@b1.cygnus.com> + + * remote.texi (Communication Protocol): ``v'' is in use. Fix + numerous formatting errors. Clarify ``i''. Mark ``i'', ``Z'', + ``z'' and ``qRcmd'' as draft instead of reserved. Identify + packets that are not supported on all hosts. Expand examples. + Spell check. + +1999-06-24 Jason Molenda (jsm@bugshack.cygnus.com) + + * Makefile.in: Recognize html, install-html. Add targets + to build HTML versions of documentation via texi2html. + +Thu Jun 24 15:59:03 1999 Stan Shebs <shebs@andros.cygnus.com> + + * gdbint.texinfo (Testsuite): New chapter, information about the + testsuite. + +Fri Jun 25 02:40:34 1999 Andrew Cagney <cagney@b1.cygnus.com> + + * remote.texi (Communication Protocol): Rewrite. + +Thu Jun 24 16:59:54 1999 Andrew Cagney <cagney@b1.cygnus.com> + + * stabs.texinfo: Fix uses of xref. + Thu Jun 17 17:23:25 1999 Stan Shebs <shebs@andros.cygnus.com> * gdbint.texinfo: Add an anti-printf exhortation, and update the diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index 4bcd62e..f81e583 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -23,6 +23,7 @@ VPATH = @srcdir@ prefix = @prefix@ infodir = @infodir@ +htmldir = $(prefix)/html SHELL = @SHELL@ @@ -39,6 +40,9 @@ TEXIDIR=${gdbdir}/../texinfo # where to find makeinfo, preferably one designed for texinfo-2 MAKEINFO=makeinfo +MAKEHTML = texi2html +MAKEHTMLFLAGS = -glossary -menu -split_chapter + # where to find texi2roff, ditto TEXI2ROFF=texi2roff @@ -94,6 +98,7 @@ all install: info: gdb.info gdbint.info stabs.info dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi ps: gdb.ps gdbint.ps stabs.ps refcard.ps +html: gdb_toc.html gdbint_toc.html stabs_toc.html all-doc: info dvi ps install-info: info @@ -101,6 +106,11 @@ install-info: info $(INSTALL_DATA) $$i $(infodir)/$$i ; \ done +install-html: html + for i in *.html ; do \ + $(INSTALL_DATA) $$i $(htmldir)/$$i ; \ + done + STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi # Copy the object files from a particular stage into a subdirectory. @@ -152,7 +162,7 @@ distclean: clean # "clean" or "distclean". Use maintainer-clean to remove them. maintainer-clean realclean: distclean - rm -f GDBvn.texi *.info* *.dvi *.ps + rm -f GDBvn.texi *.info* *.dvi *.ps *.html # GDB QUICK REFERENCE (dvi output) refcard.dvi : refcard.tex $(REFEDITS) @@ -303,6 +313,11 @@ gdb.mm: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texi sed -e 's/---/\\(em/g' \ >gdb.mm +# GDB MANUAL: HTML file + +gdb_toc.html: ${SFILES_DOC} + $(MAKEHTML) $(MAKEHTMLFLAGS) -I ${READLINE_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo + # GDB INTERNALS MANUAL: TeX dvi file gdbint.dvi : gdbint.texinfo @@ -320,9 +335,19 @@ gdbint.ps : gdbint.dvi gdbint.info: gdbint.texinfo $(MAKEINFO) -o gdbint.info $(srcdir)/gdbint.texinfo +# GDB INTERNALS MANUAL: HTML file + +gdbint_toc.html: gdbint.texinfo + $(MAKEHTML) $(MAKEHTMLFLAGS) $(srcdir)/gdbint.texinfo + stabs.info: stabs.texinfo $(MAKEINFO) -o stabs.info $(srcdir)/stabs.texinfo +# STABS DOCUMENTATION: HTML file + +stabs_toc.html: stabs.texinfo + $(MAKEHTML) $(MAKEHTMLFLAGS) $(srcdir)/stabs.texinfo + # STABS DOCUMENTATION: TeX dvi file stabs.dvi : stabs.texinfo $(SET_TEXINPUTS) $(TEX) stabs.texinfo diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 10e5278..4db5212 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -86,6 +86,7 @@ as the mechanisms that adapt GDB to specific hosts and targets. * Support Libraries:: * Coding:: * Porting GDB:: +* Testsuite:: * Hints:: @end menu @@ -2559,6 +2560,149 @@ files @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will split the document into one overall file and five or so included files. +@node Testsuite + +@chapter Testsuite + +The testsuite is an important component of the GDB package. While it is +always worthwhile to encourage user testing, in practice this is rarely +sufficient; users typically use only a small subset of the available +commands, and it has proven all too common for a change to cause a +significant regression that went unnoticed for some time. + +The GDB testsuite uses the DejaGNU testing framework. DejaGNU is built +using tcl and expect. The tests themselves are calls to various tcl +procs; the framework runs all the procs and summarizes the passes and +fails. + +@section Using the Testsuite + +To run the testsuite, simply go to the GDB object directory (or to the +testsuite's objdir) and type @code{make check}. This just sets up some +environment variables and invokes DejaGNU's @code{runtest} script. While +the testsuite is running, you'll get mentions of which test file is in use, +and a mention of any unexpected passes or fails. When the testsuite is +finished, you'll get a summary that looks like this: +@example + === gdb Summary === + +# of expected passes 6016 +# of unexpected failures 58 +# of unexpected successes 5 +# of expected failures 183 +# of unresolved testcases 3 +# of untested testcases 5 +@end example +The ideal test run consists of expected passes only; however, reality +conspires to keep us from this ideal. Unexpected failures indicate +real problems, whether in GDB or in the testsuite. Expected failures +are still failures, but ones which have been decided are too hard to +deal with at the time; for instance, a test case might work everywhere +except on AIX, and there is no prospect of the AIX case being fixed in +the near future. Expected failures should not be added lightly, since +you may be masking serious bugs in GDB. Unexpected successes are expected +fails that are passing for some reason, while unresolved and untested +cases often indicate some minor catastrophe, such as the compiler being +unable to deal with a test program. + +When making any significant change to GDB, you should run the testsuite +before and after the change, to confirm that there are no regressions. +Note that truly complete testing would require that you run the +testsuite with all supported configurations and a variety of compilers; +however this is more than really necessary. In many cases testing with +a single configuration is sufficient. Other useful options are to test +one big-endian (Sparc) and one little-endian (x86) host, a cross config +with a builtin simulator (powerpc-eabi, mips-elf), or a 64-bit host +(Alpha). + +If you add new functionality to GDB, please consider adding tests for it +as well; this way future GDB hackers can detect and fix their changes +that break the functionality you added. Similarly, if you fix a bug +that was not previously reported as a test failure, please add a test +case for it. Some cases are extremely difficult to test, such as code +that handles host OS failures or bugs in particular versions of +compilers, and it's OK not to try to write tests for all of those. + +@section Testsuite Organization + +The testsuite is entirely contained in @file{gdb/testsuite}. While the +testsuite includes some makefiles and configury, these are very minimal, +and used for little besides cleaning up, since the tests themselves +handle the compilation of the programs that GDB will run. The file +@file{testsuite/lib/gdb.exp} contains common utility procs useful for +all GDB tests, while the directory @file{testsuite/config} contains +configuration-specific files, typically used for special-purpose +definitions of procs like @code{gdb_load} and @code{gdb_start}. + +The tests themselves are to be found in @file{testsuite/gdb.*} and +subdirectories of those. The names of the test files must always end +with @file{.exp}. DejaGNU collects the test files by wildcarding +in the test directories, so both subdirectories and individual files +get chosen and run in alphabetical order. + +The following table lists the main types of subdirectories and what they +are for. Since DejaGNU finds test files no matter where they are +located, and since each test file sets up its own compilation and +execution environment, this organization is simply for convenience and +intelligibility. + +@table @code + +@item gdb.base + +This is the base testsuite. The tests in it should apply to all +configurations of GDB (but generic native-only tests may live here). +The test programs should be in the subset of C that is valid K&R, +ANSI/ISO, and C++ (ifdefs are allowed if necessary, for instance +for prototypes). + +@item gdb.@var{lang} + +Language-specific tests for all languages besides C. Examples are +@file{gdb.c++} and @file{gdb.java}. + +@item gdb.@var{platform} + +Non-portable tests. The tests are specific to a specific configuration +(host or target), such as HP-UX or eCos. Example is @file{gdb.hp}, for +HP-UX. + +@item gdb.@var{compiler} + +Tests specific to a particular compiler. As of this writing (June +1999), there aren't currently any groups of tests in this category that +couldn't just as sensibly be made platform-specific, but one could +imagine a gdb.gcc, for tests of GDB's handling of GCC extensions. + +@item gdb.@var{subsystem} + +Tests that exercise a specific GDB subsystem in more depth. For +instance, @file{gdb.disasm} exercises various disassemblers, while +@file{gdb.stabs} tests pathways through the stabs symbol reader. + +@end table + +@section Writing Tests + +In many areas, the GDB tests are already quite comprehensive; you +should be able to copy existing tests to handle new cases. + +You should try to use @code{gdb_test} whenever possible, since it +includes cases to handle all the unexpected errors that might happen. +However, it doesn't cost anything to add new test procedures; for +instance, @file{gdb.base/exprs.exp} defines a @code{test_expr} that +calls @code{gdb_test} multiple times. + +Only use @code{send_gdb} and @code{gdb_expect} when absolutely +necessary, such as when GDB has several valid responses to a command. + +The source language programs do @emph{not} need to be in a consistent +style. Since GDB is used to debug programs written in many different +styles, it's worth having a mix of styles in the testsuite; for +instance, some GDB bugs involving the display of source lines would +never manifest themselves if the programs used GNU coding style +uniformly. + @node Hints @chapter Hints diff --git a/gdb/doc/remote.texi b/gdb/doc/remote.texi index adf8e00..7b3c057 100644 --- a/gdb/doc/remote.texi +++ b/gdb/doc/remote.texi @@ -95,7 +95,7 @@ recently added stubs. * Stub Contents:: What the stub can do for you * Bootstrapping:: What you must do for the stub * Debug Session:: Putting it all together -* Protocol:: Outline of the communication protocol +* Protocol:: Definition of the communication protocol * Server:: Using the `gdbserver' program * NetWare:: Using the `gdbserve.nlm' program @end menu @@ -365,79 +365,620 @@ the protocol---for example, if there is only one serial port to your target machine, you might want your program to do something special if it recognizes a packet meant for @value{GDBN}. +In the examples below, @samp{<-} and @samp{->} are used to indicate +transmitted and received data respectfully. + @cindex protocol, @value{GDBN} remote serial @cindex serial protocol, @value{GDBN} remote @cindex remote serial protocol -All @value{GDBN} commands and responses (other than acknowledgements, which -are single characters) are sent as a packet which includes a -checksum. A packet is introduced with the character @samp{$}, and ends -with the character @samp{#} followed by a two-digit checksum: +All @value{GDBN} commands and responses (other than acknowledgments) +are sent as a @var{packet}. A @var{packet} is introduced with the +character @samp{$}, this is followed by an optional two-digit +@var{sequence-id} and the character @samp{:}, the actual +@var{packet-data}, and the terminating character @samp{#} followed by a +two-digit @var{checksum}: @example -$@var{packet info}#@var{checksum} +@code{$}@var{packet-data}@code{#}@var{checksum} +@end example +@noindent +or, with the optional @var{sequence-id}: +@example +@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} @end example @cindex checksum, for @value{GDBN} remote @noindent -@var{checksum} is computed as the modulo 256 sum of the @var{packet -info} characters. +The two-digit @var{checksum} is computed as the modulo 256 sum of all +characters between the leading @samp{$} and the trailing @samp{#} (that +consisting of both the optional @var{sequence-id}@code{:} and the actual +@var{packet-data}). + +@cindex sequence-id, for @value{GDBN} remote +@noindent +The two-digit @var{sequence-id}, when present, is returned with the +acknowledgment. Beyond that its meaning is poorly defined. +@value{GDBN} is not known to output @var{sequence-id}s. When either the host or the target machine receives a packet, the first -response expected is an acknowledgement: a single character, either -@samp{+} (to indicate the package was received correctly) or @samp{-} -(to request retransmission). +response expected is an acknowledgment: either @samp{+} (to indicate +the package was received correctly) or @samp{-} (to request +retransmission): -The host (@value{GDBN}) sends commands, and the target (the debugging stub -incorporated in your program) sends data in response. The target also -sends data when your program stops. +@example +<- @code{$}@var{packet-data}@code{#}@var{checksum} +-> @code{+} +@end example +@noindent +If the received packet included a @var{sequence-id} than that is +appended to a positive acknowledgment: -Command packets are distinguished by their first character, which -identifies the kind of command. +@example +<- @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} +-> @code{+}@var{sequence-id} +@end example -These are some of the commands currently supported (for a complete list of -commands, look in @file{gdb/remote.c.}): +The host (@value{GDBN}) sends @var{command}s, and the target (the +debugging stub incorporated in your program) sends a @var{response}. In +the case of step and continue @var{command}s, the response is only sent +when the operation has completed (the target has again stopped). + +@var{packet-data} consists of a sequence of characters with the +exception of @samp{#} and @samp{$} (see @samp{X} packet for an +exception). @samp{:} can not appear as the third character in a packet. +Fields within the packet should be separated using @samp{,} and @samp{;} +(unfortunately some packets chose to use @samp{:}). Except where +otherwise noted all numbers are represented in HEX with leading zeros +suppressed. + +Response @var{data} can be run-length encoded to save space. A @samp{*} +means that the next character is an ASCII encoding giving a repeat count +which stands for that many repetitions of the character preceding the +@samp{*}. The encoding is @code{n+29}, yielding a printable character +where @code{n >=3} (which is where rle starts to win). Don't use an +@code{n > 126}. + +So: +@example +"@code{0* }" +@end example +@noindent +means the same as "0000". -@table @code -@item g -Requests the values of CPU registers. +The error response, returned for some packets includes a two character +error number. That number is not well defined. -@item G -Sets the values of CPU registers. +For any @var{command} not supported by the stub, an empty response +(@samp{$#00}) should be returned. That way it is possible to extend the +protocol. A newer @value{GDBN} can tell if a packet is supported based +on the response. -@item m@var{addr},@var{count} -Read @var{count} bytes at location @var{addr}. +Below is a complete list of all currently defined @var{command}s and +their corresponding response @var{data}: -@item M@var{addr},@var{count}:@dots{} -Write @var{count} bytes at location @var{addr}. +@multitable @columnfractions .30 .30 .40 +@item Packet +@tab Request +@tab Description -@need 500 -@item c -@itemx c@var{addr} -Resume execution at the current address (or at @var{addr} if supplied). +@item extended ops @emph{(optional)} +@tab @code{!} +@tab +Use the extended remote protocol. Sticky -- only needs to be set once. +The extended remote protocol support the @samp{R} packet. +@item +@tab reply @samp{} +@tab +Stubs that support the extended remote protocol return @samp{} which, +unfortunately, is identical to the response returned by stubs that do not +support protocol extensions. + +@item last signal +@tab @code{?} +@tab +Reply the current reason for stopping. This is the same reply as is +generated for step or cont : @code{S}@var{AA} where @var{AA} is the +signal number. + +@item reserved +@tab @code{a} +@tab Reserved for future use + +@item set program arguments @strong{(reserved)} @emph{(optional)} +@tab @code{A}@var{arglen}@code{,}@var{argnum}@code{,}@var{arg}@code{,...} +@tab +Initialized @samp{argv[]} array passed into program. @var{arglen} +specifies the number of bytes in the hex encoded byte stream @var{arg}. +@item +@tab reply @code{OK} +@item +@tab reply @code{E}@var{NN} + +@item set baud @strong{(deprecated)} +@tab @code{b}@var{baud} +@tab +Change the serial line speed to @var{baud}. JTC: @emph{When does the +transport layer state change? When it's received, or after the ACK is +transmitted. In either case, there are problems if the command or the +acknowledgment packet is dropped.} Stan: @emph{If people really wanted +to add something like this, and get it working for the first time, they +ought to modify ser-unix.c to send some kind of out-of-band message to a +specially-setup stub and have the switch happen "in between" packets, so +that from remote protocol's point of view, nothing actually +happened.} + +@item set breakpoint @strong{(deprecated)} +@tab @code{B}@var{addr},@var{mode} +@tab +Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a +breakpoint at @var{addr}. @emph{This has been replaced by the @samp{Z} and +@samp{z} packets.} + +@item continue +@tab @code{c}@var{addr} +@tab +@var{addr} is address to resume. If @var{addr} is omitted, resume at +current address. +@item +@tab reply +@tab see below + +@item continue with signal @emph{(optional)} +@tab @code{C}@var{sig}@code{;}@var{addr} +@tab +Continue with signal @var{sig} (hex signal number). If +@code{;}@var{addr} is omitted, resume at same address. +@item +@tab reply +@tab see below -@need 500 -@item s -@itemx s@var{addr} -Step the target program for one instruction, from either the current -program counter or from @var{addr} if supplied. - -@item k -Kill the target program. - -@item ? -Report the most recent signal. To allow you to take advantage of the -@value{GDBN} signal handling commands, one of the functions of the debugging -stub is to report CPU traps as the corresponding POSIX signal values. - -@item T -Allows the remote stub to send only the registers that @value{GDBN} needs -to make a quick decision about single-stepping or conditional breakpoints. -This eliminates the need to fetch the entire register set for each instruction -being stepped through. - -@value{GDBN} now implements a write-through cache for registers and only -re-reads the registers if the target has run. -@end table +@item toggle debug @emph{(optional)} +@tab @code{d} +@tab +toggle debug flag (see 386 & 68k stubs) + +@item detach @emph{(optional)} +@tab @code{D} +@tab Reply OK. + +@item reserved +@tab @code{e} +@tab Reserved for future use + +@item reserved +@tab @code{E} +@tab Reserved for future use + +@item reserved +@tab @code{f} +@tab Reserved for future use + +@item reserved +@tab @code{F} +@tab Reserved for future use + +@item read registers +@tab @code{g} +@tab Read general registers. +@item +@tab reply @var{XX...} +@tab +Each byte of register data is described by two hex digits. The bytes +with the register are transmitted in target byte order. The size of +each register and their position within the @samp{g} @var{packet} is +determined by the @var{REGISTER_RAW_SIZE} and @var{REGISTER_NAME} +macros. +@item +@tab @code{E}@var{NN} +@tab for an error. + +@item write regs +@tab @code{G}@var{XX...} +@tab +See @samp{g} for a description of the @var{XX...} data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item reserved +@tab @code{h} +@tab Reserved for future use + +@item set thread @emph{(optional)} +@tab @code{H}@var{c}@var{t...} +@tab +Set thread for subsequent operations. @var{c} = @samp{c} for thread +used in step and continue; @var{t...} can be -1 for all threads. +@var{c} = @samp{g} for thread used in other operations. If zero, pick a +thread, any thread. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item cycle step @strong{(draft)} @emph{(optional)} +@tab @code{i}@var{addr}@code{,}@var{nnn} +@tab +Step the remote target by a single clock cycle. If @code{,}@var{nnn} is +present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle +step starting at that address. + +@item signal then cycle step @strong{(reserved)} @emph{(optional)} +@tab @code{I} +@tab +See @samp{i} and @samp{S} for likely syntax and semantics. + +@item reserved +@tab @code{j} +@tab Reserved for future use + +@item reserved +@tab @code{J} +@tab Reserved for future use + +@item kill request @emph{(optional)} +@tab @code{k} +@tab + +@item reserved +@tab @code{l} +@tab Reserved for future use + +@item reserved +@tab @code{L} +@tab Reserved for future use + +@item read memory +@tab @code{m}@var{addr}@code{,}@var{length} +@tab +Read @var{length} bytes of memory starting at address @var{addr}. +@item +@tab reply @var{XX...} +@tab +@var{XX...} is mem contents. Can be fewer bytes than requested if able to +read only part of the data. +@item +@tab reply @code{E}@var{NN} +@tab @var{NN} is errno + +@item write mem +@tab @code{M}@var{addr},@var{length}@code{:}@var{XX...} +@tab +Write @var{length} bytes of memory starting at address @var{addr}. +@var{XX...} is the data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab +for an error (this includes the case where only part of the data was +written). + +@item reserved +@tab @code{n} +@tab Reserved for future use + +@item reserved +@tab @code{N} +@tab Reserved for future use + +@item reserved +@tab @code{o} +@tab Reserved for future use + +@item reserved +@tab @code{O} +@tab Reserved for future use + +@item read reg @strong{(reserved)} +@tab @code{p}@var{n...} +@tab +See write register. +@item +@tab return @var{r....} +@tab The hex encoded value of the register in target byte order. + +@item write reg @emph{(optional)} +@tab @code{P}@var{n...}@code{=}@var{r...} +@tab +Write register @var{n...} with value @var{r...}, which contains two hex +digits for each byte in the register (target byte order). +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item general query @emph{(optional)} +@tab @code{q}@var{query} +@tab +Request info about @var{query}. In general @value{GDBN} @var{query}'s +have a leading upper case letter. Custom vendor queries should use a +leading lower case letter and a company prefix, ex: @samp{qfsf.var}. +@var{query} may optionally be followed by a @samp{,} or @samp{;} +separated list. Stubs should ensure that they fully match any +@var{query} name. +@item +@tab reply @code{XX...} +@tab Hex encoded data from query. The reply can not be empty. +@item +@tab reply @code{E}@var{NN} +@tab error reply +@item +@tab reply @samp{} +@tab Indicating an unrecognized @var{query}. + +@item current thread +@tab @code{q}@code{C} +@tab Return the current thread id. +@item +@tab reply @code{QC}@var{pid} +@tab +Where @var{pid} is a HEX encoded 16 bit process id. +@item +@tab reply * +@tab Any other reply implies the old pid. + +@item compute CRC of memory block +@tab @code{q}@code{CRC:}@var{addr}@code{,}@var{length} +@tab +@item +@tab reply @code{E}@var{NN} +@tab An error (such as memory fault) +@item +@tab reply @code{C}@var{CRC32} +@tab A 32 bit cyclic redundancy check of the specified memory region. + +@item query @var{LIST} or @var{threadLIST} +@tab @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} +@tab +Obtain thread information from RTOS. @var{startflag} is one hex digit; +@var{threadcount} is two hex digits; and @var{nextthread} is 16 hex +digits. +@item +@tab reply * +@tab +See @code{remote.c:parse_threadlist_response()}. + +@item query sect offs +@tab @code{q}@code{Offsets} +@tab Get section offsets. +@item +@tab reply @code{Text=}@var{xxx}@code{;Data=}@var{yyy}@code{;Bss=}@var{zzz} + +@item thread info request +@tab @code{q}@code{P}@var{mode}@var{threadid} +@tab +Returns information on @var{threadid}. Where: @var{mode} is a hex +encoded 32 bit mode; @var{threadid} is a hex encoded 64 bit thread ID. +@item +@tab reply * +@tab +See @code{remote.c:remote_unpack_thread_info_response()}. + +@item remote command @strong{(reserved)} +@tab @code{q}@code{Rcmd,}@var{COMMAND} +@tab +@var{COMMAND} (hex encoded) is passed to the local interpreter for +execution. @emph{Implementors should note that providing access to a +stubs's interpreter may have security implications}. +@item +@tab reply @var{OUTPUT} +@tab +The @var{OUTPUT} (hex encoded). Must be non-empty. +@item +@tab reply @samp{} +@tab +When @samp{q}@samp{Rcmd} is not recognized. + +@item general set @emph{(optional)} +@tab @code{Q}@var{var}@code{=}@var{val} +@tab +Set value of @var{var} to @var{val}. See @samp{q} for a discussing of +naming conventions. + +@item reset @emph{(optional)} +@tab r +@tab reset -- see sparc stub. + +@item remote restart @emph{(optional)} +@tab @code{R}@var{XX} +@tab +Restart the remote server. @var{XX} while needed has no clear +definition. + +@item step @emph{(optional)} +@tab @code{s}@var{addr} +@tab +@var{addr} is address to resume. If @var{addr} is omitted, resume at +same address. +@item +@tab reply +@tab see below + +@item step with signal @emph{(optional)} +@tab @code{S}@var{sig}@code{;}@var{addr} +@tab +Like @samp{C} but step not continue. +@item +@tab reply +@tab see below + +@item search @emph{(optional)} +@tab @code{t}@var{addr}@code{:}@var{PP}@code{,}@var{MM} +@tab +Search backwards starting at address @var{addr} for a match with pattern +@var{PP} and mask @var{MM}. @var{PP} and @var{MM} are 4 +bytes. @var{addr} must be at least 3 digits. + +@item thread alive @emph{(optional)} +@tab @code{T}@var{XX} +@tab Find out if the thread XX is alive. +@item +@tab reply @code{OK} +@tab thread is still alive +@item +@tab reply @code{E}@var{NN} +@tab thread is dead + +@item reserved +@tab @code{u} +@tab Reserved for future use + +@item reserved +@tab @code{U} +@tab Reserved for future use + +@item reserved +@tab @code{v} +@tab Reserved for future use + +@item reserved +@tab @code{V} +@tab Reserved for future use + +@item reserved +@tab @code{w} +@tab Reserved for future use + +@item reserved +@tab @code{W} +@tab Reserved for future use + +@item reserved +@tab @code{x} +@tab Reserved for future use + +@item write mem (binary) @emph{(optional)} +@tab @code{X}@var{addr}@code{,}@var{length}@var{:}@var{XX...} +@tab +@var{addr} is address, @var{length} is number of bytes, @var{XX...} is +binary data. +@item +@tab reply @code{OK} +@tab for success +@item +@tab reply @code{E}@var{NN} +@tab for an error + +@item reserved +@tab @code{y} +@tab Reserved for future use + +@item reserved +@tab @code{Y} +@tab Reserved for future use + +@item remove break or watchpoint @strong{(draft)} @emph{(optional)} +@tab @code{z}@var{t}@code{,}@var{addr}@code{,}@var{length} +@tab +See @samp{Z}. + +@item insert break or watchpoint @strong{(draft)} @emph{(optional)} +@tab @code{Z}@var{t}@code{,}@var{addr}@code{,}@var{length} +@tab +@var{t} is type: @samp{0} - software breakpoint, @samp{1} - hardware +breakpoint, @samp{2} - write watchpoint, @samp{3} - read watchpoint, +@samp{4} - access watchpoint; @var{addr} is address; @var{length} is in +bytes. For a software breakpoint, @var{length} specifies the size of +the instruction to be patched. For hardware breakpoints and watchpoints +@var{length} specifies the memory region to be monitored. +@item +@tab reply @code{E}@var{NN} +@tab for an error +@item +@tab reply @code{OK} +@tab for success +@item +@tab @samp{} +@tab If not supported. + +@item reserved +@tab <other> +@tab Reserved for future use + +@end multitable + +In the case of the @samp{C}, @samp{c}, @samp{S} and @samp{s} packets, +there is no immediate response. The reply, described below, comes when +the machine stops: + +@multitable @columnfractions .4 .6 + +@item @code{S}@var{AA} +@tab @var{AA} is the signal number + +@item @code{T}@var{AA}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;}@var{n...}@code{:}@var{r...}@code{;} +@tab +@var{AA} = two hex digit signal number; @var{n...} = register number +(hex), @var{r...} = target byte ordered register contents, size defined +by @code{REGISTER_RAW_SIZE}; @var{n...} = @samp{thread}, @var{r...} = +thread process ID, this is a hex integer; @var{n...} = other string not +starting with valid hex digit. @value{GDBN} should ignore this +@var{n...}, @var{r...} pair and go on to the next. This way we can +extend the protocol. + +@item @code{W}@var{AA} +@tab +The process exited, and @var{AA} is the exit status. This is only +applicable for certains sorts of targets. + +@item @code{X}@var{AA} +@tab +The process terminated with signal @var{AA}. + +@item @code{N}@var{AA}@code{;}@var{tttttttt}@code{;}@var{dddddddd}@code{;}@var{bbbbbbbb} @strong{(obsolete)} +@tab +@var{AA} = signal number; @var{tttttttt} = address of symbol "_start"; +@var{dddddddd} = base of data section; @var{bbbbbbbb} = base of bss +section. @emph{Note: only used by Cisco Systems targets. The difference +between this reply and the "qOffsets" query is that the 'N' packet may +arrive spontaneously whereas the 'qOffsets' is a query initiated by the +host debugger.} + +@item @code{O}@var{XX...} +@tab +@var{XX...} is hex encoding of ASCII data. This can happen at any time +while the program is running and the debugger should continue to wait +for 'W', 'T', etc. + +@end multitable + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + +@example +<- @code{R00} +-> @code{+} +@emph{target restarts} +<- @code{?} +-> @code{+} +-> @code{T001:1234123412341234} +<- @code{+} +@end example + +Example sequence of a target being stepped by a single instruction: + +@example +<- @code{G1445...} +-> @code{+} +<- @code{s} +-> @code{+} +@emph{time passes} +-> @code{T001:1234123412341234} +<- @code{+} +<- @code{g} +-> @code{+} +-> @code{1455...} +<- @code{+} +@end example @kindex set remotedebug @kindex show remotedebug diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo index 2e4f7b8..8239ce7 100644 --- a/gdb/doc/stabs.texinfo +++ b/gdb/doc/stabs.texinfo @@ -872,7 +872,7 @@ produces the following stabs: .stabn 224,0,0,LBE2 # @r{224 is N_RBRAC} @end example -@xref{Procedures} for more information on the @code{N_FUN} stab, and +See @ref{Procedures} for more information on the @code{N_FUN} stab, and @ref{Block Structure} for more information on the @code{N_LBRAC} and @code{N_RBRAC} stabs. @@ -3370,7 +3370,7 @@ for more information about their use. Variable on the stack; see @ref{Stack Variables}. @item : -C++ nested symbol; see @xref{Nested Symbols} +C++ nested symbol; see @xref{Nested Symbols}. @item a Parameter passed by reference in register; see @ref{Reference Parameters}. |