1.. SPDX-License-Identifier: GPL-2.0 2 3============================= 4The s390 DIAGNOSE call on KVM 5============================= 6 7KVM on s390 supports the DIAGNOSE call for making hypercalls, both for 8native hypercalls and for selected hypercalls found on other s390 9hypervisors. 10 11Note that bits are numbered as by the usual s390 convention (most significant 12bit on the left). 13 14 15General remarks 16--------------- 17 18DIAGNOSE calls by the guest cause a mandatory intercept. This implies 19all supported DIAGNOSE calls need to be handled by either KVM or its 20userspace. 21 22All 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 29The second-operand address (obtained by the base/displacement calculation) 30is not used to address data. Instead, bits 48-63 of this address specify 31the function code, and bits 0-47 are ignored. 32 33The supported DIAGNOSE function codes vary by the userspace used. For 34DIAGNOSE function codes not specific to KVM, please refer to the 35documentation for the s390 hypervisors defining them. 36 37 38DIAGNOSE function code 'X'500' - KVM functions 39---------------------------------------------- 40 41If the function code specifies 0x500, various KVM-specific functions 42are performed, including virtio functions. 43 44General register 1 contains the subfunction code. Supported subfunctions 45depend on KVM's userspace. Regarding virtio subfunctions, generally 46userspace provides either s390-virtio (subcodes 0-2) or virtio-ccw 47(subcode 3). 48 49Upon completion of the DIAGNOSE instruction, general register 2 contains 50the function's return code, which is either a return code or a subcode 51specific value. 52 53If the specified subfunction is not supported, a SPECIFICATION exception 54will be triggered. 55 56Subcode 0 - s390-virtio notification and early console printk 57 Handled by userspace. 58 59Subcode 1 - s390-virtio reset 60 Handled by userspace. 61 62Subcode 2 - s390-virtio set status 63 Handled by userspace. 64 65Subcode 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 83Subcode 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 101DIAGNOSE function code 'X'501 - KVM breakpoint 102---------------------------------------------- 103 104If the function code specifies 0x501, breakpoint functions may be performed. 105This function code is handled by userspace. 106 107This diagnose function code has no subfunctions and uses no parameters. 108 109 110DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield 111--------------------------------------------------------- 112 113General register 1 contains the target CPU address. 114 115In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs, 116DIAGNOSE with function code 0x9c may improve system performance by 117yielding the host CPU on which the guest CPU is running to be assigned 118to another guest CPU, preferably the logical CPU containing the specified 119target CPU. 120 121 122DIAG 'X'9C forwarding 123+++++++++++++++++++++ 124 125The guest may send a DIAGNOSE 0x9c in order to yield to a certain 126other vcpu. An example is a Linux guest that tries to yield to the vcpu 127that is currently holding a spinlock, but not running. 128 129However, on the host the real cpu backing the vcpu may itself not be 130running. 131Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to 132the backing cpu will hopefully cause that cpu, and thus subsequently 133the guest's vcpu, to be scheduled. 134 135 136diag9c_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. 141