intel_th: Add driver infrastructure for Intel(R) Trace Hub devices

What:		/sys/bus/intel_th/devices/<intel_th_id>-<device><id>/active

Date:		June 2015

KernelVersion:	4.3

Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>

Description:	(RW) Writes of 1 or 0 enable or disable trace output to this

		output device. Reads return current status.

What:		/sys/bus/intel_th/devices/<intel_th_id>-msc<msc-id>/port

Date:		June 2015

KernelVersion:	4.3

Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>

Description:	(RO) Port number, corresponding to this output device on the

		switch (GTH).

Intel(R) Trace Hub (TH)

=======================

Overview

--------

Intel(R) Trace Hub (TH) is a set of hardware blocks that produce,

switch and output trace data from multiple hardware and software

sources over several types of trace output ports encoded in System

Trace Protocol (MIPI STPv2) and is intended to perform full system

debugging. For more information on the hardware, see Intel(R) Trace

Hub developer's manual [1].

It consists of trace sources, trace destinations (outputs) and a

switch (Global Trace Hub, GTH). These devices are placed on a bus of

their own ("intel_th"), where they can be discovered and configured

via sysfs attributes.

Currently, the following Intel TH subdevices (blocks) are supported:

  - Software Trace Hub (STH), trace source, which is a System Trace

  Module (STM) device,

  - Memory Storage Unit (MSU), trace output, which allows storing

  trace hub output in system memory,

  - Parallel Trace Interface output (PTI), trace output to an external

  debug host via a PTI port,

  - Global Trace Hub (GTH), which is a switch and a central component

  of Intel(R) Trace Hub architecture.

Common attributes for output devices are described in

Documentation/ABI/testing/sysfs-bus-intel_th-output-devices, the most

notable of them is "active", which enables or disables trace output

into that particular output device.

GTH allows directing different STP masters into different output ports

via its "masters" attribute group. More detailed GTH interface

description is at Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth.

STH registers an stm class device, through which it provides interface

to userspace and kernelspace software trace sources. See

Documentation/tracing/stm.txt for more information on that.

MSU can be configured to collect trace data into a system memory

buffer, which can later on be read from its device nodes via read() or

mmap() interface.

On the whole, Intel(R) Trace Hub does not require any special

userspace software to function; everything can be configured, started

and collected via sysfs attributes, and device nodes.

[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf

Bus and Subdevices

------------------

For each Intel TH device in the system a bus of its own is

created and assigned an id number that reflects the order in which TH

devices were emumerated. All TH subdevices (devices on intel_th bus)

begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is

followed by device's name and an optional index.

Output devices also get a device node in /dev/intel_thN, where N is

the Intel TH device id. For example, MSU's memory buffers, when

allocated, are accessible via /dev/intel_th0/msc{0,1}.

Quick example

-------------

# figure out which GTH port is the first memory controller:

$ cat /sys/bus/intel_th/devices/0-msc0/port

0

# looks like it's port 0, configure master 33 to send data to port 0:

$ echo 0 > /sys/bus/intel_th/devices/0-gth/masters/33

# allocate a 2-windowed multiblock buffer on the first memory

# controller, each with 64 pages:

$ echo multi > /sys/bus/intel_th/devices/0-msc0/mode

$ echo 64,64 > /sys/bus/intel_th/devices/0-msc0/nr_pages

# enable wrapping for this controller, too:

$ echo 1 > /sys/bus/intel_th/devices/0-msc0/wrap

# and enable tracing into this port:

$ echo 1 > /sys/bus/intel_th/devices/0-msc0/active

# .. send data to master 33, see stm.txt for more details ..

# .. wait for traces to pile up ..

# .. and stop the trace:

$ echo 0 > /sys/bus/intel_th/devices/0-msc0/active

# and now you can collect the trace from the device node:

$ cat /dev/intel_th0/msc0 > my_stp_trace

source "drivers/hwtracing/stm/Kconfig"

source "drivers/hwtracing/intel_th/Kconfig"

endmenu

obj-$(CONFIG_RAS)		+= ras/

obj-$(CONFIG_THUNDERBOLT)	+= thunderbolt/

obj-$(CONFIG_CORESIGHT)		+= hwtracing/coresight/

obj-y				+= hwtracing/intel_th/

obj-$(CONFIG_STM)		+= hwtracing/stm/

obj-$(CONFIG_ANDROID)		+= android/

obj-$(CONFIG_NVMEM)		+= nvmem/

config INTEL_TH

	tristate "Intel(R) Trace Hub controller"

	help

	  Intel(R) Trace Hub (TH) is a set of hardware blocks (subdevices) that

	  produce, switch and output trace data from multiple hardware and

	  software sources over several types of trace output ports encoded

	  in System Trace Protocol (MIPI STPv2) and is intended to perform

	  full system debugging.

	  This option enables intel_th bus and common code used by TH

	  subdevices to interact with each other and hardware and for

	  platform glue layers to drive Intel TH devices.

	  Say Y here to enable Intel(R) Trace Hub controller support.

if INTEL_TH

config INTEL_TH_DEBUG

	bool "Intel(R) Trace Hub debugging"

	depends on DEBUG_FS

	help

	  Say Y here to enable debugging.

endif