1.. SPDX-License-Identifier: GPL-2.0 2 3=================== 4VFIO virtual device 5=================== 6 7Device types supported: 8 9 - KVM_DEV_TYPE_VFIO 10 11Only one VFIO instance may be created per VM. The created device 12tracks VFIO files (group or device) in use by the VM and features 13of those groups/devices important to the correctness and acceleration 14of the VM. As groups/devices are enabled and disabled for use by the 15VM, KVM should be updated about their presence. When registered with 16KVM, a reference to the VFIO file is held by KVM. 17 18Groups: 19 KVM_DEV_VFIO_FILE 20 alias: KVM_DEV_VFIO_GROUP 21 KVM_DEV_VFIO_PVIOMMU 22 23KVM_DEV_VFIO_FILE attributes: 24 KVM_DEV_VFIO_FILE_ADD: Add a VFIO file (group/device) to VFIO-KVM device 25 tracking 26 27 kvm_device_attr.addr points to an int32_t file descriptor for the 28 VFIO file. 29 30 KVM_DEV_VFIO_FILE_DEL: Remove a VFIO file (group/device) from VFIO-KVM 31 device tracking 32 33 kvm_device_attr.addr points to an int32_t file descriptor for the 34 VFIO file. 35 36KVM_DEV_VFIO_GROUP (legacy kvm device group restricted to the handling of VFIO group fd): 37 KVM_DEV_VFIO_GROUP_ADD: same as KVM_DEV_VFIO_FILE_ADD for group fd only 38 39 KVM_DEV_VFIO_GROUP_DEL: same as KVM_DEV_VFIO_FILE_DEL for group fd only 40 41 KVM_DEV_VFIO_GROUP_SET_SPAPR_TCE: attaches a guest visible TCE table 42 allocated by sPAPR KVM. 43 kvm_device_attr.addr points to a struct:: 44 45 struct kvm_vfio_spapr_tce { 46 __s32 groupfd; 47 __s32 tablefd; 48 }; 49 50 where: 51 52 - @groupfd is a file descriptor for a VFIO group; 53 - @tablefd is a file descriptor for a TCE table allocated via 54 KVM_CREATE_SPAPR_TCE. 55 56The FILE/GROUP_ADD operation above should be invoked prior to accessing the 57device file descriptor via VFIO_GROUP_GET_DEVICE_FD in order to support 58drivers which require a kvm pointer to be set in their .open_device() 59callback. It is the same for device file descriptor via character device 60open which gets device access via VFIO_DEVICE_BIND_IOMMUFD. For such file 61descriptors, FILE_ADD should be invoked before VFIO_DEVICE_BIND_IOMMUFD 62to support the drivers mentioned in prior sentence as well. 63 64KVM_DEV_VFIO_PVIOMMU attributes: 65 KVM_DEV_VFIO_PVIOMMU_ATTACH: Create and attach a pvIOMMU instance to the 66 KVM VM associated with this device, returns a file descriptor "pviommufd" 67 for this IOMMU which supports some IOCTLs. 68 69 KVM_DEV_VFIO_PVIOMMU_GET_INFO: Retrieve information about IOMMUs for a VFIO 70 devicefd, using the following struct: 71 72 struct kvm_vfio_iommu_info { 73 __u32 size; 74 __s32 device_fd; 75 __u32 out_nr_sids; 76 __u32 __reserved; 77 }; 78 79 Where kvm_vfio_iommu_info.device_fd the input VFIO device ID, and 80 kvm_vfio_iommu_info.out_nr_sids is the number stream IDs(endpoint) for 81 this device, this similar to VFIO_DEVICE_GET_IRQ_INFO which returns the 82 number of irqs for a VFIO device. 83 size is added to allow the struct to be extended, while __reserved 84 must be zero. 85 86 The rest of the IOCTLs are used to configure the pvIOMMU are part of 87 the pviommufd returned from the attach operation: 88 KVM_PVIOMMU_SET_CONFIG: Configure pvIOMMU for an endpoint for a device, 89 where the input struct: 90 91 struct kvm_vfio_iommu_config { 92 __u32 size; 93 __s32 device_fd; 94 __u32 sid_idx; 95 __u32 vsid; 96 __u32 __reserved; 97 }; 98 99 kvm_vfio_iommu_config.device_fd is the VFIO devicefd, 100 kvm_vfio_iommu_config.sid_idx is a valid index based on number of sids 101 from KVM_DEV_VFIO_PVIOMMU_GET_INFO. 102 And kvm_vfio_iommu_config.vsid is the virtual sid seen by the guest, 103 It is the VMM responsibility to describe this to the guest, the pvIOMMU 104 would translate an IOMMU request with this vsid to the physical SID of 105 the device for the index specified. 106 This is similar to VFIO IOCTL VFIO_DEVICE_SET_IRQS but for the IOMMU. 107 size is added to allow the struct to be extended, while __reserved 108 must be zero. 109