FreeChainXenon/binutils-gdb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

gdb/doc/

Browse source 
* 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 2011-11-20 09:20:59 +00:00
parent 3623dc3afb
commit f85b53f80e
2 changed files with 123 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
gdb/doc/ChangeLog
View file

@ -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

116
gdb/doc/gdb.texinfo
View file

@ -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}