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