Re: [PATCH 1/2] Documentation: tracing: Documentation for ultrasoc SMB drivers

[Mathieu Poirier <mathieu.poirier@linaro.org>]

On Mon, Jul 19, 2021 at 07:17:36PM +0800, Qi Liu wrote:
> Ultrasoc trace module is a system level solution for tracing, and SMB
> is the component in trace module to store trace message. This patch
> brings in a documentation for ultrasoc SMB driver and simple introduces
> how to use ultrasoc SMB by sysfs interface and perf interface.
> 
> Signed-off-by: Qi Liu <liuqi115@huawei.com>
> ---
>  .../trace/coresight/ultrasoc-trace.rst        | 193 ++++++++++++++++++
>  1 file changed, 193 insertions(+)
>  create mode 100644 Documentation/trace/coresight/ultrasoc-trace.rst
> 
> diff --git a/Documentation/trace/coresight/ultrasoc-trace.rst b/Documentation/trace/coresight/ultrasoc-trace.rst
> new file mode 100644
> index 000000000000..dee133e27bf3
> --- /dev/null
> +++ b/Documentation/trace/coresight/ultrasoc-trace.rst
> @@ -0,0 +1,193 @@
> +=======================================================
> +Siemens Embedded Analytics - HW Assisted Tracing on SoC
> +=======================================================
> +   :Author:   Jonathan Zhou <Jonathan.zhouwen@huawei.com>
> +              Qi Liu <liuqi115@huawei.com>
> +   :Date:     July 8th, 2021
> +
> +Introduction
> +------------
> +
> +This document is concerned with the Siemens Embedded Analytics Framework,
> +using for tracing of multiple type SoC. As this module is developed by
> +Ultrasoc technology, which is acquired by Siemens, we still use "Ultrasoc"
> +to name document and structures.
> +
> +System Memory Buffer is an important component in this Analytics Framework,
> +it provides a way to buffer and store messages in system memory. It provides
> +a capability to store messages received on its input message interface to an
> +area of system memory.
> +
> +A typical Siemens trace system would look like the following diagram:
> +                           @@@@@@@@@@@@@
> +                           @    CPU    @
> +                           @@@@@@@@@@@@@
> +                           #############
> +                           # Coresight #
> +                             #  ETM  #
> +                              #######
> +                                ###
> +                                 #
> +                                 |
> +                                 *
> +                    *******************************
> +                 *** AMBA Advanced Trace Bus (ATB) ***
> +                    ***************^***************
> +                          ===============    |
> +                           === FUNNEL ==<--- |
> +                              =======
> +                                 |
> +                                 *
> +                              @@@@@@@
> +                              @ TRC @
> +                               @@@@@
> +                                @@@
> +                                 @
> +                                 |
> +                                 *
> +    ************************************** *******************
> + ************************ Message BUS ***************************
> +    ******************^************************^****************
> +             |                               |
> +     @@@@@@@@@@@@@@@@@@                      |   @@@@@@@@@@@@
> +     @ Message Engine @                      |   @ JTAG COM @
> +     @@@@@@@@@@@@@@@@@@                      |    @@@@@@@@@@
> +             |                               |---> @@@@@@@@
> +             |                                      @@@@@@
> +          @@@@@@@                                      |
> +          @ SMB @                                     JTAG
> +           @@@@@
> +            @@@
> +             @
> +             |
> +             |
> +             *
> +  ***************************************************************
> + **************************** AMBA AXI  ****************************
> +  *****************************************************************
> +
> +Acronyms
> +---------------------------
> +
> +Acronyms:
> +
> +SMB:         System Memory Buffer
> +TRC:         Trace receiver
> +
> +Framework and implementation
> +------------------------------
> +
> +SMB is implemented as platform device, each SCCL has one SMB device.
> +
> +As TRC receives data from coresight ETM device, SMB can use the following API
> +to register into coresight framework as a sink device:
> +.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc);
> +.. c:function:: void coresight_unregister(struct coresight_device *csdev);
> +
> +Then users can get trace data by this path: ETM->funnel->SMB.
> +More information about coresight framework can be found in
> +Documention/trace/coresight/coresight.rst.
> +
> +If everything goes well, the relationship of Embedded Analytics devices will be
> +described under the sysfs::
> +
> +    $# ls /sys/bus/platform/devices/
> +    <HID.smb>:00
> +    $# ls /sys/bus/coresight/devices/
> +    etm0     etm14    etm2     etm25    etm30    etm8       funnel4
> +    etm1     etm15    etm20    etm26    etm31    etm9       funnel5
> +    etm10    etm16    etm21    etm27    etm4     funnel0    funnel6
> +    etm11    etm17    etm22    etm28    etm5     funnel1    funnel7
> +    etm12    etm18    etm23    etm29    etm6     funnel2    sink_smb0
> +    etm13    etm19    etm24    etm3     etm7     funnel3
> +    $# ls -l /sys/bus/coresight/devices/funnel0/connections/
> +    <file details> in:0 -> ../../../../system/cpu/cpu0/ARMHC500:00/etm0
> +    <file details> in:1 -> ../../../../system/cpu/cpu1/ARMHC500:01/etm1
> +    <file details> in:2 -> ../../../../system/cpu/cpu2/ARMHC500:02/etm2
> +    <file details> in:3 -> ../../../../system/cpu/cpu3/ARMHC500:03/etm3
> +    <file details> nr_links
> +    <file details> out:0 -> ../../../HISI0391:00/HISI03A1:00/sink_smb0
> +    $# ls -l /sys/bus/coresight/devices/sink_smb0/connections/
> +    <file details>  in:101 -> ../../../../ARMHC9FE:05/funnel5
> +    <file details>  in:114 -> ../../../../ARMHC9FE:07/funnel7
> +    <file details>  in:121 -> ../../../../ARMHC9FE:03/funnel3
> +    <file details>  in:39 -> ../../../../ARMHC9FE:00/funnel0
> +    <file details>  in:51 -> ../../../../ARMHC9FE:04/funnel4
> +    <file details>  in:61 -> ../../../../ARMHC9FE:06/funnel6
> +    <file details>  in:68 -> ../../../../ARMHC9FE:02/funnel2
> +    <file details>  in:89 -> ../../../../ARMHC9FE:01/funnel1
> +    <file details>  nr_links
> +
> +How to use the Embedded Analytics trace module
> +-----------------------------------------------
> +
> +There are two ways to use the Embedded Analytics trace module:
> +
> +1. interacting directly with the devices using the sysFS interface.
> +2. using the perf cmd line tools.
> +
> +1) Using the sysFS interface:
> +
> +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::
> +
> +    $# ls /sys/bus/coresight/devices/
> +    etm0     etm14    etm2     etm25    etm30    etm8       funnel4
> +    etm1     etm15    etm20    etm26    etm31    etm9       funnel5
> +    etm10    etm16    etm21    etm27    etm4     funnel0    funnel6
> +    etm11    etm17    etm22    etm28    etm5     funnel1    funnel7
> +    etm12    etm18    etm23    etm29    etm6     funnel2    sink_smb0
> +    etm13    etm19    etm24    etm3     etm7     funnel3
> +    $# ls /sys/bus/coresight/devices/sink_smb0
> +    connections  enable_sink  firmware_node  power  subsystem  uevent
> +    $# echo 1 > /sys/bus/coresight/devices/sink_smb0/enable_sink
> +    $# cat /sys/bus/coresight/devices/sink_smb0/enable_sink
> +    1
> +
> +When start trace collection, etm devices corresponding to the enabled sink
> +should be selected::
> +
> +    $# echo 1 > /sys/bus/coresight/devices/etm0/enable_source
> +    $# cat /sys/bus/coresight/devices/etm0/enable_source
> +    1
> +    $# cat /sys/bus/platform/devices/<HID.smb>:00/com_status
> +    com-type            : DOWN-ONLY
> +    service status      : stopped
> +    interrupt status    : 0x00000003
> +    write point         : 0x5437f400   <----- The write pointer is moving
> +
> +Trace collection is stopped the same way::
> +
> +    $# echo 0 > /sys/bus/coresight/devices/etm0/enable_source
> +    $# echo 0 > /sys/bus/coresight/devices/sink_smb0/enable_sink
> +
> +The content of the SMB buffer can be harvested directly from /dev::
> +
> +    $# dd if=/dev/sink_smb0 of=~/cstrace.bin
> +    5233+0 records in
> +    5233+0 records out
> +    2679296 bytes (2.7 MB) copied, 0.0131708 s, 203 MB/s
> +
> +    root:/sys/bus/coresight/devices#
> +
> +The file cstrace.bin can be decompressed using "ptm2human".
> +
> +2) Using perf framework:
> +
> +As SMB device has been registered with coresight framework, perf tool can be
> +used to control Embedded Analytics trace collection, and the method is similar
> +to using perf to do coresight trace collection.
> +
> +The only thing to note is, list of cpus should be correspond to the specified
> +sink device.
> +
> +Example usage of perf::
> +
> +	 $# ./perf list pmu
> +	 cs_etm//                                    [Kernel PMU event]
> +    $# ./perf record -e cs_etm/@sink_smb0/ -C 0 --per-thread sleep 2s
> +    [ perf record: Woken up 2 times to write data ]
> +    [ perf record: Captured and wrote 0.288 MB perf.data ]
> +    $# ./perf report

This IP block works like any other sink device and as such I don't really see a
need for this documentation - especially since it is mostly conveying the same
information already present in coresight.rst.

Thanks,
Mathieu

> -- 
> 2.17.1
>