[PATCH libdrm 2/4] man: add drm.7 overview page
David Herrmann
dh.herrmann at googlemail.com
Fri Sep 28 14:44:20 PDT 2012
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 <dh.herrmann at googlemail.com>
Reviewed-by: Jesse Barnes <jbarnes at virtuousgeek.org>
---
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 3030e5f..d55f444 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 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann at googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drm">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann at googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drm</refentrytitle>
+ <manvolnum>7</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drm</refname>
+ <refpurpose>Direct Rendering Manager</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>The <emphasis>Direct Rendering Manager</emphasis> (DRM) is a framework
+ to manage <emphasis>Graphics Processing Units</emphasis> (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.</para>
+
+ <para>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
+ <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ commands on the DRM character device. The <emphasis>libdrm</emphasis>
+ library provides wrappers for these system-calls and many helpers to
+ simplify the API.</para>
+
+ <para>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
+ <filename>/dev/dri/card0</filename> and can be accessed with
+ <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ and
+ <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
+ 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 <literal>EINVAL</literal>.</para>
+
+ <refsect2>
+ <title>Authentication</title>
+ <para>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
+ <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ for information on how to become DRM-Master and what the limitations
+ are. Other DRM users can be authenticated to the DRM-Master via
+ <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ so they can perform buffer allocations and rendering.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Mode-Setting</title>
+ <para>Managing connected monitors and displays and changing the current
+ modes is called <emphasis>Mode-Setting</emphasis>. 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
+ <emphasis>Kernel Mode Setting</emphasis> (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
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ for more.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Memory Management</title>
+ <para>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 <emphasis>Translation Table Manager</emphasis> (TTM) and the
+ <emphasis>Graphics Execution Manager</emphasis> (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
+ <emphasis>libgbm</emphasis> (Graphics Buffer Manager) from the
+ <emphasis>mesa-project</emphasis>. For more information on DRM
+ memory-management, see
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this manual should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
--
1.7.12.1
More information about the dri-devel
mailing list