| 1 | ==================================
|
| 2 | VFIO - "Virtual Function I/O"
|
| 3 | ==================================
|
| 4 |
|
| 5 | Many modern systems now provide DMA and interrupt remapping facilities
|
| 6 | to help ensure I/O devices behave within the boundaries they've been
|
| 7 | allotted. This includes x86 hardware with AMD-Vi and Intel VT-d,
|
| 8 | POWER systems with Partitionable Endpoints (PEs) and embedded PowerPC
|
| 9 | systems such as Freescale PAMU. The VFIO driver is an IOMMU/device
|
| 10 | agnostic framework for exposing direct device access to userspace, in
|
| 11 | a secure, IOMMU protected environment. In other words, this allows
|
| 12 | safe , non-privileged, userspace drivers.
|
| 13 |
|
| 14 | Why do we want that? Virtual machines often make use of direct device
|
| 15 | access ("device assignment") when configured for the highest possible
|
| 16 | I/O performance. From a device and host perspective, this simply
|
| 17 | turns the VM into a userspace driver, with the benefits of
|
| 18 | significantly reduced latency, higher bandwidth, and direct use of
|
| 19 | bare-metal device drivers .
|
| 20 |
|
| 21 | Some applications, particularly in the high performance computing
|
| 22 | field, also benefit from low-overhead, direct device access from
|
| 23 | userspace. Examples include network adapters (often non-TCP/IP based)
|
| 24 | and compute accelerators. Prior to VFIO, these drivers had to either
|
| 25 | go through the full development cycle to become proper upstream
|
| 26 | driver, be maintained out of tree, or make use of the UIO framework,
|
| 27 | which has no notion of IOMMU protection, limited interrupt support,
|
| 28 | and requires root privileges to access things like PCI configuration
|
| 29 | space.
|
| 30 |
|
| 31 | The VFIO driver framework intends to unify these, replacing both the
|
| 32 | KVM PCI specific device assignment code as well as provide a more
|
| 33 | secure, more featureful userspace driver environment than UIO.
|
| 34 |
|
| 35 | Groups, Devices, and IOMMUs
|
| 36 | ---------------------------
|
| 37 |
|
| 38 | Devices are the main target of any I/O driver. Devices typically
|
| 39 | create a programming interface made up of I/O access, interrupts,
|
| 40 | and DMA. Without going into the details of each of these, DMA is
|
| 41 | by far the most critical aspect for maintaining a secure environment
|
| 42 | as allowing a device read-write access to system memory imposes the
|
| 43 | greatest risk to the overall system integrity.
|
| 44 |
|
| 45 | To help mitigate this risk, many modern IOMMUs now incorporate
|
| 46 | isolation properties into what was, in many cases, an interface only
|
| 47 | meant for translation (ie. solving the addressing problems of devices
|
| 48 | with limited address spaces). With this, devices can now be isolated
|
| 49 | from each other and from arbitrary memory access, thus allowing
|
| 50 | things like secure direct assignment of devices into virtual machines.
|
| 51 |
|
| 52 | This isolation is not always at the granularity of a single device
|
| 53 | though. Even when an IOMMU is capable of this, properties of devices,
|
| 54 | interconnects, and IOMMU topologies can each reduce this isolation.
|
| 55 | For instance, an individual device may be part of a larger multi-
|
| 56 | function enclosure. While the IOMMU may be able to distinguish
|
| 57 | between devices within the enclosure, the enclosure may not require
|
| 58 | transactions between devices to reach the IOMMU. Examples of this
|
| 59 | could be anything from a multi-function PCI device with backdoors
|
| 60 | between functions to a non-PCI-ACS (Access Control Services) capable
|
| 61 | bridge allowing redirection without reaching the IOMMU. Topology
|
| 62 | can also play a factor in terms of hiding devices. A PCIe-to-PCI
|
| 63 | bridge masks the devices behind it, making transaction appear as if
|
| 64 | from the bridge itself. Obviously IOMMU design plays a major factor
|
| 65 | as well.
|
| 66 |
|
| 67 | Therefore, while for the most part an IOMMU may have device level
|
| 68 | granularity, any system is susceptible to reduced granularity. The
|
| 69 | IOMMU API therefore supports a notion of IOMMU groups. A group is
|
| 70 | a set of devices which is isolatable from all other devices in the
|
| 71 | system. Groups are therefore the unit of ownership used by VFIO.
|
| 72 |
|
| 73 | While the group is the minimum granularity that must be used to
|
| 74 | ensure secure user access, it's not necessarily the preferred
|
| 75 | granularity. In IOMMUs which make use of page tables, it may be
|
| 76 | possible to share a set of page tables between different groups,
|
| 77 | reducing the overhead both to the platform (reduced TLB thrashing,
|
| 78 | reduced duplicate page tables), and to the user (programming only
|
| 79 | a single set of translations). For this reason, VFIO makes use of
|
| 80 | a container class, which may hold one or more groups. A container
|
| 81 | is created by simply opening the /dev/vfio/vfio character device.
|
| 82 |
|
| 83 | On its own, the container provides little functionality, with all
|
| 84 | but a couple version and extension query interfaces locked away.
|
| 85 | The user needs to add a group into the container for the next level
|
| 86 | of functionality. To do this, the user first needs to identify the
|
| 87 | group associated with the desired device. This can be done using
|
| 88 | the sysfs links described in the example below. By unbinding the
|
| 89 | device from the host driver and binding it to a VFIO driver, a new
|
| 90 | VFIO group will appear for the group as /dev/vfio/$GROUP, where
|
| 91 | $GROUP is the IOMMU group number of which the device is a member.
|
| 92 | If the IOMMU group contains multiple devices, each will need to
|
| 93 | be bound to a VFIO driver before operations on the VFIO group
|
| 94 | are allowed (it's also sufficient to only unbind the device from
|
| 95 | host drivers if a VFIO driver is unavailable; this will make the
|
| 96 | group available, but not that particular device). TBD - interface
|
| 97 | for disabling driver probing/locking a device.
|
| 98 |
|
| 99 | Once the group is ready, it may be added to the container by opening
|
| 100 | the VFIO group character device (/dev/vfio/$GROUP) and using the
|
| 101 | VFIO_GROUP_SET_CONTAINER ioctl, passing the file descriptor of the
|
| 102 | previously opened container file. If desired and if the IOMMU driver
|
| 103 | supports sharing the IOMMU context between groups, multiple groups may
|
| 104 | be set to the same container. If a group fails to set to a container
|
| 105 | with existing groups, a new empty container will need to be used
|
| 106 | instead.
|
| 107 |
|
| 108 | With a group (or groups) attached to a container, the remaining
|
| 109 | ioctls become available, enabling access to the VFIO IOMMU interfaces.
|
| 110 | Additionally, it now becomes possible to get file descriptors for each
|
| 111 | device within a group using an ioctl on the VFIO group file descriptor.
|
| 112 |
|
| 113 | The VFIO device API includes ioctls for describing the device, the I/O
|
| 114 | regions and their read/write/mmap offsets on the device descriptor, as
|
| 115 | well as mechanisms for describing and registering interrupt
|
| 116 | notifications.
|
| 117 |
|
| 118 | VFIO Usage Example
|
| 119 | ------------------
|
| 120 |
|
| 121 | Assume user wants to access PCI device 0000:06:0d.0::
|
| 122 |
|
| 123 | $ readlink /sys/bus/pci/devices/0000:06:0d.0/iommu_group
|
| 124 | ../../../../kernel/iommu_groups/26
|
| 125 |
|
| 126 | This device is therefore in IOMMU group 26. This device is on the
|
| 127 | pci bus, therefore the user will make use of vfio-pci to manage the
|
| 128 | group::
|
| 129 |
|
| 130 | # modprobe vfio-pci
|
| 131 |
|
| 132 | Binding this device to the vfio-pci driver creates the VFIO group
|
| 133 | character devices for this group::
|
| 134 |
|
| 135 | $ lspci -n -s 0000:06:0d.0
|
| 136 | 06:0d.0 0401: 1102:0002 (rev 08)
|
| 137 | # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
|
| 138 | # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
|
| 139 |
|
| 140 | Now we need to look at what other devices are in the group to free
|
| 141 | it for use by VFIO::
|
| 142 |
|
| 143 | $ ls -l /sys/bus/pci/devices/0000:06:0d.0/iommu_group/devices
|
| 144 | total 0
|
| 145 | lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:00:1e.0 ->
|
| 146 | ../../../../devices/pci0000:00/0000:00:1e.0
|
| 147 | lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.0 ->
|
| 148 | ../../../../devices/pci0000:00/0000:00:1e.0/0000:06:0d.0
|
| 149 | lrwxrwxrwx. 1 root root 0 Apr 23 16:13 0000:06:0d.1 ->
|
| 150 | ../../../../devices/pci0000:00/0000:00:1e.0/0000:06:0d.1
|
| 151 |
|
| 152 | This device is behind a PCIe-to-PCI bridge , therefore we also
|
| 153 | need to add device 0000:06:0d.1 to the group following the same
|
| 154 | procedure as above. Device 0000:00:1e.0 is a bridge that does
|
| 155 | not currently have a host driver, therefore it's not required to
|
| 156 | bind this device to the vfio-pci driver (vfio-pci does not currently
|
| 157 | support PCI bridges).
|
| 158 |
|
| 159 | The final step is to provide the user with access to the group if
|
| 160 | unprivileged operation is desired (note that /dev/vfio/vfio provides
|
| 161 | no capabilities on its own and is therefore expected to be set to
|
| 162 | mode 0666 by the system)::
|
| 163 |
|
| 164 | # chown user:user /dev/vfio/26
|
| 165 |
|
| 166 | The user now has full access to all the devices and the iommu for this
|
| 167 | group and can access them as follows::
|
| 168 |
|
| 169 | int container, group, device, i;
|
| 170 | struct vfio_group_status group_status =
|
| 171 | { .argsz = sizeof(group_status) };
|
| 172 | struct vfio_iommu_type1_info iommu_info = { .argsz = sizeof(iommu_info) };
|
| 173 | struct vfio_iommu_type1_dma_map dma_map = { .argsz = sizeof(dma_map) };
|
| 174 | struct vfio_device_info device_info = { .argsz = sizeof(device_info) };
|
| 175 |
|
| 176 | /* Create a new container */
|
| 177 | container = open("/dev/vfio/vfio", O_RDWR);
|
| 178 |
|
| 179 | if (ioctl(container, VFIO_GET_API_VERSION) != VFIO_API_VERSION)
|
| 180 | /* Unknown API version */
|
| 181 |
|
| 182 | if (!ioctl(container, VFIO_CHECK_EXTENSION, VFIO_TYPE1_IOMMU))
|
| 183 | /* Doesn't support the IOMMU driver we want. */
|
| 184 |
|
| 185 | /* Open the group */
|
| 186 | group = open("/dev/vfio/26", O_RDWR);
|
| 187 |
|
| 188 | /* Test the group is viable and available */
|
| 189 | ioctl(group, VFIO_GROUP_GET_STATUS, &group_status);
|
| 190 |
|
| 191 | if (!(group_status.flags & VFIO_GROUP_FLAGS_VIABLE))
|
| 192 | /* Group is not viable (ie, not all devices bound for vfio) */
|
| 193 |
|
| 194 | /* Add the group to the container */
|
| 195 | ioctl(group, VFIO_GROUP_SET_CONTAINER, &container);
|
| 196 |
|
| 197 | /* Enable the IOMMU model we want */
|
| 198 | ioctl(container, VFIO_SET_IOMMU, VFIO_TYPE1_IOMMU);
|
| 199 |
|
| 200 | /* Get addition IOMMU info */
|
| 201 | ioctl(container, VFIO_IOMMU_GET_INFO, &iommu_info);
|
| 202 |
|
| 203 | /* Allocate some space and setup a DMA mapping */
|
| 204 | dma_map.vaddr = mmap(0, 1024 * 1024, PROT_READ | PROT_WRITE,
|
| 205 | MAP_PRIVATE | MAP_ANONYMOUS, 0, 0);
|
| 206 | dma_map.size = 1024 * 1024;
|
| 207 | dma_map.iova = 0; /* 1MB starting at 0x0 from device view */
|
| 208 | dma_map.flags = VFIO_DMA_MAP_FLAG_READ | VFIO_DMA_MAP_FLAG_WRITE;
|
| 209 |
|
| 210 | ioctl(container, VFIO_IOMMU_MAP_DMA, &dma_map);
|
| 211 |
|
| 212 | /* Get a file descriptor for the device */
|
| 213 | device = ioctl(group, VFIO_GROUP_GET_DEVICE_FD, "0000:06:0d.0");
|
| 214 |
|
| 215 | /* Test and setup the device */
|
| 216 | ioctl(device, VFIO_DEVICE_GET_INFO, &device_info);
|
| 217 |
|
| 218 | for (i = 0; i < device_info.num_regions; i++) {
|
| 219 | struct vfio_region_info reg = { .argsz = sizeof(reg) };
|
| 220 |
|
| 221 | reg.index = i;
|
| 222 |
|
| 223 | ioctl(device, VFIO_DEVICE_GET_REGION_INFO, ®);
|
| 224 |
|
| 225 | /* Setup mappings... read/write offsets, mmaps
|
| 226 | * For PCI devices, config space is a region */
|
| 227 | }
|
| 228 |
|
| 229 | for (i = 0; i < device_info.num_irqs; i++) {
|
| 230 | struct vfio_irq_info irq = { .argsz = sizeof(irq) };
|
| 231 |
|
| 232 | irq.index = i;
|
| 233 |
|
| 234 | ioctl(device, VFIO_DEVICE_GET_IRQ_INFO, &irq);
|
| 235 |
|
| 236 | /* Setup IRQs... eventfds, VFIO_DEVICE_SET_IRQS */
|
| 237 | }
|
| 238 |
|
| 239 | /* Gratuitous device reset and go... */
|
| 240 | ioctl(device, VFIO_DEVICE_RESET);
|
| 241 |
|
| 242 | IOMMUFD and vfio_iommu_type1
|
| 243 | ----------------------------
|
| 244 |
|
| 245 | IOMMUFD is the new user API to manage I/O page tables from userspace.
|
| 246 | It intends to be the portal of delivering advanced userspace DMA
|
| 247 | features (nested translation , PASID , etc.) while also providing
|
| 248 | a backwards compatibility interface for existing VFIO_TYPE1v2_IOMMU use
|
| 249 | cases. Eventually the vfio_iommu_type1 driver, as well as the legacy
|
| 250 | vfio container and group model is intended to be deprecated.
|
| 251 |
|
| 252 | The IOMMUFD backwards compatibility interface can be enabled two ways.
|
| 253 | In the first method, the kernel can be configured with
|
| 254 | CONFIG_IOMMUFD_VFIO_CONTAINER, in which case the IOMMUFD subsystem
|
| 255 | transparently provides the entire infrastructure for the VFIO
|
| 256 | container and IOMMU backend interfaces. The compatibility mode can
|
| 257 | also be accessed if the VFIO container interface, ie. /dev/vfio/vfio is
|
| 258 | simply symlink'd to /dev/iommu. Note that at the time of writing, the
|
| 259 | compatibility mode is not entirely feature complete relative to
|
| 260 | VFIO_TYPE1v2_IOMMU (ex. DMA mapping MMIO) and does not attempt to
|
| 261 | provide compatibility to the VFIO_SPAPR_TCE_IOMMU interface. Therefore
|
| 262 | it is not generally advisable at this time to switch from native VFIO
|
| 263 | implementations to the IOMMUFD compatibility interfaces.
|
| 264 |
|
| 265 | Long term, VFIO users should migrate to device access through the cdev
|
| 266 | interface described below, and native access through the IOMMUFD
|
| 267 | provided interfaces.
|
| 268 |
|
| 269 | VFIO Device cdev
|
| 270 | ----------------
|
| 271 |
|
| 272 | Traditionally user acquires a device fd via VFIO_GROUP_GET_DEVICE_FD
|
| 273 | in a VFIO group.
|
| 274 |
|
| 275 | With CONFIG_VFIO_DEVICE_CDEV=y the user can now acquire a device fd
|
| 276 | by directly opening a character device /dev/vfio/devices/vfioX where
|
| 277 | "X" is the number allocated uniquely by VFIO for registered devices.
|
| 278 |
|
| 279 | The cdev only works with IOMMUFD. Both VFIO drivers and applications
|
| 280 | must adapt to the new cdev security model which requires using
|
| 281 | VFIO_DEVICE_BIND_IOMMUFD to claim DMA ownership before starting to
|
| 282 | actually use the device. Once BIND succeeds then a VFIO device can
|
| 283 | be fully accessed by the user.
|
| 284 |
|
| 285 | VFIO device cdev doesn't rely on VFIO group/container/iommu drivers.
|
| 286 | Hence those modules can be fully compiled out in an environment
|
| 287 | where no legacy VFIO application exists.
|
| 288 |
|
| 289 | So far SPAPR does not support IOMMUFD yet. So it cannot support device
|
| 290 | cdev either.
|
| 291 |
|
| 292 | vfio device cdev access is still bound by IOMMU group semantics, ie. there
|
| 293 | can be only one DMA owner for the group. Devices belonging to the same
|
| 294 | group can not be bound to multiple iommufd_ctx or shared between native
|
| 295 | kernel and vfio bus driver or other driver supporting the driver_managed_dma
|
| 296 | flag. A violation of this ownership requirement will fail at the
|
| 297 | VFIO_DEVICE_BIND_IOMMUFD ioctl, which gates full device access.
|
| 298 |
|
| 299 | Device cdev Example
|
| 300 | -------------------
|
| 301 |
|
| 302 | Assume user wants to access PCI device 0000:6a:01.0::
|
| 303 |
|
| 304 | $ ls /sys/bus/pci/devices/0000:6a:01.0/vfio-dev/
|
| 305 | vfio0
|
| 306 |
|
| 307 | This device is therefore represented as vfio0. The user can verify
|
| 308 | its existence::
|
| 309 |
|
| 310 | $ ls -l /dev/vfio/devices/vfio0
|
| 311 | crw------- 1 root root 511, 0 Feb 16 01:22 /dev/vfio/devices/vfio0
|
| 312 | $ cat /sys/bus/pci/devices/0000:6a:01.0/vfio-dev/vfio0/dev
|
| 313 | 511:0
|
| 314 | $ ls -l /dev/char/511\:0
|
| 315 | lrwxrwxrwx 1 root root 21 Feb 16 01:22 /dev/char/511:0 -> ../vfio/devices/vfio0
|
| 316 |
|
| 317 | Then provide the user with access to the device if unprivileged
|
| 318 | operation is desired::
|
| 319 |
|
| 320 | $ chown user:user /dev/vfio/devices/vfio0
|
| 321 |
|
| 322 | Finally the user could get cdev fd by::
|
| 323 |
|
| 324 | cdev_fd = open("/dev/vfio/devices/vfio0", O_RDWR);
|
| 325 |
|
| 326 | An opened cdev_fd doesn't give the user any permission of accessing
|
| 327 | the device except binding the cdev_fd to an iommufd. After that point
|
| 328 | then the device is fully accessible including attaching it to an
|
| 329 | IOMMUFD IOAS/HWPT to enable userspace DMA::
|
| 330 |
|
| 331 | struct vfio_device_bind_iommufd bind = {
|
| 332 | .argsz = sizeof(bind),
|
| 333 | .flags = 0,
|
| 334 | };
|
| 335 | struct iommu_ioas_alloc alloc_data = {
|
| 336 | .size = sizeof(alloc_data),
|
| 337 | .flags = 0,
|
| 338 | };
|
| 339 | struct vfio_device_attach_iommufd_pt attach_data = {
|
| 340 | .argsz = sizeof(attach_data),
|
| 341 | .flags = 0,
|
| 342 | };
|
| 343 | struct iommu_ioas_map map = {
|
| 344 | .size = sizeof(map),
|
| 345 | .flags = IOMMU_IOAS_MAP_READABLE |
|
| 346 | IOMMU_IOAS_MAP_WRITEABLE |
|
| 347 | IOMMU_IOAS_MAP_FIXED_IOVA,
|
| 348 | .__reserved = 0,
|
| 349 | };
|
| 350 |
|
| 351 | iommufd = open("/dev/iommu", O_RDWR);
|
| 352 |
|
| 353 | bind.iommufd = iommufd;
|
| 354 | ioctl(cdev_fd, VFIO_DEVICE_BIND_IOMMUFD, &bind);
|
| 355 |
|
| 356 | ioctl(iommufd, IOMMU_IOAS_ALLOC, &alloc_data);
|
| 357 | attach_data.pt_id = alloc_data.out_ioas_id;
|
| 358 | ioctl(cdev_fd, VFIO_DEVICE_ATTACH_IOMMUFD_PT, &attach_data);
|
| 359 |
|
| 360 | /* Allocate some space and setup a DMA mapping */
|
| 361 | map.user_va = (int64_t)mmap(0, 1024 * 1024, PROT_READ | PROT_WRITE,
|
| 362 | MAP_PRIVATE | MAP_ANONYMOUS, 0, 0);
|
| 363 | map.iova = 0; /* 1MB starting at 0x0 from device view */
|
| 364 | map.length = 1024 * 1024;
|
| 365 | map.ioas_id = alloc_data.out_ioas_id;
|
| 366 |
|
| 367 | ioctl(iommufd, IOMMU_IOAS_MAP, &map);
|
| 368 |
|
| 369 | /* Other device operations as stated in "VFIO Usage Example" */
|
| 370 |
|
| 371 | VFIO NOIOMMU mode
|
| 372 | -------------------------------------------------------------------------------
|
| 373 | VFIO also supports a no-IOMMU mode, intended for usages where unsafe DMA can
|
| 374 | be performed by userspace drivers w/o physical IOMMU protection. This mode
|
| 375 | is controlled by the parameter:
|
| 376 |
|
| 377 | /sys/module/vfio/parameters/enable_unsafe_noiommu_mode
|
| 378 |
|
| 379 | Upon enabling this mode, with an assigned device, the user will be presented
|
| 380 | with a VFIO group and device file, e.g.::
|
| 381 |
|
| 382 | /dev/vfio/
|
| 383 | |-- devices
|
| 384 | | `-- noiommu-vfioX /* VFIO device cdev */
|
| 385 | |-- noiommu-Y /* VFIO group */
|
| 386 | `-- vfio
|
| 387 |
|
| 388 | The capabilities vary depending on the device programming interface and kernel
|
| 389 | configuration used. The following table summarizes the differences ("Yes" means
|
| 390 | the UAPI is accessible and functional in noiommu mode, "No" means the UAPI is
|
| 391 | not supported):
|
| 392 |
|
| 393 | +-------------------+---------------------+----------------------+
|
| 394 | | Feature | VFIO group | VFIO device cdev |
|
| 395 | +===================+=====================+======================+
|
| 396 | | VFIO device UAPI | Yes | Yes |
|
| 397 | +-------------------+---------------------+----------------------+
|
| 398 | | VFIO container | No | No |
|
| 399 | +-------------------+---------------------+----------------------+
|
| 400 | | IOMMUFD IOAS | No | Yes* |
|
| 401 | +-------------------+---------------------+----------------------+
|
| 402 |
|
| 403 | Note that the VFIO container case includes IOMMUFD provided VFIO compatibility
|
| 404 | interfaces when either CONFIG_VFIO_CONTAINER or CONFIG_IOMMUFD_VFIO_CONTAINER is
|
| 405 | enabled.
|
| 406 |
|
| 407 | * IOMMUFD UAPI is available for VFIO device cdev to pin and map user memory with
|
| 408 | the ability to retrieve physical addresses for DMA command submission.
|
| 409 |
|
| 410 | Kconfig Support Matrix
|
| 411 | ^^^^^^^^^^^^^^^^^^^^^^
|
| 412 |
|
| 413 | The visibility of CONFIG_VFIO_NOIOMMU depends on the combination of
|
| 414 | CONFIG_VFIO_GROUP, CONFIG_VFIO_DEVICE_CDEV, and whether a container backend
|
| 415 | (CONFIG_VFIO_CONTAINER or CONFIG_IOMMUFD_VFIO_CONTAINER) is configured. The
|
| 416 | Kconfig dependencies enforce the following constraints:
|
| 417 |
|
| 418 | - At least one access path (group or cdev) must be available.
|
| 419 | - If VFIO_GROUP is enabled, a container backend is required; otherwise the
|
| 420 | group node would be unusable in noiommu mode.
|
| 421 | - The cdev noiommu path requires CONFIG_GENERIC_ATOMIC64=n because it depends
|
| 422 | on CONFIG_IOMMUFD_NOIOMMU.
|
| 423 |
|
| 424 | The resulting support matrix:
|
| 425 |
|
| 426 | +------+-------+-----------+------+---------+---------------------------+
|
| 427 | | Case | GROUP | Container | CDEV | NOIOMMU | Notes |
|
| 428 | +======+=======+===========+======+=========+===========================+
|
| 429 | | 1 | y | y | n | yes | Group noiommu works |
|
| 430 | +------+-------+-----------+------+---------+---------------------------+
|
| 431 | | 2 | y | n | n | no | Blocked - no container |
|
| 432 | +------+-------+-----------+------+---------+---------------------------+
|
| 433 | | 3 | y | y | y | yes | Both paths work |
|
| 434 | +------+-------+-----------+------+---------+---------------------------+
|
| 435 | | 4 | y | n | y | no | Blocked - no container |
|
| 436 | +------+-------+-----------+------+---------+---------------------------+
|
| 437 | | 5 | n | - | y | yes | Cdev-only works |
|
| 438 | +------+-------+-----------+------+---------+---------------------------+
|
| 439 | | 6 | n | - | n | no | No access path |
|
| 440 | +------+-------+-----------+------+---------+---------------------------+
|
| 441 |
|
| 442 | Container = CONFIG_VFIO_CONTAINER or CONFIG_IOMMUFD_VFIO_CONTAINER (either
|
| 443 | suffices). Case 4 is intentionally blocked: allowing NOIOMMU with GROUP
|
| 444 | enabled but no container would create unusable group nodes. Users who want
|
| 445 | cdev-only noiommu should set CONFIG_VFIO_GROUP=n (case 5).
|
| 446 |
|
| 447 |
|
| 448 | CONFIG_VFIO_GROUP=y, CONFIG_VFIO_DEVICE_CDEV=y, and
|
| 449 | CONFIG_GENERIC_ATOMIC64=y, CONFIG_VFIO_NOIOMMU remains selectable for the
|
| 450 | group path, but no noiommu device cdev is registered. Cdev-only noiommu is
|
| 451 | not selectable on those platforms.
|
| 452 |
|
| 453 | A new IOMMUFD ioctl IOMMU_IOAS_NOIOMMU_GET_PA is added to retrieve the physical
|
| 454 | address for a given IOVA. Although there is no physical DMA remapping hardware,
|
| 455 | IOMMU_IOAS_MAP_FIXED_IOVA is still used to establish IOVA-to-PA mappings in the
|
| 456 | software page table for later IOMMU_IOAS_NOIOMMU_GET_PA lookups.
|
| 457 |
|
| 458 | VFIO User API
|
| 459 | -------------------------------------------------------------------------------
|
| 460 |
|
| 461 | Please see include/uapi/linux/vfio.h for complete API documentation.
|
| 462 |
|
| 463 | VFIO bus driver API
|
| 464 | -------------------------------------------------------------------------------
|
| 465 |
|
| 466 | VFIO bus drivers, such as vfio-pci make use of only a few interfaces
|
| 467 | into VFIO core. When devices are bound and unbound to the driver,
|
| 468 | Following interfaces are called when devices are bound to and
|
| 469 | unbound from the driver::
|
| 470 |
|
| 471 | int vfio_register_group_dev(struct vfio_device *device);
|
| 472 | int vfio_register_emulated_iommu_dev(struct vfio_device *device);
|
| 473 | void vfio_unregister_group_dev(struct vfio_device *device);
|
| 474 |
|
| 475 | The driver should embed the vfio_device in its own structure and use
|
| 476 | vfio_alloc_device() to allocate the structure, and can register
|
| 477 | @init/@release callbacks to manage any private state wrapping the
|
| 478 | vfio_device::
|
| 479 |
|
| 480 | vfio_alloc_device(dev_struct, member, dev, ops);
|
| 481 | void vfio_put_device(struct vfio_device *device);
|
| 482 |
|
| 483 | vfio_register_group_dev() indicates to the core to begin tracking the
|
| 484 | iommu_group of the specified dev and register the dev as owned by a VFIO bus
|
| 485 | driver. Once vfio_register_group_dev() returns it is possible for userspace to
|
| 486 | start accessing the driver, thus the driver should ensure it is completely
|
| 487 | ready before calling it. The driver provides an ops structure for callbacks
|
| 488 | similar to a file operations structure::
|
| 489 |
|
| 490 | struct vfio_device_ops {
|
| 491 | char *name;
|
| 492 | int (*init)(struct vfio_device *vdev);
|
| 493 | void (*release)(struct vfio_device *vdev);
|
| 494 | int (*bind_iommufd)(struct vfio_device *vdev,
|
| 495 | struct iommufd_ctx *ictx, u32 *out_device_id);
|
| 496 | void (*unbind_iommufd)(struct vfio_device *vdev);
|
| 497 | int (*attach_ioas)(struct vfio_device *vdev, u32 *pt_id);
|
| 498 | void (*detach_ioas)(struct vfio_device *vdev);
|
| 499 | int (*open_device)(struct vfio_device *vdev);
|
| 500 | void (*close_device)(struct vfio_device *vdev);
|
| 501 | ssize_t (*read)(struct vfio_device *vdev, char __user *buf,
|
| 502 | size_t count, loff_t *ppos);
|
| 503 | ssize_t (*write)(struct vfio_device *vdev, const char __user *buf,
|
| 504 | size_t count, loff_t *size);
|
| 505 | long (*ioctl)(struct vfio_device *vdev, unsigned int cmd,
|
| 506 | unsigned long arg);
|
| 507 | int (*mmap)(struct vfio_device *vdev, struct vm_area_struct *vma);
|
| 508 | void (*request)(struct vfio_device *vdev, unsigned int count);
|
| 509 | int (*match)(struct vfio_device *vdev, char *buf);
|
| 510 | void (*dma_unmap)(struct vfio_device *vdev, u64 iova, u64 length);
|
| 511 | int (*device_feature)(struct vfio_device *device, u32 flags,
|
| 512 | void __user *arg, size_t argsz);
|
| 513 | };
|
| 514 |
|
| 515 | Each function is passed the vdev that was originally registered
|
| 516 | in the vfio_register_group_dev() or vfio_register_emulated_iommu_dev()
|
| 517 | call above. This allows the bus driver to obtain its private data using
|
| 518 | container_of().
|
| 519 |
|
| 520 | ::
|
| 521 |
|
| 522 | - The init/release callbacks are issued when vfio_device is initialized
|
| 523 | and released.
|
| 524 |
|
| 525 | - The open/close device callbacks are issued when the first
|
| 526 | instance of a file descriptor for the device is created (eg.
|
| 527 | via VFIO_GROUP_GET_DEVICE_FD) for a user session.
|
| 528 |
|
| 529 | - The ioctl callback provides a direct pass through for some VFIO_DEVICE_*
|
| 530 | ioctls.
|
| 531 |
|
| 532 | - The [un]bind_iommufd callbacks are issued when the device is bound to
|
| 533 | and unbound from iommufd.
|
| 534 |
|
| 535 | - The [de]attach_ioas callback is issued when the device is attached to
|
| 536 | and detached from an IOAS managed by the bound iommufd. However, the
|
| 537 | attached IOAS can also be automatically detached when the device is
|
| 538 | unbound from iommufd.
|
| 539 |
|
| 540 | - The read/write/mmap callbacks implement the device region access defined
|
| 541 | by the device's own VFIO_DEVICE_GET_REGION_INFO ioctl.
|
| 542 |
|
| 543 | - The request callback is issued when device is going to be unregistered,
|
| 544 | such as when trying to unbind the device from the vfio bus driver.
|
| 545 |
|
| 546 | - The dma_unmap callback is issued when a range of iovas are unmapped
|
| 547 | in the container or IOAS attached by the device. Drivers which make
|
| 548 | use of the vfio page pinning interface must implement this callback in
|
| 549 | order to unpin pages within the dma_unmap range. Drivers must tolerate
|
| 550 | this callback even before calls to open_device().
|
| 551 |
|
| 552 | PPC64 sPAPR implementation note
|
| 553 | -------------------------------
|
| 554 |
|
| 555 | This implementation has some specifics:
|
| 556 |
|
| 557 | 1) On older systems (POWER7 with P5IOC2/IODA1) only one IOMMU group per
|
| 558 | container is supported as an IOMMU table is allocated at the boot time,
|
| 559 | one table per a IOMMU group which is a Partitionable Endpoint (PE)
|
| 560 | (PE is often a PCI domain but not always).
|
| 561 |
|
| 562 | Newer systems (POWER8 with IODA2) have improved hardware design which allows
|
| 563 | to remove this limitation and have multiple IOMMU groups per a VFIO
|
| 564 | container.
|
| 565 |
|
| 566 | 2) The hardware supports so called DMA windows - the PCI address range
|
| 567 | within which DMA transfer is allowed, any attempt to access address space
|
| 568 | out of the window leads to the whole PE isolation.
|
| 569 |
|
| 570 | 3) PPC64 guests are paravirtualized but not fully emulated. There is an API
|
| 571 | to map/unmap pages for DMA, and it normally maps 1..32 pages per call and
|
| 572 | currently there is no way to reduce the number of calls. In order to make
|
| 573 | things faster, the map/unmap handling has been implemented in real mode
|
| 574 | which provides an excellent performance which has limitations such as
|
| 575 | inability to do locked pages accounting in real time.
|
| 576 |
|
| 577 | 4) According to sPAPR specification, A Partitionable Endpoint (PE) is an I/O
|
| 578 | subtree that can be treated as a unit for the purposes of partitioning and
|
| 579 | error recovery. A PE may be a single or multi-function IOA (IO Adapter), a
|
| 580 | function of a multi-function IOA, or multiple IOAs (possibly including
|
| 581 | switch and bridge structures above the multiple IOAs). PPC64 guests detect
|
| 582 | PCI errors and recover from them via EEH RTAS services, which works on the
|
| 583 | basis of additional ioctl commands.
|
| 584 |
|
| 585 | So 4 additional ioctls have been added:
|
| 586 |
|
| 587 | VFIO_IOMMU_SPAPR_TCE_GET_INFO
|
| 588 | returns the size and the start of the DMA window on the PCI bus.
|
| 589 |
|
| 590 | VFIO_IOMMU_ENABLE
|
| 591 | enables the container. The locked pages accounting
|
| 592 | is done at this point. This lets user first to know what
|
| 593 | the DMA window is and adjust rlimit before doing any real job.
|
| 594 |
|
| 595 | VFIO_IOMMU_DISABLE
|
| 596 | disables the container.
|
| 597 |
|
| 598 | VFIO_EEH_PE_OP
|
| 599 | provides an API for EEH setup, error detection and recovery.
|
| 600 |
|
| 601 | The code flow from the example above should be slightly changed::
|
| 602 |
|
| 603 | struct vfio_eeh_pe_op pe_op = { .argsz = sizeof(pe_op), .flags = 0 };
|
| 604 |
|
| 605 | .....
|
| 606 | /* Add the group to the container */
|
| 607 | ioctl(group, VFIO_GROUP_SET_CONTAINER, &container);
|
| 608 |
|
| 609 | /* Enable the IOMMU model we want */
|
| 610 | ioctl(container, VFIO_SET_IOMMU, VFIO_SPAPR_TCE_IOMMU)
|
| 611 |
|
| 612 | /* Get addition sPAPR IOMMU info */
|
| 613 | vfio_iommu_spapr_tce_info spapr_iommu_info;
|
| 614 | ioctl(container, VFIO_IOMMU_SPAPR_TCE_GET_INFO, &spapr_iommu_info);
|
| 615 |
|
| 616 | if (ioctl(container, VFIO_IOMMU_ENABLE))
|
| 617 | /* Cannot enable container, may be low rlimit */
|
| 618 |
|
| 619 | /* Allocate some space and setup a DMA mapping */
|
| 620 | dma_map.vaddr = mmap(0, 1024 * 1024, PROT_READ | PROT_WRITE,
|
| 621 | MAP_PRIVATE | MAP_ANONYMOUS, 0, 0);
|
| 622 |
|
| 623 | dma_map.size = 1024 * 1024;
|
| 624 | dma_map.iova = 0; /* 1MB starting at 0x0 from device view */
|
| 625 | dma_map.flags = VFIO_DMA_MAP_FLAG_READ | VFIO_DMA_MAP_FLAG_WRITE;
|
| 626 |
|
| 627 | /* Check here is .iova/.size are within DMA window from spapr_iommu_info */
|
| 628 | ioctl(container, VFIO_IOMMU_MAP_DMA, &dma_map);
|
| 629 |
|
| 630 | /* Get a file descriptor for the device */
|
| 631 | device = ioctl(group, VFIO_GROUP_GET_DEVICE_FD, "0000:06:0d.0");
|
| 632 |
|
| 633 | ....
|
| 634 |
|
| 635 | /* Gratuitous device reset and go... */
|
| 636 | ioctl(device, VFIO_DEVICE_RESET);
|
| 637 |
|
| 638 | /* Make sure EEH is supported */
|
| 639 | ioctl(container, VFIO_CHECK_EXTENSION, VFIO_EEH);
|
| 640 |
|
| 641 | /* Enable the EEH functionality on the device */
|
| 642 | pe_op.op = VFIO_EEH_PE_ENABLE;
|
| 643 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 644 |
|
| 645 | /* You're suggested to create additional data struct to represent
|
| 646 | * PE, and put child devices belonging to same IOMMU group to the
|
| 647 | * PE instance for later reference.
|
| 648 | */
|
| 649 |
|
| 650 | /* Check the PE's state and make sure it's in functional state */
|
| 651 | pe_op.op = VFIO_EEH_PE_GET_STATE;
|
| 652 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 653 |
|
| 654 | /* Save device state using pci_save_state().
|
| 655 | * EEH should be enabled on the specified device.
|
| 656 | */
|
| 657 |
|
| 658 | ....
|
| 659 |
|
| 660 | /* Inject EEH error, which is expected to be caused by 32-bits
|
| 661 | * config load.
|
| 662 | */
|
| 663 | pe_op.op = VFIO_EEH_PE_INJECT_ERR;
|
| 664 | pe_op.err.type = EEH_ERR_TYPE_32;
|
| 665 | pe_op.err.func = EEH_ERR_FUNC_LD_CFG_ADDR;
|
| 666 | pe_op.err.addr = 0ul;
|
| 667 | pe_op.err.mask = 0ul;
|
| 668 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 669 |
|
| 670 | ....
|
| 671 |
|
| 672 | /* When 0xFF's returned from reading PCI config space or IO BARs
|
| 673 | * of the PCI device. Check the PE's state to see if that has been
|
| 674 | * frozen.
|
| 675 | */
|
| 676 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 677 |
|
| 678 | /* Waiting for pending PCI transactions to be completed and don't
|
| 679 | * produce any more PCI traffic from/to the affected PE until
|
| 680 | * recovery is finished.
|
| 681 | */
|
| 682 |
|
| 683 | /* Enable IO for the affected PE and collect logs. Usually, the
|
| 684 | * standard part of PCI config space, AER registers are dumped
|
| 685 | * as logs for further analysis.
|
| 686 | */
|
| 687 | pe_op.op = VFIO_EEH_PE_UNFREEZE_IO;
|
| 688 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 689 |
|
| 690 | /*
|
| 691 | * Issue PE reset: hot or fundamental reset. Usually, hot reset
|
| 692 | * is enough. However, the firmware of some PCI adapters would
|
| 693 | * require fundamental reset.
|
| 694 | */
|
| 695 | pe_op.op = VFIO_EEH_PE_RESET_HOT;
|
| 696 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 697 | pe_op.op = VFIO_EEH_PE_RESET_DEACTIVATE;
|
| 698 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 699 |
|
| 700 | /* Configure the PCI bridges for the affected PE */
|
| 701 | pe_op.op = VFIO_EEH_PE_CONFIGURE;
|
| 702 | ioctl(container, VFIO_EEH_PE_OP, &pe_op);
|
| 703 |
|
| 704 | /* Restored state we saved at initialization time. pci_restore_state()
|
| 705 | * is good enough as an example.
|
| 706 | */
|
| 707 |
|
| 708 | /* Hopefully, error is recovered successfully. Now, you can resume to
|
| 709 | * start PCI traffic to/from the affected PE.
|
| 710 | */
|
| 711 |
|
| 712 | ....
|
| 713 |
|
| 714 | 5) There is v2 of SPAPR TCE IOMMU. It deprecates VFIO_IOMMU_ENABLE/
|
| 715 | VFIO_IOMMU_DISABLE and implements 2 new ioctls:
|
| 716 | VFIO_IOMMU_SPAPR_REGISTER_MEMORY and VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY
|
| 717 | (which are unsupported in v1 IOMMU).
|
| 718 |
|
| 719 | PPC64 paravirtualized guests generate a lot of map/unmap requests,
|
| 720 | and the handling of those includes pinning/unpinning pages and updating
|
| 721 | mm::locked_vm counter to make sure we do not exceed the rlimit.
|
| 722 | The v2 IOMMU splits accounting and pinning into separate operations:
|
| 723 |
|
| 724 | - VFIO_IOMMU_SPAPR_REGISTER_MEMORY/VFIO_IOMMU_SPAPR_UNREGISTER_MEMORY ioctls
|
| 725 | receive a user space address and size of the block to be pinned.
|
| 726 | Bisecting is not supported and VFIO_IOMMU_UNREGISTER_MEMORY is expected to
|
| 727 | be called with the exact address and size used for registering
|
| 728 | the memory block. The userspace is not expected to call these often.
|
| 729 | The ranges are stored in a linked list in a VFIO container.
|
| 730 |
|
| 731 | - VFIO_IOMMU_MAP_DMA/VFIO_IOMMU_UNMAP_DMA ioctls only update the actual
|
| 732 | IOMMU table and do not do pinning; instead these check that the userspace
|
| 733 | address is from pre-registered range.
|
| 734 |
|
| 735 | This separation helps in optimizing DMA for guests.
|
| 736 |
|
| 737 | 6) sPAPR specification allows guests to have an additional DMA window(s) on
|
| 738 | a PCI bus with a variable page size. Two ioctls have been added to support
|
| 739 | this: VFIO_IOMMU_SPAPR_TCE_CREATE and VFIO_IOMMU_SPAPR_TCE_REMOVE.
|
| 740 | The platform has to support the functionality or error will be returned to
|
| 741 | the userspace. The existing hardware supports up to 2 DMA windows, one is
|
| 742 | 2GB long, uses 4K pages and called "default 32bit window"; the other can
|
| 743 | be as big as entire RAM, use different page size, it is optional - guests
|
| 744 | create those in run-time if the guest driver supports 64bit DMA.
|
| 745 |
|
| 746 | VFIO_IOMMU_SPAPR_TCE_CREATE receives a page shift, a DMA window size and
|
| 747 | a number of TCE table levels (if a TCE table is going to be big enough and
|
| 748 | the kernel may not be able to allocate enough of physically contiguous
|
| 749 | memory). It creates a new window in the available slot and returns the bus
|
| 750 | address where the new window starts. Due to hardware limitation, the user
|
| 751 | space cannot choose the location of DMA windows.
|
| 752 |
|
| 753 | VFIO_IOMMU_SPAPR_TCE_REMOVE receives the bus start address of the window
|
| 754 | and removes it.
|
| 755 |
|
| 756 | -------------------------------------------------------------------------------
|
| 757 |
|
| 758 |
|
| 759 | initial implementation by Tom Lyon while as Cisco. We've since
|
| 760 | outgrown the acronym, but it's catchy.
|
| 761 |
|
| 762 |
|
| 763 | possible for multi-function devices to have backdoors between
|
| 764 | functions and even for single function devices to have alternative
|
| 765 | access to things like PCI config space through MMIO registers. To
|
| 766 | guard against the former we can include additional precautions in the
|
| 767 | IOMMU driver to group multi-function PCI devices together
|
| 768 | (iommu=group_mf). The latter we can't prevent, but the IOMMU should
|
| 769 | still provide isolation. For PCI, SR-IOV Virtual Functions are the
|
| 770 | best indicator of "well behaved", as these are designed for
|
| 771 | virtualization usage models.
|
| 772 |
|
| 773 |
|
| 774 | assignment that are beyond the scope of VFIO. It's expected that
|
| 775 | future IOMMU technologies will reduce some, but maybe not all, of
|
| 776 | these trade-offs.
|
| 777 |
|
| 778 |
|
| 779 | from either function of the device are indistinguishable to the iommu::
|
| 780 |
|
| 781 | -[0000:00]-+-1e.0-[06]--+-0d.0
|
| 782 | \-0d.1
|
| 783 |
|
| 784 | 00:1e.0 PCI bridge: Intel Corporation 82801 PCI Bridge (rev 90)
|
| 785 |
|
| 786 |
|
| 787 | address translations. This improves the address translation efficiency
|
| 788 | in IOMMU virtualization.
|
| 789 |
|
| 790 |
|
| 791 | Express. It is a prerequisite for Shared Virtual Addressing (SVA)
|
| 792 | and Scalable I/O Virtualization (Scalable IOV).
|