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 virtio functions 39----------------------------------------------------- 40 41If the function code specifies 0x500, various virtio-related functions 42are performed. 43 44General register 1 contains the virtio subfunction code. Supported 45virtio subfunctions depend on KVM's userspace. Generally, userspace 46provides either s390-virtio (subcodes 0-2) or virtio-ccw (subcode 3). 47 48Upon completion of the DIAGNOSE instruction, general register 2 contains 49the function's return code, which is either a return code or a subcode 50specific value. 51 52Subcode 0 - s390-virtio notification and early console printk 53 Handled by userspace. 54 55Subcode 1 - s390-virtio reset 56 Handled by userspace. 57 58Subcode 2 - s390-virtio set status 59 Handled by userspace. 60 61Subcode 3 - virtio-ccw notification 62 Handled by either userspace or KVM (ioeventfd case). 63 64 General register 2 contains a subchannel-identification word denoting 65 the subchannel of the virtio-ccw proxy device to be notified. 66 67 General register 3 contains the number of the virtqueue to be notified. 68 69 General register 4 contains a 64bit identifier for KVM usage (the 70 kvm_io_bus cookie). If general register 4 does not contain a valid 71 identifier, it is ignored. 72 73 After completion of the DIAGNOSE call, general register 2 may contain 74 a 64bit identifier (in the kvm_io_bus cookie case), or a negative 75 error value, if an internal error occurred. 76 77 See also the virtio standard for a discussion of this hypercall. 78 79 80DIAGNOSE function code 'X'501 - KVM breakpoint 81---------------------------------------------- 82 83If the function code specifies 0x501, breakpoint functions may be performed. 84This function code is handled by userspace. 85 86This diagnose function code has no subfunctions and uses no parameters. 87