2019-07-05 20:46:15

by Phong Tran

Subject: [PATCH] Documentation: coresight: covert txt to rst

change the format file and adpate the text style

Signed-off-by: Phong Tran <[email protected]>
---
.../trace/{coresight.txt => coresight.rst} | 296 ++++++++++++---------
Documentation/trace/index.rst | 1 +
2 files changed, 167 insertions(+), 130 deletions(-)
rename Documentation/trace/{coresight.txt => coresight.rst} (59%)

diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
similarity index 59%
rename from Documentation/trace/coresight.txt
rename to Documentation/trace/coresight.rst
index efbc832146e7..bea24e70cfba 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.rst
@@ -1,5 +1,6 @@
- Coresight - HW Assisted Tracing on ARM
- ======================================
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================

Author: Mathieu Poirier <[email protected]>
Date: September 11th, 2014
@@ -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,6 +96,7 @@ Acronyms and Classification

Acronyms:

+======== =============================================================
PTM: Program Trace Macrocell
ETM: Embedded Trace Macrocell
STM: System trace Macrocell
@@ -104,6 +106,7 @@ 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 +121,7 @@ Misc:


Device Tree Bindings
-----------------------
+--------------------

See Documentation/devicetree/bindings/arm/coresight.txt for details.

@@ -133,57 +136,63 @@ 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 :code:`struct coresight_device *csdev` 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 :code:`struct coresight_device`, 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:

-root:~# ls /sys/bus/coresight/devices/
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:~#
+.. code:: console

-The functions take a "struct coresight_device", which looks like this:
+ root:~# ls /sys/bus/coresight/devices/
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:~#

-struct coresight_desc {
- enum coresight_dev_type type;
- struct coresight_dev_subtype subtype;
- const struct coresight_ops *ops;
- struct coresight_platform_data *pdata;
- struct device *dev;
- const struct attribute_group **groups;
-};
+The functions take a :code:`struct coresight_device`, which looks like this:
+
+.. code:: c
+
+ struct coresight_desc {
+ enum coresight_dev_type type;
+ struct coresight_dev_subtype subtype;
+ const struct coresight_ops *ops;
+ struct coresight_platform_data *pdata;
+ struct device *dev;
+ const struct attribute_group **groups;
+ };


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 :code:`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 :code:`struct coresight_ops_sink,
+struct coresight_ops_link` and :code:`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, :code:`struct coresight_platform_data *pdata` is acquired by calling
+:code:`of_get_coresight_platform_data()`, as part of the driver's _probe routine and
+:code:`struct device *dev` gets the device reference embedded in the :code:`amba_device`:

-static int etm_probe(struct amba_device *adev, const struct amba_id *id)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
+.. code:: c
+
+ static int etm_probe(struct amba_device *adev, const struct amba_id *id)
+ {
+ ...
+ ...
+ drvdata->dev = &adev->dev;
+ ...
+ }

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 :code:`struct coresight_ops`). The
+:code:`**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.

@@ -204,49 +213,56 @@ 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:

-root:/sys/bus/coresight/devices# ls
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink status trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
+.. code:: console
+
+ root:/sys/bus/coresight/devices# ls
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:/sys/bus/coresight/devices# ls 20010000.etb
+ enable_sink status trigger_cntr
+ root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+ root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+ 1
+ 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:

-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth: 0x2000
-Status: 0x1
-RAM read ptr: 0x0
-RAM wrt ptr: 0x19d3 <----- The write pointer is moving
-Trigger cnt: 0x0
-Control: 0x1
-Flush status: 0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
+.. code:: console
+
+ root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
+ root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
+ 1
+ root:/sys/bus/coresight/devices# cat 20010000.etb/status
+ Depth: 0x2000
+ Status: 0x1
+ RAM read ptr: 0x0
+ RAM wrt ptr: 0x19d3 <----- The write pointer is moving
+ Trigger cnt: 0x0
+ Control: 0x1
+ Flush status: 0x0
+ Flush ctrl: 0x2001
+ root:/sys/bus/coresight/devices#

Trace collection is stopped the same way:

-root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices#
+.. code:: console
+
+ 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:

-root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
-of=~/cstrace.bin
+.. code:: console

-64+0 records in
-64+0 records out
-32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
-root:/sys/bus/coresight/devices#
+ 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
+ root:/sys/bus/coresight/devices#

The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.

@@ -254,55 +270,57 @@ 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}
-Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
-Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
-Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Timestamp Timestamp: 17106715833
-Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
-Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
-Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
-Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
-Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
-Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
-Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
-Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
-Info Tracing enabled
-Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
-Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
-Timestamp Timestamp: 17107041535
+.. code:: c
+
+ Info Tracing enabled
+ Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
+ Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
+ Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
+ Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Timestamp Timestamp: 17106715833
+ Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
+ Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
+ Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
+ Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
+ Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
+ Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+ Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
+ Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
+ Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
+ Info Tracing enabled
+ Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
+ Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
+ Timestamp Timestamp: 17107041535

2) Using perf framework:

@@ -312,6 +330,8 @@ controlling when tracing gets enabled based on when the process of interest is
scheduled. When configured in a system, Coresight PMUs will be listed when
queried by the perf command line tool:

+.. code:: console
+
linaro@linaro-nano:~$ ./perf list pmu

List of pre-defined events (to be used in -e):
@@ -329,6 +349,8 @@ 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. Names for sink to choose
from are listed in sysFS under ($SYSFS)/bus/coresight/devices:

+.. code:: console
+
root@linaro-nano:~# ls /sys/bus/coresight/devices/
20010000.etf 20040000.funnel 20100000.stm 22040000.etm
22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
@@ -343,7 +365,7 @@ 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:

@@ -352,6 +374,8 @@ 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:

+.. code:: console
+
perf record -e cs_etm/@20070000.etr/u --per-thread

The 'perf report' and 'perf script' commands can be used to analyze execution,
@@ -370,12 +394,16 @@ 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.

+.. code:: console
+
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).

+.. code:: console
+
$ gcc-5 -O3 sort.c -o sort
$ taskset -c 2 ./sort
Bubble sorting array of 30000 elements
@@ -403,28 +431,36 @@ 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/20100000.stm
-enable_source hwevent_select port_enable subsystem uevent
-hwevent_enable mgmt port_select traceid
-root@genericarmv8:~#
+.. code:: console
+
+ root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
+ enable_source hwevent_select port_enable subsystem uevent
+ 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:

-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
+.. code:: console
+
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/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:

-root@genericarmv8:~# ls -l /dev/20100000.stm
-crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
-root@genericarmv8:~#
+.. code:: console
+
+ root@genericarmv8:~# ls -l /dev/20100000.stm
+ crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
+ root@genericarmv8:~#
+
+Details on how to use the generic STM API can be found here [#second]_.
+
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

-Details on how to use the generic STM API can be found here [2].
+.. [#second] Documentation/trace/stm.rst

-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107cf4b98..3330c5456bcb 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,4 @@ Linux Tracing Technologies
intel_th
stm
sys-t
+ coresight
--
2.11.0

2019-07-08 22:43:41

by Mathieu Poirier

Subject: Re: [PATCH] Documentation: coresight: covert txt to rst

Hi Tran,

Thank you for doing this - it adds much needed consistency to this
file. A few of comments below....

On Fri, 5 Jul 2019 at 14:45, Phong Tran <[email protected]> wrote:
>
> change the format file and adpate the text style

This changtelog is a little short and mentions what you are doing
rather than why.

>
> Signed-off-by: Phong Tran <[email protected]>
> ---
> .../trace/{coresight.txt => coresight.rst} | 296 ++++++++++++---------
> Documentation/trace/index.rst | 1 +
> 2 files changed, 167 insertions(+), 130 deletions(-)
> rename Documentation/trace/{coresight.txt => coresight.rst} (59%)

File "coresight.txt" is referenced in the MAINTAINERS file and should
probably be changed there as well.

Did you look at coresight-cpu-debug.txt? In my opinion both files
should be changed in the same patchset.

Thanks,
Mathieu

>
> diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
> similarity index 59%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index efbc832146e7..bea24e70cfba 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,5 +1,6 @@
> - Coresight - HW Assisted Tracing on ARM
> - ======================================
> +======================================
> +Coresight - HW Assisted Tracing on ARM
> +======================================
>
> Author: Mathieu Poirier <[email protected]>
> Date: September 11th, 2014
> @@ -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,6 +96,7 @@ Acronyms and Classification
>
> Acronyms:
>
> +======== =============================================================
> PTM: Program Trace Macrocell
> ETM: Embedded Trace Macrocell
> STM: System trace Macrocell
> @@ -104,6 +106,7 @@ 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 +121,7 @@ Misc:
>
>
> Device Tree Bindings
> -----------------------
> +--------------------
>
> See Documentation/devicetree/bindings/arm/coresight.txt for details.
>
> @@ -133,57 +136,63 @@ 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 :code:`struct coresight_device *csdev` 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 :code:`struct coresight_device`, 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:
>
> -root:~# ls /sys/bus/coresight/devices/
> -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> -root:~#
> +.. code:: console
>
> -The functions take a "struct coresight_device", which looks like this:
> + root:~# ls /sys/bus/coresight/devices/
> + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> + root:~#
>
> -struct coresight_desc {
> - enum coresight_dev_type type;
> - struct coresight_dev_subtype subtype;
> - const struct coresight_ops *ops;
> - struct coresight_platform_data *pdata;
> - struct device *dev;
> - const struct attribute_group **groups;
> -};
> +The functions take a :code:`struct coresight_device`, which looks like this:
> +
> +.. code:: c
> +
> + struct coresight_desc {
> + enum coresight_dev_type type;
> + struct coresight_dev_subtype subtype;
> + const struct coresight_ops *ops;
> + struct coresight_platform_data *pdata;
> + struct device *dev;
> + const struct attribute_group **groups;
> + };
>
>
> 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 :code:`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 :code:`struct coresight_ops_sink,
> +struct coresight_ops_link` and :code:`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, :code:`struct coresight_platform_data *pdata` is acquired by calling
> +:code:`of_get_coresight_platform_data()`, as part of the driver's _probe routine and
> +:code:`struct device *dev` gets the device reference embedded in the :code:`amba_device`:
>
> -static int etm_probe(struct amba_device *adev, const struct amba_id *id)
> -{
> - ...
> - ...
> - drvdata->dev = &adev->dev;
> - ...
> -}
> +.. code:: c
> +
> + static int etm_probe(struct amba_device *adev, const struct amba_id *id)
> + {
> + ...
> + ...
> + drvdata->dev = &adev->dev;
> + ...
> + }
>
> 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 :code:`struct coresight_ops`). The
> +:code:`**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.
>
> @@ -204,49 +213,56 @@ 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:
>
> -root:/sys/bus/coresight/devices# ls
> -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> -root:/sys/bus/coresight/devices# ls 20010000.etb
> -enable_sink status trigger_cntr
> -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> -1
> -root:/sys/bus/coresight/devices#
> +.. code:: console
> +
> + root:/sys/bus/coresight/devices# ls
> + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> + root:/sys/bus/coresight/devices# ls 20010000.etb
> + enable_sink status trigger_cntr
> + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> + 1
> + 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:
>
> -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
> -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
> -1
> -root:/sys/bus/coresight/devices# cat 20010000.etb/status
> -Depth: 0x2000
> -Status: 0x1
> -RAM read ptr: 0x0
> -RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> -Trigger cnt: 0x0
> -Control: 0x1
> -Flush status: 0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> +.. code:: console
> +
> + root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
> + root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
> + 1
> + root:/sys/bus/coresight/devices# cat 20010000.etb/status
> + Depth: 0x2000
> + Status: 0x1
> + RAM read ptr: 0x0
> + RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> + Trigger cnt: 0x0
> + Control: 0x1
> + Flush status: 0x0
> + Flush ctrl: 0x2001
> + root:/sys/bus/coresight/devices#
>
> Trace collection is stopped the same way:
>
> -root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source
> -root:/sys/bus/coresight/devices#
> +.. code:: console
> +
> + 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:
>
> -root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \
> -of=~/cstrace.bin
> +.. code:: console
>
> -64+0 records in
> -64+0 records out
> -32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s
> -root:/sys/bus/coresight/devices#
> + 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
> + root:/sys/bus/coresight/devices#
>
> The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32.
>
> @@ -254,55 +270,57 @@ 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}
> -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Timestamp Timestamp: 17106715833
> -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> -Info Tracing enabled
> -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> -Timestamp Timestamp: 17107041535
> +.. code:: c
> +
> + Info Tracing enabled
> + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
> + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Timestamp Timestamp: 17106715833
> + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> + Info Tracing enabled
> + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> + Timestamp Timestamp: 17107041535
>
> 2) Using perf framework:
>
> @@ -312,6 +330,8 @@ controlling when tracing gets enabled based on when the process of interest is
> scheduled. When configured in a system, Coresight PMUs will be listed when
> queried by the perf command line tool:
>
> +.. code:: console
> +
> linaro@linaro-nano:~$ ./perf list pmu
>
> List of pre-defined events (to be used in -e):
> @@ -329,6 +349,8 @@ 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. Names for sink to choose
> from are listed in sysFS under ($SYSFS)/bus/coresight/devices:
>
> +.. code:: console
> +
> root@linaro-nano:~# ls /sys/bus/coresight/devices/
> 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
> 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
> @@ -343,7 +365,7 @@ 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:
>
> @@ -352,6 +374,8 @@ 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:
>
> +.. code:: console
> +
> perf record -e cs_etm/@20070000.etr/u --per-thread
>
> The 'perf report' and 'perf script' commands can be used to analyze execution,
> @@ -370,12 +394,16 @@ 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.
>
> +.. code:: console
> +
> 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).
>
> +.. code:: console
> +
> $ gcc-5 -O3 sort.c -o sort
> $ taskset -c 2 ./sort
> Bubble sorting array of 30000 elements
> @@ -403,28 +431,36 @@ 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/20100000.stm
> -enable_source hwevent_select port_enable subsystem uevent
> -hwevent_enable mgmt port_select traceid
> -root@genericarmv8:~#
> +.. code:: console
> +
> + root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
> + enable_source hwevent_select port_enable subsystem uevent
> + 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:
>
> -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
> -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
> +.. code:: console
> +
> + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
> + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/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:
>
> -root@genericarmv8:~# ls -l /dev/20100000.stm
> -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
> -root@genericarmv8:~#
> +.. code:: console
> +
> + root@genericarmv8:~# ls -l /dev/20100000.stm
> + crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
> + root@genericarmv8:~#
> +
> +Details on how to use the generic STM API can be found here [#second]_.
> +
> +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
>
> -Details on how to use the generic STM API can be found here [2].
> +.. [#second] Documentation/trace/stm.rst
>
> -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> -[2]. Documentation/trace/stm.rst
> -[3]. https://github.com/Linaro/perf-opencsd
> +.. [#third] https://github.com/Linaro/perf-opencsd
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 6b4107cf4b98..3330c5456bcb 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -23,3 +23,4 @@ Linux Tracing Technologies
> intel_th
> stm
> sys-t
> + coresight
> --
> 2.11.0
>

2019-07-08 22:49:17

by Jonathan Corbet

Subject: Re: [PATCH] Documentation: coresight: covert txt to rst

On Sat, 6 Jul 2019 03:45:12 +0700
Phong Tran <[email protected]> wrote:

> change the format file and adpate the text style
>
> Signed-off-by: Phong Tran <[email protected]>
> ---
> .../trace/{coresight.txt => coresight.rst} | 296 ++++++++++++---------
> Documentation/trace/index.rst | 1 +
> 2 files changed, 167 insertions(+), 130 deletions(-)
> rename Documentation/trace/{coresight.txt => coresight.rst} (59%)
>
> diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
> similarity index 59%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index efbc832146e7..bea24e70cfba 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,5 +1,6 @@
> - Coresight - HW Assisted Tracing on ARM
> - ======================================
> +======================================
> +Coresight - HW Assisted Tracing on ARM
> +======================================
>
> Author: Mathieu Poirier <[email protected]>
> Date: September 11th, 2014
> @@ -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,6 +96,7 @@ Acronyms and Classification
>
> Acronyms:
>
> +======== =============================================================
> PTM: Program Trace Macrocell
> ETM: Embedded Trace Macrocell
> STM: System trace Macrocell
> @@ -104,6 +106,7 @@ 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
> +======== =============================================================

A minor nit, but since you're making a table out of this, you don't need
the colons in the first column.

> Classification:
>
> @@ -118,7 +121,7 @@ Misc:
>
>
> Device Tree Bindings
> -----------------------
> +--------------------
>
> See Documentation/devicetree/bindings/arm/coresight.txt for details.
>
> @@ -133,57 +136,63 @@ 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 :code:`struct coresight_device *csdev` and

As a general rule, we would rather see less markup in the text files than
you are applying here. Just present the prototypes in a literal block
here. (Even better would be a nice kerneldoc comment in the source that
could be pulled in, but that's more work). I wouldn't use :code: anywhere,
really.

As well as addressing Mathieu's comments, could you pass through and cut
the markup down to the bare minimum?

Thanks,

jon

2019-07-09 16:43:12

by Phong Tran

Subject: [Patch V2] Documentation: coresight: covert txt to rst

as doc-guide of kernel documentation, use Sphinx tool to
generate the html/pdf... files.

This changes the plan text txt to rst format.

Signed-off-by: Phong Tran <[email protected]>
---
ChangeLog:
V2:
* Add coresight-cpu-debug
* Update MAINTAINERS file
* Avoid use markup as much as posible
---
...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 63 ++--
.../trace/{coresight.txt => coresight.rst} | 352 +++++++++++----------
Documentation/trace/index.rst | 2 +
MAINTAINERS | 4 +-
4 files changed, 229 insertions(+), 192 deletions(-)
rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
rename Documentation/trace/{coresight.txt => coresight.rst} (55%)

diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
similarity index 84%
rename from Documentation/trace/coresight-cpu-debug.txt
rename to Documentation/trace/coresight-cpu-debug.rst
index f07e38094b40..b219d75f4f8a 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.rst
@@ -1,5 +1,6 @@
- Coresight CPU Debug Module
- ==========================
+==========================
+Coresight CPU Debug Module
+==========================

Author: Leo Yan <[email protected]>
Date: April 5th, 2017
@@ -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,18 +127,21 @@ 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:
-# insmod coresight_cpu_debug.ko debug=1
+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:
-# echo 1 > /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
+ # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

As explained in chapter "Clock and power domain", if you are working on one
platform which has idle states to power off debug logic and the power
@@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
interface (see Documentation/power/pm_qos_interface.txt 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
-...
-Do some work...
-...
-# exec 3<>-
+ # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
+ ...
+ Do some work...
+ ...
+ # exec 3<>-

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:
-
-ARM external debug module:
-coresight-cpu-debug 850000.debug: CPU[0]:
-coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
-coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
-coresight-cpu-debug 852000.debug: CPU[1]:
-coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
-coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+Here is an example of the debugging output format::
+
+ ARM external debug module:
+ coresight-cpu-debug 850000.debug: CPU[0]:
+ coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
+ coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+ coresight-cpu-debug 852000.debug: CPU[1]:
+ coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
+ coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
similarity index 55%
rename from Documentation/trace/coresight.txt
rename to Documentation/trace/coresight.rst
index efbc832146e7..fc9486b7bd87 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.rst
@@ -1,5 +1,6 @@
- Coresight - HW Assisted Tracing on ARM
- ======================================
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================

Author: Mathieu Poirier <[email protected]>
Date: September 11th, 2014
@@ -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 ****************************===||
@@ -93,17 +94,17 @@ intricate IP blocks such as STM and CTI.
Acronyms and Classification
---------------------------

-Acronyms:
+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 +119,7 @@ Misc:


Device Tree Bindings
-----------------------
+--------------------

See Documentation/devicetree/bindings/arm/coresight.txt for details.

@@ -133,57 +134,79 @@ 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
-register the device with the core framework. The unregister function takes
-a reference to a "struct coresight_device", obtained at registration time.
+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 *csdev
+
+The pointer 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:~#
+ 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;
- struct coresight_dev_subtype subtype;
- const struct coresight_ops *ops;
- struct coresight_platform_data *pdata;
- struct device *dev;
- const struct attribute_group **groups;
-};
+ struct coresight_desc {
+ enum coresight_dev_type type;
+ struct coresight_dev_subtype subtype;
+ const struct coresight_ops *ops;
+ struct coresight_platform_data *pdata;
+ struct device *dev;
+ const struct attribute_group **groups;
+ };


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
+::

-static int etm_probe(struct amba_device *adev, const struct amba_id *id)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
+ 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)
+ {
+ ...
+ ...
+ drvdata->dev = &adev->dev;
+ ...
+ }

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
+::
+
+ const struct attribute_group **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.

@@ -191,9 +214,12 @@ expected to be accessed and controlled using those entries.
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.

@@ -202,107 +228,107 @@ 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:
-
-root:/sys/bus/coresight/devices# ls
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink status trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
+class will have an "active" entry in sysfs::
+
+ root:/sys/bus/coresight/devices# ls
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:/sys/bus/coresight/devices# ls 20010000.etb
+ enable_sink status trigger_cntr
+ root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+ root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+ 1
+ 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:
-
-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth: 0x2000
-Status: 0x1
-RAM read ptr: 0x0
-RAM wrt ptr: 0x19d3 <----- The write pointer is moving
-Trigger cnt: 0x0
-Control: 0x1
-Flush status: 0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
-
-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:
-
-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
-root:/sys/bus/coresight/devices#
+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
+ 1
+ root:/sys/bus/coresight/devices# cat 20010000.etb/status
+ Depth: 0x2000
+ Status: 0x1
+ RAM read ptr: 0x0
+ RAM wrt ptr: 0x19d3 <----- The write pointer is moving
+ Trigger cnt: 0x0
+ Control: 0x1
+ Flush status: 0x0
+ Flush ctrl: 0x2001
+ root:/sys/bus/coresight/devices#
+
+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::
+
+ 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
+ root:/sys/bus/coresight/devices#

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}
-Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
-Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
-Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Timestamp Timestamp: 17106715833
-Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
-Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
-Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
-Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
-Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
-Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
-Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
-Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
-Info Tracing enabled
-Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
-Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
-Timestamp Timestamp: 17107041535
+::
+
+ Info Tracing enabled
+ Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
+ Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
+ Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
+ Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Timestamp Timestamp: 17106715833
+ Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
+ Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
+ Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
+ Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
+ Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
+ Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+ Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
+ Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
+ Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
+ Info Tracing enabled
+ Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
+ Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
+ Timestamp Timestamp: 17107041535

2) Using perf framework:

@@ -327,7 +353,7 @@ 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. Names for sink to choose
-from are listed in sysFS under ($SYSFS)/bus/coresight/devices:
+from are listed in sysFS under ($SYSFS)/bus/coresight/devices::

root@linaro-nano:~# ls /sys/bus/coresight/devices/
20010000.etf 20040000.funnel 20100000.stm 22040000.etm
@@ -343,14 +369,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/@20070000.etr/u --per-thread

@@ -369,12 +395,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
@@ -403,28 +431,30 @@ 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/20100000.stm
-enable_source hwevent_select port_enable subsystem uevent
-hwevent_enable mgmt port_select traceid
-root@genericarmv8:~#
+ root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
+ enable_source hwevent_select port_enable subsystem uevent
+ 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/20010000.etf/enable_sink
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/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/20100000.stm
+ crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
+ root@genericarmv8:~#
+
+Details on how to use the generic STM API can be found here [#second]_.

-root@genericarmv8:~# ls -l /dev/20100000.stm
-crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
-root@genericarmv8:~#
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

-Details on how to use the generic STM API can be found here [2].
+.. [#second] Documentation/trace/stm.rst

-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107cf4b98..b7891cb1ab4d 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,5 @@ Linux Tracing Technologies
intel_th
stm
sys-t
+ coresight
+ coresight-cpu-debug
diff --git a/MAINTAINERS b/MAINTAINERS
index 558acf24ea1e..04b006e5cc0a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1549,8 +1549,8 @@ R: Suzuki K Poulose <[email protected]>
L: [email protected] (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-*
--
2.11.0

2019-07-09 17:06:06

by Mauro Carvalho Chehab

Subject: Re: [Patch V2] Documentation: coresight: covert txt to rst

Em Tue, 9 Jul 2019 23:41:58 +0700
Phong Tran <[email protected]> escreveu:

> as doc-guide of kernel documentation, use Sphinx tool to
> generate the html/pdf... files.
>
> This changes the plan text txt to rst format.
>
> Signed-off-by: Phong Tran <[email protected]>
> ---
> ChangeLog:
> V2:
> * Add coresight-cpu-debug
> * Update MAINTAINERS file
> * Avoid use markup as much as posible
> ---
> ...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 63 ++--
> .../trace/{coresight.txt => coresight.rst} | 352 +++++++++++----------
> Documentation/trace/index.rst | 2 +
> MAINTAINERS | 4 +-
> 4 files changed, 229 insertions(+), 192 deletions(-)
> rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
> rename Documentation/trace/{coresight.txt => coresight.rst} (55%)
>
> diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
> similarity index 84%
> rename from Documentation/trace/coresight-cpu-debug.txt
> rename to Documentation/trace/coresight-cpu-debug.rst
> index f07e38094b40..b219d75f4f8a 100644
> --- a/Documentation/trace/coresight-cpu-debug.txt
> +++ b/Documentation/trace/coresight-cpu-debug.rst
> @@ -1,5 +1,6 @@
> - Coresight CPU Debug Module
> - ==========================
> +==========================
> +Coresight CPU Debug Module
> +==========================
>
> Author: Leo Yan <[email protected]>
> Date: April 5th, 2017

You need to either add a blank line between Author: and Date or to
use:

:Author: foo
:Date: bar

as otherwise, it will output those on a single line at the output.

> @@ -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,18 +127,21 @@ 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:
> -# insmod coresight_cpu_debug.ko debug=1
> +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:
> -# echo 1 > /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
> + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
>
> As explained in chapter "Clock and power domain", if you are working on one
> platform which has idle states to power off debug logic and the power
> @@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
> interface (see Documentation/power/pm_qos_interface.txt 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
> -...
> -Do some work...
> -...
> -# exec 3<>-
> + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
> + ...
> + Do some work...
> + ...
> + # exec 3<>-
>
> 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:
> -
> -ARM external debug module:
> -coresight-cpu-debug 850000.debug: CPU[0]:
> -coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> -coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> -coresight-cpu-debug 852000.debug: CPU[1]:
> -coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> -coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> +Here is an example of the debugging output format::
> +
> + ARM external debug module:
> + coresight-cpu-debug 850000.debug: CPU[0]:
> + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> + coresight-cpu-debug 852000.debug: CPU[1]:
> + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)

> diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
> similarity index 55%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index efbc832146e7..fc9486b7bd87 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,5 +1,6 @@
> - Coresight - HW Assisted Tracing on ARM
> - ======================================
> +======================================
> +Coresight - HW Assisted Tracing on ARM
> +======================================
>
> Author: Mathieu Poirier <[email protected]>
> Date: September 11th, 2014

Same comment here.

> @@ -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 ****************************===||
> @@ -93,17 +94,17 @@ intricate IP blocks such as STM and CTI.
> Acronyms and Classification
> ---------------------------
>
> -Acronyms:
> +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

The best here would be to add blank lines/spaces, instead. E. g.:

PTM:
Program Trace Macrocell
ETM:
Embedded Trace Macrocell

and so on.

>
> Classification:
>
> @@ -118,7 +119,7 @@ Misc:
>
>
> Device Tree Bindings
> -----------------------
> +--------------------
>
> See Documentation/devicetree/bindings/arm/coresight.txt for details.
>
> @@ -133,57 +134,79 @@ 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
> -register the device with the core framework. The unregister function takes
> -a reference to a "struct coresight_device", obtained at registration time.
> +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 *csdev
> +
> +The pointer 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:~#
> + 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;
> - struct coresight_dev_subtype subtype;
> - const struct coresight_ops *ops;
> - struct coresight_platform_data *pdata;
> - struct device *dev;
> - const struct attribute_group **groups;
> -};
> + struct coresight_desc {
> + enum coresight_dev_type type;
> + struct coresight_dev_subtype subtype;
> + const struct coresight_ops *ops;
> + struct coresight_platform_data *pdata;
> + struct device *dev;
> + const struct attribute_group **groups;
> + };
>
>
> 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

Why did you remove the "" here? (same applies to other places below)

> 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
> +::

Better to use, instead, ``struct coresight_platform_data *pdata``, e. g.:

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)
> -{
> - ...
> - ...
> - drvdata->dev = &adev->dev;
> - ...
> -}
> + 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)
> + {
> + ...
> + ...
> + drvdata->dev = &adev->dev;
> + ...
> + }
>
> 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
> +::
> +
> + const struct attribute_group **groups
> +
> +is a list of sysfs entries pertaining to operations

Same here.

> specific to that component only. "Implementation defined" customisations are
> expected to be accessed and controlled using those entries.
>
> @@ -191,9 +214,12 @@ expected to be accessed and controlled using those entries.
> 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.
>
> @@ -202,107 +228,107 @@ 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:
> -
> -root:/sys/bus/coresight/devices# ls
> -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> -root:/sys/bus/coresight/devices# ls 20010000.etb
> -enable_sink status trigger_cntr
> -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> -1
> -root:/sys/bus/coresight/devices#
> +class will have an "active" entry in sysfs::
> +
> + root:/sys/bus/coresight/devices# ls
> + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> + root:/sys/bus/coresight/devices# ls 20010000.etb
> + enable_sink status trigger_cntr
> + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> + 1
> + 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:
> -
> -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
> -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
> -1
> -root:/sys/bus/coresight/devices# cat 20010000.etb/status
> -Depth: 0x2000
> -Status: 0x1
> -RAM read ptr: 0x0
> -RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> -Trigger cnt: 0x0
> -Control: 0x1
> -Flush status: 0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> -
> -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:
> -
> -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
> -root:/sys/bus/coresight/devices#
> +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
> + 1
> + root:/sys/bus/coresight/devices# cat 20010000.etb/status
> + Depth: 0x2000
> + Status: 0x1
> + RAM read ptr: 0x0
> + RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> + Trigger cnt: 0x0
> + Control: 0x1
> + Flush status: 0x0
> + Flush ctrl: 0x2001
> + root:/sys/bus/coresight/devices#
> +
> +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::
> +
> + 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
> + root:/sys/bus/coresight/devices#
>
> 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}
> -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Timestamp Timestamp: 17106715833
> -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> -Info Tracing enabled
> -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> -Timestamp Timestamp: 17107041535
> +::
> +
> + Info Tracing enabled
> + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
> + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Timestamp Timestamp: 17106715833
> + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> + Info Tracing enabled
> + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> + Timestamp Timestamp: 17107041535
>
> 2) Using perf framework:
>
> @@ -327,7 +353,7 @@ 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. Names for sink to choose
> -from are listed in sysFS under ($SYSFS)/bus/coresight/devices:
> +from are listed in sysFS under ($SYSFS)/bus/coresight/devices::
>
> root@linaro-nano:~# ls /sys/bus/coresight/devices/
> 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
> @@ -343,14 +369,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/@20070000.etr/u --per-thread
>
> @@ -369,12 +395,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
> @@ -403,28 +431,30 @@ 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/20100000.stm
> -enable_source hwevent_select port_enable subsystem uevent
> -hwevent_enable mgmt port_select traceid
> -root@genericarmv8:~#
> + root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
> + enable_source hwevent_select port_enable subsystem uevent
> + 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/20010000.etf/enable_sink
> -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
> + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
> + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/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/20100000.stm
> + crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
> + root@genericarmv8:~#
> +
> +Details on how to use the generic STM API can be found here [#second]_.
>
> -root@genericarmv8:~# ls -l /dev/20100000.stm
> -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
> -root@genericarmv8:~#
> +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
>
> -Details on how to use the generic STM API can be found here [2].
> +.. [#second] Documentation/trace/stm.rst
>
> -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> -[2]. Documentation/trace/stm.rst
> -[3]. https://github.com/Linaro/perf-opencsd
> +.. [#third] https://github.com/Linaro/perf-opencsd
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 6b4107cf4b98..b7891cb1ab4d 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -23,3 +23,5 @@ Linux Tracing Technologies
> intel_th
> stm
> sys-t
> + coresight
> + coresight-cpu-debug
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 558acf24ea1e..04b006e5cc0a 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1549,8 +1549,8 @@ R: Suzuki K Poulose <[email protected]>
> L: [email protected] (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-*



Thanks,
Mauro

2019-07-10 02:09:30

by Phong Tran

Subject: [Patch V3] Documentation: coresight: covert txt to rst

as doc-guide of kernel documentation, use Sphinx tool to
generate the html/pdf... files.

This changes the plan text txt to rst format.

Signed-off-by: Phong Tran <[email protected]>
---
ChangeLog:
V2: review points from Mathieu, Jonathan
* Add coresight-cpu-debug
* Update MAINTAINERS file
* Avoid use markup as much as posible
V3: review points from Mauro
* add the colon author, date
* change to use ```` in the struct
* add line for the acronyms
---
...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 67 ++--
.../trace/{coresight.txt => coresight.rst} | 341 +++++++++++----------
Documentation/trace/index.rst | 2 +
MAINTAINERS | 4 +-
4 files changed, 219 insertions(+), 195 deletions(-)
rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
rename Documentation/trace/{coresight.txt => coresight.rst} (55%)

diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
similarity index 84%
rename from Documentation/trace/coresight-cpu-debug.txt
rename to Documentation/trace/coresight-cpu-debug.rst
index f07e38094b40..8c6ecb4c1f54 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.rst
@@ -1,8 +1,9 @@
- Coresight CPU Debug Module
- ==========================
+==========================
+Coresight CPU Debug Module
+==========================

- Author: Leo Yan <[email protected]>
- Date: April 5th, 2017
+ :Author: Leo Yan <[email protected]>
+ :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,18 +127,21 @@ 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:
-# insmod coresight_cpu_debug.ko debug=1
+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:
-# echo 1 > /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
+ # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

As explained in chapter "Clock and power domain", if you are working on one
platform which has idle states to power off debug logic and the power
@@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
interface (see Documentation/power/pm_qos_interface.txt 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
-...
-Do some work...
-...
-# exec 3<>-
+ # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
+ ...
+ Do some work...
+ ...
+ # exec 3<>-

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:
-
-ARM external debug module:
-coresight-cpu-debug 850000.debug: CPU[0]:
-coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
-coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
-coresight-cpu-debug 852000.debug: CPU[1]:
-coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
-coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+Here is an example of the debugging output format::
+
+ ARM external debug module:
+ coresight-cpu-debug 850000.debug: CPU[0]:
+ coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
+ coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+ coresight-cpu-debug 852000.debug: CPU[1]:
+ coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
+ coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
similarity index 55%
rename from Documentation/trace/coresight.txt
rename to Documentation/trace/coresight.rst
index efbc832146e7..39b07115ff4d 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.rst
@@ -1,8 +1,9 @@
- Coresight - HW Assisted Tracing on ARM
- ======================================
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================

- Author: Mathieu Poirier <[email protected]>
- Date: September 11th, 2014
+ :Author: Mathieu Poirier <[email protected]>
+ :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,57 +143,57 @@ 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
-register the device with the core framework. The unregister function takes
-a reference to a "struct coresight_device", obtained at registration time.
+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 *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:~#
+ 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;
- struct coresight_dev_subtype subtype;
- const struct coresight_ops *ops;
- struct coresight_platform_data *pdata;
- struct device *dev;
- const struct attribute_group **groups;
-};
+ struct coresight_desc {
+ enum coresight_dev_type type;
+ struct coresight_dev_subtype subtype;
+ const struct coresight_ops *ops;
+ struct coresight_platform_data *pdata;
+ struct device *dev;
+ const struct attribute_group **groups;
+ };


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)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
+ static int etm_probe(struct amba_device *adev, const struct amba_id *id)
+ {
+ ...
+ ...
+ drvdata->dev = &adev->dev;
+ ...
+ }

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.

@@ -191,9 +201,12 @@ expected to be accessed and controlled using those entries.
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.

@@ -202,107 +215,107 @@ 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:
-
-root:/sys/bus/coresight/devices# ls
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink status trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
+class will have an "active" entry in sysfs::
+
+ root:/sys/bus/coresight/devices# ls
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:/sys/bus/coresight/devices# ls 20010000.etb
+ enable_sink status trigger_cntr
+ root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+ root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+ 1
+ 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:
-
-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth: 0x2000
-Status: 0x1
-RAM read ptr: 0x0
-RAM wrt ptr: 0x19d3 <----- The write pointer is moving
-Trigger cnt: 0x0
-Control: 0x1
-Flush status: 0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
-
-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:
-
-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
-root:/sys/bus/coresight/devices#
+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
+ 1
+ root:/sys/bus/coresight/devices# cat 20010000.etb/status
+ Depth: 0x2000
+ Status: 0x1
+ RAM read ptr: 0x0
+ RAM wrt ptr: 0x19d3 <----- The write pointer is moving
+ Trigger cnt: 0x0
+ Control: 0x1
+ Flush status: 0x0
+ Flush ctrl: 0x2001
+ root:/sys/bus/coresight/devices#
+
+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::
+
+ 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
+ root:/sys/bus/coresight/devices#

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}
-Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
-Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
-Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Timestamp Timestamp: 17106715833
-Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
-Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
-Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
-Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
-Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
-Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
-Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
-Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
-Info Tracing enabled
-Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
-Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
-Timestamp Timestamp: 17107041535
+::
+
+ Info Tracing enabled
+ Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
+ Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
+ Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
+ Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Timestamp Timestamp: 17106715833
+ Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
+ Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
+ Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
+ Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
+ Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
+ Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+ Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
+ Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
+ Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
+ Info Tracing enabled
+ Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
+ Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
+ Timestamp Timestamp: 17107041535

2) Using perf framework:

@@ -327,7 +340,7 @@ 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. Names for sink to choose
-from are listed in sysFS under ($SYSFS)/bus/coresight/devices:
+from are listed in sysFS under ($SYSFS)/bus/coresight/devices::

root@linaro-nano:~# ls /sys/bus/coresight/devices/
20010000.etf 20040000.funnel 20100000.stm 22040000.etm
@@ -343,14 +356,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/@20070000.etr/u --per-thread

@@ -369,12 +382,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
@@ -403,28 +418,30 @@ 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/20100000.stm
-enable_source hwevent_select port_enable subsystem uevent
-hwevent_enable mgmt port_select traceid
-root@genericarmv8:~#
+ root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
+ enable_source hwevent_select port_enable subsystem uevent
+ 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/20010000.etf/enable_sink
-root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
+ root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/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/20100000.stm
+ crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
+ root@genericarmv8:~#
+
+Details on how to use the generic STM API can be found here [#second]_.

-root@genericarmv8:~# ls -l /dev/20100000.stm
-crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
-root@genericarmv8:~#
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

-Details on how to use the generic STM API can be found here [2].
+.. [#second] Documentation/trace/stm.rst

-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107cf4b98..b7891cb1ab4d 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,5 @@ Linux Tracing Technologies
intel_th
stm
sys-t
+ coresight
+ coresight-cpu-debug
diff --git a/MAINTAINERS b/MAINTAINERS
index 558acf24ea1e..04b006e5cc0a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1549,8 +1549,8 @@ R: Suzuki K Poulose <[email protected]>
L: [email protected] (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-*
--
2.11.0

2019-07-10 12:46:00

by Mauro Carvalho Chehab

Subject: Re: [Patch V3] Documentation: coresight: covert txt to rst

Em Wed, 10 Jul 2019 09:05:30 +0700
Phong Tran <[email protected]> escreveu:

> as doc-guide of kernel documentation, use Sphinx tool to
> generate the html/pdf... files.
>
> This changes the plan text txt to rst format.
>
> Signed-off-by: Phong Tran <[email protected]>
> ---
> ChangeLog:
> V2: review points from Mathieu, Jonathan
> * Add coresight-cpu-debug
> * Update MAINTAINERS file
> * Avoid use markup as much as posible
> V3: review points from Mauro
> * add the colon author, date
> * change to use ```` in the struct
> * add line for the acronyms
> ---
> ...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 67 ++--
> .../trace/{coresight.txt => coresight.rst} | 341 +++++++++++----------
> Documentation/trace/index.rst | 2 +
> MAINTAINERS | 4 +-
> 4 files changed, 219 insertions(+), 195 deletions(-)
> rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
> rename Documentation/trace/{coresight.txt => coresight.rst} (55%)

Hmm... patch failed to apply on the top of linux-next. It seems that
coresight.txt suffered some changes after your patch:

commit cd84d63a2983ee2d386ff5a020c2c36562e4ef68
Author: Suzuki K Poulose <[email protected]>
Date: Mon Jun 10 19:02:42 2019 +0100

Documentation: coresight: Update the generic device names

Update the documentation to reflect the new naming scheme with
latest changes.

Except for that, the conversion seems fine.

>
> diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
> similarity index 84%
> rename from Documentation/trace/coresight-cpu-debug.txt
> rename to Documentation/trace/coresight-cpu-debug.rst
> index f07e38094b40..8c6ecb4c1f54 100644
> --- a/Documentation/trace/coresight-cpu-debug.txt
> +++ b/Documentation/trace/coresight-cpu-debug.rst
> @@ -1,8 +1,9 @@
> - Coresight CPU Debug Module
> - ==========================
> +==========================
> +Coresight CPU Debug Module
> +==========================
>
> - Author: Leo Yan <[email protected]>
> - Date: April 5th, 2017
> + :Author: Leo Yan <[email protected]>
> + :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,18 +127,21 @@ 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:
> -# insmod coresight_cpu_debug.ko debug=1
> +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:
> -# echo 1 > /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
> + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
>
> As explained in chapter "Clock and power domain", if you are working on one
> platform which has idle states to power off debug logic and the power
> @@ -154,34 +159,34 @@ subsystem, more specifically by using the "/dev/cpu_dma_latency"
> interface (see Documentation/power/pm_qos_interface.txt 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
> -...
> -Do some work...
> -...
> -# exec 3<>-
> + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
> + ...
> + Do some work...
> + ...
> + # exec 3<>-
>
> 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:
> -
> -ARM external debug module:
> -coresight-cpu-debug 850000.debug: CPU[0]:
> -coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> -coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> -coresight-cpu-debug 852000.debug: CPU[1]:
> -coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> -coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> +Here is an example of the debugging output format::
> +
> + ARM external debug module:
> + coresight-cpu-debug 850000.debug: CPU[0]:
> + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> + coresight-cpu-debug 852000.debug: CPU[1]:
> + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
> similarity index 55%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index efbc832146e7..39b07115ff4d 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,8 +1,9 @@
> - Coresight - HW Assisted Tracing on ARM
> - ======================================
> +======================================
> +Coresight - HW Assisted Tracing on ARM
> +======================================
>
> - Author: Mathieu Poirier <[email protected]>
> - Date: September 11th, 2014
> + :Author: Mathieu Poirier <[email protected]>
> + :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,57 +143,57 @@ 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
> -register the device with the core framework. The unregister function takes
> -a reference to a "struct coresight_device", obtained at registration time.
> +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 *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:~#
> + 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;
> - struct coresight_dev_subtype subtype;
> - const struct coresight_ops *ops;
> - struct coresight_platform_data *pdata;
> - struct device *dev;
> - const struct attribute_group **groups;
> -};
> + struct coresight_desc {
> + enum coresight_dev_type type;
> + struct coresight_dev_subtype subtype;
> + const struct coresight_ops *ops;
> + struct coresight_platform_data *pdata;
> + struct device *dev;
> + const struct attribute_group **groups;
> + };
>
>
> 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)
> -{
> - ...
> - ...
> - drvdata->dev = &adev->dev;
> - ...
> -}
> + static int etm_probe(struct amba_device *adev, const struct amba_id *id)
> + {
> + ...
> + ...
> + drvdata->dev = &adev->dev;
> + ...
> + }
>
> 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.
>
> @@ -191,9 +201,12 @@ expected to be accessed and controlled using those entries.
> 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.
>
> @@ -202,107 +215,107 @@ 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:
> -
> -root:/sys/bus/coresight/devices# ls
> -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> -root:/sys/bus/coresight/devices# ls 20010000.etb
> -enable_sink status trigger_cntr
> -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> -1
> -root:/sys/bus/coresight/devices#
> +class will have an "active" entry in sysfs::
> +
> + root:/sys/bus/coresight/devices# ls
> + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> + root:/sys/bus/coresight/devices# ls 20010000.etb
> + enable_sink status trigger_cntr
> + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> + 1
> + 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:
> -
> -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
> -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
> -1
> -root:/sys/bus/coresight/devices# cat 20010000.etb/status
> -Depth: 0x2000
> -Status: 0x1
> -RAM read ptr: 0x0
> -RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> -Trigger cnt: 0x0
> -Control: 0x1
> -Flush status: 0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> -
> -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:
> -
> -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
> -root:/sys/bus/coresight/devices#
> +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
> + 1
> + root:/sys/bus/coresight/devices# cat 20010000.etb/status
> + Depth: 0x2000
> + Status: 0x1
> + RAM read ptr: 0x0
> + RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> + Trigger cnt: 0x0
> + Control: 0x1
> + Flush status: 0x0
> + Flush ctrl: 0x2001
> + root:/sys/bus/coresight/devices#
> +
> +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::
> +
> + 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
> + root:/sys/bus/coresight/devices#
>
> 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}
> -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Timestamp Timestamp: 17106715833
> -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> -Info Tracing enabled
> -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> -Timestamp Timestamp: 17107041535
> +::
> +
> + Info Tracing enabled
> + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
> + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Timestamp Timestamp: 17106715833
> + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> + Info Tracing enabled
> + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> + Timestamp Timestamp: 17107041535
>
> 2) Using perf framework:
>
> @@ -327,7 +340,7 @@ 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. Names for sink to choose
> -from are listed in sysFS under ($SYSFS)/bus/coresight/devices:
> +from are listed in sysFS under ($SYSFS)/bus/coresight/devices::
>
> root@linaro-nano:~# ls /sys/bus/coresight/devices/
> 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
> @@ -343,14 +356,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/@20070000.etr/u --per-thread
>
> @@ -369,12 +382,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
> @@ -403,28 +418,30 @@ 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/20100000.stm
> -enable_source hwevent_select port_enable subsystem uevent
> -hwevent_enable mgmt port_select traceid
> -root@genericarmv8:~#
> + root@genericarmv8:~# ls /sys/bus/coresight/devices/20100000.stm
> + enable_source hwevent_select port_enable subsystem uevent
> + 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/20010000.etf/enable_sink
> -root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/enable_source
> + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20010000.etf/enable_sink
> + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/20100000.stm/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/20100000.stm
> + crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
> + root@genericarmv8:~#
> +
> +Details on how to use the generic STM API can be found here [#second]_.
>
> -root@genericarmv8:~# ls -l /dev/20100000.stm
> -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/20100000.stm
> -root@genericarmv8:~#
> +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
>
> -Details on how to use the generic STM API can be found here [2].
> +.. [#second] Documentation/trace/stm.rst
>
> -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> -[2]. Documentation/trace/stm.rst
> -[3]. https://github.com/Linaro/perf-opencsd
> +.. [#third] https://github.com/Linaro/perf-opencsd
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 6b4107cf4b98..b7891cb1ab4d 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -23,3 +23,5 @@ Linux Tracing Technologies
> intel_th
> stm
> sys-t
> + coresight
> + coresight-cpu-debug
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 558acf24ea1e..04b006e5cc0a 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1549,8 +1549,8 @@ R: Suzuki K Poulose <[email protected]>
> L: [email protected] (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-*



Thanks,
Mauro

2019-07-10 15:04:09

by Phong Tran

Subject: [Patch V4] Documentation: coresight: covert txt to rst

as doc-guide of kernel documentation, use Sphinx tool to
generate the html/pdf... files.

This changes the plan text txt to rst format.

Signed-off-by: Phong Tran <[email protected]>
---
ChangeLog:
V2: review points from Mathieu, Jonathan
* Add coresight-cpu-debug
* Update MAINTAINERS file
* Avoid use markup as much as posible
V3: review points from Mauro
* add the colon author, date
* change to use ```` in the struct
* add line for the acronyms
V4:
* Rebase on linux-next tree
---
...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 67 ++--
.../trace/{coresight.txt => coresight.rst} | 372 +++++++++++----------
Documentation/trace/index.rst | 2 +
MAINTAINERS | 4 +-
4 files changed, 234 insertions(+), 211 deletions(-)
rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
rename Documentation/trace/{coresight.txt => coresight.rst} (56%)

diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
similarity index 84%
rename from Documentation/trace/coresight-cpu-debug.txt
rename to Documentation/trace/coresight-cpu-debug.rst
index 1a660a39e3c0..993dd294b81b 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.rst
@@ -1,8 +1,9 @@
- Coresight CPU Debug Module
- ==========================
+==========================
+Coresight CPU Debug Module
+==========================

- Author: Leo Yan <[email protected]>
- Date: April 5th, 2017
+ :Author: Leo Yan <[email protected]>
+ :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,18 +127,21 @@ 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:
-# insmod coresight_cpu_debug.ko debug=1
+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:
-# echo 1 > /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
+ # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

As explained in chapter "Clock and power domain", if you are working on one
platform which has idle states to power off debug logic and the power
@@ -154,34 +159,34 @@ 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
-...
-Do some work...
-...
-# exec 3<>-
+ # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
+ ...
+ Do some work...
+ ...
+ # exec 3<>-

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:
-
-ARM external debug module:
-coresight-cpu-debug 850000.debug: CPU[0]:
-coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
-coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
-coresight-cpu-debug 852000.debug: CPU[1]:
-coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
-coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+Here is an example of the debugging output format::
+
+ ARM external debug module:
+ coresight-cpu-debug 850000.debug: CPU[0]:
+ coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
+ coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+ coresight-cpu-debug 852000.debug: CPU[1]:
+ coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
+ coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
similarity index 56%
rename from Documentation/trace/coresight.txt
rename to Documentation/trace/coresight.rst
index b027d61b27a6..72f4b7ef1bad 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.rst
@@ -1,8 +1,9 @@
- Coresight - HW Assisted Tracing on ARM
- ======================================
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================

- Author: Mathieu Poirier <[email protected]>
- Date: September 11th, 2014
+ :Author: Mathieu Poirier <[email protected]>
+ :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,79 +143,79 @@ 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
-register the device with the core framework. The unregister function takes
-a reference to a "struct coresight_device", obtained at registration time.
+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 *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:~#
+ 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;
- struct coresight_dev_subtype subtype;
- const struct coresight_ops *ops;
- struct coresight_platform_data *pdata;
- struct device *dev;
- const struct attribute_group **groups;
-};
+ struct coresight_desc {
+ enum coresight_dev_type type;
+ struct coresight_dev_subtype subtype;
+ const struct coresight_ops *ops;
+ struct coresight_platform_data *pdata;
+ struct device *dev;
+ const struct attribute_group **groups;
+ };


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)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
+ static int etm_probe(struct amba_device *adev, const struct amba_id *id)
+ {
+ ...
+ ...
+ drvdata->dev = &adev->dev;
+ ...
+ }

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
- 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
- 20070000.etr 20120000.replicator 220c0000.funnel
- 23040000.etm 23140000.etm 23340000.etm
+ root:~# ls /sys/bus/coresight/devices/
+ 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
+ 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
+ 20070000.etr 20120000.replicator 220c0000.funnel
+ 23040000.etm 23140000.etm 23340000.etm

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,11 +230,11 @@ 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
- funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
+ root:~# ls /sys/bus/coresight/devices/
+ etm0 etm1 etm2 etm3 etm4 etm5 funnel0
+ funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0

Some of the examples below might refer to old naming scheme and some
to the newer scheme, to give a confirmation that what you see on your
@@ -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,107 +258,107 @@ 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:
-
-root:/sys/bus/coresight/devices# ls
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink status trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
+class will have an "active" entry in sysfs::
+
+ root:/sys/bus/coresight/devices# ls
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:/sys/bus/coresight/devices# ls 20010000.etb
+ enable_sink status trigger_cntr
+ root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+ root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+ 1
+ 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:
-
-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth: 0x2000
-Status: 0x1
-RAM read ptr: 0x0
-RAM wrt ptr: 0x19d3 <----- The write pointer is moving
-Trigger cnt: 0x0
-Control: 0x1
-Flush status: 0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
-
-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:
-
-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
-root:/sys/bus/coresight/devices#
+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
+ 1
+ root:/sys/bus/coresight/devices# cat 20010000.etb/status
+ Depth: 0x2000
+ Status: 0x1
+ RAM read ptr: 0x0
+ RAM wrt ptr: 0x19d3 <----- The write pointer is moving
+ Trigger cnt: 0x0
+ Control: 0x1
+ Flush status: 0x0
+ Flush ctrl: 0x2001
+ root:/sys/bus/coresight/devices#
+
+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::
+
+ 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
+ root:/sys/bus/coresight/devices#

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}
-Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
-Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
-Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Timestamp Timestamp: 17106715833
-Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
-Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
-Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
-Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
-Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
-Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
-Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
-Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
-Info Tracing enabled
-Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
-Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
-Timestamp Timestamp: 17107041535
+::
+
+ Info Tracing enabled
+ Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
+ Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
+ Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
+ Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Timestamp Timestamp: 17106715833
+ Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
+ Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
+ Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
+ Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
+ Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
+ Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+ Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
+ Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
+ Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
+ Info Tracing enabled
+ Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
+ Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
+ Timestamp Timestamp: 17107041535

2) Using perf framework:

@@ -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,28 +469,30 @@ 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
-hwevent_enable mgmt port_select traceid
-root@genericarmv8:~#
+ root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
+ enable_source hwevent_select port_enable subsystem uevent
+ 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
+ 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 [#second]_.

-root@genericarmv8:~# ls -l /dev/stm0
-crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
-root@genericarmv8:~#
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

-Details on how to use the generic STM API can be found here [2].
+.. [#second] Documentation/trace/stm.rst

-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107cf4b98..b7891cb1ab4d 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,5 @@ Linux Tracing Technologies
intel_th
stm
sys-t
+ coresight
+ coresight-cpu-debug
diff --git a/MAINTAINERS b/MAINTAINERS
index 661def85619c..eb03e5966f11 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1582,8 +1582,8 @@ R: Suzuki K Poulose <[email protected]>
L: [email protected] (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-*
--
2.11.0

2019-07-10 17:03:52

by Mauro Carvalho Chehab

Subject: Re: [Patch V4] Documentation: coresight: covert txt to rst

Em Wed, 10 Jul 2019 22:01:33 +0700
Phong Tran <[email protected]> escreveu:

> as doc-guide of kernel documentation, use Sphinx tool to
> generate the html/pdf... files.

Description looks a little bogus to me...

>
> This changes the plan text txt to rst format.
>
> Signed-off-by: Phong Tran <[email protected]>

But looking at the patch itself:

Reviewed-by: Mauro Carvalho Chehab <[email protected]>

> ---
> ChangeLog:
> V2: review points from Mathieu, Jonathan
> * Add coresight-cpu-debug
> * Update MAINTAINERS file
> * Avoid use markup as much as posible
> V3: review points from Mauro
> * add the colon author, date
> * change to use ```` in the struct
> * add line for the acronyms
> V4:
> * Rebase on linux-next tree
> ---
> ...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 67 ++--
> .../trace/{coresight.txt => coresight.rst} | 372 +++++++++++----------
> Documentation/trace/index.rst | 2 +
> MAINTAINERS | 4 +-
> 4 files changed, 234 insertions(+), 211 deletions(-)
> rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
> rename Documentation/trace/{coresight.txt => coresight.rst} (56%)
>
> diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
> similarity index 84%
> rename from Documentation/trace/coresight-cpu-debug.txt
> rename to Documentation/trace/coresight-cpu-debug.rst
> index 1a660a39e3c0..993dd294b81b 100644
> --- a/Documentation/trace/coresight-cpu-debug.txt
> +++ b/Documentation/trace/coresight-cpu-debug.rst
> @@ -1,8 +1,9 @@
> - Coresight CPU Debug Module
> - ==========================
> +==========================
> +Coresight CPU Debug Module
> +==========================
>
> - Author: Leo Yan <[email protected]>
> - Date: April 5th, 2017
> + :Author: Leo Yan <[email protected]>
> + :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,18 +127,21 @@ 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:
> -# insmod coresight_cpu_debug.ko debug=1
> +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:
> -# echo 1 > /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
> + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
>
> As explained in chapter "Clock and power domain", if you are working on one
> platform which has idle states to power off debug logic and the power
> @@ -154,34 +159,34 @@ 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
> -...
> -Do some work...
> -...
> -# exec 3<>-
> + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
> + ...
> + Do some work...
> + ...
> + # exec 3<>-
>
> 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:
> -
> -ARM external debug module:
> -coresight-cpu-debug 850000.debug: CPU[0]:
> -coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> -coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> -coresight-cpu-debug 852000.debug: CPU[1]:
> -coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> -coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> +Here is an example of the debugging output format::
> +
> + ARM external debug module:
> + coresight-cpu-debug 850000.debug: CPU[0]:
> + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> + coresight-cpu-debug 852000.debug: CPU[1]:
> + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
> similarity index 56%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index b027d61b27a6..72f4b7ef1bad 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,8 +1,9 @@
> - Coresight - HW Assisted Tracing on ARM
> - ======================================
> +======================================
> +Coresight - HW Assisted Tracing on ARM
> +======================================
>
> - Author: Mathieu Poirier <[email protected]>
> - Date: September 11th, 2014
> + :Author: Mathieu Poirier <[email protected]>
> + :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,79 +143,79 @@ 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
> -register the device with the core framework. The unregister function takes
> -a reference to a "struct coresight_device", obtained at registration time.
> +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 *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:~#
> + 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;
> - struct coresight_dev_subtype subtype;
> - const struct coresight_ops *ops;
> - struct coresight_platform_data *pdata;
> - struct device *dev;
> - const struct attribute_group **groups;
> -};
> + struct coresight_desc {
> + enum coresight_dev_type type;
> + struct coresight_dev_subtype subtype;
> + const struct coresight_ops *ops;
> + struct coresight_platform_data *pdata;
> + struct device *dev;
> + const struct attribute_group **groups;
> + };
>
>
> 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)
> -{
> - ...
> - ...
> - drvdata->dev = &adev->dev;
> - ...
> -}
> + static int etm_probe(struct amba_device *adev, const struct amba_id *id)
> + {
> + ...
> + ...
> + drvdata->dev = &adev->dev;
> + ...
> + }
>
> 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
> - 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
> - 20070000.etr 20120000.replicator 220c0000.funnel
> - 23040000.etm 23140000.etm 23340000.etm
> + root:~# ls /sys/bus/coresight/devices/
> + 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
> + 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
> + 20070000.etr 20120000.replicator 220c0000.funnel
> + 23040000.etm 23140000.etm 23340000.etm
>
> 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,11 +230,11 @@ 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
> - funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
> + root:~# ls /sys/bus/coresight/devices/
> + etm0 etm1 etm2 etm3 etm4 etm5 funnel0
> + funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
>
> Some of the examples below might refer to old naming scheme and some
> to the newer scheme, to give a confirmation that what you see on your
> @@ -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,107 +258,107 @@ 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:
> -
> -root:/sys/bus/coresight/devices# ls
> -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> -root:/sys/bus/coresight/devices# ls 20010000.etb
> -enable_sink status trigger_cntr
> -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> -1
> -root:/sys/bus/coresight/devices#
> +class will have an "active" entry in sysfs::
> +
> + root:/sys/bus/coresight/devices# ls
> + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> + root:/sys/bus/coresight/devices# ls 20010000.etb
> + enable_sink status trigger_cntr
> + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> + 1
> + 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:
> -
> -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
> -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
> -1
> -root:/sys/bus/coresight/devices# cat 20010000.etb/status
> -Depth: 0x2000
> -Status: 0x1
> -RAM read ptr: 0x0
> -RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> -Trigger cnt: 0x0
> -Control: 0x1
> -Flush status: 0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> -
> -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:
> -
> -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
> -root:/sys/bus/coresight/devices#
> +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
> + 1
> + root:/sys/bus/coresight/devices# cat 20010000.etb/status
> + Depth: 0x2000
> + Status: 0x1
> + RAM read ptr: 0x0
> + RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> + Trigger cnt: 0x0
> + Control: 0x1
> + Flush status: 0x0
> + Flush ctrl: 0x2001
> + root:/sys/bus/coresight/devices#
> +
> +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::
> +
> + 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
> + root:/sys/bus/coresight/devices#
>
> 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}
> -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Timestamp Timestamp: 17106715833
> -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> -Info Tracing enabled
> -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> -Timestamp Timestamp: 17107041535
> +::
> +
> + Info Tracing enabled
> + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
> + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Timestamp Timestamp: 17106715833
> + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> + Info Tracing enabled
> + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> + Timestamp Timestamp: 17107041535
>
> 2) Using perf framework:
>
> @@ -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,28 +469,30 @@ 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
> -hwevent_enable mgmt port_select traceid
> -root@genericarmv8:~#
> + root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
> + enable_source hwevent_select port_enable subsystem uevent
> + 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
> + 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 [#second]_.
>
> -root@genericarmv8:~# ls -l /dev/stm0
> -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
> -root@genericarmv8:~#
> +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
>
> -Details on how to use the generic STM API can be found here [2].
> +.. [#second] Documentation/trace/stm.rst
>
> -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> -[2]. Documentation/trace/stm.rst
> -[3]. https://github.com/Linaro/perf-opencsd
> +.. [#third] https://github.com/Linaro/perf-opencsd
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 6b4107cf4b98..b7891cb1ab4d 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -23,3 +23,5 @@ Linux Tracing Technologies
> intel_th
> stm
> sys-t
> + coresight
> + coresight-cpu-debug
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 661def85619c..eb03e5966f11 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1582,8 +1582,8 @@ R: Suzuki K Poulose <[email protected]>
> L: [email protected] (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-*



Thanks,
Mauro

2019-07-11 16:37:08

by Mathieu Poirier

Subject: Re: [Patch V4] Documentation: coresight: covert txt to rst

On Wed, 10 Jul 2019 at 09:01, Phong Tran <[email protected]> wrote:
>
> as doc-guide of kernel documentation, use Sphinx tool to
> generate the html/pdf... files.
>
> This changes the plan text txt to rst format.
>

I agree with Mauro - although the changelong has already been improved
it is still below the minimum requirements.

> Signed-off-by: Phong Tran <[email protected]>

As for the content of the patch:

Acked-by: Mathieu Poirier <[email protected]>


> ---
> ChangeLog:
> V2: review points from Mathieu, Jonathan
> * Add coresight-cpu-debug
> * Update MAINTAINERS file
> * Avoid use markup as much as posible
> V3: review points from Mauro
> * add the colon author, date
> * change to use ```` in the struct
> * add line for the acronyms
> V4:
> * Rebase on linux-next tree
> ---
> ...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 67 ++--
> .../trace/{coresight.txt => coresight.rst} | 372 +++++++++++----------
> Documentation/trace/index.rst | 2 +
> MAINTAINERS | 4 +-
> 4 files changed, 234 insertions(+), 211 deletions(-)
> rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
> rename Documentation/trace/{coresight.txt => coresight.rst} (56%)
>
> diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
> similarity index 84%
> rename from Documentation/trace/coresight-cpu-debug.txt
> rename to Documentation/trace/coresight-cpu-debug.rst
> index 1a660a39e3c0..993dd294b81b 100644
> --- a/Documentation/trace/coresight-cpu-debug.txt
> +++ b/Documentation/trace/coresight-cpu-debug.rst
> @@ -1,8 +1,9 @@
> - Coresight CPU Debug Module
> - ==========================
> +==========================
> +Coresight CPU Debug Module
> +==========================
>
> - Author: Leo Yan <[email protected]>
> - Date: April 5th, 2017
> + :Author: Leo Yan <[email protected]>
> + :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,18 +127,21 @@ 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:
> -# insmod coresight_cpu_debug.ko debug=1
> +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:
> -# echo 1 > /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
> + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable
>
> As explained in chapter "Clock and power domain", if you are working on one
> platform which has idle states to power off debug logic and the power
> @@ -154,34 +159,34 @@ 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
> -...
> -Do some work...
> -...
> -# exec 3<>-
> + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
> + ...
> + Do some work...
> + ...
> + # exec 3<>-
>
> 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:
> -
> -ARM external debug module:
> -coresight-cpu-debug 850000.debug: CPU[0]:
> -coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> -coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> -coresight-cpu-debug 852000.debug: CPU[1]:
> -coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> -coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> -coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> -coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> +Here is an example of the debugging output format::
> +
> + ARM external debug module:
> + coresight-cpu-debug 850000.debug: CPU[0]:
> + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
> + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> + coresight-cpu-debug 852000.debug: CPU[1]:
> + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
> + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
> + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
> + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
> diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
> similarity index 56%
> rename from Documentation/trace/coresight.txt
> rename to Documentation/trace/coresight.rst
> index b027d61b27a6..72f4b7ef1bad 100644
> --- a/Documentation/trace/coresight.txt
> +++ b/Documentation/trace/coresight.rst
> @@ -1,8 +1,9 @@
> - Coresight - HW Assisted Tracing on ARM
> - ======================================
> +======================================
> +Coresight - HW Assisted Tracing on ARM
> +======================================
>
> - Author: Mathieu Poirier <[email protected]>
> - Date: September 11th, 2014
> + :Author: Mathieu Poirier <[email protected]>
> + :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,79 +143,79 @@ 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
> -register the device with the core framework. The unregister function takes
> -a reference to a "struct coresight_device", obtained at registration time.
> +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 *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:~#
> + 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;
> - struct coresight_dev_subtype subtype;
> - const struct coresight_ops *ops;
> - struct coresight_platform_data *pdata;
> - struct device *dev;
> - const struct attribute_group **groups;
> -};
> + struct coresight_desc {
> + enum coresight_dev_type type;
> + struct coresight_dev_subtype subtype;
> + const struct coresight_ops *ops;
> + struct coresight_platform_data *pdata;
> + struct device *dev;
> + const struct attribute_group **groups;
> + };
>
>
> 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)
> -{
> - ...
> - ...
> - drvdata->dev = &adev->dev;
> - ...
> -}
> + static int etm_probe(struct amba_device *adev, const struct amba_id *id)
> + {
> + ...
> + ...
> + drvdata->dev = &adev->dev;
> + ...
> + }
>
> 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
> - 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
> - 20070000.etr 20120000.replicator 220c0000.funnel
> - 23040000.etm 23140000.etm 23340000.etm
> + root:~# ls /sys/bus/coresight/devices/
> + 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
> + 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
> + 20070000.etr 20120000.replicator 220c0000.funnel
> + 23040000.etm 23140000.etm 23340000.etm
>
> 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,11 +230,11 @@ 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
> - funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
> + root:~# ls /sys/bus/coresight/devices/
> + etm0 etm1 etm2 etm3 etm4 etm5 funnel0
> + funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
>
> Some of the examples below might refer to old naming scheme and some
> to the newer scheme, to give a confirmation that what you see on your
> @@ -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,107 +258,107 @@ 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:
> -
> -root:/sys/bus/coresight/devices# ls
> -replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> -20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> -root:/sys/bus/coresight/devices# ls 20010000.etb
> -enable_sink status trigger_cntr
> -root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> -root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> -1
> -root:/sys/bus/coresight/devices#
> +class will have an "active" entry in sysfs::
> +
> + root:/sys/bus/coresight/devices# ls
> + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
> + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
> + root:/sys/bus/coresight/devices# ls 20010000.etb
> + enable_sink status trigger_cntr
> + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
> + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
> + 1
> + 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:
> -
> -root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
> -root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
> -1
> -root:/sys/bus/coresight/devices# cat 20010000.etb/status
> -Depth: 0x2000
> -Status: 0x1
> -RAM read ptr: 0x0
> -RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> -Trigger cnt: 0x0
> -Control: 0x1
> -Flush status: 0x0
> -Flush ctrl: 0x2001
> -root:/sys/bus/coresight/devices#
> -
> -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:
> -
> -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
> -root:/sys/bus/coresight/devices#
> +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
> + 1
> + root:/sys/bus/coresight/devices# cat 20010000.etb/status
> + Depth: 0x2000
> + Status: 0x1
> + RAM read ptr: 0x0
> + RAM wrt ptr: 0x19d3 <----- The write pointer is moving
> + Trigger cnt: 0x0
> + Control: 0x1
> + Flush status: 0x0
> + Flush ctrl: 0x2001
> + root:/sys/bus/coresight/devices#
> +
> +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::
> +
> + 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
> + root:/sys/bus/coresight/devices#
>
> 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}
> -Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> -Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> -Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Timestamp Timestamp: 17106715833
> -Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> -Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> -Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> -Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> -Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> -Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> -Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> -Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> -Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> -Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> -Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> -Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> -Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> -Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> -Info Tracing enabled
> -Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> -Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> -Timestamp Timestamp: 17107041535
> +::
> +
> + Info Tracing enabled
> + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
> + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
> + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
> + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Timestamp Timestamp: 17106715833
> + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
> + Instruction 0 0x8026B550 E3530004 false CMP r3,#4
> + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
> + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
> + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
> + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
> + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
> + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
> + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
> + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
> + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
> + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
> + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
> + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
> + Info Tracing enabled
> + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
> + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
> + Timestamp Timestamp: 17107041535
>
> 2) Using perf framework:
>
> @@ -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,28 +469,30 @@ 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
> -hwevent_enable mgmt port_select traceid
> -root@genericarmv8:~#
> + root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
> + enable_source hwevent_select port_enable subsystem uevent
> + 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
> + 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 [#second]_.
>
> -root@genericarmv8:~# ls -l /dev/stm0
> -crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
> -root@genericarmv8:~#
> +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
>
> -Details on how to use the generic STM API can be found here [2].
> +.. [#second] Documentation/trace/stm.rst
>
> -[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
> -[2]. Documentation/trace/stm.rst
> -[3]. https://github.com/Linaro/perf-opencsd
> +.. [#third] https://github.com/Linaro/perf-opencsd
> diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
> index 6b4107cf4b98..b7891cb1ab4d 100644
> --- a/Documentation/trace/index.rst
> +++ b/Documentation/trace/index.rst
> @@ -23,3 +23,5 @@ Linux Tracing Technologies
> intel_th
> stm
> sys-t
> + coresight
> + coresight-cpu-debug
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 661def85619c..eb03e5966f11 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1582,8 +1582,8 @@ R: Suzuki K Poulose <[email protected]>
> L: [email protected] (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-*
> --
> 2.11.0
>

2019-07-11 16:40:49

by Marc Gonzalez

Subject: Re: [Patch V4] Documentation: coresight: covert txt to rst

On 10/07/2019 17:01, Phong Tran wrote:
> Subject: [Patch V4] Documentation: coresight: covert txt to rst

Typo in patch subject.

s/covert/convert

2019-07-11 16:53:04

by Phong Tran

Subject: [PATCH] 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 <[email protected]>
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Mathieu Poirier <[email protected]>
---
ChangeLog:
V2: review points from Mathieu, Jonathan
* Add coresight-cpu-debug
* Update MAINTAINERS file
* Avoid use markup as much as posible
V3: review points from Mauro
* add the colon author, date
* change to use ```` in the struct
* add line for the acronyms
V4:
* Rebase on linux-next tree
V5:
* Improve the commit message
---
...sight-cpu-debug.txt => coresight-cpu-debug.rst} | 67 ++--
.../trace/{coresight.txt => coresight.rst} | 372 +++++++++++----------
Documentation/trace/index.rst | 2 +
MAINTAINERS | 4 +-
4 files changed, 234 insertions(+), 211 deletions(-)
rename Documentation/trace/{coresight-cpu-debug.txt => coresight-cpu-debug.rst} (84%)
rename Documentation/trace/{coresight.txt => coresight.rst} (56%)

diff --git a/Documentation/trace/coresight-cpu-debug.txt b/Documentation/trace/coresight-cpu-debug.rst
similarity index 84%
rename from Documentation/trace/coresight-cpu-debug.txt
rename to Documentation/trace/coresight-cpu-debug.rst
index 1a660a39e3c0..993dd294b81b 100644
--- a/Documentation/trace/coresight-cpu-debug.txt
+++ b/Documentation/trace/coresight-cpu-debug.rst
@@ -1,8 +1,9 @@
- Coresight CPU Debug Module
- ==========================
+==========================
+Coresight CPU Debug Module
+==========================

- Author: Leo Yan <[email protected]>
- Date: April 5th, 2017
+ :Author: Leo Yan <[email protected]>
+ :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,18 +127,21 @@ 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:
-# insmod coresight_cpu_debug.ko debug=1
+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:
-# echo 1 > /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
+ # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

As explained in chapter "Clock and power domain", if you are working on one
platform which has idle states to power off debug logic and the power
@@ -154,34 +159,34 @@ 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
-...
-Do some work...
-...
-# exec 3<>-
+ # exec 3<> /dev/cpu_dma_latency; echo 0 >&3
+ ...
+ Do some work...
+ ...
+ # exec 3<>-

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:
-
-ARM external debug module:
-coresight-cpu-debug 850000.debug: CPU[0]:
-coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
-coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
-coresight-cpu-debug 852000.debug: CPU[1]:
-coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
-coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
-coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
-coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+Here is an example of the debugging output format::
+
+ ARM external debug module:
+ coresight-cpu-debug 850000.debug: CPU[0]:
+ coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8
+ coresight-cpu-debug 850000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
+ coresight-cpu-debug 852000.debug: CPU[1]:
+ coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock)
+ coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358
+ coresight-cpu-debug 852000.debug: EDCIDSR: 00000000
+ coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0)
diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.rst
similarity index 56%
rename from Documentation/trace/coresight.txt
rename to Documentation/trace/coresight.rst
index b027d61b27a6..72f4b7ef1bad 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.rst
@@ -1,8 +1,9 @@
- Coresight - HW Assisted Tracing on ARM
- ======================================
+======================================
+Coresight - HW Assisted Tracing on ARM
+======================================

- Author: Mathieu Poirier <[email protected]>
- Date: September 11th, 2014
+ :Author: Mathieu Poirier <[email protected]>
+ :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,79 +143,79 @@ 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
-register the device with the core framework. The unregister function takes
-a reference to a "struct coresight_device", obtained at registration time.
+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 *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:~#
+ 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;
- struct coresight_dev_subtype subtype;
- const struct coresight_ops *ops;
- struct coresight_platform_data *pdata;
- struct device *dev;
- const struct attribute_group **groups;
-};
+ struct coresight_desc {
+ enum coresight_dev_type type;
+ struct coresight_dev_subtype subtype;
+ const struct coresight_ops *ops;
+ struct coresight_platform_data *pdata;
+ struct device *dev;
+ const struct attribute_group **groups;
+ };


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)
-{
- ...
- ...
- drvdata->dev = &adev->dev;
- ...
-}
+ static int etm_probe(struct amba_device *adev, const struct amba_id *id)
+ {
+ ...
+ ...
+ drvdata->dev = &adev->dev;
+ ...
+ }

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
- 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
- 20070000.etr 20120000.replicator 220c0000.funnel
- 23040000.etm 23140000.etm 23340000.etm
+ root:~# ls /sys/bus/coresight/devices/
+ 20010000.etf 20040000.funnel 20100000.stm 22040000.etm
+ 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu
+ 20070000.etr 20120000.replicator 220c0000.funnel
+ 23040000.etm 23140000.etm 23340000.etm

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,11 +230,11 @@ 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
- funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0
+ root:~# ls /sys/bus/coresight/devices/
+ etm0 etm1 etm2 etm3 etm4 etm5 funnel0
+ funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0

Some of the examples below might refer to old naming scheme and some
to the newer scheme, to give a confirmation that what you see on your
@@ -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,107 +258,107 @@ 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:
-
-root:/sys/bus/coresight/devices# ls
-replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
-20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
-root:/sys/bus/coresight/devices# ls 20010000.etb
-enable_sink status trigger_cntr
-root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
-root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
-1
-root:/sys/bus/coresight/devices#
+class will have an "active" entry in sysfs::
+
+ root:/sys/bus/coresight/devices# ls
+ replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm
+ 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm
+ root:/sys/bus/coresight/devices# ls 20010000.etb
+ enable_sink status trigger_cntr
+ root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink
+ root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink
+ 1
+ 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:
-
-root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source
-root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source
-1
-root:/sys/bus/coresight/devices# cat 20010000.etb/status
-Depth: 0x2000
-Status: 0x1
-RAM read ptr: 0x0
-RAM wrt ptr: 0x19d3 <----- The write pointer is moving
-Trigger cnt: 0x0
-Control: 0x1
-Flush status: 0x0
-Flush ctrl: 0x2001
-root:/sys/bus/coresight/devices#
-
-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:
-
-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
-root:/sys/bus/coresight/devices#
+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
+ 1
+ root:/sys/bus/coresight/devices# cat 20010000.etb/status
+ Depth: 0x2000
+ Status: 0x1
+ RAM read ptr: 0x0
+ RAM wrt ptr: 0x19d3 <----- The write pointer is moving
+ Trigger cnt: 0x0
+ Control: 0x1
+ Flush status: 0x0
+ Flush ctrl: 0x2001
+ root:/sys/bus/coresight/devices#
+
+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::
+
+ 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
+ root:/sys/bus/coresight/devices#

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}
-Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
-Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
-Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Timestamp Timestamp: 17106715833
-Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
-Instruction 0 0x8026B550 E3530004 false CMP r3,#4
-Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
-Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
-Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
-Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
-Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
-Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
-Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
-Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
-Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
-Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
-Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
-Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
-Info Tracing enabled
-Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
-Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
-Timestamp Timestamp: 17107041535
+::
+
+ Info Tracing enabled
+ Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr}
+ Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc
+ Instruction 0 0x8026B544 E3A03000 false MOV r3,#0
+ Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Timestamp Timestamp: 17106715833
+ Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4]
+ Instruction 0 0x8026B550 E3530004 false CMP r3,#4
+ Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1
+ Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4]
+ Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c
+ Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1
+ Instruction 0 0x8026B564 E1A0100D false MOV r1,sp
+ Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0
+ Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f
+ Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4]
+ Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368
+ Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc]
+ Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0]
+ Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4
+ Info Tracing enabled
+ Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc
+ Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc}
+ Timestamp Timestamp: 17107041535

2) Using perf framework:

@@ -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,28 +469,30 @@ 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
-hwevent_enable mgmt port_select traceid
-root@genericarmv8:~#
+ root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0
+ enable_source hwevent_select port_enable subsystem uevent
+ 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
+ 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 [#second]_.

-root@genericarmv8:~# ls -l /dev/stm0
-crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0
-root@genericarmv8:~#
+.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

-Details on how to use the generic STM API can be found here [2].
+.. [#second] Documentation/trace/stm.rst

-[1]. Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
-[2]. Documentation/trace/stm.rst
-[3]. https://github.com/Linaro/perf-opencsd
+.. [#third] https://github.com/Linaro/perf-opencsd
diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst
index 6b4107cf4b98..b7891cb1ab4d 100644
--- a/Documentation/trace/index.rst
+++ b/Documentation/trace/index.rst
@@ -23,3 +23,5 @@ Linux Tracing Technologies
intel_th
stm
sys-t
+ coresight
+ coresight-cpu-debug
diff --git a/MAINTAINERS b/MAINTAINERS
index 661def85619c..eb03e5966f11 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1582,8 +1582,8 @@ R: Suzuki K Poulose <[email protected]>
L: [email protected] (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-*
--
2.11.0

2019-07-31 21:57:38

by Jonathan Corbet

Subject: Re: [PATCH] Documentation: coresight: convert txt to rst

On Thu, 11 Jul 2019 23:52:01 +0700
Phong Tran <[email protected]> wrote:

> 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 <[email protected]>
> Reviewed-by: Mauro Carvalho Chehab <[email protected]>
> Acked-by: Mathieu Poirier <[email protected]>

Applied at long last, sorry for the delay.

Thanks,

jon