Re: Process record and replay checked in to main trunk

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 30 Apr 2009 15:59:30 +0800
> From: Hui Zhu <teawater@gmail.com>
> Cc: Pedro Alves <pedro@codesourcery.com>, Marc Khouzam <marc.khouzam@ericsson.com>, 
> 	Michael Snyder <msnyder@vmware.com>, Thiago Jung Bauermann <bauerman@br.ibm.com>, Eli Zaretskii <eliz@gnu.org>, 
> 	Mark Kettenis <mark.kettenis@xs4all.nl>
> 
> Process record and replay make gdb can record inferior execute log and
> replay (include reverse debug).
> Now, it support I386-Linux single-thread single-inferior native debug.
> 
> 
> It was checked in today.
> Thanks for evey people that spent time on process record.  Precord
> can't be a part of gdb without your help.  Thank you very much.  :)

Thanks.  I clarified and improved the section in the manual with the
patch below (committed).

What I think is still missing from the manual is a few sentences that
would explain when this target is useful.  Can you provide such ``war
stories''?  I will then add them to the manual.


2009-05-01  Eli Zaretskii  <eliz@gnu.org>

	* gdb.texinfo (Process Record and Replay): Improve and clarify.
	Add index entries.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.588
diff -u -r1.588 gdb.texinfo
--- gdb.texinfo	30 Apr 2009 03:24:48 -0000	1.588
+++ gdb.texinfo	1 May 2009 09:10:11 -0000
@@ -134,7 +134,7 @@
 * Running::                     Running programs under @value{GDBN}
 * Stopping::                    Stopping and continuing
 * Reverse Execution::           Running programs backward
-* Process record and replay::   Recording inferior's execution and replaying it
+* Process Record and Replay::   Recording inferior's execution and replaying it
 * Stack::                       Examining the stack
 * Source::                      Examining source files
 * Data::                        Examining data
@@ -5003,97 +5003,119 @@
 @end table
 
 
-@node Process record and replay
-@chapter Recording inferior's execution and replaying it
+@node Process Record and Replay
+@chapter Recording Inferior's Execution and Replaying It
 @cindex process record and replay
 @cindex recording inferior's execution and replaying it
 
-In a architecture environment that supports process record and replay,
-process record and replay target can record a log of the process execution,
-and replay it with both forward and reverse execute commands.
-
-When this target is in use, if the execution log includes the record for
-the next instruction, @value{GDBN} will debug in replay mode.  So inferior
-will not really execute and all the execution events are taken from the
-execution log.  Just the values of registers (include pc register) and
-memory of the inferior will be changed.
+In an architecture environment that supports process recording and
+replay, a special @dfn{process record and replay} target can record a
+log of the process execution, and replay it later with both forward
+and reverse execution commands.
+
+@cindex replay mode
+When this target is in use, if the execution log includes the record
+for the next instruction, @value{GDBN} will debug in @dfn{replay
+mode}.  In the replay mode, the inferior does not really execute code
+instructions.  Instead, all the events that normally happen during
+code execution are taken from the execution log.  While code is not
+really executed in replay mode, the values of registers (including the
+program counter register) and the memory of the inferior are still
+changed as they normally would.
+
+@cindex record mode
+If the record for the next instruction is not in the execution log,
+@value{GDBN} will debug in @dfn{record mode}.  In this mode, the
+inferior executes normally, and @value{GDBN} records the execution log
+for future replay.
 
-Otherwise, @value{GDBN} will debug in record mode.  So inferior will
-execute normally and @value{GDBN} will record the execution log.
-
-If you are debugging in a architecture environment that supports
-process record and replay, @value{GDBN} provides the following commands.
+For architecture environments that support process record and replay,
+@value{GDBN} provides the following commands:
 
 @table @code
 @kindex target record
 @kindex record
 @kindex rec
 @item target record
-This a standard command to start process record and replay target.
-Process record and replay target can only debug a process that already
-running.  Therefore you need to first start the process @code{run},
-and then start the recording @code{target record}.
-
-Both @code{record} and @code{rec} are the aliases of @code{target record}.
-
-Displaced stepping function will disable when process record and replay
-target is opened.  Because process record and replay target doesn't
-support displaced stepping function.
-
-If inferior in non-stop mode (non-stop) or in asynchronous mode
-(target-async), process record and replay target can't be open because
-it doesn't support these two modes.
+This command starts the process record and replay target.  The process
+record and replay target can only debug a process that is already
+running.  Therefore, you need first to start the process with the
+@kbd{run} or @kbd{start} commands, and then start the recording with
+the @kbd{target record} command.
+
+Both @code{record} and @code{rec} are aliases of @code{target record}.
+
+@cindex displaced stepping, and process record and replay
+Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
+will be automatically disabled when process record and replay target
+is started.  That's because the process record and replay target
+doesn't support displaced stepping.
+
+@cindex non-stop mode, and process record and replay
+@cindex asynchronous execution, and process record and replay
+If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in
+the asynchronous execution mode (@pxref{Background Execution}), the
+process record and replay target cannot be started because it doesn't
+support these two modes.
 
 @kindex record stop
 @kindex rec s
 @item record stop
-Stop process record and replay target at once.  When Process record and
-replay target stops, all the execution log will be deleted and the inferior
-will either be terminated, or remain in its final state.
-
-When you stop the process record and replay target in record mode (at the
-end of the execution log), the inferior will be stopped at the next
-instruction that would have been recorded.  In other words, if you record
-for a while and then stop recording, the inferior process will be left in
-the same state as if recording never happened.
-
-On the other hand, if the process record and replay target is stopped while
-in replay mode (that is, not at the end of the execution log but at some
-earlier point), the inferior process will become ``live'' at that earlier state,
-and it will then be possible to continue debugging the process ``live'' from
-that state.
+Stop the process record and replay target.  When process record and
+replay target stops, the entire execution log will be deleted and the
+inferior will either be terminated, or will remain in its final state.
+
+When you stop the process record and replay target in record mode (at
+the end of the execution log), the inferior will be stopped at the
+next instruction that would have been recorded.  In other words, if
+you record for a while and then stop recording, the inferior process
+will be left in the same state as if the recording never happened.
+
+On the other hand, if the process record and replay target is stopped
+while in replay mode (that is, not at the end of the execution log,
+but at some earlier point), the inferior process will become ``live''
+at that earlier state, and it will then be possible to continue the
+usual ``live'' debugging of the process from that state.
 
-When the inferior process exits, or @value{GDBN} detaches from it, process
-record and replay target will automatically stop itself.
+When the inferior process exits, or @value{GDBN} detaches from it,
+process record and replay target will automatically stop itself.
 
 @kindex set record insn-number-max
 @item set record insn-number-max @var{limit}
 Set the limit of instructions to be recorded.  Default value is 200000.
 
-In this case, if record instructions number is bigger than @var{limit},
-@value{GDBN} will auto delete the earliest recorded instruction execute
-log.
-
-If set to 0, @value{GDBN} will not delete the earliest recorded instruction
-execute log.  Record instructions number limit function will disable.
+If @var{limit} is a positive number, then @value{GDBN} will start
+deleting instructions from the log once the number of the record
+instructions becomes greater than @var{limit}.  For every new recorded
+instruction, @value{GDBN} will delete the earliest recorded
+instruction to keep the number of recorded instructions at the limit.
+(Since deleting recorded instructions loses information, @value{GDBN}
+lets you control what happens when the limit is reached, by means of
+the @code{stop-at-limit} option, described below.)
+
+If @var{limit} is zero, @value{GDBN} will never delete recorded
+instructions from the execution log.  The number of recorded
+instructions is unlimited in this case.
 
 @kindex show record insn-number-max
 @item show record insn-number-max
-Show the value of recorded instructions limit.
+Show the limit of instructions to be recorded.
 
 @kindex set record stop-at-limit
-@item set record stop-at-limit on
-Set the behavior when record instructions limit is reached.
-This is the default mode.  Meaning that @value{GDBN} will stop ask user
-want close @code{record stop-at-limit} or stop inferior.
-
-@item set record stop-at-limit off
-This mean that @value{GDBN} will auto delete the oldest record to make
-room for each new one.
+@item set record stop-at-limit
+Control the behavior when the number of recorded instructions reaches
+the limit.  If ON (the default), @value{GDBN} will stop when the limit
+is reached for the first time and ask you whether you want to stop the
+inferior or continue running it and recording the execution log.  If
+you decide to continue recording, each new recorded instruction will
+cause the oldest one to be deleted.
+
+If this option is OFF, @value{GDBN} will automatically delete the
+oldest record to make room for each new one, without asking.
 
 @kindex show record stop-at-limit
 @item show record stop-at-limit
-Show the value of record stop-at-limit.
+Show the current setting of @code{stop-at-limit}.
 
 @kindex info record insn-number
 @item info record insn-number
@@ -5102,9 +5124,9 @@
 @kindex record delete
 @kindex rec del
 @item record delete
-When record target running in replay mode (``in the past''), delete the
+When record target runs in replay mode (``in the past''), delete the
 subsequent execution log and begin to record a new execution log starting
-from the current address.  It means you will abandon the previously
+from the current address.  This means you will abandon the previously
 recorded ``future'' and begin recording a new ``future''.
 @end table