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.
@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
@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
@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
@smallexample
def register_printers(objfile):
- objfile.pretty_printers.add(str_lookup_function)
+ objfile.pretty_printers.append(str_lookup_function)
@end smallexample
@noindent
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
* 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
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}
@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
* 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::
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}).
conventions above. Please don't use this packet as a model for new
packets.)
+@item QTNotes
+@item qTP
@item QTSave
@item qTsP
@item qTsV
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
@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.
@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
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
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
+<library-list-svr4 version="1.0" main-lm="0xe4f8f8">
+ <library name="/lib/ld-linux.so.2" lm="0xe4f51c" l_addr="0xe2d000"
+ l_ld="0xe4eefc"/>
+ <library name="/lib/libc.so.6" lm="0xe4fbe8" l_addr="0x154000"
+ l_ld="0x152350"/>
+</library-list-svr>
+@end smallexample
+
+The format of an SVR4 library list is described by this DTD:
+
+@smallexample
+<!-- library-list-svr4: Root element with versioning -->
+<!ELEMENT library-list-svr4 (library)*>
+<!ATTLIST library-list-svr4 version CDATA #FIXED "1.0">
+<!ATTLIST library-list-svr4 main-lm CDATA #IMPLIED>
+<!ELEMENT library EMPTY>
+<!ATTLIST library name CDATA #REQUIRED>
+<!ATTLIST library lm CDATA #REQUIRED>
+<!ATTLIST library l_addr CDATA #REQUIRED>
+<!ATTLIST library l_ld CDATA #REQUIRED>
+@end smallexample
+
@node Memory Map Format
@section Memory Map Format
@cindex memory map format
projects / deliverable / binutils-gdb.git / blobdiff