Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) The s390 DIAGNOSE call on KVM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) =============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) KVM on s390 supports the DIAGNOSE call for making hypercalls, both for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) native hypercalls and for selected hypercalls found on other s390
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) hypervisors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Note that bits are numbered as by the usual s390 convention (most significant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) bit on the left).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) General remarks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) DIAGNOSE calls by the guest cause a mandatory intercept. This implies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) all supported DIAGNOSE calls need to be handled by either KVM or its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) All DIAGNOSE calls supported by KVM use the RS-a format::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)   --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)   |  '83'  | R1 | R3 | B2 |     D2     |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)   --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)   0        8    12   16   20           31
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) The second-operand address (obtained by the base/displacement calculation)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) is not used to address data. Instead, bits 48-63 of this address specify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) the function code, and bits 0-47 are ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) The supported DIAGNOSE function codes vary by the userspace used. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) DIAGNOSE function codes not specific to KVM, please refer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) documentation for the s390 hypervisors defining them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) DIAGNOSE function code 'X'500' - KVM virtio functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) -----------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) If the function code specifies 0x500, various virtio-related functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) are performed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) General register 1 contains the virtio subfunction code. Supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) virtio subfunctions depend on KVM's userspace. Generally, userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) provides either s390-virtio (subcodes 0-2) or virtio-ccw (subcode 3).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Upon completion of the DIAGNOSE instruction, general register 2 contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) the function's return code, which is either a return code or a subcode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) specific value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Subcode 0 - s390-virtio notification and early console printk
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)     Handled by userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Subcode 1 - s390-virtio reset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)     Handled by userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Subcode 2 - s390-virtio set status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)     Handled by userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Subcode 3 - virtio-ccw notification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)     Handled by either userspace or KVM (ioeventfd case).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)     General register 2 contains a subchannel-identification word denoting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)     the subchannel of the virtio-ccw proxy device to be notified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)     General register 3 contains the number of the virtqueue to be notified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)     General register 4 contains a 64bit identifier for KVM usage (the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)     kvm_io_bus cookie). If general register 4 does not contain a valid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)     identifier, it is ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)     After completion of the DIAGNOSE call, general register 2 may contain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)     a 64bit identifier (in the kvm_io_bus cookie case), or a negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)     error value, if an internal error occurred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)     See also the virtio standard for a discussion of this hypercall.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) DIAGNOSE function code 'X'501 - KVM breakpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) If the function code specifies 0x501, breakpoint functions may be performed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) This function code is handled by userspace.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) This diagnose function code has no subfunctions and uses no parameters.