.. SPDX-License-Identifier: GPL-2.0

==============
KVM MMIO guard
==============

KVM implements device emulation by handling translation faults to any
IPA range that is not contained in a memory slot. Such a translation
fault is in most cases passed on to userspace (or in rare cases to the
host kernel) with the address, size and possibly data of the access
for emulation.

Should the guest exit with an address that is not one that corresponds
to an emulatable device, userspace may take measures that are not the
most graceful as far as the guest is concerned (such as terminating it
or delivering a fatal exception).

There is also an element of trust: by forwarding the request to
userspace, the kernel assumes that the guest trusts userspace to do
the right thing.

The KVM MMIO guard offers a way to mitigate this last point: a guest
can request that only certain regions of the IPA space are valid as
MMIO. Only these regions will be handled as an MMIO, and any other
will result in an exception being delivered to the guest.

This relies on a set of hypercalls defined in the KVM-specific range,
using the HVC64 calling convention.

When operating on a range of contiguous IPA space, it is recommended
to use ARM_SMCCC_KVM_FUNC_MMIO_RGUARD_MAP. This HVC takes a number of
granules as an argument. See ``KVM_FUNC_HAS_RANGE`` in hypercalls.rst
for a complete description.

Both ARM_SMCCC_KVM_FUNC_MMIO_GUARD_UNMAP and
ARM_SMCCC_KVM_FUNC_MMIO_RGUARD_UNMAP are only declared for legacy guests,
that is, older than 6.12.

* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_INFO

    ==============    ========    ================================
    Function ID:      (uint32)    0xC6000005
    Arguments:        r1-r3       Reserved / Must be zero
    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
                      (uint64)    Protection Granule (PG) size in
                                  bytes (r0). KVM_FUNC_HAS_RANGE(1)
                                  is set (r1) if RGUARD_MAP and
                                  RGUARD_UNMAP HVCs are available.
    ==============    ========    ================================

* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_ENROLL

    ==============    ========    ==============================
    Function ID:      (uint32)    0xC6000006
    Arguments:        none
    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
                                  RET_SUCCESS(0) (r0)
    ==============    ========    ==============================

* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_MAP

    ==============    ========    ====================================
    Function ID:      (uint32)    0xC6000007
    Arguments:        (uint64)    The base of the PG-sized IPA range
                                  that is allowed to be accessed as
                                  MMIO. Must be aligned to the PG size
                                  (r1)
                      (uint64)    Index in the MAIR_EL1 register
		                  providing the memory attribute that
				  is used by the guest (r2)
    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
                                  RET_SUCCESS(0) (r0)
    ==============    ========    ====================================

* ARM_SMCCC_KVM_FUNC_MMIO_GUARD_UNMAP

    ==============    ========    ======================================
    Function ID:      (uint32)    0xC6000008
    ==============    ========    ======================================

* ARM_SMCCC_KVM_FUNC_MMIO_RGUARD_MAP

    ==============    ========    ====================================
    Function ID:      (uint32)    0xC600000A
    Arguments:        (uint64)    The base of the PG-sized IPA range
                                  that is allowed to be accessed as
                                  MMIO. Must be aligned to the PG size
                                  (r1)
                      (uint64)    Number of granules to guard (r2). See
                                  ``KVM_FUNC_HAS_RANGE`` in
                                  hypercalls.rst for more details
    Return Values:    (int64)     NOT_SUPPORTED(-1) on error, or
                                  RET_SUCCESS(0) (r0)
                      (uint64)     Number of shared granules (r1)
    ==============    ========    ====================================

* ARM_SMCCC_KVM_FUNC_MMIO_RGUARD_UNMAP

    ==============    ========    ======================================
    Function ID:      (uint32)    0xC600000B
    ==============    ========    ======================================