This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [v4 2/2] multi-executable support
> From: Pedro Alves <pedro@codesourcery.com>
> Date: Thu, 3 Sep 2009 03:52:42 +0100
>
> 2009-09-03 Pedro Alves <pedro@codesourcery.com>
> Stan Shebs <stan@codesourcery.com>
>
> gdb/doc/
> * gdb.texinfo (Multiple Programs): New node.
> (Process): Rename node to...
> (Forks): ... this. Document "set|show follow-exec-mode". Add
> "info inferiors" example showing vfork parent/child relationships.
> (Inferiors) <info inferiors>: Mention the new 'SSpace' and 'Main
> Program' columns. Update example. Mention possible extra output
> below each inferior line.
>
Thanks. See my comments below.
> +@node Multiple Programs
> +@section Debugging Multiple Programs
As usual, it is a good idea to have at the beginning of a section a
@cindex entry resembling the section name. E.g., in this case
@cindex debugging multiple programs
> +@cindex inferior
I think this is too generic for the index. Suggest to qualify it:
@cindex inferior, when debugging multiple programs
Or, if we want this to be used in the generic sense, the definition
must be much earlier in the manual.
> +@cindex symbol space
Again, suggest to qualify; this is too generic when it stands alone in
the index.
> +To keep everything straight, @value{GDBN} represents a symbolic view
> +of an address space with an object called a @dfn{symbol space}. In
You introduce a term without explaining it (except saying that it's a
name of an opaque object), and then use it extensively. But "symbol
space" as a name of an opaque object is not a very good idea, because
it's too easy to make a mental shortcut and imagine that it's some
kind of "space of symbols". (A name that cannot possibly have a
semantic meaning on its own, such as "mumble", would not suffer from
this problem.) You then proceed talking about an address space, which
is clearly distinct in some way from the "symbol space":
> On embedded targets that may have several inferiors running in
> +different parts of a single address space, each inferior is still
> +bound to its own symbol space
This confuses things even more.
I guess I'm saying that you should explain more what is a "symbol
space", and how it ``represents a symbolic view of an address
space''. (What is a ``symbolic view''?)
Or maybe it is not important to understand that, in which case we
shouldn't be introducing this terminology. Can you tell me why it is
important for the user to see the "SSpace" column of "info inferiors",
and even know that we have symbol spaces under the hood?
> +the tradicional debugging scenario, there's a one-to-one
^^^^^^^^^^^
A typo.
> +You can get multiple executables into a debugging session via the
> +@code{add-symbol-space} command.
If this command ``gets executables into the session'', why its name
has no mnemonic references to any of these words?
> +@kindex add-symbol-space
> +@item add-symbol-space [ -copies @var{n} ] [ -exec @var{executable} ]
> +Adds @var{n} symbol spaces to be run using @var{exec} as the
^^^^^^^^^^
@var{executable}, I presume.
> +executable. @var{n} defaults to 1. If no executable is specified,
> +the symbol space begins empty. You can still load a program to the
> +symbol space by using e.g., the @code{file} command with the
> +executable name as its argument.
Egads! now I'm completely confused: ``symbol spaces to be run''? you
never said before a symbol space can run or be run.
> +@kindex clone-symbol-space
> +@item clone-symbol-space [ -copies @var{n} ] [ @var{ID} ]
> +Adds @var{n} symbol spaces to be run using the same executable as
> +symbol space @var{ID}. @var{n} defaults to 1.
We should explain in advance why such cloning is useful. You actually
never again speak of this command, so its utility is left unclear.
> +@smallexample
> +(@value{GDBP}) info sspaces
> + Id Main Program
> + 2 goodbye
> + Bound inferiors: ID 1 (process 21561)
> +* 1 hello
> +@end smallexample
> +
> +Here we can see that no inferior is running the program @code{hello},
> +while @code{process 21561} is running the program @code{goodbye}. On
> +some targets, it is possible that multiple inferiors are bound to the
> +same symbol space.
So "symbol space" is actually a synonym for a "program", i.e. the set
of code, data, and symbolic debug info that is the result of linking
an executable? then why not call it a "program"? I could easily
understand how several inferiors can run the same program at the same
time, you don't need to explain that.
In any case, the seemingly interchangeable use of these two here is
confusing, unless it is explained where you introduce "symbol space".
> +@kindex symbol-space
> +@item symbol-space @var{ID}
> +@itemx sspace @var{ID}
> +Set symbol space @var{ID} as the current symbol space.
What is an "ID"? earlier you talked about a "number".
Also, it's not a good idea to have the argument of @var be in caps, it
looks bad in print.
> If there's any
> +inferior bound the the symbol space, @value{GDBN} switches focus to a
> +thread of this inferior
What if there's more than one such inferior?
> +(@value{GDBP}) sspace 1
> +[Switching to thread 1]
Shouldn't this be "[Switching to sspace 1 (goodbye)]" ?
> +@code{exec} call replaces the process'es program image.
It's easier and less error-prone to say "replaces the program image of
the process".
> +@value{GDBN} reuses the process'es symbol space, and replaces its
"process'es" again; use "of the process" instead.
More importantly, what does it mean to ``reuse'' a symbol space? what
exactly is reused here?
> +(@value{GDBP}) run
> +process 12020 is executing new program: prog2
"program", "symbol space", "executable" -- do you see how using these
with similar, but somehow distinct meaning can be confusing for the
reader?
> +@item keep
> +@value{GDBN} keeps the current symbol space is kept unaltered so that
^^^^^^^
remove that
> +@value{GDBN} is capable of working with multiple programs at once, so
> +you have the option of adding executables instead of replacing them,
> +using commands such as @code{add-symbol-space} and @code{file}.
There should be a cross-reference here to where we describe these two
commands.
> +this can be useful, for instance to debug both client and server
> +programs from the same @value{GDBN}, it can also be confusing to have
> +several functions named @code{main}, several globals with the same
> +name but different values, and so forth. You may wish to try using a
> +separate @value{GDBN} instance for each program before deciding which
> +is the better approach.
Shouldn't this be in the section that describes multiple programs?
> + (a.k.a multi-exec) debugging. See "Debugging Multiple Inferiors"
"a.k.a.", the last dot is missing.