1.. _vkms: 2 3========================================== 4 drm/vkms Virtual Kernel Modesetting 5========================================== 6 7.. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c 8 :doc: vkms (Virtual Kernel Modesetting) 9 10Setup 11===== 12 13The VKMS driver can be setup with the following steps: 14 15To check if VKMS is loaded, run:: 16 17 lsmod | grep vkms 18 19This should list the VKMS driver. If no output is obtained, then 20you need to enable and/or load the VKMS driver. 21Ensure that the VKMS driver has been set as a loadable module in your 22kernel config file. Do:: 23 24 make nconfig 25 26 Go to `Device Drivers> Graphics support` 27 28 Enable `Virtual KMS (EXPERIMENTAL)` 29 30Compile and build the kernel for the changes to get reflected. 31Now, to load the driver, use:: 32 33 sudo modprobe vkms 34 35On running the lsmod command now, the VKMS driver will appear listed. 36You can also observe the driver being loaded in the dmesg logs. 37 38The VKMS driver has optional features to simulate different kinds of hardware, 39which are exposed as module options. You can use the `modinfo` command 40to see the module options for vkms:: 41 42 modinfo vkms 43 44Module options are helpful when testing, and enabling modules 45can be done while loading vkms. For example, to load vkms with cursor enabled, 46use:: 47 48 sudo modprobe vkms enable_cursor=1 49 50To disable the driver, use :: 51 52 sudo modprobe -r vkms 53 54Testing With IGT 55================ 56 57The IGT GPU Tools is a test suite used specifically for debugging and 58development of the DRM drivers. 59The IGT Tools can be installed from 60`here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ . 61 62The tests need to be run without a compositor, so you need to switch to text 63only mode. You can do this by:: 64 65 sudo systemctl isolate multi-user.target 66 67To return to graphical mode, do:: 68 69 sudo systemctl isolate graphical.target 70 71Once you are in text only mode, you can run tests using the --device switch 72or IGT_DEVICE variable to specify the device filter for the driver we want 73to test. IGT_DEVICE can also be used with the run-test.sh script to run the 74tests for a specific driver:: 75 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> 79 80For example, to test the functionality of the writeback library, 81we can run the kms_writeback test:: 82 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 86 87You can also run subtests if you do not want to run the entire test:: 88 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 91 92Testing With KUnit 93================== 94 95KUnit (Kernel unit testing framework) provides a common framework for unit tests 96within the Linux kernel. 97More information in ../dev-tools/kunit/index.rst . 98 99To run the VKMS KUnit tests:: 100 101 tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/vkms/tests 102 103TODO 104==== 105 106If you want to do any of the items listed below, please share your interest 107with VKMS maintainers. 108 109IGT better support 110------------------ 111 112Debugging: 113 114- kms_plane: some test cases are failing due to timeout on capturing CRC; 115 116Virtual hardware (vblank-less) mode: 117 118- VKMS already has support for vblanks simulated via hrtimers, which can be 119 tested with kms_flip test; in some way, we can say that VKMS already mimics 120 the real hardware vblank. However, we also have virtual hardware that does 121 not support vblank interrupt and completes page_flip events right away; in 122 this case, compositor developers may end up creating a busy loop on virtual 123 hardware. It would be useful to support Virtual Hardware behavior in VKMS 124 because this can help compositor developers to test their features in 125 multiple scenarios. 126 127Add Plane Features 128------------------ 129 130There's lots of plane features we could add support for: 131 132- Add background color KMS property[Good to get started]. 133 134- Scaling. 135 136- Additional buffer formats. Low/high bpp RGB formats would be interesting 137 [Good to get started]. 138 139- Async updates (currently only possible on cursor plane using the legacy 140 cursor api). 141 142For all of these, we also want to review the igt test coverage and make sure 143all relevant igt testcases work on vkms. They are good options for internship 144project. 145 146Runtime Configuration 147--------------------- 148 149We want to be able to reconfigure vkms instance without having to reload the 150module. Use/Test-cases: 151 152- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling 153 of compositors). 154 155- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of 156 them first). 157 158- Change output configuration: Plug/unplug screens, change EDID, allow changing 159 the refresh rate. 160 161The currently proposed solution is to expose vkms configuration through 162configfs. All existing module options should be supported through configfs 163too. 164 165Writeback support 166----------------- 167 168- The writeback and CRC capture operations share the use of composer_enabled 169 boolean to ensure vblanks. Probably, when these operations work together, 170 composer_enabled needs to refcounting the composer state to proper work. 171 [Good to get started] 172 173- Add support for cloned writeback outputs and related test cases using a 174 cloned output in the IGT kms_writeback. 175 176- As a v4l device. This is useful for debugging compositors on special vkms 177 configurations, so that developers see what's really going on. 178 179Output Features 180--------------- 181 182- Variable refresh rate/freesync support. This probably needs prime buffer 183 sharing support, so that we can use vgem fences to simulate rendering in 184 testing. Also needs support to specify the EDID. 185 186- Add support for link status, so that compositors can validate their runtime 187 fallbacks when e.g. a Display Port link goes bad. 188 189CRC API Improvements 190-------------------- 191 192- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` 193 194Atomic Check using eBPF 195----------------------- 196 197Atomic drivers have lots of restrictions which are not exposed to userspace in 198any explicit form through e.g. possible property values. Userspace can only 199inquiry about these limits through the atomic IOCTL, possibly using the 200TEST_ONLY flag. Trying to add configurable code for all these limits, to allow 201compositors to be tested against them, would be rather futile exercise. Instead 202we could add support for eBPF to validate any kind of atomic state, and 203implement a library of different restrictions. 204 205This needs a bunch of features (plane compositing, multiple outputs, ...) 206enabled already to make sense. 207