요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.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 an arbitrary
string identifier separated by a stop. From the example 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 find an appropriate policy node for a given trace source,
several mechanisms can be used. First, a trace source can explicitly
identify itself by calling an STP_POLICY_ID_SET ioctl on the character
device's file descriptor, providing their id string, before they write
any data there. Secondly, if they chose not to perform the explicit
identification (because you may not want to patch existing software
to do this), they can just start writing the data, at which point the
stm core will try to find a policy node with the name matching the
task's name (e.g., "syslogd") and if one exists, it will be used.
Thirdly, if the task name can't be found among the policy nodes, the
catch-all entry "default" will be used, if it exists. This entry also
needs to be created and configured by the system administrator or
whatever tools are taking care of the policy configuration. Finally,
if all the above steps failed, the write() to an stm file descriptor
will return a error (EINVAL).
Previously, if no policy nodes were found for a trace source, the stm
class would silently fall back to allocating the first available
contiguous range of master/channels from the beginning of the device's
master/channel range. The new requirement for a policy node to exist
will help programmers and sysadmins identify gaps in configuration
and have better control over the un-identified sources.
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 use the catch-all entry "default", if one
exists. If neither policy nodes exist, the write() to stm_source_link
will return an error.
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
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
STM과 STP 데이터 경로
1-30이 문서는 GPL-2.0 라이선스를 따릅니다. System Trace Module(STM)은 MIPI STP 명세에서 STP trace stream generator로 정의된 장치입니다.
STP(System Trace Protocol)는 여러 trace source의 데이터를 다중화하는 trace protocol입니다. 각 source에는 고유한 master/channel 쌍이 배정됩니다. 일부 master와 channel은 특정 hardware trace source에 정적으로 할당되고, 나머지는 software가 사용할 수 있습니다. software trace source는 이 pool에서 필요한 master/channel 조합을 고를 수 있습니다.
STP stream의 수신 측인 decoder는 trace source를 master/channel 조합으로만 식별합니다. 따라서 여러 source가 섞인 trace를 해석하려면 decoder가 각 master/channel 쌍을 자신이 이해하는 source에 대응시킬 수 있어야 합니다.
예를 들어 syslog message는 master 7, channel 15로 들어오고 임의의 user application은 master 48~63과 channel 0~127을 사용할 수 있다는 식의 합의가 필요합니다.
이 매핑 문제를 해결하기 위해 stm class는 `configfs`를 통한 policy 관리 기법을 제공합니다. 문자열 식별자를 master와 channel 범위에 대응시키는 규칙을 정의하며, 이 policy가 decoder의 기대와 일치하면 trace data를 올바르게 처리할 수 있습니다.
여러 source의 data가 master/channel 식별자와 함께 STP stream으로 합쳐지고 decoder가 policy에 따라 다시 구분합니다.
.. SPDX-License-Identifier: GPL-2.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.configfs policy tree와 범위 할당
31-55policy는 규칙인 `policy_node`를 담는 tree 구조입니다. 각 node에는 이름인 문자열 식별자와 연관된 master/channel 범위가 있으며, configfs의 `stp-policy` subsystem directory 아래에 놓입니다.
최상위 directory 이름인 policy 이름은 적용 대상 STM device 이름과 임의의 문자열 식별자를 마침표로 구분해 만듭니다. 아래 예에서는 `dummy_stm.my-policy`가 policy이고 `user`가 규칙 이름입니다.
$ 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이 규칙의 master allocation pool은 48~63이고 channel allocation pool은 0~127입니다. 자신을 `user` 식별 문자열로 나타내는 producer, 즉 trace source에는 이 범위 안의 master와 channel이 할당됩니다.
규칙은 중첩할 수 있습니다. 위 `user` directory 아래에 `dummy` 규칙을 만들면 식별 문자열이 `user/dummy`인 trace source에 새 규칙이 적용됩니다.
directory 계층이 source 식별 문자열의 계층과 대응합니다.
문서 예제의 식별자와 할당 pool을 정리합니다.
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 an arbitrary
string identifier separated by a stop. From the example 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 source 식별과 fallback 순서
56-81trace source는 stm class device node를 열고 그 file descriptor에 trace data를 써야 합니다.
적절한 policy node를 찾는 첫 번째 방법은 data를 쓰기 전에 character device file descriptor에 `STP_POLICY_ID_SET` ioctl을 호출하고 source의 id 문자열을 명시적으로 전달하는 것입니다.
두 번째 방법은 기존 software를 수정하고 싶지 않아 명시적 식별을 하지 않는 경우입니다. source가 바로 data 쓰기를 시작하면 stm core는 task 이름, 예를 들어 `syslogd`와 같은 이름의 policy node를 찾아 사용합니다.
세 번째로 task 이름에 맞는 node가 없으면 catch-all 항목인 `default`가 존재할 때 이를 사용합니다. `default` 역시 system administrator 또는 policy 구성 도구가 만들고 설정해야 합니다. 이 모든 단계가 실패하면 stm file descriptor의 `write()`는 `EINVAL` 오류를 반환합니다.
과거에는 policy node를 찾지 못하면 stm class가 device의 master/channel 범위 시작점부터 첫 번째로 사용 가능한 연속 범위를 조용히 할당했습니다. 이제 policy node의 존재를 요구하므로 programmer와 sysadmin이 구성 누락을 발견하고 식별되지 않은 source를 더 잘 통제할 수 있습니다.
source 식별 방법을 명시적인 것부터 catch-all까지 순서대로 적용합니다.
Trace sources have to open the stm class device's node and write their
trace data into its file descriptor.
In order to find an appropriate policy node for a given trace source,
several mechanisms can be used. First, a trace source can explicitly
identify itself by calling an STP_POLICY_ID_SET ioctl on the character
device's file descriptor, providing their id string, before they write
any data there. Secondly, if they chose not to perform the explicit
identification (because you may not want to patch existing software
to do this), they can just start writing the data, at which point the
stm core will try to find a policy node with the name matching the
task's name (e.g., "syslogd") and if one exists, it will be used.
Thirdly, if the task name can't be found among the policy nodes, the
catch-all entry "default" will be used, if it exists. This entry also
needs to be created and configured by the system administrator or
whatever tools are taking care of the policy configuration. Finally,
if all the above steps failed, the write() to an stm file descriptor
will return a error (EINVAL).
Previously, if no policy nodes were found for a trace source, the stm
class would silently fall back to allocating the first available
contiguous range of master/channels from the beginning of the device's
master/channel range. The new requirement for a policy node to exist
will help programmers and sysadmins identify gaps in configuration
and have better control over the un-identified sources.channel MMIO의 zero-copy mapping
82-95일부 STM device는 zero-copy 쓰기를 위해 channel MMIO region을 userspace에 직접 mapping할 수 있습니다. MMU 기준으로 mapping 가능한 한 page에는 보통 여러 channel의 MMIO가 들어가므로, 사용자는 앞서 설명한 ioctl 호출로 그 수만큼의 channel을 자신에게 할당해야 합니다.
예를 들어 channel MMIO region이 64 byte이고 hardware page size가 4096 byte라면, `width==64`로 `STP_POLICY_ID_SET` ioctl을 성공시킨 뒤 이 file descriptor에서 한 page를 `mmap()`하여 64개 channel의 MMIO region에 직접 접근할 수 있습니다. 즉 한 page에 함께 노출되는 모든 channel을 먼저 할당받아야 mapping 경계를 안전하게 유지할 수 있습니다.
STM device의 예로 Intel(R) Trace Hub와 Coresight STM이 있으며, 문서 끝의 참고문헌 [1], [2]에 연결됩니다.
한 hardware page를 구성하는 channel 수와 필요한 할당 폭의 관계입니다.
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].
kernel trace source용 stm_source
96-118kernel 기반 trace source에는 `stm_source` device class가 있습니다. 이 class의 device는 `stm_source_link`라는 sysfs attribute에 원하는 STM device 이름을 써서 runtime에 stm device와 연결하거나 연결을 끊을 수 있습니다.
$ echo dummy_stm.0 > /sys/class/stm_source/console/stm_source_linkkernel에서 stm_source interface를 사용하는 예는 `stm_console`, `stm_heartbeat`, `stm_ftrace` driver에서 볼 수 있습니다.
각 stm_source device는 필요한 channel 수에 따라 master 하나와 channel 범위를 가져야 하며, policy 구성에 따라 할당됩니다. policy directory root에 stm_source device 이름과 같은 node, 예를 들어 `console`이 있으면 그 node로 master와 channel 번호를 할당합니다.
이름이 같은 node가 없으면 stm core는 `default` 항목을 사용합니다. 이름 node와 default가 모두 없으면 `stm_source_link`에 대한 `write()`가 오류를 반환합니다.
sysfs link 요청은 policy node를 거쳐 STM 장치의 master/channel 자원으로 연결됩니다.
문서에서 참조하는 kernel 기반 source driver입니다.
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 use the catch-all entry "default", if one
exists. If neither policy nodes exist, the write() to stm_source_link
will return an error.
stm_console 구성
119-130앞의 예에서도 사용한 `stm_console` driver는 stm_source interface 구현 중 하나이며, STM device를 통해 kernel message를 보내는 단방향 console을 제공합니다.
STP stream에서 이 console에 할당할 master/channel 쌍을 구성하려면 이 문서 앞부분의 절차대로 `console` policy 항목을 만듭니다. 초기화될 때 channel 하나를 소비합니다.
console policy가 channel 하나를 할당하고 kernel message를 STP stream으로 전달합니다.
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와 참고문헌
131-143`stm_ftrace`도 stm_source device입니다. stm_ftrace를 STM device와 연결하고 Ftrace의 `function` tracer를 활성화하면, Ftrace subsystem이 ring buffer에 저장할 function address와 parent function address를 동시에 STM device를 통해 내보냅니다.
현재 지원되는 Ftrace tracer는 `function` tracer뿐입니다.
참고문헌 [1]은 Intel Trace Hub Developer Manual이고, [2]는 Arm CoreSight STM 문서입니다. 원문의 URL을 아래 영어 원문과 원문 보존 블록에 그대로 유지합니다.
function tracer의 주소 정보가 기존 ring buffer와 STM 출력 경로로 함께 전달됩니다.
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
요약·해설
stm.rst:1-143STM은 여러 trace source를 master/channel 쌍으로 다중화합니다. decoder와 producer가 같은 매핑을 사용하도록 configfs policy를 구성하며, kernel source는 stm_source_link로 STM 장치에 연결됩니다.