Identify and Configure PCI Passthrough by Vendor ID

Updated

Introduction

This article is an addendum to Identify and Configure USB Devices for PCI Passthrough, and explains how to identify a vendor id or product id and configure it as a new entity in your hardware model JSON file.

As of September 2024, both EVE-OS and ZEDEDA Cloud support the option of USB passthrough either as a whole controller or an individual device. Originally, USB port passthrough support was provided for USB controllers using PCI device passthrough. These adapters were identified in ZEDEDA Cloud as IO_TYPE USB. Then USB device passthrough was added in addition to the existing USB controller PCI passthrough support. To differentiate between these two cases more clearly, there are now two additional IO device categories: IO_TYPE USB_Controller and IO_TYPE USB_Device. 

The supported USB types follow:

  • IO_TYPE_USB_CONTROLLER: represents the PCI controller 
  • IO_TYPE_USB_DEVICE: represents a USB device such as keyboard, mouse, usb stick
  • IO_TYPE_USB: represents the original method of configuring a USB controller using PCI device passthrough (remains supported for backward compatibility)

With the introduction of separate controller and device IO types, you gain finer-grained control over a single controller rather than dependency on multiple PCI controllers. This is needed because of Input-Output Memory Management Unit (IOMMU) groups. For example, with the original method of PCI device passthrough, if you have a PCI controller (USB card) and another PCI card in the same IOMMU group (as defined as assigngrp in the model manifest) and the latter card is passed through, then the USB devices on the USB card cannot be passed through anymore. Individual devices connected to USB ports (on the same controller) cannot be passed through to different virtual machines. With separate controller and device IO types, you can specify exactly what to pass through to where.

 

This is a series of articles. You will likely follow them in this order.

  1. Create a Hardware Model 
  2. Use the ZEDEDA CLI to Upload a Hardware Model
  3. Use ZCLI to Update a Hardware Model Logo

Prerequisites

Caveats

  • Devices connected to a USB hub can be forwarded, but USB hubs themselves cannot be forwarded.
  • The physical port on the device might have a different bus number and port number depending on the USB version of the connected device.
  • It currently only works with Quick Emulator (QEMU).
  • Passthrough of devices that do PCI over Thunderbolt/USB4 is not supported (might work with PCI passthrough though).

Implementation

The implementation is using passthrough of USB devices as follows:

  1. Bus number - mostly corresponds with the PCI address of the controller
  2. Device number - a simple counter to enumerate plugging in USB devices, for example:
    1. insert a mouse → device number 3
    2. insert a keyboard → device number 4
    3. remove the mouse
    4. insert the same mouse again → device number 5

Define a Hardware Model with USB Passthrough

See Create a Hardware Model for more details about commands and creating hardware models in general. 

Configure Passthrough by USB vendor id or product id

Use the lsusb command to see the connected USB devices. The following output shows that the vendor id is 045e (for example, from the Microsoft List of USB IDs) and the product id is 0823.

Bus 003 Device 033: ID 045e:0823 Microsoft Corp. Classic IntelliMouse

Edit the model manifest

The vendor and product IDs can be added to the model manifest as usbproduct to represent this device.

"ioMemberList": [
    	{
        	"ztype": "IO_TYPE_USB_CONTROLLER",
        	"phylabel": "USB Controller Phy",
        	"assigngrp": "USB-controller-1",
        	"phyaddrs": {
            	"PciLong": "0000:14:00.0",
        	},
        	"logicallabel": "USB Controller",
        	"usagePolicy": { }
    	},
    	{
        	"ztype": "IO_TYPE_USB_DEVICE",
        	"phylabel": "IntelliMouse",
        	"assigngrp": "USB",
        	"phyaddrs": {
            	"usbproduct": "045e:0823",
        	},
        	"logicallabel": "IntelliMouse",	 
        	"parentassigngrp": "USB-controller-1"
    	}

Upload the hardware model

Upload the json file via ZCLI and confirm updates are reflected in the Adapters section of the Marketplace > Device Model section in the ZEDEDA GUI.

Next Steps

This is a series of articles. You will likely follow them in this order.

  1. Create a Hardware Model 
  2. Use the ZEDEDA CLI to Upload a Hardware Model
  3. Use ZCLI to Update a Hardware Model Logo
Was this article helpful?
0 out of 0 found this helpful