X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=50c299e480d0723b81d97cc888500117829576f7;hb=f8eba3c61629b3c03ac1f33853eab4d8507adb9c;hp=bb9bede05ae91ef4b57cf10d1e60ce89f1a65bbf;hpb=bfccc43c1218b6d89bb021381276ac742e7a9a9e;p=deliverable%2Fbinutils-gdb.git diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index bb9bede05a..50c299e480 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -3521,6 +3521,9 @@ It is possible that a breakpoint corresponds to several locations in your program. Examples of this situation are: @itemize @bullet +@item +Multiple functions in the program may have the same name. + @item For a C@t{++} constructor, the @value{NGCC} compiler generates several instances of the function body, used in different cases. @@ -3535,11 +3538,7 @@ several places where that function is inlined. @end itemize In all those cases, @value{GDBN} will insert a breakpoint at all -the relevant locations@footnote{ -As of this writing, multiple-location breakpoints work only if there's -line number information for all the locations. This means that they -will generally not work in system libraries, unless you have debug -info with line numbers for them.}. +the relevant locations. A breakpoint with multiple locations is displayed in the breakpoint table using several rows---one header row, followed by one row for @@ -10902,20 +10901,27 @@ Cnt ID Enb Address What @subsection Starting and Stopping Trace Experiments @table @code -@kindex tstart +@kindex tstart [ @var{notes} ] @cindex start a new trace experiment @cindex collected data discarded @item tstart -This command takes no arguments. It starts the trace experiment, and -begins collecting data. This has the side effect of discarding all -the data collected in the trace buffer during the previous trace -experiment. - -@kindex tstop +This command starts the trace experiment, and begins collecting data. +It has the side effect of discarding all the data collected in the +trace buffer during the previous trace experiment. If any arguments +are supplied, they are taken as a note and stored with the trace +experiment's state. The notes may be arbitrary text, and are +especially useful with disconnected tracing in a multi-user context; +the notes can explain what the trace is doing, supply user contact +information, and so forth. + +@kindex tstop [ @var{notes} ] @cindex stop a running trace experiment @item tstop -This command takes no arguments. It ends the trace experiment, and -stops collecting data. +This command stops the trace experiment. If any arguments are +supplied, they are recorded with the experiment as a note. This is +useful if you are stopping a trace started by someone else, for +instance if the trace is interfering with the system's behavior and +needs to be stopped quickly. @strong{Note}: a trace experiment and data collection may stop automatically if any tracepoint's passcount is reached @@ -11019,6 +11025,33 @@ for instance if you are looking at frames from a trace file. @end table +@table @code +@item set trace-user @var{text} +@kindex set trace-user + +@item show trace-user +@kindex show trace-user + +@item set trace-notes @var{text} +@kindex set trace-notes +Set the trace run's notes. + +@item show trace-notes +@kindex show trace-notes +Show the trace run's notes. + +@item set trace-stop-notes @var{text} +@kindex set trace-stop-notes +Set the trace run's stop notes. The handling of the note is as for +@code{tstop} arguments; the set command is convenient way to fix a +stop note that is mistaken or incomplete. + +@item show trace-stop-notes +@kindex show trace-stop-notes +Show the trace run's stop notes. + +@end table + @node Tracepoint Restrictions @subsection Tracepoint Restrictions @@ -22557,7 +22590,7 @@ this code might appear in @code{gdb.libstdcxx.v6}: @smallexample def register_printers(objfile): - objfile.pretty_printers.add(str_lookup_function) + objfile.pretty_printers.append(str_lookup_function) @end smallexample @noindent @@ -26138,6 +26171,25 @@ The inferior exited. The inferior exited normally. @item signal-received A signal was received by the inferior. +@item solib-event +The inferior has stopped due to a library being loaded or unloaded. +This can only happen when @code{stop-on-solib-events} (@pxref{Files}) +is set. +@item fork +The inferior has forked. This is reported when @code{catch fork} +(@pxref{Set Catchpoints}) has been used. +@item vfork +The inferior has vforked. This is reported in when @code{catch vfork} +(@pxref{Set Catchpoints}) has been used. +@item syscall-entry +The inferior entered a system call. This is reported when @code{catch +syscall} (@pxref{Set Catchpoints}) has been used. +@item syscall-entry +The inferior returned from a system call. This is reported when +@code{catch syscall} (@pxref{Set Catchpoints}) has been used. +@item exec +The inferior called @code{exec}. This is reported when @code{catch exec} +(@pxref{Set Catchpoints}) has been used. @end table The @var{id} field identifies the thread that directly caused the stop @@ -31775,6 +31827,7 @@ out about additional code. * Declarations:: Relevant C struct declarations * Registering Code:: Steps to register code * Unregistering Code:: Steps to unregister code +* Custom Debug Info:: Emit debug information in a custom format @end menu @node Declarations @@ -31871,6 +31924,121 @@ Set @code{action_flag} to @code{JIT_UNREGISTER} and call If the JIT frees or recompiles code without unregistering it, then @value{GDBN} and the JIT will leak the memory used for the associated symbol files. +@node Custom Debug Info +@section Custom Debug Info +@cindex custom JIT debug info +@cindex JIT debug info reader + +Generating debug information in platform-native file formats (like ELF +or COFF) may be an overkill for JIT compilers; especially if all the +debug info is used for is displaying a meaningful backtrace. The +issue can be resolved by having the JIT writers decide on a debug info +format and also provide a reader that parses the debug info generated +by the JIT compiler. This section gives a brief overview on writing +such a parser. More specific details can be found in the source file +@file{gdb/jit-reader.in}, which is also installed as a header at +@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion. + +The reader is implemented as a shared object (so this functionality is +not available on platforms which don't allow loading shared objects at +runtime). Two @value{GDBN} commands, @code{jit-reader-load} and +@code{jit-reader-unload} are provided, to be used to load and unload +the readers from a preconfigured directory. Once loaded, the shared +object is used the parse the debug information emitted by the JIT +compiler. + +@menu +* Using JIT Debug Info Readers:: How to use supplied readers correctly +* Writing JIT Debug Info Readers:: Creating a debug-info reader +@end menu + +@node Using JIT Debug Info Readers +@subsection Using JIT Debug Info Readers +@kindex jit-reader-load +@kindex jit-reader-unload + +Readers can be loaded and unloaded using the @code{jit-reader-load} +and @code{jit-reader-unload} commands. + +@table @code +@item jit-reader-load @var{reader-name} +Load the JIT reader named @var{reader-name}. On a UNIX system, this +will usually load @file{@var{libdir}/gdb/@var{reader-name}}, where +@var{libdir} is the system library directory, usually +@file{/usr/local/lib}. Only one reader can be active at a time; +trying to load a second reader when one is already loaded will result +in @value{GDBN} reporting an error. A new JIT reader can be loaded by +first unloading the current one using @code{jit-reader-load} and then +invoking @code{jit-reader-load}. + +@item jit-reader-unload +Unload the currently loaded JIT reader. + +@end table + +@node Writing JIT Debug Info Readers +@subsection Writing JIT Debug Info Readers +@cindex writing JIT debug info readers + +As mentioned, a reader is essentially a shared object conforming to a +certain ABI. This ABI is described in @file{jit-reader.h}. + +@file{jit-reader.h} defines the structures, macros and functions +required to write a reader. It is installed (along with +@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is +the system include directory. + +Readers need to be released under a GPL compatible license. A reader +can be declared as released under such a license by placing the macro +@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file. + +The entry point for readers is the symbol @code{gdb_init_reader}, +which is expected to be a function with the prototype + +@findex gdb_init_reader +@smallexample +extern struct gdb_reader_funcs *gdb_init_reader (void); +@end smallexample + +@cindex @code{struct gdb_reader_funcs} + +@code{struct gdb_reader_funcs} contains a set of pointers to callback +functions. These functions are executed to read the debug info +generated by the JIT compiler (@code{read}), to unwind stack frames +(@code{unwind}) and to create canonical frame IDs +(@code{get_Frame_id}). It also has a callback that is called when the +reader is being unloaded (@code{destroy}). The struct looks like this + +@smallexample +struct gdb_reader_funcs +@{ + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; +@}; +@end smallexample + +@cindex @code{struct gdb_symbol_callbacks} +@cindex @code{struct gdb_unwind_callbacks} + +The callbacks are provided with another set of callbacks by +@value{GDBN} to do their job. For @code{read}, these callbacks are +passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind} +and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}. +@code{struct gdb_symbol_callbacks} has callbacks to create new object +files and new symbol tables inside those object files. @code{struct +gdb_unwind_callbacks} has callbacks to read registers off the current +frame and to write out the values of the registers in the previous +frame. Both have a callback (@code{target_read}) to read bytes off the +target's address space. + @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} @cindex bugs in @value{GDBN} @@ -32279,7 +32447,8 @@ Remote protocol memory maps (@pxref{Memory Map Format}) @item Target descriptions (@pxref{Target Descriptions}) @item -Remote shared library lists (@pxref{Library List Format}) +Remote shared library lists (@xref{Library List Format}, +or alternatively @pxref{Library List Format for SVR4 Targets}) @item MS-Windows shared libraries (@pxref{Shared Libraries}) @item @@ -33116,6 +33285,7 @@ Show the current setting of the target wait timeout. * Examples:: * File-I/O Remote Protocol Extension:: * Library List Format:: +* Library List Format for SVR4 Targets:: * Memory Map Format:: * Thread List Format:: * Traceframe Info Format:: @@ -34817,6 +34987,10 @@ The remote stub understands the @samp{qXfer:features:read} packet The remote stub understands the @samp{qXfer:libraries:read} packet (@pxref{qXfer library list read}). +@item qXfer:libraries-svr4:read +The remote stub understands the @samp{qXfer:libraries-svr4:read} packet +(@pxref{qXfer svr4 library list read}). + @item qXfer:memory-map:read The remote stub understands the @samp{qXfer:memory-map:read} packet (@pxref{qXfer memory map read}). @@ -34999,6 +35173,8 @@ the command by a @samp{,}, not a @samp{:}, contrary to the naming conventions above. Please don't use this packet as a model for new packets.) +@item QTNotes +@item qTP @item QTSave @item qTsP @item qTsV @@ -35060,6 +35236,18 @@ the operating system manages the list of loaded libraries. This packet is not probed by default; the remote stub must request it, by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer svr4 library list read} +Access the target's list of loaded libraries when the target is an SVR4 +platform. @xref{Library List Format for SVR4 Targets}. The annex part +of the generic @samp{qXfer} packet must be empty (@pxref{qXfer read}). + +This packet is optional for better performance on SVR4 targets. +@value{GDBN} uses memory read packets to read the SVR4 library list otherwise. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + @item qXfer:memory-map:read::@var{offset},@var{length} @anchor{qXfer memory map read} Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The @@ -35581,8 +35769,11 @@ explanations as one of the optional fields: @item tnotrun:0 No trace has been run yet. -@item tstop:0 -The trace was stopped by a user-originated stop command. +@item tstop[:@var{text}]:0 +The trace was stopped by a user-originated stop command. The optional +@var{text} field is a user-supplied string supplied as part of the +stop command (for instance, an explanation of why the trace was +stopped manually). It is hex-encoded. @item tfull:0 The trace stopped because the trace buffer filled up. @@ -35638,6 +35829,22 @@ that the trace run will stop. @end table +@item qTP:@var{tp}:@var{addr} +@cindex tracepoint status, remote request +@cindex @samp{qTP} packet +Ask the stub for the current state of tracepoint number @var{tp} at +address @var{addr}. + +Replies: +@table @samp +@item V@var{hits}:@var{usage} +The tracepoint has been hit @var{hits} times so far during the trace +run, and accounts for @var{usage} in the trace buffer. Note that +@code{while-stepping} steps are not counted as separate hits, but the +steps' space consumption is added into the usage number. + +@end table + @item qTV:@var{var} @cindex trace state variable value, remote request @cindex @samp{qTV} packet @@ -35731,6 +35938,11 @@ available. This packet directs the target to use a circular trace buffer if @var{value} is 1, or a linear buffer if the value is 0. +@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} +This packet adds optional textual notes to the trace run. Allowable +types include @code{user}, @code{notes}, and @code{tstop}, the +@var{text} fields are arbitrary strings, hex-encoded. + @end table @subsection Relocate instruction reply packet @@ -37347,6 +37559,68 @@ In addition, segments and section descriptors cannot be mixed within a single library element, and you must supply at least one segment or section for each library. +@node Library List Format for SVR4 Targets +@section Library List Format for SVR4 Targets +@cindex library list format, remote protocol + +On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader +(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of +shared libraries. Still a special library list provided by this packet is +more efficient for the @value{GDBN} remote protocol. + +The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists +loaded libraries and their SVR4 linker parameters. For each library on SVR4 +target, the following parameters are reported: + +@itemize @minus +@item +@code{name}, the absolute file name from the @code{l_name} field of +@code{struct link_map}. +@item +@code{lm} with address of @code{struct link_map} used for TLS +(Thread Local Storage) access. +@item +@code{l_addr}, the displacement as read from the field @code{l_addr} of +@code{struct link_map}. For prelinked libraries this is not an absolute +memory address. It is a displacement of absolute memory address against +address the file was prelinked to during the library load. +@item +@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment +@end itemize + +Additionally the single @code{main-lm} attribute specifies address of +@code{struct link_map} used for the main executable. This parameter is used +for TLS access and its presence is optional. + +@value{GDBN} must be linked with the Expat library to support XML +SVR4 library lists. @xref{Expat}. + +A simple memory map, with two loaded libraries (which do not use prelink), +looks like this: + +@smallexample + + + + +@end smallexample + +The format of an SVR4 library list is described by this DTD: + +@smallexample + + + + + + + + + +@end smallexample + @node Memory Map Format @section Memory Map Format @cindex memory map format