81 lines
3.8 KiB
Plaintext
81 lines
3.8 KiB
Plaintext
|
System Trace Module
|
||
|
|
===================
|
||
|
|
|
||
|
|
System Trace Module (STM) is a device described in MIPI STP specs as
|
||
|
|
STP trace stream generator. STP (System Trace Protocol) is a trace
|
||
|
|
protocol multiplexing data from multiple trace sources, each one of
|
||
|
|
which is assigned a unique pair of master and channel. While some of
|
||
|
|
these masters and channels are statically allocated to certain
|
||
|
|
hardware trace sources, others are available to software. Software
|
||
|
|
trace sources are usually free to pick for themselves any
|
||
|
|
master/channel combination from this pool.
|
||
|
|
|
||
|
|
On the receiving end of this STP stream (the decoder side), trace
|
||
|
|
sources can only be identified by master/channel combination, so in
|
||
|
|
order for the decoder to be able to make sense of the trace that
|
||
|
|
involves multiple trace sources, it needs to be able to map those
|
||
|
|
master/channel pairs to the trace sources that it understands.
|
||
|
|
|
||
|
|
For instance, it is helpful to know that syslog messages come on
|
||
|
|
master 7 channel 15, while arbitrary user applications can use masters
|
||
|
|
48 to 63 and channels 0 to 127.
|
||
|
|
|
||
|
|
To solve this mapping problem, stm class provides a policy management
|
||
|
|
mechanism via configfs, that allows defining rules that map string
|
||
|
|
identifiers to ranges of masters and channels. If these rules (policy)
|
||
|
|
are consistent with what decoder expects, it will be able to properly
|
||
|
|
process the trace data.
|
||
|
|
|
||
|
|
This policy is a tree structure containing rules (policy_node) that
|
||
|
|
have a name (string identifier) and a range of masters and channels
|
||
|
|
associated with it, located in "stp-policy" subsystem directory in
|
||
|
|
configfs. The topmost directory's name (the policy) is formatted as
|
||
|
|
the STM device name to which this policy applies and and arbitrary
|
||
|
|
string identifier separated by a stop. From the examle above, a rule
|
||
|
|
may look like this:
|
||
|
|
|
||
|
|
$ ls /config/stp-policy/dummy_stm.my-policy/user
|
||
|
|
channels masters
|
||
|
|
$ cat /config/stp-policy/dummy_stm.my-policy/user/masters
|
||
|
|
48 63
|
||
|
|
$ cat /config/stp-policy/dummy_stm.my-policy/user/channels
|
||
|
|
0 127
|
||
|
|
|
||
|
|
which means that the master allocation pool for this rule consists of
|
||
|
|
masters 48 through 63 and channel allocation pool has channels 0
|
||
|
|
through 127 in it. Now, any producer (trace source) identifying itself
|
||
|
|
with "user" identification string will be allocated a master and
|
||
|
|
channel from within these ranges.
|
||
|
|
|
||
|
|
These rules can be nested, for example, one can define a rule "dummy"
|
||
|
|
under "user" directory from the example above and this new rule will
|
||
|
|
be used for trace sources with the id string of "user/dummy".
|
||
|
|
|
||
|
|
Trace sources have to open the stm class device's node and write their
|
||
|
|
trace data into its file descriptor. In order to identify themselves
|
||
|
|
to the policy, they need to do a STP_POLICY_ID_SET ioctl on this file
|
||
|
|
descriptor providing their id string. Otherwise, they will be
|
||
|
|
automatically allocated a master/channel pair upon first write to this
|
||
|
|
file descriptor according to the "default" rule of the policy, if such
|
||
|
|
exists.
|
||
|
|
|
||
|
|
Some STM devices may allow direct mapping of the channel mmio regions
|
||
|
|
to userspace for zero-copy writing. One mappable page (in terms of
|
||
|
|
mmu) will usually contain multiple channels' mmios, so the user will
|
||
|
|
need to allocate that many channels to themselves (via the
|
||
|
|
aforementioned ioctl() call) to be able to do this. That is, if your
|
||
|
|
stm device's channel mmio region is 64 bytes and hardware page size is
|
||
|
|
4096 bytes, after a successful STP_POLICY_ID_SET ioctl() call with
|
||
|
|
width==64, you should be able to mmap() one page on this file
|
||
|
|
descriptor and obtain direct access to an mmio region for 64 channels.
|
||
|
|
|
||
|
|
For kernel-based trace sources, there is "stm_source" device
|
||
|
|
class. Devices of this class can be connected and disconnected to/from
|
||
|
|
stm devices at runtime via a sysfs attribute.
|
||
|
|
|
||
|
|
Examples of STM devices are Intel(R) Trace Hub [1] and Coresight STM
|
||
|
|
[2].
|
||
|
|
|
||
|
|
[1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
|
||
|
|
[2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html
|