Commit | Line | Data |
---|---|---|
6613581e | 1 | ======================= |
39f40346 AS |
2 | Intel(R) Trace Hub (TH) |
3 | ======================= | |
4 | ||
5 | Overview | |
6 | -------- | |
7 | ||
8 | Intel(R) Trace Hub (TH) is a set of hardware blocks that produce, | |
9 | switch and output trace data from multiple hardware and software | |
10 | sources over several types of trace output ports encoded in System | |
11 | Trace Protocol (MIPI STPv2) and is intended to perform full system | |
12 | debugging. For more information on the hardware, see Intel(R) Trace | |
13 | Hub developer's manual [1]. | |
14 | ||
15 | It consists of trace sources, trace destinations (outputs) and a | |
16 | switch (Global Trace Hub, GTH). These devices are placed on a bus of | |
17 | their own ("intel_th"), where they can be discovered and configured | |
18 | via sysfs attributes. | |
19 | ||
20 | Currently, the following Intel TH subdevices (blocks) are supported: | |
21 | - Software Trace Hub (STH), trace source, which is a System Trace | |
6613581e | 22 | Module (STM) device, |
39f40346 | 23 | - Memory Storage Unit (MSU), trace output, which allows storing |
6613581e | 24 | trace hub output in system memory, |
39f40346 | 25 | - Parallel Trace Interface output (PTI), trace output to an external |
6613581e | 26 | debug host via a PTI port, |
39f40346 | 27 | - Global Trace Hub (GTH), which is a switch and a central component |
6613581e | 28 | of Intel(R) Trace Hub architecture. |
39f40346 AS |
29 | |
30 | Common attributes for output devices are described in | |
31 | Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most | |
32 | notable of them is "active", which enables or disables trace output | |
33 | into that particular output device. | |
34 | ||
35 | GTH allows directing different STP masters into different output ports | |
36 | via its "masters" attribute group. More detailed GTH interface | |
37 | description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth. | |
38 | ||
39 | STH registers an stm class device, through which it provides interface | |
40 | to userspace and kernelspace software trace sources. See | |
5fb94e9c | 41 | Documentation/trace/stm.rst for more information on that. |
39f40346 AS |
42 | |
43 | MSU can be configured to collect trace data into a system memory | |
44 | buffer, which can later on be read from its device nodes via read() or | |
45 | mmap() interface. | |
46 | ||
47 | On the whole, Intel(R) Trace Hub does not require any special | |
48 | userspace software to function; everything can be configured, started | |
49 | and collected via sysfs attributes, and device nodes. | |
50 | ||
51 | [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf | |
52 | ||
53 | Bus and Subdevices | |
54 | ------------------ | |
55 | ||
56 | For each Intel TH device in the system a bus of its own is | |
57 | created and assigned an id number that reflects the order in which TH | |
58 | devices were emumerated. All TH subdevices (devices on intel_th bus) | |
59 | begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is | |
60 | followed by device's name and an optional index. | |
61 | ||
62 | Output devices also get a device node in /dev/intel_thN, where N is | |
63 | the Intel TH device id. For example, MSU's memory buffers, when | |
64 | allocated, are accessible via /dev/intel_th0/msc{0,1}. | |
65 | ||
66 | Quick example | |
67 | ------------- | |
68 | ||
6613581e | 69 | # figure out which GTH port is the first memory controller:: |
39f40346 | 70 | |
6613581e CD |
71 | $ cat /sys/bus/intel_th/devices/0-msc0/port |
72 | 0 | |
39f40346 | 73 | |
6613581e | 74 | # looks like it's port 0, configure master 33 to send data to port 0:: |
39f40346 | 75 | |
6613581e | 76 | $ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33 |
39f40346 AS |
77 | |
78 | # allocate a 2-windowed multiblock buffer on the first memory | |
6613581e | 79 | # controller, each with 64 pages:: |
39f40346 | 80 | |
6613581e CD |
81 | $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode |
82 | $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages | |
39f40346 | 83 | |
6613581e | 84 | # enable wrapping for this controller, too:: |
39f40346 | 85 | |
6613581e | 86 | $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap |
39f40346 | 87 | |
6613581e | 88 | # and enable tracing into this port:: |
39f40346 | 89 | |
6613581e | 90 | $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active |
39f40346 AS |
91 | |
92 | # .. send data to master 33, see stm.txt for more details .. | |
93 | # .. wait for traces to pile up .. | |
6613581e | 94 | # .. and stop the trace:: |
39f40346 | 95 | |
6613581e | 96 | $ echo 0 > /sys/bus/intel_th/devices/0-msc0/active |
39f40346 | 97 | |
6613581e | 98 | # and now you can collect the trace from the device node:: |
39f40346 | 99 | |
6613581e | 100 | $ cat /dev/intel_th0/msc0 > my_stp_trace |
ee01aebb AS |
101 | |
102 | Host Debugger Mode | |
6613581e | 103 | ------------------ |
ee01aebb AS |
104 | |
105 | It is possible to configure the Trace Hub and control its trace | |
106 | capture from a remote debug host, which should be connected via one of | |
107 | the hardware debugging interfaces, which will then be used to both | |
108 | control Intel Trace Hub and transfer its trace data to the debug host. | |
109 | ||
110 | The driver needs to be told that such an arrangement is taking place | |
111 | so that it does not touch any capture/port configuration and avoids | |
112 | conflicting with the debug host's configuration accesses. The only | |
113 | activity that the driver will perform in this mode is collecting | |
114 | software traces to the Software Trace Hub (an stm class device). The | |
115 | user is still responsible for setting up adequate master/channel | |
116 | mappings that the decoder on the receiving end would recognize. | |
117 | ||
118 | In order to enable the host mode, set the 'host_mode' parameter of the | |
119 | 'intel_th' kernel module to 'y'. None of the virtual output devices | |
120 | will show up on the intel_th bus. Also, trace configuration and | |
121 | capture controlling attribute groups of the 'gth' device will not be | |
122 | exposed. The 'sth' device will operate as usual. |