Patchwork [v7,7/7] Extended-remote follow fork documentation

login
register
mail settings
Submitter Don Breazeal
Date April 10, 2015, 5:09 p.m.
Message ID <1428685786-18094-8-git-send-email-donb@codesourcery.com>
Download mbox | patch
Permalink /patch/6146/
State New
Headers show

Comments

Don Breazeal - April 10, 2015, 5:09 p.m.
This patch contains the accumulated documentation changes for the
rest of the extended-remote follow fork patchset.

[Eli, you have reviewed parts of this before, but there are some new
bits as well.  Sorry for all the iterations.]

Thanks
--Don

gdb/
2015-04-08  Don Breazeal  <donb@codesourcery.com>

	* NEWS: Announce fork support in the RSP and support
	  for fork debugging in extended mode.

gdb/doc/
2015-04-08  Don Breazeal  <donb@codesourcery.com>

	* gdb.texinfo (Forks): Note that fork debugging is 
	  supported in extended mode.
	  (Remote Configuration): Add fork event features to table
	  of packet settings.
	  (Stop Reply Packets): Add fork events to list of stop reasons.
	  (General Query Packets): Add fork events to tables of
	  'gdbfeatures' and 'stub features' supported in the qSupported
	  packet, as well as to the list containing stub feature
	  details.

---
 gdb/NEWS            | 24 ++++++++++++++++
 gdb/doc/gdb.texinfo | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)
Eli Zaretskii - April 10, 2015, 5:56 p.m.
> From: Don Breazeal <donb@codesourcery.com>
> Date: Fri, 10 Apr 2015 10:09:46 -0700
> 
> This patch contains the accumulated documentation changes for the
> rest of the extended-remote follow fork patchset.

Thanks.

>  gdb/NEWS            | 24 ++++++++++++++++

This part is OK.

> +@cindex fork events, remote reply
> +@item fork
> +The packet indicates that @code{fork} was called, and @var{r}

What does that @var{r} refer to?  The previous text mentions
@var{n}:@var{r} pairs, but there's no @var{n} in this description, so
it doesn't seem to fit.  What am I missing?

> +shared. The @var{r} part is ignored.  This packet is only
         ^^
Two spaces.

OK with those fixed.
Don Breazeal - April 10, 2015, 6:15 p.m.
On 4/10/2015 10:56 AM, Eli Zaretskii wrote:
>> From: Don Breazeal <donb@codesourcery.com>
>> Date: Fri, 10 Apr 2015 10:09:46 -0700
>>

> 
>> +@cindex fork events, remote reply
>> +@item fork
>> +The packet indicates that @code{fork} was called, and @var{r}
> 
> What does that @var{r} refer to?  The previous text mentions
> @var{n}:@var{r} pairs, but there's no @var{n} in this description, so
> it doesn't seem to fit.  What am I missing?

Maybe I'm the one who is missing something.  I thought that the @var{n}
was implied by '@item fork', because of this text above:

  If @var{n} is a recognized @dfn{stop reason},

In this case @var{n} is a stop reason.  Subsequently '@item fork' is in
this table:

  The currently defined stop reasons are:

  @table @samp

I pretty much just copied what had been done for shared library events
in the same table.  Should I do this differently?  I see that swbreak
and hwbreak aren't the same as the other items.

Thanks
--Don
Eli Zaretskii - April 10, 2015, 6:29 p.m.
> Date: Fri, 10 Apr 2015 11:15:30 -0700
> From: "Breazeal, Don" <donb@codesourcery.com>
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> 
> >> +@cindex fork events, remote reply
> >> +@item fork
> >> +The packet indicates that @code{fork} was called, and @var{r}
> > 
> > What does that @var{r} refer to?  The previous text mentions
> > @var{n}:@var{r} pairs, but there's no @var{n} in this description, so
> > it doesn't seem to fit.  What am I missing?
> 
> Maybe I'm the one who is missing something.  I thought that the @var{n}
> was implied by '@item fork', because of this text above:
> 
>   If @var{n} is a recognized @dfn{stop reason},

Sheesh! 2 pages ago...

> In this case @var{n} is a stop reason.  Subsequently '@item fork' is in
> this table:
> 
>   The currently defined stop reasons are:
> 
>   @table @samp
> 
> I pretty much just copied what had been done for shared library events
> in the same table.  Should I do this differently?  I see that swbreak
> and hwbreak aren't the same as the other items.

Never mind, let's leave it as it is.

Thanks.

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 884c381..730b965 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -101,6 +101,30 @@  hwbreak stop reason
 vFile:fstat:
   Return information about files on the remote system.
 
+fork stop reason
+  Indicates that a fork system call was executed.
+
+vfork stop reason
+  Indicates that a vfork system call was executed.
+
+vforkdone stop reason
+  Indicates that a vfork child of the specified process has executed
+  an exec or exit, allowing the vfork parent to resume execution.
+
+fork-events and vfork-events features in qSupported
+  The qSupported packet allows GDB to request support for fork and 
+  vfork events using new 'gdbfeatures' fork-events and vfork-events,
+  and the qSupported response can contain the corresponding
+  'stubfeatures'.  Set and show commands can be used to display
+  whether these features are enabled.
+
+* Extended-remote fork events
+
+  ** GDB now has support for fork events on extended-remote Linux
+     targets.  For targets with Linux kernels 2.5.60 and later, this
+     enables follow-fork-mode and detach-on-fork for both fork and
+     vfork, as well as fork and vfork catchpoints.
+
 * The info record command now shows the recording format and the
   branch tracing configuration for the current thread when using
   the btrace record target.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d794893..4ecbd11 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3142,6 +3142,9 @@  create additional processes using the @code{fork} or @code{vfork} functions.
 Currently, the only platforms with this feature are HP-UX (11.x and later
 only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
 
+The fork debugging commands are supported in both native mode and when
+connected to @code{gdbserver} using @kbd{target extended-remote}.
+
 By default, when a program forks, @value{GDBN} will continue to debug
 the parent process and the child process will run unimpeded.
 
@@ -19848,6 +19851,14 @@  are:
 @tab @code{hwbreak stop reason}
 @tab @code{hbreak}
 
+@item @code{fork-event-feature}
+@tab @code{fork stop reason}
+@tab @code{fork}
+
+@item @code{vfork-event-feature}
+@tab @code{vfork stop reason}
+@tab @code{vfork}
+
 @end multitable
 
 @node Remote Stub
@@ -35286,6 +35297,45 @@  The @var{r} part must be left empty.
 
 The same remarks about @samp{qSupported} and non-stop mode above
 apply.
+
+@cindex fork events, remote reply
+@item fork
+The packet indicates that @code{fork} was called, and @var{r}
+is the ptid of the new child process.  This packet is only
+applicable to targets that support fork events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it.  @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}).  The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex vfork events, remote reply
+@item vfork
+The packet indicates that @code{vfork} was called, and @var{r}
+is the ptid of the new child process.  This packet is only
+applicable to targets that support vfork events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it.  @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}).  The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
+@cindex vforkdone events, remote reply
+@item vforkdone
+The packet indicates that a child process created by a vfork
+has either called @code{exec} or terminated, so that the
+address spaces of the parent and child process are no longer
+shared. The @var{r} part is ignored.  This packet is only
+applicable to targets that support vforkdone events.
+
+This packet should not be sent by default; older @value{GDBN} versions
+did not support it.  @value{GDBN} requests it, by supplying an
+appropriate @samp{qSupported} feature (@pxref{qSupported}).  The
+remote stub must also supply the appropriate @samp{qSupported} feature
+indicating support.
+
 @end table
 
 @item W @var{AA}
@@ -35878,6 +35928,18 @@  reason in stop replies.  @xref{swbreak stop reason}, for details.
 @item hwbreak
 This feature indicates whether @value{GDBN} supports the hwbreak stop
 reason in stop replies.  @xref{swbreak stop reason}, for details.
+
+@item fork-events
+This feature indicates whether @value{GDBN} supports fork event
+extensions to the remote protocol.  @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{fork-events+} in its @samp{qSupported} reply.
+
+@item vfork-events
+This feature indicates whether @value{GDBN} supports vfork event
+extensions to the remote protocol.  @value{GDBN} does not use such
+extensions unless the stub also reports that it supports them by
+including @samp{vfork-events+} in its @samp{qSupported} reply.
 @end table
 
 Stubs should ignore any unknown values for
@@ -36116,6 +36178,16 @@  These are the currently defined stub features and their properties:
 @tab @samp{-}
 @tab No
 
+@item @samp{fork-events}
+@tab No
+@tab @samp{-}
+@tab No
+
+@item @samp{vfork-events}
+@tab No
+@tab @samp{-}
+@tab No
+
 @end multitable
 
 These are the currently defined stub features, in more detail:
@@ -36304,6 +36376,13 @@  breakpoints.
 The remote stub reports the @samp{hwbreak} stop reason for hardware
 breakpoints.
 
+@item fork-events
+The remote stub reports the @samp{fork} stop reason for fork events.
+
+@item vfork-events
+The remote stub reports the @samp{vfork} stop reason for vfork events
+and vforkdone events.
+
 @end table
 
 @item qSymbol::