0001 .. _vkms:
0002
0003 ==========================================
0004 drm/vkms Virtual Kernel Modesetting
0005 ==========================================
0006
0007 .. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c
0008 :doc: vkms (Virtual Kernel Modesetting)
0009
0010 Setup
0011 =====
0012
0013 The VKMS driver can be setup with the following steps:
0014
0015 To check if VKMS is loaded, run::
0016
0017 lsmod | grep vkms
0018
0019 This should list the VKMS driver. If no output is obtained, then
0020 you need to enable and/or load the VKMS driver.
0021 Ensure that the VKMS driver has been set as a loadable module in your
0022 kernel config file. Do::
0023
0024 make nconfig
0025
0026 Go to `Device Drivers> Graphics support`
0027
0028 Enable `Virtual KMS (EXPERIMENTAL)`
0029
0030 Compile and build the kernel for the changes to get reflected.
0031 Now, to load the driver, use::
0032
0033 sudo modprobe vkms
0034
0035 On running the lsmod command now, the VKMS driver will appear listed.
0036 You can also observe the driver being loaded in the dmesg logs.
0037
0038 The VKMS driver has optional features to simulate different kinds of hardware,
0039 which are exposed as module options. You can use the `modinfo` command
0040 to see the module options for vkms::
0041
0042 modinfo vkms
0043
0044 Module options are helpful when testing, and enabling modules
0045 can be done while loading vkms. For example, to load vkms with cursor enabled,
0046 use::
0047
0048 sudo modprobe vkms enable_cursor=1
0049
0050 To disable the driver, use ::
0051
0052 sudo modprobe -r vkms
0053
0054 Testing With IGT
0055 ================
0056
0057 The IGT GPU Tools is a test suite used specifically for debugging and
0058 development of the DRM drivers.
0059 The IGT Tools can be installed from
0060 `here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .
0061
0062 The tests need to be run without a compositor, so you need to switch to text
0063 only mode. You can do this by::
0064
0065 sudo systemctl isolate multi-user.target
0066
0067 To return to graphical mode, do::
0068
0069 sudo systemctl isolate graphical.target
0070
0071 Once you are in text only mode, you can run tests using the --device switch
0072 or IGT_DEVICE variable to specify the device filter for the driver we want
0073 to test. IGT_DEVICE can also be used with the run-test.sh script to run the
0074 tests for a specific driver::
0075
0076 sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"
0077 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>
0078 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>
0079
0080 For example, to test the functionality of the writeback library,
0081 we can run the kms_writeback test::
0082
0083 sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms"
0084 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback
0085 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback
0086
0087 You can also run subtests if you do not want to run the entire test::
0088
0089 sudo ./build/tests/kms_flip --run-subtest basic-plain-flip --device "sys:/sys/devices/platform/vkms"
0090 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip
0091
0092 TODO
0093 ====
0094
0095 If you want to do any of the items listed below, please share your interest
0096 with VKMS maintainers.
0097
0098 IGT better support
0099 ------------------
0100
0101 Debugging:
0102
0103 - kms_plane: some test cases are failing due to timeout on capturing CRC;
0104
0105 Virtual hardware (vblank-less) mode:
0106
0107 - VKMS already has support for vblanks simulated via hrtimers, which can be
0108 tested with kms_flip test; in some way, we can say that VKMS already mimics
0109 the real hardware vblank. However, we also have virtual hardware that does
0110 not support vblank interrupt and completes page_flip events right away; in
0111 this case, compositor developers may end up creating a busy loop on virtual
0112 hardware. It would be useful to support Virtual Hardware behavior in VKMS
0113 because this can help compositor developers to test their features in
0114 multiple scenarios.
0115
0116 Add Plane Features
0117 ------------------
0118
0119 There's lots of plane features we could add support for:
0120
0121 - Clearing primary plane: clear primary plane before plane composition (at the
0122 start) for correctness of pixel blend ops. It also guarantees alpha channel
0123 is cleared in the target buffer for stable crc. [Good to get started]
0124
0125 - ARGB format on primary plane: blend the primary plane into background with
0126 translucent alpha.
0127
0128 - Support when the primary plane isn't exactly matching the output size: blend
0129 the primary plane into the black background.
0130
0131 - Full alpha blending on all planes.
0132
0133 - Rotation, scaling.
0134
0135 - Additional buffer formats, especially YUV formats for video like NV12.
0136 Low/high bpp RGB formats would also be interesting.
0137
0138 - Async updates (currently only possible on cursor plane using the legacy
0139 cursor api).
0140
0141 For all of these, we also want to review the igt test coverage and make sure
0142 all relevant igt testcases work on vkms. They are good options for internship
0143 project.
0144
0145 Runtime Configuration
0146 ---------------------
0147
0148 We want to be able to reconfigure vkms instance without having to reload the
0149 module. Use/Test-cases:
0150
0151 - Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
0152 of compositors).
0153
0154 - Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
0155 them first).
0156
0157 - Change output configuration: Plug/unplug screens, change EDID, allow changing
0158 the refresh rate.
0159
0160 The currently proposed solution is to expose vkms configuration through
0161 configfs. All existing module options should be supported through configfs
0162 too.
0163
0164 Writeback support
0165 -----------------
0166
0167 - The writeback and CRC capture operations share the use of composer_enabled
0168 boolean to ensure vblanks. Probably, when these operations work together,
0169 composer_enabled needs to refcounting the composer state to proper work.
0170 [Good to get started]
0171
0172 - Add support for cloned writeback outputs and related test cases using a
0173 cloned output in the IGT kms_writeback.
0174
0175 - As a v4l device. This is useful for debugging compositors on special vkms
0176 configurations, so that developers see what's really going on.
0177
0178 Output Features
0179 ---------------
0180
0181 - Variable refresh rate/freesync support. This probably needs prime buffer
0182 sharing support, so that we can use vgem fences to simulate rendering in
0183 testing. Also needs support to specify the EDID.
0184
0185 - Add support for link status, so that compositors can validate their runtime
0186 fallbacks when e.g. a Display Port link goes bad.
0187
0188 CRC API Improvements
0189 --------------------
0190
0191 - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
0192
0193 Atomic Check using eBPF
0194 -----------------------
0195
0196 Atomic drivers have lots of restrictions which are not exposed to userspace in
0197 any explicit form through e.g. possible property values. Userspace can only
0198 inquiry about these limits through the atomic IOCTL, possibly using the
0199 TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
0200 compositors to be tested against them, would be rather futile exercise. Instead
0201 we could add support for eBPF to validate any kind of atomic state, and
0202 implement a library of different restrictions.
0203
0204 This needs a bunch of features (plane compositing, multiple outputs, ...)
0205 enabled already to make sense.
