[PATCH 7/7] Add documentation.

[Sanjoy Das <sanjoy at playingwithpointers dot com>]

Adds some basic documentation to gdb.texinfo about the new JIT reader
functionality. Most of the actual documentation is still in
jit-reader.h.
---
 gdb/ChangeLog       |    5 +++
 gdb/doc/gdb.texinfo |   94 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+), 0 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 2b3dc1a..5fa54bc 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,5 +1,10 @@
 2011-08-09  Sanjoy Das  <sdas@igalia.com>
 
+	* doc/gdb.texinfo (JIT Interface): Added node `Custom Debug Info'.
+	(Custom Debug Info, Using Readers, Writing Readers): New nodes.
+
+2011-08-09  Sanjoy Das  <sdas@igalia.com>
+
 	* alpha-tdep.c (alpha_dwarf2_init_abi): Call jit_prepend_unwinder.
 	* arm-tdep.c (arm_gdbarch_init): Likewise.
 	* bfin-tdep.c (bfin_gdbarch_init): Likewise.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 35fa075..e9de85b 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -30850,6 +30850,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
@@ -30946,6 +30947,99 @@ 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
+
+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 provide a third-party 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 file
+@file{gdb/jit-reader.h.in}.
+
+The reader is implemented as a shared object.  Two new @value{GDBN}
+commands, @code{load-jit-reader} and @code{unload-jit-reader} are
+added, to be used to load and unload the readers from a preconfigured
+directory.  Once a correct shared object is loaded, @value{GDBN} tries
+to use it to parse the debug information registered by the JIT and to
+unwind stack frames.
+
+@menu
+* Using Readers::       How to use supplied readers correctly
+* Writing Readers::     Creating a debug-info reader
+@end menu
+
+@node Using Readers
+@subsection Using Readers
+
+A mentioned, readers can be loaded using the @code{load-jit-reader}
+command.  Executing @code{load-jit-reader foo} will have @value{GDBN}
+try to load @code{foo.so} from @code{$libdir/gdb} where @code{libdir}
+is the library directory for the system (usually something like
+@code{/usr/local/lib}).  Once a reader is loaded correctly
+(@value{GDBN} will prompt otherwise if this is not the case), no
+further interaction is required from the user's side.  The current
+reader can be unloaded by executing @code{unload-jit-reader}, after
+which a new reader may be loaded, using @code{load-jit-reader} as
+usual.
+
+@node Writing Readers
+@subsection Writing 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 @code{$includedir/gdb} where @code{$includedir} is
+the system include directory.
+
+Readers need to be released under a GPL compatible license.  A reader
+can be declared 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
+
+@smallexample
+extern struct gdb_reader_funcs *gdb_init_reader (void);
+@end smallexample
+
+@code{struct gdb_reader_funcs} contains a set of pointers to callback
+functions.  These functions are executed to read 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
+@{
+  gdb_read_debug_info *read;
+  gdb_unwind_frame *unwind;
+  gdb_get_frame_id *get_frame_id;
+  gdb_destroy_reader *destroy;
+  /* Must be set to GDB_READER_INTERFACE_VERSION */
+  int reader_version;
+
+  /* For use by the reader. */
+  void *priv_data;
+@};
+@end smallexample
+
+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}
-- 
1.7.5.4