Documentation/virt/kvm/devices/arm-vgic-its.rst

Source file repositories/reference/linux-study-clean/Documentation/virt/kvm/devices/arm-vgic-its.rst

File Facts

System
Linux kernel
Corpus path
Documentation/virt/kvm/devices/arm-vgic-its.rst
Extension
.rst
Size
7845 bytes
Lines
216
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

===============================================
ARM Virtual Interrupt Translation Service (ITS)
===============================================

Device types supported:
  KVM_DEV_TYPE_ARM_VGIC_ITS    ARM Interrupt Translation Service Controller

The ITS allows MSI(-X) interrupts to be injected into guests. This extension is
optional.  Creating a virtual ITS controller also requires a host GICv3 (see
arm-vgic-v3.txt), but does not depend on having physical ITS controllers.

There can be multiple ITS controllers per guest, each of them has to have
a separate, non-overlapping MMIO region.


Groups
======

KVM_DEV_ARM_VGIC_GRP_ADDR
-------------------------

  Attributes:
    KVM_VGIC_ITS_ADDR_TYPE (rw, 64-bit)
      Base address in the guest physical address space of the GICv3 ITS
      control register frame.
      This address needs to be 64K aligned and the region covers 128K.

  Errors:

    =======  =================================================
    -E2BIG   Address outside of addressable IPA range
    -EINVAL  Incorrectly aligned address
    -EEXIST  Address already configured
    -EFAULT  Invalid user pointer for attr->addr.
    -ENODEV  Incorrect attribute or the ITS is not supported.
    =======  =================================================


KVM_DEV_ARM_VGIC_GRP_CTRL
-------------------------

  Attributes:
    KVM_DEV_ARM_VGIC_CTRL_INIT
      request the initialization of the ITS, no additional parameter in
      kvm_device_attr.addr.

    KVM_DEV_ARM_ITS_CTRL_RESET
      reset the ITS, no additional parameter in kvm_device_attr.addr.
      See "ITS Reset State" section.

    KVM_DEV_ARM_ITS_SAVE_TABLES
      save the ITS table data into guest RAM, at the location provisioned
      by the guest in corresponding registers/table entries. Should userspace
      require a form of dirty tracking to identify which pages are modified
      by the saving process, it should use a bitmap even if using another
      mechanism to track the memory dirtied by the vCPUs.

      The layout of the tables in guest memory defines an ABI. The entries
      are laid out in little endian format as described in the last paragraph.

    KVM_DEV_ARM_ITS_RESTORE_TABLES
      restore the ITS tables from guest RAM to ITS internal structures.

      The GICV3 must be restored before the ITS and all ITS registers but
      the GITS_CTLR must be restored before restoring the ITS tables.

      The GITS_IIDR read-only register must also be restored before
      calling KVM_DEV_ARM_ITS_RESTORE_TABLES as the IIDR revision field

Annotation

Implementation Notes