1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============================= 3 =============================
4 The s390 DIAGNOSE call on KVM 4 The s390 DIAGNOSE call on KVM
5 ============================= 5 =============================
6 6
7 KVM on s390 supports the DIAGNOSE call for mak 7 KVM on s390 supports the DIAGNOSE call for making hypercalls, both for
8 native hypercalls and for selected hypercalls 8 native hypercalls and for selected hypercalls found on other s390
9 hypervisors. 9 hypervisors.
10 10
11 Note that bits are numbered as by the usual s3 11 Note that bits are numbered as by the usual s390 convention (most significant
12 bit on the left). 12 bit on the left).
13 13
14 14
15 General remarks 15 General remarks
16 --------------- 16 ---------------
17 17
18 DIAGNOSE calls by the guest cause a mandatory 18 DIAGNOSE calls by the guest cause a mandatory intercept. This implies
19 all supported DIAGNOSE calls need to be handle 19 all supported DIAGNOSE calls need to be handled by either KVM or its
20 userspace. 20 userspace.
21 21
22 All DIAGNOSE calls supported by KVM use the RS 22 All DIAGNOSE calls supported by KVM use the RS-a format::
23 23
24 -------------------------------------- 24 --------------------------------------
25 | '83' | R1 | R3 | B2 | D2 | 25 | '83' | R1 | R3 | B2 | D2 |
26 -------------------------------------- 26 --------------------------------------
27 0 8 12 16 20 31 27 0 8 12 16 20 31
28 28
29 The second-operand address (obtained by the ba 29 The second-operand address (obtained by the base/displacement calculation)
30 is not used to address data. Instead, bits 48- 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. 31 the function code, and bits 0-47 are ignored.
32 32
33 The supported DIAGNOSE function codes vary by 33 The supported DIAGNOSE function codes vary by the userspace used. For
34 DIAGNOSE function codes not specific to KVM, p 34 DIAGNOSE function codes not specific to KVM, please refer to the
35 documentation for the s390 hypervisors definin 35 documentation for the s390 hypervisors defining them.
36 36
37 37
38 DIAGNOSE function code 'X'500' - KVM virtio fu 38 DIAGNOSE function code 'X'500' - KVM virtio functions
39 ---------------------------------------------- 39 -----------------------------------------------------
40 40
41 If the function code specifies 0x500, various 41 If the function code specifies 0x500, various virtio-related functions
42 are performed. 42 are performed.
43 43
44 General register 1 contains the virtio subfunc 44 General register 1 contains the virtio subfunction code. Supported
45 virtio subfunctions depend on KVM's userspace. 45 virtio subfunctions depend on KVM's userspace. Generally, userspace
46 provides either s390-virtio (subcodes 0-2) or 46 provides either s390-virtio (subcodes 0-2) or virtio-ccw (subcode 3).
47 47
48 Upon completion of the DIAGNOSE instruction, g 48 Upon completion of the DIAGNOSE instruction, general register 2 contains
49 the function's return code, which is either a 49 the function's return code, which is either a return code or a subcode
50 specific value. 50 specific value.
51 51
52 Subcode 0 - s390-virtio notification and early 52 Subcode 0 - s390-virtio notification and early console printk
53 Handled by userspace. 53 Handled by userspace.
54 54
55 Subcode 1 - s390-virtio reset 55 Subcode 1 - s390-virtio reset
56 Handled by userspace. 56 Handled by userspace.
57 57
58 Subcode 2 - s390-virtio set status 58 Subcode 2 - s390-virtio set status
59 Handled by userspace. 59 Handled by userspace.
60 60
61 Subcode 3 - virtio-ccw notification 61 Subcode 3 - virtio-ccw notification
62 Handled by either userspace or KVM (ioeven 62 Handled by either userspace or KVM (ioeventfd case).
63 63
64 General register 2 contains a subchannel-i 64 General register 2 contains a subchannel-identification word denoting
65 the subchannel of the virtio-ccw proxy dev 65 the subchannel of the virtio-ccw proxy device to be notified.
66 66
67 General register 3 contains the number of 67 General register 3 contains the number of the virtqueue to be notified.
68 68
69 General register 4 contains a 64bit identi 69 General register 4 contains a 64bit identifier for KVM usage (the
70 kvm_io_bus cookie). If general register 4 70 kvm_io_bus cookie). If general register 4 does not contain a valid
71 identifier, it is ignored. 71 identifier, it is ignored.
72 72
73 After completion of the DIAGNOSE call, gen 73 After completion of the DIAGNOSE call, general register 2 may contain
74 a 64bit identifier (in the kvm_io_bus cook 74 a 64bit identifier (in the kvm_io_bus cookie case), or a negative
75 error value, if an internal error occurred 75 error value, if an internal error occurred.
76 76
77 See also the virtio standard for a discuss 77 See also the virtio standard for a discussion of this hypercall.
78 78
79 79
80 DIAGNOSE function code 'X'501 - KVM breakpoint 80 DIAGNOSE function code 'X'501 - KVM breakpoint
81 ---------------------------------------------- 81 ----------------------------------------------
82 82
83 If the function code specifies 0x501, breakpoi 83 If the function code specifies 0x501, breakpoint functions may be performed.
84 This function code is handled by userspace. 84 This function code is handled by userspace.
85 85
86 This diagnose function code has no subfunction 86 This diagnose function code has no subfunctions and uses no parameters.
87 87
88 88
89 DIAGNOSE function code 'X'9C - Voluntary Time 89 DIAGNOSE function code 'X'9C - Voluntary Time Slice Yield
90 ---------------------------------------------- 90 ---------------------------------------------------------
91 91
92 General register 1 contains the target CPU add 92 General register 1 contains the target CPU address.
93 93
94 In a guest of a hypervisor like LPAR, KVM or z 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 s 95 DIAGNOSE with function code 0x9c may improve system performance by
96 yielding the host CPU on which the guest CPU i 96 yielding the host CPU on which the guest CPU is running to be assigned
97 to another guest CPU, preferably the logical C 97 to another guest CPU, preferably the logical CPU containing the specified
98 target CPU. 98 target CPU.
99 99
100 100
101 DIAG 'X'9C forwarding 101 DIAG 'X'9C forwarding
102 +++++++++++++++++++++ 102 +++++++++++++++++++++
103 103
104 The guest may send a DIAGNOSE 0x9c in order to 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 t 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 106 that is currently holding a spinlock, but not running.
107 107
108 However, on the host the real cpu backing the 108 However, on the host the real cpu backing the vcpu may itself not be
109 running. 109 running.
110 Forwarding the DIAGNOSE 0x9c initially sent by 110 Forwarding the DIAGNOSE 0x9c initially sent by the guest to yield to
111 the backing cpu will hopefully cause that cpu, 111 the backing cpu will hopefully cause that cpu, and thus subsequently
112 the guest's vcpu, to be scheduled. 112 the guest's vcpu, to be scheduled.
113 113
114 114
115 diag9c_forwarding_hz 115 diag9c_forwarding_hz
116 KVM kernel parameter allowing to specify t 116 KVM kernel parameter allowing to specify the maximum number of DIAGNOSE
117 0x9c forwarding per second in the purpose 117 0x9c forwarding per second in the purpose of avoiding a DIAGNOSE 0x9c
118 forwarding storm. 118 forwarding storm.
119 A value of 0 turns the forwarding off. 119 A value of 0 turns the forwarding off.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.