151 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=======================4Intel(R) Trace Hub (TH)5=======================6 7Overview8--------9 10Intel(R) Trace Hub (TH) is a set of hardware blocks that produce,11switch and output trace data from multiple hardware and software12sources over several types of trace output ports encoded in System13Trace Protocol (MIPI STPv2) and is intended to perform full system14debugging. For more information on the hardware, see Intel(R) Trace15Hub developer's manual [1].16 17It consists of trace sources, trace destinations (outputs) and a18switch (Global Trace Hub, GTH). These devices are placed on a bus of19their own ("intel_th"), where they can be discovered and configured20via sysfs attributes.21 22Currently, the following Intel TH subdevices (blocks) are supported:23 - Software Trace Hub (STH), trace source, which is a System Trace24 Module (STM) device,25 - Memory Storage Unit (MSU), trace output, which allows storing26 trace hub output in system memory,27 - Parallel Trace Interface output (PTI), trace output to an external28 debug host via a PTI port,29 - Global Trace Hub (GTH), which is a switch and a central component30 of Intel(R) Trace Hub architecture.31 32Common attributes for output devices are described in33Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most34notable of them is "active", which enables or disables trace output35into that particular output device.36 37GTH allows directing different STP masters into different output ports38via its "masters" attribute group. More detailed GTH interface39description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth.40 41STH registers an stm class device, through which it provides interface42to userspace and kernelspace software trace sources. See43Documentation/trace/stm.rst for more information on that.44 45MSU can be configured to collect trace data into a system memory46buffer, which can later on be read from its device nodes via read() or47mmap() interface and directed to a "software sink" driver that will48consume the data and/or relay it further.49 50On the whole, Intel(R) Trace Hub does not require any special51userspace software to function; everything can be configured, started52and collected via sysfs attributes, and device nodes.53 54[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf55 56Bus and Subdevices57------------------58 59For each Intel TH device in the system a bus of its own is60created and assigned an id number that reflects the order in which TH61devices were enumerated. All TH subdevices (devices on intel_th bus)62begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is63followed by device's name and an optional index.64 65Output devices also get a device node in /dev/intel_thN, where N is66the Intel TH device id. For example, MSU's memory buffers, when67allocated, are accessible via /dev/intel_th0/msc{0,1}.68 69Quick example70-------------71 72# figure out which GTH port is the first memory controller::73 74 $ cat /sys/bus/intel_th/devices/0-msc0/port75 076 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/3380 81# allocate a 2-windowed multiblock buffer on the first memory82# controller, each with 64 pages::83 84 $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode85 $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages86 87# enable wrapping for this controller, too::88 89 $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap90 91# and enable tracing into this port::92 93 $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active94 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/active100 101# and now you can collect the trace from the device node::102 103 $ cat /dev/intel_th0/msc0 > my_stp_trace104 105Host Debugger Mode106------------------107 108It is possible to configure the Trace Hub and control its trace109capture from a remote debug host, which should be connected via one of110the hardware debugging interfaces, which will then be used to both111control Intel Trace Hub and transfer its trace data to the debug host.112 113The driver needs to be told that such an arrangement is taking place114so that it does not touch any capture/port configuration and avoids115conflicting with the debug host's configuration accesses. The only116activity that the driver will perform in this mode is collecting117software traces to the Software Trace Hub (an stm class device). The118user is still responsible for setting up adequate master/channel119mappings that the decoder on the receiving end would recognize.120 121In order to enable the host mode, set the 'host_mode' parameter of the122'intel_th' kernel module to 'y'. None of the virtual output devices123will show up on the intel_th bus. Also, trace configuration and124capture controlling attribute groups of the 'gth' device will not be125exposed. The 'sth' device will operate as usual.126 127Software Sinks128--------------129 130The Memory Storage Unit (MSU) driver provides an in-kernel API for131drivers to register themselves as software sinks for the trace data.132Such drivers can further export the data via other devices, such as133USB device controllers or network cards.134 135The API has two main parts::136 - notifying the software sink that a particular window is full, and137 "locking" that window, that is, making it unavailable for the trace138 collection; when this happens, the MSU driver will automatically139 switch to the next window in the buffer if it is unlocked, or stop140 the trace capture if it's not;141 - tracking the "locked" state of windows and providing a way for the142 software sink driver to notify the MSU driver when a window is143 unlocked and can be used again to collect trace data.144 145An example sink driver, msu-sink illustrates the implementation of a146software sink. Functionally, it simply unlocks windows as soon as they147are full, keeping the MSU running in a circular buffer mode. Unlike the148"multi" mode, it will fill out all the windows in the buffer as opposed149to just the first one. It can be enabled by writing "sink" to the "mode"150file (assuming msu-sink.ko is loaded).151