|
| 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 |
0 commit comments