From 1606f8d8e75bea1992a8cda35df06737b624cbe5 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Sat, 17 Feb 2018 13:39:50 +0800 Subject: trace doc: convert trace/stm.txt to rst format This converts the plain text documentation to reStructuredText format and add it into Sphinx TOC tree. No essential content change. Cc: Steven Rostedt Signed-off-by: Changbin Du Signed-off-by: Jonathan Corbet --- Documentation/trace/index.rst | 1 + Documentation/trace/stm.rst | 123 ++++++++++++++++++++++++++++++++++++++++++ Documentation/trace/stm.txt | 122 ----------------------------------------- 3 files changed, 124 insertions(+), 122 deletions(-) create mode 100644 Documentation/trace/stm.rst delete mode 100644 Documentation/trace/stm.txt (limited to 'Documentation/trace') diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index 02cc56c3eda9..b58c10b04e27 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -20,3 +20,4 @@ Linux Tracing Technologies mmiotrace hwlat_detector intel_th + stm diff --git a/Documentation/trace/stm.rst b/Documentation/trace/stm.rst new file mode 100644 index 000000000000..2c22ddb7fd3e --- /dev/null +++ b/Documentation/trace/stm.rst @@ -0,0 +1,123 @@ +=================== +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, stm_heartbeat or stm_ftrace 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. + +stm_ftrace +========== + +This is another "stm_source" device, once the stm_ftrace has been +linked with an stm device, and if "function" tracer is enabled, +function address and parent function address which Ftrace subsystem +would store into ring buffer will be exported via the stm device at +the same time. + +Currently only Ftrace "function" tracer is supported. + +* [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 diff --git a/Documentation/trace/stm.txt b/Documentation/trace/stm.txt deleted file mode 100644 index 03765750104b..000000000000 --- a/Documentation/trace/stm.txt +++ /dev/null @@ -1,122 +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, stm_heartbeat or stm_ftrace 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. - -stm_ftrace -========== - -This is another "stm_source" device, once the stm_ftrace has been -linked with an stm device, and if "function" tracer is enabled, -function address and parent function address which Ftrace subsystem -would store into ring buffer will be exported via the stm device at -the same time. - -Currently only Ftrace "function" tracer is supported. - -[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 -- cgit v1.2.3