1# Cloud Hypervisor VFIO HOWTO 2 3VFIO (Virtual Function I/O) is a kernel framework that exposes direct device 4access to userspace. `cloud-hypervisor`, as many VMMs do, uses the VFIO 5framework to directly assign host physical devices to the guest workloads. 6 7## Direct Device Assignment with Cloud Hypervisor 8 9To assign a device to a `cloud-hypervisor` guest, the device needs to be managed 10by the VFIO kernel drivers. However, by default, a host device will be bound to 11its native driver, which is not the VFIO one. 12 13As a consequence, a device must be unbound from its native driver before passing 14it to `cloud-hypervisor` for assigning it to a guest. 15 16### Example 17 18In this example we're going to assign a PCI memory card (SD, MMC, etc) reader 19from the host in a cloud hypervisor guest. 20 21`cloud-hypervisor` only supports assigning PCI devices to its guests. `lspci` 22helps with identifying PCI devices on the host: 23 24``` 25$ lspci 26[...] 2701:00.0 Unassigned class [ff00]: Realtek Semiconductor Co., Ltd. RTS525A PCI Express Card Reader (rev 01) 28[...] 29``` 30 31Here we see that our device is on bus 1, slot 0 and function 0 (`01:00.0`). 32 33Now that we have identified the device, we must unbind it from its native driver 34(`rtsx_pci`) and bind it to the VFIO driver instead (`vfio_pci`). 35 36First we add VFIO support to the host: 37 38``` 39$ sudo modprobe vfio_pci 40$ sudo modprobe vfio_iommu_type1 allow_unsafe_interrupts 41``` 42 43Then we unbind it from its native driver: 44 45``` 46$ echo 0000:01:00.0 > /sys/bus/pci/devices/0000\:01\:00.0/driver/unbind 47``` 48 49And finally we bind it to the VFIO driver. To do that we first need to get the 50device's VID (Vendor ID) and PID (Product ID): 51 52``` 53$ lspci -n -s 01:00.0 5401:00.0 ff00: 10ec:525a (rev 01) 55 56$ echo 10ec 525a > /sys/bus/pci/drivers/vfio-pci/new_id 57$ echo 0000:01:00.0 > /sys/bus/pci/drivers/vfio-pci/bind 58``` 59 60Now the device is managed by the VFIO framework. 61 62The final step is to give that device to `cloud-hypervisor` to assign it to the 63guest. This is done by using the `--device` command line option. This option 64takes the device's sysfs path as an argument. In our example it is 65`/sys/bus/pci/devices/0000:01:00.0/`: 66 67``` 68./target/debug/cloud-hypervisor \ 69 --kernel ~/vmlinux \ 70 --disk path=~/focal-server-cloudimg-amd64.raw \ 71 --console off \ 72 --serial tty \ 73 --cmdline "console=ttyS0 root=/dev/vda1 rw" \ 74 --cpus 4 \ 75 --memory size=512M \ 76 --device path=/sys/bus/pci/devices/0000:01:00.0/ 77``` 78 79The guest kernel will then detect the card reader on its PCI bus and provided 80that support for this device is enabled, it will probe and enable it for the 81guest to use. 82