Re: Multiprocess GDB, formal spec

Re: Multiprocess GDB, formal spec

[Marc Khouzam]

Hi,

(side note, anyone know how I can keep a thread going, when I don't have
the original email?  Here, I'm trying to reply to
http://sourceware.org/ml/gdb/2008-08/msg00169.html , but I'm going to
end up creating a new thread :-( )


> On Wed, 13 Aug 2008 15:16:02 Stan Shebs wrote:
> The following writeup is a more formal specification for multiprocess
GDB. 
[...]
>
> * The GDB/MI Interface
> [TBD]
> 
> ** Planned limitations of the first version
> [...]
> The MI interface is not supported.

First let me say that I think the proposal (snipped out) is very
interesting and I'm looking forward
to the GDB version that will implement it :-)

Now, as a frontend developer, am I very interested with the MI support
for such features.
I was just wondering how come there were not more MI details included,
considering there
was already a post for Multiprocess MI extensions:
http://sourceware.org/ml/gdb/2008-06/msg00080.html

Furthermore, I find myself in a strange situation where I have been
working with a preliminary, 
non-public version of GDB which has some support for multi-process
through MI.  This support, will
eventually (I believe) makes its way to mainline GDB.  But until then, I
am not sure where
I can discuss/comment on my experience using the 'proposed' MI
extensions.  Because of
the intended use of MI, it greatly benefits from respecting
backwards-compatibility, which
implies that it would be beneficial to update/modify the multi-process
parts of MI, before
they are released officially.

As the multi-process work seems to be progressing quite well, I was
wondering if it was time to 
start looking at MI again?

Thanks

Marc

Re: Multiprocess GDB, formal spec

[Joel Brobecker]

> (side note, anyone know how I can keep a thread going, when I don't have
> the original email?  Here, I'm trying to reply to
> http://sourceware.org/ml/gdb/2008-08/msg00169.html , but I'm going to
> end up creating a new thread :-( )

There is a link at the top to the text-version of the mail (Other
format: [Raw text]). It's in mbox version, so you should be able
to import that email into your mailer.  I also keep a copy of
all emails sent to these mail-lists, so I can bounce you a copy of
the email if you tell me which one...

-- 
Joel

Re: Multiprocess GDB, formal spec

[Stan Shebs]

Marc Khouzam wrote:
>> On Wed, 13 Aug 2008 15:16:02 Stan Shebs wrote:
>> The following writeup is a more formal specification for multiprocess
>>     
> First let me say that I think the proposal (snipped out) is very
> interesting and I'm looking forward
> to the GDB version that will implement it :-)
>   
I have a set of patches applied to FSF GDB, and it generally works, but 
there are, uh, some regressions. :-) I wasn't going to make a branch for 
them pre-submission, but could be persuaded if everyone promises not to 
laugh at the code.
> Now, as a frontend developer, am I very interested with the MI support
> for such features.
> I was just wondering how come there were not more MI details included,
> considering there
> was already a post for Multiprocess MI extensions:
> http://sourceware.org/ml/gdb/2008-06/msg00080.html
>   
This goes back to the multi-exec / multi-process distinction.  Those MI 
extensions are for multiple-process single-executable debugging.  
Multiple executables introduces a whole new class of confusions, 
especially on the symbol side.
> Furthermore, I find myself in a strange situation where I have been
> working with a preliminary, 
> non-public version of GDB which has some support for multi-process
> through MI.  This support, will
> eventually (I believe) makes its way to mainline GDB.  But until then, I
> am not sure where
> I can discuss/comment on my experience using the 'proposed' MI
> extensions.  Because of
> the intended use of MI, it greatly benefits from respecting
> backwards-compatibility, which
> implies that it would be beneficial to update/modify the multi-process
> parts of MI, before
> they are released officially.
>   
This is the perfect place to discuss. It certainly wouldn't be the first 
time we've talked about features of GDB versions that we don't yet have 
in hand!
> As the multi-process work seems to be progressing quite well, I was
> wondering if it was time to 
> start looking at MI again?
>   
Yes, now would be a good time. I had to neglect MI due to time 
constraints on this project, but after people try their hand at juggling 
a half-dozen programs through the command line, I think an MI 
alternative is going to get considerable interest all of a sudden. :-)

Stan

RE: Multiprocess GDB, formal spec

[Marc Khouzam]

 

Stan Shebs wrote:
> Marc Khouzam wrote:
> >> On Wed, 13 Aug 2008 15:16:02 Stan Shebs wrote:
> >> The following writeup is a more formal specification for 
> multiprocess
> >>     
> > First let me say that I think the proposal (snipped out) is very
> > interesting and I'm looking forward
> > to the GDB version that will implement it :-)
> >   
> I have a set of patches applied to FSF GDB, and it generally 
> works, but 
> there are, uh, some regressions. :-) I wasn't going to make a 
> branch for 
> them pre-submission, but could be persuaded if everyone 
> promises not to 
> laugh at the code.

I wish I had more time to spend on this, but in my case,
such fun will have to wait until at least the new year...
But my interests in reading about developments remains :-)

> > Now, as a frontend developer, am I very interested with the 
> MI support
> > for such features.
> > I was just wondering how come there were not more MI 
> details included,
> > considering there
> > was already a post for Multiprocess MI extensions:
> > http://sourceware.org/ml/gdb/2008-06/msg00080.html
> >   
> This goes back to the multi-exec / multi-process distinction. 
>  Those MI 
> extensions are for multiple-process single-executable debugging.  
> Multiple executables introduces a whole new class of confusions, 
> especially on the symbol side.

Maybe some extentions to the MI extensions is the way to go :-)

> > Furthermore, I find myself in a strange situation where I have been
> > working with a preliminary, 
> > non-public version of GDB which has some support for multi-process
> > through MI.  This support, will
> > eventually (I believe) makes its way to mainline GDB.  But 
> until then, I
> > am not sure where
> > I can discuss/comment on my experience using the 'proposed' MI
> > extensions.  Because of
> > the intended use of MI, it greatly benefits from respecting
> > backwards-compatibility, which
> > implies that it would be beneficial to update/modify the 
> multi-process
> > parts of MI, before
> > they are released officially.
> >   
> This is the perfect place to discuss. It certainly wouldn't 
> be the first 
> time we've talked about features of GDB versions that we 
> don't yet have 
> in hand!

Great!

> > As the multi-process work seems to be progressing quite well, I was
> > wondering if it was time to 
> > start looking at MI again?
> >   
> Yes, now would be a good time. I had to neglect MI due to time 
> constraints on this project, but after people try their hand 
> at juggling 
> a half-dozen programs through the command line, I think an MI 
> alternative is going to get considerable interest all of a sudden. :-)

And I'm hoping we can get DSF-GDB to support this quickly after.

So, the good news is that the proposed MI extensions posted by Volodya
http://sourceware.org/ml/gdb/2008-06/msg00080.html 
are quite good and provide almost all of what I needed for the frontend.

The missing part (which triggered this post), is the support for the
'focus' command described in this specification.   For multi-process, 
there are commands which apply to a process in general but no 
specific thread.  It seems like 'focus' would allow GDB to know which 
process those commands should affect.  Is this correct?

For non-stop, MI was enhanced quite nicely with the --thread/--frame
generic options.  From what I have experienced in adapting DSF-GDB for
mutli-process, it would be good to have a similar generic way to specify
the process (if no thread is specified.)

In a previous post, Pawel suggested to use the same name space to
describe
processes and threads.  That way, the --thread option could be used with
either
a thread or a process, in a very generic fashion.

For example, in the case of multiple-processes and reading memory, a
user
may simply request to read the memory of a specific process at an
address, 
without specifying any thread.  It would be nice to be able to specify
this in MI.

One of the issues is that it does not seem entirely clear (maybe just to
me),
what set of commands will eventually apply to a process only.

Thanks

Marc

RE: Multiprocess GDB, formal spec

[Marc Khouzam]

> From: Stan Shebs [mailto:stan@codesourcery.com] 
> Sent: Monday, October 20, 2008 11:53 AM
> 
> I have a set of patches applied to FSF GDB, and it generally 
> works, but there are, uh, some regressions. :-) 

Do you think this work will make it to HEAD before March next year?

> > As the multi-process work seems to be progressing quite well, I was
> > wondering if it was time to 
> > start looking at MI again?
> >   
> Yes, now would be a good time. I had to neglect MI due to time 
> constraints on this project, but after people try their hand 
> at juggling 
> a half-dozen programs through the command line, I think an MI 
> alternative is going to get considerable interest all of a sudden. :-)

So does Vladimir and/or yourself have plans for MI to be enhanced
correspondingly
by the time this feature makes it into HEAD?

Thanks for your input

Marc

Re: Multiprocess GDB, formal spec

[Stan Shebs]

Marc Khouzam wrote:
>> From: Stan Shebs [mailto:stan@codesourcery.com] 
>> Sent: Monday, October 20, 2008 11:53 AM
>>
>> I have a set of patches applied to FSF GDB, and it generally 
>> works, but there are, uh, some regressions. :-) 
>>     
>
> Do you think this work will make it to HEAD before March next year?
>   
I hope so! I'm down to about three main breakages to fix, and we have a 
design decision to make, namely whether to have a single target stack 
shared by multiple inferiors, or make multiple instances of the target 
stack.
>>> As the multi-process work seems to be progressing quite well, I was
>>> wondering if it was time to 
>>> start looking at MI again?
>>>   
>>>       
>> Yes, now would be a good time. I had to neglect MI due to time 
>> constraints on this project, but after people try their hand 
>> at juggling 
>> a half-dozen programs through the command line, I think an MI 
>> alternative is going to get considerable interest all of a sudden. :-)
>>     
>
> So does Vladimir and/or yourself have plans for MI to be enhanced
> correspondingly
> by the time this feature makes it into HEAD?
>   
Not me, at the moment anyway. It's a little too big to sneak in amongst 
my for-pay projects. :-)

Stan

Getting old emails from mailing list (was:RE: Multiprocess GDB, formal spec)

[Marc Khouzam]

Sorry to those that know this already.  See below.

> -----Original Message-----
> From: Joel Brobecker [mailto:brobecker@adacore.com] 
> Sent: Monday, October 20, 2008 11:38 AM
> To: Marc Khouzam
> Cc: gdb@sourceware.org
> Subject: Re: Multiprocess GDB, formal spec
> 
> > (side note, anyone know how I can keep a thread going, when 
> I don't have
> > the original email?  Here, I'm trying to reply to
> > http://sourceware.org/ml/gdb/2008-08/msg00169.html , but 
> I'm going to
> > end up creating a new thread :-( )
> 
> There is a link at the top to the text-version of the mail (Other
> format: [Raw text]). It's in mbox version, so you should be able
> to import that email into your mailer.  I also keep a copy of
> all emails sent to these mail-lists, so I can bounce you a copy of
> the email if you tell me which one...

I just found out you can request the mailing list to send you old
copies of an email!  Then you can reply to that and keep the thread
going.  This is what I'm doing right now (but maybe changing the
subject will screw it up..., let's see).

(To find a message number, use the [Raw text] link on the web interface.
The number is on the first line)

==
To get messages 123 through 145 (a maximum of 100 per request), mail:
   <gdb-get.123_145@sourceware.org>

To get an index with subject and author for messages 123-456 , mail:
   <gdb-index.123_456@sourceware.org>

They are always returned as sets of 100, max 2000 per request,
so you'll actually get 100-499.

To receive all messages with the same subject as message 12345,
send an empty message to:
   <gdb-thread.12345@sourceware.org>
==

Marc

Re: Getting old emails from mailing list (was:RE: Multiprocess GDB, formal spec)

[Christopher Faylor]

On Thu, Dec 03, 2009 at 09:55:15AM -0500, Marc Khouzam wrote:
>Sorry to those that know this already.  See below.
>
>> -----Original Message-----
>> From: Joel Brobecker
>> Sent: Monday, October 20, 2008 11:38 AM
>> To: Marc Khouzam
>> Subject: Re: Multiprocess GDB, formal spec
>> 
>> > (side note, anyone know how I can keep a thread going, when 
>> I don't have
>> > the original email?  Here, I'm trying to reply to
>> > http://sourceware.org/ml/gdb/2008-08/msg00169.html , but 
>> I'm going to
>> > end up creating a new thread :-( )
>> 
>> There is a link at the top to the text-version of the mail (Other
>> format: [Raw text]). It's in mbox version, so you should be able
>> to import that email into your mailer.  I also keep a copy of
>> all emails sent to these mail-lists, so I can bounce you a copy of
>> the email if you tell me which one...
>
>I just found out you can request the mailing list to send you old
>copies of an email!  Then you can reply to that and keep the thread
>going.  This is what I'm doing right now (but maybe changing the
>subject will screw it up..., let's see).
>
>(To find a message number, use the [Raw text] link on the web interface.
>The number is on the first line)
>
>==
>To get messages 123 through 145 (a maximum of 100 per request), mail:
>   <gdb-get.123_145@sourceware.org>
>
>To get an index with subject and author for messages 123-456 , mail:
>   <gdb-index.123_456@sourceware.org>
>
>They are always returned as sets of 100, max 2000 per request,
>so you'll actually get 100-499.
>
>To receive all messages with the same subject as message 12345,
>send an empty message to:
>   <gdb-thread.12345@sourceware.org>

That doesn't always work because the mailing list archives are not always
complete.

FYI.

cgf

RE: Multiprocess GDB, formal spec

[Marc Khouzam]

Sorry again, just testing my theory about keeping a thread 
going from my previous post:
http://sourceware.org/ml/gdb/2009-12/msg00020.html
(didn't work when I changed the subject; I'm trying to see
if it works with the same subject)

> -----Original Message-----
> From: Joel Brobecker [mailto:brobecker@adacore.com] 
> Sent: Monday, October 20, 2008 11:38 AM
> To: Marc Khouzam
> Cc: gdb@sourceware.org
> Subject: Re: Multiprocess GDB, formal spec
> 
> > (side note, anyone know how I can keep a thread going, when 
> I don't have
> > the original email?  Here, I'm trying to reply to
> > http://sourceware.org/ml/gdb/2008-08/msg00169.html , but 
> I'm going to
> > end up creating a new thread :-( )
> 
> There is a link at the top to the text-version of the mail (Other
> format: [Raw text]). It's in mbox version, so you should be able
> to import that email into your mailer.  I also keep a copy of
> all emails sent to these mail-lists, so I can bounce you a copy of
> the email if you tell me which one...
> 
> -- 
> Joel
> 

RE: Multiprocess GDB, formal spec

[Marc Khouzam]

Bummer. Last test.

Re: Multiprocess GDB, formal spec

[Christopher Faylor]

On Thu, Dec 03, 2009 at 10:05:11AM -0500, Marc Khouzam wrote:
>Bummer. Last test.

Please don't use the mailing list as your test bed.

If you want to continue a discussion then either just change the subject
or, if you want to be really complete, add an In-Reply-To.

cgf

Re: Multiprocess GDB, formal spec

[Tom Tromey]

>>>>> "Stan" == Stan Shebs <stan@codesourcery.com> writes:

Stan> set args <arg> ...
Stan> set environment <arg> ...

It occurred to me today that "set target-charset" will also have to be
per-inferior.

I am not sure if you were trying to make an exhaustive list here or
not, but figured it was better to mention it than not.

Note that this has some weird implications.  Suppose you are debugging
two running instances of "program", each with a different target
charset.  And suppose you set a breakpoint somewhere in that program,
and that breakpoint's condition uses a string.

Right now, gdb converts to the target charset early -- while parsing.
However, in this case, you would actually want to do the conversion
lazily.  (Lazy would be better anyhow, since target-charset can be
changed by the user at any time.)

These are rather obscure scenarios.

Tom

Re: Multiprocess GDB, formal spec

[Stan Shebs]

Tom Tromey wrote:
>>>>>> "Stan" == Stan Shebs <stan@codesourcery.com> writes:
>>>>>>             
>
> Stan> The following writeup is a more formal specification for
> Stan> multiprocess GDB.
>
> I read this.  I like it a lot.
>
> I have a few comments -- nothing too major though.
>
> Stan> The command-line syntax for inferior/thread sets is '[<spec>]', where
> Stan> <spec> may take several forms.
>
> I know this comes from HPD.  I wonder if maybe "inferior apply" would
> be more gdb-ish?  Or even just "focus [itset] command"?  (I sort of
> hesitate to mention this, due to its bikesheddy nature.  If it helps I
> dropped most of my commentary on the names of other things :-)
>   
One of things I noticed about thread apply is that it really depends on 
threads being numbered, whereas inferiors in general can be named or 
numbered. So we're going to get roped into some sort of alternate syntax 
one way or another. This is the right time to talk about syntax in any 
case, don't want future generations cursing us because we saddled them 
with something lame. :-)
> Stan> [<name>]
> Stan> Specifies the named itset <name>.
> Stan> [<exec>]
> Stan> Specifies the default inferior corresponding to the program named <exec>.
>
> I'm a bit cautious here due to possible ambiguities.
>   
Yeah, I imagine we can set up a reasonable priority rule, such as "itset 
names first" - execs can always be referred to by partial path if an 
itset name manages to mask one. I don't have any intuition about a best 
rule.
> Perhaps we don't care since names are assigned by the user.. ?
>
> Do we want an explicit name for the current itset?
>   
One would think so - oddly, I can't seem to find any notation for it in 
the HPD spec. (Perhaps because it's always implicit?)
> But actually, this is kind of a weird area.  Should a breakpoint
> command be able to change the focus for the CLI?  Or should the
> commands push a focus, then pop it after the commands are done?
>   
An interesting question...
> ISTR some other thread touching this topic recently.
>
> Stan> set follow_exec true
>
> Maybe a "-" instead of "_", for consistency with follow-fork?
>   
I scrubbed follow-exec, Pedro showed me it was a brain cramp. :-)
> Stan> For instance, "break main" can cause every program under GDB's
> Stan> control to stop soon after it starts; to break in only some
> Stan> executables, the syntax "break #<inf>#main" would be necessary.
>
> I am curious how I would go about setting a breakpoint in an inferior
> that doesn't exist yet.
>
> E.g., suppose I want to run gcc and break at a function in cc1.  Would
> I "add-file /dir/cc1" and then "break #cc1#function"?  And then gdb
> would hold this as a kind of pending breakpoint until a cc1 actually
> starts?
>   
Pending breakpoint seems right, that way you don't have to know ahead of 
time which of the many cc1's lying around is going to be the one that 
gets executed.
> Stan> [TBD: have a way to delete "locations" from a breakpoint? too
> Stan> complicated?]
>
> If we had a name for the current itset, you could do:
>
>     [all] break #[current]#main
>
> ... to set individual breakpoints on each main.  That would make each
> one individually manipulable.
>   
That assumes the prefix syntax temporarily alters the current itset from 
the user has been using. It's almost like one wants a [this] itset, that 
automagically consists of the one inferior that is the iterator in the 
prefix syntax.
> Stan> When one of the inferiors/threads stops, GDB sets the current
> Stan> itset to consist of just the inferior and thread that actually
> Stan> stopped. The user is free to change the focus thereafter.
>
> I wonder about the UI here.  Suppose I am debugging many programs, all
> running async.  And, I have my focus on one particular one, which I
> have stopped.  Then, some background program hits a breakpoint.
>
> In this case, I am already typing away at the gdb prompt -- so, having
> the itset change immediately would seem unfriendly.  I could easily
> end up typing commands at an inferior other than the one I thought I
> was working on.
>
> So, maybe in the async case gdb should just print a notification, e.g.:
>
>     Inferior stopped, type "focus 5" to focus.
>
> I don't think this is a problem if programs are running synchronously.
> In fact there it would be better to set the focus automatically when
> the inferior stops, just because that is what everybody is used to.
>   
That sounds right, I'll incorporate.
> Stan> info program
> Stan> Displays the status of each inferior currently in existence, including
> Stan> whether it is stopped and why.
>
> Is this different from "info inferior"?
>   
I'm thinking of "info inferior" as displaying all inferiors, including 
those that are setting up argument lists but not have run yet, while 
"info program" is a generalization of the current behavior, displaying 
only inferiors that have started execution but not finished.

Stan

Re: Multiprocess GDB, formal spec

[Tom Tromey]

>>>>> "Stan" == Stan Shebs <stan@codesourcery.com> writes:

Stan> The following writeup is a more formal specification for
Stan> multiprocess GDB.

I read this.  I like it a lot.

I have a few comments -- nothing too major though.

Stan> The command-line syntax for inferior/thread sets is '[<spec>]', where
Stan> <spec> may take several forms.

I know this comes from HPD.  I wonder if maybe "inferior apply" would
be more gdb-ish?  Or even just "focus [itset] command"?  (I sort of
hesitate to mention this, due to its bikesheddy nature.  If it helps I
dropped most of my commentary on the names of other things :-)

Stan> [<name>]
Stan> Specifies the named itset <name>.
Stan> [<exec>]
Stan> Specifies the default inferior corresponding to the program named <exec>.

I'm a bit cautious here due to possible ambiguities.

Perhaps we don't care since names are assigned by the user.. ?

Do we want an explicit name for the current itset?

Stan> [TBD: Allow '[]' to be optional when it is unambiguous, as in
Stan> focus command?]

Yeah, I think so, at least as long as that is all that "focus" does.

Stan> focus <itset>
Stan> Sets the effect of subsequent commands to apply only to the inferiors
Stan> and threads in the given itset. This set is known as the "current" itset.

I think there has to be an implicit focus around breakpoint commands
(this comes a bit later in the spec).

But actually, this is kind of a weird area.  Should a breakpoint
command be able to change the focus for the CLI?  Or should the
commands push a focus, then pop it after the commands are done?

ISTR some other thread touching this topic recently.

Stan> set follow_exec true

Maybe a "-" instead of "_", for consistency with follow-fork?

Stan> For instance, "break main" can cause every program under GDB's
Stan> control to stop soon after it starts; to break in only some
Stan> executables, the syntax "break #<inf>#main" would be necessary.

I am curious how I would go about setting a breakpoint in an inferior
that doesn't exist yet.

E.g., suppose I want to run gcc and break at a function in cc1.  Would
I "add-file /dir/cc1" and then "break #cc1#function"?  And then gdb
would hold this as a kind of pending breakpoint until a cc1 actually
starts?

Stan> [TBD: have a way to delete "locations" from a breakpoint? too
Stan> complicated?]

If we had a name for the current itset, you could do:

    [all] break #[current]#main

... to set individual breakpoints on each main.  That would make each
one individually manipulable.

Stan> When one of the inferiors/threads stops, GDB sets the current
Stan> itset to consist of just the inferior and thread that actually
Stan> stopped. The user is free to change the focus thereafter.

I wonder about the UI here.  Suppose I am debugging many programs, all
running async.  And, I have my focus on one particular one, which I
have stopped.  Then, some background program hits a breakpoint.

In this case, I am already typing away at the gdb prompt -- so, having
the itset change immediately would seem unfriendly.  I could easily
end up typing commands at an inferior other than the one I thought I
was working on.

So, maybe in the async case gdb should just print a notification, e.g.:

    Inferior stopped, type "focus 5" to focus.

I don't think this is a problem if programs are running synchronously.
In fact there it would be better to set the focus automatically when
the inferior stops, just because that is what everybody is used to.

Stan> info program
Stan> Displays the status of each inferior currently in existence, including
Stan> whether it is stopped and why.

Is this different from "info inferior"?

Stan> ** Planned limitations of the first version

Thanks for being explicit about this.

Tom

Multiprocess GDB, formal spec

[Stan Shebs]

[-- Attachment #1: Type: text/plain, Size: 593 bytes --]

The following writeup is a more formal specification for multiprocess 
GDB. It incorporates feedback from recent discussion, the results of my 
experimentation with a prototype, and bits from the HPD draft standard. 
Although there is a lot here, I wanted to lay out some longer-term 
direction so as to clarify how the immediate work fits into the big 
picture - the last section delimits what the first version will actually 
do, which is not much more than what I was able to get working in a 
couple weeks of prototyping (read: we have reason to believe it's 
implementable :-) ).

Stan



[-- Attachment #2: mpgdb-spec --]
[-- Type: text/plain, Size: 10953 bytes --]

This is a behavioral specification for multiprocess/multiprogram
GDB. This specification is phrased in terms of user-visible behavior,
and generally organized according to the format of the GDB manual.

There is a technical distinction to be made between the term
"multiprogram" and "multiprocess".  Most precisely, "multiprogram" or
"multiexec" refers to the ability to work with several different
executables at the same time within a debugging session. (Currently,
GDB can only handle one at a time; a command bringing in an
executable, such as "file", causes the previous one to be removed.)
Conversely, the term "multiprocess" is appropriate when GDB has
several inferiors, which may or may not be associated with the same
executable. However, since the two are being implemented together, the
distinction will not be important to users.

This spec borrows liberally from the HPD draft standard.

Definitions

Exec: Short for executable program, which is defined as a file that
contains a program which may be run independently of other programs.

Program: Synonym for exec. (Informally, "program" is preferable for
user documentation, while "exec" is preferable for GDB internals
documentation.)

Inferior: A GDB object representing a futurely-, currently- or
formerly-running program. There must be an inferior for each execution
of each program. (Informally, an inferior corresponds to a process or
corefile.)

Address space: A GDB object providing an interpretation of a
CORE_ADDR. Execs and inferiors each have at least one address space,
and may have several, with contents distinguished in a target-specific
way. Multiple execs and inferiors may share an address space.

Thread: A single locus of control within an inferior.

Inferior/thread set: A collection of inferiors and/or threads,
abbreviated "itset".

Generalities

Basic multiprogram and multiprocess support in GDB will be
automatically available in every version of GDB; there will be no
special configuration flags or compiletime options. Support for
simultaneous control of multiple inferiors will typically require
target-specific additions, and so some targets may not include these
additions; GDB will warn but do nothing else if the user attempts to
run more than one inferior at a time on these targets.

GDB's behavior in the case of one program and one inferior will be the
same as formerly, with the possible exception of some rarely-seen edge
cases.

* Inferiors and inferior sets

An inferior object is a representation of a single program run. While
conceptually similar to a Unix process, it is more general; an
inferior may be created before a program starts running, and it may
continue to exist after the program exits.

Running or attaching to a program creates an inferior if one does not
exist for the program already. The default name of the inferior
depends on the target, but is typically a number corresponding to
process id.

The syntax for symbols and source lines is extended to allow reference
to specific inferiors. An inferior-specific symbol reference is
'#<inf>#<symbol>', while a general source line reference has the form
'#<inf>#<source>:<line>'. If an inferior is not specified, GDB will
use a most logical inferior, such as the last one used, or one from
the current itset.

An inferior/thread set is a collection of inferiors and threads within
those inferiors. Itsets may enumerate their members explicitly, or be
determined dynamically; for instance, the itset named "all"
automatically includes all inferiors and all threads. Itsets may have
names.

The command-line syntax for inferior/thread sets is '[<spec>]', where
<spec> may take several forms.

[<name>]

Specifies the named itset <name>.

[<name>]

Specifies the inferior named <name> (which may be a number).

[<exec>]

Specifies the default inferior corresponding to the program named <exec>.

[<spec1>,<spec2>,<spec3>,...]

Specifies the union of the itsets specified by speci.

[<inf>.<thread>]

Specifies thread <thread> of inferior <inf>. Both <inf> and <thread>
may be '*', which specifies all of each.

[all]

Specifies all inferiors and all threads.

[TBD: Allow '[]' to be optional when it is unambiguous, as in focus command?]

focus <itset>

Sets the effect of subsequent commands to apply only to the inferiors
and threads in the given itset. This set is known as the "current" itset.

It will be possible to create inferiors manually. This will be useful
to set up complicated runs involving multiple instances of execs.

add-inferior <exec> [-copies <n>] [-name <name>]

Creates <n> (default 1) inferiors, all associated with the exec <exec>. The
inferiors will be numbered consecutively, with <name> as a common
prefix if specified.

remove-inferior <itset>

Deletes the inferiors included in <itset>. Autogenerated inferiors,
such as for execs, cannot be removed manually, but will go away when
the associated exec or other object is removed.

name-inferior <oldname> <newname>

Change the inferior named <oldname> to have the name <newname>.

info inferiors

Lists all inferiors in existence.

<itset> <cmd> <args> ...

Apply <cmd> <args> to everything in <itset>.

* Invoking GDB

GDB will allow multiple programs to be specified on the command line.
The basic form will be

    gdb prog1 prog2 prog3 ...

If progi is recognized as a core file, then GDB will take it as a core
file corresponding to the most recently specified executable; it will
be an error if the previous argument is not an executable. Similarly,
if progi is a decimal number, GDB will interpret it as a process id,
corresponding to the last executable specified.

For instance,

    gdb prog1 core1 prog2 core2

sets up to debug two programs prog1 and prog2, each with a
corresponding core file. Conversely,

     gdb prog1 prog2 core1 core2

sets up to debug prog1 and two crashes of prog2, each with its own
core file.

For the sake of compatibility, the options -exec, -symbols, and -core
will clear the list of files already seen on the command line, and
replace them with the single file that is supplied with the option.
(This is so that "gdb -exec foo -exec bar" continues to work as
before.)

* Running Programs under GDB

The run command will run all the execs in the current itset. The
arguments to run will be passed to all execs; if no arguments are
supplied, then the arguments will be those associated with the exec's
inferior; either those set manually with "set args", or the same
arguments as used in the previous run.

attach <pid1> ...

Attaches to each process listed, and creates an inferior named after the pid.

detach [<itset>]

Detaches from each process mentioned in the optional <itset>. If
<itset> is omitted, GDB will detach from all process in the current
itset.

kill [<itset>]

Kills each process included in the optional <itset>. If <itset> is
omitted, GDB will attempt to kill every process in the current itset.

set args <arg> ...

Set the list of arguments to be used the next time any of the
inferiors in the current itset starts.

set environment <arg> ...

Similarly, for the environment.

set follow-fork-mode both

On targets that support process forking, lets the developer choose to
include both parent and child of a fork as processes being debugged.

set follow_exec true

On targets that support process exec'ing, lets the developer debug
processes created via exec/execl.

* Stopping and Continuing

Breakpoints, watchpoints, etc, are intrinsically global; any given
breakpoint may apply to a number of locations in each of several
executables. For instance, "break main" can cause every program under
GDB's control to stop soon after it starts; to break in only some executables,
the syntax "break #<inf>#main" would be necessary.

[TBD: have a way to delete "locations" from a breakpoint? too complicated?]

By default, the break and watch commands only associates a breakpoint
with members of the current itset.

Step only affects a single inferior, while continue may cause one or
all inferiors to resume execution. When one of the inferiors/threads
stops, GDB sets the current itset to consist of just the inferior and
thread that actually stopped. The user is free to change the focus
thereafter.

info program

Displays the status of each inferior currently in existence, including
whether it is stopped and why.

* Examining the Stack

By default, the backtrace and frame commands apply only to the current
thread in the current itset.

[TBD: Extend frame command syntax to #<inf>#<n> ? ]

* Examining Source Files

By default, an argument to the list command is interpreted as
referring to the first exec found in the current itset. An argument
may be prefixed with the '#' syntax designating a particular inferior.

* Examining Data

By default, the expression given to a print command is evaluated
relative to each member of the current itset. If there are multiple
threads and/or inferiors, each distinct value is printed separately,
prefixed by an itset spec showing which threads and/or inferiors
yielded that value.

* GDB Files

file <file>  ...
exec-file <exec-file> ...
symbol-file <symbol-file> ...

Replace all files/exec files/symbol files with the given file(s).

add-file <file> ...

Adds <file> arguments to the list of executables and to the list of symbol files.

remove-file <fileids>

Removes <file> from the list of executables and from the list of symbol files.

info files

Lists all the execs that are being debugged.

add-exec-file <exec-file> ...

Adds <exec-file> to the list of executables being debugged.

remove-exec-file <execids>

Removes <exec-file> from the list of executables being debugged.

* Specifying a Debugging Target

Targets will need internal changes in order to support multiple inferiors,
but they need not change in any user-visible way.

The remote protocol will optionally send and receive id's identifying
the inferior to which each packet applies. Packets not identifying an
inferior will be assumed to refer to the current itset; if the current
itset contains more than one inferior, then they will be assumed to be
sharing the same address space.

* The GDB/MI Interface

[TBD]

** Planned limitations of the first version

The proposed set of extensions is a considerable amount of work, too
much to be done all at once. This section suggests a set of
limitations on the general capability that still yield a usable
multiprocess debugger.

The itset prefix to commands is not implemented.

Definition of named itsets is not supported.

The focus command only allows sets consisting of a single exec, and
focus in general is only on one inferior.

The attach command takes only one pid. The detach and kill commands take no arguments.

All inferiors must use the same target stack. (All remote, all native, etc)

The "both" follow-fork-mode and the follow-exec options are not available.

The file etc commands do not take multiple arguments.

The MI interface is not supported.