From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21400 invoked by alias); 3 Sep 2009 18:31:00 -0000 Received: (qmail 21384 invoked by uid 22791); 3 Sep 2009 18:30:59 -0000 X-SWARE-Spam-Status: No, hits=0.5 required=5.0 tests=AWL,BAYES_00,J_CHICKENPOX_37,J_CHICKENPOX_72,RCVD_IN_JMF_BL,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout6.012.net.il (HELO mtaout6.012.net.il) (84.95.2.16) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 03 Sep 2009 18:30:48 +0000 Received: from conversion-daemon.i-mtaout6.012.net.il by i-mtaout6.012.net.il (HyperSendmail v2007.08) id <0KPE00600QDXXB00@i-mtaout6.012.net.il> for gdb-patches@sourceware.org; Thu, 03 Sep 2009 21:30:44 +0300 (IDT) Received: from HOME-C4E4A596F7 ([84.228.144.38]) by i-mtaout6.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KPE00299RF5ESA0@i-mtaout6.012.net.il>; Thu, 03 Sep 2009 21:30:43 +0300 (IDT) Date: Thu, 03 Sep 2009 18:31:00 -0000 From: Eli Zaretskii Subject: Re: [v4 2/2] multi-executable support In-reply-to: <200909030352.43203.pedro@codesourcery.com> To: Pedro Alves Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83pra7992c.fsf@gnu.org> References: <200909030349.38319.pedro@codesourcery.com> <200909030352.43203.pedro@codesourcery.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: 2009-09/txt/msg00084.txt.bz2 > From: Pedro Alves > Date: Thu, 3 Sep 2009 03:52:42 +0100 > > 2009-09-03 Pedro Alves > Stan Shebs > > 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) : 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.