]>
Commit | Line | Data |
---|---|---|
7bd1d409 AS |
1 | System Trace Module |
2 | =================== | |
3 | ||
4 | System Trace Module (STM) is a device described in MIPI STP specs as | |
5 | STP trace stream generator. STP (System Trace Protocol) is a trace | |
6 | protocol multiplexing data from multiple trace sources, each one of | |
7 | which is assigned a unique pair of master and channel. While some of | |
8 | these masters and channels are statically allocated to certain | |
9 | hardware trace sources, others are available to software. Software | |
10 | trace sources are usually free to pick for themselves any | |
11 | master/channel combination from this pool. | |
12 | ||
13 | On the receiving end of this STP stream (the decoder side), trace | |
14 | sources can only be identified by master/channel combination, so in | |
15 | order for the decoder to be able to make sense of the trace that | |
16 | involves multiple trace sources, it needs to be able to map those | |
17 | master/channel pairs to the trace sources that it understands. | |
18 | ||
19 | For instance, it is helpful to know that syslog messages come on | |
20 | master 7 channel 15, while arbitrary user applications can use masters | |
21 | 48 to 63 and channels 0 to 127. | |
22 | ||
23 | To solve this mapping problem, stm class provides a policy management | |
24 | mechanism via configfs, that allows defining rules that map string | |
25 | identifiers to ranges of masters and channels. If these rules (policy) | |
26 | are consistent with what decoder expects, it will be able to properly | |
27 | process the trace data. | |
28 | ||
29 | This policy is a tree structure containing rules (policy_node) that | |
30 | have a name (string identifier) and a range of masters and channels | |
31 | associated with it, located in "stp-policy" subsystem directory in | |
32 | configfs. The topmost directory's name (the policy) is formatted as | |
33 | the STM device name to which this policy applies and and arbitrary | |
34 | string identifier separated by a stop. From the examle above, a rule | |
35 | may look like this: | |
36 | ||
37 | $ ls /config/stp-policy/dummy_stm.my-policy/user | |
38 | channels masters | |
39 | $ cat /config/stp-policy/dummy_stm.my-policy/user/masters | |
40 | 48 63 | |
41 | $ cat /config/stp-policy/dummy_stm.my-policy/user/channels | |
42 | 0 127 | |
43 | ||
44 | which means that the master allocation pool for this rule consists of | |
45 | masters 48 through 63 and channel allocation pool has channels 0 | |
46 | through 127 in it. Now, any producer (trace source) identifying itself | |
47 | with "user" identification string will be allocated a master and | |
48 | channel from within these ranges. | |
49 | ||
50 | These rules can be nested, for example, one can define a rule "dummy" | |
51 | under "user" directory from the example above and this new rule will | |
52 | be used for trace sources with the id string of "user/dummy". | |
53 | ||
54 | Trace sources have to open the stm class device's node and write their | |
55 | trace data into its file descriptor. In order to identify themselves | |
56 | to the policy, they need to do a STP_POLICY_ID_SET ioctl on this file | |
57 | descriptor providing their id string. Otherwise, they will be | |
58 | automatically allocated a master/channel pair upon first write to this | |
59 | file descriptor according to the "default" rule of the policy, if such | |
60 | exists. | |
61 | ||
62 | Some STM devices may allow direct mapping of the channel mmio regions | |
63 | to userspace for zero-copy writing. One mappable page (in terms of | |
64 | mmu) will usually contain multiple channels' mmios, so the user will | |
65 | need to allocate that many channels to themselves (via the | |
66 | aforementioned ioctl() call) to be able to do this. That is, if your | |
67 | stm device's channel mmio region is 64 bytes and hardware page size is | |
68 | 4096 bytes, after a successful STP_POLICY_ID_SET ioctl() call with | |
69 | width==64, you should be able to mmap() one page on this file | |
70 | descriptor and obtain direct access to an mmio region for 64 channels. | |
71 | ||
72 | For kernel-based trace sources, there is "stm_source" device | |
73 | class. Devices of this class can be connected and disconnected to/from | |
74 | stm devices at runtime via a sysfs attribute. | |
75 | ||
76 | Examples of STM devices are Intel(R) Trace Hub [1] and Coresight STM | |
77 | [2]. | |
78 | ||
79 | [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf | |
80 | [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html |