Parse IOMMU Devices

v1.0.1

Bash script to parse, sort, and display hardware devices by IOMMU group, and return the device drivers and hardware IDs as output.

Download

Table of Contents

• 1. Why?
• 2. Related Projects
• 3. Documentation
• 4. Host Requirements
• 5. Download
• 6. Usage
  • 6.1. Install
  • 6.2. Executable
• 7. Contact
• 8. References

Contents

1. Why?

If you wish to determine if your current machine's hardware specifications are able to support VFIO, then this script is for you. The script allows one to query exactly what hardware you wish to allocate for a VFIO setup, and returns the relevant output to deploy a VFIO setup.

Disclaimer

This script must be run on a system without VFIO setup already. If not, the script output will not show a complete list of valid device drivers. This is due to the fact that a VFIO setup involves replacing the device drivers (example: NVIDIA GPUs use nouveau or nvidia) with the VFIO driver (vfio-pci).

Other outputs such as lists for IOMMU group IDs and hardware IDs are not affected by this.

2. Related Projects

Project	Codeberg	GitHub
Deploy VFIO	link	link
Auto X.Org	link	link
Generate Evdev	link	link
Guest Machine Guide	link	link
Libvirt Hooks	link	link
Parse IOMMU Devices	link	link
Power State Virtual Machine Manager	link	link

3. Documentation

• What is VFIO?
• VFIO Discussion and Support
• Hardware-Passthrough Guide
• Virtual Machine XML Format Guide

4. Host Requirements

Linux.

5. Download

• Download the Latest Release: Codeberg, GitHub

• Download the .zip file:

  1. Viewing from the top of the repository's (current) webpage, click the drop-down icon:
     • ··· on Codeberg.
     • <> Code on GitHub.
  2. Click Download ZIP and save.
  3. Open the .zip file, then extract its contents.

• Clone the repository:

  1. Open a Command Line Interface (CLI).
     • Open a console emulator (for Debian systems: Konsole).
     • Open a existing console: press CTRL + ALT + F2, F3, F4, F5, or F6.
       • To return to the desktop, press CTRL + ALT + F7.
       • F1 is reserved for debug output of the Linux kernel.
       • F7 is reserved for video output of the desktop environment.
       • F8 and above are unused.
  2. Change your directory to your home folder or anywhere safe:
     • cd ~
  3. Clone the repository:
     • git clone https://www.codeberg.org/portellam/parse-iommu-devices
     • git clone https://www.github.com/portellam/parse-iommu-devices

6. Usage

6.1. Install

Installer will copy required files to /usr/bin/local/.

sudo bash installer.sh

6.2. Executable

• From anywhere, execute: parse-iommu-devices

  -h, --help                    Print this help and exit.
  -q, --quiet                   Quiet all output except for comma delimited lists
                                of device drivers and hardware IDs.
  -e, --external                Match IOMMU groups without only internal devices.
  -g, --group [OPTION]          Match IOMMU group ID(s). Comma delimited.
  -i, --internal                Match IOMMU groups without only external devices.
  -n, --name [OPTION]           Match IOMMU group(s) with device name.
                                Comma delimited.
  --reverse-name [OPTION]       Match IOMMU group(s) without device name.
                                Comma delimited.
  -v, --vga-index [OPTION]      Match all IOMMU groups without VGA, and any with
                                VGA which match the index value(s)
                                (not an IOMMU group ID). Comma delimited.

Examples:
  parse-iommu-devices -eq -v 2  Quiet output except for drivers and hardware IDs
                                (of IOMMU groups with external devices) and
                                exclude IOMMU groups with VGA device(s) before and
                                after the second matched group.

7. Contact

Did you encounter a bug? Do you need help? Please visit the Issues page (Codeberg, GitHub).

8. References

1.

PCI passthrough via OVMF. ArchWiki. Accessed June 14, 2024. ^{https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF.}

2.

VFIO - ‘Virtual Function I/O’ - The Linux Kernel Documentation. The linux kernel. Accessed June 14, 2024. ^{https://www.kernel.org/doc/html/latest/driver-api/vfio.html.}

3.

VFIO Discussion and Support. Reddit. Accessed June 14, 2024. ^{https://www.reddit.com/r/VFIO/.}

4.

XML Design Format GitHub - libvirt/libvirt. Accessed June 18, 2024. ^{https://github.com/libvirt/libvirt/blob/master/docs/formatdomain.rst.}

TO DO

• reference and query database for original device drivers.
  • Query manifest of hardware IDs and drivers. If any devices or groups are ever binded to the VFIO driver, the feature should be able to grab the original drivers (should the system's hardware configuration not change).
• use XML file? This will work
• use Internet database? Not sure if this is possible, but lspci mentions something to this effect.