From 0a766a5388ba6ff0983ad5181a5f6644aea8050a Mon Sep 17 00:00:00 2001 From: David Herrmann Date: Fri, 28 Sep 2012 23:44:20 +0200 Subject: [PATCH] man: add drm.7 overview page The drm.xml file compiles to drm.7 and is meant as a global overview page for libdrm. It is targeted to new users of libdrm and redirects to all other main man-pages. Signed-off-by: David Herrmann Reviewed-by: Jesse Barnes --- man/Makefile.am | 1 + man/drm.xml | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 man/drm.xml diff --git a/man/Makefile.am b/man/Makefile.am index b93fdef..01b5699 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -5,6 +5,7 @@ # MANPAGES = \ + drm.7 \ drmAvailable.3 \ drmHandleEvent.3 \ drmModeGetResources.3 diff --git a/man/drm.xml b/man/drm.xml new file mode 100644 index 0000000..5a49fe1 --- /dev/null +++ b/man/drm.xml @@ -0,0 +1,137 @@ + + + + + + + + Direct Rendering Manager + libdrm + September 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + drm + 7 + + + + drm + Direct Rendering Manager + + + + + #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 priviledged user-space processes which implement + all the hardware abstraction layers. But more and more tasks where + moved into the kernel. All these interfaces are based on + ioctl2 + 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 + open2 + and + close2. + However, it still depends on the grapics 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 + drmSetMaster3 + for information on how to become DRM-Master and what the limitations + are. Other DRM users can be authenticated to the DRM-Master via + drmAuthMagic3 + 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-kms7 + 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-depedent 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-memory7. + + + + + Reporting Bugs + Bugs in this manual should be reported to + http://bugs.freedesktop.org under the "Mesa" product, with "Other" or + "libdrm" as the component. + + + + See Also + + drm-kms7, + drm-memory7, + drmSetMaster3, + drmAuthMagic3, + drmAvailable3, + drmOpen3 + + + -- 2.7.4