Commit | Line | Data |
---|---|---|
22554020 | 1 | =================== |
ca00c2b9 JN |
2 | Userland interfaces |
3 | =================== | |
4 | ||
5 | The DRM core exports several interfaces to applications, generally | |
6 | intended to be used through corresponding libdrm wrapper functions. In | |
7 | addition, drivers export device-specific interfaces for use by userspace | |
8 | drivers & device-aware applications through ioctls and sysfs files. | |
9 | ||
10 | External interfaces include: memory mapping, context management, DMA | |
11 | operations, AGP management, vblank control, fence management, memory | |
12 | management, and output management. | |
13 | ||
14 | Cover generic ioctls and sysfs layout here. We only need high-level | |
15 | info, since man pages should cover the rest. | |
16 | ||
a3257256 DV |
17 | libdrm Device Lookup |
18 | ==================== | |
19 | ||
20 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
21 | :doc: getunique and setversion story | |
22 | ||
3b96a0b1 | 23 | |
b93658f8 DV |
24 | .. _drm_primary_node: |
25 | ||
3b96a0b1 DV |
26 | Primary Nodes, DRM Master and Authentication |
27 | ============================================ | |
28 | ||
29 | .. kernel-doc:: drivers/gpu/drm/drm_auth.c | |
30 | :doc: master and authentication | |
31 | ||
32 | .. kernel-doc:: drivers/gpu/drm/drm_auth.c | |
33 | :export: | |
34 | ||
35 | .. kernel-doc:: include/drm/drm_auth.h | |
36 | :internal: | |
37 | ||
bcb32b69 DV |
38 | Open-Source Userspace Requirements |
39 | ================================== | |
40 | ||
0d42204f DV |
41 | The DRM subsystem has stricter requirements than most other kernel subsystems on |
42 | what the userspace side for new uAPI needs to look like. This section here | |
43 | explains what exactly those requirements are, and why they exist. | |
44 | ||
45 | The short summary is that any addition of DRM uAPI requires corresponding | |
46 | open-sourced userspace patches, and those patches must be reviewed and ready for | |
47 | merging into a suitable and canonical upstream project. | |
48 | ||
49 | GFX devices (both display and render/GPU side) are really complex bits of | |
50 | hardware, with userspace and kernel by necessity having to work together really | |
51 | closely. The interfaces, for rendering and modesetting, must be extremely wide | |
52 | and flexible, and therefore it is almost always impossible to precisely define | |
53 | them for every possible corner case. This in turn makes it really practically | |
54 | infeasible to differentiate between behaviour that's required by userspace, and | |
55 | which must not be changed to avoid regressions, and behaviour which is only an | |
56 | accidental artifact of the current implementation. | |
57 | ||
58 | Without access to the full source code of all userspace users that means it | |
59 | becomes impossible to change the implementation details, since userspace could | |
60 | depend upon the accidental behaviour of the current implementation in minute | |
61 | details. And debugging such regressions without access to source code is pretty | |
62 | much impossible. As a consequence this means: | |
63 | ||
64 | - The Linux kernel's "no regression" policy holds in practice only for | |
65 | open-source userspace of the DRM subsystem. DRM developers are perfectly fine | |
66 | if closed-source blob drivers in userspace use the same uAPI as the open | |
67 | drivers, but they must do so in the exact same way as the open drivers. | |
68 | Creative (ab)use of the interfaces will, and in the past routinely has, lead | |
69 | to breakage. | |
70 | ||
71 | - Any new userspace interface must have an open-source implementation as | |
72 | demonstration vehicle. | |
73 | ||
74 | The other reason for requiring open-source userspace is uAPI review. Since the | |
75 | kernel and userspace parts of a GFX stack must work together so closely, code | |
76 | review can only assess whether a new interface achieves its goals by looking at | |
77 | both sides. Making sure that the interface indeed covers the use-case fully | |
78 | leads to a few additional requirements: | |
79 | ||
80 | - The open-source userspace must not be a toy/test application, but the real | |
81 | thing. Specifically it needs to handle all the usual error and corner cases. | |
82 | These are often the places where new uAPI falls apart and hence essential to | |
83 | assess the fitness of a proposed interface. | |
84 | ||
85 | - The userspace side must be fully reviewed and tested to the standards of that | |
86 | userspace project. For e.g. mesa this means piglit testcases and review on the | |
87 | mailing list. This is again to ensure that the new interface actually gets the | |
e33df4ca DV |
88 | job done. The userspace-side reviewer should also provide an Acked-by on the |
89 | kernel uAPI patch indicating that they believe the proposed uAPI is sound and | |
90 | sufficiently documented and validated for userspace's consumption. | |
0d42204f DV |
91 | |
92 | - The userspace patches must be against the canonical upstream, not some vendor | |
93 | fork. This is to make sure that no one cheats on the review and testing | |
94 | requirements by doing a quick fork. | |
95 | ||
96 | - The kernel patch can only be merged after all the above requirements are met, | |
3d42fca0 EA |
97 | but it **must** be merged to either drm-next or drm-misc-next **before** the |
98 | userspace patches land. uAPI always flows from the kernel, doing things the | |
99 | other way round risks divergence of the uAPI definitions and header files. | |
0d42204f DV |
100 | |
101 | These are fairly steep requirements, but have grown out from years of shared | |
102 | pain and experience with uAPI added hastily, and almost always regretted about | |
103 | just as fast. GFX devices change really fast, requiring a paradigm shift and | |
104 | entire new set of uAPI interfaces every few years at least. Together with the | |
105 | Linux kernel's guarantee to keep existing userspace running for 10+ years this | |
106 | is already rather painful for the DRM subsystem, with multiple different uAPIs | |
107 | for the same thing co-existing. If we add a few more complete mistakes into the | |
108 | mix every year it would be entirely unmanageable. | |
109 | ||
b93658f8 DV |
110 | .. _drm_render_node: |
111 | ||
ca00c2b9 | 112 | Render nodes |
22554020 | 113 | ============ |
ca00c2b9 JN |
114 | |
115 | DRM core provides multiple character-devices for user-space to use. | |
116 | Depending on which device is opened, user-space can perform a different | |
117 | set of operations (mainly ioctls). The primary node is always created | |
118 | and called card<num>. Additionally, a currently unused control node, | |
119 | called controlD<num> is also created. The primary node provides all | |
120 | legacy operations and historically was the only interface used by | |
121 | userspace. With KMS, the control node was introduced. However, the | |
122 | planned KMS control interface has never been written and so the control | |
123 | node stays unused to date. | |
124 | ||
125 | With the increased use of offscreen renderers and GPGPU applications, | |
126 | clients no longer require running compositors or graphics servers to | |
127 | make use of a GPU. But the DRM API required unprivileged clients to | |
128 | authenticate to a DRM-Master prior to getting GPU access. To avoid this | |
129 | step and to grant clients GPU access without authenticating, render | |
130 | nodes were introduced. Render nodes solely serve render clients, that | |
131 | is, no modesetting or privileged ioctls can be issued on render nodes. | |
132 | Only non-global rendering commands are allowed. If a driver supports | |
133 | render nodes, it must advertise it via the DRIVER_RENDER DRM driver | |
134 | capability. If not supported, the primary node must be used for render | |
135 | clients together with the legacy drmAuth authentication procedure. | |
136 | ||
137 | If a driver advertises render node support, DRM core will create a | |
138 | separate render node called renderD<num>. There will be one render node | |
139 | per device. No ioctls except PRIME-related ioctls will be allowed on | |
140 | this node. Especially GEM_OPEN will be explicitly prohibited. Render | |
141 | nodes are designed to avoid the buffer-leaks, which occur if clients | |
142 | guess the flink names or mmap offsets on the legacy interface. | |
143 | Additionally to this basic interface, drivers must mark their | |
144 | driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render | |
145 | clients can use them. Driver authors must be careful not to allow any | |
146 | privileged ioctls on render nodes. | |
147 | ||
148 | With render nodes, user-space can now control access to the render node | |
149 | via basic file-system access-modes. A running graphics server which | |
150 | authenticates clients on the privileged primary/legacy node is no longer | |
151 | required. Instead, a client can open the render node and is immediately | |
152 | granted GPU access. Communication between clients (or servers) is done | |
153 | via PRIME. FLINK from render node to legacy node is not supported. New | |
154 | clients must not use the insecure FLINK interface. | |
155 | ||
156 | Besides dropping all modeset/global ioctls, render nodes also drop the | |
157 | DRM-Master concept. There is no reason to associate render clients with | |
158 | a DRM-Master as they are independent of any graphics server. Besides, | |
159 | they must work without any running master, anyway. Drivers must be able | |
160 | to run without a master object if they support render nodes. If, on the | |
161 | other hand, a driver requires shared state between clients which is | |
162 | visible to user-space and accessible beyond open-file boundaries, they | |
163 | cannot support render nodes. | |
164 | ||
bb2eaba6 DV |
165 | .. _drm_driver_ioctl: |
166 | ||
2640981f DV |
167 | IOCTL Support on Device Nodes |
168 | ============================= | |
169 | ||
170 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
171 | :doc: driver specific ioctls | |
172 | ||
371cadd8 DV |
173 | Recommended IOCTL Return Values |
174 | ------------------------------- | |
175 | ||
176 | In theory a driver's IOCTL callback is only allowed to return very few error | |
177 | codes. In practice it's good to abuse a few more. This section documents common | |
178 | practice within the DRM subsystem: | |
179 | ||
180 | ENOENT: | |
181 | Strictly this should only be used when a file doesn't exist e.g. when | |
182 | calling the open() syscall. We reuse that to signal any kind of object | |
183 | lookup failure, e.g. for unknown GEM buffer object handles, unknown KMS | |
184 | object handles and similar cases. | |
185 | ||
186 | ENOSPC: | |
187 | Some drivers use this to differentiate "out of kernel memory" from "out | |
188 | of VRAM". Sometimes also applies to other limited gpu resources used for | |
189 | rendering (e.g. when you have a special limited compression buffer). | |
190 | Sometimes resource allocation/reservation issues in command submission | |
191 | IOCTLs are also signalled through EDEADLK. | |
192 | ||
193 | Simply running out of kernel/system memory is signalled through ENOMEM. | |
194 | ||
cba8087d | 195 | EPERM/EACCES: |
371cadd8 DV |
196 | Returned for an operation that is valid, but needs more privileges. |
197 | E.g. root-only or much more common, DRM master-only operations return | |
198 | this when when called by unpriviledged clients. There's no clear | |
cba8087d | 199 | difference between EACCES and EPERM. |
371cadd8 DV |
200 | |
201 | ENODEV: | |
9edb6a0b DV |
202 | The device is not (yet) present or fully initialized. |
203 | ||
204 | EOPNOTSUPP: | |
371cadd8 DV |
205 | Feature (like PRIME, modesetting, GEM) is not supported by the driver. |
206 | ||
207 | ENXIO: | |
208 | Remote failure, either a hardware transaction (like i2c), but also used | |
209 | when the exporting driver of a shared dma-buf or fence doesn't support a | |
210 | feature needed. | |
211 | ||
212 | EINTR: | |
213 | DRM drivers assume that userspace restarts all IOCTLs. Any DRM IOCTL can | |
214 | return EINTR and in such a case should be restarted with the IOCTL | |
215 | parameters left unchanged. | |
216 | ||
217 | EIO: | |
218 | The GPU died and couldn't be resurrected through a reset. Modesetting | |
219 | hardware failures are signalled through the "link status" connector | |
220 | property. | |
221 | ||
222 | EINVAL: | |
223 | Catch-all for anything that is an invalid argument combination which | |
224 | cannot work. | |
225 | ||
226 | IOCTL also use other error codes like ETIME, EFAULT, EBUSY, ENOTTY but their | |
227 | usage is in line with the common meanings. The above list tries to just document | |
228 | DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of | |
229 | "this IOCTL does not exist", and is used exactly as such in DRM. | |
230 | ||
2640981f DV |
231 | .. kernel-doc:: include/drm/drm_ioctl.h |
232 | :internal: | |
233 | ||
234 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
235 | :export: | |
236 | ||
237 | .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c | |
238 | :export: | |
a8182863 DV |
239 | |
240 | Testing and validation | |
241 | ====================== | |
242 | ||
badfa5be DV |
243 | Testing Requirements for userspace API |
244 | -------------------------------------- | |
245 | ||
246 | New cross-driver userspace interface extensions, like new IOCTL, new KMS | |
247 | properties, new files in sysfs or anything else that constitutes an API change | |
248 | should have driver-agnostic testcases in IGT for that feature, if such a test | |
249 | can be reasonably made using IGT for the target hardware. | |
250 | ||
75ac4953 | 251 | Validating changes with IGT |
a8182863 | 252 | --------------------------- |
75ac4953 TV |
253 | |
254 | There's a collection of tests that aims to cover the whole functionality of | |
255 | DRM drivers and that can be used to check that changes to DRM drivers or the | |
256 | core don't regress existing functionality. This test suite is called IGT and | |
257 | its code can be found in https://cgit.freedesktop.org/drm/igt-gpu-tools/. | |
258 | ||
259 | To build IGT, start by installing its build dependencies. In Debian-based | |
260 | systems:: | |
261 | ||
262 | # apt-get build-dep intel-gpu-tools | |
263 | ||
264 | And in Fedora-based systems:: | |
265 | ||
266 | # dnf builddep intel-gpu-tools | |
267 | ||
268 | Then clone the repository:: | |
269 | ||
270 | $ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools | |
271 | ||
272 | Configure the build system and start the build:: | |
273 | ||
274 | $ cd igt-gpu-tools && ./autogen.sh && make -j6 | |
275 | ||
276 | Download the piglit dependency:: | |
277 | ||
278 | $ ./scripts/run-tests.sh -d | |
279 | ||
280 | And run the tests:: | |
281 | ||
282 | $ ./scripts/run-tests.sh -t kms -t core -s | |
283 | ||
284 | run-tests.sh is a wrapper around piglit that will execute the tests matching | |
285 | the -t options. A report in HTML format will be available in | |
286 | ./results/html/index.html. Results can be compared with piglit. | |
287 | ||
a8182863 DV |
288 | Display CRC Support |
289 | ------------------- | |
290 | ||
291 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c | |
292 | :doc: CRC ABI | |
293 | ||
760f71e7 DV |
294 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c |
295 | :export: | |
296 | ||
0cad7f71 DV |
297 | Debugfs Support |
298 | --------------- | |
299 | ||
300 | .. kernel-doc:: include/drm/drm_debugfs.h | |
301 | :internal: | |
302 | ||
303 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs.c | |
304 | :export: | |
305 | ||
e2271704 DV |
306 | Sysfs Support |
307 | ============= | |
308 | ||
309 | .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c | |
310 | :doc: overview | |
311 | ||
312 | .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c | |
313 | :export: | |
314 | ||
315 | ||
ca00c2b9 | 316 | VBlank event handling |
22554020 | 317 | ===================== |
ca00c2b9 JN |
318 | |
319 | The DRM core exposes two vertical blank related ioctls: | |
320 | ||
321 | DRM_IOCTL_WAIT_VBLANK | |
322 | This takes a struct drm_wait_vblank structure as its argument, and | |
323 | it is used to block or request a signal when a specified vblank | |
324 | event occurs. | |
325 | ||
326 | DRM_IOCTL_MODESET_CTL | |
327 | This was only used for user-mode-settind drivers around modesetting | |
328 | changes to allow the kernel to update the vblank interrupt after | |
329 | mode setting, since on many devices the vertical blank counter is | |
330 | reset to 0 at some point during modeset. Modern drivers should not | |
331 | call this any more since with kernel mode setting it is a no-op. | |
309aa926 US |
332 | |
333 | Userspace API Structures | |
334 | ======================== | |
335 | ||
336 | .. kernel-doc:: include/uapi/drm/drm_mode.h | |
337 | :doc: overview | |
338 | ||
339 | .. kernel-doc:: include/uapi/drm/drm_mode.h | |
340 | :internal: |