write in 30M

hc

2024-02-20 ea08eeccae9297f7aabd2ef7f0c2517ac4549acc

 kernel/Documentation/trace/intel_th.rst
..
..
@@ -1,3 +1,5 @@
1
+.. SPDX-License-Identifier: GPL-2.0
2
+
1
3
 =======================
2
4
 Intel(R) Trace Hub (TH)
3
5
 =======================
..
..
@@ -42,7 +44,8 @@
42
44
 
43
45
 MSU can be configured to collect trace data into a system memory
44
46
 buffer, which can later on be read from its device nodes via read() or
45
-mmap() interface.
47
+mmap() interface and directed to a "software sink" driver that will
48
+consume the data and/or relay it further.
46
49
 
47
50
 On the whole, Intel(R) Trace Hub does not require any special
48
51
 userspace software to function; everything can be configured, started
..
..
@@ -55,7 +58,7 @@
55
58
 
56
59
 For each Intel TH device in the system a bus of its own is
57
60
 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)
61
+devices were enumerated. All TH subdevices (devices on intel_th bus)
59
62
 begin with this id: 0-gth, 0-msc0, 0-msc1, 0-pti, 0-sth, which is
60
63
 followed by device's name and an optional index.
61
64
 
..
..
@@ -120,3 +123,28 @@
120
123
 will show up on the intel_th bus. Also, trace configuration and
121
124
 capture controlling attribute groups of the 'gth' device will not be
122
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).