Documentation/trace/intel_th.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   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).