man/drm.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3           "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
   7   Dedicated to the Public Domain
   8 -->
   9
  10 <refentry id="drm">
  11   <refentryinfo>
  12     <title>Direct Rendering Manager</title>
  13     <productname>libdrm</productname>
  14     <date>September 2012</date>
  15     <authorgroup>
  16       <author>
  17         <contrib>Developer</contrib>
  18         <firstname>David</firstname>
  19         <surname>Herrmann</surname>
  20         <email>dh.herrmann@googlemail.com</email>
  21       </author>
  22     </authorgroup>
  23   </refentryinfo>
  24
  25   <refmeta>
  26     <refentrytitle>drm</refentrytitle>
  27     <manvolnum>7</manvolnum>
  28   </refmeta>
  29
  30   <refnamediv>
  31     <refname>drm</refname>
  32     <refpurpose>Direct Rendering Manager</refpurpose>
  33   </refnamediv>
  34
  35   <refsynopsisdiv>
  36     <funcsynopsis>
  37       <funcsynopsisinfo>#include &lt;xf86drm.h&gt;</funcsynopsisinfo>
  38     </funcsynopsis>
  39   </refsynopsisdiv>
  40
  41   <refsect1>
  42     <title>Description</title>
  43     <para>The <emphasis>Direct Rendering Manager</emphasis> (DRM) is a framework
  44           to manage <emphasis>Graphics Processing Units</emphasis> (GPUs). It is
  45           designed to support the needs of complex graphics devices, usually
  46           containing programmable pipelines well suited to 3D graphics
  47           acceleration. Furthermore, it is responsible for memory management,
  48           interrupt handling and DMA to provide a uniform interface to
  49           applications.</para>
  50
  51     <para>In earlier days, the kernel framework was solely used to provide raw
  52           hardware access to priviledged user-space processes which implement
  53           all the hardware abstraction layers. But more and more tasks where
  54           moved into the kernel. All these interfaces are based on
  55           <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  56           commands on the DRM character device. The <emphasis>libdrm</emphasis>
  57           library provides wrappers for these system-calls and many helpers to
  58           simplify the API.</para>
  59
  60     <para>When a GPU is detected, the DRM system loads a driver for the detected
  61           hardware type. Each connected GPU is then presented to user-space via
  62           a character-device that is usually available as
  63           <filename>/dev/dri/card0</filename> and can be accessed with
  64           <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>
  65           and
  66           <citerefentry><refentrytitle>close</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
  67           However, it still depends on the grapics driver which interfaces are
  68           available on these devices. If an interface is not available, the
  69           syscalls will fail with <literal>EINVAL</literal>.</para>
  70
  71     <refsect2>
  72       <title>Authentication</title>
  73       <para>All DRM devices provide authentication mechanisms. Only a DRM-Master
  74             is allowed to perform mode-setting or modify core state and only one
  75             user can be DRM-Master at a time. See
  76             <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  77             for information on how to become DRM-Master and what the limitations
  78             are. Other DRM users can be authenticated to the DRM-Master via
  79             <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  80             so they can perform buffer allocations and rendering.</para>
  81     </refsect2>
  82
  83     <refsect2>
  84       <title>Mode-Setting</title>
  85       <para>Managing connected monitors and displays and changing the current
  86             modes is called <emphasis>Mode-Setting</emphasis>. This is
  87             restricted to the current DRM-Master. Historically, this was
  88             implemented in user-space, but new DRM drivers implement a kernel
  89             interface to perform mode-setting called
  90             <emphasis>Kernel Mode Setting</emphasis> (KMS). If your
  91             hardware-driver supports it, you can use the KMS API provided by
  92             DRM. This includes allocating framebuffers, selecting modes and
  93             managing CRTCs and encoders. See
  94             <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>
  95             for more.</para>
  96     </refsect2>
  97
  98     <refsect2>
  99       <title>Memory Management</title>
 100       <para>The most sophisticated tasks for GPUs today is managing memory
 101             objects. Textures, framebuffers, command-buffers and all other kinds
 102             of commands for the GPU have to be stored in memory. The DRM driver
 103             takes care of managing all memory objects, flushing caches,
 104             synchronizing access and providing CPU access to GPU memory. All
 105             memory management is hardware driver dependent. However, two generic
 106             frameworks are available that are used by most DRM drivers. These
 107             are the <emphasis>Translation Table Manager</emphasis> (TTM) and the
 108             <emphasis>Graphics Execution Manager</emphasis> (GEM). They provide
 109             generic APIs to create, destroy and access buffers from user-space.
 110             However, there are still many differences between the drivers so
 111             driver-depedent code is still needed. Many helpers are provided in
 112             <emphasis>libgbm</emphasis> (Graphics Buffer Manager) from the
 113             <emphasis>mesa-project</emphasis>. For more information on DRM
 114             memory-management, see
 115             <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 116     </refsect2>
 117   </refsect1>
 118
 119   <refsect1>
 120     <title>Reporting Bugs</title>
 121     <para>Bugs in this manual should be reported to
 122           http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
 123           "libdrm" as the component.</para>
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>See Also</title>
 128     <para>
 129       <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 130       <citerefentry><refentrytitle>drm-memory</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 131       <citerefentry><refentrytitle>drmSetMaster</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 132       <citerefentry><refentrytitle>drmAuthMagic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 133       <citerefentry><refentrytitle>drmAvailable</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 134       <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 135     </para>
 136   </refsect1>
 137 </refentry>