From 34828732bd94945f2bae0dcaa051bfe329e7bf39 Mon Sep 17 00:00:00 2001
From: lukas <lukas@phyllo.me>
Date: Wed, 2 Apr 2025 17:16:42 +0000
Subject: [PATCH] docs: update gofurther/vfio-pci

---
 gofurther/vfio-pci.md | 84 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 80 insertions(+), 4 deletions(-)

diff --git a/gofurther/vfio-pci.md b/gofurther/vfio-pci.md
index f3022d2..eff7ce9 100644
--- a/gofurther/vfio-pci.md
+++ b/gofurther/vfio-pci.md
@@ -2,7 +2,7 @@
 title: Virtual Function I/O passthrough (vfio-pci)
 description: Pass a physical device to a guest sysstem
 published: true
-date: 2025-04-02T16:07:41.270Z
+date: 2025-04-02T17:16:40.166Z
 tags: 
 editor: markdown
 dateCreated: 2025-04-01T11:18:43.924Z
@@ -20,7 +20,9 @@ dateCreated: 2025-04-01T11:18:43.924Z
 * Make sure the GRUB has been updated after the first boot: 
 `# grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg`
 
-## Collect information on the physical device to share
+## How to share a physical device
+
+### Collect information
 
 * List IOMMU groups and their associated devices (script courtesy of the [Arch Linux wiki](https://wiki.archlinux.org/title/PCI_passthrough_via_OVMF#Ensuring_that_the_groups_are_valid):
 
@@ -70,7 +72,7 @@ In the above example, most devices are well isolated in their own IOMMU group, a
 > In general, but not always, devices associated to a particular IOMMU group have to be passed through a guest system together
 {.is-info}
 
-In our example, Phyllome OS is installed on the Intel SSD 660P NVMe SSD. This device should not be shared with a guest system.
+In our example, Phyllome OS is installed on the Intel SSD 660P NVMe SSD. This device should *not* be shared with a guest system.
 
 | IOMMU Group | Bus | Slot | Function | Device | ID | 
 | --- | --- | --- | --- | --- | --- |
@@ -88,6 +90,8 @@ In our example, Phyllome OS is installed on the Intel SSD 660P NVMe SSD. This de
 | 14 | 0x03 | 0x00 | 0x0 | Intel Corporation Wireless 8260 | 8086:24f3 |
 | 15 | 0x3d | 0x00 | 0x0 | NVMe SSD Controller SM951/PM951 | 144d:a802 |
 
+### Example 1: share a wireless controller
+
 Let's focus on sharing the wireless controller, which is conveniently located on a IOMMU group of its own.
 
 ```
@@ -137,7 +141,79 @@ $ lspci
 09:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
 ``` 
 
-The wireless controller has been attached to bus 9 of the virtual chipset.
+The wireless controller has been successfully attached to bus 9 of the virtual chipset.
+
+### Example 2: share the USB controller
+
+Let's try to share the USB controller, which is in the same IOMMU group as the Thermal Subsystem.
+
+```
+IOMMU Group 3:
+	00:14.0 USB controller [0c03]: Intel Corporation 100 Series/C230 Series Chipset Family USB 3.0 xHCI Controller [8086:a12f] (rev 31)
+	00:14.2 Signal processing controller [1180]: Intel Corporation 100 Series/C230 Series Chipset Family Thermal Subsystem [8086:a131] (rev 31)
+```
+
+| IOMMU Group | Bus | Slot | Function | Device | ID | 
+| --- | --- | --- | --- | --- | --- |
+| **3**   | 0x00 | 0x14 | 0x0 | USB 3.0 xHCI Controller | 8086:a12f |
+| **3**   | 0x00 | 0x14 | 0x2 | Thermal Subsystem | 8086:a131 |
+
+The two devices has to tbe shared with the guest at the same time. Edit the XML file associated to the domain and add the following:
+
+```
+<domain type="kvm">
+[...]
+	<devices>
+[...]
+    <hostdev mode="subsystem" type="pci" managed="yes">
+      <source>
+        <address domain="0x0000" bus="0x00" slot="0x14" function="0x0"/>
+      </source>
+    </hostdev>
+    <hostdev mode="subsystem" type="pci" managed="yes">
+      <source>
+        <address domain="0x0000" bus="0x00" slot="0x14" function="0x2"/>
+      </source>
+    </hostdev>
+ 
+[...]
+	</devices>
+[...]
+</domain>
+```
+
+- Start the domain and have a look inside the guest system that has the physical devices attached to it:
+
+```
+$ lspci
+
+00:00.0 Host bridge: Intel Corporation 82G33/G31/P35/P31 Express DRAM Controller
+[...]
+0b:00.0 PCI bridge: Red Hat, Inc. Device 000e
+0c:03.0 USB controller: Intel Corporation 100 Series/C230 Series Chipset Family USB 3.0 xHCI Controller (rev 31)
+0c:04.0 Signal processing controller: Intel Corporation 100 Series/C230 Series Chipset Family Thermal Subsystem (rev 31)
+``` 
+
+The USB controller and the Thermal Subsystem has been successfully attached to the domain.
+
+- All devices attached to physical USB ports will be automatically shared with the guest system
+
+```
+$ lsusb
+
+Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
+Bus 001 Device 002: ID 1a40:0101 Terminus Technology Inc. Hub
+Bus 001 Device 003: ID 8087:0a2b Intel Corp. Bluetooth wireless interface
+Bus 001 Device 004: ID 046d:c077 Logitech, Inc. Mouse
+Bus 001 Device 005: ID 046d:c31c Logitech, Inc. Keyboard K120
+Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
+``` 
+
+## Troubleshooting
+
+### "Please ensure all devices within the iommu_group are bound to their vfio bus driver."
+
+
 
 ---