gdb/doc/
* gdb.texinfo (JIT Interface): Add documentation on writing and usind JIT debug info readers. (Custom Debug Info, Using JIT Debug Info Readers, Writing JIT Debug Info Readers): New nodes.
This commit is contained in:
Sanjoy Das
parent
3623dc3afb
commit
f85b53f80e
|
|
@ -1,3 +1,10 @@
|
|||
2011-11-20 Sanjoy Das <sdas@igalia.com>
|
||||
|
||||
* gdb.texinfo (JIT Interface): Add documentation on writing and
|
||||
usind JIT debug info readers.
|
||||
(Custom Debug Info, Using JIT Debug Info Readers, Writing JIT
|
||||
Debug Info Readers): New nodes.
|
||||
|
||||
2011-11-18 Yao Qi <yao@codesourcery.com>
|
||||
|
||||
* gdb.texinfo (Create and Delete Tracepoints): Mention pending
|
||||
|
|
|
|||
|
|
@ -31775,6 +31775,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 +31872,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}
|
||||
|
|
|
|||
Loading…
Reference in New Issue