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 | |
47 | mmap() interface. | |
48 | ||
49 | On the whole, Intel(R) Trace Hub does not require any special | |
50 | userspace software to function; everything can be configured, started | |
51 | and collected via sysfs attributes, and device nodes. | |
52 | ||
53 | [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf | |
54 | ||
55 | Bus and Subdevices | |
56 | ------------------ | |
57 | ||
58 | For each Intel TH device in the system a bus of its own is | |
59 | created and assigned an id number that reflects the order in which TH | |
60 | devices were emumerated. All TH subdevices (devices on intel_th bus) | |
61 | begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is | |
62 | followed by device's name and an optional index. | |
63 | ||
64 | Output devices also get a device node in /dev/intel_thN, where N is | |
65 | the Intel TH device id. For example, MSU's memory buffers, when | |
66 | allocated, are accessible via /dev/intel_th0/msc{0,1}. | |
67 | ||
68 | Quick example | |
69 | ------------- | |
70 | ||
6613581e | 71 | # figure out which GTH port is the first memory controller:: |
39f40346 | 72 | |
6613581e CD |
73 | $ cat /sys/bus/intel_th/devices/0-msc0/port |
74 | 0 | |
39f40346 | 75 | |
6613581e | 76 | # looks like it's port 0, configure master 33 to send data to port 0:: |
39f40346 | 77 | |
6613581e | 78 | $ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33 |
39f40346 AS |
79 | |
80 | # allocate a 2-windowed multiblock buffer on the first memory | |
6613581e | 81 | # controller, each with 64 pages:: |
39f40346 | 82 | |
6613581e CD |
83 | $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode |
84 | $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages | |
39f40346 | 85 | |
6613581e | 86 | # enable wrapping for this controller, too:: |
39f40346 | 87 | |
6613581e | 88 | $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap |
39f40346 | 89 | |
6613581e | 90 | # and enable tracing into this port:: |
39f40346 | 91 | |
6613581e | 92 | $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active |
39f40346 AS |
93 | |
94 | # .. send data to master 33, see stm.txt for more details .. | |
95 | # .. wait for traces to pile up .. | |
6613581e | 96 | # .. and stop the trace:: |
39f40346 | 97 | |
6613581e | 98 | $ echo 0 > /sys/bus/intel_th/devices/0-msc0/active |
39f40346 | 99 | |
6613581e | 100 | # and now you can collect the trace from the device node:: |
39f40346 | 101 | |
6613581e | 102 | $ cat /dev/intel_th0/msc0 > my_stp_trace |
ee01aebb AS |
103 | |
104 | Host Debugger Mode | |
6613581e | 105 | ------------------ |
ee01aebb AS |
106 | |
107 | It is possible to configure the Trace Hub and control its trace | |
108 | capture from a remote debug host, which should be connected via one of | |
109 | the hardware debugging interfaces, which will then be used to both | |
110 | control Intel Trace Hub and transfer its trace data to the debug host. | |
111 | ||
112 | The driver needs to be told that such an arrangement is taking place | |
113 | so that it does not touch any capture/port configuration and avoids | |
114 | conflicting with the debug host's configuration accesses. The only | |
115 | activity that the driver will perform in this mode is collecting | |
116 | software traces to the Software Trace Hub (an stm class device). The | |
117 | user is still responsible for setting up adequate master/channel | |
118 | mappings that the decoder on the receiving end would recognize. | |
119 | ||
120 | In order to enable the host mode, set the 'host_mode' parameter of the | |
121 | 'intel_th' kernel module to 'y'. None of the virtual output devices | |
122 | will show up on the intel_th bus. Also, trace configuration and | |
123 | capture controlling attribute groups of the 'gth' device will not be | |
124 | exposed. The 'sth' device will operate as usual. |