VFIO‐PCI Passthrough Assistant
The VFIO-PCI Passthrough Assistant is an included utility script within the project.
It can be found and run from the Passthrough Tools menu.
This tool allows you to automatically add your stubbed VFIO-PCI devices to your existing AutoPilot script, and walks you through each step of the process, including automatically detecting devices, and formatting the custom QEMU arguments for your specific devices.
Before you begin this misadventure, you should ideally make sure that you and your system are ready. There is a built in check tool to assist you with this.
You should return to this guide only when ALL of the following are complete:
- Kernel is compatible and set up to load the required modules
- Your OS is installed and booted in UEFI mode
- Your host supports IOMMU and you've added the relevant kernel modules and parameters
- The devices you want to pass through are confined to their own IOMMU groups
- The devices are bound to the
vfio-pcikernel driver using the VFIO kernel parameters
Please see the comprehensive passthrough guide for a full explanation of these tasks.
Once the assistant successfully detects devices bound to the vfio-pci kernel driver, you will be presented with a menu displaying the total number of detected devices.
IMAGE
After continuing, a list of the detected devices will be shown under the AVAILABLE DEVICES heading. Each device will be assigned a number from 1 onwards.
To select devices to pass through to your VM, type each device entry's corresponding number followed by ENTER. As you select devices, they will light up and move from under the AVAILABLE DEVICES heading to under the SELECTED DEVICES heading.
To deselect a device, type its corresponding number again to move it back.
Once you have selected the devices you want, type the word done and press ENTER.
After selecting your devices to pass through, you will be shown a summary screen allowing you to confirm your selections. The names of each device will be shown, along with a preview of the QEMU argument that will be generated for it.
IMAGE
To confirm your selections, type Y and press ENTER. If you'd like to go back, type N and press ENTER.
There are 3 options you can choose from after confirming your device selections:
- Auto-detected script (recommended) This is by far the easiest and most convenient option. If you generated your boot script using AutoPilot, the passthrough assistant will try to detect this automatically, and offer to add the new passthrough devices to this script for you.
- Manually selected script If the passthrough assistant fails to automatically find an AutoPilot-generated boot script - or you want to add the devices to a different script - you can enter the path to the desired script file. It MUST have been generated by AutoPilot at some point - but does not have to be from the current installation or version of ULTMOS.
- Save to file If you'd rather save the generated QEMU device arguments for a later time, you can do this too. All of the generated lines will be saved to a text file in the root of the repo directory. You can use this to copy and paste the lines into other non-AutoPilot scripts.
Select an option when prompted and press ENTER. The assistant will perform your chosen method.
After confirming your device selections in step 2, you may receive another screen informing you that the assistant has detected one or more of your selections may be a GPU.
Some GPUs require specific VBIOS ROM files to be used with VFIO-PCI passthrough. The assistant allows you to enter the file path of a ROM file if you need it. The file is automatically copied to the roms directory in your repo folder.
However, if your GPU does NOT need a ROM file (most likely), you can type skip and press ENTER to continue without one.
Some devices are known to have issues or otherwise interfere with the macOS boot process - such as AMD's Navi-based GPUs. The passthrough assistant is designed to try and detect these devices, and offer automatic boot patching through integration with the macOS Boot Argument Editor - if patches are available.
If problematic devices are detected - and relevant patches are available - the assistant will offer you the chance to automatically patch your OpenCore image immediately to ensure a seamless passthrough experience.
It is just an offer, and if you'd rather do it yourself later, you'll always have the option to skip. You can apply the same available patches at any time using the macOS Boot Argument Editor, found in the Extras menu.
After passing through devices that inhibit the operation of virtual input devices - such as the virtual mouse and keyboard emulation - the assistant will alert you of this and offer to run the USB passthrough assistant.
This allows you to add physical input devices connected to your host, in order to interact with the virtual machine without the need for input emulation.
As always, this is optional, and the USB passthrough assistant can be run at any time from the passthrough tools menu.
Written and maintained by Coopydood.
You can contribute to documentation, too!