| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
============================= |
| 4 |
The s390 DIAGNOSE call on KVM |
| 5 |
============================= |
| 6 |
|
| 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. |
| 10 |
|
| 11 |
Note that bits are numbered as by the usual s390 convention (most significant |
| 12 |
bit on the left). |
| 13 |
|
| 14 |
|
| 15 |
General remarks |
| 16 |
--------------- |
| 17 |
|
| 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. |
| 21 |
|
| 22 |
All DIAGNOSE calls supported by KVM use the RS-a format:: |
| 23 |
|
| 24 |
-------------------------------------- |
| 25 |
| '83' | R1 | R3 | B2 | D2 | |
| 26 |
-------------------------------------- |
| 27 |
0 8 12 16 20 31 |
| 28 |
|
| 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. |
| 32 |
|
| 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. |
| 36 |
|
| 37 |
|
| 38 |
DIAGNOSE function code 'X'500' - KVM functions |
| 39 |
---------------------------------------------- |
| 40 |
|
| 41 |
If the function code specifies 0x500, various KVM-specific functions |
| 42 |
are performed, including virtio functions. |
| 43 |
|
| 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). |
| 48 |
|
| 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. |
| 52 |
|
| 53 |
If the specified subfunction is not supported, a SPECIFICATION exception |
| 54 |
will be triggered. |
| 55 |
|
| 56 |
Subcode 0 - s390-virtio notification and early console printk |
| 57 |
Handled by userspace. |
| 58 |
|
| 59 |
Subcode 1 - s390-virtio reset |
| 60 |
Handled by userspace. |
| 61 |
|
| 62 |
Subcode 2 - s390-virtio set status |
| 63 |
Handled by userspace. |
| 64 |
|
| 65 |
Subcode 3 - virtio-ccw notification |
| 66 |
Handled by either userspace or KVM (ioeventfd case). |
| 67 |
|
| 68 |
General register 2 contains a subchannel-identification word denoting |
| 69 |
the subchannel of the virtio-ccw proxy device to be notified. |
| 70 |
|
| 71 |
General register 3 contains the number of the virtqueue to be notified. |
| 72 |
|
| 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. |
| 76 |
|
| 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. |
| 80 |
|
| 81 |
See also the virtio standard for a discussion of this hypercall. |
| 82 |
|
| 83 |
Subcode 4 - storage-limit |
| 84 |
Handled by userspace. |
| 85 |
|
| 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. |
| 89 |
|
| 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. |
| 95 |
|
| 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". |
| 99 |
|
| 100 |
|
| 101 |
DIAGNOSE function code 'X'501 - KVM breakpoint |
| 102 |
---------------------------------------------- |
| 103 |
|
| 104 |
If the function code specifies 0x501, breakpoint functions may be performed. |
| 105 |
This function code is handled by userspace. |
| 106 |
|
| 107 |
This diagnose function code has no subfunctions and uses no parameters. |
| 108 |
|
| 109 |
|
| 110 |
DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield |
| 111 |
--------------------------------------------------------- |
| 112 |
|
| 113 |
General register 1 contains the target CPU address. |
| 114 |
|
| 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. |
| 120 |
|
| 121 |
|
| 122 |
DIAG 'X'9C forwarding |
| 123 |
+++++++++++++++++++++ |
| 124 |
|
| 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. |
| 128 |
|
| 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. |
| 134 |
|
| 135 |
|
| 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. |