Debian Codegraph @

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

raw
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 functions
39 ----------------------------------------------
40
41 If the function code specifies 0x500, various KVM-specific functions
42 are performed, including virtio functions.
43
44 General register 1 contains the subfunction code. Supported subfunctions
45 depend on KVM's userspace. Regarding virtio subfunctions, generally
46 userspace provides either s390-virtio (subcodes 0-2) or virtio-ccw
47 (subcode 3).
48
49 Upon completion of the DIAGNOSE instruction, general register 2 contains
50 the function's return code, which is either a return code or a subcode
51 specific value.
52
53 If the specified subfunction is not supported, a SPECIFICATION exception
54 will be triggered.
55
56 Subcode 0 - s390-virtio notification and early console printk
57 Handled by userspace.
58
59 Subcode 1 - s390-virtio reset
60 Handled by userspace.
61
62 Subcode 2 - s390-virtio set status
63 Handled by userspace.
64
65 Subcode 3 - virtio-ccw notification
66 Handled by either userspace or KVM (ioeventfd case).
67
68 General register 2 contains a subchannel-identification word denoting
69 the subchannel of the virtio-ccw proxy device to be notified.
70
71 General register 3 contains the number of the virtqueue to be notified.
72
73 General register 4 contains a 64bit identifier for KVM usage (the
74 kvm_io_bus cookie). If general register 4 does not contain a valid
75 identifier, it is ignored.
76
77 After completion of the DIAGNOSE call, general register 2 may contain
78 a 64bit identifier (in the kvm_io_bus cookie case), or a negative
79 error value, if an internal error occurred.
80
81 See also the virtio standard for a discussion of this hypercall.
82
83 Subcode 4 - storage-limit
84 Handled by userspace.
85
86 After completion of the DIAGNOSE call, general register 2 will
87 contain the storage limit: the maximum physical address that might be
88 used for storage throughout the lifetime of the VM.
89
90 The storage limit does not indicate currently usable storage, it may
91 include holes, standby storage and areas reserved for other means, such
92 as memory hotplug or virtio-mem devices. Other interfaces for detecting
93 actually usable storage, such as SCLP, must be used in conjunction with
94 this subfunction.
95
96 Note that the storage limit can be larger, but never smaller than the
97 maximum storage address indicated by SCLP via the "maximum storage
98 increment" and the "increment size".
99
100
101 DIAGNOSE function code 'X'501 - KVM breakpoint
102 ----------------------------------------------
103
104 If the function code specifies 0x501, breakpoint functions may be performed.
105 This function code is handled by userspace.
106
107 This diagnose function code has no subfunctions and uses no parameters.
108
109
110 DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield
111 ---------------------------------------------------------
112
113 General register 1 contains the target CPU address.
114
115 In a guest of a hypervisor like LPAR, KVM or z/VM using shared host CPUs,
116 DIAGNOSE with function code 0x9c may improve system performance by
117 yielding the host CPU on which the guest CPU is running to be assigned
118 to another guest CPU, preferably the logical CPU containing the specified
119 target CPU.
120
121
122 DIAG 'X'9C forwarding
123 +++++++++++++++++++++
124
125 The guest may send a DIAGNOSE 0x9c in order to yield to a certain
126 other vcpu. An example is a Linux guest that tries to yield to the vcpu
127 that is currently holding a spinlock, but not running.
128
129 However, on the host the real cpu backing the vcpu may itself not be
130 running.
131 Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to
132 the backing cpu will hopefully cause that cpu, and thus subsequently
133 the guest's vcpu, to be scheduled.
134
135
136 diag9c_forwarding_hz
137 KVM kernel parameter allowing to specify the maximum number of DIAGNOSE
138 0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c
139 forwarding storm.
140 A value of 0 turns the forwarding off.