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