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

[Suzuki K Poulose]

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 at 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 at arm.com>