Documentation/trace/intel_th.rst

   1 =======================
   2 Intel(R) Trace Hub (TH)
   3 =======================
   4
   5 Overview
   6 --------
   7
   8 Intel(R) Trace Hub (TH) is a set of hardware blocks that produce,
   9 switch and output trace data from multiple hardware and software
  10 sources over several types of trace output ports encoded in System
  11 Trace Protocol (MIPI STPv2) and is intended to perform full system
  12 debugging. For more information on the hardware, see Intel(R) Trace
  13 Hub developer's manual [1].
  14
  15 It consists of trace sources, trace destinations (outputs) and a
  16 switch (Global Trace Hub, GTH). These devices are placed on a bus of
  17 their own ("intel_th"), where they can be discovered and configured
  18 via sysfs attributes.
  19
  20 Currently, the following Intel TH subdevices (blocks) are supported:
  21   - Software Trace Hub (STH), trace source, which is a System Trace
  22     Module (STM) device,
  23   - Memory Storage Unit (MSU), trace output, which allows storing
  24     trace hub output in system memory,
  25   - Parallel Trace Interface output (PTI), trace output to an external
  26     debug host via a PTI port,
  27   - Global Trace Hub (GTH), which is a switch and a central component
  28     of Intel(R) Trace Hub architecture.
  29
  30 Common attributes for output devices are described in
  31 Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most
  32 notable of them is "active", which enables or disables trace output
  33 into that particular output device.
  34
  35 GTH allows directing different STP masters into different output ports
  36 via its "masters" attribute group. More detailed GTH interface
  37 description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth.
  38
  39 STH registers an stm class device, through which it provides interface
  40 to userspace and kernelspace software trace sources. See
  41 Documentation/trace/stm.rst for more information on that.
  42
  43 MSU can be configured to collect trace data into a system memory
  44 buffer, which can later on be read from its device nodes via read() or
  45 mmap() interface.
  46
  47 On the whole, Intel(R) Trace Hub does not require any special
  48 userspace software to function; everything can be configured, started
  49 and collected via sysfs attributes, and device nodes.
  50
  51 [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
  52
  53 Bus and Subdevices
  54 ------------------
  55
  56 For each Intel TH device in the system a bus of its own is
  57 created and assigned an id number that reflects the order in which TH
  58 devices were emumerated. All TH subdevices (devices on intel_th bus)
  59 begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is
  60 followed by device's name and an optional index.
  61
  62 Output devices also get a device node in /dev/intel_thN, where N is
  63 the Intel TH device id. For example, MSU's memory buffers, when
  64 allocated, are accessible via /dev/intel_th0/msc{0,1}.
  65
  66 Quick example
  67 -------------
  68
  69 # figure out which GTH port is the first memory controller::
  70
  71         $ cat /sys/bus/intel_th/devices/0-msc0/port
  72         0
  73
  74 # looks like it's port 0, configure master 33 to send data to port 0::
  75
  76         $ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33
  77
  78 # allocate a 2-windowed multiblock buffer on the first memory
  79 # controller, each with 64 pages::
  80
  81         $ echo multi > /sys/bus/intel_th/devices/0-msc0/mode
  82         $ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages
  83
  84 # enable wrapping for this controller, too::
  85
  86         $ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap
  87
  88 # and enable tracing into this port::
  89
  90         $ echo 1 > /sys/bus/intel_th/devices/0-msc0/active
  91
  92 # .. send data to master 33, see stm.txt for more details ..
  93 # .. wait for traces to pile up ..
  94 # .. and stop the trace::
  95
  96         $ echo 0 > /sys/bus/intel_th/devices/0-msc0/active
  97
  98 # and now you can collect the trace from the device node::
  99
 100         $ cat /dev/intel_th0/msc0 > my_stp_trace
 101
 102 Host Debugger Mode
 103 ------------------
 104
 105 It is possible to configure the Trace Hub and control its trace
 106 capture from a remote debug host, which should be connected via one of
 107 the hardware debugging interfaces, which will then be used to both
 108 control Intel Trace Hub and transfer its trace data to the debug host.
 109
 110 The driver needs to be told that such an arrangement is taking place
 111 so that it does not touch any capture/port configuration and avoids
 112 conflicting with the debug host's configuration accesses. The only
 113 activity that the driver will perform in this mode is collecting
 114 software traces to the Software Trace Hub (an stm class device). The
 115 user is still responsible for setting up adequate master/channel
 116 mappings that the decoder on the receiving end would recognize.
 117
 118 In order to enable the host mode, set the 'host_mode' parameter of the
 119 'intel_th' kernel module to 'y'. None of the virtual output devices
 120 will show up on the intel_th bus. Also, trace configuration and
 121 capture controlling attribute groups of the 'gth' device will not be
 122 exposed. The 'sth' device will operate as usual.