doc: Generic vfio setup for passthrough

Signed-off-by: Jon Sahlberg <[email protected]>

docs/src/SUMMARY.md

@@ -1,3 +1,8 @@
+<!--
+    Copyright 2022-2023 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
 # Summary
 
 # Overview
@@ -23,6 +28,7 @@
     - [Modules Options](ref_impl/modules_options.md)
 - [Technologies](technologies/technologies.md)
     - [Passthrough](technologies/passthrough.md)
+        - [Binding Device to VFIO Driver](technologies/vfio.md)
         - [NVIDIA Jetson AGX Orin: UART Passthrough](technologies/nvidia_agx_pt_uart.md)
         - [NVIDIA Jetson AGX Orin: PCIe Passthrough](technologies/nvidia_agx_pt_pcie.md)
     - [Hypervisor Options](technologies/hypervisor_options.md)

docs/src/technologies/passthrough.md

@@ -8,6 +8,9 @@
 Devices passthrough to virtual machines (VM) allows us to isolate the device drivers 
 and their memory access in one or several VMs. This reduces the Trusted Code Base (TCB) in the host, due to the passed-through device drivers can be removed completely from the host kernel.
 
+Whether the device platform is x86 or ARM, the passthrough device needs to be bound to the VFIO device driver by the host system before it can be passed through to the guest environment. For more information, see [Binding Device to VFIO Driver](vfio.md).
+
+
 Our current supported passthrough devices implementations:
 - [NVIDIA Jetson AGX Orin: UART Passthrough](nvidia_agx_pt_uart.md)
-- [NVIDIA Jetson AGX Orin: PCIe Passthrough](nvidia_agx_pt_pcie.md)
+- [NVIDIA Jetson AGX Orin: PCIe Passthrough](nvidia_agx_pt_pcie.md)

docs/src/technologies/vfio.md

@@ -0,0 +1,70 @@
+<!--
+    Copyright 2022-2023 TII (SSRC) and the Ghaf contributors
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Binding Devices to VFIO Driver to Allow Passthrough
+
+An example of binding a PCI device to the VFIO driver manually:
+
+```
+export DEVICE="0001:01:00.0"
+export VENDOR_ID=$(cat /sys/bus/pci/devices/$DEVICE/vendor)
+export DEVICE_ID=$(cat /sys/bus/pci/devices/$DEVICE/device)
+
+echo "$DEVICE" > /sys/bus/pci/devices/$DEVICE/driver/unbind
+
+echo "$VENDOR_ID $DEVICE_ID" > /sys/bus/pci/drivers/vfio-pci/new_id
+```
+
+Similar approach also works for platform devices. The device path for platform
+ devices is `/sys/bus/platform/devices/$DEVICE/`.
+
+```
+export DEVICE="31d0000.serial"
+echo vfio-platform > /sys/bus/platform/devices/$DEVICE/driver_override
+echo "$DEVICE" > /sys/bus/platform/drivers/vfio-platform/bind
+```
+
+
+## Using driverctl Package
+
+[driverctl](https://gitlab.com/driverctl/driverctl) is an open-source device
+driver control utility for Linux systems. With `driverctl` it is easier to set
+up VFIO or change the driver for a device:
+
+```
+export DEVICE="0001:01:00.0"
+driverctl --nosave set-override ${DEVICE} vfio-pci
+```
+
+or for platform bus device passthrough
+```
+export DEVICE="31d0000.serial"
+driverctl --nosave --bus platform set-override ${DEVICE} vfio-platform
+```
+
+It is important to note that by default `driverctl` stores the set driver
+overrides and reactivates the override after a device reboot. With VFIO this
+can cause issues since some hardware devices may be required while the device
+starts up. This behavior can be effected by using the `--nosave` option as in
+the example above so that the override is reset back to default at reboot.
+
+The `driverctl` tool also features a way to list devices based on their bus type
+ with the `list-devices` command.
+
+ ```
+# Default usage of the tool is for pci bus
+driverctl list-devices
+
+# Using command line option --bus platform sets the usage for platform bus
+driverctl --bus platform list-devices
+```
+
+driverctl can also reset the default driver by using the `unset-override`
+command.
+
+```
+export DEVICE="0001:01:00.0"
+driverctl unset-override ${DEVICE}
+```