Documentation: coresight: convert txt to rst

==========================

Coresight CPU Debug Module

==========================

   Author:   Leo Yan <leo.yan@linaro.org>

   Date:     April 5th, 2017

   :Author:   Leo Yan <leo.yan@linaro.org>

   :Date:     April 5th, 2017

Introduction

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

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.

::

                                +---------------+

                                |               |

"coresight_cpu_debug.enable=1" to the kernel command line parameter.

The driver also can work as module, so can enable the debugging when insmod

module:

module::

  # insmod coresight_cpu_debug.ko debug=1

When boot time or insmod module you have not enabled the debugging, the driver

uses the debugfs file system to provide a knob to dynamically enable or disable

debugging:

To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:

To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable::

  # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable

To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:

To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable::

  # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable

As explained in chapter "Clock and power domain", if you are working on one

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

  ...

The same can also be done from an application program.

Disable specific CPU's specific idle state from cpuidle sysfs (see

Documentation/admin-guide/pm/cpuidle.rst):

# echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable

Documentation/admin-guide/pm/cpuidle.rst)::

  # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable

Output format

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

Here is an example of the debugging output format:

Here is an example of the debugging output format::

  ARM external debug module:

  coresight-cpu-debug 850000.debug: CPU[0]:

======================================

Coresight - HW Assisted Tracing on ARM

======================================

   Author:   Mathieu Poirier <mathieu.poirier@linaro.org>

   Date:     September 11th, 2014

   :Author:   Mathieu Poirier <mathieu.poirier@linaro.org>

   :Date:     September 11th, 2014

Introduction

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

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  ****************************===||

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:

Device Tree Bindings

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

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

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

manage coresight devices on a platform.  Any coresight compliant device can

register with the framework for as long as they use the right APIs:

struct coresight_device *coresight_register(struct coresight_desc *desc);

void coresight_unregister(struct coresight_device *csdev);

.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc);

.. c:function:: void coresight_unregister(struct coresight_device *csdev);

The registering function is taking a "struct coresight_device *csdev" and

The registering function is taking a ``struct coresight_desc *desc`` and

register the device with the core framework. The unregister function takes

a reference to a "struct coresight_device", obtained at registration time.

a reference to a ``struct coresight_device *csdev`` obtained at registration time.

If everything goes well during the registration process the new devices will

show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:

show up under /sys/bus/coresight/devices, as showns here for a TC2 platform::

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

    replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm

    20010000.etb         20040000.funnel  2201d000.ptm  2203d000.etm

    root:~#

The functions take a "struct coresight_device", which looks like this:

The functions take a ``struct coresight_device``, which looks like this::

    struct coresight_desc {

            enum coresight_dev_type type;

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)

    {

    }

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

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.

	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

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.

Before trace collection can start, a coresight sink needs to be identified.

There is no limit on the amount of sinks (nor sources) that can be enabled at

any given moment.  As a generic operation, all device pertaining to the sink

class will have an "active" entry in sysfs:

class will have an "active" entry in sysfs::

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

    replicator  20030000.tpiu    2201c000.ptm  2203c000.etm  2203e000.etm

At boot time the current etm3x driver will configure the first address

comparator with "_stext" and "_etext", essentially tracing any instruction

that falls within that range.  As such "enabling" a source will immediately

trigger a trace capture:

trigger a trace capture::

    root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source

    root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source

    Flush ctrl:     0x2001

    root:/sys/bus/coresight/devices#

Trace collection is stopped the same way:

Trace collection is stopped the same way::

    root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source

    root:/sys/bus/coresight/devices#

The content of the ETB buffer can be harvested directly from /dev:

The content of the ETB buffer can be harvested directly from /dev::

    root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \

    of=~/cstrace.bin

    64+0 records in

    64+0 records out

    32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s

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}

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

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

'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

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

    root@genericarmv8:~#

Like any other source a sink needs to be identified and the STM enabled before

being used:

being used::

    root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink

    root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source

From there user space applications can request and use channels using the devfs

interface provided for that purpose by the generic STM API:

interface provided for that purpose by the generic STM API::

    root@genericarmv8:~# ls -l /dev/stm0

    crw-------    1 root     root       10,  61 Jan  3 18:11 /dev/stm0

    root@genericarmv8:~#

Details on how to use the generic STM API can be found here [2].

Details on how to use the generic STM API can be found here [#second]_.

.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm

.. [#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

   intel_th

   stm

   sys-t

   coresight

   coresight-cpu-debug

L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)

S:	Maintained

F:	drivers/hwtracing/coresight/*

F:	Documentation/trace/coresight.txt

F:	Documentation/trace/coresight-cpu-debug.txt

F:	Documentation/trace/coresight.rst

F:	Documentation/trace/coresight-cpu-debug.rst

F:	Documentation/devicetree/bindings/arm/coresight.txt

F:	Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt

F:	Documentation/ABI/testing/sysfs-bus-coresight-devices-*