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 10 Setup 11 ===== 12 13 The VKMS driver can be setup with the following steps: 14 15 To check if VKMS is loaded, run:: 16 17 lsmod | grep vkms 18 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:: 23 24 make nconfig 25 26 Go to `Device Drivers> Graphics support` 27 28 Enable `Virtual KMS (EXPERIMENTAL)` 29 30 Compile and build the kernel for the changes to get reflected. 31 Now, to load the driver, use:: 32 33 sudo modprobe vkms 34 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. 37 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:: 41 42 modinfo vkms 43 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, 46 use:: 47 48 sudo modprobe vkms enable_cursor=1 49 50 To disable the driver, use :: 51 52 sudo modprobe -r vkms 53 54 Testing With IGT 55 ================ 56 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>`_ . 61 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:: 64 65 sudo systemctl isolate multi-user.target 66 67 To return to graphical mode, do:: 68 69 sudo systemctl isolate graphical.target 70 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:: 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 80 For example, to test the functionality of the writeback library, 81 we 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 87 You 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 92 TODO 93 ==== 94 95 If you want to do any of the items listed below, please share your interest 96 with VKMS maintainers. 97 98 IGT better support 99 ------------------ 100 101 Debugging: 102 103 - kms_plane: some test cases are failing due to timeout on capturing CRC; 104 105 Virtual hardware (vblank-less) mode: 106 107 - VKMS already has support for vblanks simulated via hrtimers, which can be 108 tested with kms_flip test; in some way, we can say that VKMS already mimics 109 the real hardware vblank. However, we also have virtual hardware that does 110 not support vblank interrupt and completes page_flip events right away; in 111 this case, compositor developers may end up creating a busy loop on virtual 112 hardware. It would be useful to support Virtual Hardware behavior in VKMS 113 because this can help compositor developers to test their features in 114 multiple scenarios. 115 116 Add Plane Features 117 ------------------ 118 119 There's lots of plane features we could add support for: 120 121 - Add background color KMS property[Good to get started]. 122 123 - Scaling. 124 125 - Additional buffer formats, especially YUV formats for video like NV12. 126 Low/high bpp RGB formats would also be interesting. 127 128 - Async updates (currently only possible on cursor plane using the legacy 129 cursor api). 130 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. They are good options for internship 133 project. 134 135 Runtime Configuration 136 --------------------- 137 138 We want to be able to reconfigure vkms instance without having to reload the 139 module. Use/Test-cases: 140 141 - Hotplug/hotremove connectors on the fly (to be able to test DP MST handling 142 of compositors). 143 144 - Configure planes/crtcs/connectors (we'd need some code to have more than 1 of 145 them first). 146 147 - Change output configuration: Plug/unplug screens, change EDID, allow changing 148 the refresh rate. 149 150 The currently proposed solution is to expose vkms configuration through 151 configfs. All existing module options should be supported through configfs 152 too. 153 154 Writeback support 155 ----------------- 156 157 - The writeback and CRC capture operations share the use of composer_enabled 158 boolean to ensure vblanks. Probably, when these operations work together, 159 composer_enabled needs to refcounting the composer state to proper work. 160 [Good to get started] 161 162 - Add support for cloned writeback outputs and related test cases using a 163 cloned output in the IGT kms_writeback. 164 165 - As a v4l device. This is useful for debugging compositors on special vkms 166 configurations, so that developers see what's really going on. 167 168 Output Features 169 --------------- 170 171 - Variable refresh rate/freesync support. This probably needs prime buffer 172 sharing support, so that we can use vgem fences to simulate rendering in 173 testing. Also needs support to specify the EDID. 174 175 - Add support for link status, so that compositors can validate their runtime 176 fallbacks when e.g. a Display Port link goes bad. 177 178 CRC API Improvements 179 -------------------- 180 181 - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` 182 183 Atomic Check using eBPF 184 ----------------------- 185 186 Atomic drivers have lots of restrictions which are not exposed to userspace in 187 any explicit form through e.g. possible property values. Userspace can only 188 inquiry about these limits through the atomic IOCTL, possibly using the 189 TEST_ONLY flag. Trying to add configurable code for all these limits, to allow 190 compositors to be tested against them, would be rather futile exercise. Instead 191 we could add support for eBPF to validate any kind of atomic state, and 192 implement a library of different restrictions. 193 194 This needs a bunch of features (plane compositing, multiple outputs, ...) 195 enabled already to make sense.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.