blob: f7fc5ba5df8d4bd8f21bec56106ee6e2bf45d16f [file] [log] [blame]
Alexander Shishkin39f40342015-09-22 15:47:14 +03001Intel(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