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 | ||
fb786a48 | 105 | Virtual 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 | |
116 | Add Plane Features | |
117 | ------------------ | |
118 | ||
119 | There'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 | ||
137 | For all of these, we also want to review the igt test coverage and make sure | |
fb786a48 MW |
138 | all relevant igt testcases work on vkms. They are good options for internship |
139 | project. | |
5a388432 MW |
140 | |
141 | Runtime Configuration | |
142 | --------------------- | |
143 | ||
144 | We want to be able to reconfigure vkms instance without having to reload the | |
145 | module. 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 | ||
156 | The currently proposed solution is to expose vkms configuration through | |
fb786a48 | 157 | configfs. All existing module options should be supported through configfs |
5a388432 | 158 | too. |
d717c6df DV |
159 | |
160 | Writeback 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 |
174 | Output 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 |
184 | CRC API Improvements |
185 | -------------------- | |
186 | ||
187 | - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()`` | |
d717c6df DV |
188 | |
189 | Atomic Check using eBPF | |
190 | ----------------------- | |
191 | ||
192 | Atomic drivers have lots of restrictions which are not exposed to userspace in | |
193 | any explicit form through e.g. possible property values. Userspace can only | |
194 | inquiry about these limits through the atomic IOCTL, possibly using the | |
195 | TEST_ONLY flag. Trying to add configurable code for all these limits, to allow | |
196 | compositors to be tested against them, would be rather futile exercise. Instead | |
197 | we could add support for eBPF to validate any kind of atomic state, and | |
198 | implement a library of different restrictions. | |
199 | ||
200 | This needs a bunch of features (plane compositing, multiple outputs, ...) | |
201 | enabled already to make sense. |