Documentation/virt/kvm/s390/s390-diag.rst

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