tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
powerpc/pseries/htmdump: Add documentation for H_HTM debugfs interface
Documentation for HTM (Hardware Trace Macro) debugfs interface
and how it can be used to configure/control the HTM operations.
Signed-off-by: Athira Rajeev <atrajeev@linux.ibm.com>
Tested-by: Venkat Rao Bagalkote <venkat88@linux.ibm.com>
Signed-off-by: Madhavan Srinivasan <maddy@linux.ibm.com>
Link: https://patch.msgid.link/20250420180844.53128-10-atrajeev@linux.ibm.com
authored by
Athira Rajeev
and committed by
Madhavan Srinivasan
ab1456c5
143a2584
+104
+104
Documentation/arch/powerpc/htm.rst
+104
Documentation/arch/powerpc/htm.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
.. _htm:
3
+
4
+
===================================
5
+
HTM (Hardware Trace Macro)
6
+
===================================
7
+
8
+
Athira Rajeev, 2 Mar 2025
9
+
10
+
.. contents::
11
+
:depth: 3
12
+
13
+
14
+
Basic overview
15
+
==============
16
+
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.
23
+
24
+
25
+
HTM debugfs example usage
26
+
=========================
27
+
28
+
.. code-block:: sh
29
+
30
+
# ls /sys/kernel/debug/powerpc/htmdump/
31
+
coreindexonchip htmcaps htmconfigure htmflags htminfo htmsetup
32
+
htmstart htmstatus htmtype nodalchipindex nodeindex trace
33
+
34
+
Details on each file:
35
+
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.
39
+
* htmconfigure: Configure/Deconfigure the HTM. Writing 1 to the file will configure the trace, writing 0 to the file will do deconfigure.
40
+
* 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
43
+
* 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.
46
+
47
+
To see the system processor configuration details:
48
+
49
+
.. code-block:: sh
50
+
51
+
# cat /sys/kernel/debug/powerpc/htmdump/htminfo > htminfo_file
52
+
53
+
The result can be interpreted using hexdump.
54
+
55
+
To collect HTM traces for a partition represented by nodeindex as
56
+
zero, nodalchipindex as 1 and coreindexonchip as 12
57
+
58
+
.. code-block:: sh
59
+
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 )
63
+
64
+
This requires a CEC reboot to get the HTM buffers allocated.
65
+
66
+
.. code-block:: sh
67
+
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
79
+
80
+
Above will set the htmtype and core details, followed by executing respective HTM operation.
81
+
82
+
Read the HTM trace data
83
+
========================
84
+
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.
88
+
89
+
.. code-block:: sh
90
+
91
+
# cat /sys/kernel/debug/powerpc/htmdump/trace > trace_file
92
+
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.
96
+
97
+
Benefits of using HTM debugfs interface
98
+
=======================================
99
+
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.