Documentation/trace/intel_th.txt

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