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

  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.

---

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
  

> From: "Metzger, Markus T" <markus.t.metzger@intel.com>
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> Date: Wed, 28 Feb 2018 07:38:03 +0000
> > 
> >   @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".

But that completely loses the explanation of what the errata are.  If
my explanation is not accurate, let's correct it, rather than deleting
it.
  

Hello Eli,

> > >   @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".
> 
> But that completely loses the explanation of what the errata are.  If my
> explanation is not accurate, let's correct it, rather than deleting it.

I didn't mean to delete your explanation.  I only removed the 'firmware' part.
And the bit about 'unaware decoders' because it really only matters to the
reader what GDB's decoder does.  Or that's what I thought I did.  What else is
missing?

Thanks,
Markus.

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
  

> From: "Metzger, Markus T" <markus.t.metzger@intel.com>
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> Date: Thu, 1 Mar 2018 07:05:42 +0000
> 
> > > >   @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.
> > >
> > But that completely loses the explanation of what the errata are.  If my
> > explanation is not accurate, let's correct it, rather than deleting it.
> 
> I didn't mean to delete your explanation.  I only removed the 'firmware' part.

The text I proposed is above.  It begins with an explanation of what
those errata are, and why they are detrimental to btrace.  The text
you proposed instead is this:

  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.

This just says that trace decode can fail, but tells nothing about the
phenomenon itself.  Thus my "completely loses" reaction.

But I don't want to argue.  If you feel that the text you wrote is
good enough, go ahead and push it, even though I'm unhappy.

Thanks.
  

Hello Eli,

> > > > >   @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.
> > > >
> > > But that completely loses the explanation of what the errata are.
> > > If my explanation is not accurate, let's correct it, rather than deleting it.
> >
> > I didn't mean to delete your explanation.  I only removed the 'firmware' part.
> 
> The text I proposed is above.  It begins with an explanation of what those errata
> are, and why they are detrimental to btrace.  The text you proposed instead is
> this:
> 
>   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.
> 
> This just says that trace decode can fail, but tells nothing about the phenomenon
> itself.  Thus my "completely loses" reaction.
> 
> But I don't want to argue.  If you feel that the text you wrote is good enough, go
> ahead and push it, even though I'm unhappy.

I'd rather we find a wording we can all agree on.

I added that errata cause the trace to not match the spec and that this would
cause decode to fail.

I removed the bit about errata being in the firmware since that is not correct.

And I replaced "unaware decoders might fail to decode such a trace" with "This,
in turn, may cause trace decode to fail".

The rest I took as you suggested.

Where do you think we need to improve the wording?

Thanks,
Markus.

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
  

> From: "Metzger, Markus T" <markus.t.metzger@intel.com>
> CC: "gdb-patches@sourceware.org" <gdb-patches@sourceware.org>
> Date: Thu, 1 Mar 2018 16:23:59 +0000
> 
> Where do you think we need to improve the wording?

I'd like to have an explanation of what the errata are and what causes
them.  If "bugs in firmware" is inaccurate, then how do we describe
the reason accurately?  (If you can point me to some URL where that is
described, I might be able to come up with an accurate description
myself.)

Than ks.
  

Hello Eli,

> > Where do you think we need to improve the wording?
> 
> I'd like to have an explanation of what the errata are and what causes them.  If
> "bugs in firmware" is inaccurate, then how do we describe the reason accurately?
> (If you can point me to some URL where that is described, I might be able to
> come up with an accurate description
> myself.)

The term "erratum" already means 'bug somewhere in the processor'.

From https://en.wikipedia.org/wiki/Erratum:

    "Design errors and mistakes in a CPU's hardwired logic may also be documented
     and described as errata."

Intel publishes them in documents called ....-spec-update.pdf.

Thanks,
Markus.

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
  

On Thu, 1 Mar 2018, Metzger, Markus T wrote:

> The term "erratum" already means 'bug somewhere in the processor'.

 The term "erratum" is generic and usually means a mistake in a published 
text.  You need to be more specific and clarify what the term means in 
this context.

 I think that Eli's proposal sounds about right, except that I agree that 
"firmware" does not really fit here; an erratum may be present in hardware 
logic or in microcode, or it may even be a phenomenon of the manufacturing 
process, e.g. cases have been known where a malfunction of a specific CPU 
operation was caused by thermal effects in silicon in otherwise seemingly 
correct logic.  This makes a "processor erratum" a broad term and 
therefore I think this specific case does not belong to the concept index.

 So how about:

  Processor errata are known to exist 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 or workarounds are enabled based on the processor on 
  which the trace was recorded.

?

  Maciej
  

> Date: Fri, 2 Mar 2018 14:15:20 +0000
> From: "Maciej W. Rozycki" <macro@mips.com>
> CC: Eli Zaretskii <eliz@gnu.org>, "gdb-patches@sourceware.org"
> 	<gdb-patches@sourceware.org>
> 
> On Thu, 1 Mar 2018, Metzger, Markus T wrote:
> 
> > The term "erratum" already means 'bug somewhere in the processor'.
> 
>  The term "erratum" is generic and usually means a mistake in a published 
> text.  You need to be more specific and clarify what the term means in 
> this context.
> 
>  I think that Eli's proposal sounds about right, except that I agree that 
> "firmware" does not really fit here; an erratum may be present in hardware 
> logic or in microcode, or it may even be a phenomenon of the manufacturing 
> process, e.g. cases have been known where a malfunction of a specific CPU 
> operation was caused by thermal effects in silicon in otherwise seemingly 
> correct logic.  This makes a "processor erratum" a broad term and 
> therefore I think this specific case does not belong to the concept index.
> 
>  So how about:
> 
>   Processor errata are known to exist 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 or workarounds are enabled based on the processor on 
>   which the trace was recorded.

That still doesn't explain what are those errata.

How about replacing the first sentence above with these two:

  Processor errata are defects in processor operation, caused by its
  design or manufacture.  They can cause a trace not to match the
  specification.
  

On Fri, 2 Mar 2018, Eli Zaretskii wrote:

> >  So how about:
> > 
> >   Processor errata are known to exist 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 or workarounds are enabled based on the processor on 
> >   which the trace was recorded.
> 
> That still doesn't explain what are those errata.
> 
> How about replacing the first sentence above with these two:
> 
>   Processor errata are defects in processor operation, caused by its
>   design or manufacture.  They can cause a trace not to match the
>   specification.

 Fine with me.

  Maciej
  

On Fri, 2 Mar 2018, Eli Zaretskii wrote:

> >  So how about:
> > 
> >   Processor errata are known to exist 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 or workarounds are enabled based on the processor on 
> >   which the trace was recorded.
> 
> That still doesn't explain what are those errata.
> 
> How about replacing the first sentence above with these two:
> 
>   Processor errata are defects in processor operation, caused by its
>   design or manufacture.  They can cause a trace not to match the
>   specification.

 Fine with me.

  Maciej
  

Hello Eli, Maciej,

> > >  So how about:
> > >
> > >   Processor errata are known to exist 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 or workarounds are enabled based on the processor on
> > >   which the trace was recorded.
> >
> > That still doesn't explain what are those errata.
> >
> > How about replacing the first sentence above with these two:
> >
> >   Processor errata are defects in processor operation, caused by its
> >   design or manufacture.  They can cause a trace not to match the
> >   specification.
> 
>  Fine with me.

Fine with me, as well.  I will send out the full series with the updated
wording and a reduced column limit.

Thanks,
Markus.
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