| 1 | |
| 2 |
|
| 3 | =======================
|
| 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
|
| 24 | Module (STM) device,
|
| 25 | - Memory Storage Unit (MSU), trace output, which allows storing
|
| 26 | trace hub output in system memory,
|
| 27 | - Parallel Trace Interface output (PTI), trace output to an external
|
| 28 | debug host via a PTI port,
|
| 29 | - Global Trace Hub (GTH), which is a switch and a central component
|
| 30 | of Intel(R) Trace Hub architecture.
|
| 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
|
| 43 | Documentation/trace/stm.rst for more information on that.
|
| 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 and directed to a "software sink" driver that will
|
| 48 | consume the data and/or relay it further.
|
| 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 enumerated. 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 |
|
| 72 | # figure out which GTH port is the first memory controller::
|
| 73 |
|
| 74 | $ cat /sys/bus/intel_th/devices/0-msc0/port
|
| 75 | 0
|
| 76 |
|
| 77 | # looks like it's port 0, configure master 33 to send data to port 0::
|
| 78 |
|
| 79 | $ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33
|
| 80 |
|
| 81 | # allocate a 2-windowed multiblock buffer on the first memory
|
| 82 | # controller, each with 64 pages::
|
| 83 |
|
| 84 | $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode
|
| 85 | $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages
|
| 86 |
|
| 87 | # enable wrapping for this controller, too::
|
| 88 |
|
| 89 | $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap
|
| 90 |
|
| 91 | # and enable tracing into this port::
|
| 92 |
|
| 93 | $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active
|
| 94 |
|
| 95 | # .. send data to master 33, see stm.txt for more details ..
|
| 96 | # .. wait for traces to pile up ..
|
| 97 | # .. and stop the trace::
|
| 98 |
|
| 99 | $ echo 0 > /sys/bus/intel_th/devices/0-msc0/active
|
| 100 |
|
| 101 | # and now you can collect the trace from the device node::
|
| 102 |
|
| 103 | $ cat /dev/intel_th0/msc0 > my_stp_trace
|
| 104 |
|
| 105 | Host Debugger Mode
|
| 106 | ------------------
|
| 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.
|
| 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).
|