Crate vfio_ioctls

Virtual Function I/O (VFIO) API

Many modern system now provide DMA and interrupt remapping facilities to help ensure I/O devices behave within the boundaries they’ve been allotted. This includes x86 hardware with AMD-Vi and Intel VT-d, POWER systems with Partitionable Endpoints (PEs) and embedded PowerPC systems such as Freescale PAMU. The VFIO driver is an IOMMU/device agnostic framework for exposing direct device access to userspace, in a secure, IOMMU protected environment. In other words, the VFIO framework allows safe, non-privileged, userspace drivers.

Why do we want that? Virtual machines often make use of direct device access (“device assignment”) when configured for the highest possible I/O performance. From a device and host perspective, this simply turns the VM into a userspace driver, with the benefits of significantly reduced latency, higher bandwidth, and direct use of bare-metal device drivers.

Devices are the main target of any I/O driver. Devices typically create a programming interface made up of I/O access, interrupts, and DMA. Without going into the details of each of these, DMA is by far the most critical aspect for maintaining a secure environment as allowing a device read-write access to system memory imposes the greatest risk to the overall system integrity.

To help mitigate this risk, many modern IOMMUs now incorporate isolation properties into what was, in many cases, an interface only meant for translation (ie. solving the addressing problems of devices with limited address spaces). With this, devices can now be isolated from each other and from arbitrary memory access, thus allowing things like secure direct assignment of devices into virtual machines.

While for the most part an IOMMU may have device level granularity, any system is susceptible to reduced granularity. The IOMMU API therefore supports a notion of IOMMU groups. A group is a set of devices which is isolatable from all other devices in the system. Groups are therefore the unit of ownership used by VFIO.

While the group is the minimum granularity that must be used to ensure secure user access, it’s not necessarily the preferred granularity. In IOMMUs which make use of page tables, it may be possible to share a set of page tables between different groups, reducing the overhead both to the platform (reduced TLB thrashing, reduced duplicate page tables), and to the user (programming only a single set of translations). For this reason, VFIO makes use of a container class, which may hold one or more groups. A container is created by simply opening the /dev/vfio/vfio character device.

This crate is a safe wrapper around the Linux kernel’s VFIO interfaces, which offering safe wrappers for:

• VFIO Container using the VfioContainer structure
• VFIO Device using the VfioDevice structure

Platform support

• x86_64

NOTE: The list of available ioctls is not exhaustive.

Structs

• VfioContainer
  A safe wrapper over a VFIO container object.
• VfioDevice
  A safe wrapper over a Vfio device to access underlying hardware device.
• VfioGroup
  A safe wrapper over a VFIO group object.
• VfioIrq
  Information about VFIO interrupts.
• VfioRegion
  Information about VFIO MMIO region.
• VfioRegionInfoCapNvlink2Lnkspd
  Carry NVLink link speed information
• VfioRegionInfoCapNvlink2Ssatgt
  Carry NVLink SSA TGT information
• VfioRegionInfoCapSparseMmap
  List of sparse mmap areas
• VfioRegionInfoCapType
  Represent a specific device by providing type and subtype
• VfioRegionSparseMmapArea
  Represent one area of the sparse mmap

Enums

• VfioError
  Error codes for VFIO operations.
• VfioRegionInfoCap
  List of capabilities that can be related to a region.

Type Aliases

• Result
  Specialized version of Result for VFIO subsystem.