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