요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
GPCI access capabilities와 versions
sysfs-bus-event_source-devices-hv_gpci:32-75Other-guest·physical-domain counter access, GA·EXPANDED·LAB events 지원 여부와 hypervisor/kernel GPCI interface versions를 제공합니다.
GPCI HCALL CPU mask
sysfs-bus-event_source-devices-hv_gpci:77-82cpumask는 hv-gpci event counter data를 가져오는 HCALLs를 수행하도록 지정된 CPUs를 나타냅니다.
POWER10+ topology HCALL interfaces
sysfs-bus-event_source-devices-hv_gpci:84-242다섯 admin-only files는 H_GET_PERF_COUNTER_INFO request로 processor topology, configuration과 affinity domains를 제공하며 firmware-specific decoding을 요구합니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
What: /sys/bus/event_source/devices/hv_gpci/format
2
Date: September 2020
3
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
4
Description: Read-only. Attribute group to describe the magic bits
5
that go into perf_event_attr.config for a particular pmu.
6
(See ABI/testing/sysfs-bus-event_source-devices-format).
8
Each attribute under this group defines a bit range of the
9
perf_event_attr.config. All supported attributes are listed
10
below::
12
counter_info_version = "config:16-23"
13
length = "config:24-31"
14
partition_id = "config:32-63"
15
request = "config:0-31"
16
sibling_part_id = "config:32-63"
17
hw_chip_id = "config:32-63"
18
offset = "config:32-63"
19
phys_processor_idx = "config:32-63"
20
secondary_index = "config:0-15"
21
starting_index = "config:32-63"
23
For example::
25
processor_core_utilization_instructions_completed = "request=0x94,
26
phys_processor_idx=?,counter_info_version=0x8,
27
length=8,offset=0x18"
29
In this event, '?' after phys_processor_idx specifies this value
30
this value will be provided by user while running this event.
32
What: /sys/bus/event_source/devices/hv_gpci/interface/collect_privileged
33
Date: February 2014
34
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
35
Description:
36
'0' if the hypervisor is configured to forbid access to event
37
counters being accumulated by other guests and to physical
38
domain event counters.
40
'1' if that access is allowed.
42
What: /sys/bus/event_source/devices/hv_gpci/interface/ga
43
Date: February 2014
44
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
45
Description:
46
0 or 1. Indicates whether we have access to "GA" events (listed
47
in arch/powerpc/perf/hv-gpci.h).
49
What: /sys/bus/event_source/devices/hv_gpci/interface/expanded
50
Date: February 2014
51
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
52
Description:
53
0 or 1. Indicates whether we have access to "EXPANDED" events (listed
54
in arch/powerpc/perf/hv-gpci.h).
56
What: /sys/bus/event_source/devices/hv_gpci/interface/lab
57
Date: February 2014
58
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
59
Description:
60
0 or 1. Indicates whether we have access to "LAB" events (listed
61
in arch/powerpc/perf/hv-gpci.h).
63
What: /sys/bus/event_source/devices/hv_gpci/interface/version
64
Date: February 2014
65
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
66
Description:
67
A number indicating the version of the gpci interface that the
68
hypervisor reports supporting.
70
What: /sys/bus/event_source/devices/hv_gpci/interface/kernel_version
71
Date: February 2014
72
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
73
Description:
74
A number indicating the latest version of the gpci interface
75
that the kernel is aware of.
77
What: /sys/devices/hv_gpci/cpumask
78
Date: October 2020
79
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
80
Description: read only
81
This sysfs file exposes the cpumask which is designated to make
82
HCALLs to retrieve hv-gpci pmu event counter data.
84
What: /sys/devices/hv_gpci/interface/processor_bus_topology
85
Date: July 2023
86
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
87
Description: admin read only
88
This sysfs file exposes the system topology information by making HCALL
89
H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
90
PROCESSOR_BUS_TOPOLOGY(0xD0).
92
* This sysfs file will be created only for power10 and above platforms.
94
* User needs root privileges to read data from this sysfs file.
96
* This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
97
"H_AUTHORITY" or "H_PARAMETER" as the return type.
99
HCALL with return error type "H_AUTHORITY" can be resolved during
100
runtime by setting "Enable Performance Information Collection" option.
102
* The end user reading this sysfs file must decode the content as per
103
underlying platform/firmware.
105
Possible error codes while reading this sysfs file:
107
* "-EPERM" : Partition is not permitted to retrieve performance information,
108
required to set "Enable Performance Information Collection" option.
110
* "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
111
or because of some hardware error. Refer to getPerfCountInfo documentation for
112
more information.
114
* "-EFBIG" : System information exceeds PAGE_SIZE.
116
What: /sys/devices/hv_gpci/interface/processor_config
117
Date: July 2023
118
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
119
Description: admin read only
120
This sysfs file exposes the system topology information by making HCALL
121
H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
122
PROCESSOR_CONFIG(0x90).
124
* This sysfs file will be created only for power10 and above platforms.
126
* User needs root privileges to read data from this sysfs file.
128
* This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
129
"H_AUTHORITY" or "H_PARAMETER" as the return type.
131
HCALL with return error type "H_AUTHORITY" can be resolved during
132
runtime by setting "Enable Performance Information Collection" option.
134
* The end user reading this sysfs file must decode the content as per
135
underlying platform/firmware.
137
Possible error codes while reading this sysfs file:
139
* "-EPERM" : Partition is not permitted to retrieve performance information,
140
required to set "Enable Performance Information Collection" option.
142
* "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
143
or because of some hardware error. Refer to getPerfCountInfo documentation for
144
more information.
146
* "-EFBIG" : System information exceeds PAGE_SIZE.
148
What: /sys/devices/hv_gpci/interface/affinity_domain_via_virtual_processor
149
Date: July 2023
150
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
151
Description: admin read only
152
This sysfs file exposes the system topology information by making HCALL
153
H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
154
AFFINITY_DOMAIN_INFORMATION_BY_VIRTUAL_PROCESSOR(0xA0).
156
* This sysfs file will be created only for power10 and above platforms.
158
* User needs root privileges to read data from this sysfs file.
160
* This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
161
"H_AUTHORITY" or "H_PARAMETER" as the return type.
163
HCALL with return error type "H_AUTHORITY" can be resolved during
164
runtime by setting "Enable Performance Information Collection" option.
166
* The end user reading this sysfs file must decode the content as per
167
underlying platform/firmware.
169
Possible error codes while reading this sysfs file:
171
* "-EPERM" : Partition is not permitted to retrieve performance information,
172
required to set "Enable Performance Information Collection" option.
174
* "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
175
or because of some hardware error. Refer to getPerfCountInfo documentation for
176
more information.
178
* "-EFBIG" : System information exceeds PAGE_SIZE.
180
What: /sys/devices/hv_gpci/interface/affinity_domain_via_domain
181
Date: July 2023
182
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
183
Description: admin read only
184
This sysfs file exposes the system topology information by making HCALL
185
H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
186
AFFINITY_DOMAIN_INFORMATION_BY_DOMAIN(0xB0).
188
* This sysfs file will be created only for power10 and above platforms.
190
* User needs root privileges to read data from this sysfs file.
192
* This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
193
"H_AUTHORITY" or "H_PARAMETER" as the return type.
195
HCALL with return error type "H_AUTHORITY" can be resolved during
196
runtime by setting "Enable Performance Information Collection" option.
198
* The end user reading this sysfs file must decode the content as per
199
underlying platform/firmware.
201
Possible error codes while reading this sysfs file:
203
* "-EPERM" : Partition is not permitted to retrieve performance information,
204
required to set "Enable Performance Information Collection" option.
206
* "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
207
or because of some hardware error. Refer to getPerfCountInfo documentation for
208
more information.
210
* "-EFBIG" : System information exceeds PAGE_SIZE.
212
What: /sys/devices/hv_gpci/interface/affinity_domain_via_partition
213
Date: July 2023
214
Contact: Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org>
215
Description: admin read only
216
This sysfs file exposes the system topology information by making HCALL
217
H_GET_PERF_COUNTER_INFO. The HCALL is made with counter request value
218
AFFINITY_DOMAIN_INFORMATION_BY_PARTITION(0xB1).
220
* This sysfs file will be created only for power10 and above platforms.
222
* User needs root privileges to read data from this sysfs file.
224
* This sysfs file will be created, only when the HCALL returns "H_SUCCESS",
225
"H_AUTHORITY" or "H_PARAMETER" as the return type.
227
HCALL with return error type "H_AUTHORITY" can be resolved during
228
runtime by setting "Enable Performance Information Collection" option.
230
* The end user reading this sysfs file must decode the content as per
231
underlying platform/firmware.
233
Possible error codes while reading this sysfs file:
235
* "-EPERM" : Partition is not permitted to retrieve performance information,
236
required to set "Enable Performance Information Collection" option.
238
* "-EIO" : Can't retrieve system information because of invalid buffer length/invalid address
239
or because of some hardware error. Refer to getPerfCountInfo documentation for
240
more information.
242
* "-EFBIG" : System information exceeds PAGE_SIZE.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
hv_gpci perf event format
1-30| 항목 | 전문 번역 |
|---|---|
| What | /sys/bus/event_source/devices/hv_gpci/format |
| Date | 2020년 9월 |
| Contact | Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
| Description | Read-only입니다. 특정 PMU의 perf_event_attr.config에 들어가는 magic bits를 설명하는 attribute group입니다. ABI/testing/sysfs-bus-event_source-devices-format을 참조합니다. 이 group 아래의 각 attribute는 perf_event_attr.config bit range를 정의합니다. |
| Attribute | Bit range |
|---|---|
| counter_info_version | config:16-23 |
| length | config:24-31 |
| partition_id | config:32-63 |
| request | config:0-31 |
| sibling_part_id | config:32-63 |
| hw_chip_id | config:32-63 |
| offset | config:32-63 |
| phys_processor_idx | config:32-63 |
| secondary_index | config:0-15 |
| starting_index | config:32-63 |
processor_core_utilization_instructions_completed = "request=0x94,
phys_processor_idx=?,counter_info_version=0x8,
length=8,offset=0x18"이 event에서 phys_processor_idx 뒤의 ?는 event 실행 중 user가 값을 제공한다는 뜻입니다.
hv_gpci interface capabilities와 versions
32-75| What | Date / Contact | 전문 번역 |
|---|---|---|
| /sys/bus/event_source/devices/hv_gpci/interface/collect_privileged | 2014년 2월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> | Hypervisor가 다른 guests가 누적하는 event counters와 physical-domain event counters에 대한 access를 금지하도록 구성되었으면 0, 해당 access를 허용하면 1입니다. |
| /sys/bus/event_source/devices/hv_gpci/interface/ga | 2014년 2월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> | 0 또는 1입니다. arch/powerpc/perf/hv-gpci.h에 나열된 GA events에 access할 수 있는지 나타냅니다. |
| /sys/bus/event_source/devices/hv_gpci/interface/expanded | 2014년 2월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> | 0 또는 1입니다. arch/powerpc/perf/hv-gpci.h에 나열된 EXPANDED events에 access할 수 있는지 나타냅니다. |
| /sys/bus/event_source/devices/hv_gpci/interface/lab | 2014년 2월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> | 0 또는 1입니다. arch/powerpc/perf/hv-gpci.h에 나열된 LAB events에 access할 수 있는지 나타냅니다. |
| /sys/bus/event_source/devices/hv_gpci/interface/version | 2014년 2월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> | Hypervisor가 지원한다고 보고하는 GPCI interface version을 나타내는 number입니다. |
| /sys/bus/event_source/devices/hv_gpci/interface/kernel_version | 2014년 2월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> | Kernel이 알고 있는 최신 GPCI interface version을 나타내는 number입니다. |
hv_gpci HCALL cpumask
77-82| 항목 | 전문 번역 |
|---|---|
| What | /sys/devices/hv_gpci/cpumask |
| Date | 2020년 10월 |
| Contact | Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
| Description | Read-only입니다. hv-gpci PMU event counter data를 가져오는 HCALLs를 수행하도록 지정된 cpumask를 노출합니다. |
POWER10+ H_GET_PERF_COUNTER_INFO files
84-242| What | HCALL request | Date / Contact |
|---|---|---|
| /sys/devices/hv_gpci/interface/processor_bus_topology | PROCESSOR_BUS_TOPOLOGY(0xD0) | 2023년 7월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
| /sys/devices/hv_gpci/interface/processor_config | PROCESSOR_CONFIG(0x90) | 2023년 7월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
| /sys/devices/hv_gpci/interface/affinity_domain_via_virtual_processor | AFFINITY_DOMAIN_INFORMATION_BY_VIRTUAL_PROCESSOR(0xA0) | 2023년 7월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
| /sys/devices/hv_gpci/interface/affinity_domain_via_domain | AFFINITY_DOMAIN_INFORMATION_BY_DOMAIN(0xB0) | 2023년 7월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
| /sys/devices/hv_gpci/interface/affinity_domain_via_partition | AFFINITY_DOMAIN_INFORMATION_BY_PARTITION(0xB1) | 2023년 7월 / Linux on PowerPC Developer List <linuxppc-dev@lists.ozlabs.org> |
각 file은 admin read-only이며 H_GET_PERF_COUNTER_INFO HCALL을 위 counter request value로 호출해 system topology information을 노출합니다. POWER10 이상 platform에서만 만들고 data를 읽으려면 root privileges가 필요합니다. HCALL return type이 H_SUCCESS, H_AUTHORITY 또는 H_PARAMETER일 때만 file을 만듭니다. H_AUTHORITY error는 runtime에 Enable Performance Information Collection option을 설정하여 해결할 수 있습니다. End user는 underlying platform/firmware에 따라 file content를 decode해야 합니다.
| Read error | 전문 번역 |
|---|---|
| -EPERM | Partition이 performance information을 가져올 권한이 없습니다. Enable Performance Information Collection option을 설정해야 합니다. |
| -EIO | Invalid buffer length/address 또는 hardware error 때문에 system information을 가져올 수 없습니다. 자세한 내용은 getPerfCountInfo documentation을 참조합니다. |
| -EFBIG | System information이 PAGE_SIZE를 초과합니다. |
POWER10+ root read→H_GET_PERF_COUNTER_INFO→Request 0x90 / 0xA0 / 0xB0 / 0xB1 / 0xD0→H_SUCCESS payload→Platform or firmware decoding
H_AUTHORITY→Enable Performance Information Collection→Retry read
POWER10+ root user가 file을 읽으면 kernel이 request-specific HCALL을 수행하고 platform-defined payload를 반환합니다.
hv_gpci event format
sysfs-bus-event_source-devices-hv_gpci:1-30format group은 request, version, length와 여러 processor·partition indices를 perf_event_attr.config fields에 mapping하고 ? parameter를 userspace에서 받습니다.