RE: [PATCH 2/2] btrace: set/show record btrace cpu

["Metzger, Markus T" <markus dot t dot metzger at intel dot com>]

Hello Eli,

> Thanks.  Then I suggest to have this text in the manual:
> 
>   @item set record btrace cpu @var{identifier}
>   Set the processor to be used for enabling workarounds for processor
>   errata when decoding the trace.
> 
>   @cindex processor errata
>   @dfn{Processor errata} are bugs in processor firmware that can cause
>   a trace not to match the specification.  Trace decoders that are
>   unaware of these errata might fail to decode such a trace.
>   @value{GDBN} can detect erroneous trace packets and correct them,
>   thus avoiding the decoding failures.  These corrections are known as
>   @dfn{errata workarounds}, and are enabled based on the processor on
>   which the trace was recorded.

I'm not sure whether the term 'firmware' is correct.  I would instead phrase
it like this:

"Errata may cause the recorded trace to not match the specification.  This,
in turn, may cause trace decode to fail".

Then continue with "@value{GDBN} can detect ..." as you suggested.


>   By default, @value{GDBN} attempts to detect the processor
>   automatically, and apply the necessary workarounds for it.  However,
>   you may need to specify the processor if @value{GDBN} does not yet
>   support it.  This command allows you to do that, and also allows to
>   disable the workarounds.

That sounds good.  Thanks for your help.

Below is the full doc patch.

regards,
Markus.

---
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index ee7adc8..2abb8d7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6952,10 +6952,72 @@ and to read-write memory.  Beware that the accessed memory corresponds
 to the live target and not necessarily to the current replay
 position.
 
+@item set record btrace cpu @var{identifier}
+Set the processor to be used for enabling workarounds for processor
+errata when decoding the trace.
+
+Errata may cause the recorded trace to not match the specification.
+This, in turn, may cause trace decode to fail.  @value{GDBN} can
+detect erroneous trace packets and correct them, thus avoiding the
+decoding failures.  These corrections are known as @dfn{errata
+workarounds}, and are enabled based on the processor on which the
+trace was recorded.
+
+By default, @value{GDBN} attempts to detect the processor
+automatically, and apply the necessary workarounds for it.  However,
+you may need to specify the processor if @value{GDBN} does not yet
+support it.  This command allows you to do that, and also allows to
+disable the workarounds.
+
+The argument @var{identifier} identifies the @sc{cpu} and is of the
+form: @code{@var{vendor}:@var{procesor identifier}}.  In addition,
+there are two special identifiers, @code{none} and @code{auto}
+(default).
+
+The following vendor identifiers and corresponding processor
+identifiers are currently supported:
+
+@multitable @columnfractions .1 .9
+
+@item @code{intel}
+@tab @var{family}/@var{model}[/@var{stepping}]
+
+@end multitable
+
+On GNU/Linux systems, the processor @var{family}, @var{model}, and
+@var{stepping} can be obtained from @code{/proc/cpuinfo}.
+
+If @var{identifier} is @code{auto}, enable errata workarounds for the
+processor on which the trace was recorded.  If @var{identifier} is
+@code{none}, errata workarounds are disabled.
+
+For example, when using an old @value{GDBN} on a new system, decode
+may fail because @value{GDBN} does not support the new processor.  It
+often suffices to specify an older processor that @value{GDBN}
+supports.
+
+@smallexample
+(gdb) info record
+Active record target: record-btrace
+Recording format: Intel Processor Trace.
+Buffer size: 16kB.
+Failed to configure the Intel Processor Trace decoder: unknown cpu.
+(gdb) set record btrace cpu intel:6/158
+(gdb) info record
+Active record target: record-btrace
+Recording format: Intel Processor Trace.
+Buffer size: 16kB.
+Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...).
+@end smallexample
+
 @kindex show record btrace
 @item show record btrace replay-memory-access
 Show the current setting of @code{replay-memory-access}.
 
+@item show record btrace cpu
+Show the processor to be used for enabling trace decode errata
+workarounds.
+
 @kindex set record btrace bts
 @item set record btrace bts buffer-size @var{size}
 @itemx set record btrace bts buffer-size unlimited

Intel Deutschland GmbH
Registered Address: Am Campeon 10-12, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de
Managing Directors: Christin Eisenschmid, Christian Lamprechter
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928