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 <dh.herrmann@googlemail.com> Reviewed-by: Jesse Barnes <jbarnes@virtuousgeek.org>main
David Herrmann
Jesse Barnes
parent
6b7e45c751
commit
0a766a5388
|
|
@ -5,6 +5,7 @@
|
|||
#
|
||||
|
||||
MANPAGES = \
|
||||
drm.7 \
|
||||
drmAvailable.3 \
|
||||
drmHandleEvent.3 \
|
||||
drmModeGetResources.3
|
||||
|
|
|
|||
|
|
@ -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 <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>
|
||||
Loading…
Reference in New Issue