reverse execution part of the manual is written backwards

reverse execution part of the manual is written backwards

[Paul Eggert]

[resent from https://sourceware.org/bugzilla/show_bug.cgi?id=24417]

At least two Emacs developers were confused by GDB's documentation for reverse 
execution. One said he could never get it to work and recommended another 
debugger instead since it always worked for him. We tracked down the issue to a 
problem in GDB's documentation: it documents how to do reverse execution, but 
never mentions until a later section that you can't use reverse execution unless 
you first turn on process recording.

Surely it's not intended that one must read the GDB documentation backwards in 
order to know how to do reverse execution....

Proposed patch follows. This is just a minor doc patch so I assume no ChangeLog 
entry is needed.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f410d026b8..147c7c0f37 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6697,8 +6697,11 @@ assumes that the memory and registers that the target 
reports are in a
  consistant state, but @value{GDBN} accepts whatever it is given.
  }.

-If you are debugging in a target environment that supports
-reverse execution, @value{GDBN} provides the following commands.
+Before using reverse execution, you should first use the @code{record}
+command, so that instructions executed by the program are saved for
+reverse execution later.  @xref{Process Record and Replay}.
+@value{GDBN} provides the following commands to examine the process
+record and execute the program in reverse.

  @table @code
  @kindex reverse-continue

Re: reverse execution part of the manual is written backwards

[Pedro Alves]

On 4/10/19 5:19 AM, Paul Eggert wrote:
> [resent from https://sourceware.org/bugzilla/show_bug.cgi?id=24417]
> 
> At least two Emacs developers were confused by GDB's documentation for reverse execution. One said he could never get it to work and recommended another debugger instead since it always worked for him. We tracked down the issue to a problem in GDB's documentation: it documents how to do reverse execution, but never mentions until a later section that you can't use reverse execution unless you first turn on process recording.
> 
> Surely it's not intended that one must read the GDB documentation backwards in order to know how to do reverse execution....
> 
> Proposed patch follows. This is just a minor doc patch so I assume no ChangeLog entry is needed.
> 
> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index f410d026b8..147c7c0f37 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -6697,8 +6697,11 @@ assumes that the memory and registers that the target reports are in a
>  consistant state, but @value{GDBN} accepts whatever it is given.
>  }.
> 
> -If you are debugging in a target environment that supports
> -reverse execution, @value{GDBN} provides the following commands.
> +Before using reverse execution, you should first use the @code{record}
> +command, so that instructions executed by the program are saved for
> +reverse execution later.  @xref{Process Record and Replay}.
> +@value{GDBN} provides the following commands to examine the process
> +record and execute the program in reverse.

This is not correct.  "record" is one way to support reverse execution,
but there are others.  For example, "record" is an alias for "record full".
"record btrace" also supports reverse debugging.  And then there are
remote targets that suppose reverse debugging natively, like system emulators,
and you won't type "record" with those at all.  Mozilla's RR is another
example.  

https://www.gnu.org/software/gdb/news/reversible.html

> 
>  @table @code
>  @kindex reverse-continue
Thanks,
Pedro Alves

Re: reverse execution part of the manual is written backwards

[Eli Zaretskii]

> From: Pedro Alves <palves@redhat.com>
> Date: Wed, 10 Apr 2019 12:51:36 +0100
> 
> > +Before using reverse execution, you should first use the @code{record}
> > +command, so that instructions executed by the program are saved for
> > +reverse execution later.  @xref{Process Record and Replay}.
> > +@value{GDBN} provides the following commands to examine the process
> > +record and execute the program in reverse.
> 
> This is not correct.  "record" is one way to support reverse execution,
> but there are others.  For example, "record" is an alias for "record full".
> "record btrace" also supports reverse debugging.  And then there are
> remote targets that suppose reverse debugging natively, like system emulators,
> and you won't type "record" with those at all.  Mozilla's RR is another
> example.  
> 
> https://www.gnu.org/software/gdb/news/reversible.html

Pedro,

First, thanks for responding, I posted a similar question to gdb@, and
only got one uncertain response.  What you wrote is much more
definitive.

Next, please try to put yourself in the shoes of a GDB user who is
debugging a native target, let's say on GNU/Linux.  How would such a
user know what to do to start using the reverse debugging feature?

The above URL basically says that reverse debugging is available
natively only on GNU/Linux running on x86 CPUs, and then only if one
activates "target record".  This is essentially what Paul was saying,
so he wasn't very far off the mark.  The remote targets are an
important addition to what Paul said.

In any case, I think the Reverse Execution section should say
something about the conditions for using this mode, regardless of
whether it precedes or follows the chapter about recording and
replaying.  It probably should simply say what the above URL says at
its beginning, and then describe the commands to activate the correct
target, or point to a clear description of those commands elsewhere in
the manual.  Because right now we have a description of record and
replay, and we have a description of reverse-execution commands, but
no "glue" to connect them, and there's no reasonable way for a reader
to guess what to do to bridge over that chasm.

Do you agree?

Re: reverse execution part of the manual is written backwards

[Paul Eggert]

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

Pedro Alves wrote:
> This is not correct.  "record" is one way to support reverse execution,
> but there are others.

OK, how about the attached patch instead?

[-- Attachment #2: gdb-diff.txt --]
[-- Type: text/plain, Size: 867 bytes --]

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f410d026b8..6410e9cc7b 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6697,8 +6697,13 @@ assumes that the memory and registers that the target reports are in a
 consistant state, but @value{GDBN} accepts whatever it is given.
 }.
 
-If you are debugging in a target environment that supports
-reverse execution, @value{GDBN} provides the following commands.
+Not every target environment supports reverse execution, and some
+targets require that you first use the @code{record} or @code{record
+btrace} command, so that instructions executed by the program are
+saved for reverse execution later.  @xref{Process Record and Replay}.
+
+@value{GDBN} provides the following commands to examine the process
+record and execute the program in reverse.
 
 @table @code
 @kindex reverse-continue

Re: reverse execution part of the manual is written backwards

[Pedro Alves]

On 4/10/19 3:54 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Date: Wed, 10 Apr 2019 12:51:36 +0100
>>
>>> +Before using reverse execution, you should first use the @code{record}
>>> +command, so that instructions executed by the program are saved for
>>> +reverse execution later.  @xref{Process Record and Replay}.
>>> +@value{GDBN} provides the following commands to examine the process
>>> +record and execute the program in reverse.
>>
>> This is not correct.  "record" is one way to support reverse execution,
>> but there are others.  For example, "record" is an alias for "record full".
>> "record btrace" also supports reverse debugging.  And then there are
>> remote targets that suppose reverse debugging natively, like system emulators,
>> and you won't type "record" with those at all.  Mozilla's RR is another
>> example.  
>>
>> https://www.gnu.org/software/gdb/news/reversible.html
> 
> Pedro,
> 
> First, thanks for responding, I posted a similar question to gdb@, and
> only got one uncertain response.  What you wrote is much more
> definitive.

Sorry, wish I could answer every question.

> Next, please try to put yourself in the shoes of a GDB user who is
> debugging a native target, let's say on GNU/Linux.  How would such a
> user know what to do to start using the reverse debugging feature?
> 
> The above URL basically says that reverse debugging is available
> natively only on GNU/Linux running on x86 CPUs, and then only if one
> activates "target record".  This is essentially what Paul was saying,
> so he wasn't very far off the mark.  The remote targets are an
> important addition to what Paul said.
> 
> In any case, I think the Reverse Execution section should say
> something about the conditions for using this mode, regardless of
> whether it precedes or follows the chapter about recording and
> replaying.  It probably should simply say what the above URL says at
> its beginning, and then describe the commands to activate the correct
> target, or point to a clear description of those commands elsewhere in
> the manual.  Because right now we have a description of record and
> replay, and we have a description of reverse-execution commands, but
> no "glue" to connect them, and there's no reasonable way for a reader
> to guess what to do to bridge over that chasm.
> 
> Do you agree?
> 

How about this?

From ed99ed89bf0d06edf844eaa018619d617b9bb99b Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Thu, 11 Apr 2019 16:03:33 +0100
Subject: [PATCH] Improve reverse debugging docs

	* gdb.texinfo (Reverse Execution): Mention and xref process record
	and replay.  Mention remote and system emulators.
	(Process Record and Replay): List supported architectures.
	Mention that "record btrace" is only supported on Intel
	processors.
---
 gdb/doc/gdb.texinfo | 26 +++++++++++++++++++-------
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f410d026b82..aa5b8756b7c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6697,6 +6697,12 @@ assumes that the memory and registers that the target reports are in a
 consistant state, but @value{GDBN} accepts whatever it is given.
 }.
 
+On some platforms, @value{GDBN} has built-in support for reverse
+execution, activated with the @code{record} or @code{record btrace}
+commands.  @xref{Process Record and Replay}.  Some remote targets,
+typically full system emulators, support reverse execution directly
+without requiring any special command.
+
 If you are debugging in a target environment that supports
 reverse execution, @value{GDBN} provides the following commands.
 
@@ -6817,6 +6823,11 @@ replay mode as long as the execution log includes the record for the
 previous instruction; otherwise, it will work in record mode, if the
 platform supports reverse execution, or stop if not.
 
+Currently, process record and replay is supported on ARM, Aarch64,
+Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running
+GNU/Linux.  Process record and replay can be used both when native
+debugging, and when remote debugging via @code{gdbserver}.
+
 For architecture environments that support process record and replay,
 @value{GDBN} provides the following commands:
 
@@ -6851,13 +6862,14 @@ replay implementation.  This method allows replaying and reverse
 execution.
 
 @item btrace @var{format}
-Hardware-supported instruction recording.  This method does not record
-data.  Further, the data is collected in a ring buffer so old data will
-be overwritten when the buffer is full.  It allows limited reverse
-execution.  Variables and registers are not available during reverse
-execution.  In remote debugging, recording continues on disconnect.
-Recorded data can be inspected after reconnecting.  The recording may
-be stopped using @code{record stop}.
+Hardware-supported instruction recording, supported on Intel
+processors.  This method does not record data.  Further, the data is
+collected in a ring buffer so old data will be overwritten when the
+buffer is full.  It allows limited reverse execution.  Variables and
+registers are not available during reverse execution.  In remote
+debugging, recording continues on disconnect.  Recorded data can be
+inspected after reconnecting.  The recording may be stopped using
+@code{record stop}.
 
 The recording format can be specified as parameter.  Without a parameter
 the command chooses the recording format.  The following recording
-- 
2.14.5

Re: reverse execution part of the manual is written backwards

[Eli Zaretskii]

> Cc: eggert@cs.ucla.edu, gdb-patches@sourceware.org
> From: Pedro Alves <palves@redhat.com>
> Date: Thu, 11 Apr 2019 16:54:22 +0100
> 
> > In any case, I think the Reverse Execution section should say
> > something about the conditions for using this mode, regardless of
> > whether it precedes or follows the chapter about recording and
> > replaying.  It probably should simply say what the above URL says at
> > its beginning, and then describe the commands to activate the correct
> > target, or point to a clear description of those commands elsewhere in
> > the manual.  Because right now we have a description of record and
> > replay, and we have a description of reverse-execution commands, but
> > no "glue" to connect them, and there's no reasonable way for a reader
> > to guess what to do to bridge over that chasm.
> > 
> > Do you agree?
> > 
> 
> How about this?

LGTM, thanks.  Paul, does this address your concerns?

Re: reverse execution part of the manual is written backwards

[Paul Eggert]

Pedro Alves wrote:

> How about this?
> 
>  From ed99ed89bf0d06edf844eaa018619d617b9bb99b Mon Sep 17 00:00:00 2001
> From: Pedro Alves <palves@redhat.com>
> Date: Thu, 11 Apr 2019 16:03:33 +0100
> Subject: [PATCH] Improve reverse debugging docs
> 
> 	* gdb.texinfo (Reverse Execution): Mention and xref process record
> 	and replay.  Mention remote and system emulators.
> 	(Process Record and Replay): List supported architectures.
> 	Mention that "record btrace" is only supported on Intel
> 	processors.

Thanks, that patch looks good. Would you please install it?

Re: reverse execution part of the manual is written backwards

[Pedro Alves]

On 4/22/19 7:50 AM, Paul Eggert wrote:
> Pedro Alves wrote:
> 
>> How about this?
>>
>>  From ed99ed89bf0d06edf844eaa018619d617b9bb99b Mon Sep 17 00:00:00 2001
>> From: Pedro Alves <palves@redhat.com>
>> Date: Thu, 11 Apr 2019 16:03:33 +0100
>> Subject: [PATCH] Improve reverse debugging docs
>>
>>     * gdb.texinfo (Reverse Execution): Mention and xref process record
>>     and replay.  Mention remote and system emulators.
>>     (Process Record and Replay): List supported architectures.
>>     Mention that "record btrace" is only supported on Intel
>>     processors.
> 
> Thanks, that patch looks good. Would you please install it?

I've installed it now.

Thanks,
Pedro Alves