aboutsummaryrefslogtreecommitdiffstats
path: root/HOWTO.md
diff options
context:
space:
mode:
Diffstat (limited to 'HOWTO.md')
-rw-r--r--HOWTO.md115
1 files changed, 74 insertions, 41 deletions
diff --git a/HOWTO.md b/HOWTO.md
index b16294a317ef..c1196ce3c716 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -4,37 +4,39 @@ HOWTO - using the library with perf {#howto_perf}
@brief Using command line perf and OpenCSD to collect and decode trace.
This HOWTO explains how to use the perf cmd line tools and the openCSD
-library to collect and extract program flow traces generated by the
+library to collect and extract program flow traces generated by the
CoreSight IP blocks on a Linux system. The examples have been generated using
-an aarch64 Juno-r0 platform. All information is considered accurate and tested
-using the latest version of the library and the `master` branch on the
-[perf-opencsd github repository][1].
+an aarch64 Juno-r0 platform.
On Target Trace Acquisition - Perf Record
-----------------------------------------
-All the enhancement to the Perf tools that support the new `cs_etm` pmu have
-not been upstreamed yet. To get the required functionality branch
-`perf-opencsd-master` needs to be downloaded to the target system where
-traces are to be collected. This branch is a vanilla upstream kernel
-supplemented with modifications to the CoreSight framework and drivers to be
-usable by the Perf core. The remaining out of tree patches are being
-upstreamed incrementally.
-
-From there compiling the perf tools with `make -C tools/perf CORESIGHT=1` will
-yield a `perf` executable that will support CoreSight trace collection. Note
-that if traces are to be decompressed *off* target, there is no need to download
+
+Compile the perf tool from the same kernel source code version you are using with:
+
+ make -C tools/perf
+
+This will yield a `perf` executable that will support CoreSight trace collection.
+
+*Note:* If traces are to be decompressed **off** target, there is no need to download
and compile the openCSD library (on the target).
+If you are instead planning to use perf to record and decode the trace on the target,
+compile the perf tool linking against the openCSD library, in the following way:
+
+ make -C tools/perf VF=1 CORESIGHT=1
+
+Further information on the needed build environments and options are detailed later
+in the section **Off Target Perf Tools Compilation**.
+
Before launching a trace run a sink that will collect trace data needs to be
identified. All CoreSight blocks identified by the framework are registed in
sysFS:
linaro@linaro-nano:~$ ls /sys/bus/coresight/devices/
- 20010000.etf 20040000.main_funnel 22040000.etm 22140000.etm
- 230c0000.A53_funnel 23240000.etm replicator@20020000 20030000.tpiu
- 20070000.etr 220c0000.A57_funnel 23040000.etm 23140000.etm 23340000.etm
+ etm0 etm2 etm4 etm6 funnel0 funnel2 funnel4 stm0 tmc_etr0
+ etm1 etm3 etm5 etm7 funnel1 funnel3 replicator0 tmc_etf0
CoreSight blocks are listed in the device tree for a specific system and
@@ -43,7 +45,7 @@ the sink that will recieve trace data needs to be identified and given as an
option on the perf command line. Once a sink has been identify trace collection
can start. An easy and yet interesting example is the `uname` command:
- linaro@linaro-nano:~/kernel$ ./tools/perf/perf record -e cs_etm/@20070000.etr/ --per-thread uname
+ linaro@linaro-nano:~/kernel$ ./tools/perf/perf record -e cs_etm/@tmc_etr0/ --per-thread uname
This will generate a `perf.data` file where execution has been traced for both
user and kernel space. To narrow the field to either user or kernel space the
@@ -51,7 +53,7 @@ user and kernel space. To narrow the field to either user or kernel space the
traces to user space:
- linaro@linaro-nano:~/kernel$ ./tools/perf/perf record -vvv -e cs_etm/@20070000.etr/u --per-thread uname
+ linaro@linaro-nano:~/kernel$ ./tools/perf/perf record -vvv -e cs_etm/@tmc_etr0/u --per-thread uname
Problems setting modules path maps, continuing anyway...
-----------------------------------------------------------
perf_event_attr:
@@ -131,9 +133,9 @@ falls within the specified range. Any work done by the CPU outside of that
range will not be traced. Address range filters can be specified for both
user and kernel space session:
- perf record -e cs_etm/@20070000.etr/k --filter 'filter 0xffffff8008562d0c/0x48' --per-thread uname
+ perf record -e cs_etm/@tmc_etr0/k --filter 'filter 0xffffff8008562d0c/0x48' --per-thread uname
- perf record -e cs_etm/@20070000.etr/u --filter 'filter 0x72c/0x40@/opt/lib/libcstest.so.1.0' --per-thread ./main
+ perf record -e cs_etm/@tmc_etr0/u --filter 'filter 0x72c/0x40@/opt/lib/libcstest.so.1.0' --per-thread ./main
When dealing with kernel space trace addresses are typically taken in the
'System.map' file. In user space addresses are relocatable and can be
@@ -171,20 +173,20 @@ equal to the start address. Incidentally traces stop being generated when the
insruction pointer is equal to the stop address. Anything that happens between
there to events is traced:
- perf record -e cs_etm/@20070000.etr/k --filter 'start 0xffffff800856bc50,stop 0xffffff800856bcb0' --per-thread uname
+ perf record -e cs_etm/@tmc_etr0/k --filter 'start 0xffffff800856bc50,stop 0xffffff800856bcb0' --per-thread uname
- perf record -vvv -e cs_etm/@20070000.etr/u --filter 'start 0x72c@/opt/lib/libcstest.so.1.0, \
+ perf record -vvv -e cs_etm/@tmc_etr0/u --filter 'start 0x72c@/opt/lib/libcstest.so.1.0, \
stop 0x40082c@/home/linaro/main' \
- --per-thread ./main
+ --per-thread ./main
**Limitation on address filters:**
The only limitation on address filters is the amount of address comparator
found on an implementation and the mutual exclusion between range and
start stop filters. As such the following example would _not_ work:
- perf record -e cs_etm/@20070000.etr/k --filter 'start 0xffffff800856bc50,stop 0xffffff800856bcb0, \ // start/stop
+ perf record -e cs_etm/@tmc_etr0/k --filter 'start 0xffffff800856bc50,stop 0xffffff800856bcb0, \ // start/stop
filter 0x72c/0x40@/opt/lib/libcstest.so.1.0' \ // address range
- --per-thread uname
+ --per-thread uname
Additional Trace Options
------------------------
@@ -198,10 +200,32 @@ Presently this threshold is fixed at 256 cycles for `perf record`.
Command line options in `perf record` to use these features are part of the options for the `cs_etm` event:
- perf record -e cs_etm/timestamp,cycacc,@20070000.etr/ --per-thread uname
+ perf record -e cs_etm/timestamp,cycacc,@tmc_etr0/ --per-thread uname
At current version, `perf record` and `perf script` do not use this additional information.
+The cs_etm perf event
+---------------------
+
+System information for this perf pmu event can be found at:
+
+ /sys/devices/cs_etm
+
+This contains internal format of the parameters described above:
+
+ root@linaro-developer:~# ls /sys/devices/cs_etm/format
+ contextid cycacc retstack sinkid timestamp
+
+and names of registered sinks:
+
+ root@linaro-developer:~# ls /sys/devices/cs_etm/sinks
+ tmc_etf0 tmc_etr0 tpiu0
+
+Note: The `sinkid` parameter is there to document the usage of a 32-bit internal parameter to
+pass the sink name used in the cs_etm/@sink/ command to the kernel drivers. It can be used
+directly as cs_etm/sinkid=<hash_value>/ but this is not recommended as the values used are
+considered opaque and subject to changes.
+
On Target Trace Collection
--------------------------
The entire program flow will have been recorded in the `perf.data` file.
@@ -248,7 +272,7 @@ The openCSD library is not part of the perf tools. It is available on
[github][1] and needs to be compiled before the perf tools. Checkout the
required branch/tag version into a local directory.
- linaro@t430:~/linaro/coresight$ git clone -b v0.8 https://github.com/Linaro/OpenCSD.git my-opencsd
+ linaro@t430:~/linaro/coresight$ git clone https://github.com/Linaro/OpenCSD.git my-opencsd
Cloning into 'OpenCSD'...
remote: Counting objects: 2063, done.
remote: Total 2063 (delta 0), reused 0 (delta 0), pack-reused 2063
@@ -301,7 +325,8 @@ distribution without having to be compiled.
Off Target Perf Tools Compilation
---------------------------------
-As mentionned above the openCSD library is not part of the perf tools' code base
+
+As mentioned above the openCSD library is not part of the perf tools' code base
and needs to be installed on a system prior to compilation. Information about
the status of the openCSD library on a system is given at compile time by the
perf tools build script:
@@ -366,8 +391,8 @@ output as follows:-
Set to any other value will remove the RAW_PACKED lines.
-Working with a debug version of the openCSD library
----------------------------------------------------
+Working with an alternate version of the openCSD library
+--------------------------------------------------------
When compiling the perf tools it is possible to reference another version of
the openCSD library than the one installed on the system. This is useful when
working with multiple development trees or having the desire to keep system
@@ -407,9 +432,13 @@ where the perf tools and openCSD library have been compiled.
-rw------- 1 linaro linaro 78016 Feb 24 12:21 perf.data
-rw-rw-r-- 1 linaro linaro 1245881 Feb 24 12:25 uname.v4.user.sept20.tgz
-Perf is expecting files related to the trace capture (`perf.data`) to be located
-under `~/.debug` [3]. This example will remove the current `~/.debug` directory
-to be sure everything is clean.
+Perf is expecting files related to the trace capture (`perf.data`) to be located in the `buildid` directory.
+By default this is under `~/.debug`. Alternatively the default `buildid` directory can be changed
+using the command:
+
+ perf config --system buildid.dir=/my/own/buildid/dir
+
+This example will remove the current `~/.debug` directory to be sure everything is clean.
linaro@t430:~/linaro/coresight/sept20$ rm -rf ~/.debug
linaro@t430:~/linaro/coresight/sept20$ cp -dpR .debug ~/
@@ -586,12 +615,18 @@ Use as follows:-
1. Prior to building perf, edit `perf-setup-env.bash` to conform to your environment. There are four lines at the top of the file that will require editing.
-2. Execute the script using the command
+2. Execute the script using the command:
source perf-setup-env.bash
- This will set up all the environment variables mentioned in the sections on building and running
- perf above, and these are used by the `perf-test...` scripts to run the tests.
+ This will set up a perf execute environment for using the perf report and script commands.
+
+ Alternatively use the command:
+
+ source perf-setup-env.base buildenv
+
+ This will add in the build environment variables mentioned in the sections on building above alongside the
+ environment for using the used by the `perf-test...` scripts to run the tests.
3. Build perf as described above.
4. Follow the instructions for downloading the test capture, or create a capture from your target.
@@ -629,8 +664,6 @@ Best regards,
*The Linaro CoreSight Team*
--------------------------------------
-[1]: https://github.com/Linaro/perf-opencsd "perf-opencsd Github"
+[1]: https://github.com/Linaro/OpenCSD
[2]: http://people.linaro.org/~mathieu.poirier/openCSD/uname.v4.user.sept20.tgz
-
-[3]: Get in touch with us if you know a way to change this.