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