Re: [reverse RFC] Add documentation for process record and replay

[teawater <teawater@gmail.com>]

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

Thanks Eli.
I make a new one.

2008-10-17  Hui Zhu  <teawater@gmail.com>

	* gdb.texinfo: Add documentation for process record and replay.

Thanks,
Hui

On Fri, Oct 17, 2008 at 02:40, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Thu, 16 Oct 2008 15:35:01 +0800
>> From: teawater <teawater@gmail.com>
>> Cc: msnyder@vmware.com, gdb-patches@sourceware.org
>>
>> According to the suggestions. I make a new patch.
>>
>> 2008-10-16  Hui Zhu  <teawater@gmail.com>
>>
>>       * gdb.texinfo: Add documentation for process record and replay.
>
> OK.  This needs some rewording and rephrasing, but I can do that
> later, after the patch is committed.  (However, please fix the few
> simple formatting errors I mention below.)
>
> I'm somewhat concerned about the fact that the functionality and
> limitations of the ``record and replay'' target are not described at
> all.  If I were to debug using such an architecture, I'd like to know
> what it can and cannot do.  For example, if I replay, does the I/O
> happen like it happened during the recorded session?  What about
> signals? crashes? etc.  Are there things that simply cannot be
> reproduced exactly, due to fundamental limitations of the replay
> target?
>
> Shouldn't we give the reader some idea about these issues?
>
>> +running. Therefore you need to first start the process @code{run},
>          ^^
> Please make sure you have 2 spaces after each period that ends a
> sentence.
>
>> +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.
>
> ``live'', not "live".  In Texinfo, please always use ``...'' quoting
> rather than "..", because the former produces prettier results in the
> printed manual.  ".." should be reserved only for string constants in
> code fragments.
>
>> +@kindex set record-insn-number-max @var{limit}
>
> Please don't put arguments in the index entries.  Index entries should
> name only the command name.
>
>> +@item set record-stop-at-limit
>> +@item set record-stop-at-limit on
>
> Only the first item of several that share the same description can use
> @item, the rest should use @itemx.
>
>> +@itemx set record-stop-at-limit off
>
> @itemx cannot be the first item.
>
>> +(see "Set values of variables", above); it means you will abandon the
>
> Is this a reference to another section?  If so, please use @pxref,
> which will produce a true hyperlink that can be followed in an Info
> reader.
>

[-- Attachment #2: rec_doc.txt --]
[-- Type: text/plain, Size: 4867 bytes --]

--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2008-10-17  Hui Zhu  <teawater@gmail.com>
+
+	* gdb.texinfo: Add documentation for process record and replay.
+
 2008-09-30  Michael Snyder  <msnyder@vmware.com>
 
 	* gdb.texinfo: Add documentation for reverse execution.
--- a/gdb.texinfo
+++ b/gdb.texinfo
@@ -144,6 +144,7 @@ software in general.  We will miss him.
 * Running::                     Running programs under @value{GDBN}
 * Stopping::                    Stopping and continuing
 * Reverse Execution::           Running programs backward
+* Process record and replay::   Recording programs running message and replay it
 * Stack::                       Examining the stack
 * Source::                      Examining source files
 * Data::                        Examining data
@@ -4963,6 +4964,102 @@ This is the default.
 @end table
 
 
+@node Process record and replay
+@chapter Recording programs running message and replay it
+@cindex process record and replay
+@cindex recording programs running message and replay 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.
+
+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.
+
+@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{record}.
+
+@kindex stoprecord
+@kindex sr
+@item stoprecord
+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.
+
+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.
+
+@kindex show record-insn-number-max
+@item show record-insn-number-max
+Show the value of recorded instructions limit.
+
+@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.
+
+@kindex show record-stop-at-limit
+@item show record-stop-at-limit
+Show the value of record-stop-at-limit.
+
+@kindex info record-insn-number
+@item info record-insn-number
+Show the current number of recorded instructions.
+
+@kindex delrecord
+@kindex dr
+@item delrecord
+When record target running 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
+recorded ``future" and begin recording a new ``future".
+@end table
+
+
 @node Stack
 @chapter Examining the Stack