From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9681 invoked by alias); 3 Nov 2011 17:55:14 -0000 Received: (qmail 9650 invoked by uid 22791); 3 Nov 2011 17:55:11 -0000 X-SWARE-Spam-Status: No, hits=-1.7 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mail-iy0-f169.google.com (HELO mail-iy0-f169.google.com) (209.85.210.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 03 Nov 2011 17:54:56 +0000 Received: by iaae16 with SMTP id e16so273213iaa.0 for ; Thu, 03 Nov 2011 10:54:56 -0700 (PDT) Received: by 10.231.82.12 with SMTP id z12mr2350216ibk.36.1320342896030; Thu, 03 Nov 2011 10:54:56 -0700 (PDT) Received: from [127.0.0.1] ([203.110.240.205]) by mx.google.com with ESMTPS id l28sm11208154ibc.3.2011.11.03.10.54.52 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 03 Nov 2011 10:54:54 -0700 (PDT) Message-ID: <4EB2D66B.3020305@playingwithpointers.com> Date: Thu, 03 Nov 2011 17:55:00 -0000 From: Sanjoy Das User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.23) Gecko/20111010 Icedove/3.1.15 MIME-Version: 1.0 To: Eli Zaretskii CC: tromey@redhat.com, gdb-patches@sourceware.org Subject: Re: JIT Reader References: <4EA9095D.5070408@playingwithpointers.com> <4EB26FF7.1070102@playingwithpointers.com> <4EB2C49A.2020001@playingwithpointers.com> <838vnxm8or.fsf@gnu.org> In-Reply-To: <838vnxm8or.fsf@gnu.org> Content-Type: multipart/mixed; boundary="------------010707040503030100010006" 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-11/txt/msg00093.txt.bz2 This is a multi-part message in MIME format. --------------010707040503030100010006 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-length: 53 Done. -- Sanjoy Das http://playingwithpointers.com --------------010707040503030100010006 Content-Type: text/x-diff; name="0007-Documentation.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename="0007-Documentation.patch" Content-length: 6171 >From e4f734417a69d4ee38f0b0ac5c2e2e9f9ce3abb1 Mon Sep 17 00:00:00 2001 From: Sanjoy Das Date: Tue, 25 Oct 2011 18:50:53 +0530 Subject: [PATCH 7/7] Documentation. 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/gdb.texinfo | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 116 insertions(+), 0 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 25942b3..1caed06 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -31709,6 +31709,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 @@ -31805,6 +31806,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} -- 1.7.7 --------------010707040503030100010006--