^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) System Trace Module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) System Trace Module (STM) is a device described in MIPI STP specs as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) STP trace stream generator. STP (System Trace Protocol) is a trace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) protocol multiplexing data from multiple trace sources, each one of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) which is assigned a unique pair of master and channel. While some of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) these masters and channels are statically allocated to certain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) hardware trace sources, others are available to software. Software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) trace sources are usually free to pick for themselves any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) master/channel combination from this pool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) On the receiving end of this STP stream (the decoder side), trace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) sources can only be identified by master/channel combination, so in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) order for the decoder to be able to make sense of the trace that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) involves multiple trace sources, it needs to be able to map those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) master/channel pairs to the trace sources that it understands.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) For instance, it is helpful to know that syslog messages come on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) master 7 channel 15, while arbitrary user applications can use masters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) 48 to 63 and channels 0 to 127.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) To solve this mapping problem, stm class provides a policy management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) mechanism via configfs, that allows defining rules that map string
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) identifiers to ranges of masters and channels. If these rules (policy)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) are consistent with what decoder expects, it will be able to properly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) process the trace data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) This policy is a tree structure containing rules (policy_node) that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) have a name (string identifier) and a range of masters and channels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) associated with it, located in "stp-policy" subsystem directory in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) configfs. The topmost directory's name (the policy) is formatted as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) the STM device name to which this policy applies and an arbitrary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) string identifier separated by a stop. From the example above, a rule
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) may look like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) $ ls /config/stp-policy/dummy_stm.my-policy/user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) channels masters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) $ cat /config/stp-policy/dummy_stm.my-policy/user/masters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 48 63
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) $ cat /config/stp-policy/dummy_stm.my-policy/user/channels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) 0 127
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) which means that the master allocation pool for this rule consists of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) masters 48 through 63 and channel allocation pool has channels 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) through 127 in it. Now, any producer (trace source) identifying itself
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) with "user" identification string will be allocated a master and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) channel from within these ranges.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) These rules can be nested, for example, one can define a rule "dummy"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) under "user" directory from the example above and this new rule will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) be used for trace sources with the id string of "user/dummy".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) Trace sources have to open the stm class device's node and write their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) trace data into its file descriptor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) In order to find an appropriate policy node for a given trace source,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) several mechanisms can be used. First, a trace source can explicitly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) identify itself by calling an STP_POLICY_ID_SET ioctl on the character
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) device's file descriptor, providing their id string, before they write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) any data there. Secondly, if they chose not to perform the explicit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) identification (because you may not want to patch existing software
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) to do this), they can just start writing the data, at which point the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) stm core will try to find a policy node with the name matching the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) task's name (e.g., "syslogd") and if one exists, it will be used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) Thirdly, if the task name can't be found among the policy nodes, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) catch-all entry "default" will be used, if it exists. This entry also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) needs to be created and configured by the system administrator or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) whatever tools are taking care of the policy configuration. Finally,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) if all the above steps failed, the write() to an stm file descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) will return a error (EINVAL).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) Previously, if no policy nodes were found for a trace source, the stm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) class would silently fall back to allocating the first available
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) contiguous range of master/channels from the beginning of the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) master/channel range. The new requirement for a policy node to exist
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) will help programmers and sysadmins identify gaps in configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) and have better control over the un-identified sources.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) Some STM devices may allow direct mapping of the channel mmio regions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) to userspace for zero-copy writing. One mappable page (in terms of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) mmu) will usually contain multiple channels' mmios, so the user will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) need to allocate that many channels to themselves (via the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) aforementioned ioctl() call) to be able to do this. That is, if your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) stm device's channel mmio region is 64 bytes and hardware page size is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) 4096 bytes, after a successful STP_POLICY_ID_SET ioctl() call with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) width==64, you should be able to mmap() one page on this file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) descriptor and obtain direct access to an mmio region for 64 channels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) Examples of STM devices are Intel(R) Trace Hub [1] and Coresight STM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) [2].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) stm_source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) For kernel-based trace sources, there is "stm_source" device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) class. Devices of this class can be connected and disconnected to/from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) stm devices at runtime via a sysfs attribute called "stm_source_link"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) by writing the name of the desired stm device there, for example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) $ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) For examples on how to use stm_source interface in the kernel, refer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) to stm_console, stm_heartbeat or stm_ftrace drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) Each stm_source device will need to assume a master and a range of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) channels, depending on how many channels it requires. These are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) allocated for the device according to the policy configuration. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) there's a node in the root of the policy directory that matches the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) stm_source device's name (for example, "console"), this node will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) used to allocate master and channel numbers. If there's no such policy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) node, the stm core will use the catch-all entry "default", if one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) exists. If neither policy nodes exist, the write() to stm_source_link
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) will return an error.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) stm_console
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) One implementation of this interface also used in the example above is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) the "stm_console" driver, which basically provides a one-way console
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) for kernel messages over an stm device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) To configure the master/channel pair that will be assigned to this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) console in the STP stream, create a "console" policy entry (see the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) beginning of this text on how to do that). When initialized, it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) consume one channel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) stm_ftrace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) This is another "stm_source" device, once the stm_ftrace has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) linked with an stm device, and if "function" tracer is enabled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) function address and parent function address which Ftrace subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) would store into ring buffer will be exported via the stm device at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) the same time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) Currently only Ftrace "function" tracer is supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) * [1] https://software.intel.com/sites/default/files/managed/d3/3c/intel-th-developer-manual.pdf
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) * [2] http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0444b/index.html
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags