From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 26724 invoked by alias); 9 Aug 2011 15:21:56 -0000 Received: (qmail 26714 invoked by uid 22791); 9 Aug 2011 15:21:55 -0000 X-SWARE-Spam-Status: No, hits=-1.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_LOW,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mail-yw0-f41.google.com (HELO mail-yw0-f41.google.com) (209.85.213.41) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 09 Aug 2011 15:21:41 +0000 Received: by ywa6 with SMTP id 6so84547ywa.0 for ; Tue, 09 Aug 2011 08:21:40 -0700 (PDT) Received: by 10.142.200.16 with SMTP id x16mr1229598wff.256.1312903299914; Tue, 09 Aug 2011 08:21:39 -0700 (PDT) Received: from localhost.localdomain ([203.110.240.178]) by mx.google.com with ESMTPS id s9sm46202pbk.66.2011.08.09.08.21.33 (version=TLSv1/SSLv3 cipher=OTHER); Tue, 09 Aug 2011 08:21:39 -0700 (PDT) From: Sanjoy Das To: gdb-patches@sourceware.org Cc: Sanjoy Das Subject: [PATCH 7/7] Add documentation. Date: Tue, 09 Aug 2011 15:21:00 -0000 Message-Id: <1312903509-25132-8-git-send-email-sanjoy@playingwithpointers.com> In-Reply-To: <1312903509-25132-1-git-send-email-sanjoy@playingwithpointers.com> References: <1312903509-25132-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/msg00191.txt.bz2 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 + * doc/gdb.texinfo (JIT Interface): Added node `Custom Debug Info'. + (Custom Debug Info, Using Readers, Writing Readers): New nodes. + +2011-08-09 Sanjoy Das + * 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