1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===================
4 System Trace Module
5 ===================
6
7 System Trace Module (STM) is a device describe
8 STP trace stream generator. STP (System Trace
9 protocol multiplexing data from multiple trace
10 which is assigned a unique pair of master and
11 these masters and channels are statically allo
12 hardware trace sources, others are available t
13 trace sources are usually free to pick for the
14 master/channel combination from this pool.
15
16 On the receiving end of this STP stream (the d
17 sources can only be identified by master/chann
18 order for the decoder to be able to make sense
19 involves multiple trace sources, it needs to b
20 master/channel pairs to the trace sources that
21
22 For instance, it is helpful to know that syslo
23 master 7 channel 15, while arbitrary user appl
24 48 to 63 and channels 0 to 127.
25
26 To solve this mapping problem, stm class provi
27 mechanism via configfs, that allows defining r
28 identifiers to ranges of masters and channels.
29 are consistent with what decoder expects, it w
30 process the trace data.
31
32 This policy is a tree structure containing rul
33 have a name (string identifier) and a range of
34 associated with it, located in "stp-policy" su
35 configfs. The topmost directory's name (the po
36 the STM device name to which this policy appli
37 string identifier separated by a stop. From th
38 may look like this::
39
40 $ ls /config/stp-policy/dummy_stm.my-p
41 channels masters
42 $ cat /config/stp-policy/dummy_stm.my-
43 48 63
44 $ cat /config/stp-policy/dummy_stm.my-
45 0 127
46
47 which means that the master allocation pool fo
48 masters 48 through 63 and channel allocation p
49 through 127 in it. Now, any producer (trace so
50 with "user" identification string will be allo
51 channel from within these ranges.
52
53 These rules can be nested, for example, one ca
54 under "user" directory from the example above
55 be used for trace sources with the id string o
56
57 Trace sources have to open the stm class devic
58 trace data into its file descriptor.
59
60 In order to find an appropriate policy node fo
61 several mechanisms can be used. First, a trace
62 identify itself by calling an STP_POLICY_ID_SE
63 device's file descriptor, providing their id s
64 any data there. Secondly, if they chose not to
65 identification (because you may not want to pa
66 to do this), they can just start writing the d
67 stm core will try to find a policy node with t
68 task's name (e.g., "syslogd") and if one exist
69 Thirdly, if the task name can't be found among
70 catch-all entry "default" will be used, if it
71 needs to be created and configured by the syst
72 whatever tools are taking care of the policy c
73 if all the above steps failed, the write() to
74 will return a error (EINVAL).
75
76 Previously, if no policy nodes were found for
77 class would silently fall back to allocating t
78 contiguous range of master/channels from the b
79 master/channel range. The new requirement for
80 will help programmers and sysadmins identify g
81 and have better control over the un-identified
82
83 Some STM devices may allow direct mapping of t
84 to userspace for zero-copy writing. One mappab
85 mmu) will usually contain multiple channels' m
86 need to allocate that many channels to themsel
87 aforementioned ioctl() call) to be able to do
88 stm device's channel mmio region is 64 bytes a
89 4096 bytes, after a successful STP_POLICY_ID_S
90 width==64, you should be able to mmap() one pa
91 descriptor and obtain direct access to an mmio
92
93 Examples of STM devices are Intel(R) Trace Hub
94 [2].
95
96 stm_source
97 ==========
98
99 For kernel-based trace sources, there is "stm_
100 class. Devices of this class can be connected
101 stm devices at runtime via a sysfs attribute c
102 by writing the name of the desired stm device
103
104 $ echo dummy_stm.0 > /sys/class/stm_so
105
106 For examples on how to use stm_source interfac
107 to stm_console, stm_heartbeat or stm_ftrace dr
108
109 Each stm_source device will need to assume a m
110 channels, depending on how many channels it re
111 allocated for the device according to the poli
112 there's a node in the root of the policy direc
113 stm_source device's name (for example, "consol
114 used to allocate master and channel numbers. I
115 node, the stm core will use the catch-all entr
116 exists. If neither policy nodes exist, the wri
117 will return an error.
118
119 stm_console
120 ===========
121
122 One implementation of this interface also used
123 the "stm_console" driver, which basically prov
124 for kernel messages over an stm device.
125
126 To configure the master/channel pair that will
127 console in the STP stream, create a "console"
128 beginning of this text on how to do that). Whe
129 consume one channel.
130
131 stm_ftrace
132 ==========
133
134 This is another "stm_source" device, once the
135 linked with an stm device, and if "function" t
136 function address and parent function address w
137 would store into ring buffer will be exported
138 the same time.
139
140 Currently only Ftrace "function" tracer is sup
141
142 * [1] https://software.intel.com/sites/default
143 * [2] http://infocenter.arm.com/help/index.jsp
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.