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