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

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 14 Oct 2008 23:00:59 +0800
> From: teawater <teawater@gmail.com>
> 
> This patch add doc to gdb.texinfo.
> 
> 2008-10-14  Hui Zhu  <teawater@gmail.com>
> 
> 	* gdb.texinfo: Add documentation for process record and replay.

Thank you.  I have a few questions and suggestions about this.

> +When this target is in use, if the next instruction to be executed is in the
> +execution log, @value{GDBN} will debug in replay mode so that all the
> +execution events are taken from the execution log.  Otherwise, @value{GDBN}
> +will debug in record mode and record the execution log while executing
> +normally.

What exactly is the "execution log"?  You talk about "next
instruction", which seems to hint that the log records the machine
instructions executed by the inferior -- is that true?  If so, what
are the "execution events" you mention here -- are they just a synonym
for the "instructions", or are they something else?

> +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}.

This is really inconvenient, because it means the beginning of the
program's execution cannot be recorded.  Is that a limitation, or am I
missing something?

This:

> +@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.

and this:

> +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.

seem to be in contradiction: the former says that the inferior will be
terminated, the latter says that it will be stopped.  Which one is it?

>                                              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 you had never done any recording.

Why is this sentence important?  Recording has no side effects except
for the recorded information, so why did you need to say that the
inferior will be left in a state ``as if recording never happened''?

> +@itemx set record-auto-delete 1
> +Set the behavior when record instructions limit is reached. 1 mean that GDB
> +will auto delete the oldest record to make room for each new one.
> +
> +@item set record-auto-delete 0
> +0 is the default value, meaning that @value{GDBN} will stop the inferior.

Either the name of the option or the argument should be modified,
IMO.  I prefer to rename the option (to something like
record-stop-at-limit, and change the default to 1).

Also, there's a relation between this option and
record-insn-number-max, right?  If so, the text should mention that.

> +@item set record-insn-number-max @var{limit}
> +Set the limit of instructions to be recorded.  Default value is 200000.
> +If set to 0, record instructions number limit function will disable.
> +In this case, if record instructions number is bigger than @var{limit},
> +@value{GDBN} will auto delete the earliest recorded instruction to make room
> +for each new one.

I think you need to transpose the two last sentences, otherwise the
text seems to say that when the limit is set to zero, GDB will delete
earliest instruction when the (zero) limit is exhausted.