1.. SPDX-License-Identifier: GPL-2.0 2 3======================= 4Intel(R) Trace Hub (TH) 5======================= 6 7Overview 8-------- 9 10Intel(R) Trace Hub (TH) is a set of hardware blocks that produce, 11switch and output trace data from multiple hardware and software 12sources over several types of trace output ports encoded in System 13Trace Protocol (MIPI STPv2) and is intended to perform full system 14debugging. For more information on the hardware, see Intel(R) Trace 15Hub developer's manual [1]. 16 17It consists of trace sources, trace destinations (outputs) and a 18switch (Global Trace Hub, GTH). These devices are placed on a bus of 19their own ("intel_th"), where they can be discovered and configured 20via sysfs attributes. 21 22Currently, the following Intel TH subdevices (blocks) are supported: 23 - Software Trace Hub (STH), trace source, which is a System Trace 24 Module (STM) device, 25 - Memory Storage Unit (MSU), trace output, which allows storing 26 trace hub output in system memory, 27 - Parallel Trace Interface output (PTI), trace output to an external 28 debug host via a PTI port, 29 - Global Trace Hub (GTH), which is a switch and a central component 30 of Intel(R) Trace Hub architecture. 31 32Common attributes for output devices are described in 33Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most 34notable of them is "active", which enables or disables trace output 35into that particular output device. 36 37GTH allows directing different STP masters into different output ports 38via its "masters" attribute group. More detailed GTH interface 39description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth. 40 41STH registers an stm class device, through which it provides interface 42to userspace and kernelspace software trace sources. See 43Documentation/trace/stm.rst for more information on that. 44 45MSU can be configured to collect trace data into a system memory 46buffer, which can later on be read from its device nodes via read() or 47mmap() interface. 48 49On the whole, Intel(R) Trace Hub does not require any special 50userspace software to function; everything can be configured, started 51and collected via sysfs attributes, and device nodes. 52 53[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf 54 55Bus and Subdevices 56------------------ 57 58For each Intel TH device in the system a bus of its own is 59created and assigned an id number that reflects the order in which TH 60devices were emumerated. All TH subdevices (devices on intel_th bus) 61begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is 62followed by device's name and an optional index. 63 64Output devices also get a device node in /dev/intel_thN, where N is 65the Intel TH device id. For example, MSU's memory buffers, when 66allocated, are accessible via /dev/intel_th0/msc{0,1}. 67 68Quick example 69------------- 70 71# figure out which GTH port is the first memory controller:: 72 73 $ cat /sys/bus/intel_th/devices/0-msc0/port 74 0 75 76# looks like it's port 0, configure master 33 to send data to port 0:: 77 78 $ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33 79 80# allocate a 2-windowed multiblock buffer on the first memory 81# controller, each with 64 pages:: 82 83 $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode 84 $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages 85 86# enable wrapping for this controller, too:: 87 88 $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap 89 90# and enable tracing into this port:: 91 92 $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active 93 94# .. send data to master 33, see stm.txt for more details .. 95# .. wait for traces to pile up .. 96# .. and stop the trace:: 97 98 $ echo 0 > /sys/bus/intel_th/devices/0-msc0/active 99 100# and now you can collect the trace from the device node:: 101 102 $ cat /dev/intel_th0/msc0 > my_stp_trace 103 104Host Debugger Mode 105------------------ 106 107It is possible to configure the Trace Hub and control its trace 108capture from a remote debug host, which should be connected via one of 109the hardware debugging interfaces, which will then be used to both 110control Intel Trace Hub and transfer its trace data to the debug host. 111 112The driver needs to be told that such an arrangement is taking place 113so that it does not touch any capture/port configuration and avoids 114conflicting with the debug host's configuration accesses. The only 115activity that the driver will perform in this mode is collecting 116software traces to the Software Trace Hub (an stm class device). The 117user is still responsible for setting up adequate master/channel 118mappings that the decoder on the receiving end would recognize. 119 120In order to enable the host mode, set the 'host_mode' parameter of the 121'intel_th' kernel module to 'y'. None of the virtual output devices 122will show up on the intel_th bus. Also, trace configuration and 123capture controlling attribute groups of the 'gth' device will not be 124exposed. The 'sth' device will operate as usual. 125
