From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13688 invoked by alias); 20 Aug 2011 06:33:01 -0000 Received: (qmail 13672 invoked by uid 22791); 20 Aug 2011 06:33:00 -0000 X-SWARE-Spam-Status: No, hits=-0.6 required=5.0 tests=AWL,BAYES_50,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, 20 Aug 2011 06:32:45 +0000 Received: by pzk36 with SMTP id 36so6709024pzk.3 for ; Fri, 19 Aug 2011 23:32:44 -0700 (PDT) Received: by 10.142.128.21 with SMTP id a21mr135909wfd.371.1313821608729; Fri, 19 Aug 2011 23:26:48 -0700 (PDT) Received: from localhost.localdomain ([203.110.240.178]) by mx.google.com with ESMTPS id v2sm2931441pbi.51.2011.08.19.23.26.46 (version=TLSv1/SSLv3 cipher=OTHER); Fri, 19 Aug 2011 23:26:48 -0700 (PDT) From: Sanjoy Das To: gdb-patches@sourceware.org Cc: Sanjoy Das Subject: [PATCH 6/6] Documentation. Date: Sat, 20 Aug 2011 06:33:00 -0000 Message-Id: <1313821635-22137-7-git-send-email-sanjoy@playingwithpointers.com> In-Reply-To: <1313821635-22137-1-git-send-email-sanjoy@playingwithpointers.com> References: <1313821635-22137-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/msg00390.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/ChangeLog * doc/gdb.texinfo (JIT Interface): Added node `Custom Debug Info'. (Custom Debug Info, Using Readers, Writing Readers): New nodes. --- gdb/ChangeLog | 5 ++ gdb/doc/gdb.texinfo | 119 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 0 deletions(-) diff --git a/gdb/ChangeLog b/gdb/ChangeLog index 92d645b..a2f6794 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,5 +1,10 @@ 2011-08-20 Sanjoy Das + * doc/gdb.texinfo (JIT Interface): Added node `Custom Debug Info'. + (Custom Debug Info, Using Readers, Writing Readers): New nodes. + +2011-08-20 Sanjoy Das + * jit.c (jut_unwind_reg_set_impl, free_reg_value_impl) (jit_unwind_reg_get_impl, jit_frame_sniffer) (jit_frame_unwind_stop_reason, jit_frame_this_id) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 6e7bf52..f6103aa 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -30950,6 +30950,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 @@ -31046,6 +31047,124 @@ 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 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 loaded, the shared object is used the parse the debug +information emitted by the JIT compiler. + +@menu +* Using Readers:: How to use supplied readers correctly +* Writing Readers:: Creating a debug-info reader +@end menu + +@node Using Readers +@subsection Using 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 +@kindex load-jit-reader +@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 running @code{load-jit-reader}. + +@kindex unload-jit-reader +@item unload-jit-reader + +Unload the currently loaded JIT reader. + +@end table + +@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 @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