From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16444 invoked by alias); 24 Jul 2011 17:26:27 -0000 Received: (qmail 16435 invoked by uid 22791); 24 Jul 2011 17:26:27 -0000 X-SWARE-Spam-Status: No, hits=0.5 required=5.0 tests=AWL,BAYES_50,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout21.012.net.il (HELO mtaout21.012.net.il) (80.179.55.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sun, 24 Jul 2011 17:26:11 +0000 Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0LOU00600LO4Q300@a-mtaout21.012.net.il> for gdb-patches@sourceware.org; Sun, 24 Jul 2011 20:26:09 +0300 (IDT) Received: from HOME-C4E4A596F7 ([77.124.68.10]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LOU0062VLRKNY50@a-mtaout21.012.net.il>; Sun, 24 Jul 2011 20:26:09 +0300 (IDT) Date: Sun, 24 Jul 2011 17:51:00 -0000 From: Eli Zaretskii Subject: Re: [PATCH 3/4] Adds documentation. In-reply-to: <1311523427-20501-4-git-send-email-sanjoy@playingwithpointers.com> To: Sanjoy Das Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83zkk3egjr.fsf@gnu.org> References: <1311523427-20501-1-git-send-email-sanjoy@playingwithpointers.com> <1311523427-20501-4-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-07/txt/msg00671.txt.bz2 > From: Sanjoy Das > Cc: Sanjoy Das > Date: Sun, 24 Jul 2011 21:33:46 +0530 > > Adds some basic documentation to gdb.texinfo about the new JIT reader functionality. This should be a good entry point for developers writing parsers for the debug info their JIT compiler generates. Thanks. > gdb/ChangeLog > * gdb.texinfo: Some documentation about the new JIT debug info reader functionality. This should state the name(s) of the new node(s), in the same format as gdb/ChangeLog documents functions, as if each node were a function. > +@node Custom Object File Format You cannot add a node without also adding it to the menu in its parent (which happens to be "JIT Interface" in this case). I guess you didn't actually say "make info", because I don't think it would have worked for you. > +@section Custom Object File Format As a general rule, each @section should have a @cindex entry whose text is identical to the section name, but with all lower-case letters. > +Generating debug information in native file formats (like ELF or COFF) can become an overkill for JIT compilers; especially if all the debug info is used for 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 an overview on writing such a parser. More details can be found in the file @code{gdb/jit-reader.h.in}. First, please don't make such long lines, they make reading harder. Second, please leave 2 spaces after a period that ends a sentence. And third, "gdb/jit-reader.h.in" is a file, so it should have the @file markup, not @code. > +The reader is implemented as a shared object. GDB, when trying to read the debug information generated by a JIT compiler, looks for such shared objects in a special, pre-configured, directory. If such a (conforming) shared object is found, it is dynamically loaded and used to parse the debug info. Please use "@value{GDBN}" instead of a literal "GDB". That allows to change the name in only one place, if someone wants to produce a manual for a customized GDB that has a different name. > +@node Writing A Parser > +@subsection Writing A Parser There should be a @menu in the previous node before you can use a @subsection here. Please add an index entry here, something like @cindex JIT parser @cindex writing JIT parsers > +The parser needs to include @code{jit-reader.h}, which defines the required structures, macros and functions. ^^^^^ @file > +@node Elements Of @code{jit-reader.h} A @node cannot use @-commands. So just "Elements of jit-reader.h" Also, this node has to appear in a menu, see above. > +@subsubsection Elements Of @code{jit-reader.h} ^^^^^ @file > +After the plugin is loaded, GDB looks for the function @code{gdb_init_reader}. The prototype of the function (also included in @code{jit-reader.h}) is: ^^^^^ @file > +@node The API Should be in a menu. > +The plugin provides an API for creating symbol files (which GDB will use to, for instance, display function names in the backtrace) and implementing a frame unwinder. ^^^ @value{GDBN} > +@strong{Symbol Reading} If this is supposed to be a heading, please use @heading. > +The @code{read} function in @code{struct gdb_reader_funcs} is called to read in the debug info emitted by the JIT compiler and create the appropriate symbol tables. To keep the API clean and stable, GDB's internal structures are not exposed. Instead, a @code{struct} full of function pointers are passed to @code{read} which it is supposed to use to construct the symbol table. Again, @value{GDBN}.