diff options
Diffstat (limited to 'Documentation/trace/stm.txt')
| -rw-r--r-- | Documentation/trace/stm.txt | 111 |
1 files changed, 0 insertions, 111 deletions
diff --git a/Documentation/trace/stm.txt b/Documentation/trace/stm.txt deleted file mode 100644 index 11cff47eecce..000000000000 --- a/Documentation/trace/stm.txt +++ /dev/null @@ -1,111 +0,0 @@ -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. - -Examples of STM devices are Intel(R) Trace Hub [1] and Coresight STM -[2]. - -stm_source -========== - -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 called "stm_source_link" -by writing the name of the desired stm device there, for example: - -$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link - -For examples on how to use stm_source interface in the kernel, refer -to stm_console or stm_heartbeat drivers. - -Each stm_source device will need to assume a master and a range of -channels, depending on how many channels it requires. These are -allocated for the device according to the policy configuration. If -there's a node in the root of the policy directory that matches the -stm_source device's name (for example, "console"), this node will be -used to allocate master and channel numbers. If there's no such policy -node, the stm core will pick the first contiguous chunk of channels -within the first available master. Note that the node must exist -before the stm_source device is connected to its stm device. - -stm_console -=========== - -One implementation of this interface also used in the example above is -the "stm_console" driver, which basically provides a one-way console -for kernel messages over an stm device. - -To configure the master/channel pair that will be assigned to this -console in the STP stream, create a "console" policy entry (see the -beginning of this text on how to do that). When initialized, it will -consume one channel. - -[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 |