| 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 | Configuring With Configfs
|
| 55 | =========================
|
| 56 |
|
| 57 | It is possible to create and configure multiple VKMS instances via configfs.
|
| 58 |
|
| 59 | Start by mounting configfs and loading VKMS::
|
| 60 |
|
| 61 | sudo mount -t configfs none /config
|
| 62 | sudo modprobe vkms
|
| 63 |
|
| 64 | Once VKMS is loaded, ``/config/vkms`` is created automatically. Each directory
|
| 65 | under ``/config/vkms`` represents a VKMS instance, create a new one::
|
| 66 |
|
| 67 | sudo mkdir /config/vkms/my-vkms
|
| 68 |
|
| 69 | By default, the instance is disabled::
|
| 70 |
|
| 71 | cat /config/vkms/my-vkms/enabled
|
| 72 | 0
|
| 73 |
|
| 74 | And directories are created for each configurable item of the display pipeline::
|
| 75 |
|
| 76 | tree /config/vkms/my-vkms
|
| 77 | ├── connectors
|
| 78 | ├── crtcs
|
| 79 | ├── enabled
|
| 80 | ├── encoders
|
| 81 | └── planes
|
| 82 |
|
| 83 | To add items to the display pipeline, create one or more directories under the
|
| 84 | available paths.
|
| 85 |
|
| 86 | Start by creating one or more planes::
|
| 87 |
|
| 88 | sudo mkdir /config/vkms/my-vkms/planes/plane0
|
| 89 |
|
| 90 | Planes have 1 configurable attribute:
|
| 91 |
|
| 92 | - type: Plane type: 0 overlay, 1 primary, 2 cursor (same values as those
|
| 93 | exposed by the "type" property of a plane)
|
| 94 |
|
| 95 | Continue by creating one or more CRTCs::
|
| 96 |
|
| 97 | sudo mkdir /config/vkms/my-vkms/crtcs/crtc0
|
| 98 |
|
| 99 | CRTCs have 1 configurable attribute:
|
| 100 |
|
| 101 | - writeback: Enable or disable writeback connector support by writing 1 or 0
|
| 102 |
|
| 103 | Next, create one or more encoders::
|
| 104 |
|
| 105 | sudo mkdir /config/vkms/my-vkms/encoders/encoder0
|
| 106 |
|
| 107 | Last but not least, create one or more connectors::
|
| 108 |
|
| 109 | sudo mkdir /config/vkms/my-vkms/connectors/connector0
|
| 110 |
|
| 111 | Connectors have 1 configurable attribute:
|
| 112 |
|
| 113 | - status: Connection status: 1 connected, 2 disconnected, 3 unknown (same values
|
| 114 | as those exposed by the "status" property of a connector)
|
| 115 |
|
| 116 | To finish the configuration, link the different pipeline items::
|
| 117 |
|
| 118 | sudo ln -s /config/vkms/my-vkms/crtcs/crtc0 /config/vkms/my-vkms/planes/plane0/possible_crtcs
|
| 119 | sudo ln -s /config/vkms/my-vkms/crtcs/crtc0 /config/vkms/my-vkms/encoders/encoder0/possible_crtcs
|
| 120 | sudo ln -s /config/vkms/my-vkms/encoders/encoder0 /config/vkms/my-vkms/connectors/connector0/possible_encoders
|
| 121 |
|
| 122 | Since at least one primary plane is required, make sure to set the right type::
|
| 123 |
|
| 124 | echo "1" | sudo tee /config/vkms/my-vkms/planes/plane0/type
|
| 125 |
|
| 126 | Once you are done configuring the VKMS instance, enable it::
|
| 127 |
|
| 128 | echo "1" | sudo tee /config/vkms/my-vkms/enabled
|
| 129 |
|
| 130 | Finally, you can remove the VKMS instance disabling it::
|
| 131 |
|
| 132 | echo "0" | sudo tee /config/vkms/my-vkms/enabled
|
| 133 |
|
| 134 | And removing the top level directory and its subdirectories::
|
| 135 |
|
| 136 | sudo rm /config/vkms/my-vkms/planes/*/possible_crtcs/*
|
| 137 | sudo rm /config/vkms/my-vkms/encoders/*/possible_crtcs/*
|
| 138 | sudo rm /config/vkms/my-vkms/connectors/*/possible_encoders/*
|
| 139 | sudo rmdir /config/vkms/my-vkms/planes/*
|
| 140 | sudo rmdir /config/vkms/my-vkms/crtcs/*
|
| 141 | sudo rmdir /config/vkms/my-vkms/encoders/*
|
| 142 | sudo rmdir /config/vkms/my-vkms/connectors/*
|
| 143 | sudo rmdir /config/vkms/my-vkms
|
| 144 |
|
| 145 | Testing With IGT
|
| 146 | ================
|
| 147 |
|
| 148 | The IGT GPU Tools is a test suite used specifically for debugging and
|
| 149 | development of the DRM drivers.
|
| 150 | The IGT Tools can be installed from
|
| 151 | `here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .
|
| 152 |
|
| 153 | The tests need to be run without a compositor, so you need to switch to text
|
| 154 | only mode. You can do this by::
|
| 155 |
|
| 156 | sudo systemctl isolate multi-user.target
|
| 157 |
|
| 158 | To return to graphical mode, do::
|
| 159 |
|
| 160 | sudo systemctl isolate graphical.target
|
| 161 |
|
| 162 | Once you are in text only mode, you can run tests using the IGT_FORCE_DRIVER
|
| 163 | variable to specify the device filter for the driver we want to test.
|
| 164 | IGT_FORCE_DRIVER can also be used with the run-tests.sh script to run the
|
| 165 | tests for a specific driver::
|
| 166 |
|
| 167 | sudo IGT_FORCE_DRIVER="vkms" ./build/tests/<name of test>
|
| 168 | sudo IGT_FORCE_DRIVER="vkms" ./scripts/run-tests.sh -t <name of test>
|
| 169 |
|
| 170 | For example, to test the functionality of the writeback library,
|
| 171 | we can run the kms_writeback test::
|
| 172 |
|
| 173 | sudo IGT_FORCE_DRIVER="vkms" ./build/tests/kms_writeback
|
| 174 | sudo IGT_FORCE_DRIVER="vkms" ./scripts/run-tests.sh -t kms_writeback
|
| 175 |
|
| 176 | You can also run subtests if you do not want to run the entire test::
|
| 177 |
|
| 178 | sudo IGT_FORCE_DRIVER="vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip
|
| 179 |
|
| 180 | Testing With KUnit
|
| 181 | ==================
|
| 182 |
|
| 183 | KUnit (Kernel unit testing framework) provides a common framework for unit tests
|
| 184 | within the Linux kernel.
|
| 185 | More information in ../dev-tools/kunit/index.rst .
|
| 186 |
|
| 187 | To run the VKMS KUnit tests::
|
| 188 |
|
| 189 | tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/vkms/tests
|
| 190 |
|
| 191 | TODO
|
| 192 | ====
|
| 193 |
|
| 194 | If you want to do any of the items listed below, please share your interest
|
| 195 | with VKMS maintainers.
|
| 196 |
|
| 197 | IGT better support
|
| 198 | ------------------
|
| 199 |
|
| 200 | Debugging:
|
| 201 |
|
| 202 | - kms_plane: some test cases are failing due to timeout on capturing CRC;
|
| 203 |
|
| 204 | Virtual hardware (vblank-less) mode:
|
| 205 |
|
| 206 | - VKMS already has support for vblanks simulated via hrtimers, which can be
|
| 207 | tested with kms_flip test; in some way, we can say that VKMS already mimics
|
| 208 | the real hardware vblank. However, we also have virtual hardware that does
|
| 209 | not support vblank interrupt and completes page_flip events right away; in
|
| 210 | this case, compositor developers may end up creating a busy loop on virtual
|
| 211 | hardware. It would be useful to support Virtual Hardware behavior in VKMS
|
| 212 | because this can help compositor developers to test their features in
|
| 213 | multiple scenarios.
|
| 214 |
|
| 215 | Add Plane Features
|
| 216 | ------------------
|
| 217 |
|
| 218 | There's lots of plane features we could add support for:
|
| 219 |
|
| 220 | - Add background color KMS property[Good to get started].
|
| 221 |
|
| 222 | - Scaling.
|
| 223 |
|
| 224 | - Additional buffer formats. Low/high bpp RGB formats would be interesting
|
| 225 | [Good to get started].
|
| 226 |
|
| 227 | - Async updates (currently only possible on cursor plane using the legacy
|
| 228 | cursor api).
|
| 229 |
|
| 230 | For all of these, we also want to review the igt test coverage and make sure
|
| 231 | all relevant igt testcases work on vkms. They are good options for internship
|
| 232 | project.
|
| 233 |
|
| 234 | Runtime Configuration
|
| 235 | ---------------------
|
| 236 |
|
| 237 | We want to be able to reconfigure vkms instance without having to reload the
|
| 238 | module through configfs. Use/Test-cases:
|
| 239 |
|
| 240 | - Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
|
| 241 | of compositors).
|
| 242 |
|
| 243 | - Change output configuration: Plug/unplug screens, change EDID, allow changing
|
| 244 | the refresh rate.
|
| 245 |
|
| 246 | Writeback support
|
| 247 | -----------------
|
| 248 |
|
| 249 | - The writeback and CRC capture operations share the use of composer_enabled
|
| 250 | boolean to ensure vblanks. Probably, when these operations work together,
|
| 251 | composer_enabled needs to refcounting the composer state to proper work.
|
| 252 | [Good to get started]
|
| 253 |
|
| 254 | - Add support for cloned writeback outputs and related test cases using a
|
| 255 | cloned output in the IGT kms_writeback.
|
| 256 |
|
| 257 | - As a v4l device. This is useful for debugging compositors on special vkms
|
| 258 | configurations, so that developers see what's really going on.
|
| 259 |
|
| 260 | Output Features
|
| 261 | ---------------
|
| 262 |
|
| 263 | - Variable refresh rate/freesync support. This probably needs prime buffer
|
| 264 | sharing support, so that we can use vgem fences to simulate rendering in
|
| 265 | testing. Also needs support to specify the EDID.
|
| 266 |
|
| 267 | - Add support for link status, so that compositors can validate their runtime
|
| 268 | fallbacks when e.g. a Display Port link goes bad.
|
| 269 |
|
| 270 | CRC API Improvements
|
| 271 | --------------------
|
| 272 |
|
| 273 | - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
|
| 274 |
|
| 275 | Atomic Check using eBPF
|
| 276 | -----------------------
|
| 277 |
|
| 278 | Atomic drivers have lots of restrictions which are not exposed to userspace in
|
| 279 | any explicit form through e.g. possible property values. Userspace can only
|
| 280 | inquiry about these limits through the atomic IOCTL, possibly using the
|
| 281 | TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
|
| 282 | compositors to be tested against them, would be rather futile exercise. Instead
|
| 283 | we could add support for eBPF to validate any kind of atomic state, and
|
| 284 | implement a library of different restrictions.
|
| 285 |
|
| 286 | This needs a bunch of features (plane compositing, multiple outputs, ...)
|
| 287 | enabled already to make sense.
|