About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / trace / intel_th.txt




Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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/trace/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
100	
101	Host Debugger Mode
102	==================
103	
104	It is possible to configure the Trace Hub and control its trace
105	capture from a remote debug host, which should be connected via one of
106	the hardware debugging interfaces, which will then be used to both
107	control Intel Trace Hub and transfer its trace data to the debug host.
108	
109	The driver needs to be told that such an arrangement is taking place
110	so that it does not touch any capture/port configuration and avoids
111	conflicting with the debug host's configuration accesses. The only
112	activity that the driver will perform in this mode is collecting
113	software traces to the Software Trace Hub (an stm class device). The
114	user is still responsible for setting up adequate master/channel
115	mappings that the decoder on the receiving end would recognize.
116	
117	In order to enable the host mode, set the 'host_mode' parameter of the
118	'intel_th' kernel module to 'y'. None of the virtual output devices
119	will show up on the intel_th bus. Also, trace configuration and
120	capture controlling attribute groups of the 'gth' device will not be
121	exposed. The 'sth' device will operate as usual.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.