aboutsummaryrefslogtreecommitdiffstats
path: root/man/drm.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/drm.xml')
-rw-r--r--man/drm.xml137
1 files changed, 137 insertions, 0 deletions
diff --git a/man/drm.xml b/man/drm.xml
new file mode 100644
index 00000000..5a49fe13
--- /dev/null
+++ b/man/drm.xml
@@ -0,0 +1,137 @@
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>
generated by cgit v1.2.3 (git 2.39.2)