0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =============================
0004 The s390 DIAGNOSE call on KVM
0005 =============================
0006
0007 KVM on s390 supports the DIAGNOSE call for making hypercalls, both for
0008 native hypercalls and for selected hypercalls found on other s390
0009 hypervisors.
0010
0011 Note that bits are numbered as by the usual s390 convention (most significant
0012 bit on the left).
0013
0014
0015 General remarks
0016 ---------------
0017
0018 DIAGNOSE calls by the guest cause a mandatory intercept. This implies
0019 all supported DIAGNOSE calls need to be handled by either KVM or its
0020 userspace.
0021
0022 All DIAGNOSE calls supported by KVM use the RS-a format::
0023
0024 --------------------------------------
0025 | '83' | R1 | R3 | B2 | D2 |
0026 --------------------------------------
0027 0 8 12 16 20 31
0028
0029 The second-operand address (obtained by the base/displacement calculation)
0030 is not used to address data. Instead, bits 48-63 of this address specify
0031 the function code, and bits 0-47 are ignored.
0032
0033 The supported DIAGNOSE function codes vary by the userspace used. For
0034 DIAGNOSE function codes not specific to KVM, please refer to the
0035 documentation for the s390 hypervisors defining them.
0036
0037
0038 DIAGNOSE function code 'X'500' - KVM virtio functions
0039 -----------------------------------------------------
0040
0041 If the function code specifies 0x500, various virtio-related functions
0042 are performed.
0043
0044 General register 1 contains the virtio subfunction code. Supported
0045 virtio subfunctions depend on KVM's userspace. Generally, userspace
0046 provides either s390-virtio (subcodes 0-2) or virtio-ccw (subcode 3).
0047
0048 Upon completion of the DIAGNOSE instruction, general register 2 contains
0049 the function's return code, which is either a return code or a subcode
0050 specific value.
0051
0052 Subcode 0 - s390-virtio notification and early console printk
0053 Handled by userspace.
0054
0055 Subcode 1 - s390-virtio reset
0056 Handled by userspace.
0057
0058 Subcode 2 - s390-virtio set status
0059 Handled by userspace.
0060
0061 Subcode 3 - virtio-ccw notification
0062 Handled by either userspace or KVM (ioeventfd case).
0063
0064 General register 2 contains a subchannel-identification word denoting
0065 the subchannel of the virtio-ccw proxy device to be notified.
0066
0067 General register 3 contains the number of the virtqueue to be notified.
0068
0069 General register 4 contains a 64bit identifier for KVM usage (the
0070 kvm_io_bus cookie). If general register 4 does not contain a valid
0071 identifier, it is ignored.
0072
0073 After completion of the DIAGNOSE call, general register 2 may contain
0074 a 64bit identifier (in the kvm_io_bus cookie case), or a negative
0075 error value, if an internal error occurred.
0076
0077 See also the virtio standard for a discussion of this hypercall.
0078
0079
0080 DIAGNOSE function code 'X'501 - KVM breakpoint
0081 ----------------------------------------------
0082
0083 If the function code specifies 0x501, breakpoint functions may be performed.
0084 This function code is handled by userspace.
0085
0086 This diagnose function code has no subfunctions and uses no parameters.
0087
0088
0089 DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield
0090 ---------------------------------------------------------
0091
0092 General register 1 contains the target CPU address.
0093
0094 In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs,
0095 DIAGNOSE with function code 0x9c may improve system performance by
0096 yielding the host CPU on which the guest CPU is running to be assigned
0097 to another guest CPU, preferably the logical CPU containing the specified
0098 target CPU.
0099
0100
0101 DIAG 'X'9C forwarding
0102 +++++++++++++++++++++
0103
0104 The guest may send a DIAGNOSE 0x9c in order to yield to a certain
0105 other vcpu. An example is a Linux guest that tries to yield to the vcpu
0106 that is currently holding a spinlock, but not running.
0107
0108 However, on the host the real cpu backing the vcpu may itself not be
0109 running.
0110 Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to
0111 the backing cpu will hopefully cause that cpu, and thus subsequently
0112 the guest's vcpu, to be scheduled.
0113
0114
0115 diag9c_forwarding_hz
0116 KVM kernel parameter allowing to specify the maximum number of DIAGNOSE
0117 0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c
0118 forwarding storm.
0119 A value of 0 turns the forwarding off.
