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