| 1 |
=== |
| 2 |
drm |
| 3 |
=== |
| 4 |
|
| 5 |
------------------------ |
| 6 |
Direct Rendering Manager |
| 7 |
------------------------ |
| 8 |
|
| 9 |
:Date: September 2012 |
| 10 |
:Manual section: 7 |
| 11 |
:Manual group: Direct Rendering Manager |
| 12 |
|
| 13 |
Synopsis |
| 14 |
======== |
| 15 |
|
| 16 |
``#include <xf86drm.h>`` |
| 17 |
|
| 18 |
Description |
| 19 |
=========== |
| 20 |
|
| 21 |
The *Direct Rendering Manager* (DRM) is a framework to manage *Graphics |
| 22 |
Processing Units* (GPUs). It is designed to support the needs of complex |
| 23 |
graphics devices, usually containing programmable pipelines well suited |
| 24 |
to 3D graphics acceleration. Furthermore, it is responsible for memory |
| 25 |
management, interrupt handling and DMA to provide a uniform interface to |
| 26 |
applications. |
| 27 |
|
| 28 |
In earlier days, the kernel framework was solely used to provide raw |
| 29 |
hardware access to privileged user-space processes which implement all |
| 30 |
the hardware abstraction layers. But more and more tasks were moved into |
| 31 |
the kernel. All these interfaces are based on **ioctl**\ (2) commands on |
| 32 |
the DRM character device. The *libdrm* library provides wrappers for these |
| 33 |
system-calls and many helpers to simplify the API. |
| 34 |
|
| 35 |
When a GPU is detected, the DRM system loads a driver for the detected |
| 36 |
hardware type. Each connected GPU is then presented to user-space via a |
| 37 |
character-device that is usually available as ``/dev/dri/card0`` and can |
| 38 |
be accessed with **open**\ (2) and **close**\ (2). However, it still |
| 39 |
depends on the graphics driver which interfaces are available on these |
| 40 |
devices. If an interface is not available, the syscalls will fail with |
| 41 |
``EINVAL``. |
| 42 |
|
| 43 |
Authentication |
| 44 |
-------------- |
| 45 |
|
| 46 |
All DRM devices provide authentication mechanisms. Only a DRM master is |
| 47 |
allowed to perform mode-setting or modify core state and only one user |
| 48 |
can be DRM master at a time. See **drmSetMaster**\ (3) for information |
| 49 |
on how to become DRM master and what the limitations are. Other DRM users |
| 50 |
can be authenticated to the DRM-Master via **drmAuthMagic**\ (3) so they |
| 51 |
can perform buffer allocations and rendering. |
| 52 |
|
| 53 |
Mode-Setting |
| 54 |
------------ |
| 55 |
|
| 56 |
Managing connected monitors and displays and changing the current modes |
| 57 |
is called *Mode-Setting*. This is restricted to the current DRM master. |
| 58 |
Historically, this was implemented in user-space, but new DRM drivers |
| 59 |
implement a kernel interface to perform mode-setting called *Kernel Mode |
| 60 |
Setting* (KMS). If your hardware-driver supports it, you can use the KMS |
| 61 |
API provided by DRM. This includes allocating framebuffers, selecting |
| 62 |
modes and managing CRTCs and encoders. See **drm-kms**\ (7) for more. |
| 63 |
|
| 64 |
Memory Management |
| 65 |
----------------- |
| 66 |
|
| 67 |
The most sophisticated tasks for GPUs today is managing memory objects. |
| 68 |
Textures, framebuffers, command-buffers and all other kinds of commands |
| 69 |
for the GPU have to be stored in memory. The DRM driver takes care of |
| 70 |
managing all memory objects, flushing caches, synchronizing access and |
| 71 |
providing CPU access to GPU memory. All memory management is hardware |
| 72 |
driver dependent. However, two generic frameworks are available that are |
| 73 |
used by most DRM drivers. These are the *Translation Table Manager* |
| 74 |
(TTM) and the *Graphics Execution Manager* (GEM). They provide generic |
| 75 |
APIs to create, destroy and access buffers from user-space. However, |
| 76 |
there are still many differences between the drivers so driver-dependent |
| 77 |
code is still needed. Many helpers are provided in *libgbm* (Graphics |
| 78 |
Buffer Manager) from the *Mesa* project. For more information on DRM |
| 79 |
memory management, see **drm-memory**\ (7). |
| 80 |
|
| 81 |
Reporting Bugs |
| 82 |
============== |
| 83 |
|
| 84 |
Bugs in this manual should be reported to |
| 85 |
https://gitlab.freedesktop.org/mesa/libdrm/-/issues. |
| 86 |
|
| 87 |
See Also |
| 88 |
======== |
| 89 |
|
| 90 |
**drm-kms**\ (7), **drm-memory**\ (7), **drmSetMaster**\ (3), |
| 91 |
**drmAuthMagic**\ (3), **drmAvailable**\ (3), **drmOpen**\ (3) |