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

From: Qi Liu
Date: Mon Jul 19 2021 - 07:22:03 EST

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@xxxxxxxxxx>
---
.../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@xxxxxxxxxx>
+ Qi Liu <liuqi115@xxxxxxxxxx>
+ :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
--
2.17.1