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 | |
88 | job done. | |
89 | ||
90 | - The userspace patches must be against the canonical upstream, not some vendor | |
91 | fork. This is to make sure that no one cheats on the review and testing | |
92 | requirements by doing a quick fork. | |
93 | ||
94 | - The kernel patch can only be merged after all the above requirements are met, | |
95 | but it **must** be merged **before** the userspace patches land. uAPI always flows | |
96 | from the kernel, doing things the other way round risks divergence of the uAPI | |
97 | definitions and header files. | |
98 | ||
99 | These are fairly steep requirements, but have grown out from years of shared | |
100 | pain and experience with uAPI added hastily, and almost always regretted about | |
101 | just as fast. GFX devices change really fast, requiring a paradigm shift and | |
102 | entire new set of uAPI interfaces every few years at least. Together with the | |
103 | Linux kernel's guarantee to keep existing userspace running for 10+ years this | |
104 | is already rather painful for the DRM subsystem, with multiple different uAPIs | |
105 | for the same thing co-existing. If we add a few more complete mistakes into the | |
106 | mix every year it would be entirely unmanageable. | |
107 | ||
b93658f8 DV |
108 | .. _drm_render_node: |
109 | ||
ca00c2b9 | 110 | Render nodes |
22554020 | 111 | ============ |
ca00c2b9 JN |
112 | |
113 | DRM core provides multiple character-devices for user-space to use. | |
114 | Depending on which device is opened, user-space can perform a different | |
115 | set of operations (mainly ioctls). The primary node is always created | |
116 | and called card<num>. Additionally, a currently unused control node, | |
117 | called controlD<num> is also created. The primary node provides all | |
118 | legacy operations and historically was the only interface used by | |
119 | userspace. With KMS, the control node was introduced. However, the | |
120 | planned KMS control interface has never been written and so the control | |
121 | node stays unused to date. | |
122 | ||
123 | With the increased use of offscreen renderers and GPGPU applications, | |
124 | clients no longer require running compositors or graphics servers to | |
125 | make use of a GPU. But the DRM API required unprivileged clients to | |
126 | authenticate to a DRM-Master prior to getting GPU access. To avoid this | |
127 | step and to grant clients GPU access without authenticating, render | |
128 | nodes were introduced. Render nodes solely serve render clients, that | |
129 | is, no modesetting or privileged ioctls can be issued on render nodes. | |
130 | Only non-global rendering commands are allowed. If a driver supports | |
131 | render nodes, it must advertise it via the DRIVER_RENDER DRM driver | |
132 | capability. If not supported, the primary node must be used for render | |
133 | clients together with the legacy drmAuth authentication procedure. | |
134 | ||
135 | If a driver advertises render node support, DRM core will create a | |
136 | separate render node called renderD<num>. There will be one render node | |
137 | per device. No ioctls except PRIME-related ioctls will be allowed on | |
138 | this node. Especially GEM_OPEN will be explicitly prohibited. Render | |
139 | nodes are designed to avoid the buffer-leaks, which occur if clients | |
140 | guess the flink names or mmap offsets on the legacy interface. | |
141 | Additionally to this basic interface, drivers must mark their | |
142 | driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render | |
143 | clients can use them. Driver authors must be careful not to allow any | |
144 | privileged ioctls on render nodes. | |
145 | ||
146 | With render nodes, user-space can now control access to the render node | |
147 | via basic file-system access-modes. A running graphics server which | |
148 | authenticates clients on the privileged primary/legacy node is no longer | |
149 | required. Instead, a client can open the render node and is immediately | |
150 | granted GPU access. Communication between clients (or servers) is done | |
151 | via PRIME. FLINK from render node to legacy node is not supported. New | |
152 | clients must not use the insecure FLINK interface. | |
153 | ||
154 | Besides dropping all modeset/global ioctls, render nodes also drop the | |
155 | DRM-Master concept. There is no reason to associate render clients with | |
156 | a DRM-Master as they are independent of any graphics server. Besides, | |
157 | they must work without any running master, anyway. Drivers must be able | |
158 | to run without a master object if they support render nodes. If, on the | |
159 | other hand, a driver requires shared state between clients which is | |
160 | visible to user-space and accessible beyond open-file boundaries, they | |
161 | cannot support render nodes. | |
162 | ||
bb2eaba6 DV |
163 | .. _drm_driver_ioctl: |
164 | ||
2640981f DV |
165 | IOCTL Support on Device Nodes |
166 | ============================= | |
167 | ||
168 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
169 | :doc: driver specific ioctls | |
170 | ||
371cadd8 DV |
171 | Recommended IOCTL Return Values |
172 | ------------------------------- | |
173 | ||
174 | In theory a driver's IOCTL callback is only allowed to return very few error | |
175 | codes. In practice it's good to abuse a few more. This section documents common | |
176 | practice within the DRM subsystem: | |
177 | ||
178 | ENOENT: | |
179 | Strictly this should only be used when a file doesn't exist e.g. when | |
180 | calling the open() syscall. We reuse that to signal any kind of object | |
181 | lookup failure, e.g. for unknown GEM buffer object handles, unknown KMS | |
182 | object handles and similar cases. | |
183 | ||
184 | ENOSPC: | |
185 | Some drivers use this to differentiate "out of kernel memory" from "out | |
186 | of VRAM". Sometimes also applies to other limited gpu resources used for | |
187 | rendering (e.g. when you have a special limited compression buffer). | |
188 | Sometimes resource allocation/reservation issues in command submission | |
189 | IOCTLs are also signalled through EDEADLK. | |
190 | ||
191 | Simply running out of kernel/system memory is signalled through ENOMEM. | |
192 | ||
cba8087d | 193 | EPERM/EACCES: |
371cadd8 DV |
194 | Returned for an operation that is valid, but needs more privileges. |
195 | E.g. root-only or much more common, DRM master-only operations return | |
196 | this when when called by unpriviledged clients. There's no clear | |
cba8087d | 197 | difference between EACCES and EPERM. |
371cadd8 DV |
198 | |
199 | ENODEV: | |
9edb6a0b DV |
200 | The device is not (yet) present or fully initialized. |
201 | ||
202 | EOPNOTSUPP: | |
371cadd8 DV |
203 | Feature (like PRIME, modesetting, GEM) is not supported by the driver. |
204 | ||
205 | ENXIO: | |
206 | Remote failure, either a hardware transaction (like i2c), but also used | |
207 | when the exporting driver of a shared dma-buf or fence doesn't support a | |
208 | feature needed. | |
209 | ||
210 | EINTR: | |
211 | DRM drivers assume that userspace restarts all IOCTLs. Any DRM IOCTL can | |
212 | return EINTR and in such a case should be restarted with the IOCTL | |
213 | parameters left unchanged. | |
214 | ||
215 | EIO: | |
216 | The GPU died and couldn't be resurrected through a reset. Modesetting | |
217 | hardware failures are signalled through the "link status" connector | |
218 | property. | |
219 | ||
220 | EINVAL: | |
221 | Catch-all for anything that is an invalid argument combination which | |
222 | cannot work. | |
223 | ||
224 | IOCTL also use other error codes like ETIME, EFAULT, EBUSY, ENOTTY but their | |
225 | usage is in line with the common meanings. The above list tries to just document | |
226 | DRM specific patterns. Note that ENOTTY has the slightly unintuitive meaning of | |
227 | "this IOCTL does not exist", and is used exactly as such in DRM. | |
228 | ||
2640981f DV |
229 | .. kernel-doc:: include/drm/drm_ioctl.h |
230 | :internal: | |
231 | ||
232 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
233 | :export: | |
234 | ||
235 | .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c | |
236 | :export: | |
a8182863 DV |
237 | |
238 | Testing and validation | |
239 | ====================== | |
240 | ||
badfa5be DV |
241 | Testing Requirements for userspace API |
242 | -------------------------------------- | |
243 | ||
244 | New cross-driver userspace interface extensions, like new IOCTL, new KMS | |
245 | properties, new files in sysfs or anything else that constitutes an API change | |
246 | should have driver-agnostic testcases in IGT for that feature, if such a test | |
247 | can be reasonably made using IGT for the target hardware. | |
248 | ||
75ac4953 | 249 | Validating changes with IGT |
a8182863 | 250 | --------------------------- |
75ac4953 TV |
251 | |
252 | There's a collection of tests that aims to cover the whole functionality of | |
253 | DRM drivers and that can be used to check that changes to DRM drivers or the | |
254 | core don't regress existing functionality. This test suite is called IGT and | |
255 | its code can be found in https://cgit.freedesktop.org/drm/igt-gpu-tools/. | |
256 | ||
257 | To build IGT, start by installing its build dependencies. In Debian-based | |
258 | systems:: | |
259 | ||
260 | # apt-get build-dep intel-gpu-tools | |
261 | ||
262 | And in Fedora-based systems:: | |
263 | ||
264 | # dnf builddep intel-gpu-tools | |
265 | ||
266 | Then clone the repository:: | |
267 | ||
268 | $ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools | |
269 | ||
270 | Configure the build system and start the build:: | |
271 | ||
272 | $ cd igt-gpu-tools && ./autogen.sh && make -j6 | |
273 | ||
274 | Download the piglit dependency:: | |
275 | ||
276 | $ ./scripts/run-tests.sh -d | |
277 | ||
278 | And run the tests:: | |
279 | ||
280 | $ ./scripts/run-tests.sh -t kms -t core -s | |
281 | ||
282 | run-tests.sh is a wrapper around piglit that will execute the tests matching | |
283 | the -t options. A report in HTML format will be available in | |
284 | ./results/html/index.html. Results can be compared with piglit. | |
285 | ||
a8182863 DV |
286 | Display CRC Support |
287 | ------------------- | |
288 | ||
289 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c | |
290 | :doc: CRC ABI | |
291 | ||
760f71e7 DV |
292 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c |
293 | :export: | |
294 | ||
0cad7f71 DV |
295 | Debugfs Support |
296 | --------------- | |
297 | ||
298 | .. kernel-doc:: include/drm/drm_debugfs.h | |
299 | :internal: | |
300 | ||
301 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs.c | |
302 | :export: | |
303 | ||
e2271704 DV |
304 | Sysfs Support |
305 | ============= | |
306 | ||
307 | .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c | |
308 | :doc: overview | |
309 | ||
310 | .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c | |
311 | :export: | |
312 | ||
313 | ||
ca00c2b9 | 314 | VBlank event handling |
22554020 | 315 | ===================== |
ca00c2b9 JN |
316 | |
317 | The DRM core exposes two vertical blank related ioctls: | |
318 | ||
319 | DRM_IOCTL_WAIT_VBLANK | |
320 | This takes a struct drm_wait_vblank structure as its argument, and | |
321 | it is used to block or request a signal when a specified vblank | |
322 | event occurs. | |
323 | ||
324 | DRM_IOCTL_MODESET_CTL | |
325 | This was only used for user-mode-settind drivers around modesetting | |
326 | changes to allow the kernel to update the vblank interrupt after | |
327 | mode setting, since on many devices the vertical blank counter is | |
328 | reset to 0 at some point during modeset. Modern drivers should not | |
329 | call this any more since with kernel mode setting it is a no-op. |