Re: [PATCH 25/25] Documentation: coresight: Document AUX sample decoding

[James Clark <james.clark@linaro.org>]

On 15/09/2026 16:49, Leo Yan wrote:
> Describe recording AUX trace in PMU samples and generating callchains
> and branch stacks with --itrace=G and --itrace=L.
> 
> Explain the default decoding behavior, preservation of recorded stacks,
> context ID requirements and decoding limitations.
> 
> Assisted-by: Codex:gpt-6
> Signed-off-by: Leo Yan <leo.yan@arm.com>
> ---
>   Documentation/trace/coresight/coresight-perf.rst | 39 ++++++++++++++++++++++++
>   1 file changed, 39 insertions(+)
> 
> diff --git a/Documentation/trace/coresight/coresight-perf.rst b/Documentation/trace/coresight/coresight-perf.rst
> index c0c82b3d26ea88dad7143afdb047c4d8f502b4a6..59eda2a5b6473ed1cb6bade5d281a12bdde76bb0 100644
> --- a/Documentation/trace/coresight/coresight-perf.rst
> +++ b/Documentation/trace/coresight/coresight-perf.rst
> @@ -171,6 +171,45 @@ no branch history at all, for example samples from a thread that was never
>   traced, or samples recorded before the first or after the last trace window.
>   It is built and installed with perf's other dlfilters.
>   
> +Decode branch stack and callchain from AUX samples
> +--------------------------------------------------
> +
> +With a kernel that supports CoreSight AUX sampling, record an AUX trace
> +window inside each cycle sample::
> +
> +  perf record --aux-sample=8192 -e '{cs_etm//u,cycles/period=100003/u}' \
> +        -- ./workload
> +  perf script --itrace=G16L64 -F comm,pid,tid,cpu,event,ip,brstack
> +
> +``G16`` adds a reconstructed callchain and ``L64`` adds up to 64 branches.
> +Either option can be used alone. Existing callchains and branch stacks are
> +preserved. Without an explicit ``--itrace`` option, both are enabled for AUX
> +samples. Decoded history is available in ``perf script`` and ``perf report``.
> +
> +AUX sampling supports unformatted, per-CPU sink (TRBE) trace. Each sample

Minor nit, but "per-CPU" in this context might be confusing for users. I 
know we've used "percpu_sink" in the driver (unrelated, but maybe 
"single_source" would be better there anyway), but from the point of 
view of userspace, "per-CPU" and "per-thread" would be related to how 
the event is opened. Which doesn't affect aux sampling.

> +selects its CPU's decoder and starts a fresh trace window. The window already
> +belongs to the sample, so ETM timestamps are not required for attribution.
> +Samples without decodable history receive no reconstructed stack. CPU-wide
> +recordings must enable context IDs to distinguish tasks within a window; the
> +default recording setup enables them.
> +
> +Callchains cover only calls visible in the captured window; callers before
> +the first synchronization point cannot be recovered.
> +
> +When kernel tracing is enabled, AUX samples can include PMU interrupt-handler
> +execution before the trace source is paused. The late-sample helpers trim
> +this using instruction addresses, which may not uniquely identify the sample
> +boundary for kernel samples.
> +
> +Formatted sinks such as ETR are not supported. They can collect trace from
> +sources on multiple CPUs in a shared buffer, mixing execution from unrelated
> +threads into the AUX sample. Context IDs can distinguish these threads, but
> +trace from other CPUs can consume the limited sample window, leaving little
> +history for the sampled thread.

This isn't really an issue if you are only tracing a single process 
regardless of shared sinks. As the aux sampling driver implementation is 
quite tied to the sink, it only makes sense to say we didn't implement 
it because we think the main users only want TRBE, and it's extra 
complexity to do it for ETR. But that doesn't really seem necessary to 
mention here.

TRBE also supports multiple threads anyway, because you haven't put a 
hard limitation on using --per-thread.


> +
> +Guest samples, synthesizing instruction events, and saving reconstructed

I don't think guest is working anyway even without aux sampling. There 
is some structure left in the code for if we ever decide to support it. 
But I don't think we should mention or do anything special for guest in 
relation to aux sampling.

> +callchains with ``perf inject`` are also unsupported.
> +
>   Perf test - Verify kernel and userspace perf CoreSight work
>   -----------------------------------------------------------
>   
>