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