[patch v9 21/23] doc, record: document record changes

[Markus Metzger <markus.t.metzger@intel.com>]

Document changes to the record target resulting from the renaming into
record-full.

Document two new record sub-commands "record instruction-history" and
"record function-call-history" and two associated set/show commands
"set record instruction-history-size" and "set record
function-call-history-size".

Add this to NEWS.

CC: Eli Zaretskii <eliz@gnu.org>

2013-03-04  Markus Metzger <markus.t.metzger@intel.com>

	* NEWS: Add record changes.

doc/
	* gdb.texinfo (Process Record and Replay): Document record
	changes.


---
 gdb/NEWS            |   26 ++++++
 gdb/doc/gdb.texinfo |  215 +++++++++++++++++++++++++++++++++++++++++++--------
 2 files changed, 207 insertions(+), 34 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 0877aa2..e8dec14 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -3,6 +3,32 @@
 
 *** Changes since GDB 7.5
 
+* Target record has been renamed to record-full.
+  Record/replay is now enabled with the "record full" command.
+  This also affects settings that are associated with full record/replay
+  that have been moved from "set/show record" to "set/show record full":
+
+record insn-number-max
+record stop-at-limit
+record memory-query
+
+* Two new commands have been added for record/replay to give information
+  about the recorded execution without having to replay the execution.
+
+"record instruction-history" disassembles instructions stored in the
+execution log.
+
+"record function-call-history" prints the names of the functions
+from instructions stored in the execution log.
+
+* A new record target "record-btrace" has been added.  The new target
+  uses hardware support to record the control-flow of a process.  It
+  does not support replaying the execution, but it implements the
+  above commands for investigating the recorded execution log.
+
+  The "record-btrace" target is only available on Intel Atom processors
+  and requires a Linux kernel 2.6.32 or later.
+
 * New native configurations
 
 ARM AArch64 GNU/Linux		aarch64*-*-linux-gnu
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 337675c..a3ebcd2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6117,16 +6117,40 @@ For architecture environments that support process record and replay,
 
 @table @code
 @kindex target record
+@kindex target record-full
+@kindex target record-btrace
 @kindex record
+@kindex record full
+@kindex record btrace
 @kindex rec
-@item target record
-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.
+@kindex rec full
+@kindex rec btrace
+@item record @var{method}
+This command starts the process record and replay target.  The
+recording method can be specified as parameter.  Without a parameter
+the command uses the @var{full} recording method.  The following
+recording methods are available:
 
-Both @code{record} and @code{rec} are aliases of @code{target record}.
+@table @code
+@item full
+Full record/replay recording using @value{GDBN}'s software record and
+replay implementation.  This method allows replaying and reverse
+execution.
+
+@item btrace
+Hardware-supported instruction recording.  This method does not allow
+replaying and reverse execution.
+
+This recording method may not be available on all processors.
+@end table
+
+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{record @var{method}} command.
+
+Both @code{record @var{method}} and @code{rec @var{method}} are
+aliases of @code{target record-@var{method}}.
 
 @cindex displaced stepping, and process record and replay
 Displaced stepping (@pxref{Maintenance Commands,, displaced stepping})
@@ -6137,9 +6161,9 @@ 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.
+the asynchronous execution mode (@pxref{Background Execution}), not
+all recording methods are available.  The @var{full} recording method
+does not support these two modes.
 
 @kindex record stop
 @kindex rec s
@@ -6169,14 +6193,17 @@ Save the execution log to a file @file{@var{filename}}.
 Default filename is @file{gdb_record.@var{process_id}}, where
 @var{process_id} is the process ID of the inferior.
 
+This command may not be available for all recording methods.
+
 @kindex record restore
 @item record restore @var{filename}
 Restore the execution log from a file @file{@var{filename}}.
 File must have been created with @code{record save}.
 
-@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.
+@kindex set record full
+@item set record full insn-number-max @var{limit}
+Set the limit of instructions to be recorded for the @var{full}
+recording method.  Default value is 200000.
 
 If @var{limit} is a positive number, then @value{GDBN} will start
 deleting instructions from the log once the number of the record
@@ -6191,31 +6218,31 @@ 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 limit of instructions to be recorded.
+@kindex show record full
+@item show record full insn-number-max
+Show the limit of instructions to be recorded with the @var{full}
+recording method.
 
-@kindex set record stop-at-limit
-@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.
+@item set record full stop-at-limit
+Control the behavior of the  @var{full} recording method 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
+@item show record full stop-at-limit
 Show the current setting of @code{stop-at-limit}.
 
-@kindex set record memory-query
-@item set record memory-query
+@item set record full memory-query
 Control the behavior when @value{GDBN} is unable to record memory
-changes caused by an instruction.  If ON, @value{GDBN} will query
-whether to stop the inferior in that case.
+changes caused by an instruction for the @var{full} recording method.
+If ON, @value{GDBN} will query whether to stop the inferior in that
+case.
 
 If this option is OFF (the default), @value{GDBN} will automatically
 ignore the effect of such instructions on memory.  Later, when
@@ -6223,14 +6250,18 @@ ignore the effect of such instructions on memory.  Later, when
 instruction as not accessible, and it will not affect the replay
 results.
 
-@kindex show record memory-query
-@item show record memory-query
+@item show record full memory-query
 Show the current setting of @code{memory-query}.
 
 @kindex info record
 @item info record
-Show various statistics about the state of process record and its
-in-memory execution log buffer, including:
+Show various statistics about the recording depending on the recording
+method:
+
+@table @code
+@item full
+For the @var{full} recording method, it shows the state of process
+record and its in-memory execution log buffer, including:
 
 @itemize @bullet
 @item
@@ -6247,6 +6278,12 @@ Number of instructions contained in the execution log.
 Maximum number of instructions that may be contained in the execution log.
 @end itemize
 
+@item btrace
+For the @var{btrace} recording method, it shows the number of
+instructions that have been recorded and the number of blocks of
+sequential control-flow that is formed by the recorded instructions.
+@end table
+
 @kindex record delete
 @kindex rec del
 @item record delete
@@ -6254,6 +6291,116 @@ 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.  This means you will abandon the previously
 recorded ``future'' and begin recording a new ``future''.
+
+@kindex record instruction-history
+@kindex rec instruction-history
+@item record instruction-history
+Disassembles instructions from the recorded execution log.  By
+default, ten instructions are disassembled.  This can be changed using
+the @code{set record instruction-history-size} command.  Instructions
+are printed in execution order.  There are several ways to specify
+what part of the execution log to disassemble:
+
+@table @code
+@item record instruction-history @var{insn}
+Disassembles ten instructions starting from instruction number
+@var{insn}.
+
+@item record instruction-history @var{insn}, +/-@var{n}
+Disassembles @var{n} instructions around instruction number
+@var{insn}.  If @var{n} is preceded with @code{+}, disassembles
+@var{n} instructions after instruction number @var{insn}.  If
+@var{n} is preceded with @code{-}, disassembles @var{n}
+instructions before instruction number @var{insn}.
+
+@item record instruction-history
+Disassembles ten more instructions after the last disassembly.
+
+@item record instruction-history -
+Disassembles ten more instructions before the last disassembly.
+
+@item record instruction-history @var{begin} @var{end}
+Disassembles instructions beginning with instruction number
+@var{begin} until instruction number @var{end}.  The instruction
+number @var{end} is not included.
+@end table
+
+This command may not be available for all recording methods.
+
+@kindex set record
+@item set record instruction-history-size
+Define how many instructions to disassemble in the @code{record
+instruction-history} command.  The default value is 10.
+
+@kindex show record
+@item show record instruction-history-size
+Show how many instructions to disassemble in the @code{record
+instruction-history} command.
+
+@kindex record function-call-history
+@kindex rec function-call-history
+@item record function-call-history
+Prints the execution history at function granularity. It prints one
+line for each sequence of instructions that belong to the same
+function giving the name of that function, the source lines
+for this instruction sequence (if the @code{/l} modifier is
+specified), and the instructions numbers that form the sequence (if
+the @code{/i} modifier is specified).
+
+@smallexample
+(@value{GDBP}) @b{list 1, 10}
+1   void foo (void)
+2   @{
+3   @}
+4
+5   void bar (void)
+6   @{
+7     ...
+8     foo ();
+9     ...
+10  @}
+(@value{GDBP}) @b{record function-call-history /l}
+1  foo.c:6-8   bar
+2  foo.c:2-3   foo
+3  foo.c:9-10  bar
+@end smallexample
+
+By default, ten lines are printed.  This can be changed using the
+@code{set record function-call-history-size} command.  Functions are
+printed in execution order.  There are several ways to specify what
+to print:
+
+@table @code
+@item record function-call-history @var{func}
+Prints ten functions starting from function number @var{func}.
+
+@item record function-call-history @var{func}, +/-@var{n}
+Prints @var{n} functions around function number @var{func}.  If
+@var{n} is preceded with @code{+}, prints @var{n} functions after
+function number @var{func}.  If @var{n} is preceded with @code{-},
+prints @var{n} functions before function number @var{func}.
+
+@item record function-call-history
+Prints ten more functions after the last ten-line print.
+
+@item record function-call-history -
+Prints ten more functions before the last ten-line print.
+
+@item record function-call-history @var{begin} @var{end}
+Prints functions beginning with function number @var{begin} until
+function number @var{end}.  The function number @var{end} is not
+included.
+@end table
+
+This command may not be available for all recording methods.
+
+@item set record function-call-history-size
+Define how many lines to print in the
+@code{record function-call-history} command.  The default value is 10.
+
+@item show record function-call-history-size
+Show how many lines to print in the
+@code{record function-call-history} command.
 @end table
 
 
-- 
1.7.1