HTM (Hardware Trace Macro) | Linux 6.18.37

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

htm.rst:1-104

`htmdump` debugfs는 buffer allocation과 target core 선택부터 configure/start/stop, trace export까지 HTM lifecycle을 제공합니다. Buffer size 변경에는 CEC reboot가 필요합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기

1 .. SPDX-License-Identifier: GPL-2.0

2 .. _htm:

4 ===================================

5 HTM (Hardware Trace Macro)

6 ===================================

8 Athira Rajeev, 2 Mar 2025

10 .. contents::

11 :depth: 3

14 Basic overview

15 ==============

17 H_HTM is used as an interface for executing Hardware Trace Macro (HTM)

18 functions, including setup, configuration, control and dumping of the HTM data.

19 For using HTM, it is required to setup HTM buffers and HTM operations can

20 be controlled using the H_HTM hcall. The hcall can be invoked for any core/chip

21 of the system from within a partition itself. To use this feature, a debugfs

22 folder called "htmdump" is present under /sys/kernel/debug/powerpc.

25 HTM debugfs example usage

26 =========================

28 .. code-block:: sh

30 # ls /sys/kernel/debug/powerpc/htmdump/

31 coreindexonchip htmcaps htmconfigure htmflags htminfo htmsetup

32 htmstart htmstatus htmtype nodalchipindex nodeindex trace

34 Details on each file:

36 * nodeindex, nodalchipindex, coreindexonchip specifies which partition to configure the HTM for.

37 * htmtype: specifies the type of HTM. Supported target is hardwareTarget.

38 * trace: is to read the HTM data.

* htmconfigure: Configure/Deconfigure the HTM. Writing 1 to the file will configure the trace, writing 0 to the file will do deconfigure.

* htmstart: start/Stop the HTM. Writing 1 to the file will start the tracing, writing 0 to the file will stop the tracing.

41 * htmstatus: get the status of HTM. This is needed to understand the HTM state after each operation.

42 * htmsetup: set the HTM buffer size. Size of HTM buffer is in power of 2

* htminfo: provides the system processor configuration details. This is needed to understand the appropriate values for nodeindex, nodalchipindex, coreindexonchip.

44 * htmcaps : provides the HTM capabilities like minimum/maximum buffer size, what kind of tracing the HTM supports etc.

45 * htmflags : allows to pass flags to hcall. Currently supports controlling the wrapping of HTM buffer.

47 To see the system processor configuration details:

49 .. code-block:: sh

51 # cat /sys/kernel/debug/powerpc/htmdump/htminfo > htminfo_file

53 The result can be interpreted using hexdump.

55 To collect HTM traces for a partition represented by nodeindex as

56 zero, nodalchipindex as 1 and coreindexonchip as 12

58 .. code-block:: sh

60 # cd /sys/kernel/debug/powerpc/htmdump/

61 # echo 2 > htmtype

62 # echo 33 > htmsetup ( sets 8GB memory for HTM buffer, number is size in power of 2 )

64 This requires a CEC reboot to get the HTM buffers allocated.

66 .. code-block:: sh

68 # cd /sys/kernel/debug/powerpc/htmdump/

69 # echo 2 > htmtype

70 # echo 0 > nodeindex

71 # echo 1 > nodalchipindex

72 # echo 12 > coreindexonchip

73 # echo 1 > htmflags # to set noWrap for HTM buffers

74 # echo 1 > htmconfigure # Configure the HTM

75 # echo 1 > htmstart # Start the HTM

76 # echo 0 > htmstart # Stop the HTM

77 # echo 0 > htmconfigure # Deconfigure the HTM

78 # cat htmstatus # Dump the status of HTM entries as data

80 Above will set the htmtype and core details, followed by executing respective HTM operation.

82 Read the HTM trace data

83 ========================

85 After starting the trace collection, run the workload

86 of interest. Stop the trace collection after required period

87 of time, and read the trace file.

89 .. code-block:: sh

91 # cat /sys/kernel/debug/powerpc/htmdump/trace > trace_file

93 This trace file will contain the relevant instruction traces

94 collected during the workload execution. And can be used as

95 input file for trace decoders to understand data.

97 Benefits of using HTM debugfs interface

98 =======================================

100 It is now possible to collect traces for a particular core/chip

101 from within any partition of the system and decode it. Through

102 this enablement, a small partition can be dedicated to collect the

103 trace data and analyze to provide important information for Performance

104 analysis, Software tuning, or Hardware debug.

105

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Hardware Trace Macro 문서

1-13

SPDX-License-Identifier는 GPL-2.0입니다. 저자는 Athira Rajeev이며 문서 날짜는 2025년 3월 2일입니다. 목차 깊이는 3입니다.

`H_HTM` interface

14-23

`H_HTM`은 Hardware Trace Macro (`HTM`)의 setup, configuration, control, data dump function을 실행하는 interface입니다. HTM buffer를 먼저 설정하고 `H_HTM` hcall로 operation을 제어합니다.

Partition 내부에서 system의 어떤 core/chip에도 hcall을 invoke할 수 있습니다. Debugfs interface는 `/sys/kernel/debug/powerpc/htmdump`에 있습니다.

`htmdump` debugfs file

24-46

#  ls /sys/kernel/debug/powerpc/htmdump/
coreindexonchip  htmcaps  htmconfigure  htmflags  htminfo  htmsetup
htmstart  htmstatus  htmtype  nodalchipindex  nodeindex  trace

File	기능
`nodeindex`, `nodalchipindex`, `coreindexonchip`	HTM을 configure할 target partition/core 위치 지정
`htmtype`	HTM type 지정. 지원 target은 `hardwareTarget`
`trace`	HTM trace data read
`htmconfigure`	`1` write로 configure, `0` write로 deconfigure
`htmstart`	`1` write로 trace start, `0` write로 stop
`htmstatus`	각 operation 뒤 HTM state 확인
`htmsetup`	HTM buffer size 설정. Size 값은 2의 exponent
`htminfo`	적절한 index를 고를 system processor configuration 정보
`htmcaps`	최소/최대 buffer size와 지원 trace 종류 등 capability
`htmflags`	Hcall flag 전달. 현재 HTM buffer wrapping 제어 지원

Processor 정보와 buffer setup

47-64

System processor configuration은 다음 command로 저장합니다.

# cat /sys/kernel/debug/powerpc/htmdump/htminfo > htminfo_file

결과는 `hexdump`로 해석할 수 있습니다.

`nodeindex=0`, `nodalchipindex=1`, `coreindexonchip=12`인 partition trace를 준비하는 첫 단계는 HTM type과 buffer size를 설정하는 것입니다.

# cd /sys/kernel/debug/powerpc/htmdump/
# echo 2 > htmtype
# echo 33 > htmsetup ( sets 8GB memory for HTM buffer, number is size in power of 2 )

`htmsetup` 값 33은 2의 33제곱 byte, 즉 8GB HTM buffer를 뜻합니다. Buffer allocation을 적용하려면 CEC reboot가 필요합니다.

HTM configure/start/stop sequence

65-81

# cd /sys/kernel/debug/powerpc/htmdump/
# echo 2 > htmtype
# echo 0 > nodeindex
# echo 1 > nodalchipindex
# echo 12 > coreindexonchip
# echo 1 > htmflags     # to set noWrap for HTM buffers
# echo 1 > htmconfigure # Configure the HTM
# echo 1 > htmstart     # Start the HTM
# echo 0 > htmstart     # Stop the HTM
# echo 0 > htmconfigure # Deconfigure the HTM
# cat htmstatus         # Dump the status of HTM entries as data

이 sequence는 `htmtype`과 core location을 설정하고 no-wrap flag를 적용한 뒤 configure, start, stop, deconfigure를 차례로 실행하고 마지막 상태를 dump합니다.

HTM trace operation

Type/core index 설정`htmflags``htmconfigure=1``htmstart=1`Workload`htmstart=0``htmconfigure=0``htmstatus`

Target 선택과 buffer setup 뒤 trace lifecycle을 순서대로 실행합니다.

HTM trace data 읽기

82-96

Trace collection을 시작한 뒤 관심 workload를 실행하고 필요한 시간이 지나면 collection을 stop한 다음 trace file을 읽습니다.

# cat /sys/kernel/debug/powerpc/htmdump/trace > trace_file

Output은 workload 실행 중 수집한 관련 instruction trace를 담으며 trace decoder의 input으로 사용해 data를 해석할 수 있습니다.

Debugfs HTM의 이점

97-104

System의 어떤 partition에서도 특정 core/chip trace를 수집하고 decode할 수 있습니다. 작은 partition을 trace 수집/분석 전용으로 두어 performance analysis, software tuning, hardware debug에 필요한 정보를 제공할 수 있습니다.