[PATCH libdrm 2/4] man: add drm.7 overview page

[David Herrmann <dh.herrmann@googlemail.com>]

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@googlemail.com>
Reviewed-by: Jesse Barnes <jbarnes@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@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@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 &lt;xf86drm.h&gt;</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