From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20649 invoked by alias); 27 Aug 2011 13:08:49 -0000 Received: (qmail 20481 invoked by uid 22791); 27 Aug 2011 13:08:46 -0000 X-SWARE-Spam-Status: No, hits=-1.8 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mail-pz0-f44.google.com (HELO mail-pz0-f44.google.com) (209.85.210.44) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sat, 27 Aug 2011 13:08:29 +0000 Received: by mail-pz0-f44.google.com with SMTP id 36so6427620pzk.3 for ; Sat, 27 Aug 2011 06:08:29 -0700 (PDT) Received: by 10.142.139.19 with SMTP id m19mr1217881wfd.108.1314450508721; Sat, 27 Aug 2011 06:08:28 -0700 (PDT) Received: from localhost.localdomain ([203.110.240.205]) by mx.google.com with ESMTPS id b20sm933541wfh.12.2011.08.27.06.08.25 (version=TLSv1/SSLv3 cipher=OTHER); Sat, 27 Aug 2011 06:08:27 -0700 (PDT) From: Sanjoy Das To: gdb-patches@sourceware.org Cc: Sanjoy Das Subject: [PATCH 7/7] Documentation. Date: Sat, 27 Aug 2011 13:08:00 -0000 Message-Id: <1314450736-19389-8-git-send-email-sanjoy@playingwithpointers.com> In-Reply-To: <1314450736-19389-1-git-send-email-sanjoy@playingwithpointers.com> References: <1314450736-19389-1-git-send-email-sanjoy@playingwithpointers.com> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-08/txt/msg00528.txt.bz2 Add some basic documentation to gdb.texinfo about the new JIT reader functionality. Most of the actual documentation is still in jit-reader.h. gdb/doc/ChangeLog: * 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. --- gdb/doc/ChangeLog | 7 +++ gdb/doc/gdb.texinfo | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 0 deletions(-) diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 80038f1..190ff75 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,10 @@ +2011-08-27 Sanjoy Das + + * 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-08-25 Andrew Oakley * gdb.texinfo (Types In Python): Document 'bitpos' for enums. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 23b2a98..8168952 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -30951,6 +30951,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 @@ -31047,6 +31048,122 @@ 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. Two new @value{GDBN} +commands, @code{load-jit-reader} and @code{unload-jit-reader} 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 load-jit-reader +@kindex unload-jit-reader + +Readers can be loaded and unloaded using the @code{load-jit-reader} +and @code{unload-jit-reader} commands. + +@table @code +@item load-jit-reader @var{reader-name} + +Load the JIT reader named @var{reader-name}. On a UNIX system, this +will usually result 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{unload-jit-reader} and +then invoking @code{load-jit-reader}. + +@item unload-jit-reader + +Unload the currently loaded JIT reader. + +@end table + +@node Writing JIT Debug Info Readers +@subsection 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} -- 1.7.5.4