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 | ||
2640981f DV |
163 | IOCTL Support on Device Nodes |
164 | ============================= | |
165 | ||
166 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
167 | :doc: driver specific ioctls | |
168 | ||
169 | .. kernel-doc:: include/drm/drm_ioctl.h | |
170 | :internal: | |
171 | ||
172 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
173 | :export: | |
174 | ||
175 | .. kernel-doc:: drivers/gpu/drm/drm_ioc32.c | |
176 | :export: | |
a8182863 DV |
177 | |
178 | Testing and validation | |
179 | ====================== | |
180 | ||
75ac4953 | 181 | Validating changes with IGT |
a8182863 | 182 | --------------------------- |
75ac4953 TV |
183 | |
184 | There's a collection of tests that aims to cover the whole functionality of | |
185 | DRM drivers and that can be used to check that changes to DRM drivers or the | |
186 | core don't regress existing functionality. This test suite is called IGT and | |
187 | its code can be found in https://cgit.freedesktop.org/drm/igt-gpu-tools/. | |
188 | ||
189 | To build IGT, start by installing its build dependencies. In Debian-based | |
190 | systems:: | |
191 | ||
192 | # apt-get build-dep intel-gpu-tools | |
193 | ||
194 | And in Fedora-based systems:: | |
195 | ||
196 | # dnf builddep intel-gpu-tools | |
197 | ||
198 | Then clone the repository:: | |
199 | ||
200 | $ git clone git://anongit.freedesktop.org/drm/igt-gpu-tools | |
201 | ||
202 | Configure the build system and start the build:: | |
203 | ||
204 | $ cd igt-gpu-tools && ./autogen.sh && make -j6 | |
205 | ||
206 | Download the piglit dependency:: | |
207 | ||
208 | $ ./scripts/run-tests.sh -d | |
209 | ||
210 | And run the tests:: | |
211 | ||
212 | $ ./scripts/run-tests.sh -t kms -t core -s | |
213 | ||
214 | run-tests.sh is a wrapper around piglit that will execute the tests matching | |
215 | the -t options. A report in HTML format will be available in | |
216 | ./results/html/index.html. Results can be compared with piglit. | |
217 | ||
a8182863 DV |
218 | Display CRC Support |
219 | ------------------- | |
220 | ||
221 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c | |
222 | :doc: CRC ABI | |
223 | ||
760f71e7 DV |
224 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs_crc.c |
225 | :export: | |
226 | ||
0cad7f71 DV |
227 | Debugfs Support |
228 | --------------- | |
229 | ||
230 | .. kernel-doc:: include/drm/drm_debugfs.h | |
231 | :internal: | |
232 | ||
233 | .. kernel-doc:: drivers/gpu/drm/drm_debugfs.c | |
234 | :export: | |
235 | ||
e2271704 DV |
236 | Sysfs Support |
237 | ============= | |
238 | ||
239 | .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c | |
240 | :doc: overview | |
241 | ||
242 | .. kernel-doc:: drivers/gpu/drm/drm_sysfs.c | |
243 | :export: | |
244 | ||
245 | ||
ca00c2b9 | 246 | VBlank event handling |
22554020 | 247 | ===================== |
ca00c2b9 JN |
248 | |
249 | The DRM core exposes two vertical blank related ioctls: | |
250 | ||
251 | DRM_IOCTL_WAIT_VBLANK | |
252 | This takes a struct drm_wait_vblank structure as its argument, and | |
253 | it is used to block or request a signal when a specified vblank | |
254 | event occurs. | |
255 | ||
256 | DRM_IOCTL_MODESET_CTL | |
257 | This was only used for user-mode-settind drivers around modesetting | |
258 | changes to allow the kernel to update the vblank interrupt after | |
259 | mode setting, since on many devices the vertical blank counter is | |
260 | reset to 0 at some point during modeset. Modern drivers should not | |
261 | call this any more since with kernel mode setting it is a no-op. |