Adding upstream version 2.4.120.upstream/2.4.120

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 91 insertions, 0 deletions

diff --git a/man/drm.7.rst b/man/drm.7.rst
new file mode 100644
index 0000000..df2c1c7
--- /dev/null
+++ b/man/drm.7.rst
@@ -0,0 +1,91 @@
+===
+drm
+===
+
+------------------------
+Direct Rendering Manager
+------------------------
+
+:Date: September 2012
+:Manual section: 7
+:Manual group: Direct Rendering Manager
+
+Synopsis
+========
+
+``#include <xf86drm.h>``
+
+Description
+===========
+
+The *Direct Rendering Manager* (DRM) is a framework to manage *Graphics
+Processing Units* (GPUs). It is designed to support the needs of complex
+graphics devices, usually containing programmable pipelines well suited
+to 3D graphics acceleration. Furthermore, it is responsible for memory
+management, interrupt handling and DMA to provide a uniform interface to
+applications.
+
+In earlier days, the kernel framework was solely used to provide raw
+hardware access to privileged user-space processes which implement all
+the hardware abstraction layers. But more and more tasks were moved into
+the kernel. All these interfaces are based on **ioctl**\ (2) commands on
+the DRM character device. The *libdrm* library provides wrappers for these
+system-calls and many helpers to simplify the API.
+
+When a GPU is detected, the DRM system loads a driver for the detected
+hardware type. Each connected GPU is then presented to user-space via a
+character-device that is usually available as ``/dev/dri/card0`` and can
+be accessed with **open**\ (2) and **close**\ (2). However, it still
+depends on the graphics driver which interfaces are available on these
+devices. If an interface is not available, the syscalls will fail with
+``EINVAL``.
+
+Authentication
+--------------
+
+All DRM devices provide authentication mechanisms. Only a DRM master is
+allowed to perform mode-setting or modify core state and only one user
+can be DRM master at a time. See **drmSetMaster**\ (3) for information
+on how to become DRM master and what the limitations are. Other DRM users
+can be authenticated to the DRM-Master via **drmAuthMagic**\ (3) so they
+can perform buffer allocations and rendering.
+
+Mode-Setting
+------------
+
+Managing connected monitors and displays and changing the current modes
+is called *Mode-Setting*. This is restricted to the current DRM master.
+Historically, this was implemented in user-space, but new DRM drivers
+implement a kernel interface to perform mode-setting called *Kernel Mode
+Setting* (KMS). If your hardware-driver supports it, you can use the KMS
+API provided by DRM. This includes allocating framebuffers, selecting
+modes and managing CRTCs and encoders. See **drm-kms**\ (7) for more.
+
+Memory Management
+-----------------
+
+The most sophisticated tasks for GPUs today is managing memory objects.
+Textures, framebuffers, command-buffers and all other kinds of commands
+for the GPU have to be stored in memory. The DRM driver takes care of
+managing all memory objects, flushing caches, synchronizing access and
+providing CPU access to GPU memory. All memory management is hardware
+driver dependent. However, two generic frameworks are available that are
+used by most DRM drivers. These are the *Translation Table Manager*
+(TTM) and the *Graphics Execution Manager* (GEM). They provide generic
+APIs to create, destroy and access buffers from user-space. However,
+there are still many differences between the drivers so driver-dependent
+code is still needed. Many helpers are provided in *libgbm* (Graphics
+Buffer Manager) from the *Mesa* project. For more information on DRM
+memory management, see **drm-memory**\ (7).
+
+Reporting Bugs
+==============
+
+Bugs in this manual should be reported to
+https://gitlab.freedesktop.org/mesa/drm/-/issues.
+
+See Also
+========
+
+**drm-kms**\ (7), **drm-memory**\ (7), **drmSetMaster**\ (3),
+**drmAuthMagic**\ (3), **drmAvailable**\ (3), **drmOpen**\ (3)