Documentation/virt/kvm/devices/vfio.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================
   4 VFIO virtual device
   5 ===================
   6
   7 Device types supported:
   8
   9   - KVM_DEV_TYPE_VFIO
  10
  11 Only one VFIO instance may be created per VM.  The created device
  12 tracks VFIO files (group or device) in use by the VM and features
  13 of those groups/devices important to the correctness and acceleration
  14 of the VM.  As groups/devices are enabled and disabled for use by the
  15 VM, KVM should be updated about their presence.  When registered with
  16 KVM, a reference to the VFIO file is held by KVM.
  17
  18 Groups:
  19   KVM_DEV_VFIO_FILE
  20         alias: KVM_DEV_VFIO_GROUP
  21
  22 KVM_DEV_VFIO_FILE attributes:
  23   KVM_DEV_VFIO_FILE_ADD: Add a VFIO file (group/device) to VFIO-KVM device
  24         tracking
  25
  26         kvm_device_attr.addr points to an int32_t file descriptor for the
  27         VFIO file.
  28
  29   KVM_DEV_VFIO_FILE_DEL: Remove a VFIO file (group/device) from VFIO-KVM
  30         device tracking
  31
  32         kvm_device_attr.addr points to an int32_t file descriptor for the
  33         VFIO file.
  34
  35 KVM_DEV_VFIO_GROUP (legacy kvm device group restricted to the handling of VFIO group fd):
  36   KVM_DEV_VFIO_GROUP_ADD: same as KVM_DEV_VFIO_FILE_ADD for group fd only
  37
  38   KVM_DEV_VFIO_GROUP_DEL: same as KVM_DEV_VFIO_FILE_DEL for group fd only
  39
  40   KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table
  41         allocated by sPAPR KVM.
  42         kvm_device_attr.addr points to a struct::
  43
  44                 struct kvm_vfio_spapr_tce {
  45                         __s32   groupfd;
  46                         __s32   tablefd;
  47                 };
  48
  49         where:
  50
  51         - @groupfd is a file descriptor for a VFIO group;
  52         - @tablefd is a file descriptor for a TCE table allocated via
  53           KVM_CREATE_SPAPR_TCE.
  54
  55 The FILE/GROUP_ADD operation above should be invoked prior to accessing the
  56 device file descriptor via VFIO_GROUP_GET_DEVICE_FD in order to support
  57 drivers which require a kvm pointer to be set in their .open_device()
  58 callback.  It is the same for device file descriptor via character device
  59 open which gets device access via VFIO_DEVICE_BIND_IOMMUFD.  For such file
  60 descriptors, FILE_ADD should be invoked before VFIO_DEVICE_BIND_IOMMUFD
  61 to support the drivers mentioned in prior sentence as well.