]>
Commit | Line | Data |
---|---|---|
60e6f6d5 AS |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
1606f8d8 | 3 | =================== |
7bd1d409 AS |
4 | System Trace Module |
5 | =================== | |
6 | ||
7 | System Trace Module (STM) is a device described in MIPI STP specs as | |
8 | STP trace stream generator. STP (System Trace Protocol) is a trace | |
9 | protocol multiplexing data from multiple trace sources, each one of | |
10 | which is assigned a unique pair of master and channel. While some of | |
11 | these masters and channels are statically allocated to certain | |
12 | hardware trace sources, others are available to software. Software | |
13 | trace sources are usually free to pick for themselves any | |
14 | master/channel combination from this pool. | |
15 | ||
16 | On the receiving end of this STP stream (the decoder side), trace | |
17 | sources can only be identified by master/channel combination, so in | |
18 | order for the decoder to be able to make sense of the trace that | |
19 | involves multiple trace sources, it needs to be able to map those | |
20 | master/channel pairs to the trace sources that it understands. | |
21 | ||
22 | For instance, it is helpful to know that syslog messages come on | |
23 | master 7 channel 15, while arbitrary user applications can use masters | |
24 | 48 to 63 and channels 0 to 127. | |
25 | ||
26 | To solve this mapping problem, stm class provides a policy management | |
27 | mechanism via configfs, that allows defining rules that map string | |
28 | identifiers to ranges of masters and channels. If these rules (policy) | |
29 | are consistent with what decoder expects, it will be able to properly | |
30 | process the trace data. | |
31 | ||
32 | This policy is a tree structure containing rules (policy_node) that | |
33 | have a name (string identifier) and a range of masters and channels | |
34 | associated with it, located in "stp-policy" subsystem directory in | |
35 | configfs. The topmost directory's name (the policy) is formatted as | |
a13a9956 RD |
36 | the STM device name to which this policy applies and an arbitrary |
37 | string identifier separated by a stop. From the example above, a rule | |
1606f8d8 | 38 | may look like this:: |
7bd1d409 | 39 | |
1606f8d8 CD |
40 | $ ls /config/stp-policy/dummy_stm.my-policy/user |
41 | channels masters | |
42 | $ cat /config/stp-policy/dummy_stm.my-policy/user/masters | |
43 | 48 63 | |
44 | $ cat /config/stp-policy/dummy_stm.my-policy/user/channels | |
45 | 0 127 | |
7bd1d409 AS |
46 | |
47 | which means that the master allocation pool for this rule consists of | |
48 | masters 48 through 63 and channel allocation pool has channels 0 | |
49 | through 127 in it. Now, any producer (trace source) identifying itself | |
50 | with "user" identification string will be allocated a master and | |
51 | channel from within these ranges. | |
52 | ||
53 | These rules can be nested, for example, one can define a rule "dummy" | |
54 | under "user" directory from the example above and this new rule will | |
55 | be used for trace sources with the id string of "user/dummy". | |
56 | ||
57 | Trace sources have to open the stm class device's node and write their | |
3ef23037 AS |
58 | trace data into its file descriptor. |
59 | ||
60 | In order to find an appropriate policy node for a given trace source, | |
61 | several mechanisms can be used. First, a trace source can explicitly | |
62 | identify itself by calling an STP_POLICY_ID_SET ioctl on the character | |
63 | device's file descriptor, providing their id string, before they write | |
64 | any data there. Secondly, if they chose not to perform the explicit | |
65 | identification (because you may not want to patch existing software | |
66 | to do this), they can just start writing the data, at which point the | |
67 | stm core will try to find a policy node with the name matching the | |
68 | task's name (e.g., "syslogd") and if one exists, it will be used. | |
69 | Thirdly, if the task name can't be found among the policy nodes, the | |
70 | catch-all entry "default" will be used, if it exists. This entry also | |
71 | needs to be created and configured by the system administrator or | |
72 | whatever tools are taking care of the policy configuration. Finally, | |
73 | if all the above steps failed, the write() to an stm file descriptor | |
74 | will return a error (EINVAL). | |
75 | ||
76 | Previously, if no policy nodes were found for a trace source, the stm | |
77 | class would silently fall back to allocating the first available | |
78 | contiguous range of master/channels from the beginning of the device's | |
79 | master/channel range. The new requirement for a policy node to exist | |
80 | will help programmers and sysadmins identify gaps in configuration | |
81 | and have better control over the un-identified sources. | |
7bd1d409 AS |
82 | |
83 | Some STM devices may allow direct mapping of the channel mmio regions | |
84 | to userspace for zero-copy writing. One mappable page (in terms of | |
85 | mmu) will usually contain multiple channels' mmios, so the user will | |
86 | need to allocate that many channels to themselves (via the | |
87 | aforementioned ioctl() call) to be able to do this. That is, if your | |
88 | stm device's channel mmio region is 64 bytes and hardware page size is | |
89 | 4096 bytes, after a successful STP_POLICY_ID_SET ioctl() call with | |
90 | width==64, you should be able to mmap() one page on this file | |
91 | descriptor and obtain direct access to an mmio region for 64 channels. | |
92 | ||
bd566189 AS |
93 | Examples of STM devices are Intel(R) Trace Hub [1] and Coresight STM |
94 | [2]. | |
95 | ||
96 | stm_source | |
97 | ========== | |
98 | ||
7bd1d409 AS |
99 | For kernel-based trace sources, there is "stm_source" device |
100 | class. Devices of this class can be connected and disconnected to/from | |
bd566189 | 101 | stm devices at runtime via a sysfs attribute called "stm_source_link" |
1606f8d8 | 102 | by writing the name of the desired stm device there, for example:: |
7bd1d409 | 103 | |
1606f8d8 | 104 | $ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link |
bd566189 AS |
105 | |
106 | For examples on how to use stm_source interface in the kernel, refer | |
39fccd2f | 107 | to stm_console, stm_heartbeat or stm_ftrace drivers. |
bd566189 | 108 | |
b29f6d3e AS |
109 | Each stm_source device will need to assume a master and a range of |
110 | channels, depending on how many channels it requires. These are | |
111 | allocated for the device according to the policy configuration. If | |
112 | there's a node in the root of the policy directory that matches the | |
113 | stm_source device's name (for example, "console"), this node will be | |
114 | used to allocate master and channel numbers. If there's no such policy | |
3ef23037 AS |
115 | node, the stm core will use the catch-all entry "default", if one |
116 | exists. If neither policy nodes exist, the write() to stm_source_link | |
117 | will return an error. | |
b29f6d3e | 118 | |
bd566189 AS |
119 | stm_console |
120 | =========== | |
121 | ||
122 | One implementation of this interface also used in the example above is | |
123 | the "stm_console" driver, which basically provides a one-way console | |
124 | for kernel messages over an stm device. | |
125 | ||
126 | To configure the master/channel pair that will be assigned to this | |
127 | console in the STP stream, create a "console" policy entry (see the | |
128 | beginning of this text on how to do that). When initialized, it will | |
129 | consume one channel. | |
7bd1d409 | 130 | |
39fccd2f CZ |
131 | stm_ftrace |
132 | ========== | |
133 | ||
134 | This is another "stm_source" device, once the stm_ftrace has been | |
135 | linked with an stm device, and if "function" tracer is enabled, | |
136 | function address and parent function address which Ftrace subsystem | |
137 | would store into ring buffer will be exported via the stm device at | |
138 | the same time. | |
139 | ||
140 | Currently only Ftrace "function" tracer is supported. | |
141 | ||
1606f8d8 CD |
142 | * [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf |
143 | * [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html |