Documentation/gpu/vkms.rst

   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 - kms_flip: when running test cases in sequence, some successful individual
 106   test cases are failing randomly; when individually, some successful test
 107   cases display in the log the following error::
 108
 109   [drm:vkms_prepare_fb [vkms]] ERROR vmap failed: -4
 110
 111 Virtual hardware (vblank-less) mode:
 112
 113 - VKMS already has support for vblanks simulated via hrtimers, which can be
 114   tested with kms_flip test; in some way, we can say that VKMS already mimics
 115   the real hardware vblank. However, we also have virtual hardware that does
 116   not support vblank interrupt and completes page_flip events right away; in
 117   this case, compositor developers may end up creating a busy loop on virtual
 118   hardware. It would be useful to support Virtual Hardware behavior in VKMS
 119   because this can help compositor developers to test their features in
 120   multiple scenarios.
 121
 122 Add Plane Features
 123 ------------------
 124
 125 There's lots of plane features we could add support for:
 126
 127 - Multiple overlay planes. [Good to get started]
 128
 129 - Clearing primary plane: clear primary plane before plane composition (at the
 130   start) for correctness of pixel blend ops. It also guarantees alpha channel
 131   is cleared in the target buffer for stable crc. [Good to get started]
 132
 133 - ARGB format on primary plane: blend the primary plane into background with
 134   translucent alpha.
 135
 136 - Support when the primary plane isn't exactly matching the output size: blend
 137   the primary plane into the black background.
 138
 139 - Full alpha blending on all planes.
 140
 141 - Rotation, scaling.
 142
 143 - Additional buffer formats, especially YUV formats for video like NV12.
 144   Low/high bpp RGB formats would also be interesting.
 145
 146 - Async updates (currently only possible on cursor plane using the legacy
 147   cursor api).
 148
 149 For all of these, we also want to review the igt test coverage and make sure
 150 all relevant igt testcases work on vkms. They are good options for internship
 151 project.
 152
 153 Runtime Configuration
 154 ---------------------
 155
 156 We want to be able to reconfigure vkms instance without having to reload the
 157 module. Use/Test-cases:
 158
 159 - Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
 160   of compositors).
 161
 162 - Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
 163   them first).
 164
 165 - Change output configuration: Plug/unplug screens, change EDID, allow changing
 166   the refresh rate.
 167
 168 The currently proposed solution is to expose vkms configuration through
 169 configfs. All existing module options should be supported through configfs
 170 too.
 171
 172 Writeback support
 173 -----------------
 174
 175 - The writeback and CRC capture operations share the use of composer_enabled
 176   boolean to ensure vblanks. Probably, when these operations work together,
 177   composer_enabled needs to refcounting the composer state to proper work.
 178   [Good to get started]
 179
 180 - Add support for cloned writeback outputs and related test cases using a
 181   cloned output in the IGT kms_writeback.
 182
 183 - As a v4l device. This is useful for debugging compositors on special vkms
 184   configurations, so that developers see what's really going on.
 185
 186 Output Features
 187 ---------------
 188
 189 - Variable refresh rate/freesync support. This probably needs prime buffer
 190   sharing support, so that we can use vgem fences to simulate rendering in
 191   testing. Also needs support to specify the EDID.
 192
 193 - Add support for link status, so that compositors can validate their runtime
 194   fallbacks when e.g. a Display Port link goes bad.
 195
 196 CRC API Improvements
 197 --------------------
 198
 199 - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
 200
 201 Atomic Check using eBPF
 202 -----------------------
 203
 204 Atomic drivers have lots of restrictions which are not exposed to userspace in
 205 any explicit form through e.g. possible property values. Userspace can only
 206 inquiry about these limits through the atomic IOCTL, possibly using the
 207 TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
 208 compositors to be tested against them, would be rather futile exercise. Instead
 209 we could add support for eBPF to validate any kind of atomic state, and
 210 implement a library of different restrictions.
 211
 212 This needs a bunch of features (plane compositing, multiple outputs, ...)
 213 enabled already to make sense.