120 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=============================4The s390 DIAGNOSE call on KVM5=============================6 7KVM on s390 supports the DIAGNOSE call for making hypercalls, both for8native hypercalls and for selected hypercalls found on other s3909hypervisors.10 11Note that bits are numbered as by the usual s390 convention (most significant12bit on the left).13 14 15General remarks16---------------17 18DIAGNOSE calls by the guest cause a mandatory intercept. This implies19all supported DIAGNOSE calls need to be handled by either KVM or its20userspace.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 3128 29The second-operand address (obtained by the base/displacement calculation)30is not used to address data. Instead, bits 48-63 of this address specify31the function code, and bits 0-47 are ignored.32 33The supported DIAGNOSE function codes vary by the userspace used. For34DIAGNOSE function codes not specific to KVM, please refer to the35documentation for the s390 hypervisors defining them.36 37 38DIAGNOSE function code 'X'500' - KVM virtio functions39-----------------------------------------------------40 41If the function code specifies 0x500, various virtio-related functions42are performed.43 44General register 1 contains the virtio subfunction code. Supported45virtio subfunctions depend on KVM's userspace. Generally, userspace46provides either s390-virtio (subcodes 0-2) or virtio-ccw (subcode 3).47 48Upon completion of the DIAGNOSE instruction, general register 2 contains49the function's return code, which is either a return code or a subcode50specific value.51 52Subcode 0 - s390-virtio notification and early console printk53 Handled by userspace.54 55Subcode 1 - s390-virtio reset56 Handled by userspace.57 58Subcode 2 - s390-virtio set status59 Handled by userspace.60 61Subcode 3 - virtio-ccw notification62 Handled by either userspace or KVM (ioeventfd case).63 64 General register 2 contains a subchannel-identification word denoting65 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 (the70 kvm_io_bus cookie). If general register 4 does not contain a valid71 identifier, it is ignored.72 73 After completion of the DIAGNOSE call, general register 2 may contain74 a 64bit identifier (in the kvm_io_bus cookie case), or a negative75 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 breakpoint81----------------------------------------------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 88 89DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield90---------------------------------------------------------91 92General register 1 contains the target CPU address.93 94In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs,95DIAGNOSE with function code 0x9c may improve system performance by96yielding the host CPU on which the guest CPU is running to be assigned97to another guest CPU, preferably the logical CPU containing the specified98target CPU.99 100 101DIAG 'X'9C forwarding102+++++++++++++++++++++103 104The guest may send a DIAGNOSE 0x9c in order to yield to a certain105other vcpu. An example is a Linux guest that tries to yield to the vcpu106that is currently holding a spinlock, but not running.107 108However, on the host the real cpu backing the vcpu may itself not be109running.110Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to111the backing cpu will hopefully cause that cpu, and thus subsequently112the guest's vcpu, to be scheduled.113 114 115diag9c_forwarding_hz116 KVM kernel parameter allowing to specify the maximum number of DIAGNOSE117 0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c118 forwarding storm.119 A value of 0 turns the forwarding off.120