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