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