]>
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 SV |
17 | libdrm Device Lookup |
18 | ==================== | |
19 | ||
20 | .. kernel-doc:: drivers/gpu/drm/drm_ioctl.c | |
21 | :doc: getunique and setversion story | |
22 | ||
3b96a0b1 SV |
23 | |
24 | Primary Nodes, DRM Master and Authentication | |
25 | ============================================ | |
26 | ||
27 | .. kernel-doc:: drivers/gpu/drm/drm_auth.c | |
28 | :doc: master and authentication | |
29 | ||
30 | .. kernel-doc:: drivers/gpu/drm/drm_auth.c | |
31 | :export: | |
32 | ||
33 | .. kernel-doc:: include/drm/drm_auth.h | |
34 | :internal: | |
35 | ||
ca00c2b9 | 36 | Render nodes |
22554020 | 37 | ============ |
ca00c2b9 JN |
38 | |
39 | DRM core provides multiple character-devices for user-space to use. | |
40 | Depending on which device is opened, user-space can perform a different | |
41 | set of operations (mainly ioctls). The primary node is always created | |
42 | and called card<num>. Additionally, a currently unused control node, | |
43 | called controlD<num> is also created. The primary node provides all | |
44 | legacy operations and historically was the only interface used by | |
45 | userspace. With KMS, the control node was introduced. However, the | |
46 | planned KMS control interface has never been written and so the control | |
47 | node stays unused to date. | |
48 | ||
49 | With the increased use of offscreen renderers and GPGPU applications, | |
50 | clients no longer require running compositors or graphics servers to | |
51 | make use of a GPU. But the DRM API required unprivileged clients to | |
52 | authenticate to a DRM-Master prior to getting GPU access. To avoid this | |
53 | step and to grant clients GPU access without authenticating, render | |
54 | nodes were introduced. Render nodes solely serve render clients, that | |
55 | is, no modesetting or privileged ioctls can be issued on render nodes. | |
56 | Only non-global rendering commands are allowed. If a driver supports | |
57 | render nodes, it must advertise it via the DRIVER_RENDER DRM driver | |
58 | capability. If not supported, the primary node must be used for render | |
59 | clients together with the legacy drmAuth authentication procedure. | |
60 | ||
61 | If a driver advertises render node support, DRM core will create a | |
62 | separate render node called renderD<num>. There will be one render node | |
63 | per device. No ioctls except PRIME-related ioctls will be allowed on | |
64 | this node. Especially GEM_OPEN will be explicitly prohibited. Render | |
65 | nodes are designed to avoid the buffer-leaks, which occur if clients | |
66 | guess the flink names or mmap offsets on the legacy interface. | |
67 | Additionally to this basic interface, drivers must mark their | |
68 | driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render | |
69 | clients can use them. Driver authors must be careful not to allow any | |
70 | privileged ioctls on render nodes. | |
71 | ||
72 | With render nodes, user-space can now control access to the render node | |
73 | via basic file-system access-modes. A running graphics server which | |
74 | authenticates clients on the privileged primary/legacy node is no longer | |
75 | required. Instead, a client can open the render node and is immediately | |
76 | granted GPU access. Communication between clients (or servers) is done | |
77 | via PRIME. FLINK from render node to legacy node is not supported. New | |
78 | clients must not use the insecure FLINK interface. | |
79 | ||
80 | Besides dropping all modeset/global ioctls, render nodes also drop the | |
81 | DRM-Master concept. There is no reason to associate render clients with | |
82 | a DRM-Master as they are independent of any graphics server. Besides, | |
83 | they must work without any running master, anyway. Drivers must be able | |
84 | to run without a master object if they support render nodes. If, on the | |
85 | other hand, a driver requires shared state between clients which is | |
86 | visible to user-space and accessible beyond open-file boundaries, they | |
87 | cannot support render nodes. | |
88 | ||
89 | VBlank event handling | |
22554020 | 90 | ===================== |
ca00c2b9 JN |
91 | |
92 | The DRM core exposes two vertical blank related ioctls: | |
93 | ||
94 | DRM_IOCTL_WAIT_VBLANK | |
95 | This takes a struct drm_wait_vblank structure as its argument, and | |
96 | it is used to block or request a signal when a specified vblank | |
97 | event occurs. | |
98 | ||
99 | DRM_IOCTL_MODESET_CTL | |
100 | This was only used for user-mode-settind drivers around modesetting | |
101 | changes to allow the kernel to update the vblank interrupt after | |
102 | mode setting, since on many devices the vertical blank counter is | |
103 | reset to 0 at some point during modeset. Modern drivers should not | |
104 | call this any more since with kernel mode setting it is a no-op. | |
105 | ||
106 | This second part of the GPU Driver Developer's Guide documents driver | |
107 | code, implementation details and also all the driver-specific userspace | |
108 | interfaces. Especially since all hardware-acceleration interfaces to | |
109 | userspace are driver specific for efficiency and other reasons these | |
110 | interfaces can be rather substantial. Hence every driver has its own | |
111 | chapter. |