Re: reverse execution part of the manual is written backwards

[Pedro Alves <palves at redhat dot com>]

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