1 .. SPDX-License-Identifier: GPL-2.0
2
3 =======================
4 Intel(R) Trace Hub (TH)
5 =======================
6
7 Overview
8 --------
9
10 Intel(R) Trace Hub (TH) is a set of hardware b
11 switch and output trace data from multiple har
12 sources over several types of trace output por
13 Trace Protocol (MIPI STPv2) and is intended to
14 debugging. For more information on the hardwar
15 Hub developer's manual [1].
16
17 It consists of trace sources, trace destinatio
18 switch (Global Trace Hub, GTH). These devices
19 their own ("intel_th"), where they can be disc
20 via sysfs attributes.
21
22 Currently, the following Intel TH subdevices (
23 - Software Trace Hub (STH), trace source, wh
24 Module (STM) device,
25 - Memory Storage Unit (MSU), trace output, w
26 trace hub output in system memory,
27 - Parallel Trace Interface output (PTI), tra
28 debug host via a PTI port,
29 - Global Trace Hub (GTH), which is a switch
30 of Intel(R) Trace Hub architecture.
31
32 Common attributes for output devices are descr
33 Documentation/ABI/testing/sysfs-bus-intel_th-o
34 notable of them is "active", which enables or
35 into that particular output device.
36
37 GTH allows directing different STP masters int
38 via its "masters" attribute group. More detail
39 description is at Documentation/ABI/testing/sy
40
41 STH registers an stm class device, through whi
42 to userspace and kernelspace software trace so
43 Documentation/trace/stm.rst for more informati
44
45 MSU can be configured to collect trace data in
46 buffer, which can later on be read from its de
47 mmap() interface and directed to a "software s
48 consume the data and/or relay it further.
49
50 On the whole, Intel(R) Trace Hub does not requ
51 userspace software to function; everything can
52 and collected via sysfs attributes, and device
53
54 [1] https://software.intel.com/sites/default/f
55
56 Bus and Subdevices
57 ------------------
58
59 For each Intel TH device in the system a bus o
60 created and assigned an id number that reflect
61 devices were enumerated. All TH subdevices (de
62 begin with this id: 0-gth, 0-msc0, 0-msc1, 0-p
63 followed by device's name and an optional inde
64
65 Output devices also get a device node in /dev/
66 the Intel TH device id. For example, MSU's mem
67 allocated, are accessible via /dev/intel_th0/m
68
69 Quick example
70 -------------
71
72 # figure out which GTH port is the first memor
73
74 $ cat /sys/bus/intel_th/devices/0-msc0
75 0
76
77 # looks like it's port 0, configure master 33
78
79 $ echo 0 > /sys/bus/intel_th/devices/0
80
81 # allocate a 2-windowed multiblock buffer on t
82 # controller, each with 64 pages::
83
84 $ echo multi > /sys/bus/intel_th/devic
85 $ echo 64,64 > /sys/bus/intel_th/devic
86
87 # enable wrapping for this controller, too::
88
89 $ echo 1 > /sys/bus/intel_th/devices/0
90
91 # and enable tracing into this port::
92
93 $ echo 1 > /sys/bus/intel_th/devices/0
94
95 # .. send data to master 33, see stm.txt for m
96 # .. wait for traces to pile up ..
97 # .. and stop the trace::
98
99 $ echo 0 > /sys/bus/intel_th/devices/0
100
101 # and now you can collect the trace from the d
102
103 $ cat /dev/intel_th0/msc0 > my_stp_tra
104
105 Host Debugger Mode
106 ------------------
107
108 It is possible to configure the Trace Hub and
109 capture from a remote debug host, which should
110 the hardware debugging interfaces, which will
111 control Intel Trace Hub and transfer its trace
112
113 The driver needs to be told that such an arran
114 so that it does not touch any capture/port con
115 conflicting with the debug host's configuratio
116 activity that the driver will perform in this
117 software traces to the Software Trace Hub (an
118 user is still responsible for setting up adequ
119 mappings that the decoder on the receiving end
120
121 In order to enable the host mode, set the 'hos
122 'intel_th' kernel module to 'y'. None of the v
123 will show up on the intel_th bus. Also, trace
124 capture controlling attribute groups of the 'g
125 exposed. The 'sth' device will operate as usua
126
127 Software Sinks
128 --------------
129
130 The Memory Storage Unit (MSU) driver provides
131 drivers to register themselves as software sin
132 Such drivers can further export the data via o
133 USB device controllers or network cards.
134
135 The API has two main parts::
136 - notifying the software sink that a particul
137 "locking" that window, that is, making it u
138 collection; when this happens, the MSU driv
139 switch to the next window in the buffer if
140 the trace capture if it's not;
141 - tracking the "locked" state of windows and
142 software sink driver to notify the MSU driv
143 unlocked and can be used again to collect t
144
145 An example sink driver, msu-sink illustrates t
146 software sink. Functionally, it simply unlocks
147 are full, keeping the MSU running in a circula
148 "multi" mode, it will fill out all the windows
149 to just the first one. It can be enabled by wr
150 file (assuming msu-sink.ko is loaded).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.