| 1 | .. SPDX-License-Identifier: GPL-2.0-or-later |
| 2 | |
| 3 | =================================== |
| 4 | Testing VFIO display with mdev mdpy |
| 5 | =================================== |
| 6 | |
| 7 | .. contents:: Table of Contents |
| 8 | |
| 9 | The kernel provides a sample mediated device driver, ``mdpy`` |
| 10 | (``samples/vfio-mdev/mdpy.c``), that exposes a fake framebuffer through the VFIO |
| 11 | display region interface. It can be used to test VFIO display support, including |
| 12 | hotplug, without any real GPU hardware. |
| 13 | |
| 14 | The kernel modules |
| 15 | ================== |
| 16 | |
| 17 | The ``mdpy`` driver depends on the ``mdev`` subsystem. Enable, build and load |
| 18 | the modules. |
| 19 | |
| 20 | The minimal set is:: |
| 21 | |
| 22 | CONFIG_SAMPLE_VFIO_MDEV_MDPY=m |
| 23 | CONFIG_SAMPLE_VFIO_MDEV_MDPY_FB=m # guest framebuffer driver |
| 24 | |
| 25 | CONFIG_VFIO_MDEV is selected automatically. |
| 26 | |
| 27 | Verify that the driver registered successfully: |
| 28 | |
| 29 | .. code-block:: bash |
| 30 | |
| 31 | ls /sys/devices/virtual/mdpy/mdpy/mdev_supported_types/ |
| 32 | |
| 33 | Creating an mdev instance |
| 34 | ========================= |
| 35 | |
| 36 | Available types correspond to different resolutions (e.g. ``mdpy-vga`` |
| 37 | for 640x480, ``mdpy-xga`` for 1024x768, ``mdpy-hd`` for 1920x1080). |
| 38 | |
| 39 | Each mdev instance is identified by a UUID: |
| 40 | |
| 41 | .. code-block:: bash |
| 42 | |
| 43 | uuid=$(uuidgen) |
| 44 | echo "$uuid" > /sys/devices/virtual/mdpy/mdpy/mdev_supported_types/mdpy-xga/create |
| 45 | |
| 46 | To remove the instance later: |
| 47 | |
| 48 | .. code-block:: bash |
| 49 | |
| 50 | echo 1 > /sys/bus/mdev/devices/$uuid/remove |
| 51 | |
| 52 | Make sure your user has the necessary permissions to access the vfio group. |
| 53 | (ex: chmod 666 /dev/vfio/16) |
| 54 | |
| 55 | Starting QEMU |
| 56 | ============= |
| 57 | |
| 58 | Boot-time attachment |
| 59 | -------------------- |
| 60 | |
| 61 | .. code-block:: bash |
| 62 | |
| 63 | qemu-system-x86_64 -machine q35 -m 1G \ |
| 64 | -device vfio-pci,sysfsdev=/sys/bus/mdev/devices/$uuid,display=on \ |
| 65 | -display gtk,gl=on |
| 66 | |
| 67 | Hotplug via HMP |
| 68 | --------------- |
| 69 | |
| 70 | Start QEMU with a PCIe root port (required for PCIe hotplug) and a |
| 71 | monitor: |
| 72 | |
| 73 | .. code-block:: bash |
| 74 | |
| 75 | qemu-system-x86_64 -machine q35 -m 1G \ |
| 76 | -device pcie-root-port,id=rp0,slot=1 \ |
| 77 | -display gtk,gl=on \ |
| 78 | -monitor stdio |
| 79 | |
| 80 | Then at the ``(qemu)`` prompt: |
| 81 | |
| 82 | .. code-block:: none |
| 83 | |
| 84 | device_add vfio-pci,sysfsdev=/sys/bus/mdev/devices/<uuid>,display=on,bus=rp0,id=mdpy0 |
| 85 | |
| 86 | To hot-unplug: |
| 87 | |
| 88 | .. code-block:: none |
| 89 | |
| 90 | device_del mdpy0 |