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

Source file repositories/reference/linux-study-clean/Documentation/virt/kvm/s390/s390-diag.rst

File Facts

System
Linux kernel
Corpus path
Documentation/virt/kvm/s390/s390-diag.rst
Extension
.rst
Size
5064 bytes
Lines
141
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

=============================
The s390 DIAGNOSE call on KVM
=============================

KVM on s390 supports the DIAGNOSE call for making hypercalls, both for
native hypercalls and for selected hypercalls found on other s390
hypervisors.

Note that bits are numbered as by the usual s390 convention (most significant
bit on the left).


General remarks
---------------

DIAGNOSE calls by the guest cause a mandatory intercept. This implies
all supported DIAGNOSE calls need to be handled by either KVM or its
userspace.

All DIAGNOSE calls supported by KVM use the RS-a format::

  --------------------------------------
  |  '83'  | R1 | R3 | B2 |     D2     |
  --------------------------------------
  0        8    12   16   20           31

The second-operand address (obtained by the base/displacement calculation)
is not used to address data. Instead, bits 48-63 of this address specify
the function code, and bits 0-47 are ignored.

The supported DIAGNOSE function codes vary by the userspace used. For
DIAGNOSE function codes not specific to KVM, please refer to the
documentation for the s390 hypervisors defining them.


DIAGNOSE function code 'X'500' - KVM functions
----------------------------------------------

If the function code specifies 0x500, various KVM-specific functions
are performed, including virtio functions.

General register 1 contains the subfunction code. Supported subfunctions
depend on KVM's userspace. Regarding virtio subfunctions, generally
userspace provides either s390-virtio (subcodes 0-2) or virtio-ccw
(subcode 3).

Upon completion of the DIAGNOSE instruction, general register 2 contains
the function's return code, which is either a return code or a subcode
specific value.

If the specified subfunction is not supported, a SPECIFICATION exception
will be triggered.

Subcode 0 - s390-virtio notification and early console printk
    Handled by userspace.

Subcode 1 - s390-virtio reset
    Handled by userspace.

Subcode 2 - s390-virtio set status
    Handled by userspace.

Subcode 3 - virtio-ccw notification
    Handled by either userspace or KVM (ioeventfd case).

    General register 2 contains a subchannel-identification word denoting
    the subchannel of the virtio-ccw proxy device to be notified.

Annotation

Implementation Notes