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 <xf86drm.h></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> 138