Commit 4a29fa26 authored by James Clark's avatar James Clark Committed by Suzuki K Poulose
Browse files

coresight: docs: Remove target sink from examples 



Previously the sink had to be specified, but now it auto selects one by
default. Including a sink in the examples causes issues when copy
pasting the command because it might not work if that sink isn't
present. Remove the sink from all the basic examples and create a new
section specifically about overriding the default one.

Make the text a but more concise now that it's in the advanced section,
and similarly for removing the old kernel advice.

Signed-off-by: default avatarJames Clark <james.clark@linaro.org>
Reviewed-by: default avatarLeo Yan <leo.yan@arm.com>
Signed-off-by: default avatarSuzuki K Poulose <suzuki.poulose@arm.com>
Link: https://lore.kernel.org/r/20241210144933.295798-1-james.clark@linaro.org
parent d11eb31d

Documentation/trace/coresight/coresight.rst

+16 −25
Original line number Diff line number Diff line
@@ -462,44 +462,35 @@ queried by the perf command line tool: 


		cs_etm//                                    [Kernel PMU event]



	linaro@linaro-nano:~$



Regardless of the number of tracers available in a system (usually equal to the

amount of processor cores), the "cs_etm" PMU will be listed only once.



A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is

listed along with configuration options within forward slashes '/'.  Since a

Coresight system will typically have more than one sink, the name of the sink to

work with needs to be specified as an event option.

On newer kernels the available sinks are listed in sysFS under

provided along with configuration options within forward slashes '/' (see

`Config option formats`_).



Advanced Perf framework usage

-----------------------------



Sink selection

~~~~~~~~~~~~~~



An appropriate sink will be selected automatically for use with Perf, but since

there will typically be more than one sink, the name of the sink to use may be

specified as a special config option prefixed with '@'.



The available sinks are listed in sysFS under

($SYSFS)/bus/event_source/devices/cs_etm/sinks/::



	root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls

	tmc_etf0  tmc_etr0  tpiu0



On older kernels, this may need to be found from the list of coresight devices,

available under ($SYSFS)/bus/coresight/devices/::



	root:~# ls /sys/bus/coresight/devices/

	 etm0     etm1     etm2         etm3  etm4      etm5      funnel0

	 funnel1  funnel2  replicator0  stm0  tmc_etf0  tmc_etr0  tpiu0

	root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program



As mentioned above in section "Device Naming scheme", the names of the devices could

look different from what is used in the example above. One must use the device names

as it appears under the sysFS.



The syntax within the forward slashes '/' is important.  The '@' character

tells the parser that a sink is about to be specified and that this is the sink

to use for the trace session.



More information on the above and other example on how to use Coresight with

the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub

repository [#third]_.



Advanced perf framework usage

-----------------------------



AutoFDO analysis using the perf tools

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -508,7 +499,7 @@ perf can be used to record and analyze trace of programs. 
Execution can be recorded using 'perf record' with the cs_etm event,

specifying the name of the sink to record to, e.g::



    perf record -e cs_etm/@tmc_etr0/u --per-thread

    perf record -e cs_etm//u --per-thread



The 'perf report' and 'perf script' commands can be used to analyze execution,

synthesizing instruction and branch events from the instruction trace.
@@ -572,7 +563,7 @@ sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tuto 
	Bubble sorting array of 30000 elements

	5910 ms



	$ perf record -e cs_etm/@tmc_etr0/u --per-thread taskset -c 2 ./sort

	$ perf record -e cs_etm//u --per-thread taskset -c 2 ./sort

	Bubble sorting array of 30000 elements

	12543 ms

	[ perf record: Woken up 35 times to write data ]

Documentation/userspace-api/perf_ring_buffer.rst

+2 −2
Original line number Diff line number Diff line
@@ -627,7 +627,7 @@ regular ring buffer. 
AUX events and AUX trace data are two different things.  Let's see an

example::



        perf record -a -e cycles -e cs_etm/@tmc_etr0/ -- sleep 2

        perf record -a -e cycles -e cs_etm// -- sleep 2



The above command enables two events: one is the event *cycles* from PMU

and another is the AUX event *cs_etm* from Arm CoreSight, both are saved
@@ -766,7 +766,7 @@ only record AUX trace data at a specific time point which users are 
interested in.  E.g. below gives an example of how to take snapshots

with 1 second interval with Arm CoreSight::



  perf record -e cs_etm/@tmc_etr0/u -S -a program &

  perf record -e cs_etm//u -S -a program &

  PERFPID=$!

  while true; do

      kill -USR2 $PERFPID