요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
=============================
4
The s390 DIAGNOSE call on KVM
5
=============================
7
KVM on s390 supports the DIAGNOSE call for making hypercalls, both for
8
native hypercalls and for selected hypercalls found on other s390
9
hypervisors.
11
Note that bits are numbered as by the usual s390 convention (most significant
12
bit on the left).
15
General remarks
16
---------------
18
DIAGNOSE calls by the guest cause a mandatory intercept. This implies
19
all supported DIAGNOSE calls need to be handled by either KVM or its
20
userspace.
22
All DIAGNOSE calls supported by KVM use the RS-a format::
24
--------------------------------------
25
| '83' | R1 | R3 | B2 | D2 |
26
--------------------------------------
27
0 8 12 16 20 31
29
The second-operand address (obtained by the base/displacement calculation)
30
is not used to address data. Instead, bits 48-63 of this address specify
31
the function code, and bits 0-47 are ignored.
33
The supported DIAGNOSE function codes vary by the userspace used. For
34
DIAGNOSE function codes not specific to KVM, please refer to the
35
documentation for the s390 hypervisors defining them.
38
DIAGNOSE function code 'X'500' - KVM functions
39
----------------------------------------------
41
If the function code specifies 0x500, various KVM-specific functions
42
are performed, including virtio functions.
44
General register 1 contains the subfunction code. Supported subfunctions
45
depend on KVM's userspace. Regarding virtio subfunctions, generally
46
userspace provides either s390-virtio (subcodes 0-2) or virtio-ccw
47
(subcode 3).
49
Upon completion of the DIAGNOSE instruction, general register 2 contains
50
the function's return code, which is either a return code or a subcode
51
specific value.
53
If the specified subfunction is not supported, a SPECIFICATION exception
54
will be triggered.
56
Subcode 0 - s390-virtio notification and early console printk
57
Handled by userspace.
59
Subcode 1 - s390-virtio reset
60
Handled by userspace.
62
Subcode 2 - s390-virtio set status
63
Handled by userspace.
65
Subcode 3 - virtio-ccw notification
66
Handled by either userspace or KVM (ioeventfd case).
68
General register 2 contains a subchannel-identification word denoting
69
the subchannel of the virtio-ccw proxy device to be notified.
71
General register 3 contains the number of the virtqueue to be notified.
73
General register 4 contains a 64bit identifier for KVM usage (the
74
kvm_io_bus cookie). If general register 4 does not contain a valid
75
identifier, it is ignored.
77
After completion of the DIAGNOSE call, general register 2 may contain
78
a 64bit identifier (in the kvm_io_bus cookie case), or a negative
79
error value, if an internal error occurred.
81
See also the virtio standard for a discussion of this hypercall.
83
Subcode 4 - storage-limit
84
Handled by userspace.
86
After completion of the DIAGNOSE call, general register 2 will
87
contain the storage limit: the maximum physical address that might be
88
used for storage throughout the lifetime of the VM.
90
The storage limit does not indicate currently usable storage, it may
91
include holes, standby storage and areas reserved for other means, such
92
as memory hotplug or virtio-mem devices. Other interfaces for detecting
93
actually usable storage, such as SCLP, must be used in conjunction with
94
this subfunction.
96
Note that the storage limit can be larger, but never smaller than the
97
maximum storage address indicated by SCLP via the "maximum storage
98
increment" and the "increment size".
101
DIAGNOSE function code 'X'501 - KVM breakpoint
102
----------------------------------------------
104
If the function code specifies 0x501, breakpoint functions may be performed.
105
This function code is handled by userspace.
107
This diagnose function code has no subfunctions and uses no parameters.
110
DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield
111
---------------------------------------------------------
113
General register 1 contains the target CPU address.
115
In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs,
116
DIAGNOSE with function code 0x9c may improve system performance by
117
yielding the host CPU on which the guest CPU is running to be assigned
118
to another guest CPU, preferably the logical CPU containing the specified
119
target CPU.
122
DIAG 'X'9C forwarding
123
+++++++++++++++++++++
125
The guest may send a DIAGNOSE 0x9c in order to yield to a certain
126
other vcpu. An example is a Linux guest that tries to yield to the vcpu
127
that is currently holding a spinlock, but not running.
129
However, on the host the real cpu backing the vcpu may itself not be
130
running.
131
Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to
132
the backing cpu will hopefully cause that cpu, and thus subsequently
133
the guest's vcpu, to be scheduled.
136
diag9c_forwarding_hz
137
KVM kernel parameter allowing to specify the maximum number of DIAGNOSE
138
0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c
139
forwarding storm.
140
A value of 0 turns the forwarding off.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
명령 형식과 처리 원칙
1-37s390 KVM은 자체 하이퍼콜과 다른 s390 하이퍼바이저에서 선택한 하이퍼콜을 DIAGNOSE로 제공합니다. 비트 번호는 왼쪽 최상위 비트부터 세는 일반 s390 관례를 따릅니다.
게스트 DIAGNOSE는 반드시 intercept되므로 지원하는 모든 호출을 KVM 또는 userspace가 처리해야 합니다. 모든 KVM 지원 호출은 RS-a 형식을 사용합니다.
비트필드
0-7opcode `'83'`
8-11`R1`
12-15`R3`
16-19`B2`
20-31`D2`
원문 ASCII 명령 배치를 구조화한 표입니다.
base/displacement로 얻은 두 번째 피연산자 주소는 데이터 주소로 쓰지 않습니다. 주소의 bit 48-63이 function code이고 bit 0-47은 무시합니다. 지원 코드는 userspace에 따라 달라지며 KVM 전용이 아닌 코드는 해당 s390 하이퍼바이저 문서를 참조해야 합니다.
.. SPDX-License-Identifier: GPL-2.0
=============================
The s390 DIAGNOSE call on KVM
=============================
KVM on s390 supports the DIAGNOSE call for making hypercalls, both for
native hypercalls and for selected hypercalls found on other s390
hypervisors.
Note that bits are numbered as by the usual s390 convention (most significant
bit on the left).
General remarks
---------------
DIAGNOSE calls by the guest cause a mandatory intercept. This implies
all supported DIAGNOSE calls need to be handled by either KVM or its
userspace.
All DIAGNOSE calls supported by KVM use the RS-a format::
--------------------------------------
| '83' | R1 | R3 | B2 | D2 |
--------------------------------------
0 8 12 16 20 31
The second-operand address (obtained by the base/displacement calculation)
is not used to address data. Instead, bits 48-63 of this address specify
the function code, and bits 0-47 are ignored.
The supported DIAGNOSE function codes vary by the userspace used. For
DIAGNOSE function codes not specific to KVM, please refer to the
documentation for the s390 hypervisors defining them.
DIAGNOSE X'500' KVM 기능
38-100function code `0x500`은 virtio를 포함한 KVM 전용 기능을 실행합니다. general register 1은 subfunction code이고 완료 뒤 general register 2는 반환 코드 또는 subcode별 값을 담습니다. 미지원 subfunction은 SPECIFICATION 예외를 일으킵니다.
Subcode기능처리자
0s390-virtio 알림과 early console printkuserspace
1s390-virtio resetuserspace
2s390-virtio status 설정userspace
3virtio-ccw 알림userspace 또는 KVM ioeventfd
4storage-limituserspace
userspace 또는 KVM이 처리하는 기능입니다.
subcode 3에서 GR2는 알릴 virtio-ccw proxy 장치의 subchannel-identification word, GR3은 virtqueue 번호, GR4는 선택적인 64비트 `kvm_io_bus` cookie입니다. 완료 뒤 GR2에는 cookie 또는 내부 오류의 음수 값이 돌아올 수 있습니다.
subcode 4는 VM 수명 동안 저장소로 사용할 가능성이 있는 최대 물리 주소를 GR2에 반환합니다. 이 한계에는 hole, standby storage, memory hotplug나 virtio-mem 예약 영역이 포함될 수 있으므로 현재 사용 가능한 메모리는 SCLP 같은 다른 인터페이스와 함께 판단해야 합니다.
storage limit은 SCLP의 maximum storage increment와 increment size로 계산한 최대 주소보다 클 수 있지만 더 작을 수는 없습니다.
DIAGNOSE function code 'X'500' - KVM functions
----------------------------------------------
If the function code specifies 0x500, various KVM-specific functions
are performed, including virtio functions.
General register 1 contains the subfunction code. Supported subfunctions
depend on KVM's userspace. Regarding virtio subfunctions, generally
userspace provides either s390-virtio (subcodes 0-2) or virtio-ccw
(subcode 3).
Upon completion of the DIAGNOSE instruction, general register 2 contains
the function's return code, which is either a return code or a subcode
specific value.
If the specified subfunction is not supported, a SPECIFICATION exception
will be triggered.
Subcode 0 - s390-virtio notification and early console printk
Handled by userspace.
Subcode 1 - s390-virtio reset
Handled by userspace.
Subcode 2 - s390-virtio set status
Handled by userspace.
Subcode 3 - virtio-ccw notification
Handled by either userspace or KVM (ioeventfd case).
General register 2 contains a subchannel-identification word denoting
the subchannel of the virtio-ccw proxy device to be notified.
General register 3 contains the number of the virtqueue to be notified.
General register 4 contains a 64bit identifier for KVM usage (the
kvm_io_bus cookie). If general register 4 does not contain a valid
identifier, it is ignored.
After completion of the DIAGNOSE call, general register 2 may contain
a 64bit identifier (in the kvm_io_bus cookie case), or a negative
error value, if an internal error occurred.
See also the virtio standard for a discussion of this hypercall.
Subcode 4 - storage-limit
Handled by userspace.
After completion of the DIAGNOSE call, general register 2 will
contain the storage limit: the maximum physical address that might be
used for storage throughout the lifetime of the VM.
The storage limit does not indicate currently usable storage, it may
include holes, standby storage and areas reserved for other means, such
as memory hotplug or virtio-mem devices. Other interfaces for detecting
actually usable storage, such as SCLP, must be used in conjunction with
this subfunction.
Note that the storage limit can be larger, but never smaller than the
maximum storage address indicated by SCLP via the "maximum storage
increment" and the "increment size".
DIAGNOSE X'501' breakpoint
101-109function code `0x501`은 breakpoint 기능을 수행할 수 있으며 userspace가 처리합니다. subfunction과 매개변수는 없습니다.
DIAGNOSE function code 'X'501 - KVM breakpoint
----------------------------------------------
If the function code specifies 0x501, breakpoint functions may be performed.
This function code is handled by userspace.
This diagnose function code has no subfunctions and uses no parameters.
DIAGNOSE X'9C' 자발적 양보
110-140`0x9c`는 GR1에 target CPU 주소를 넣어 현재 게스트 CPU가 쓰는 공유 호스트 CPU를 다른 게스트 CPU, 가능하면 target CPU가 속한 논리 CPU에 양보합니다. LPAR, KVM, z/VM처럼 호스트 CPU를 공유하는 환경의 성능을 높일 수 있습니다.
대표 사례는 Linux 게스트가 spinlock을 보유했지만 현재 실행되지 않는 vCPU에 양보하려는 경우입니다. 호스트에서 그 vCPU를 뒷받침하는 실제 CPU 역시 실행 중이 아닐 수 있으므로 KVM은 DIAGNOSE를 backing CPU로 전달해 해당 CPU와 게스트 vCPU가 스케줄되도록 유도합니다.
값동작
양수초당 DIAGNOSE 0x9c 전달 최대 횟수
0전달 끄기
전달 폭주를 제한하는 KVM 커널 매개변수입니다.
DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield
---------------------------------------------------------
General register 1 contains the target CPU address.
In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs,
DIAGNOSE with function code 0x9c may improve system performance by
yielding the host CPU on which the guest CPU is running to be assigned
to another guest CPU, preferably the logical CPU containing the specified
target CPU.
DIAG 'X'9C forwarding
+++++++++++++++++++++
The guest may send a DIAGNOSE 0x9c in order to yield to a certain
other vcpu. An example is a Linux guest that tries to yield to the vcpu
that is currently holding a spinlock, but not running.
However, on the host the real cpu backing the vcpu may itself not be
running.
Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to
the backing cpu will hopefully cause that cpu, and thus subsequently
the guest's vcpu, to be scheduled.
diag9c_forwarding_hz
KVM kernel parameter allowing to specify the maximum number of DIAGNOSE
0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c
forwarding storm.
A value of 0 turns the forwarding off.
요약·해설
s390-diag.rst:1-140s390 KVM의 DIAGNOSE 명령 형식과 X'500', X'501', X'9C 기능을 정의합니다.
ABI 필드, 명령·레지스터 이름, 소스 경로와 줄 좌표를 보존하고 보안 경계와 실행 순서를 구조화했습니다.