Documentation: coresight: convert txt to rst
This changes from plain text to reStructuredText as suggestion in doc-guide [1] [1] https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html Some adaptations such as: literal block, ``inline literal`` and alignment text,... Signed-off-by: Phong Tran <tranmanphong@gmail.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Mathieu Poirier <mathieu.poirier@linaro.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Phong Tran
Jonathan Corbet
parent
34d5f4f269
commit
fe13225fdc
|
|
@ -1,8 +1,9 @@
|
|||
==========================
|
||||
Coresight CPU Debug Module
|
||||
==========================
|
||||
|
||||
Author: Leo Yan <leo.yan@linaro.org>
|
||||
Date: April 5th, 2017
|
||||
:Author: Leo Yan <leo.yan@linaro.org>
|
||||
:Date: April 5th, 2017
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
|
@ -69,6 +70,7 @@ Before accessing debug registers, we should ensure the clock and power domain
|
|||
have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1
|
||||
Debug registers', the debug registers are spread into two domains: the debug
|
||||
domain and the CPU domain.
|
||||
::
|
||||
|
||||
+---------------+
|
||||
| |
|
||||
|
|
@ -125,17 +127,20 @@ If you want to enable debugging functionality at boot time, you can add
|
|||
"coresight_cpu_debug.enable=1" to the kernel command line parameter.
|
||||
|
||||
The driver also can work as module, so can enable the debugging when insmod
|
||||
module:
|
||||
module::
|
||||
|
||||
# insmod coresight_cpu_debug.ko debug=1
|
||||
|
||||
When boot time or insmod module you have not enabled the debugging, the driver
|
||||
uses the debugfs file system to provide a knob to dynamically enable or disable
|
||||
debugging:
|
||||
|
||||
To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:
|
||||
To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::
|
||||
|
||||
# echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable
|
||||
|
||||
To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:
|
||||
To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::
|
||||
|
||||
# echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
|
||||
|
||||
As explained in chapter "Clock and power domain", if you are working on one
|
||||
|
|
@ -154,7 +159,7 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
|
|||
interface (see Documentation/power/pm_qos_interface.rst for more
|
||||
details). As specified in the PM QoS documentation the requested
|
||||
parameter will stay in effect until the file descriptor is released.
|
||||
For example:
|
||||
For example::
|
||||
|
||||
# exec 3<> /dev/cpu_dma_latency; echo 0 >&3
|
||||
...
|
||||
|
|
@ -165,14 +170,14 @@ Do some work...
|
|||
The same can also be done from an application program.
|
||||
|
||||
Disable specific CPU's specific idle state from cpuidle sysfs (see
|
||||
Documentation/admin-guide/pm/cpuidle.rst):
|
||||
# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
|
||||
Documentation/admin-guide/pm/cpuidle.rst)::
|
||||
|
||||
# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable
|
||||
|
||||
Output format
|
||||
-------------
|
||||
|
||||
Here is an example of the debugging output format:
|
||||
Here is an example of the debugging output format::
|
||||
|
||||
ARM external debug module:
|
||||
coresight-cpu-debug 850000.debug: CPU[0]:
|
||||
|
|
@ -1,8 +1,9 @@
|
|||
======================================
|
||||
Coresight - HW Assisted Tracing on ARM
|
||||
======================================
|
||||
|
||||
Author: Mathieu Poirier <mathieu.poirier@linaro.org>
|
||||
Date: September 11th, 2014
|
||||
:Author: Mathieu Poirier <mathieu.poirier@linaro.org>
|
||||
:Date: September 11th, 2014
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
|
@ -26,7 +27,7 @@ implementation, either storing the compressed stream in a memory buffer or
|
|||
creating an interface to the outside world where data can be transferred to a
|
||||
host without fear of filling up the onboard coresight memory buffer.
|
||||
|
||||
At typical coresight system would look like this:
|
||||
At typical coresight system would look like this::
|
||||
|
||||
*****************************************************************
|
||||
**************************** AMBA AXI ****************************===||
|
||||
|
|
@ -95,15 +96,24 @@ Acronyms and Classification
|
|||
|
||||
Acronyms:
|
||||
|
||||
PTM: Program Trace Macrocell
|
||||
ETM: Embedded Trace Macrocell
|
||||
STM: System trace Macrocell
|
||||
ETB: Embedded Trace Buffer
|
||||
ITM: Instrumentation Trace Macrocell
|
||||
TPIU: Trace Port Interface Unit
|
||||
TMC-ETR: Trace Memory Controller, configured as Embedded Trace Router
|
||||
TMC-ETF: Trace Memory Controller, configured as Embedded Trace FIFO
|
||||
CTI: Cross Trigger Interface
|
||||
PTM:
|
||||
Program Trace Macrocell
|
||||
ETM:
|
||||
Embedded Trace Macrocell
|
||||
STM:
|
||||
System trace Macrocell
|
||||
ETB:
|
||||
Embedded Trace Buffer
|
||||
ITM:
|
||||
Instrumentation Trace Macrocell
|
||||
TPIU:
|
||||
Trace Port Interface Unit
|
||||
TMC-ETR:
|
||||
Trace Memory Controller, configured as Embedded Trace Router
|
||||
TMC-ETF:
|
||||
Trace Memory Controller, configured as Embedded Trace FIFO
|
||||
CTI:
|
||||
Cross Trigger Interface
|
||||
|
||||
Classification:
|
||||
|
||||
|
|
@ -118,7 +128,7 @@ Misc:
|
|||
|
||||
|
||||
Device Tree Bindings
|
||||
----------------------
|
||||
--------------------
|
||||
|
||||
See Documentation/devicetree/bindings/arm/coresight.txt for details.
|
||||
|
||||
|
|
@ -133,22 +143,22 @@ The coresight framework provides a central point to represent, configure and
|
|||
manage coresight devices on a platform. Any coresight compliant device can
|
||||
register with the framework for as long as they use the right APIs:
|
||||
|
||||
struct coresight_device *coresight_register(struct coresight_desc *desc);
|
||||
void coresight_unregister(struct coresight_device *csdev);
|
||||
.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc);
|
||||
.. c:function:: void coresight_unregister(struct coresight_device *csdev);
|
||||
|
||||
The registering function is taking a "struct coresight_device *csdev" and
|
||||
The registering function is taking a ``struct coresight_desc *desc`` and
|
||||
register the device with the core framework. The unregister function takes
|
||||
a reference to a "struct coresight_device", obtained at registration time.
|
||||
a reference to a ``struct coresight_device *csdev`` obtained at registration time.
|
||||
|
||||
If everything goes well during the registration process the new devices will
|
||||
show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:
|
||||
show up under /sys/bus/coresight/devices, as showns here for a TC2 platform::
|
||||
|
||||
root:~# ls /sys/bus/coresight/devices/
|
||||
replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
|
||||
20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
|
||||
root:~#
|
||||
|
||||
The functions take a "struct coresight_device", which looks like this:
|
||||
The functions take a ``struct coresight_device``, which looks like this::
|
||||
|
||||
struct coresight_desc {
|
||||
enum coresight_dev_type type;
|
||||
|
|
@ -163,15 +173,15 @@ struct coresight_desc {
|
|||
The "coresight_dev_type" identifies what the device is, i.e, source link or
|
||||
sink while the "coresight_dev_subtype" will characterise that type further.
|
||||
|
||||
The "struct coresight_ops" is mandatory and will tell the framework how to
|
||||
The ``struct coresight_ops`` is mandatory and will tell the framework how to
|
||||
perform base operations related to the components, each component having
|
||||
a different set of requirement. For that "struct coresight_ops_sink",
|
||||
"struct coresight_ops_link" and "struct coresight_ops_source" have been
|
||||
a different set of requirement. For that ``struct coresight_ops_sink``,
|
||||
``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been
|
||||
provided.
|
||||
|
||||
The next field, "struct coresight_platform_data *pdata" is acquired by calling
|
||||
"of_get_coresight_platform_data()", as part of the driver's _probe routine and
|
||||
"struct device *dev" gets the device reference embedded in the "amba_device":
|
||||
The next field ``struct coresight_platform_data *pdata`` is acquired by calling
|
||||
``of_get_coresight_platform_data()``, as part of the driver's _probe routine and
|
||||
``struct device *dev`` gets the device reference embedded in the ``amba_device``::
|
||||
|
||||
static int etm_probe(struct amba_device *adev, const struct amba_id *id)
|
||||
{
|
||||
|
|
@ -182,19 +192,19 @@ static int etm_probe(struct amba_device *adev, const struct amba_id *id)
|
|||
}
|
||||
|
||||
Specific class of device (source, link, or sink) have generic operations
|
||||
that can be performed on them (see "struct coresight_ops"). The
|
||||
"**groups" is a list of sysfs entries pertaining to operations
|
||||
that can be performed on them (see ``struct coresight_ops``). The ``**groups``
|
||||
is a list of sysfs entries pertaining to operations
|
||||
specific to that component only. "Implementation defined" customisations are
|
||||
expected to be accessed and controlled using those entries.
|
||||
|
||||
|
||||
Device Naming scheme
|
||||
------------------------
|
||||
--------------------
|
||||
|
||||
The devices that appear on the "coresight" bus were named the same as their
|
||||
parent devices, i.e, the real devices that appears on AMBA bus or the platform bus.
|
||||
Thus the names were based on the Linux Open Firmware layer naming convention,
|
||||
which follows the base physical address of the device followed by the device
|
||||
type. e.g:
|
||||
type. e.g::
|
||||
|
||||
root:~# ls /sys/bus/coresight/devices/
|
||||
20010000.etf 20040000.funnel 20100000.stm 22040000.etm
|
||||
|
|
@ -205,7 +215,7 @@ root:~# ls /sys/bus/coresight/devices/
|
|||
However, with the introduction of ACPI support, the names of the real
|
||||
devices are a bit cryptic and non-obvious. Thus, a new naming scheme was
|
||||
introduced to use more generic names based on the type of the device. The
|
||||
following rules apply:
|
||||
following rules apply::
|
||||
|
||||
1) Devices that are bound to CPUs, are named based on the CPU logical
|
||||
number.
|
||||
|
|
@ -220,7 +230,7 @@ following rules apply:
|
|||
|
||||
e.g, tmc_etf0, tmc_etr0, funnel0, funnel1
|
||||
|
||||
Thus, with the new scheme the devices could appear as :
|
||||
Thus, with the new scheme the devices could appear as ::
|
||||
|
||||
root:~# ls /sys/bus/coresight/devices/
|
||||
etm0 etm1 etm2 etm3 etm4 etm5 funnel0
|
||||
|
|
@ -234,9 +244,12 @@ the system under specified locations.
|
|||
How to use the tracer modules
|
||||
-----------------------------
|
||||
|
||||
There are two ways to use the Coresight framework: 1) using the perf cmd line
|
||||
tools and 2) interacting directly with the Coresight devices using the sysFS
|
||||
interface. Preference is given to the former as using the sysFS interface
|
||||
There are two ways to use the Coresight framework:
|
||||
|
||||
1. using the perf cmd line tools.
|
||||
2. interacting directly with the Coresight devices using the sysFS interface.
|
||||
|
||||
Preference is given to the former as using the sysFS interface
|
||||
requires a deep understanding of the Coresight HW. The following sections
|
||||
provide details on using both methods.
|
||||
|
||||
|
|
@ -245,7 +258,7 @@ provide details on using both methods.
|
|||
Before trace collection can start, a coresight sink needs to be identified.
|
||||
There is no limit on the amount of sinks (nor sources) that can be enabled at
|
||||
any given moment. As a generic operation, all device pertaining to the sink
|
||||
class will have an "active" entry in sysfs:
|
||||
class will have an "active" entry in sysfs::
|
||||
|
||||
root:/sys/bus/coresight/devices# ls
|
||||
replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
|
||||
|
|
@ -260,7 +273,7 @@ root:/sys/bus/coresight/devices#
|
|||
At boot time the current etm3x driver will configure the first address
|
||||
comparator with "_stext" and "_etext", essentially tracing any instruction
|
||||
that falls within that range. As such "enabling" a source will immediately
|
||||
trigger a trace capture:
|
||||
trigger a trace capture::
|
||||
|
||||
root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
|
||||
root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
|
||||
|
|
@ -276,16 +289,15 @@ Flush status: 0x0
|
|||
Flush ctrl: 0x2001
|
||||
root:/sys/bus/coresight/devices#
|
||||
|
||||
Trace collection is stopped the same way:
|
||||
Trace collection is stopped the same way::
|
||||
|
||||
root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
|
||||
root:/sys/bus/coresight/devices#
|
||||
|
||||
The content of the ETB buffer can be harvested directly from /dev:
|
||||
The content of the ETB buffer can be harvested directly from /dev::
|
||||
|
||||
root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
|
||||
of=~/cstrace.bin
|
||||
|
||||
64+0 records in
|
||||
64+0 records out
|
||||
32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
|
||||
|
|
@ -296,6 +308,7 @@ The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
|
|||
Following is a DS-5 output of an experimental loop that increments a variable up
|
||||
to a certain value. The example is simple and yet provides a glimpse of the
|
||||
wealth of possibilities that coresight provides.
|
||||
::
|
||||
|
||||
Info Tracing enabled
|
||||
Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
|
||||
|
|
@ -370,19 +383,18 @@ 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:
|
||||
($SYSFS)/bus/event_source/devices/cs_etm/sinks/
|
||||
On newer kernels 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/:
|
||||
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
|
||||
|
|
@ -395,14 +407,14 @@ 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 [3].
|
||||
repository [#third]_.
|
||||
|
||||
2.1) AutoFDO analysis using the perf tools:
|
||||
|
||||
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:
|
||||
specifying the name of the sink to record to, e.g::
|
||||
|
||||
perf record -e cs_etm/@tmc_etr0/u --per-thread
|
||||
|
||||
|
|
@ -421,12 +433,14 @@ Generating coverage files for Feedback Directed Optimization: AutoFDO
|
|||
|
||||
'perf inject' accepts the --itrace option in which case tracing data is
|
||||
removed and replaced with the synthesized events. e.g.
|
||||
::
|
||||
|
||||
perf inject --itrace --strip -i perf.data -o perf.data.new
|
||||
|
||||
Below is an example of using ARM ETM for autoFDO. It requires autofdo
|
||||
(https://github.com/google/autofdo) and gcc version 5. The bubble
|
||||
sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial).
|
||||
::
|
||||
|
||||
$ gcc-5 -O3 sort.c -o sort
|
||||
$ taskset -c 2 ./sort
|
||||
|
|
@ -455,7 +469,7 @@ difference is that clients are driving the trace capture rather
|
|||
than the program flow through the code.
|
||||
|
||||
As with any other CoreSight component, specifics about the STM tracer can be
|
||||
found in sysfs with more information on each entry being found in [1]:
|
||||
found in sysfs with more information on each entry being found in [#first]_::
|
||||
|
||||
root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
|
||||
enable_source hwevent_select port_enable subsystem uevent
|
||||
|
|
@ -463,20 +477,22 @@ hwevent_enable mgmt port_select traceid
|
|||
root@genericarmv8:~#
|
||||
|
||||
Like any other source a sink needs to be identified and the STM enabled before
|
||||
being used:
|
||||
being used::
|
||||
|
||||
root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink
|
||||
root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source
|
||||
|
||||
From there user space applications can request and use channels using the devfs
|
||||
interface provided for that purpose by the generic STM API:
|
||||
interface provided for that purpose by the generic STM API::
|
||||
|
||||
root@genericarmv8:~# ls -l /dev/stm0
|
||||
crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
|
||||
root@genericarmv8:~#
|
||||
|
||||
Details on how to use the generic STM API can be found here [2].
|
||||
Details on how to use the generic STM API can be found here [#second]_.
|
||||
|
||||
[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
|
||||
[2]. Documentation/trace/stm.rst
|
||||
[3]. https://github.com/Linaro/perf-opencsd
|
||||
.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
|
||||
|
||||
.. [#second] Documentation/trace/stm.rst
|
||||
|
||||
.. [#third] https://github.com/Linaro/perf-opencsd
|
||||
|
|
@ -23,3 +23,5 @@ Linux Tracing Technologies
|
|||
intel_th
|
||||
stm
|
||||
sys-t
|
||||
coresight
|
||||
coresight-cpu-debug
|
||||
|
|
|
|||
|
|
@ -1582,8 +1582,8 @@ R: Suzuki K Poulose <suzuki.poulose@arm.com>
|
|||
L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
|
||||
S: Maintained
|
||||
F: drivers/hwtracing/coresight/*
|
||||
F: Documentation/trace/coresight.txt
|
||||
F: Documentation/trace/coresight-cpu-debug.txt
|
||||
F: Documentation/trace/coresight.rst
|
||||
F: Documentation/trace/coresight-cpu-debug.rst
|
||||
F: Documentation/devicetree/bindings/arm/coresight.txt
|
||||
F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt
|
||||
F: Documentation/ABI/testing/sysfs-bus-coresight-devices-*
|
||||
|
|
|
|||
Loading…
Reference in New Issue