diff mbox series

[v2,7/7] Documentation: coresight: Add PID tracing description

Message ID 20210202163842.134734-8-leo.yan@linaro.org (mailing list archive)
State New, archived
Headers show
Series coresight: etm-perf: Fix pid tracing with VHE | expand

Commit Message

Leo Yan Feb. 2, 2021, 4:38 p.m. UTC
After support the PID tracing for the kernel in EL1 or EL2, the usage
gets more complicated.

This patch gives description for the PMU formats of contextID configs,
this can help users to understand how to control the knobs for PID
tracing when the kernel is in different ELs.

Signed-off-by: Leo Yan <leo.yan@linaro.org>
---
 Documentation/trace/coresight/coresight.rst | 37 +++++++++++++++++++++
 1 file changed, 37 insertions(+)

Comments

Suzuki K Poulose Feb. 2, 2021, 11:24 p.m. UTC | #1
On 2/2/21 4:38 PM, Leo Yan wrote:
> After support the PID tracing for the kernel in EL1 or EL2, the usage
> gets more complicated.
> 
> This patch gives description for the PMU formats of contextID configs,
> this can help users to understand how to control the knobs for PID
> tracing when the kernel is in different ELs.
> 
> Signed-off-by: Leo Yan <leo.yan@linaro.org>
> ---
>   Documentation/trace/coresight/coresight.rst | 37 +++++++++++++++++++++
>   1 file changed, 37 insertions(+)
> 
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 0b73acb44efa..771558f22938 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -512,6 +512,43 @@ The --itrace option controls the type and frequency of synthesized events
>   Note that only 64-bit programs are currently supported - further work is
>   required to support instruction decode of 32-bit Arm programs.
>   
> +2.2) Tracing PID
> +
> +When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
> +perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
> +decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
> +traced for PID.
> +
> +To support tracing PID for the kernel runs at different exception levels,
> +the PMU formats are defined as follow:
> +
> +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
> +                kernel is running at EL1, "contextid1" enables the PID
> +                tracing; when the kernel is running at EL2, this enables
> +                tracing the PID of guest applications.
> +
> +  "contextid2": Only usable when the kernel is running at EL2.  When
> +                selected, enables PID tracing on EL2 kernel.
> +
> +  "contextid":  Will be an alias for the option that enables PID
> +                tracing.  I.e,
> +                contextid == contextid1, on EL1 kernel.
> +                contextid == contextid2, on EL2 kernel.
> +
> +The perf tool automatically sets corresponding bit for the "contextid" config,
> +therefore, the user doesn't have to bother which EL the kernel is running.
> +
> +  i.e, perf record -e cs_etm/contextid/u -- uname
> +    or perf record -e cs_etm//u -- uname
> +
> +will always do the "PID" tracing, independent of the kernel EL.
> +
> +When the kernel is running at EL2 with VHE, if user wants to trace both the
> +PIDs for both host and guest, the two configs "contextid1" and "contextid2"
> +can be set at the same time:
> +
> +  perf record -e cs_etm/contextid1,contextid2/u -- uname
> +

To make this case clear, we could change the command from uname to
something like:

     perf record -e cs_etm/contextid1,contextid2/u -- vm

Otherwise looks good to me.

With the above fixed,

Reviewed-by: Suzuki K Poulose <suzuki.poulose@arm.com>
Mike Leach Feb. 3, 2021, 5:39 p.m. UTC | #2
Hi,

On Tue, 2 Feb 2021 at 16:39, Leo Yan <leo.yan@linaro.org> wrote:
>
> After support the PID tracing for the kernel in EL1 or EL2, the usage
> gets more complicated.
>
> This patch gives description for the PMU formats of contextID configs,
> this can help users to understand how to control the knobs for PID
> tracing when the kernel is in different ELs.
>
> Signed-off-by: Leo Yan <leo.yan@linaro.org>
> ---
>  Documentation/trace/coresight/coresight.rst | 37 +++++++++++++++++++++
>  1 file changed, 37 insertions(+)
>
> diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> index 0b73acb44efa..771558f22938 100644
> --- a/Documentation/trace/coresight/coresight.rst
> +++ b/Documentation/trace/coresight/coresight.rst
> @@ -512,6 +512,43 @@ The --itrace option controls the type and frequency of synthesized events
>  Note that only 64-bit programs are currently supported - further work is
>  required to support instruction decode of 32-bit Arm programs.
>
> +2.2) Tracing PID
> +
> +When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
> +perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
> +decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
> +traced for PID.
> +

Would this introductory paragraph be better if is explained where the
kernel stores the PID for the different levels, then we logically move
on to how to trace this in perf.

e.g:-

"The lernel can be built to write the PID value into the PE ContextID registers.
For a kernel running at EL1, the PID is stored in CONTEXTIDR_EL1.
A PE may implement ARM Virtualisation Host Extensions (VHE), were the
kernel can run at EL2 as a virtualisation host.
In this case the PID value is stored in CONTEXTIDR_EL2.
perf provides PMU options which program the ETM to insert these values
into the trace data."

> +To support tracing PID for the kernel runs at different exception levels,
> +the PMU formats are defined as follow:
> +
> +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
> +                kernel is running at EL1, "contextid1" enables the PID
> +                tracing; when the kernel is running at EL2, this enables
> +                tracing the PID of guest applications.
> +
> +  "contextid2": Only usable when the kernel is running at EL2.  When
> +                selected, enables PID tracing on EL2 kernel.
> +
> +  "contextid":  Will be an alias for the option that enables PID
> +                tracing.  I.e,
> +                contextid == contextid1, on EL1 kernel.
> +                contextid == contextid2, on EL2 kernel.
> +
> +The perf tool automatically sets corresponding bit for the "contextid" config,
> +therefore, the user doesn't have to bother which EL the kernel is running.
> +
> +  i.e, perf record -e cs_etm/contextid/u -- uname
> +    or perf record -e cs_etm//u -- uname
> +
> +will always do the "PID" tracing, independent of the kernel EL.
> +

This is telling me that both cs_etm// and cs_etm/contextid/ have the
same effect - trace PID. Is this correct?
If so, then contextid, contextid1 and contextid2 have no effect except
in specific EL2 circumstances.


> +When the kernel is running at EL2 with VHE, if user wants to trace both the
> +PIDs for both host and guest, the two configs "contextid1" and "contextid2"
> +can be set at the same time:
> +
> +  perf record -e cs_etm/contextid1,contextid2/u -- uname
> +
>


Regards

Mike


>  Generating coverage files for Feedback Directed Optimization: AutoFDO
>  ---------------------------------------------------------------------
> --
> 2.25.1
>


--
Mike Leach
Principal Engineer, ARM Ltd.
Manchester Design Centre. UK
Leo Yan Feb. 4, 2021, 4:02 a.m. UTC | #3
On Tue, Feb 02, 2021 at 11:24:48PM +0000, Suzuki Kuruppassery Poulose wrote:
> On 2/2/21 4:38 PM, Leo Yan wrote:
> > After support the PID tracing for the kernel in EL1 or EL2, the usage
> > gets more complicated.
> > 
> > This patch gives description for the PMU formats of contextID configs,
> > this can help users to understand how to control the knobs for PID
> > tracing when the kernel is in different ELs.
> > 
> > Signed-off-by: Leo Yan <leo.yan@linaro.org>
> > ---
> >   Documentation/trace/coresight/coresight.rst | 37 +++++++++++++++++++++
> >   1 file changed, 37 insertions(+)
> > 
> > diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
> > index 0b73acb44efa..771558f22938 100644
> > --- a/Documentation/trace/coresight/coresight.rst
> > +++ b/Documentation/trace/coresight/coresight.rst
> > @@ -512,6 +512,43 @@ The --itrace option controls the type and frequency of synthesized events
> >   Note that only 64-bit programs are currently supported - further work is
> >   required to support instruction decode of 32-bit Arm programs.
> > +2.2) Tracing PID
> > +
> > +When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
> > +perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
> > +decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
> > +traced for PID.
> > +
> > +To support tracing PID for the kernel runs at different exception levels,
> > +the PMU formats are defined as follow:
> > +
> > +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
> > +                kernel is running at EL1, "contextid1" enables the PID
> > +                tracing; when the kernel is running at EL2, this enables
> > +                tracing the PID of guest applications.
> > +
> > +  "contextid2": Only usable when the kernel is running at EL2.  When
> > +                selected, enables PID tracing on EL2 kernel.
> > +
> > +  "contextid":  Will be an alias for the option that enables PID
> > +                tracing.  I.e,
> > +                contextid == contextid1, on EL1 kernel.
> > +                contextid == contextid2, on EL2 kernel.
> > +
> > +The perf tool automatically sets corresponding bit for the "contextid" config,
> > +therefore, the user doesn't have to bother which EL the kernel is running.
> > +
> > +  i.e, perf record -e cs_etm/contextid/u -- uname
> > +    or perf record -e cs_etm//u -- uname
> > +
> > +will always do the "PID" tracing, independent of the kernel EL.
> > +
> > +When the kernel is running at EL2 with VHE, if user wants to trace both the
> > +PIDs for both host and guest, the two configs "contextid1" and "contextid2"
> > +can be set at the same time:
> > +
> > +  perf record -e cs_etm/contextid1,contextid2/u -- uname
> > +
> 
> To make this case clear, we could change the command from uname to
> something like:
> 
>     perf record -e cs_etm/contextid1,contextid2/u -- vm

Exactly, will refine.

> Otherwise looks good to me.
> 
> With the above fixed,
> 
> Reviewed-by: Suzuki K Poulose <suzuki.poulose@arm.com>

Thanks,
Leo
Leo Yan Feb. 4, 2021, 4:09 a.m. UTC | #4
Hi Mike,

On Wed, Feb 03, 2021 at 05:39:54PM +0000, Mike Leach wrote:

[...]

> > +2.2) Tracing PID
> > +
> > +When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
> > +perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
> > +decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
> > +traced for PID.
> > +
> 
> Would this introductory paragraph be better if is explained where the
> kernel stores the PID for the different levels, then we logically move
> on to how to trace this in perf.
> 
> e.g:-
> 
> "The lernel can be built to write the PID value into the PE ContextID registers.
> For a kernel running at EL1, the PID is stored in CONTEXTIDR_EL1.
> A PE may implement ARM Virtualisation Host Extensions (VHE), were the
> kernel can run at EL2 as a virtualisation host.
> In this case the PID value is stored in CONTEXTIDR_EL2.
> perf provides PMU options which program the ETM to insert these values
> into the trace data."

Will in next spin; thanks a lot for writing up!

> > +To support tracing PID for the kernel runs at different exception levels,
> > +the PMU formats are defined as follow:
> > +
> > +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
> > +                kernel is running at EL1, "contextid1" enables the PID
> > +                tracing; when the kernel is running at EL2, this enables
> > +                tracing the PID of guest applications.
> > +
> > +  "contextid2": Only usable when the kernel is running at EL2.  When
> > +                selected, enables PID tracing on EL2 kernel.
> > +
> > +  "contextid":  Will be an alias for the option that enables PID
> > +                tracing.  I.e,
> > +                contextid == contextid1, on EL1 kernel.
> > +                contextid == contextid2, on EL2 kernel.
> > +
> > +The perf tool automatically sets corresponding bit for the "contextid" config,
> > +therefore, the user doesn't have to bother which EL the kernel is running.
> > +
> > +  i.e, perf record -e cs_etm/contextid/u -- uname
> > +    or perf record -e cs_etm//u -- uname
> > +
> > +will always do the "PID" tracing, independent of the kernel EL.
> > +
> 
> This is telling me that both cs_etm// and cs_etm/contextid/ have the
> same effect - trace PID. Is this correct?

Correct.

> If so, then contextid, contextid1 and contextid2 have no effect except
> in specific EL2 circumstances.

Yes, exactly.

Thanks,
Leo

> > +When the kernel is running at EL2 with VHE, if user wants to trace both the
> > +PIDs for both host and guest, the two configs "contextid1" and "contextid2"
> > +can be set at the same time:
> > +
> > +  perf record -e cs_etm/contextid1,contextid2/u -- uname
> > +
> >
> 
> 
> Regards
> 
> Mike
> 
> 
> >  Generating coverage files for Feedback Directed Optimization: AutoFDO
> >  ---------------------------------------------------------------------
> > --
> > 2.25.1
> >
> 
> 
> --
> Mike Leach
> Principal Engineer, ARM Ltd.
> Manchester Design Centre. UK
Suzuki K Poulose Feb. 4, 2021, 11:08 a.m. UTC | #5
On 2/4/21 4:09 AM, Leo Yan wrote:
> Hi Mike,
> 
> On Wed, Feb 03, 2021 at 05:39:54PM +0000, Mike Leach wrote:
> 
> [...]
> 
>>> +2.2) Tracing PID
>>> +
>>> +When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
>>> +perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
>>> +decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
>>> +traced for PID.
>>> +
>>
>> Would this introductory paragraph be better if is explained where the
>> kernel stores the PID for the different levels, then we logically move
>> on to how to trace this in perf.
>>
>> e.g:-
>>
>> "The lernel can be built to write the PID value into the PE ContextID registers.
>> For a kernel running at EL1, the PID is stored in CONTEXTIDR_EL1.
>> A PE may implement ARM Virtualisation Host Extensions (VHE), were the
>> kernel can run at EL2 as a virtualisation host.
>> In this case the PID value is stored in CONTEXTIDR_EL2.
>> perf provides PMU options which program the ETM to insert these values
>> into the trace data."
> 
> Will in next spin; thanks a lot for writing up!
> 
>>> +To support tracing PID for the kernel runs at different exception levels,
>>> +the PMU formats are defined as follow:
>>> +
>>> +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
>>> +                kernel is running at EL1, "contextid1" enables the PID
>>> +                tracing; when the kernel is running at EL2, this enables
>>> +                tracing the PID of guest applications.
>>> +
>>> +  "contextid2": Only usable when the kernel is running at EL2.  When
>>> +                selected, enables PID tracing on EL2 kernel.
>>> +
>>> +  "contextid":  Will be an alias for the option that enables PID
>>> +                tracing.  I.e,
>>> +                contextid == contextid1, on EL1 kernel.
>>> +                contextid == contextid2, on EL2 kernel.
>>> +
>>> +The perf tool automatically sets corresponding bit for the "contextid" config,
>>> +therefore, the user doesn't have to bother which EL the kernel is running.
>>> +
>>> +  i.e, perf record -e cs_etm/contextid/u -- uname
>>> +    or perf record -e cs_etm//u -- uname
>>> +
>>> +will always do the "PID" tracing, independent of the kernel EL.
>>> +
>>
>> This is telling me that both cs_etm// and cs_etm/contextid/ have the
>> same effect - trace PID. Is this correct?
> 

Just to make this clear, this is not a side effect of the patch. The perf
tool driver automatically adds the "contextid" tracing and timestamp for
"system wide" and process bound events, as they traces get mixed into
the single sink. So these options are added implicitly by the perf tool
to make the decoding easier.

> Correct.
> 
>> If so, then contextid, contextid1 and contextid2 have no effect except
>> in specific EL2 circumstances.

These are required when perf tool may not automatically request them.
With this series the EL2 is on par with the EL1, where we get the PID
automatcially in the trace.

And as you rightly said, contextid1, contextid2 are for EL2 specific
usage.

Cheers
Suzuki

> 
> Yes, exactly.
> 
> Thanks,
> Leo
> 
>>> +When the kernel is running at EL2 with VHE, if user wants to trace both the
>>> +PIDs for both host and guest, the two configs "contextid1" and "contextid2"
>>> +can be set at the same time:
>>> +
>>> +  perf record -e cs_etm/contextid1,contextid2/u -- uname
>>> +
>>>
>>
>>
>> Regards
>>
>> Mike
>>
>>
>>>   Generating coverage files for Feedback Directed Optimization: AutoFDO
>>>   ---------------------------------------------------------------------
>>> --
>>> 2.25.1
>>>
>>
>>
>> --
>> Mike Leach
>> Principal Engineer, ARM Ltd.
>> Manchester Design Centre. UK
Mike Leach Feb. 4, 2021, 12:14 p.m. UTC | #6
Hi,

On Thu, 4 Feb 2021 at 11:08, Suzuki K Poulose <suzuki.poulose@arm.com> wrote:
>
> On 2/4/21 4:09 AM, Leo Yan wrote:
> > Hi Mike,
> >
> > On Wed, Feb 03, 2021 at 05:39:54PM +0000, Mike Leach wrote:
> >
> > [...]
> >
> >>> +2.2) Tracing PID
> >>> +
> >>> +When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
> >>> +perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
> >>> +decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
> >>> +traced for PID.
> >>> +
> >>
> >> Would this introductory paragraph be better if is explained where the
> >> kernel stores the PID for the different levels, then we logically move
> >> on to how to trace this in perf.
> >>
> >> e.g:-
> >>
> >> "The lernel can be built to write the PID value into the PE ContextID registers.
> >> For a kernel running at EL1, the PID is stored in CONTEXTIDR_EL1.
> >> A PE may implement ARM Virtualisation Host Extensions (VHE), were the
> >> kernel can run at EL2 as a virtualisation host.
> >> In this case the PID value is stored in CONTEXTIDR_EL2.
> >> perf provides PMU options which program the ETM to insert these values
> >> into the trace data."
> >
> > Will in next spin; thanks a lot for writing up!
> >
> >>> +To support tracing PID for the kernel runs at different exception levels,
> >>> +the PMU formats are defined as follow:
> >>> +
> >>> +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
> >>> +                kernel is running at EL1, "contextid1" enables the PID
> >>> +                tracing; when the kernel is running at EL2, this enables
> >>> +                tracing the PID of guest applications.
> >>> +
> >>> +  "contextid2": Only usable when the kernel is running at EL2.  When
> >>> +                selected, enables PID tracing on EL2 kernel.
> >>> +
> >>> +  "contextid":  Will be an alias for the option that enables PID
> >>> +                tracing.  I.e,
> >>> +                contextid == contextid1, on EL1 kernel.
> >>> +                contextid == contextid2, on EL2 kernel.
> >>> +
> >>> +The perf tool automatically sets corresponding bit for the "contextid" config,
> >>> +therefore, the user doesn't have to bother which EL the kernel is running.
> >>> +
> >>> +  i.e, perf record -e cs_etm/contextid/u -- uname
> >>> +    or perf record -e cs_etm//u -- uname
> >>> +
> >>> +will always do the "PID" tracing, independent of the kernel EL.
> >>> +
> >>
> >> This is telling me that both cs_etm// and cs_etm/contextid/ have the
> >> same effect - trace PID. Is this correct?
> >
>
> Just to make this clear, this is not a side effect of the patch.

Which is fine - but the documentation should accurately reflect what
is happening on the system.
This is a new paragraph about the PID tracing or otherwise, Even if
some of the effects pre-date this patch, they have to be accurately
communicated.
I am also reading the new paragraph in the context of the rest of the
coresight.rst document - which is a user level document explaining the
basic operation of the coresight system and tools.
This document mentions no other perf command line parameters relevant
to coresight other than the @sink option.It actually calls out to the
OpenCSD docs to provide further information.

> The perf
> tool driver automatically adds the "contextid" tracing and timestamp for
> "system wide" and process bound events, as they traces get mixed into
> the single sink. So these options are added implicitly by the perf tool
> to make the decoding easier.
>

That's fine - I have no problem with contextID trace enabled by
default. Context ID is relatively low overhead - and only emitted at
start of trace  / context changes.
But the explanation of the parameters currently reads as though they
always have an effect - and not putting them in there will omit the
effect - unless you spot the very subtle line at the end.

The user does not need to know about parameters that have no effect!

Perhaps a better approach would be to explain the above - an explicit
statement that "perf will always enable PID/ contextID tracing at the
relevant EL - but for EL2 it is possible to make specific adjustments
using parameters......."

Cheers

Mike


> > Correct.
> >
> >> If so, then contextid, contextid1 and contextid2 have no effect except
> >> in specific EL2 circumstances.
>
> These are required when perf tool may not automatically request them.
> With this series the EL2 is on par with the EL1, where we get the PID
> automatcially in the trace.
>
> And as you rightly said, contextid1, contextid2 are for EL2 specific
> usage.
>
> Cheers
> Suzuki
>
> >
> > Yes, exactly.
> >
> > Thanks,
> > Leo
> >
> >>> +When the kernel is running at EL2 with VHE, if user wants to trace both the
> >>> +PIDs for both host and guest, the two configs "contextid1" and "contextid2"
> >>> +can be set at the same time:
> >>> +
> >>> +  perf record -e cs_etm/contextid1,contextid2/u -- uname
> >>> +
> >>>
> >>
> >>
> >> Regards
> >>
> >> Mike
> >>
> >>
> >>>   Generating coverage files for Feedback Directed Optimization: AutoFDO
> >>>   ---------------------------------------------------------------------
> >>> --
> >>> 2.25.1
> >>>
> >>
> >>
> >> --
> >> Mike Leach
> >> Principal Engineer, ARM Ltd.
> >> Manchester Design Centre. UK
>
Leo Yan Feb. 5, 2021, 5:42 a.m. UTC | #7
On Thu, Feb 04, 2021 at 12:14:12PM +0000, Mike Leach wrote:

[...]

> > >>> +To support tracing PID for the kernel runs at different exception levels,
> > >>> +the PMU formats are defined as follow:
> > >>> +
> > >>> +  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
> > >>> +                kernel is running at EL1, "contextid1" enables the PID
> > >>> +                tracing; when the kernel is running at EL2, this enables
> > >>> +                tracing the PID of guest applications.
> > >>> +
> > >>> +  "contextid2": Only usable when the kernel is running at EL2.  When
> > >>> +                selected, enables PID tracing on EL2 kernel.
> > >>> +
> > >>> +  "contextid":  Will be an alias for the option that enables PID
> > >>> +                tracing.  I.e,
> > >>> +                contextid == contextid1, on EL1 kernel.
> > >>> +                contextid == contextid2, on EL2 kernel.
> > >>> +
> > >>> +The perf tool automatically sets corresponding bit for the "contextid" config,
> > >>> +therefore, the user doesn't have to bother which EL the kernel is running.
> > >>> +
> > >>> +  i.e, perf record -e cs_etm/contextid/u -- uname
> > >>> +    or perf record -e cs_etm//u -- uname
> > >>> +
> > >>> +will always do the "PID" tracing, independent of the kernel EL.
> > >>> +
> > >>
> > >> This is telling me that both cs_etm// and cs_etm/contextid/ have the
> > >> same effect - trace PID. Is this correct?
> > >
> >
> > Just to make this clear, this is not a side effect of the patch.
> 
> Which is fine - but the documentation should accurately reflect what
> is happening on the system.
> This is a new paragraph about the PID tracing or otherwise, Even if
> some of the effects pre-date this patch, they have to be accurately
> communicated.
> I am also reading the new paragraph in the context of the rest of the
> coresight.rst document - which is a user level document explaining the
> basic operation of the coresight system and tools.
> This document mentions no other perf command line parameters relevant
> to coresight other than the @sink option.It actually calls out to the
> OpenCSD docs to provide further information.
> 
> > The perf
> > tool driver automatically adds the "contextid" tracing and timestamp for
> > "system wide" and process bound events, as they traces get mixed into
> > the single sink. So these options are added implicitly by the perf tool
> > to make the decoding easier.
> >
> 
> That's fine - I have no problem with contextID trace enabled by
> default. Context ID is relatively low overhead - and only emitted at
> start of trace  / context changes.
> But the explanation of the parameters currently reads as though they
> always have an effect - and not putting them in there will omit the
> effect - unless you spot the very subtle line at the end.
> 
> The user does not need to know about parameters that have no effect!

Thanks for the suggestion, Mike.

> Perhaps a better approach would be to explain the above - an explicit
> statement that "perf will always enable PID/ contextID tracing at the
> relevant EL - but for EL2 it is possible to make specific adjustments
> using parameters......."

Usually users assume the PMU format has no effect if without set it; but
this is not the case for the config "contextid", this config has been
automatically enabled by perf tool.

Based on your suggesiton, will refine the descrption for two things:
clarify what's the common usage for EL1/EL2, and what's specific for
EL2.

Thanks,
Leo
diff mbox series

Patch

diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst
index 0b73acb44efa..771558f22938 100644
--- a/Documentation/trace/coresight/coresight.rst
+++ b/Documentation/trace/coresight/coresight.rst
@@ -512,6 +512,43 @@  The --itrace option controls the type and frequency of synthesized events
 Note that only 64-bit programs are currently supported - further work is
 required to support instruction decode of 32-bit Arm programs.
 
+2.2) Tracing PID
+
+When the kernel is running at EL2 with Virtualization Host Extensions (VHE),
+perf records CONTEXTIDR_EL2 in the trace data and can be used as PID when
+decoding; and if the kernel is running at EL1 with nVHE, CONTEXTIDR_EL1 is
+traced for PID.
+
+To support tracing PID for the kernel runs at different exception levels,
+the PMU formats are defined as follow:
+
+  "contextid1": Available on both EL1 kernel and EL2 kernel.  When the
+                kernel is running at EL1, "contextid1" enables the PID
+                tracing; when the kernel is running at EL2, this enables
+                tracing the PID of guest applications.
+
+  "contextid2": Only usable when the kernel is running at EL2.  When
+                selected, enables PID tracing on EL2 kernel.
+
+  "contextid":  Will be an alias for the option that enables PID
+                tracing.  I.e,
+                contextid == contextid1, on EL1 kernel.
+                contextid == contextid2, on EL2 kernel.
+
+The perf tool automatically sets corresponding bit for the "contextid" config,
+therefore, the user doesn't have to bother which EL the kernel is running.
+
+  i.e, perf record -e cs_etm/contextid/u -- uname
+    or perf record -e cs_etm//u -- uname
+
+will always do the "PID" tracing, independent of the kernel EL.
+
+When the kernel is running at EL2 with VHE, if user wants to trace both the
+PIDs for both host and guest, the two configs "contextid1" and "contextid2"
+can be set at the same time:
+
+  perf record -e cs_etm/contextid1,contextid2/u -- uname
+
 
 Generating coverage files for Feedback Directed Optimization: AutoFDO
 ---------------------------------------------------------------------