Re: [RFA] Add interface for registering JITed code

[Eli Zaretskii <eliz at gnu dot org>]

> From: Reid Kleckner <rnk@mit.edu>
> Date: Mon, 27 Jul 2009 13:40:02 -0700
> Cc: Tom Tromey <tromey@redhat.com>, gdb-patches@sourceware.org, 
> 	unladen-swallow@googlegroups.com
> 
> I mentioned the manual chapter in the NEWS entry, since the
> explanation of how it works is long.

Thanks.  I have a few comments.

> +* GDB now has an interface for JIT compilation.  Applications that
> +dynamically generate code can create symbol files in memory and register
> +them with GDB.  For users, the feature should work transparently, and
> +for JIT developers, the interface is documented in the GDB manual.

Please state the name of the chapter in the manual where this is
documented.

> +@node JIT Interface
> +@chapter @value{GDBN}'s JIT Interface

I think a better name is "JIT Compilation Interface".

Please add pertinent index entries here.  I suggest these:

  @cindex just-in-time compilation
  @cindex JIT compilation interface

> +This chapter documents @value{GDBN}'s just-in-time compiler (JIT) interface.

Whenever you introduce new terminology, first usage should be in @dfn,
to make the term stand out:

   This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT)
   compilation interface.

Also, how about saying a few words here about JIT compiling, for those
who maybe hear about that for the first time?  Just a sentence or two
would be good enough.

> +Just-in-time compilers (JITs) are normally difficult to debug because they

Are we talking about debugging a JIT compiler or about debugging a
program that uses a JIT compiler?  I thought the latter, but it sounds
like you are talking about the former here.

> +generate code at runtime, and GDB normally gets all of its symbols from object
                                 ^^^
"@value{GDBN}" (here and elsewhere).

> +files.

Does this rewording of the above sentence catch what you meant to say
(I'm not sure I understood)?

  Programs compiled with JIT compilers are normally difficult to debug
  because portions of their code are generated at runtime, and not
  written to object files, where @value{GDBN} normally finds the debug
  information it needs.

The rest of the text needs similar rewording, to make it more clear.
In particular, you use "JIT" meaning "a JIT compiler" and "executables
that use JIT" when you really mean "programs that use JIT
compilation".

If you can rephrase the text along the above guidelines, that'd be
great.  If not, go ahead and commit it with the few technical changes
I mention here, and I will do the rest.

> +    In order to debug executables that use JITs, GDB has an interface that
> +allows the JIT to register in-memory symbol files with GDB at runtime.  If you
> +are using GDB to debug a program using this interface, then it should just work
> +so long as you have not stripped the binary.  If you are developing a JIT, then
> +the interface is documented in the next section.  At this time, the only known
> +client of this interface is the LLVM JIT.

A question out of ignorance: are the special symbols you use to
interface with the JIT generated code specific to LLVM, or are they
part of some broader standard?  If the former, the instructions below
are actually instructions to develop other JIT compilers that follow
the LLVM conventions, and we are in effect committing GDB to force
these conventions on developers of JIT compilers, don't we?

> +@section Using the JIT Interface

Please make each @section also a @node.  (This will need a @menu be
added to the parent chapter.)  I would like to avoid sections that are
not nodes, because nodes make it easier to navigate the manual in a
structural way.

> +If the JIT recompiles code throughout its lifetime without unregistering it,
> +then GDB and the JIT will continue to use extra memory for these symbol files.

Does this simply say "don't recompile without unregistering, or you
will leak memory", or does it say something else?

Thanks.