3 ==========================================
4 drm/vkms Virtual Kernel Modesetting
5 ==========================================
7 .. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c
8 :doc: vkms (Virtual Kernel Modesetting)
13 The VKMS driver can be setup with the following steps:
15 To check if VKMS is loaded, run::
19 This should list the VKMS driver. If no output is obtained, then
20 you need to enable and/or load the VKMS driver.
21 Ensure that the VKMS driver has been set as a loadable module in your
22 kernel config file. Do::
26 Go to `Device Drivers> Graphics support`
28 Enable `Virtual KMS (EXPERIMENTAL)`
30 Compile and build the kernel for the changes to get reflected.
31 Now, to load the driver, use::
35 On running the lsmod command now, the VKMS driver will appear listed.
36 You can also observe the driver being loaded in the dmesg logs.
38 The VKMS driver has optional features to simulate different kinds of hardware,
39 which are exposed as module options. You can use the `modinfo` command
40 to see the module options for vkms::
44 Module options are helpful when testing, and enabling modules
45 can be done while loading vkms. For example, to load vkms with cursor enabled,
48 sudo modprobe vkms enable_cursor=1
50 To disable the driver, use ::
57 The IGT GPU Tools is a test suite used specifically for debugging and
58 development of the DRM drivers.
59 The IGT Tools can be installed from
60 `here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .
62 The tests need to be run without a compositor, so you need to switch to text
63 only mode. You can do this by::
65 sudo systemctl isolate multi-user.target
67 To return to graphical mode, do::
69 sudo systemctl isolate graphical.target
71 Once you are in text only mode, you can run tests using the --device switch
72 or IGT_DEVICE variable to specify the device filter for the driver we want
73 to test. IGT_DEVICE can also be used with the run-test.sh script to run the
74 tests for a specific driver::
76 sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"
77 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>
78 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>
80 For example, to test the functionality of the writeback library,
81 we can run the kms_writeback test::
83 sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms"
84 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback
85 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback
87 You can also run subtests if you do not want to run the entire test::
89 sudo ./build/tests/kms_flip --run-subtest basic-plain-flip --device "sys:/sys/devices/platform/vkms"
90 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip
95 If you want to do any of the items listed below, please share your interest
96 with VKMS maintainers.
101 - Investigate: (1) test cases on kms_plane that are failing due to timeout on
102 capturing CRC; (2) when running kms_flip test cases in sequence, some
103 successful individual test cases are failing randomly.
105 - VKMS already has support for vblanks simulated via hrtimers, which can be
106 tested with kms_flip test; in some way, we can say that VKMS already mimics
107 the real hardware vblank. However, we also have virtual hardware that does
108 not support vblank interrupt and completes page_flip events right away; in
109 this case, compositor developers may end up creating a busy loop on virtual
110 hardware. It would be useful to support Virtual Hardware behavior in VKMS
111 because this can help compositor developers to test their features in
117 There's lots of plane features we could add support for:
119 - Real overlay planes, not just cursor.
121 - Full alpha blending on all planes.
125 - Additional buffer formats, especially YUV formats for video like NV12.
126 Low/high bpp RGB formats would also be interesting.
128 - Async updates (currently only possible on cursor plane using the legacy
131 For all of these, we also want to review the igt test coverage and make sure
132 all relevant igt testcases work on vkms.
137 - Syzbot report - WARNING in vkms_gem_free_object:
138 https://syzkaller.appspot.com/bug?extid=e7ad70d406e74d8fc9d0
140 Runtime Configuration
141 ---------------------
143 We want to be able to reconfigure vkms instance without having to reload the
144 module. Use/Test-cases:
146 - Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
149 - Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
152 - Change output configuration: Plug/unplug screens, change EDID, allow changing
155 The currently proposed solution is to expose vkms configuration through
156 configfs. All existing module options should be supported through configfs
162 - The writeback and CRC capture operations share the use of composer_enabled
163 boolean to ensure vblanks. Probably, when these operations work together,
164 composer_enabled needs to refcounting the composer state to proper work.
166 - Add support for cloned writeback outputs and related test cases using a
167 cloned output in the IGT kms_writeback.
169 - As a v4l device. This is useful for debugging compositors on special vkms
170 configurations, so that developers see what's really going on.
175 - Variable refresh rate/freesync support. This probably needs prime buffer
176 sharing support, so that we can use vgem fences to simulate rendering in
177 testing. Also needs support to specify the EDID.
179 - Add support for link status, so that compositors can validate their runtime
180 fallbacks when e.g. a Display Port link goes bad.
185 - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
187 Atomic Check using eBPF
188 -----------------------
190 Atomic drivers have lots of restrictions which are not exposed to userspace in
191 any explicit form through e.g. possible property values. Userspace can only
192 inquiry about these limits through the atomic IOCTL, possibly using the
193 TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
194 compositors to be tested against them, would be rather futile exercise. Instead
195 we could add support for eBPF to validate any kind of atomic state, and
196 implement a library of different restrictions.
198 This needs a bunch of features (plane compositing, multiple outputs, ...)
199 enabled already to make sense.