drm: vkms: Refactor the plane composer to accept new formats
[linux-block.git] / Documentation / gpu / vkms.rst
CommitLineData
ad9ff96f
HM
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
63ade104
SP
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
af20724c
SP
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
63ade104
SP
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
ad9ff96f
HM
92TODO
93====
94
5a388432
MW
95If you want to do any of the items listed below, please share your interest
96with VKMS maintainers.
d717c6df 97
5a388432
MW
98IGT better support
99------------------
d717c6df 100
fb786a48
MW
101Debugging:
102
103- kms_plane: some test cases are failing due to timeout on capturing CRC;
104
fb786a48 105Virtual hardware (vblank-less) mode:
d717c6df 106
5a388432
MW
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.
d717c6df
DV
115
116Add Plane Features
117------------------
118
119There's lots of plane features we could add support for:
120
fb786a48
MW
121- ARGB format on primary plane: blend the primary plane into background with
122 translucent alpha.
123
124- Support when the primary plane isn't exactly matching the output size: blend
125 the primary plane into the black background.
d717c6df
DV
126
127- Full alpha blending on all planes.
128
129- Rotation, scaling.
130
131- Additional buffer formats, especially YUV formats for video like NV12.
132 Low/high bpp RGB formats would also be interesting.
133
5a388432
MW
134- Async updates (currently only possible on cursor plane using the legacy
135 cursor api).
136
137For all of these, we also want to review the igt test coverage and make sure
fb786a48
MW
138all relevant igt testcases work on vkms. They are good options for internship
139project.
5a388432
MW
140
141Runtime Configuration
142---------------------
143
144We want to be able to reconfigure vkms instance without having to reload the
145module. Use/Test-cases:
146
147- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
148 of compositors).
149
150- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
151 them first).
152
153- Change output configuration: Plug/unplug screens, change EDID, allow changing
154 the refresh rate.
155
156The currently proposed solution is to expose vkms configuration through
fb786a48 157configfs. All existing module options should be supported through configfs
5a388432 158too.
d717c6df
DV
159
160Writeback support
161-----------------
162
5a388432
MW
163- The writeback and CRC capture operations share the use of composer_enabled
164 boolean to ensure vblanks. Probably, when these operations work together,
165 composer_enabled needs to refcounting the composer state to proper work.
fb786a48 166 [Good to get started]
d717c6df 167
5a388432
MW
168- Add support for cloned writeback outputs and related test cases using a
169 cloned output in the IGT kms_writeback.
d717c6df
DV
170
171- As a v4l device. This is useful for debugging compositors on special vkms
172 configurations, so that developers see what's really going on.
173
d717c6df
DV
174Output Features
175---------------
176
177- Variable refresh rate/freesync support. This probably needs prime buffer
178 sharing support, so that we can use vgem fences to simulate rendering in
179 testing. Also needs support to specify the EDID.
180
181- Add support for link status, so that compositors can validate their runtime
182 fallbacks when e.g. a Display Port link goes bad.
183
5a388432
MW
184CRC API Improvements
185--------------------
186
187- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
d717c6df
DV
188
189Atomic Check using eBPF
190-----------------------
191
192Atomic drivers have lots of restrictions which are not exposed to userspace in
193any explicit form through e.g. possible property values. Userspace can only
194inquiry about these limits through the atomic IOCTL, possibly using the
195TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
196compositors to be tested against them, would be rather futile exercise. Instead
197we could add support for eBPF to validate any kind of atomic state, and
198implement a library of different restrictions.
199
200This needs a bunch of features (plane compositing, multiple outputs, ...)
201enabled already to make sense.