1 .. _vkms: 1 .. _vkms:
2 2
3 ========================================== 3 ==========================================
4 drm/vkms Virtual Kernel Modesetting 4 drm/vkms Virtual Kernel Modesetting
5 ========================================== 5 ==========================================
6 6
7 .. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv. 7 .. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c
8 :doc: vkms (Virtual Kernel Modesetting) 8 :doc: vkms (Virtual Kernel Modesetting)
9 9
10 Setup 10 Setup
11 ===== 11 =====
12 12
13 The VKMS driver can be setup with the followin 13 The VKMS driver can be setup with the following steps:
14 14
15 To check if VKMS is loaded, run:: 15 To check if VKMS is loaded, run::
16 16
17 lsmod | grep vkms 17 lsmod | grep vkms
18 18
19 This should list the VKMS driver. If no output 19 This should list the VKMS driver. If no output is obtained, then
20 you need to enable and/or load the VKMS driver 20 you need to enable and/or load the VKMS driver.
21 Ensure that the VKMS driver has been set as a 21 Ensure that the VKMS driver has been set as a loadable module in your
22 kernel config file. Do:: 22 kernel config file. Do::
23 23
24 make nconfig 24 make nconfig
25 25
26 Go to `Device Drivers> Graphics support` 26 Go to `Device Drivers> Graphics support`
27 27
28 Enable `Virtual KMS (EXPERIMENTAL)` 28 Enable `Virtual KMS (EXPERIMENTAL)`
29 29
30 Compile and build the kernel for the changes t 30 Compile and build the kernel for the changes to get reflected.
31 Now, to load the driver, use:: 31 Now, to load the driver, use::
32 32
33 sudo modprobe vkms 33 sudo modprobe vkms
34 34
35 On running the lsmod command now, the VKMS dri 35 On running the lsmod command now, the VKMS driver will appear listed.
36 You can also observe the driver being loaded i 36 You can also observe the driver being loaded in the dmesg logs.
37 37
38 The VKMS driver has optional features to simul 38 The VKMS driver has optional features to simulate different kinds of hardware,
39 which are exposed as module options. You can u 39 which are exposed as module options. You can use the `modinfo` command
40 to see the module options for vkms:: 40 to see the module options for vkms::
41 41
42 modinfo vkms 42 modinfo vkms
43 43
44 Module options are helpful when testing, and e 44 Module options are helpful when testing, and enabling modules
45 can be done while loading vkms. For example, t 45 can be done while loading vkms. For example, to load vkms with cursor enabled,
46 use:: 46 use::
47 47
48 sudo modprobe vkms enable_cursor=1 48 sudo modprobe vkms enable_cursor=1
49 49
50 To disable the driver, use :: 50 To disable the driver, use ::
51 51
52 sudo modprobe -r vkms 52 sudo modprobe -r vkms
53 53
54 Testing With IGT 54 Testing With IGT
55 ================ 55 ================
56 56
57 The IGT GPU Tools is a test suite used specifi 57 The IGT GPU Tools is a test suite used specifically for debugging and
58 development of the DRM drivers. 58 development of the DRM drivers.
59 The IGT Tools can be installed from 59 The IGT Tools can be installed from
60 `here <https://gitlab.freedesktop.org/drm/igt- 60 `here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .
61 61
62 The tests need to be run without a compositor, 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:: 63 only mode. You can do this by::
64 64
65 sudo systemctl isolate multi-user.target 65 sudo systemctl isolate multi-user.target
66 66
67 To return to graphical mode, do:: 67 To return to graphical mode, do::
68 68
69 sudo systemctl isolate graphical.target 69 sudo systemctl isolate graphical.target
70 70
71 Once you are in text only mode, you can run te 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 f 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 73 to test. IGT_DEVICE can also be used with the run-test.sh script to run the
74 tests for a specific driver:: 74 tests for a specific driver::
75 75
76 sudo ./build/tests/<name of test> --device " 76 sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"
77 sudo IGT_DEVICE="sys:/sys/devices/platform/v 77 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>
78 sudo IGT_DEVICE="sys:/sys/devices/platform/v 78 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>
79 79
80 For example, to test the functionality of the 80 For example, to test the functionality of the writeback library,
81 we can run the kms_writeback test:: 81 we can run the kms_writeback test::
82 82
83 sudo ./build/tests/kms_writeback --device "s 83 sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms"
84 sudo IGT_DEVICE="sys:/sys/devices/platform/v 84 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback
85 sudo IGT_DEVICE="sys:/sys/devices/platform/v 85 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback
86 86
87 You can also run subtests if you do not want t 87 You can also run subtests if you do not want to run the entire test::
88 88
89 sudo ./build/tests/kms_flip --run-subtest ba 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/v 90 sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip
91 91
92 TODO 92 TODO
93 ==== 93 ====
94 94
95 If you want to do any of the items listed belo 95 If you want to do any of the items listed below, please share your interest
96 with VKMS maintainers. 96 with VKMS maintainers.
97 97
98 IGT better support 98 IGT better support
99 ------------------ 99 ------------------
100 100
101 Debugging: 101 Debugging:
102 102
103 - kms_plane: some test cases are failing due t 103 - kms_plane: some test cases are failing due to timeout on capturing CRC;
104 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
105 Virtual hardware (vblank-less) mode: 111 Virtual hardware (vblank-less) mode:
106 112
107 - VKMS already has support for vblanks simulat 113 - VKMS already has support for vblanks simulated via hrtimers, which can be
108 tested with kms_flip test; in some way, we c 114 tested with kms_flip test; in some way, we can say that VKMS already mimics
109 the real hardware vblank. However, we also h 115 the real hardware vblank. However, we also have virtual hardware that does
110 not support vblank interrupt and completes p 116 not support vblank interrupt and completes page_flip events right away; in
111 this case, compositor developers may end up 117 this case, compositor developers may end up creating a busy loop on virtual
112 hardware. It would be useful to support Virt 118 hardware. It would be useful to support Virtual Hardware behavior in VKMS
113 because this can help compositor developers 119 because this can help compositor developers to test their features in
114 multiple scenarios. 120 multiple scenarios.
115 121
116 Add Plane Features 122 Add Plane Features
117 ------------------ 123 ------------------
118 124
119 There's lots of plane features we could add su 125 There's lots of plane features we could add support for:
120 126
121 - Add background color KMS property[Good to ge !! 127 - Multiple overlay planes. [Good to get started]
>> 128
>> 129 - Clearing primary plane: clear primary plane before plane composition (at the
>> 130 start) for correctness of pixel blend ops. It also guarantees alpha channel
>> 131 is cleared in the target buffer for stable crc. [Good to get started]
>> 132
>> 133 - ARGB format on primary plane: blend the primary plane into background with
>> 134 translucent alpha.
>> 135
>> 136 - Support when the primary plane isn't exactly matching the output size: blend
>> 137 the primary plane into the black background.
>> 138
>> 139 - Full alpha blending on all planes.
122 140
123 - Scaling. !! 141 - Rotation, scaling.
124 142
125 - Additional buffer formats, especially YUV fo 143 - Additional buffer formats, especially YUV formats for video like NV12.
126 Low/high bpp RGB formats would also be inter 144 Low/high bpp RGB formats would also be interesting.
127 145
128 - Async updates (currently only possible on cu 146 - Async updates (currently only possible on cursor plane using the legacy
129 cursor api). 147 cursor api).
130 148
131 For all of these, we also want to review the i 149 For all of these, we also want to review the igt test coverage and make sure
132 all relevant igt testcases work on vkms. They 150 all relevant igt testcases work on vkms. They are good options for internship
133 project. 151 project.
134 152
135 Runtime Configuration 153 Runtime Configuration
136 --------------------- 154 ---------------------
137 155
138 We want to be able to reconfigure vkms instanc 156 We want to be able to reconfigure vkms instance without having to reload the
139 module. Use/Test-cases: 157 module. Use/Test-cases:
140 158
141 - Hotplug/hotremove connectors on the fly (to 159 - Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
142 of compositors). 160 of compositors).
143 161
144 - Configure planes/crtcs/connectors (we'd need 162 - Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
145 them first). 163 them first).
146 164
147 - Change output configuration: Plug/unplug scr 165 - Change output configuration: Plug/unplug screens, change EDID, allow changing
148 the refresh rate. 166 the refresh rate.
149 167
150 The currently proposed solution is to expose v 168 The currently proposed solution is to expose vkms configuration through
151 configfs. All existing module options should b 169 configfs. All existing module options should be supported through configfs
152 too. 170 too.
153 171
154 Writeback support 172 Writeback support
155 ----------------- 173 -----------------
156 174
157 - The writeback and CRC capture operations sha 175 - The writeback and CRC capture operations share the use of composer_enabled
158 boolean to ensure vblanks. Probably, when th 176 boolean to ensure vblanks. Probably, when these operations work together,
159 composer_enabled needs to refcounting the co 177 composer_enabled needs to refcounting the composer state to proper work.
160 [Good to get started] 178 [Good to get started]
161 179
162 - Add support for cloned writeback outputs and 180 - Add support for cloned writeback outputs and related test cases using a
163 cloned output in the IGT kms_writeback. 181 cloned output in the IGT kms_writeback.
164 182
165 - As a v4l device. This is useful for debuggin 183 - As a v4l device. This is useful for debugging compositors on special vkms
166 configurations, so that developers see what' 184 configurations, so that developers see what's really going on.
167 185
168 Output Features 186 Output Features
169 --------------- 187 ---------------
170 188
171 - Variable refresh rate/freesync support. This 189 - Variable refresh rate/freesync support. This probably needs prime buffer
172 sharing support, so that we can use vgem fen 190 sharing support, so that we can use vgem fences to simulate rendering in
173 testing. Also needs support to specify the E 191 testing. Also needs support to specify the EDID.
174 192
175 - Add support for link status, so that composi 193 - Add support for link status, so that compositors can validate their runtime
176 fallbacks when e.g. a Display Port link goes 194 fallbacks when e.g. a Display Port link goes bad.
177 195
178 CRC API Improvements 196 CRC API Improvements
179 -------------------- 197 --------------------
180 198
181 - Optimize CRC computation ``compute_crc()`` a 199 - Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
182 200
183 Atomic Check using eBPF 201 Atomic Check using eBPF
184 ----------------------- 202 -----------------------
185 203
186 Atomic drivers have lots of restrictions which 204 Atomic drivers have lots of restrictions which are not exposed to userspace in
187 any explicit form through e.g. possible proper 205 any explicit form through e.g. possible property values. Userspace can only
188 inquiry about these limits through the atomic 206 inquiry about these limits through the atomic IOCTL, possibly using the
189 TEST_ONLY flag. Trying to add configurable cod 207 TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
190 compositors to be tested against them, would b 208 compositors to be tested against them, would be rather futile exercise. Instead
191 we could add support for eBPF to validate any 209 we could add support for eBPF to validate any kind of atomic state, and
192 implement a library of different restrictions. 210 implement a library of different restrictions.
193 211
194 This needs a bunch of features (plane composit 212 This needs a bunch of features (plane compositing, multiple outputs, ...)
195 enabled already to make sense. 213 enabled already to make sense.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.