aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJesse Barnes <jbarnes@virtuousgeek.org>2009-10-26 16:06:31 -0400
committerDave Airlie <airlied@redhat.com>2010-04-20 18:12:11 -0400
commit2d2ef822758e3f5da59c40a392d0c6d89394d4b4 (patch)
tree95f99075fc8d67b2ccc99fa7c937c325c7e39a8a
parent10fd883ce384706f88554a0b08cc4d63345e7d8b (diff)
drm: add initial DRM developer documentation
Add a DRM DocBook providing basic information about DRM interfaces, including TTM, GEM, KMS and vblank infrastructure. Intended to provide information to new and existing developers about how to perform driver initialization, implement mode setting and other DRM features. Signed-off-by: Jesse Barnes <jbarnes@virtuousgeek.org> Signed-off-by: Dave Airlie <airlied@redhat.com>
Diffstat
-rw-r--r--Documentation/DocBook/Makefile2
-rw-r--r--Documentation/DocBook/drm.tmpl839
2 files changed, 840 insertions, 1 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 325cfd1d6d99..c7e5dc7e8cb3 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -14,7 +14,7 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \
14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
15 mac80211.xml debugobjects.xml sh.xml regulator.xml \ 15 mac80211.xml debugobjects.xml sh.xml regulator.xml \
16 alsa-driver-api.xml writing-an-alsa-driver.xml \ 16 alsa-driver-api.xml writing-an-alsa-driver.xml \
17 tracepoint.xml media.xml 17 tracepoint.xml media.xml drm.xml
18 18
19### 19###
20# The build process is as follows (targets): 20# The build process is as follows (targets):
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
new file mode 100644
index 000000000000..7583dc7cf64d
--- /dev/null
+++ b/Documentation/DocBook/drm.tmpl
@@ -0,0 +1,839 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="drmDevelopersGuide">
6 <bookinfo>
7 <title>Linux DRM Developer's Guide</title>
8
9 <copyright>
10 <year>2008-2009</year>
11 <holder>
12 Intel Corporation (Jesse Barnes &lt;jesse.barnes@intel.com&gt;)
13 </holder>
14 </copyright>
15
16 <legalnotice>
17 <para>
18 The contents of this file may be used under the terms of the GNU
19 General Public License version 2 (the "GPL") as distributed in
20 the kernel source COPYING file.
21 </para>
22 </legalnotice>
23 </bookinfo>
24
25<toc></toc>
26
27 <!-- Introduction -->
28
29 <chapter id="drmIntroduction">
30 <title>Introduction</title>
31 <para>
32 The Linux DRM layer contains code intended to support the needs
33 of complex graphics devices, usually containing programmable
34 pipelines well suited to 3D graphics acceleration. Graphics
35 drivers in the kernel can make use of DRM functions to make
36 tasks like memory management, interrupt handling and DMA easier,
37 and provide a uniform interface to applications.
38 </para>
39 <para>
40 A note on versions: this guide covers features found in the DRM
41 tree, including the TTM memory manager, output configuration and
42 mode setting, and the new vblank internals, in addition to all
43 the regular features found in current kernels.
44 </para>
45 <para>
46 [Insert diagram of typical DRM stack here]
47 </para>
48 </chapter>
49
50 <!-- Internals -->
51
52 <chapter id="drmInternals">
53 <title>DRM Internals</title>
54 <para>
55 This chapter documents DRM internals relevant to driver authors
56 and developers working to add support for the latest features to
57 existing drivers.
58 </para>
59 <para>
60 First, we'll go over some typical driver initialization
61 requirements, like setting up command buffers, creating an
62 initial output configuration, and initializing core services.
63 Subsequent sections will cover core internals in more detail,
64 providing implementation notes and examples.
65 </para>
66 <para>
67 The DRM layer provides several services to graphics drivers,
68 many of them driven by the application interfaces it provides
69 through libdrm, the library that wraps most of the DRM ioctls.
70 These include vblank event handling, memory
71 management, output management, framebuffer management, command
72 submission &amp; fencing, suspend/resume support, and DMA
73 services.
74 </para>
75 <para>
76 The core of every DRM driver is struct drm_device. Drivers
77 will typically statically initialize a drm_device structure,
78 then pass it to drm_init() at load time.
79 </para>
80
81 <!-- Internals: driver init -->
82
83 <sect1>
84 <title>Driver initialization</title>
85 <para>
86 Before calling the DRM initialization routines, the driver must
87 first create and fill out a struct drm_device structure.
88 </para>
89 <programlisting>
90 static struct drm_driver driver = {
91 /* don't use mtrr's here, the Xserver or user space app should
92 * deal with them for intel hardware.
93 */
94 .driver_features =
95 DRIVER_USE_AGP | DRIVER_REQUIRE_AGP |
96 DRIVER_HAVE_IRQ | DRIVER_IRQ_SHARED | DRIVER_MODESET,
97 .load = i915_driver_load,
98 .unload = i915_driver_unload,
99 .firstopen = i915_driver_firstopen,
100 .lastclose = i915_driver_lastclose,
101 .preclose = i915_driver_preclose,
102 .save = i915_save,
103 .restore = i915_restore,
104 .device_is_agp = i915_driver_device_is_agp,
105 .get_vblank_counter = i915_get_vblank_counter,
106 .enable_vblank = i915_enable_vblank,
107 .disable_vblank = i915_disable_vblank,
108 .irq_preinstall = i915_driver_irq_preinstall,
109 .irq_postinstall = i915_driver_irq_postinstall,
110 .irq_uninstall = i915_driver_irq_uninstall,
111 .irq_handler = i915_driver_irq_handler,
112 .reclaim_buffers = drm_core_reclaim_buffers,
113 .get_map_ofs = drm_core_get_map_ofs,
114 .get_reg_ofs = drm_core_get_reg_ofs,
115 .fb_probe = intelfb_probe,
116 .fb_remove = intelfb_remove,
117 .fb_resize = intelfb_resize,
118 .master_create = i915_master_create,
119 .master_destroy = i915_master_destroy,
120#if defined(CONFIG_DEBUG_FS)
121 .debugfs_init = i915_debugfs_init,
122 .debugfs_cleanup = i915_debugfs_cleanup,
123#endif
124 .gem_init_object = i915_gem_init_object,
125 .gem_free_object = i915_gem_free_object,
126 .gem_vm_ops = &amp;i915_gem_vm_ops,
127 .ioctls = i915_ioctls,
128 .fops = {
129 .owner = THIS_MODULE,
130 .open = drm_open,
131 .release = drm_release,
132 .ioctl = drm_ioctl,
133 .mmap = drm_mmap,
134 .poll = drm_poll,
135 .fasync = drm_fasync,
136#ifdef CONFIG_COMPAT
137 .compat_ioctl = i915_compat_ioctl,
138#endif
139 },
140 .pci_driver = {
141 .name = DRIVER_NAME,
142 .id_table = pciidlist,
143 .probe = probe,
144 .remove = __devexit_p(drm_cleanup_pci),
145 },
146 .name = DRIVER_NAME,
147 .desc = DRIVER_DESC,
148 .date = DRIVER_DATE,
149 .major = DRIVER_MAJOR,
150 .minor = DRIVER_MINOR,
151 .patchlevel = DRIVER_PATCHLEVEL,
152 };
153 </programlisting>
154 <para>
155 In the example above, taken from the i915 DRM driver, the driver
156 sets several flags indicating what core features it supports.
157 We'll go over the individual callbacks in later sections. Since
158 flags indicate which features your driver supports to the DRM
159 core, you need to set most of them prior to calling drm_init(). Some,
160 like DRIVER_MODESET can be set later based on user supplied parameters,
161 but that's the exception rather than the rule.
162 </para>
163 <variablelist>
164 <title>Driver flags</title>
165 <varlistentry>
166 <term>DRIVER_USE_AGP</term>
167 <listitem><para>
168 Driver uses AGP interface
169 </para></listitem>
170 </varlistentry>
171 <varlistentry>
172 <term>DRIVER_REQUIRE_AGP</term>
173 <listitem><para>
174 Driver needs AGP interface to function.
175 </para></listitem>
176 </varlisten