docs: add mdpy mdev vfio display testing guide
Document how to test VFIO display hotplug using the kernel mdpy mdev sample. Reviewed-by: Cédric Le Goater <clg@redhat.com> Reviewed-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-ID: <20260623-b4-ui-v4-6-4656aec3398d@redhat.com>
Marc-André Lureau committed
Jun 23, 2026 at 11:44 UTC
a161949de8ddb00c9a8576b5b6fb1680b339b91a
2 files changed
+91
docs/devel/index-internals.rst
+1
@@ -22,6 +22,7 @@ Details about QEMU's various subsystems including how to add features to them.
22
tracing
23
uefi-vars
24
vfio-iommufd
25
+ vfio-mdpy
26
writing-monitor-commands
27
virtio-backends
28
crypto
docs/devel/vfio-mdpy.rst
new
+90
@@ -0,0 +1,90 @@
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