Commit | Line | Data |
---|---|---|
ca00c2b9 JN |
1 | Userland interfaces |
2 | =================== | |
3 | ||
4 | The DRM core exports several interfaces to applications, generally | |
5 | intended to be used through corresponding libdrm wrapper functions. In | |
6 | addition, drivers export device-specific interfaces for use by userspace | |
7 | drivers & device-aware applications through ioctls and sysfs files. | |
8 | ||
9 | External interfaces include: memory mapping, context management, DMA | |
10 | operations, AGP management, vblank control, fence management, memory | |
11 | management, and output management. | |
12 | ||
13 | Cover generic ioctls and sysfs layout here. We only need high-level | |
14 | info, since man pages should cover the rest. | |
15 | ||
16 | Render nodes | |
17 | ------------ | |
18 | ||
19 | DRM core provides multiple character-devices for user-space to use. | |
20 | Depending on which device is opened, user-space can perform a different | |
21 | set of operations (mainly ioctls). The primary node is always created | |
22 | and called card<num>. Additionally, a currently unused control node, | |
23 | called controlD<num> is also created. The primary node provides all | |
24 | legacy operations and historically was the only interface used by | |
25 | userspace. With KMS, the control node was introduced. However, the | |
26 | planned KMS control interface has never been written and so the control | |
27 | node stays unused to date. | |
28 | ||
29 | With the increased use of offscreen renderers and GPGPU applications, | |
30 | clients no longer require running compositors or graphics servers to | |
31 | make use of a GPU. But the DRM API required unprivileged clients to | |
32 | authenticate to a DRM-Master prior to getting GPU access. To avoid this | |
33 | step and to grant clients GPU access without authenticating, render | |
34 | nodes were introduced. Render nodes solely serve render clients, that | |
35 | is, no modesetting or privileged ioctls can be issued on render nodes. | |
36 | Only non-global rendering commands are allowed. If a driver supports | |
37 | render nodes, it must advertise it via the DRIVER_RENDER DRM driver | |
38 | capability. If not supported, the primary node must be used for render | |
39 | clients together with the legacy drmAuth authentication procedure. | |
40 | ||
41 | If a driver advertises render node support, DRM core will create a | |
42 | separate render node called renderD<num>. There will be one render node | |
43 | per device. No ioctls except PRIME-related ioctls will be allowed on | |
44 | this node. Especially GEM_OPEN will be explicitly prohibited. Render | |
45 | nodes are designed to avoid the buffer-leaks, which occur if clients | |
46 | guess the flink names or mmap offsets on the legacy interface. | |
47 | Additionally to this basic interface, drivers must mark their | |
48 | driver-dependent render-only ioctls as DRM_RENDER_ALLOW so render | |
49 | clients can use them. Driver authors must be careful not to allow any | |
50 | privileged ioctls on render nodes. | |
51 | ||
52 | With render nodes, user-space can now control access to the render node | |
53 | via basic file-system access-modes. A running graphics server which | |
54 | authenticates clients on the privileged primary/legacy node is no longer | |
55 | required. Instead, a client can open the render node and is immediately | |
56 | granted GPU access. Communication between clients (or servers) is done | |
57 | via PRIME. FLINK from render node to legacy node is not supported. New | |
58 | clients must not use the insecure FLINK interface. | |
59 | ||
60 | Besides dropping all modeset/global ioctls, render nodes also drop the | |
61 | DRM-Master concept. There is no reason to associate render clients with | |
62 | a DRM-Master as they are independent of any graphics server. Besides, | |
63 | they must work without any running master, anyway. Drivers must be able | |
64 | to run without a master object if they support render nodes. If, on the | |
65 | other hand, a driver requires shared state between clients which is | |
66 | visible to user-space and accessible beyond open-file boundaries, they | |
67 | cannot support render nodes. | |
68 | ||
69 | VBlank event handling | |
70 | --------------------- | |
71 | ||
72 | The DRM core exposes two vertical blank related ioctls: | |
73 | ||
74 | DRM_IOCTL_WAIT_VBLANK | |
75 | This takes a struct drm_wait_vblank structure as its argument, and | |
76 | it is used to block or request a signal when a specified vblank | |
77 | event occurs. | |
78 | ||
79 | DRM_IOCTL_MODESET_CTL | |
80 | This was only used for user-mode-settind drivers around modesetting | |
81 | changes to allow the kernel to update the vblank interrupt after | |
82 | mode setting, since on many devices the vertical blank counter is | |
83 | reset to 0 at some point during modeset. Modern drivers should not | |
84 | call this any more since with kernel mode setting it is a no-op. | |
85 | ||
86 | This second part of the GPU Driver Developer's Guide documents driver | |
87 | code, implementation details and also all the driver-specific userspace | |
88 | interfaces. Especially since all hardware-acceleration interfaces to | |
89 | userspace are driver specific for efficiency and other reasons these | |
90 | interfaces can be rather substantial. Hence every driver has its own | |
91 | chapter. |