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