aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2012-10-04 02:29:23 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2012-10-04 02:29:23 -0400
commit612a9aab56a93533e76e3ad91642db7033e03b69 (patch)
tree8402096973f67af941f9392f7da06cca03e0b58a /Documentation
parent3a494318b14b1bc0f59d2d6ce84c505c74d82d2a (diff)
parent268d28371cd326be4dfcd7eba5917bf4b9d30c8f (diff)
Merge branch 'drm-next' of git://people.freedesktop.org/~airlied/linux
Pull drm merge (part 1) from Dave Airlie: "So first of all my tree and uapi stuff has a conflict mess, its my fault as the nouveau stuff didn't hit -next as were trying to rebase regressions out of it before we merged. Highlights: - SH mobile modesetting driver and associated helpers - some DRM core documentation - i915 modesetting rework, haswell hdmi, haswell and vlv fixes, write combined pte writing, ilk rc6 support, - nouveau: major driver rework into a hw core driver, makes features like SLI a lot saner to implement, - psb: add eDP/DP support for Cedarview - radeon: 2 layer page tables, async VM pte updates, better PLL selection for > 2 screens, better ACPI interactions The rest is general grab bag of fixes. So why part 1? well I have the exynos pull req which came in a bit late but was waiting for me to do something they shouldn't have and it looks fairly safe, and David Howells has some more header cleanups he'd like me to pull, that seem like a good idea, but I'd like to get this merge out of the way so -next dosen't get blocked." Tons of conflicts mostly due to silly include line changes, but mostly mindless. A few other small semantic conflicts too, noted from Dave's pre-merged branch. * 'drm-next' of git://people.freedesktop.org/~airlied/linux: (447 commits) drm/nv98/crypt: fix fuc build with latest envyas drm/nouveau/devinit: fixup various issues with subdev ctor/init ordering drm/nv41/vm: fix and enable use of "real" pciegart drm/nv44/vm: fix and enable use of "real" pciegart drm/nv04/dmaobj: fixup vm target handling in preparation for nv4x pcie drm/nouveau: store supported dma mask in vmmgr drm/nvc0/ibus: initial implementation of subdev drm/nouveau/therm: add support for fan-control modes drm/nouveau/hwmon: rename pwm0* to pmw1* to follow hwmon's rules drm/nouveau/therm: calculate the pwm divisor on nv50+ drm/nouveau/fan: rewrite the fan tachometer driver to get more precision, faster drm/nouveau/therm: move thermal-related functions to the therm subdev drm/nouveau/bios: parse the pwm divisor from the perf table drm/nouveau/therm: use the EXTDEV table to detect i2c monitoring devices drm/nouveau/therm: rework thermal table parsing drm/nouveau/gpio: expose the PWM/TOGGLE parameter found in the gpio vbios table drm/nouveau: fix pm initialization order drm/nouveau/bios: check that fixed tvdac gpio data is valid before using it drm/nouveau: log channel debug/error messages from client object rather than drm client drm/nouveau: have drm debugging macros build on top of core macros ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/drm.tmpl2835
1 files changed, 2226 insertions, 609 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 196b8b9dba11..b0300529ab13 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -6,11 +6,36 @@
6 <bookinfo> 6 <bookinfo>
7 <title>Linux DRM Developer's Guide</title> 7 <title>Linux DRM Developer's Guide</title>
8 8
9 <authorgroup>
10 <author>
11 <firstname>Jesse</firstname>
12 <surname>Barnes</surname>
13 <contrib>Initial version</contrib>
14 <affiliation>
15 <orgname>Intel Corporation</orgname>
16 <address>
17 <email>jesse.barnes@intel.com</email>
18 </address>
19 </affiliation>
20 </author>
21 <author>
22 <firstname>Laurent</firstname>
23 <surname>Pinchart</surname>
24 <contrib>Driver internals</contrib>
25 <affiliation>
26 <orgname>Ideas on board SPRL</orgname>
27 <address>
28 <email>laurent.pinchart@ideasonboard.com</email>
29 </address>
30 </affiliation>
31 </author>
32 </authorgroup>
33
9 <copyright> 34 <copyright>
10 <year>2008-2009</year> 35 <year>2008-2009</year>
11 <holder> 36 <year>2012</year>
12 Intel Corporation (Jesse Barnes &lt;jesse.barnes@intel.com&gt;) 37 <holder>Intel Corporation</holder>
13 </holder> 38 <holder>Laurent Pinchart</holder>
14 </copyright> 39 </copyright>
15 40
16 <legalnotice> 41 <legalnotice>
@@ -20,6 +45,17 @@
20 the kernel source COPYING file. 45 the kernel source COPYING file.
21 </para> 46 </para>
22 </legalnotice> 47 </legalnotice>
48
49 <revhistory>
50 <!-- Put document revisions here, newest first. -->
51 <revision>
52 <revnumber>1.0</revnumber>
53 <date>2012-07-13</date>
54 <authorinitials>LP</authorinitials>
55 <revremark>Added extensive documentation about driver internals.
56 </revremark>
57 </revision>
58 </revhistory>
23 </bookinfo> 59 </bookinfo>
24 60
25<toc></toc> 61<toc></toc>
@@ -72,342 +108,361 @@
72 submission &amp; fencing, suspend/resume support, and DMA 108 submission &amp; fencing, suspend/resume support, and DMA
73 services. 109 services.
74 </para> 110 </para>
75 <para>
76 The core of every DRM driver is struct drm_driver. Drivers
77 typically statically initialize a drm_driver structure,
78 then pass it to drm_init() at load time.
79 </para>
80 111
81 <!-- Internals: driver init --> 112 <!-- Internals: driver init -->
82 113
83 <sect1> 114 <sect1>
84 <title>Driver initialization</title> 115 <title>Driver Initialization</title>
85 <para> 116 <para>
86 Before calling the DRM initialization routines, the driver must 117 At the core of every DRM driver is a <structname>drm_driver</structname>
87 first create and fill out a struct drm_driver structure. 118 structure. Drivers typically statically initialize a drm_driver structure,
88 </para> 119 and then pass it to one of the <function>drm_*_init()</function> functions
89 <programlisting> 120 to register it with the DRM subsystem.
90 static struct drm_driver driver = {
91 /* Don't use MTRRs here; the Xserver or userspace 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 .llseek = noop_llseek,
140 },
141 .pci_driver = {
142 .name = DRIVER_NAME,
143 .id_table = pciidlist,
144 .probe = probe,
145 .remove = __devexit_p(drm_cleanup_pci),
146 },
147 .name = DRIVER_NAME,
148 .desc = DRIVER_DESC,
149 .date = DRIVER_DATE,
150 .major = DRIVER_MAJOR,
151 .minor = DRIVER_MINOR,
152 .patchlevel = DRIVER_PATCHLEVEL,
153 };
154 </programlisting>
155 <para>
156 In the example above, taken from the i915 DRM driver, the driver
157 sets several flags indicating what core features it supports;
158 we go over the individual callbacks in later sections. Since
159 flags indicate which features your driver supports to the DRM
160 core, you need to set most of them prior to calling drm_init(). Some,
161 like DRIVER_MODESET can be set later based on user supplied parameters,
162 but that's the exception rather than the rule.
163 </para>
164 <variablelist>
165 <title>Driver flags</title>
166 <varlistentry>
167 <term>DRIVER_USE_AGP</term>
168 <listitem><para>
169 Driver uses AGP interface
170 </para></listitem>
171 </varlistentry>
172 <varlistentry>
173 <term>DRIVER_REQUIRE_AGP</term>
174 <listitem><para>
175 Driver needs AGP interface to function.
176 </para></listitem>
177 </varlistentry>
178 <varlistentry>
179 <term>DRIVER_USE_MTRR</term>
180 <listitem>
181 <para>
182 Driver uses MTRR interface for mapping memory. Deprecated.
183 </para>
184 </listitem>
185 </varlistentry>
186 <varlistentry>
187 <term>DRIVER_PCI_DMA</term>
188 <listitem><para>
189 Driver is capable of PCI DMA. Deprecated.
190 </para></listitem>
191 </varlistentry>
192 <varlistentry>
193 <term>DRIVER_SG</term>
194 <listitem><para>
195 Driver can perform scatter/gather DMA. Deprecated.
196 </para></listitem>
197 </varlistentry>
198 <varlistentry>
199 <term>DRIVER_HAVE_DMA</term>
200 <listitem><para>Driver supports DMA. Deprecated.</para></listitem>
201 </varlistentry>
202 <varlistentry>
203 <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
204 <listitem>
205 <para>
206 DRIVER_HAVE_IRQ indicates whether the driver has an IRQ
207 handler. DRIVER_IRQ_SHARED indicates whether the device &amp;
208 handler support shared IRQs (note that this is required of
209 PCI drivers).
210 </para>
211 </listitem>
212 </varlistentry>
213 <varlistentry>
214 <term>DRIVER_DMA_QUEUE</term>
215 <listitem>
216 <para>
217 Should be set if the driver queues DMA requests and completes them
218 asynchronously. Deprecated.
219 </para>
220 </listitem>
221 </varlistentry>
222 <varlistentry>
223 <term>DRIVER_FB_DMA</term>
224 <listitem>
225 <para>
226 Driver supports DMA to/from the framebuffer. Deprecated.
227 </para>
228 </listitem>
229 </varlistentry>
230 <varlistentry>
231 <term>DRIVER_MODESET</term>
232 <listitem>
233 <para>
234 Driver supports mode setting interfaces.
235 </para>
236 </listitem>
237 </varlistentry>
238 </variablelist>
239 <para>
240 In this specific case, the driver requires AGP and supports
241 IRQs. DMA, as discussed later, is handled by device-specific ioctls
242 in this case. It also supports the kernel mode setting APIs, though
243 unlike in the actual i915 driver source, this example unconditionally
244 exports KMS capability.
245 </para> 121 </para>
246 </sect1> 122 <para>
247 123 The <structname>drm_driver</structname> structure contains static
248 <!-- Internals: driver load --> 124 information that describes the driver and features it supports, and
249 125 pointers to methods that the DRM core will call to implement the DRM API.
250 <sect1> 126 We will first go through the <structname>drm_driver</structname> static
251 <title>Driver load</title> 127 information fields, and will then describe individual operations in
252 <para> 128 details as they get used in later sections.
253 In the previous section, we saw what a typical drm_driver
254 structure might look like. One of the more important fields in
255 the structure is the hook for the load function.
256 </para>
257 <programlisting>
258 static struct drm_driver driver = {
259 ...
260 .load = i915_driver_load,
261 ...
262 };
263 </programlisting>
264 <para>
265 The load function has many responsibilities: allocating a driver
266 private structure, specifying supported performance counters,
267 configuring the device (e.g. mapping registers &amp; command
268 buffers), initializing the memory manager, and setting up the
269 initial output configuration.
270 </para>
271 <para>
272 If compatibility is a concern (e.g. with drivers converted over
273 to the new interfaces from the old ones), care must be taken to
274 prevent device initialization and control that is incompatible with
275 currently active userspace drivers. For instance, if user
276 level mode setting drivers are in use, it would be problematic
277 to perform output discovery &amp; configuration at load time.
278 Likewise, if user-level drivers unaware of memory management are
279 in use, memory management and command buffer setup may need to
280 be omitted. These requirements are driver-specific, and care
281 needs to be taken to keep both old and new applications and
282 libraries working. The i915 driver supports the "modeset"
283 module parameter to control whether advanced features are
284 enabled at load time or in legacy fashion.
285 </para> 129 </para>
286
287 <sect2> 130 <sect2>
288 <title>Driver private &amp; performance counters</title> 131 <title>Driver Information</title>
289 <para> 132 <sect3>
290 The driver private hangs off the main drm_device structure and 133 <title>Driver Features</title>
291 can be used for tracking various device-specific bits of 134 <para>
292 information, like register offsets, command buffer status, 135 Drivers inform the DRM core about their requirements and supported
293 register state for suspend/resume, etc. At load time, a 136 features by setting appropriate flags in the
294 driver may simply allocate one and set drm_device.dev_priv 137 <structfield>driver_features</structfield> field. Since those flags
295 appropriately; it should be freed and drm_device.dev_priv set 138 influence the DRM core behaviour since registration time, most of them
296 to NULL when the driver is unloaded. 139 must be set to registering the <structname>drm_driver</structname>
297 </para> 140 instance.
141 </para>
142 <synopsis>u32 driver_features;</synopsis>
143 <variablelist>
144 <title>Driver Feature Flags</title>
145 <varlistentry>
146 <term>DRIVER_USE_AGP</term>
147 <listitem><para>
148 Driver uses AGP interface, the DRM core will manage AGP resources.
149 </para></listitem>
150 </varlistentry>
151 <varlistentry>
152 <term>DRIVER_REQUIRE_AGP</term>
153 <listitem><para>
154 Driver needs AGP interface to function. AGP initialization failure
155 will become a fatal error.
156 </para></listitem>
157 </varlistentry>
158 <varlistentry>
159 <term>DRIVER_USE_MTRR</term>
160 <listitem><para>
161 Driver uses MTRR interface for mapping memory, the DRM core will
162 manage MTRR resources. Deprecated.
163 </para></listitem>
164 </varlistentry>
165 <varlistentry>
166 <term>DRIVER_PCI_DMA</term>
167 <listitem><para>
168 Driver is capable of PCI DMA, mapping of PCI DMA buffers to
169 userspace will be enabled. Deprecated.
170 </para></listitem>
171 </varlistentry>
172 <varlistentry>
173 <term>DRIVER_SG</term>
174 <listitem><para>
175 Driver can perform scatter/gather DMA, allocation and mapping of
176 scatter/gather buffers will be enabled. Deprecated.
177 </para></listitem>
178 </varlistentry>
179 <varlistentry>
180 <term>DRIVER_HAVE_DMA</term>
181 <listitem><para>
182 Driver supports DMA, the userspace DMA API will be supported.
183 Deprecated.
184 </para></listitem>
185 </varlistentry>
186 <varlistentry>
187 <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
188 <listitem><para>
189 DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler. The
190 DRM core will automatically register an interrupt handler when the
191 flag is set. DRIVER_IRQ_SHARED indicates whether the device &amp;
192 handler support shared IRQs (note that this is required of PCI
193 drivers).
194 </para></listitem>
195 </varlistentry>
196 <varlistentry>
197 <term>DRIVER_IRQ_VBL</term>
198 <listitem><para>Unused. Deprecated.</para></listitem>
199 </varlistentry>
200 <varlistentry>
201 <term>DRIVER_DMA_QUEUE</term>
202 <listitem><para>
203 Should be set if the driver queues DMA requests and completes them
204 asynchronously. Deprecated.
205 </para></listitem>
206 </varlistentry>
207 <varlistentry>
208 <term>DRIVER_FB_DMA</term>
209 <listitem><para>
210 Driver supports DMA to/from the framebuffer, mapping of frambuffer
211 DMA buffers to userspace will be supported. Deprecated.
212 </para></listitem>
213 </varlistentry>
214 <varlistentry>
215 <term>DRIVER_IRQ_VBL2</term>
216 <listitem><para>Unused. Deprecated.</para></listitem>
217 </varlistentry>
218 <varlistentry>
219 <term>DRIVER_GEM</term>
220 <listitem><para>
221 Driver use the GEM memory manager.
222 </para></listitem>
223 </varlistentry>
224 <varlistentry>
225 <term>DRIVER_MODESET</term>
226 <listitem><para>
227 Driver supports mode setting interfaces (KMS).
228 </para></listitem>
229 </varlistentry>
230 <varlistentry>
231 <term>DRIVER_PRIME</term>
232 <listitem><para>
233 Driver implements DRM PRIME buffer sharing.
234 </para></listitem>
235 </varlistentry>
236 </variablelist>
237 </sect3>
238 <sect3>
239 <title>Major, Minor and Patchlevel</title>
240 <synopsis>int major;
241int minor;
242int patchlevel;</synopsis>
243 <para>
244 The DRM core identifies driver versions by a major, minor and patch
245 level triplet. The information is printed to the kernel log at
246 initialization time and passed to userspace through the
247 DRM_IOCTL_VERSION ioctl.
248 </para>
249 <para>
250 The major and minor numbers are also used to verify the requested driver
251 API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes
252 between minor versions, applications can call DRM_IOCTL_SET_VERSION to
253 select a specific version of the API. If the requested major isn't equal
254 to the driver major, or the requested minor is larger than the driver
255 minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise
256 the driver's set_version() method will be called with the requested
257 version.
258 </para>
259 </sect3>
260 <sect3>
261 <title>Name, Description and Date</title>
262 <synopsis>char *name;
263char *desc;
264char *date;</synopsis>
265 <para>
266 The driver name is printed to the kernel log at initialization time,
267 used for IRQ registration and passed to userspace through
268 DRM_IOCTL_VERSION.
269 </para>
270 <para>
271 The driver description is a purely informative string passed to
272 userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
273 the kernel.
274 </para>
275 <para>
276 The driver date, formatted as YYYYMMDD, is meant to identify the date of
277 the latest modification to the driver. However, as most drivers fail to
278 update it, its value is mostly useless. The DRM core prints it to the
279 kernel log at initialization time and passes it to userspace through the
280 DRM_IOCTL_VERSION ioctl.
281 </para>
282 </sect3>
283 </sect2>
284 <sect2>
285 <title>Driver Load</title>
298 <para> 286 <para>
299 The DRM supports several counters which may be used for rough 287 The <methodname>load</methodname> method is the driver and device
300 performance characterization. Note that the DRM stat counter 288 initialization entry point. The method is responsible for allocating and
301 system is not often used by applications, and supporting 289 initializing driver private data, specifying supported performance
302 additional counters is completely optional. 290 counters, performing resource allocation and mapping (e.g. acquiring
291 clocks, mapping registers or allocating command buffers), initializing
292 the memory manager (<xref linkend="drm-memory-management"/>), installing
293 the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up
294 vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode
295 setting (<xref linkend="drm-mode-setting"/>) and initial output
296 configuration (<xref linkend="drm-kms-init"/>).
303 </para> 297 </para>
298 <note><para>
299 If compatibility is a concern (e.g. with drivers converted over from
300 User Mode Setting to Kernel Mode Setting), care must be taken to prevent
301 device initialization and control that is incompatible with currently
302 active userspace drivers. For instance, if user level mode setting
303 drivers are in use, it would be problematic to perform output discovery
304 &amp; configuration at load time. Likewise, if user-level drivers
305 unaware of memory management are in use, memory management and command
306 buffer setup may need to be omitted. These requirements are
307 driver-specific, and care needs to be taken to keep both old and new
308 applications and libraries working.
309 </para></note>
310 <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis>
304 <para> 311 <para>
305 These interfaces are deprecated and should not be used. If performance 312 The method takes two arguments, a pointer to the newly created
306 monitoring is desired, the developer should investigate and 313 <structname>drm_device</structname> and flags. The flags are used to
307 potentially enhance the kernel perf and tracing infrastructure to export 314 pass the <structfield>driver_data</structfield> field of the device id
308 GPU related performance information for consumption by performance 315 corresponding to the device passed to <function>drm_*_init()</function>.
309 monitoring tools and applications. 316 Only PCI devices currently use this, USB and platform DRM drivers have
317 their <methodname>load</methodname> method called with flags to 0.
310 </para> 318 </para>
319 <sect3>
320 <title>Driver Private &amp; Performance Counters</title>
321 <para>
322 The driver private hangs off the main
323 <structname>drm_device</structname> structure and can be used for
324 tracking various device-specific bits of information, like register
325 offsets, command buffer status, register state for suspend/resume, etc.
326 At load time, a driver may simply allocate one and set
327 <structname>drm_device</structname>.<structfield>dev_priv</structfield>
328 appropriately; it should be freed and
329 <structname>drm_device</structname>.<structfield>dev_priv</structfield>
330 set to NULL when the driver is unloaded.
331 </para>
332 <para>
333 DRM supports several counters which were used for rough performance
334 characterization. This stat counter system is deprecated and should not
335 be used. If performance monitoring is desired, the developer should
336 investigate and potentially enhance the kernel perf and tracing
337 infrastructure to export GPU related performance information for
338 consumption by performance monitoring tools and applications.
339 </para>
340 </sect3>
341 <sect3 id="drm-irq-registration">
342 <title>IRQ Registration</title>
343 <para>
344 The DRM core tries to facilitate IRQ handler registration and
345 unregistration by providing <function>drm_irq_install</function> and
346 <function>drm_irq_uninstall</function> functions. Those functions only
347 support a single interrupt per device.
348 </para>
349 <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install-->
350 <para>
351 Both functions get the device IRQ by calling
352 <function>drm_dev_to_irq</function>. This inline function will call a
353 bus-specific operation to retrieve the IRQ number. For platform devices,
354 <function>platform_get_irq</function>(..., 0) is used to retrieve the
355 IRQ number.
356 </para>
357 <para>
358 <function>drm_irq_install</function> starts by calling the
359 <methodname>irq_preinstall</methodname> driver operation. The operation
360 is optional and must make sure that the interrupt will not get fired by
361 clearing all pending interrupt flags or disabling the interrupt.
362 </para>
363 <para>
364 The IRQ will then be requested by a call to
365 <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
366 feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
367 requested.
368 </para>
369 <para>
370 The IRQ handler function must be provided as the mandatory irq_handler
371 driver operation. It will get passed directly to
372 <function>request_irq</function> and thus has the same prototype as all
373 IRQ handlers. It will get called with a pointer to the DRM device as the
374 second argument.
375 </para>
376 <para>
377 Finally the function calls the optional
378 <methodname>irq_postinstall</methodname> driver operation. The operation
379 usually enables interrupts (excluding the vblank interrupt, which is
380 enabled separately), but drivers may choose to enable/disable interrupts
381 at a different time.
382 </para>
383 <para>
384 <function>drm_irq_uninstall</function> is similarly used to uninstall an
385 IRQ handler. It starts by waking up all processes waiting on a vblank
386 interrupt to make sure they don't hang, and then calls the optional
387 <methodname>irq_uninstall</methodname> driver operation. The operation
388 must disable all hardware interrupts. Finally the function frees the IRQ
389 by calling <function>free_irq</function>.
390 </para>
391 </sect3>
392 <sect3>
393 <title>Memory Manager Initialization</title>
394 <para>
395 Every DRM driver requires a memory manager which must be initialized at
396 load time. DRM currently contains two memory managers, the Translation
397 Table Manager (TTM) and the Graphics Execution Manager (GEM).
398 This document describes the use of the GEM memory manager only. See
399 <xref linkend="drm-memory-management"/> for details.
400 </para>
401 </sect3>
402 <sect3>
403 <title>Miscellaneous Device Configuration</title>
404 <para>
405 Another task that may be necessary for PCI devices during configuration
406 is mapping the video BIOS. On many devices, the VBIOS describes device
407 configuration, LCD panel timings (if any), and contains flags indicating
408 device state. Mapping the BIOS can be done using the pci_map_rom() call,
409 a convenience function that takes care of mapping the actual ROM,
410 whether it has been shadowed into memory (typically at address 0xc0000)
411 or exists on the PCI device in the ROM BAR. Note that after the ROM has
412 been mapped and any necessary information has been extracted, it should
413 be unmapped; on many devices, the ROM address decoder is shared with
414 other BARs, so leaving it mapped could cause undesired behaviour like
415 hangs or memory corruption.
416 <!--!Fdrivers/pci/rom.c pci_map_rom-->
417 </para>
418 </sect3>
311 </sect2> 419 </sect2>
420 </sect1>
312 421
313 <sect2> 422 <!-- Internals: memory management -->
314 <title>Configuring the device</title>
315 <para>
316 Obviously, device configuration is device-specific.
317 However, there are several common operations: finding a
318 device's PCI resources, mapping them, and potentially setting
319 up an IRQ handler.
320 </para>
321 <para>
322 Finding &amp; mapping resources is fairly straightforward. The
323 DRM wrapper functions, drm_get_resource_start() and
324 drm_get_resource_len(), may be used to find BARs on the given
325 drm_device struct. Once those values have been retrieved, the
326 driver load function can call drm_addmap() to create a new
327 mapping for the BAR in question. Note that you probably want a
328 drm_local_map_t in your driver private structure to track any
329 mappings you create.
330<!-- !Fdrivers/gpu/drm/drm_bufs.c drm_get_resource_* -->
331<!-- !Finclude/drm/drmP.h drm_local_map_t -->
332 </para>
333 <para>
334 if compatibility with other operating systems isn't a concern
335 (DRM drivers can run under various BSD variants and OpenSolaris),
336 native Linux calls may be used for the above, e.g. pci_resource_*
337 and iomap*/iounmap. See the Linux device driver book for more
338 info.
339 </para>
340 <para>
341 Once you have a register map, you may use the DRM_READn() and
342 DRM_WRITEn() macros to access the registers on your device, or
343 use driver-specific versions to offset into your MMIO space
344 relative to a driver-specific base pointer (see I915_READ for
345 an example).
346 </para>
347 <para>
348 If your device supports interrupt generation, you may want to
349 set up an interrupt handler when the driver is loaded. This
350 is done using the drm_irq_install() function. If your device
351 supports vertical blank interrupts, it should call
352 drm_vblank_init() to initialize the core vblank handling code before
353 enabling interrupts on your device. This ensures the vblank related
354 structures are allocated and allows the core to handle vblank events.
355 </para>
356<!--!Fdrivers/char/drm/drm_irq.c drm_irq_install-->
357 <para>
358 Once your interrupt handler is registered (it uses your
359 drm_driver.irq_handler as the actual interrupt handling
360 function), you can safely enable interrupts on your device,
361 assuming any other state your interrupt handler uses is also
362 initialized.
363 </para>
364 <para>
365 Another task that may be necessary during configuration is
366 mapping the video BIOS. On many devices, the VBIOS describes
367 device configuration, LCD panel timings (if any), and contains
368 flags indicating device state. Mapping the BIOS can be done
369 using the pci_map_rom() call, a convenience function that
370 takes care of mapping the actual ROM, whether it has been
371 shadowed into memory (typically at address 0xc0000) or exists
372 on the PCI device in the ROM BAR. Note that after the ROM
373 has been mapped and any necessary information has been extracted,
374 it should be unmapped; on many devices, the ROM address decoder is
375 shared with other BARs, so leaving it mapped could cause
376 undesired behavior like hangs or memory corruption.
377<!--!Fdrivers/pci/rom.c pci_map_rom-->
378 </para>
379 </sect2>
380 423
424 <sect1 id="drm-memory-management">
425 <title>Memory management</title>
426 <para>
427 Modern Linux systems require large amount of graphics memory to store
428 frame buffers, textures, vertices and other graphics-related data. Given
429 the very dynamic nature of many of that data, managing graphics memory
430 efficiently is thus crucial for the graphics stack and plays a central
431 role in the DRM infrastructure.
432 </para>
433 <para>
434 The DRM core includes two memory managers, namely Translation Table Maps
435 (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory
436 manager to be developed and tried to be a one-size-fits-them all
437 solution. It provides a single userspace API to accomodate the need of
438 all hardware, supporting both Unified Memory Architecture (UMA) devices
439 and devices with dedicated video RAM (i.e. most discrete video cards).
440 This resulted in a large, complex piece of code that turned out to be
441 hard to use for driver development.
442 </para>
443 <para>
444 GEM started as an Intel-sponsored project in reaction to TTM's
445 complexity. Its design philosophy is completely different: instead of
446 providing a solution to every graphics memory-related problems, GEM
447 identified common code between drivers and created a support library to
448 share it. GEM has simpler initialization and execution requirements than
449 TTM, but has no video RAM management capabitilies and is thus limited to
450 UMA devices.
451 </para>
381 <sect2> 452 <sect2>
382 <title>Memory manager initialization</title> 453 <title>The Translation Table Manager (TTM)</title>
383 <para>
384 In order to allocate command buffers, cursor memory, scanout
385 buffers, etc., as well as support the latest features provided
386 by packages like Mesa and the X.Org X server, your driver
387 should support a memory manager.
388 </para>
389 <para> 454 <para>
390 If your driver supports memory management (it should!), you 455 TTM design background and information belongs here.
391 need to set that up at load time as well. How you initialize
392 it depends on which memory manager you're using: TTM or GEM.
393 </para> 456 </para>
394 <sect3> 457 <sect3>
395 <title>TTM initialization</title> 458 <title>TTM initialization</title>
396 <para> 459 <warning><para>This section is outdated.</para></warning>
397 TTM (for Translation Table Manager) manages video memory and 460 <para>
398 aperture space for graphics devices. TTM supports both UMA devices 461 Drivers wishing to support TTM must fill out a drm_bo_driver
399 and devices with dedicated video RAM (VRAM), i.e. most discrete 462 structure. The structure contains several fields with function
400 graphics devices. If your device has dedicated RAM, supporting 463 pointers for initializing the TTM, allocating and freeing memory,
401 TTM is desirable. TTM also integrates tightly with your 464 waiting for command completion and fence synchronization, and memory
402 driver-specific buffer execution function. See the radeon 465 migration. See the radeon_ttm.c file for an example of usage.
403 driver for examples.
404 </para>
405 <para>
406 The core TTM structure is the ttm_bo_driver struct. It contains
407 several fields with function pointers for initializing the TTM,
408 allocating and freeing memory, waiting for command completion
409 and fence synchronization, and memory migration. See the
410 radeon_ttm.c file for an example of usage.
411 </para> 466 </para>
412 <para> 467 <para>
413 The ttm_global_reference structure is made up of several fields: 468 The ttm_global_reference structure is made up of several fields:
@@ -445,82 +500,1081 @@
445 count for the TTM, which will call your initialization function. 500 count for the TTM, which will call your initialization function.
446 </para> 501 </para>
447 </sect3> 502 </sect3>
503 </sect2>
504 <sect2 id="drm-gem">
505 <title>The Graphics Execution Manager (GEM)</title>
506 <para>
507 The GEM design approach has resulted in a memory manager that doesn't
508 provide full coverage of all (or even all common) use cases in its
509 userspace or kernel API. GEM exposes a set of standard memory-related
510 operations to userspace and a set of helper functions to drivers, and let
511 drivers implement hardware-specific operations with their own private API.
512 </para>
513 <para>
514 The GEM userspace API is described in the
515 <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics
516 Execution Manager</citetitle></ulink> article on LWN. While slightly
517 outdated, the document provides a good overview of the GEM API principles.
518 Buffer allocation and read and write operations, described as part of the
519 common GEM API, are currently implemented using driver-specific ioctls.
520 </para>
521 <para>
522 GEM is data-agnostic. It manages abstract buffer objects without knowing
523 what individual buffers contain. APIs that require knowledge of buffer
524 contents or purpose, such as buffer allocation or synchronization
525 primitives, are thus outside of the scope of GEM and must be implemented
526 using driver-specific ioctls.
527 </para>
528 <para>
529 On a fundamental level, GEM involves several operations:
530 <itemizedlist>
531 <listitem>Memory allocation and freeing</listitem>
532 <listitem>Command execution</listitem>
533 <listitem>Aperture management at command execution time</listitem>
534 </itemizedlist>
535 Buffer object allocation is relatively straightforward and largely
536 provided by Linux's shmem layer, which provides memory to back each
537 object.
538 </para>
539 <para>
540 Device-specific operations, such as command execution, pinning, buffer
541 read &amp; write, mapping, and domain ownership transfers are left to
542 driver-specific ioctls.
543 </para>
544 <sect3>
545 <title>GEM Initialization</title>
546 <para>
547 Drivers that use GEM must set the DRIVER_GEM bit in the struct
548 <structname>drm_driver</structname>
549 <structfield>driver_features</structfield> field. The DRM core will
550 then automatically initialize the GEM core before calling the
551 <methodname>load</methodname> operation. Behind the scene, this will
552 create a DRM Memory Manager object which provides an address space
553 pool for object allocation.
554 </para>
555 <para>
556 In a KMS configuration, drivers need to allocate and initialize a
557 command ring buffer following core GEM initialization if required by
558 the hardware. UMA devices usually have what is called a "stolen"
559 memory region, which provides space for the initial framebuffer and
560 large, contiguous memory regions required by the device. This space is
561 typically not managed by GEM, and must be initialized separately into
562 its own DRM MM object.
563 </para>
564 </sect3>
448 <sect3> 565 <sect3>
449 <title>GEM initialization</title> 566 <title>GEM Objects Creation</title>
450 <para> 567 <para>
451 GEM is an alternative to TTM, designed specifically for UMA 568 GEM splits creation of GEM objects and allocation of the memory that
452 devices. It has simpler initialization and execution requirements 569 backs them in two distinct operations.
453 than TTM, but has no VRAM management capability. Core GEM 570 </para>
454 is initialized by calling drm_mm_init() to create 571 <para>
455 a GTT DRM MM object, which provides an address space pool for 572 GEM objects are represented by an instance of struct
456 object allocation. In a KMS configuration, the driver 573 <structname>drm_gem_object</structname>. Drivers usually need to extend
457 needs to allocate and initialize a command ring buffer following 574 GEM objects with private information and thus create a driver-specific
458 core GEM initialization. A UMA device usually has what is called a 575 GEM object structure type that embeds an instance of struct
459 "stolen" memory region, which provides space for the initial 576 <structname>drm_gem_object</structname>.
460 framebuffer and large, contiguous memory regions required by the 577 </para>
461 device. This space is not typically managed by GEM, and it must 578 <para>
462 be initialized separately into its own DRM MM object. 579 To create a GEM object, a driver allocates memory for an instance of its
463 </para> 580 specific GEM object type and initializes the embedded struct
464 <para> 581 <structname>drm_gem_object</structname> with a call to
465 Initialization is driver-specific. In the case of Intel 582 <function>drm_gem_object_init</function>. The function takes a pointer to
466 integrated graphics chips like 965GM, GEM initialization can 583 the DRM device, a pointer to the GEM object and the buffer object size
467 be done by calling the internal GEM init function, 584 in bytes.
468 i915_gem_do_init(). Since the 965GM is a UMA device 585 </para>
469 (i.e. it doesn't have dedicated VRAM), GEM manages 586 <para>
470 making regular RAM available for GPU operations. Memory set 587 GEM uses shmem to allocate anonymous pageable memory.
471 aside by the BIOS (called "stolen" memory by the i915 588 <function>drm_gem_object_init</function> will create an shmfs file of
472 driver) is managed by the DRM memrange allocator; the 589 the requested size and store it into the struct
473 rest of the aperture is managed by GEM. 590 <structname>drm_gem_object</structname> <structfield>filp</structfield>
474 <programlisting> 591 field. The memory is used as either main storage for the object when the
475 /* Basic memrange allocator for stolen space (aka vram) */ 592 graphics hardware uses system memory directly or as a backing store
476 drm_memrange_init(&amp;dev_priv->vram, 0, prealloc_size); 593 otherwise.
477 /* Let GEM Manage from end of prealloc space to end of aperture */ 594 </para>
478 i915_gem_do_init(dev, prealloc_size, agp_size); 595 <para>
479 </programlisting> 596 Drivers are responsible for the actual physical pages allocation by
480<!--!Edrivers/char/drm/drm_memrange.c--> 597 calling <function>shmem_read_mapping_page_gfp</function> for each page.
481 </para> 598 Note that they can decide to allocate pages when initializing the GEM
482 <para> 599 object, or to delay allocation until the memory is needed (for instance
483 Once the memory manager has been set up, we may allocate the 600 when a page fault occurs as a result of a userspace memory access or
484 command buffer. In the i915 case, this is also done with a 601 when the driver needs to start a DMA transfer involving the memory).
485 GEM function, i915_gem_init_ringbuffer(). 602 </para>
486 </para> 603 <para>
604 Anonymous pageable memory allocation is not always desired, for instance
605 when the hardware requires physically contiguous system memory as is
606 often the case in embedded devices. Drivers can create GEM objects with
607 no shmfs backing (called private GEM objects) by initializing them with
608 a call to <function>drm_gem_private_object_init</function> instead of
609 <function>drm_gem_object_init</function>. Storage for private GEM
610 objects must be managed by drivers.
611 </para>
612 <para>
613 Drivers that do not need to extend GEM objects with private information
614 can call the <function>drm_gem_object_alloc</function> function to
615 allocate and initialize a struct <structname>drm_gem_object</structname>
616 instance. The GEM core will call the optional driver
617 <methodname>gem_init_object</methodname> operation after initializing
618 the GEM object with <function>drm_gem_object_init</function>.
619 <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis>
620 </para>
621 <para>
622 No alloc-and-init function exists for private GEM objects.
623 </para>
624 </sect3>
625 <sect3>
626 <title>GEM Objects Lifetime</title>
627 <para>
628 All GEM objects are reference-counted by the GEM core. References can be
629 acquired and release by <function>calling drm_gem_object_reference</function>
630 and <function>drm_gem_object_unreference</function> respectively. The
631 caller must hold the <structname>drm_device</structname>
632 <structfield>struct_mutex</structfield> lock. As a convenience, GEM
633 provides the <function>drm_gem_object_reference_unlocked</function> and
634 <function>drm_gem_object_unreference_unlocked</function> functions that
635 can be called without holding the lock.
636 </para>
637 <para>
638 When the last reference to a GEM object is released the GEM core calls
639 the <structname>drm_driver</structname>
640 <methodname>gem_free_object</methodname> operation. That operation is
641 mandatory for GEM-enabled drivers and must free the GEM object and all
642 associated resources.
643 </para>
644 <para>
645 <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis>
646 Drivers are responsible for freeing all GEM object resources, including
647 the resources created by the GEM core. If an mmap offset has been
648 created for the object (in which case
649 <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield>
650 is not NULL) it must be freed by a call to
651 <function>drm_gem_free_mmap_offset</function>. The shmfs backing store
652 must be released by calling <function>drm_gem_object_release</function>
653 (that function can safely be called if no shmfs backing store has been
654 created).
655 </para>
656 </sect3>
657 <sect3>
658 <title>GEM Objects Naming</title>
659 <para>
660 Communication between userspace and the kernel refers to GEM objects
661 using local handles, global names or, more recently, file descriptors.
662 All of those are 32-bit integer values; the usual Linux kernel limits
663 apply to the file descriptors.
664 </para>
665 <para>
666 GEM handles are local to a DRM file. Applications get a handle to a GEM
667 object through a driver-specific ioctl, and can use that handle to refer
668 to the GEM object in other standard or driver-specific ioctls. Closing a
669 DRM file handle frees all its GEM handles and dereferences the
670 associated GEM objects.
671 </para>
672 <para>
673 To create a handle for a GEM object drivers call
674 <function>drm_gem_handle_create</function>. The function takes a pointer
675 to the DRM file and the GEM object and returns a locally unique handle.
676 When the handle is no longer needed drivers delete it with a call to
677 <function>drm_gem_handle_delete</function>. Finally the GEM object
678 associated with a handle can be retrieved by a call to
679 <function>drm_gem_object_lookup</function>.
680 </para>
681 <para>
682 Handles don't take ownership of GEM objects, they only take a reference
683 to the object that will be dropped when the handle is destroyed. To
684 avoid leaking GEM objects, drivers must make sure they drop the
685 reference(s) they own (such as the initial reference taken at object
686 creation time) as appropriate, without any special consideration for the
687 handle. For example, in the particular case of combined GEM object and
688 handle creation in the implementation of the
689 <methodname>dumb_create</methodname> operation, drivers must drop the
690 initial reference to the GEM object before returning the handle.
691 </para>
692 <para>
693 GEM names are similar in purpose to handles but are not local to DRM
694 files. They can be passed between processes to reference a GEM object
695 globally. Names can't be used directly to refer to objects in the DRM
696 API, applications must convert handles to names and names to handles
697 using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls
698 respectively. The conversion is handled by the DRM core without any
699 driver-specific support.
700 </para>
701 <para>
702 Similar to global names, GEM file descriptors are also used to share GEM
703 objects across processes. They offer additional security: as file
704 descriptors must be explictly sent over UNIX domain sockets to be shared
705 between applications, they can't be guessed like the globally unique GEM
706 names.
707 </para>
708 <para>
709 Drivers that support GEM file descriptors, also known as the DRM PRIME
710 API, must set the DRIVER_PRIME bit in the struct
711 <structname>drm_driver</structname>
712 <structfield>driver_features</structfield> field, and implement the
713 <methodname>prime_handle_to_fd</methodname> and
714 <methodname>prime_fd_to_handle</methodname> operations.
715 </para>
716 <para>
717 <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,
718 struct drm_file *file_priv, uint32_t handle,
719 uint32_t flags, int *prime_fd);
720 int (*prime_fd_to_handle)(struct drm_device *dev,
721 struct drm_file *file_priv, int prime_fd,
722 uint32_t *handle);</synopsis>
723 Those two operations convert a handle to a PRIME file descriptor and
724 vice versa. Drivers must use the kernel dma-buf buffer sharing framework
725 to manage the PRIME file descriptors.
726 </para>
727 <para>
728 While non-GEM drivers must implement the operations themselves, GEM
729 drivers must use the <function>drm_gem_prime_handle_to_fd</function>
730 and <function>drm_gem_prime_fd_to_handle</function> helper functions.
731 Those helpers rely on the driver
732 <methodname>gem_prime_export</methodname> and
733 <methodname>gem_prime_import</methodname> operations to create a dma-buf
734 instance from a GEM object (dma-buf exporter role) and to create a GEM
735 object from a dma-buf instance (dma-buf importer role).
736 </para>
737 <para>
738 <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
739 struct drm_gem_object *obj,
740 int flags);
741 struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
742 struct dma_buf *dma_buf);</synopsis>
743 These two operations are mandatory for GEM drivers that support DRM
744 PRIME.
745 </para>
746 </sect3>
747 <sect3 id="drm-gem-objects-mapping">
748 <title>GEM Objects Mapping</title>
749 <para>
750 Because mapping operations are fairly heavyweight GEM favours
751 read/write-like access to buffers, implemented through driver-specific
752 ioctls, over mapping buffers to userspace. However, when random access
753 to the buffer is needed (to perform software rendering for instance),
754 direct access to the object can be more efficient.
755 </para>
756 <para>
757 The mmap system call can't be used directly to map GEM objects, as they
758 don't have their own file handle. Two alternative methods currently
759 co-exist to map GEM objects to userspace. The first method uses a
760 driver-specific ioctl to perform the mapping operation, calling
761 <function>do_mmap</function> under the hood. This is often considered
762 dubious, seems to be discouraged for new GEM-enabled drivers, and will
763 thus not be described here.
764 </para>
765 <para>
766 The second method uses the mmap system call on the DRM file handle.
767 <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd,
768 off_t offset);</synopsis>
769 DRM identifies the GEM object to be mapped by a fake offset passed
770 through the mmap offset argument. Prior to being mapped, a GEM object
771 must thus be associated with a fake offset. To do so, drivers must call
772 <function>drm_gem_create_mmap_offset</function> on the object. The
773 function allocates a fake offset range from a pool and stores the
774 offset divided by PAGE_SIZE in
775 <literal>obj-&gt;map_list.hash.key</literal>. Care must be taken not to
776 call <function>drm_gem_create_mmap_offset</function> if a fake offset
777 has already been allocated for the object. This can be tested by
778 <literal>obj-&gt;map_list.map</literal> being non-NULL.
779 </para>
780 <para>
781 Once allocated, the fake offset value
782 (<literal>obj-&gt;map_list.hash.key &lt;&lt; PAGE_SHIFT</literal>)
783 must be passed to the application in a driver-specific way and can then
784 be used as the mmap offset argument.
785 </para>
786 <para>
787 The GEM core provides a helper method <function>drm_gem_mmap</function>
788 to handle object mapping. The method can be set directly as the mmap
789 file operation handler. It will look up the GEM object based on the
790 offset value and set the VMA operations to the
791 <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
792 field. Note that <function>drm_gem_mmap</function> doesn't map memory to
793 userspace, but relies on the driver-provided fault handler to map pages
794 individually.
795 </para>
796 <para>
797 To use <function>drm_gem_mmap</function>, drivers must fill the struct
798 <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
799 field with a pointer to VM operations.
800 </para>
801 <para>
802 <synopsis>struct vm_operations_struct *gem_vm_ops
803
804 struct vm_operations_struct {
805 void (*open)(struct vm_area_struct * area);
806 void (*close)(struct vm_area_struct * area);
807 int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf);
808 };</synopsis>
809 </para>
810 <para>
811 The <methodname>open</methodname> and <methodname>close</methodname>
812 operations must update the GEM object reference count. Drivers can use
813 the <function>drm_gem_vm_open</function> and
814 <function>drm_gem_vm_close</function> helper functions directly as open
815 and close handlers.
816 </para>
817 <para>
818 The fault operation handler is responsible for mapping individual pages
819 to userspace when a page fault occurs. Depending on the memory
820 allocation scheme, drivers can allocate pages at fault time, or can
821 decide to allocate memory for the GEM object at the time the object is
822 created.
823 </para>
824 <para>
825 Drivers that want to map the GEM object upfront instead of handling page
826 faults can implement their own mmap file operation handler.
827 </para>
828 </sect3>
829 <sect3>
830 <title>Dumb GEM Objects</title>
831 <para>
832 The GEM API doesn't standardize GEM objects creation and leaves it to
833 driver-specific ioctls. While not an issue for full-fledged graphics
834 stacks that include device-specific userspace components (in libdrm for
835 instance), this limit makes DRM-based early boot graphics unnecessarily
836 complex.
837 </para>
838 <para>
839 Dumb GEM objects partly alleviate the problem by providing a standard
840 API to create dumb buffers suitable for scanout, which can then be used
841 to create KMS frame buffers.
842 </para>
843 <para>
844 To support dumb GEM objects drivers must implement the
845 <methodname>dumb_create</methodname>,
846 <methodname>dumb_destroy</methodname> and
847 <methodname>dumb_map_offset</methodname> operations.
848 </para>
849 <itemizedlist>
850 <listitem>
851 <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev,
852 struct drm_mode_create_dumb *args);</synopsis>
853 <para>
854 The <methodname>dumb_create</methodname> operation creates a GEM
855 object suitable for scanout based on the width, height and depth
856 from the struct <structname>drm_mode_create_dumb</structname>
857 argument. It fills the argument's <structfield>handle</structfield>,
858 <structfield>pitch</structfield> and <structfield>size</structfield>
859 fields with a handle for the newly created GEM object and its line
860 pitch and size in bytes.
861 </para>
862 </listitem>
863 <listitem>
864 <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev,
865 uint32_t handle);</synopsis>
866 <para>
867 The <methodname>dumb_destroy</methodname> operation destroys a dumb
868 GEM object created by <methodname>dumb_create</methodname>.
869 </para>
870 </listitem>
871 <listitem>
872 <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev,
873 uint32_t handle, uint64_t *offset);</synopsis>
874 <para>
875 The <methodname>dumb_map_offset</methodname> operation associates an
876 mmap fake offset with the GEM object given by the handle and returns
877 it. Drivers must use the
878 <function>drm_gem_create_mmap_offset</function> function to
879 associate the fake offset as described in
880 <xref linkend="drm-gem-objects-mapping"/>.
881 </para>
882 </listitem>
883 </itemizedlist>
884 </sect3>
885 <sect3>
886 <title>Memory Coherency</title>
887 <para>
888 When mapped to the device or used in a command buffer, backing pages
889 for an object are flushed to memory and marked write combined so as to
890 be coherent with the GPU. Likewise, if the CPU accesses an object
891 after the GPU has finished rendering to the object, then the object
892 must be made coherent with the CPU's view of memory, usually involving
893 GPU cache flushing of various kinds. This core CPU&lt;-&gt;GPU
894 coherency management is provided by a device-specific ioctl, which
895 evaluates an object's current domain and performs any necessary
896 flushing or synchronization to put the object into the desired
897 coherency domain (note that the object may be busy, i.e. an active
898 render target; in that case, setting the domain blocks the client and
899 waits for rendering to complete before performing any necessary
900 flushing operations).
901 </para>
902 </sect3>
903 <sect3>
904 <title>Command Execution</title>
905 <para>
906 Perhaps the most important GEM function for GPU devices is providing a
907 command execution interface to clients. Client programs construct
908 command buffers containing references to previously allocated memory
909 objects, and then submit them to GEM. At that point, GEM takes care to
910 bind all the objects into the GTT, execute the buffer, and provide
911 necessary synchronization between clients accessing the same buffers.
912 This often involves evicting some objects from the GTT and re-binding
913 others (a fairly expensive operation), and providing relocation
914 support which hides fixed GTT offsets from clients. Clients must take
915 care not to submit command buffers that reference more objects than
916 can fit in the GTT; otherwise, GEM will reject them and no rendering
917 will occur. Similarly, if several objects in the buffer require fence
918 registers to be allocated for correct rendering (e.g. 2D blits on
919 pre-965 chips), care must be taken not to require more fence registers
920 than are available to the client. Such resource management should be
921 abstracted from the client in libdrm.
922 </para>
487 </sect3> 923 </sect3>
488 </sect2> 924 </sect2>
925 </sect1>
926
927 <!-- Internals: mode setting -->
489 928
929 <sect1 id="drm-mode-setting">
930 <title>Mode Setting</title>
931 <para>
932 Drivers must initialize the mode setting core by calling
933 <function>drm_mode_config_init</function> on the DRM device. The function
934 initializes the <structname>drm_device</structname>
935 <structfield>mode_config</structfield> field and never fails. Once done,
936 mode configuration must be setup by initializing the following fields.
937 </para>
938 <itemizedlist>
939 <listitem>
940 <synopsis>int min_width, min_height;
941int max_width, max_height;</synopsis>
942 <para>
943 Minimum and maximum width and height of the frame buffers in pixel
944 units.
945 </para>
946 </listitem>
947 <listitem>
948 <synopsis>struct drm_mode_config_funcs *funcs;</synopsis>
949 <para>Mode setting functions.</para>
950 </listitem>
951 </itemizedlist>
490 <sect2> 952 <sect2>
491 <title>Output configuration</title> 953 <title>Frame Buffer Creation</title>
954 <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
955 struct drm_file *file_priv,
956 struct drm_mode_fb_cmd2 *mode_cmd);</synopsis>
492 <para> 957 <para>
493 The final initialization task is output configuration. This involves: 958 Frame buffers are abstract memory objects that provide a source of
494 <itemizedlist> 959 pixels to scanout to a CRTC. Applications explicitly request the
495 <listitem> 960 creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and
496 Finding and initializing the CRTCs, encoders, and connectors 961 receive an opaque handle that can be passed to the KMS CRTC control,
497 for the device. 962 plane configuration and page flip functions.
498 </listitem> 963 </para>
499 <listitem> 964 <para>
500 Creating an initial configuration. 965 Frame buffers rely on the underneath memory manager for low-level memory
501 </listitem> 966 operations. When creating a frame buffer applications pass a memory
502 <listitem> 967 handle (or a list of memory handles for multi-planar formats) through
503 Registering a framebuffer console driver. 968 the <parameter>drm_mode_fb_cmd2</parameter> argument. This document
504 </listitem> 969 assumes that the driver uses GEM, those handles thus reference GEM
505 </itemizedlist> 970 objects.
971 </para>
972 <para>
973 Drivers must first validate the requested frame buffer parameters passed
974 through the mode_cmd argument. In particular this is where invalid
975 sizes, pixel formats or pitches can be caught.
976 </para>
977 <para>
978 If the parameters are deemed valid, drivers then create, initialize and
979 return an instance of struct <structname>drm_framebuffer</structname>.
980 If desired the instance can be embedded in a larger driver-specific
981 structure. The new instance is initialized with a call to
982 <function>drm_framebuffer_init</function> which takes a pointer to DRM
983 frame buffer operations (struct
984 <structname>drm_framebuffer_funcs</structname>). Frame buffer operations are
985 <itemizedlist>
986 <listitem>
987 <synopsis>int (*create_handle)(struct drm_framebuffer *fb,
988 struct drm_file *file_priv, unsigned int *handle);</synopsis>
989 <para>
990 Create a handle to the frame buffer underlying memory object. If
991 the frame buffer uses a multi-plane format, the handle will
992 reference the memory object associated with the first plane.
993 </para>
994 <para>
995 Drivers call <function>drm_gem_handle_create</function> to create
996 the handle.
997 </para>
998 </listitem>
999 <listitem>
1000 <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis>
1001 <para>
1002 Destroy the frame buffer object and frees all associated
1003 resources. Drivers must call
1004 <function>drm_framebuffer_cleanup</function> to free resources
1005 allocated by the DRM core for the frame buffer object, and must
1006 make sure to unreference all memory objects associated with the
1007 frame buffer. Handles created by the
1008 <methodname>create_handle</methodname> operation are released by
1009 the DRM core.
1010 </para>
1011 </listitem>
1012 <listitem>
1013 <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer,
1014 struct drm_file *file_priv, unsigned flags, unsigned color,
1015 struct drm_clip_rect *clips, unsigned num_clips);</synopsis>
1016 <para>
1017 This optional operation notifies the driver that a region of the
1018 frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB
1019 ioctl call.
1020 </para>
1021 </listitem>
1022 </itemizedlist>
1023 </para>
1024 <para>
1025 After initializing the <structname>drm_framebuffer</structname>
1026 instance drivers must fill its <structfield>width</structfield>,
1027 <structfield>height</structfield>, <structfield>pitches</structfield>,
1028 <structfield>offsets</structfield>, <structfield>depth</structfield>,
1029 <structfield>bits_per_pixel</structfield> and
1030 <structfield>pixel_format</structfield> fields from the values passed
1031 through the <parameter>drm_mode_fb_cmd2</parameter> argument. They
1032 should call the <function>drm_helper_mode_fill_fb_struct</function>
1033 helper function to do so.
1034 </para>
1035 </sect2>
1036 <sect2>
1037 <title>Output Polling</title>
1038 <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis>
1039 <para>
1040 This operation notifies the driver that the status of one or more
1041 connectors has changed. Drivers that use the fb helper can just call the
1042 <function>drm_fb_helper_hotplug_event</function> function to handle this
1043 operation.
1044 </para>
1045 </sect2>
1046 </sect1>
1047
1048 <!-- Internals: kms initialization and cleanup -->
1049
1050 <sect1 id="drm-kms-init">
1051 <title>KMS Initialization and Cleanup</title>
1052 <para>
1053 A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders
1054 and connectors. KMS drivers must thus create and initialize all those
1055 objects at load time after initializing mode setting.
1056 </para>
1057 <sect2>
1058 <title>CRTCs (struct <structname>drm_crtc</structname>)</title>
1059 <para>
1060 A CRTC is an abstraction representing a part of the chip that contains a
1061 pointer to a scanout buffer. Therefore, the number of CRTCs available
1062 determines how many independent scanout buffers can be active at any
1063 given time. The CRTC structure contains several fields to support this:
1064 a pointer to some video memory (abstracted as a frame buffer object), a
1065 display mode, and an (x, y) offset into the video memory to support
1066 panning or configurations where one piece of video memory spans multiple
1067 CRTCs.
506 </para> 1068 </para>
507 <sect3> 1069 <sect3>
508 <title>Output discovery and initialization</title> 1070 <title>CRTC Initialization</title>
509 <para> 1071 <para>
510 Several core functions exist to create CRTCs, encoders, and 1072 A KMS device must create and register at least one struct
511 connectors, namely: drm_crtc_init(), drm_connector_init(), and 1073 <structname>drm_crtc</structname> instance. The instance is allocated
512 drm_encoder_init(), along with several "helper" functions to 1074 and zeroed by the driver, possibly as part of a larger structure, and
513 perform common tasks. 1075 registered with a call to <function>drm_crtc_init</function> with a
514 </para> 1076 pointer to CRTC functions.
515 <para> 1077 </para>
516 Connectors should be registered with sysfs once they've been 1078 </sect3>
517 detected and initialized, using the 1079 <sect3>
518 drm_sysfs_connector_add() function. Likewise, when they're 1080 <title>CRTC Operations</title>
519 removed from the system, they should be destroyed with 1081 <sect4>
520 drm_sysfs_connector_remove(). 1082 <title>Set Configuration</title>
521 </para> 1083 <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis>
522 <programlisting> 1084 <para>
523<![CDATA[ 1085 Apply a new CRTC configuration to the device. The configuration
1086 specifies a CRTC, a frame buffer to scan out from, a (x,y) position in
1087 the frame buffer, a display mode and an array of connectors to drive
1088 with the CRTC if possible.
1089 </para>
1090 <para>
1091 If the frame buffer specified in the configuration is NULL, the driver
1092 must detach all encoders connected to the CRTC and all connectors
1093 attached to those encoders and disable them.
1094 </para>
1095 <para>
1096 This operation is called with the mode config lock held.
1097 </para>
1098 <note><para>
1099 FIXME: How should set_config interact with DPMS? If the CRTC is
1100 suspended, should it be resumed?
1101 </para></note>
1102 </sect4>
1103 <sect4>
1104 <title>Page Flipping</title>
1105 <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb,
1106 struct drm_pending_vblank_event *event);</synopsis>
1107 <para>
1108 Schedule a page flip to the given frame buffer for the CRTC. This
1109 operation is called with the mode config mutex held.
1110 </para>
1111 <para>
1112 Page flipping is a synchronization mechanism that replaces the frame
1113 buffer being scanned out by the CRTC with a new frame buffer during
1114 vertical blanking, avoiding tearing. When an application requests a page
1115 flip the DRM core verifies that the new frame buffer is large enough to
1116 be scanned out by the CRTC in the currently configured mode and then
1117 calls the CRTC <methodname>page_flip</methodname> operation with a
1118 pointer to the new frame buffer.
1119 </para>
1120 <para>
1121 The <methodname>page_flip</methodname> operation schedules a page flip.
1122 Once any pending rendering targetting the new frame buffer has
1123 completed, the CRTC will be reprogrammed to display that frame buffer
1124 after the next vertical refresh. The operation must return immediately
1125 without waiting for rendering or page flip to complete and must block
1126 any new rendering to the frame buffer until the page flip completes.
1127 </para>
1128 <para>
1129 If a page flip is already pending, the
1130 <methodname>page_flip</methodname> operation must return
1131 -<errorname>EBUSY</errorname>.
1132 </para>
1133 <para>
1134 To synchronize page flip to vertical blanking the driver will likely
1135 need to enable vertical blanking interrupts. It should call
1136 <function>drm_vblank_get</function> for that purpose, and call
1137 <function>drm_vblank_put</function> after the page flip completes.
1138 </para>
1139 <para>
1140 If the application has requested to be notified when page flip completes
1141 the <methodname>page_flip</methodname> operation will be called with a
1142 non-NULL <parameter>event</parameter> argument pointing to a
1143 <structname>drm_pending_vblank_event</structname> instance. Upon page
1144 flip completion the driver must fill the
1145 <parameter>event</parameter>::<structfield>event</structfield>
1146 <structfield>sequence</structfield>, <structfield>tv_sec</structfield>
1147 and <structfield>tv_usec</structfield> fields with the associated
1148 vertical blanking count and timestamp, add the event to the
1149 <parameter>drm_file</parameter> list of events to be signaled, and wake
1150 up any waiting process. This can be performed with
1151 <programlisting><![CDATA[
1152 struct timeval now;
1153
1154 event->event.sequence = drm_vblank_count_and_time(..., &now);
1155 event->event.tv_sec = now.tv_sec;
1156 event->event.tv_usec = now.tv_usec;
1157
1158 spin_lock_irqsave(&dev->event_lock, flags);
1159 list_add_tail(&event->base.link, &event->base.file_priv->event_list);
1160 wake_up_interruptible(&event->base.file_priv->event_wait);
1161 spin_unlock_irqrestore(&dev->event_lock, flags);
1162 ]]></programlisting>
1163 </para>
1164 <note><para>
1165 FIXME: Could drivers that don't need to wait for rendering to complete
1166 just add the event to <literal>dev-&gt;vblank_event_list</literal> and
1167 let the DRM core handle everything, as for "normal" vertical blanking
1168 events?
1169 </para></note>
1170 <para>
1171 While waiting for the page flip to complete, the
1172 <literal>event-&gt;base.link</literal> list head can be used freely by
1173 the driver to store the pending event in a driver-specific list.
1174 </para>
1175 <para>
1176 If the file handle is closed before the event is signaled, drivers must
1177 take care to destroy the event in their
1178 <methodname>preclose</methodname> operation (and, if needed, call
1179 <function>drm_vblank_put</function>).
1180 </para>
1181 </sect4>
1182 <sect4>
1183 <title>Miscellaneous</title>
1184 <itemizedlist>
1185 <listitem>
1186 <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
1187 uint32_t start, uint32_t size);</synopsis>
1188 <para>
1189 Apply a gamma table to the device. The operation is optional.
1190 </para>
1191 </listitem>
1192 <listitem>
1193 <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis>
1194 <para>
1195 Destroy the CRTC when not needed anymore. See
1196 <xref linkend="drm-kms-init"/>.
1197 </para>
1198 </listitem>
1199 </itemizedlist>
1200 </sect4>
1201 </sect3>
1202 </sect2>
1203 <sect2>
1204 <title>Planes (struct <structname>drm_plane</structname>)</title>
1205 <para>
1206 A plane represents an image source that can be blended with or overlayed
1207 on top of a CRTC during the scanout process. Planes are associated with
1208 a frame buffer to crop a portion of the image memory (source) and
1209 optionally scale it to a destination size. The result is then blended
1210 with or overlayed on top of a CRTC.
1211 </para>
1212 <sect3>
1213 <title>Plane Initialization</title>
1214 <para>
1215 Planes are optional. To create a plane, a KMS drivers allocates and
1216 zeroes an instances of struct <structname>drm_plane</structname>
1217 (possibly as part of a larger structure) and registers it with a call
1218 to <function>drm_plane_init</function>. The function takes a bitmask
1219 of the CRTCs that can be associated with the plane, a pointer to the
1220 plane functions and a list of format supported formats.
1221 </para>
1222 </sect3>
1223 <sect3>
1224 <title>Plane Operations</title>
1225 <itemizedlist>
1226 <listitem>
1227 <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc,
1228 struct drm_framebuffer *fb, int crtc_x, int crtc_y,
1229 unsigned int crtc_w, unsigned int crtc_h,
1230 uint32_t src_x, uint32_t src_y,
1231 uint32_t src_w, uint32_t src_h);</synopsis>
1232 <para>
1233 Enable and configure the plane to use the given CRTC and frame buffer.
1234 </para>
1235 <para>
1236 The source rectangle in frame buffer memory coordinates is given by
1237 the <parameter>src_x</parameter>, <parameter>src_y</parameter>,
1238 <parameter>src_w</parameter> and <parameter>src_h</parameter>
1239 parameters (as 16.16 fixed point values). Devices that don't support
1240 subpixel plane coordinates can ignore the fractional part.
1241 </para>
1242 <para>
1243 The destination rectangle in CRTC coordinates is given by the
1244 <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>,
1245 <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter>
1246 parameters (as integer values). Devices scale the source rectangle to
1247 the destination rectangle. If scaling is not supported, and the source
1248 rectangle size doesn't match the destination rectangle size, the
1249 driver must return a -<errorname>EINVAL</errorname> error.
1250 </para>
1251 </listitem>
1252 <listitem>
1253 <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis>
1254 <para>
1255 Disable the plane. The DRM core calls this method in response to a
1256 DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0.
1257 Disabled planes must not be processed by the CRTC.
1258 </para>
1259 </listitem>
1260 <listitem>
1261 <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis>
1262 <para>
1263 Destroy the plane when not needed anymore. See
1264 <xref linkend="drm-kms-init"/>.
1265 </para>
1266 </listitem>
1267 </itemizedlist>
1268 </sect3>
1269 </sect2>
1270 <sect2>
1271 <title>Encoders (struct <structname>drm_encoder</structname>)</title>
1272 <para>
1273 An encoder takes pixel data from a CRTC and converts it to a format
1274 suitable for any attached connectors. On some devices, it may be
1275 possible to have a CRTC send data to more than one encoder. In that
1276 case, both encoders would receive data from the same scanout buffer,
1277 resulting in a "cloned" display configuration across the connectors
1278 attached to each encoder.
1279 </para>
1280 <sect3>
1281 <title>Encoder Initialization</title>
1282 <para>
1283 As for CRTCs, a KMS driver must create, initialize and register at
1284 least one struct <structname>drm_encoder</structname> instance. The
1285 instance is allocated and zeroed by the driver, possibly as part of a
1286 larger structure.
1287 </para>
1288 <para>
1289 Drivers must initialize the struct <structname>drm_encoder</structname>
1290 <structfield>possible_crtcs</structfield> and
1291 <structfield>possible_clones</structfield> fields before registering the
1292 encoder. Both fields are bitmasks of respectively the CRTCs that the
1293 encoder can be connected to, and sibling encoders candidate for cloning.
1294 </para>
1295 <para>
1296 After being initialized, the encoder must be registered with a call to
1297 <function>drm_encoder_init</function>. The function takes a pointer to
1298 the encoder functions and an encoder type. Supported types are
1299 <itemizedlist>
1300 <listitem>
1301 DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A
1302 </listitem>
1303 <listitem>
1304 DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort
1305 </listitem>
1306 <listitem>
1307 DRM_MODE_ENCODER_LVDS for display panels
1308 </listitem>
1309 <listitem>
1310 DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component,
1311 SCART)
1312 </listitem>
1313 <listitem>
1314 DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
1315 </listitem>
1316 </itemizedlist>
1317 </para>
1318 <para>
1319 Encoders must be attached to a CRTC to be used. DRM drivers leave
1320 encoders unattached at initialization time. Applications (or the fbdev
1321 compatibility layer when implemented) are responsible for attaching the
1322 encoders they want to use to a CRTC.
1323 </para>
1324 </sect3>
1325 <sect3>
1326 <title>Encoder Operations</title>
1327 <itemizedlist>
1328 <listitem>
1329 <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis>
1330 <para>
1331 Called to destroy the encoder when not needed anymore. See
1332 <xref linkend="drm-kms-init"/>.
1333 </para>
1334 </listitem>
1335 </itemizedlist>
1336 </sect3>
1337 </sect2>
1338 <sect2>
1339 <title>Connectors (struct <structname>drm_connector</structname>)</title>
1340 <para>
1341 A connector is the final destination for pixel data on a device, and
1342 usually connects directly to an external display device like a monitor
1343 or laptop panel. A connector can only be attached to one encoder at a
1344 time. The connector is also the structure where information about the
1345 attached display is kept, so it contains fields for display data, EDID
1346 data, DPMS &amp; connection status, and information about modes
1347 supported on the attached displays.
1348 </para>
1349 <sect3>
1350 <title>Connector Initialization</title>
1351 <para>
1352 Finally a KMS driver must create, initialize, register and attach at
1353 least one struct <structname>drm_connector</structname> instance. The
1354 instance is created as other KMS objects and initialized by setting the
1355 following fields.
1356 </para>
1357 <variablelist>
1358 <varlistentry>
1359 <term><structfield>interlace_allowed</structfield></term>
1360 <listitem><para>
1361 Whether the connector can handle interlaced modes.
1362 </para></listitem>
1363 </varlistentry>
1364 <varlistentry>
1365 <term><structfield>doublescan_allowed</structfield></term>
1366 <listitem><para>
1367 Whether the connector can handle doublescan.
1368 </para></listitem>
1369 </varlistentry>
1370 <varlistentry>
1371 <term><structfield>display_info
1372 </structfield></term>
1373 <listitem><para>
1374 Display information is filled from EDID information when a display
1375 is detected. For non hot-pluggable displays such as flat panels in
1376 embedded systems, the driver should initialize the
1377 <structfield>display_info</structfield>.<structfield>width_mm</structfield>
1378 and
1379 <structfield>display_info</structfield>.<structfield>height_mm</structfield>
1380 fields with the physical size of the display.
1381 </para></listitem>
1382 </varlistentry>
1383 <varlistentry>
1384 <term id="drm-kms-connector-polled"><structfield>polled</structfield></term>
1385 <listitem><para>
1386 Connector polling mode, a combination of
1387 <variablelist>
1388 <varlistentry>
1389 <term>DRM_CONNECTOR_POLL_HPD</term>
1390 <listitem><para>
1391 The connector generates hotplug events and doesn't need to be
1392 periodically polled. The CONNECT and DISCONNECT flags must not
1393 be set together with the HPD flag.
1394 </para></listitem>
1395 </varlistentry>
1396 <varlistentry>
1397 <term>DRM_CONNECTOR_POLL_CONNECT</term>
1398 <listitem><para>
1399 Periodically poll the connector for connection.
1400 </para></listitem>
1401 </varlistentry>
1402 <varlistentry>
1403 <term>DRM_CONNECTOR_POLL_DISCONNECT</term>
1404 <listitem><para>
1405 Periodically poll the connector for disconnection.
1406 </para></listitem>
1407 </varlistentry>
1408 </variablelist>
1409 Set to 0 for connectors that don't support connection status
1410 discovery.
1411 </para></listitem>
1412 </varlistentry>
1413 </variablelist>
1414 <para>
1415 The connector is then registered with a call to
1416 <function>drm_connector_init</function> with a pointer to the connector
1417 functions and a connector type, and exposed through sysfs with a call to
1418 <function>drm_sysfs_connector_add</function>.
1419 </para>
1420 <para>
1421 Supported connector types are
1422 <itemizedlist>
1423 <listitem>DRM_MODE_CONNECTOR_VGA</listitem>
1424 <listitem>DRM_MODE_CONNECTOR_DVII</listitem>
1425 <listitem>DRM_MODE_CONNECTOR_DVID</listitem>
1426 <listitem>DRM_MODE_CONNECTOR_DVIA</listitem>
1427 <listitem>DRM_MODE_CONNECTOR_Composite</listitem>
1428 <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem>
1429 <listitem>DRM_MODE_CONNECTOR_LVDS</listitem>
1430 <listitem>DRM_MODE_CONNECTOR_Component</listitem>
1431 <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem>
1432 <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem>
1433 <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem>
1434 <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem>
1435 <listitem>DRM_MODE_CONNECTOR_TV</listitem>
1436 <listitem>DRM_MODE_CONNECTOR_eDP</listitem>
1437 <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem>
1438 </itemizedlist>
1439 </para>
1440 <para>
1441 Connectors must be attached to an encoder to be used. For devices that
1442 map connectors to encoders 1:1, the connector should be attached at
1443 initialization time with a call to
1444 <function>drm_mode_connector_attach_encoder</function>. The driver must
1445 also set the <structname>drm_connector</structname>
1446 <structfield>encoder</structfield> field to point to the attached
1447 encoder.
1448 </para>
1449 <para>
1450 Finally, drivers must initialize the connectors state change detection
1451 with a call to <function>drm_kms_helper_poll_init</function>. If at
1452 least one connector is pollable but can't generate hotplug interrupts
1453 (indicated by the DRM_CONNECTOR_POLL_CONNECT and
1454 DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
1455 automatically be queued to periodically poll for changes. Connectors
1456 that can generate hotplug interrupts must be marked with the
1457 DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must
1458 call <function>drm_helper_hpd_irq_event</function>. The function will
1459 queue a delayed work to check the state of all connectors, but no
1460 periodic polling will be done.
1461 </para>
1462 </sect3>
1463 <sect3>
1464 <title>Connector Operations</title>
1465 <note><para>
1466 Unless otherwise state, all operations are mandatory.
1467 </para></note>
1468 <sect4>
1469 <title>DPMS</title>
1470 <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis>
1471 <para>
1472 The DPMS operation sets the power state of a connector. The mode
1473 argument is one of
1474 <itemizedlist>
1475 <listitem><para>DRM_MODE_DPMS_ON</para></listitem>
1476 <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem>
1477 <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem>
1478 <listitem><para>DRM_MODE_DPMS_OFF</para></listitem>
1479 </itemizedlist>
1480 </para>
1481 <para>
1482 In all but DPMS_ON mode the encoder to which the connector is attached
1483 should put the display in low-power mode by driving its signals
1484 appropriately. If more than one connector is attached to the encoder
1485 care should be taken not to change the power state of other displays as
1486 a side effect. Low-power mode should be propagated to the encoders and
1487 CRTCs when all related connectors are put in low-power mode.
1488 </para>
1489 </sect4>
1490 <sect4>
1491 <title>Modes</title>
1492 <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width,
1493 uint32_t max_height);</synopsis>
1494 <para>
1495 Fill the mode list with all supported modes for the connector. If the
1496 <parameter>max_width</parameter> and <parameter>max_height</parameter>
1497 arguments are non-zero, the implementation must ignore all modes wider
1498 than <parameter>max_width</parameter> or higher than
1499 <parameter>max_height</parameter>.
1500 </para>
1501 <para>
1502 The connector must also fill in this operation its
1503 <structfield>display_info</structfield>
1504 <structfield>width_mm</structfield> and
1505 <structfield>height_mm</structfield> fields with the connected display
1506 physical size in millimeters. The fields should be set to 0 if the value
1507 isn't known or is not applicable (for instance for projector devices).
1508 </para>
1509 </sect4>
1510 <sect4>
1511 <title>Connection Status</title>
1512 <para>
1513 The connection status is updated through polling or hotplug events when
1514 supported (see <xref linkend="drm-kms-connector-polled"/>). The status
1515 value is reported to userspace through ioctls and must not be used
1516 inside the driver, as it only gets initialized by a call to
1517 <function>drm_mode_getconnector</function> from userspace.
1518 </para>
1519 <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector,
1520 bool force);</synopsis>
1521 <para>
1522 Check to see if anything is attached to the connector. The
1523 <parameter>force</parameter> parameter is set to false whilst polling or
1524 to true when checking the connector due to user request.
1525 <parameter>force</parameter> can be used by the driver to avoid
1526 expensive, destructive operations during automated probing.
1527 </para>
1528 <para>
1529 Return connector_status_connected if something is connected to the
1530 connector, connector_status_disconnected if nothing is connected and
1531 connector_status_unknown if the connection state isn't known.
1532 </para>
1533 <para>
1534 Drivers should only return connector_status_connected if the connection
1535 status has really been probed as connected. Connectors that can't detect
1536 the connection status, or failed connection status probes, should return
1537 connector_status_unknown.
1538 </para>
1539 </sect4>
1540 <sect4>
1541 <title>Miscellaneous</title>
1542 <itemizedlist>
1543 <listitem>
1544 <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
1545 <para>
1546 Destroy the connector when not needed anymore. See
1547 <xref linkend="drm-kms-init"/>.
1548 </para>
1549 </listitem>
1550 </itemizedlist>
1551 </sect4>
1552 </sect3>
1553 </sect2>
1554 <sect2>
1555 <title>Cleanup</title>
1556 <para>
1557 The DRM core manages its objects' lifetime. When an object is not needed
1558 anymore the core calls its destroy function, which must clean up and
1559 free every resource allocated for the object. Every
1560 <function>drm_*_init</function> call must be matched with a
1561 corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs
1562 (<function>drm_crtc_cleanup</function>), planes
1563 (<function>drm_plane_cleanup</function>), encoders
1564 (<function>drm_encoder_cleanup</function>) and connectors
1565 (<function>drm_connector_cleanup</function>). Furthermore, connectors
1566 that have been added to sysfs must be removed by a call to
1567 <function>drm_sysfs_connector_remove</function> before calling
1568 <function>drm_connector_cleanup</function>.
1569 </para>
1570 <para>
1571 Connectors state change detection must be cleanup up with a call to
1572 <function>drm_kms_helper_poll_fini</function>.
1573 </para>
1574 </sect2>
1575 <sect2>
1576 <title>Output discovery and initialization example</title>
1577 <programlisting><![CDATA[
524void intel_crt_init(struct drm_device *dev) 1578void intel_crt_init(struct drm_device *dev)
525{ 1579{
526 struct drm_connector *connector; 1580 struct drm_connector *connector;
@@ -556,252 +1610,741 @@ void intel_crt_init(struct drm_device *dev)
556 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); 1610 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
557 1611
558 drm_sysfs_connector_add(connector); 1612 drm_sysfs_connector_add(connector);
559} 1613}]]></programlisting>
560]]> 1614 <para>
561 </programlisting> 1615 In the example above (taken from the i915 driver), a CRTC, connector and
562 <para> 1616 encoder combination is created. A device-specific i2c bus is also
563 In the example above (again, taken from the i915 driver), a 1617 created for fetching EDID data and performing monitor detection. Once
564 CRT connector and encoder combination is created. A device-specific 1618 the process is complete, the new connector is registered with sysfs to
565 i2c bus is also created for fetching EDID data and 1619 make its properties available to applications.
566 performing monitor detection. Once the process is complete, 1620 </para>
567 the new connector is registered with sysfs to make its
568 properties available to applications.
569 </para>
570 <sect4>
571 <title>Helper functions and core functions</title>
572 <para>
573 Since many PC-class graphics devices have similar display output
574 designs, the DRM provides a set of helper functions to make
575 output management easier. The core helper routines handle
576 encoder re-routing and the disabling of unused functions following
577 mode setting. Using the helpers is optional, but recommended for
578 devices with PC-style architectures (i.e. a set of display planes
579 for feeding pixels to encoders which are in turn routed to
580 connectors). Devices with more complex requirements needing
581 finer grained management may opt to use the core callbacks
582 directly.
583 </para>
584 <para>
585 [Insert typical diagram here.] [Insert OMAP style config here.]
586 </para>
587 </sect4>
588 <para>
589 Each encoder object needs to provide:
590 <itemizedlist>
591 <listitem>
592 A DPMS (basically on/off) function.
593 </listitem>
594 <listitem>
595 A mode-fixup function (for converting requested modes into
596 native hardware timings).
597 </listitem>
598 <listitem>
599 Functions (prepare, set, and commit) for use by the core DRM
600 helper functions.
601 </listitem>
602 </itemizedlist>
603 Connector helpers need to provide functions (mode-fetch, validity,
604 and encoder-matching) for returning an ideal encoder for a given
605 connector. The core connector functions include a DPMS callback,
606 save/restore routines (deprecated), detection, mode probing,
607 property handling, and cleanup functions.
608 </para>
609<!--!Edrivers/char/drm/drm_crtc.h-->
610<!--!Edrivers/char/drm/drm_crtc.c-->
611<!--!Edrivers/char/drm/drm_crtc_helper.c-->
612 </sect3>
613 </sect2> 1621 </sect2>
614 </sect1> 1622 </sect1>
615 1623
616 <!-- Internals: vblank handling --> 1624 <!-- Internals: mid-layer helper functions -->
617 1625
618 <sect1> 1626 <sect1>
619 <title>VBlank event handling</title> 1627 <title>Mid-layer Helper Functions</title>
620 <para> 1628 <para>
621 The DRM core exposes two vertical blank related ioctls: 1629 The CRTC, encoder and connector functions provided by the drivers
622 <variablelist> 1630 implement the DRM API. They're called by the DRM core and ioctl handlers
623 <varlistentry> 1631 to handle device state changes and configuration request. As implementing
624 <term>DRM_IOCTL_WAIT_VBLANK</term> 1632 those functions often requires logic not specific to drivers, mid-layer
625 <listitem> 1633 helper functions are available to avoid duplicating boilerplate code.
626 <para> 1634 </para>
627 This takes a struct drm_wait_vblank structure as its argument, 1635 <para>
628 and it is used to block or request a signal when a specified 1636 The DRM core contains one mid-layer implementation. The mid-layer provides
629 vblank event occurs. 1637 implementations of several CRTC, encoder and connector functions (called
630 </para> 1638 from the top of the mid-layer) that pre-process requests and call
631 </listitem> 1639 lower-level functions provided by the driver (at the bottom of the
632 </varlistentry> 1640 mid-layer). For instance, the
633 <varlistentry> 1641 <function>drm_crtc_helper_set_config</function> function can be used to
634 <term>DRM_IOCTL_MODESET_CTL</term> 1642 fill the struct <structname>drm_crtc_funcs</structname>
635 <listitem> 1643 <structfield>set_config</structfield> field. When called, it will split
636 <para> 1644 the <methodname>set_config</methodname> operation in smaller, simpler
637 This should be called by application level drivers before and 1645 operations and call the driver to handle them.
638 after mode setting, since on many devices the vertical blank
639 counter is reset at that time. Internally, the DRM snapshots
640 the last vblank count when the ioctl is called with the
641 _DRM_PRE_MODESET command, so that the counter won't go backwards
642 (which is dealt with when _DRM_POST_MODESET is used).
643 </para>
644 </listitem>
645 </varlistentry>
646 </variablelist>
647<!--!Edrivers/char/drm/drm_irq.c-->
648 </para> 1646 </para>
649 <para> 1647 <para>
650 To support the functions above, the DRM core provides several 1648 To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>,
651 helper functions for tracking vertical blank counters, and 1649 <function>drm_encoder_helper_add</function> and
652 requires drivers to provide several callbacks: 1650 <function>drm_connector_helper_add</function> functions to install their
653 get_vblank_counter(), enable_vblank() and disable_vblank(). The 1651 mid-layer bottom operations handlers, and fill the
654 core uses get_vblank_counter() to keep the counter accurate 1652 <structname>drm_crtc_funcs</structname>,
655 across interrupt disable periods. It should return the current 1653 <structname>drm_encoder_funcs</structname> and
656 vertical blank event count, which is often tracked in a device 1654 <structname>drm_connector_funcs</structname> structures with pointers to
657 register. The enable and disable vblank callbacks should enable 1655 the mid-layer top API functions. Installing the mid-layer bottom operation
658 and disable vertical blank interrupts, respectively. In the 1656 handlers is best done right after registering the corresponding KMS object.
659 absence of DRM clients waiting on vblank events, the core DRM
660 code uses the disable_vblank() function to disable
661 interrupts, which saves power. They are re-enabled again when
662 a client calls the vblank wait ioctl above.
663 </para> 1657 </para>
664 <para> 1658 <para>
665 A device that doesn't provide a count register may simply use an 1659 The mid-layer is not split between CRTC, encoder and connector operations.
666 internal atomic counter incremented on every vertical blank 1660 To use it, a driver must provide bottom functions for all of the three KMS
667 interrupt (and then treat the enable_vblank() and disable_vblank() 1661 entities.
668 callbacks as no-ops).
669 </para> 1662 </para>
1663 <sect2>
1664 <title>Helper Functions</title>
1665 <itemizedlist>
1666 <listitem>
1667 <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis>
1668 <para>
1669 The <function>drm_crtc_helper_set_config</function> helper function
1670 is a CRTC <methodname>set_config</methodname> implementation. It
1671 first tries to locate the best encoder for each connector by calling
1672 the connector <methodname>best_encoder</methodname> helper
1673 operation.
1674 </para>
1675 <para>
1676 After locating the appropriate encoders, the helper function will
1677 call the <methodname>mode_fixup</methodname> encoder and CRTC helper
1678 operations to adjust the requested mode, or reject it completely in
1679 which case an error will be returned to the application. If the new
1680 configuration after mode adjustment is identical to the current
1681 configuration the helper function will return without performing any
1682 other operation.
1683 </para>
1684 <para>
1685 If the adjusted mode is identical to the current mode but changes to
1686 the frame buffer need to be applied, the
1687 <function>drm_crtc_helper_set_config</function> function will call
1688 the CRTC <methodname>mode_set_base</methodname> helper operation. If
1689 the adjusted mode differs from the current mode, or if the
1690 <methodname>mode_set_base</methodname> helper operation is not
1691 provided, the helper function performs a full mode set sequence by
1692 calling the <methodname>prepare</methodname>,
1693 <methodname>mode_set</methodname> and
1694 <methodname>commit</methodname> CRTC and encoder helper operations,
1695 in that order.
1696 </para>
1697 </listitem>
1698 <listitem>
1699 <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis>
1700 <para>
1701 The <function>drm_helper_connector_dpms</function> helper function
1702 is a connector <methodname>dpms</methodname> implementation that
1703 tracks power state of connectors. To use the function, drivers must
1704 provide <methodname>dpms</methodname> helper operations for CRTCs
1705 and encoders to apply the DPMS state to the device.
1706 </para>
1707 <para>
1708 The mid-layer doesn't track the power state of CRTCs and encoders.
1709 The <methodname>dpms</methodname> helper operations can thus be
1710 called with a mode identical to the currently active mode.
1711 </para>
1712 </listitem>
1713 <listitem>
1714 <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector,
1715 uint32_t maxX, uint32_t maxY);</synopsis>
1716 <para>
1717 The <function>drm_helper_probe_single_connector_modes</function> helper
1718 function is a connector <methodname>fill_modes</methodname>
1719 implementation that updates the connection status for the connector
1720 and then retrieves a list of modes by calling the connector
1721 <methodname>get_modes</methodname> helper operation.
1722 </para>
1723 <para>
1724 The function filters out modes larger than
1725 <parameter>max_width</parameter> and <parameter>max_height</parameter>
1726 if specified. It then calls the connector
1727 <methodname>mode_valid</methodname> helper operation for each mode in
1728 the probed list to check whether the mode is valid for the connector.
1729 </para>
1730 </listitem>
1731 </itemizedlist>
1732 </sect2>
1733 <sect2>
1734 <title>CRTC Helper Operations</title>
1735 <itemizedlist>
1736 <listitem id="drm-helper-crtc-mode-fixup">
1737 <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc,
1738 const struct drm_display_mode *mode,
1739 struct drm_display_mode *adjusted_mode);</synopsis>
1740 <para>
1741 Let CRTCs adjust the requested mode or reject it completely. This
1742 operation returns true if the mode is accepted (possibly after being
1743 adjusted) or false if it is rejected.
1744 </para>
1745 <para>
1746 The <methodname>mode_fixup</methodname> operation should reject the
1747 mode if it can't reasonably use it. The definition of "reasonable"
1748 is currently fuzzy in this context. One possible behaviour would be
1749 to set the adjusted mode to the panel timings when a fixed-mode
1750 panel is used with hardware capable of scaling. Another behaviour
1751 would be to accept any input mode and adjust it to the closest mode
1752 supported by the hardware (FIXME: This needs to be clarified).
1753 </para>
1754 </listitem>
1755 <listitem>
1756 <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
1757 struct drm_framebuffer *old_fb)</synopsis>
1758 <para>
1759 Move the CRTC on the current frame buffer (stored in
1760 <literal>crtc-&gt;fb</literal>) to position (x,y). Any of the frame
1761 buffer, x position or y position may have been modified.
1762 </para>
1763 <para>
1764 This helper operation is optional. If not provided, the
1765 <function>drm_crtc_helper_set_config</function> function will fall
1766 back to the <methodname>mode_set</methodname> helper operation.
1767 </para>
1768 <note><para>
1769 FIXME: Why are x and y passed as arguments, as they can be accessed
1770 through <literal>crtc-&gt;x</literal> and
1771 <literal>crtc-&gt;y</literal>?
1772 </para></note>
1773 </listitem>
1774 <listitem>
1775 <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis>
1776 <para>
1777 Prepare the CRTC for mode setting. This operation is called after
1778 validating the requested mode. Drivers use it to perform
1779 device-specific operations required before setting the new mode.
1780 </para>
1781 </listitem>
1782 <listitem>
1783 <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
1784 struct drm_display_mode *adjusted_mode, int x, int y,
1785 struct drm_framebuffer *old_fb);</synopsis>
1786 <para>
1787 Set a new mode, position and frame buffer. Depending on the device
1788 requirements, the mode can be stored internally by the driver and
1789 applied in the <methodname>commit</methodname> operation, or
1790 programmed to the hardware immediately.
1791 </para>
1792 <para>
1793 The <methodname>mode_set</methodname> operation returns 0 on success
1794 or a negative error code if an error occurs.
1795 </para>
1796 </listitem>
1797 <listitem>
1798 <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis>
1799 <para>
1800 Commit a mode. This operation is called after setting the new mode.
1801 Upon return the device must use the new mode and be fully
1802 operational.
1803 </para>
1804 </listitem>
1805 </itemizedlist>
1806 </sect2>
1807 <sect2>
1808 <title>Encoder Helper Operations</title>
1809 <itemizedlist>
1810 <listitem>
1811 <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder,
1812 const struct drm_display_mode *mode,
1813 struct drm_display_mode *adjusted_mode);</synopsis>
1814 <note><para>
1815 FIXME: The mode argument be const, but the i915 driver modifies
1816 mode-&gt;clock in <function>intel_dp_mode_fixup</function>.
1817 </para></note>
1818 <para>
1819 Let encoders adjust the requested mode or reject it completely. This
1820 operation returns true if the mode is accepted (possibly after being
1821 adjusted) or false if it is rejected. See the
1822 <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper
1823 operation</link> for an explanation of the allowed adjustments.
1824 </para>
1825 </listitem>
1826 <listitem>
1827 <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis>
1828 <para>
1829 Prepare the encoder for mode setting. This operation is called after
1830 validating the requested mode. Drivers use it to perform
1831 device-specific operations required before setting the new mode.
1832 </para>
1833 </listitem>
1834 <listitem>
1835 <synopsis>void (*mode_set)(struct drm_encoder *encoder,
1836 struct drm_display_mode *mode,
1837 struct drm_display_mode *adjusted_mode);</synopsis>
1838 <para>
1839 Set a new mode. Depending on the device requirements, the mode can
1840 be stored internally by the driver and applied in the
1841 <methodname>commit</methodname> operation, or programmed to the
1842 hardware immediately.
1843 </para>
1844 </listitem>
1845 <listitem>
1846 <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis>
1847 <para>
1848 Commit a mode. This operation is called after setting the new mode.
1849 Upon return the device must use the new mode and be fully
1850 operational.
1851 </para>
1852 </listitem>
1853 </itemizedlist>
1854 </sect2>
1855 <sect2>
1856 <title>Connector Helper Operations</title>
1857 <itemizedlist>
1858 <listitem>
1859 <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis>
1860 <para>
1861 Return a pointer to the best encoder for the connecter. Device that
1862 map connectors to encoders 1:1 simply return the pointer to the
1863 associated encoder. This operation is mandatory.
1864 </para>
1865 </listitem>
1866 <listitem>
1867 <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis>
1868 <para>
1869 Fill the connector's <structfield>probed_modes</structfield> list
1870 by parsing EDID data with <function>drm_add_edid_modes</function> or
1871 calling <function>drm_mode_probed_add</function> directly for every
1872 supported mode and return the number of modes it has detected. This
1873 operation is mandatory.
1874 </para>
1875 <para>
1876 When adding modes manually the driver creates each mode with a call to
1877 <function>drm_mode_create</function> and must fill the following fields.
1878 <itemizedlist>
1879 <listitem>
1880 <synopsis>__u32 type;</synopsis>
1881 <para>
1882 Mode type bitmask, a combination of
1883 <variablelist>
1884 <varlistentry>
1885 <term>DRM_MODE_TYPE_BUILTIN</term>
1886 <listitem><para>not used?</para></listitem>
1887 </varlistentry>
1888 <varlistentry>
1889 <term>DRM_MODE_TYPE_CLOCK_C</term>
1890 <listitem><para>not used?</para></listitem>
1891 </varlistentry>
1892 <varlistentry>
1893 <term>DRM_MODE_TYPE_CRTC_C</term>
1894 <listitem><para>not used?</para></listitem>
1895 </varlistentry>
1896 <varlistentry>
1897 <term>
1898 DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector
1899 </term>
1900 <listitem>
1901 <para>not used?</para>
1902 </listitem>
1903 </varlistentry>
1904 <varlistentry>
1905 <term>DRM_MODE_TYPE_DEFAULT</term>
1906 <listitem><para>not used?</para></listitem>
1907 </varlistentry>
1908 <varlistentry>
1909 <term>DRM_MODE_TYPE_USERDEF</term>
1910 <listitem><para>not used?</para></listitem>
1911 </varlistentry>
1912 <varlistentry>
1913 <term>DRM_MODE_TYPE_DRIVER</term>
1914 <listitem>
1915 <para>
1916 The mode has been created by the driver (as opposed to
1917 to user-created modes).
1918 </para>
1919 </listitem>
1920 </varlistentry>
1921 </variablelist>
1922 Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they
1923 create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred
1924 mode.
1925 </para>
1926 </listitem>
1927 <listitem>
1928 <synopsis>__u32 clock;</synopsis>
1929 <para>Pixel clock frequency in kHz unit</para>
1930 </listitem>
1931 <listitem>
1932 <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal;
1933 __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis>
1934 <para>Horizontal and vertical timing information</para>
1935 <screen><![CDATA[
1936 Active Front Sync Back
1937 Region Porch Porch
1938 <-----------------------><----------------><-------------><-------------->
1939
1940 //////////////////////|
1941 ////////////////////// |
1942 ////////////////////// |.................. ................
1943 _______________
1944
1945 <----- [hv]display ----->
1946 <------------- [hv]sync_start ------------>
1947 <--------------------- [hv]sync_end --------------------->
1948 <-------------------------------- [hv]total ----------------------------->
1949]]></screen>
1950 </listitem>
1951 <listitem>
1952 <synopsis>__u16 hskew;
1953 __u16 vscan;</synopsis>
1954 <para>Unknown</para>
1955 </listitem>
1956 <listitem>
1957 <synopsis>__u32 flags;</synopsis>
1958 <para>
1959 Mode flags, a combination of
1960 <variablelist>
1961 <varlistentry>
1962 <term>DRM_MODE_FLAG_PHSYNC</term>
1963 <listitem><para>
1964 Horizontal sync is active high
1965 </para></listitem>
1966 </varlistentry>
1967 <varlistentry>
1968 <term>DRM_MODE_FLAG_NHSYNC</term>
1969 <listitem><para>
1970 Horizontal sync is active low
1971 </para></listitem>
1972 </varlistentry>
1973 <varlistentry>
1974 <term>DRM_MODE_FLAG_PVSYNC</term>
1975 <listitem><para>
1976 Vertical sync is active high
1977 </para></listitem>
1978 </varlistentry>
1979 <varlistentry>
1980 <term>DRM_MODE_FLAG_NVSYNC</term>
1981 <listitem><para>
1982 Vertical sync is active low
1983 </para></listitem>
1984 </varlistentry>
1985 <varlistentry>
1986 <term>DRM_MODE_FLAG_INTERLACE</term>
1987 <listitem><para>
1988 Mode is interlaced
1989 </para></listitem>
1990 </varlistentry>
1991 <varlistentry>
1992 <term>DRM_MODE_FLAG_DBLSCAN</term>
1993 <listitem><para>
1994 Mode uses doublescan
1995 </para></listitem>
1996 </varlistentry>
1997 <varlistentry>
1998 <term>DRM_MODE_FLAG_CSYNC</term>
1999 <listitem><para>
2000 Mode uses composite sync
2001 </para></listitem>
2002 </varlistentry>
2003 <varlistentry>
2004 <term>DRM_MODE_FLAG_PCSYNC</term>
2005 <listitem><para>
2006 Composite sync is active high
2007 </para></listitem>
2008 </varlistentry>
2009 <varlistentry>
2010 <term>DRM_MODE_FLAG_NCSYNC</term>
2011 <listitem><para>
2012 Composite sync is active low
2013 </para></listitem>
2014 </varlistentry>
2015 <varlistentry>
2016 <term>DRM_MODE_FLAG_HSKEW</term>
2017 <listitem><para>
2018 hskew provided (not used?)
2019 </para></listitem>
2020 </varlistentry>
2021 <varlistentry>
2022 <term>DRM_MODE_FLAG_BCAST</term>
2023 <listitem><para>
2024 not used?
2025 </para></listitem>
2026 </varlistentry>
2027 <varlistentry>
2028 <term>DRM_MODE_FLAG_PIXMUX</term>
2029 <listitem><para>
2030 not used?
2031 </para></listitem>
2032 </varlistentry>
2033 <varlistentry>
2034 <term>DRM_MODE_FLAG_DBLCLK</term>
2035 <listitem><para>
2036 not used?
2037 </para></listitem>
2038 </varlistentry>
2039 <varlistentry>
2040 <term>DRM_MODE_FLAG_CLKDIV2</term>
2041 <listitem><para>
2042 ?
2043 </para></listitem>
2044 </varlistentry>
2045 </variablelist>
2046 </para>
2047 <para>
2048 Note that modes marked with the INTERLACE or DBLSCAN flags will be
2049 filtered out by
2050 <function>drm_helper_probe_single_connector_modes</function> if
2051 the connector's <structfield>interlace_allowed</structfield> or
2052 <structfield>doublescan_allowed</structfield> field is set to 0.
2053 </para>
2054 </listitem>
2055 <listitem>
2056 <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis>
2057 <para>
2058 Mode name. The driver must call
2059 <function>drm_mode_set_name</function> to fill the mode name from
2060 <structfield>hdisplay</structfield>,
2061 <structfield>vdisplay</structfield> and interlace flag after
2062 filling the corresponding fields.
2063 </para>
2064 </listitem>
2065 </itemizedlist>
2066 </para>
2067 <para>
2068 The <structfield>vrefresh</structfield> value is computed by
2069 <function>drm_helper_probe_single_connector_modes</function>.
2070 </para>
2071 <para>
2072 When parsing EDID data, <function>drm_add_edid_modes</function> fill the
2073 connector <structfield>display_info</structfield>
2074 <structfield>width_mm</structfield> and
2075 <structfield>height_mm</structfield> fields. When creating modes
2076 manually the <methodname>get_modes</methodname> helper operation must
2077 set the <structfield>display_info</structfield>
2078 <structfield>width_mm</structfield> and
2079 <structfield>height_mm</structfield> fields if they haven't been set
2080 already (for instance at initilization time when a fixed-size panel is
2081 attached to the connector). The mode <structfield>width_mm</structfield>
2082 and <structfield>height_mm</structfield> fields are only used internally
2083 during EDID parsing and should not be set when creating modes manually.
2084 </para>
2085 </listitem>
2086 <listitem>
2087 <synopsis>int (*mode_valid)(struct drm_connector *connector,
2088 struct drm_display_mode *mode);</synopsis>
2089 <para>
2090 Verify whether a mode is valid for the connector. Return MODE_OK for
2091 supported modes and one of the enum drm_mode_status values (MODE_*)
2092 for unsupported modes. This operation is mandatory.
2093 </para>
2094 <para>
2095 As the mode rejection reason is currently not used beside for
2096 immediately removing the unsupported mode, an implementation can
2097 return MODE_BAD regardless of the exact reason why the mode is not
2098 valid.
2099 </para>
2100 <note><para>
2101 Note that the <methodname>mode_valid</methodname> helper operation is
2102 only called for modes detected by the device, and
2103 <emphasis>not</emphasis> for modes set by the user through the CRTC
2104 <methodname>set_config</methodname> operation.
2105 </para></note>
2106 </listitem>
2107 </itemizedlist>
2108 </sect2>
670 </sect1> 2109 </sect1>
671 2110
672 <sect1> 2111 <!-- Internals: vertical blanking -->
673 <title>Memory management</title> 2112
2113 <sect1 id="drm-vertical-blank">
2114 <title>Vertical Blanking</title>
2115 <para>
2116 Vertical blanking plays a major role in graphics rendering. To achieve
2117 tear-free display, users must synchronize page flips and/or rendering to
2118 vertical blanking. The DRM API offers ioctls to perform page flips
2119 synchronized to vertical blanking and wait for vertical blanking.
2120 </para>
2121 <para>
2122 The DRM core handles most of the vertical blanking management logic, which
2123 involves filtering out spurious interrupts, keeping race-free blanking
2124 counters, coping with counter wrap-around and resets and keeping use
2125 counts. It relies on the driver to generate vertical blanking interrupts
2126 and optionally provide a hardware vertical blanking counter. Drivers must
2127 implement the following operations.
2128 </para>
2129 <itemizedlist>
2130 <listitem>
2131 <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc);
2132void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis>
2133 <para>
2134 Enable or disable vertical blanking interrupts for the given CRTC.
2135 </para>
2136 </listitem>
2137 <listitem>
2138 <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis>
2139 <para>
2140 Retrieve the value of the vertical blanking counter for the given
2141 CRTC. If the hardware maintains a vertical blanking counter its value
2142 should be returned. Otherwise drivers can use the
2143 <function>drm_vblank_count</function> helper function to handle this
2144 operation.
2145 </para>
2146 </listitem>
2147 </itemizedlist>
674 <para> 2148 <para>
675 The memory manager lies at the heart of many DRM operations; it 2149 Drivers must initialize the vertical blanking handling core with a call to
676 is required to support advanced client features like OpenGL 2150 <function>drm_vblank_init</function> in their
677 pbuffers. The DRM currently contains two memory managers: TTM 2151 <methodname>load</methodname> operation. The function will set the struct
678 and GEM. 2152 <structname>drm_device</structname>
2153 <structfield>vblank_disable_allowed</structfield> field to 0. This will
2154 keep vertical blanking interrupts enabled permanently until the first mode
2155 set operation, where <structfield>vblank_disable_allowed</structfield> is
2156 set to 1. The reason behind this is not clear. Drivers can set the field
2157 to 1 after <function>calling drm_vblank_init</function> to make vertical
2158 blanking interrupts dynamically managed from the beginning.
679 </para> 2159 </para>
2160 <para>
2161 Vertical blanking interrupts can be enabled by the DRM core or by drivers
2162 themselves (for instance to handle page flipping operations). The DRM core
2163 maintains a vertical blanking use count to ensure that the interrupts are
2164 not disabled while a user still needs them. To increment the use count,
2165 drivers call <function>drm_vblank_get</function>. Upon return vertical
2166 blanking interrupts are guaranteed to be enabled.
2167 </para>
2168 <para>
2169 To decrement the use count drivers call
2170 <function>drm_vblank_put</function>. Only when the use count drops to zero
2171 will the DRM core disable the vertical blanking interrupts after a delay
2172 by scheduling a timer. The delay is accessible through the vblankoffdelay
2173 module parameter or the <varname>drm_vblank_offdelay</varname> global
2174 variable and expressed in milliseconds. Its default value is 5000 ms.
2175 </para>
2176 <para>
2177 When a vertical blanking interrupt occurs drivers only need to call the
2178 <function>drm_handle_vblank</function> function to account for the
2179 interrupt.
2180 </para>
2181 <para>
2182 Resources allocated by <function>drm_vblank_init</function> must be freed
2183 with a call to <function>drm_vblank_cleanup</function> in the driver
2184 <methodname>unload</methodname> operation handler.
2185 </para>
2186 </sect1>
2187
2188 <!-- Internals: open/close, file operations and ioctls -->
680 2189
2190 <sect1>
2191 <title>Open/Close, File Operations and IOCTLs</title>
681 <sect2> 2192 <sect2>
682 <title>The Translation Table Manager (TTM)</title> 2193 <title>Open and Close</title>
2194 <synopsis>int (*firstopen) (struct drm_device *);
2195void (*lastclose) (struct drm_device *);
2196int (*open) (struct drm_device *, struct drm_file *);
2197void (*preclose) (struct drm_device *, struct drm_file *);
2198void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
2199 <abstract>Open and close handlers. None of those methods are mandatory.
2200 </abstract>
683 <para> 2201 <para>
684 TTM was developed by Tungsten Graphics, primarily by Thomas 2202 The <methodname>firstopen</methodname> method is called by the DRM core
685 Hellström, and is intended to be a flexible, high performance 2203 when an application opens a device that has no other opened file handle.
686 graphics memory manager. 2204 Similarly the <methodname>lastclose</methodname> method is called when
2205 the last application holding a file handle opened on the device closes
2206 it. Both methods are mostly used for UMS (User Mode Setting) drivers to
2207 acquire and release device resources which should be done in the
2208 <methodname>load</methodname> and <methodname>unload</methodname>
2209 methods for KMS drivers.
687 </para> 2210 </para>
688 <para> 2211 <para>
689 Drivers wishing to support TTM must fill out a drm_bo_driver 2212 Note that the <methodname>lastclose</methodname> method is also called
690 structure. 2213 at module unload time or, for hot-pluggable devices, when the device is
2214 unplugged. The <methodname>firstopen</methodname> and
2215 <methodname>lastclose</methodname> calls can thus be unbalanced.
691 </para> 2216 </para>
692 <para> 2217 <para>
693 TTM design background and information belongs here. 2218 The <methodname>open</methodname> method is called every time the device
2219 is opened by an application. Drivers can allocate per-file private data
2220 in this method and store them in the struct
2221 <structname>drm_file</structname> <structfield>driver_priv</structfield>
2222 field. Note that the <methodname>open</methodname> method is called
2223 before <methodname>firstopen</methodname>.
2224 </para>
2225 <para>
2226 The close operation is split into <methodname>preclose</methodname> and
2227 <methodname>postclose</methodname> methods. Drivers must stop and
2228 cleanup all per-file operations in the <methodname>preclose</methodname>
2229 method. For instance pending vertical blanking and page flip events must
2230 be cancelled. No per-file operation is allowed on the file handle after
2231 returning from the <methodname>preclose</methodname> method.
2232 </para>
2233 <para>
2234 Finally the <methodname>postclose</methodname> method is called as the
2235 last step of the close operation, right before calling the
2236 <methodname>lastclose</methodname> method if no other open file handle
2237 exists for the device. Drivers that have allocated per-file private data
2238 in the <methodname>open</methodname> method should free it here.
2239 </para>
2240 <para>
2241 The <methodname>lastclose</methodname> method should restore CRTC and
2242 plane properties to default value, so that a subsequent open of the
2243 device will not inherit state from the previous user.
694 </para> 2244 </para>
695 </sect2> 2245 </sect2>
696
697 <sect2> 2246 <sect2>
698 <title>The Graphics Execution Manager (GEM)</title> 2247 <title>File Operations</title>
2248 <synopsis>const struct file_operations *fops</synopsis>
2249 <abstract>File operations for the DRM device node.</abstract>
699 <para> 2250 <para>
700 GEM is an Intel project, authored by Eric Anholt and Keith 2251 Drivers must define the file operations structure that forms the DRM
701 Packard. It provides simpler interfaces than TTM, and is well 2252 userspace API entry point, even though most of those operations are
702 suited for UMA devices. 2253 implemented in the DRM core. The <methodname>open</methodname>,
2254 <methodname>release</methodname> and <methodname>ioctl</methodname>
2255 operations are handled by
2256 <programlisting>
2257 .owner = THIS_MODULE,
2258 .open = drm_open,
2259 .release = drm_release,
2260 .unlocked_ioctl = drm_ioctl,
2261 #ifdef CONFIG_COMPAT
2262 .compat_ioctl = drm_compat_ioctl,
2263 #endif
2264 </programlisting>
703 </para> 2265 </para>
704 <para> 2266 <para>
705 GEM-enabled drivers must provide gem_init_object() and 2267 Drivers that implement private ioctls that requires 32/64bit
706 gem_free_object() callbacks to support the core memory 2268 compatibility support must provide their own
707 allocation routines. They should also provide several driver-specific 2269 <methodname>compat_ioctl</methodname> handler that processes private
708 ioctls to support command execution, pinning, buffer 2270 ioctls and calls <function>drm_compat_ioctl</function> for core ioctls.
709 read &amp; write, mapping, and domain ownership transfers.
710 </para> 2271 </para>
711 <para> 2272 <para>
712 On a fundamental level, GEM involves several operations: 2273 The <methodname>read</methodname> and <methodname>poll</methodname>
713 <itemizedlist> 2274 operations provide support for reading DRM events and polling them. They
714 <listitem>Memory allocation and freeing</listitem> 2275 are implemented by
715 <listitem>Command execution</listitem> 2276 <programlisting>
716 <listitem>Aperture management at command execution time</listitem> 2277 .poll = drm_poll,
717 </itemizedlist> 2278 .read = drm_read,
718 Buffer object allocation is relatively 2279 .fasync = drm_fasync,
719 straightforward and largely provided by Linux's shmem layer, which 2280 .llseek = no_llseek,
720 provides memory to back each object. When mapped into the GTT 2281 </programlisting>
721 or used in a command buffer, the backing pages for an object are 2282 </para>
722 flushed to memory and marked write combined so as to be coherent 2283 <para>
723 with the GPU. Likewise, if the CPU accesses an object after the GPU 2284 The memory mapping implementation varies depending on how the driver
724 has finished rendering to the object, then the object must be made 2285 manages memory. Pre-GEM drivers will use <function>drm_mmap</function>,
725 coherent with the CPU's view 2286 while GEM-aware drivers will use <function>drm_gem_mmap</function>. See
726 of memory, usually involving GPU cache flushing of various kinds. 2287 <xref linkend="drm-gem"/>.
727 This core CPU&lt;-&gt;GPU coherency management is provided by a 2288 <programlisting>
728 device-specific ioctl, which evaluates an object's current domain and 2289 .mmap = drm_gem_mmap,
729 performs any necessary flushing or synchronization to put the object 2290 </programlisting>
730 into the desired coherency domain (note that the object may be busy, 2291 </para>
731 i.e. an active render target; in that case, setting the domain 2292 <para>
732 blocks the client and waits for rendering to complete before 2293 No other file operation is supported by the DRM API.
733 performing any necessary flushing operations). 2294 </para>
734 </para> 2295 </sect2>
735 <para> 2296 <sect2>
736 Perhaps the most important GEM function is providing a command 2297 <title>IOCTLs</title>
737 execution interface to clients. Client programs construct command 2298 <synopsis>struct drm_ioctl_desc *ioctls;
738 buffers containing references to previously allocated memory objects, 2299int num_ioctls;</synopsis>
739 and then submit them to GEM. At that point, GEM takes care to bind 2300 <abstract>Driver-specific ioctls descriptors table.</abstract>
740 all the objects into the GTT, execute the buffer, and provide 2301 <para>
741 necessary synchronization between clients accessing the same buffers. 2302 Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls
742 This often involves evicting some objects from the GTT and re-binding 2303 descriptors table is indexed by the ioctl number offset from the base
743 others (a fairly expensive operation), and providing relocation 2304 value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the
744 support which hides fixed GTT offsets from clients. Clients must 2305 table entries.
745 take care not to submit command buffers that reference more objects 2306 </para>
746 than can fit in the GTT; otherwise, GEM will reject them and no rendering 2307 <para>
747 will occur. Similarly, if several objects in the buffer require 2308 <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting>
748 fence registers to be allocated for correct rendering (e.g. 2D blits 2309 <para>
749 on pre-965 chips), care must be taken not to require more fence 2310 <parameter>ioctl</parameter> is the ioctl name. Drivers must define
750 registers than are available to the client. Such resource management 2311 the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number
751 should be abstracted from the client in libdrm. 2312 offset from DRM_COMMAND_BASE and the ioctl number respectively. The
2313 first macro is private to the device while the second must be exposed
2314 to userspace in a public header.
2315 </para>
2316 <para>
2317 <parameter>func</parameter> is a pointer to the ioctl handler function
2318 compatible with the <type>drm_ioctl_t</type> type.
2319 <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data,
2320 struct drm_file *file_priv);</programlisting>
2321 </para>
2322 <para>
2323 <parameter>flags</parameter> is a bitmask combination of the following
2324 values. It restricts how the ioctl is allowed to be called.
2325 <itemizedlist>
2326 <listitem><para>
2327 DRM_AUTH - Only authenticated callers allowed
2328 </para></listitem>
2329 <listitem><para>
2330 DRM_MASTER - The ioctl can only be called on the master file
2331 handle
2332 </para></listitem>
2333 <listitem><para>
2334 DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed
2335 </para></listitem>
2336 <listitem><para>
2337 DRM_CONTROL_ALLOW - The ioctl can only be called on a control
2338 device
2339 </para></listitem>
2340 <listitem><para>
2341 DRM_UNLOCKED - The ioctl handler will be called without locking
2342 the DRM global mutex
2343 </para></listitem>
2344 </itemizedlist>
2345 </para>
752 </para> 2346 </para>
753 </sect2> 2347 </sect2>
754
755 </sect1>
756
757 <!-- Output management -->
758 <sect1>
759 <title>Output management</title>
760 <para>
761 At the core of the DRM output management code is a set of
762 structures representing CRTCs, encoders, and connectors.
763 </para>
764 <para>
765 A CRTC is an abstraction representing a part of the chip that
766 contains a pointer to a scanout buffer. Therefore, the number
767 of CRTCs available determines how many independent scanout
768 buffers can be active at any given time. The CRTC structure
769 contains several fields to support this: a pointer to some video
770 memory, a display mode, and an (x, y) offset into the video
771 memory to support panning or configurations where one piece of
772 video memory spans multiple CRTCs.
773 </para>
774 <para>
775 An encoder takes pixel data from a CRTC and converts it to a
776 format suitable for any attached connectors. On some devices,
777 it may be possible to have a CRTC send data to more than one
778 encoder. In that case, both encoders would receive data from
779 the same scanout buffer, resulting in a "cloned" display
780 configuration across the connectors attached to each encoder.
781 </para>
782 <para>
783 A connector is the final destination for pixel data on a device,
784 and usually connects directly to an external display device like
785 a monitor or laptop panel. A connector can only be attached to
786 one encoder at a time. The connector is also the structure
787 where information about the attached display is kept, so it
788 contains fields for display data, EDID data, DPMS &amp;
789 connection status, and information about modes supported on the
790 attached displays.
791 </para>
792<!--!Edrivers/char/drm/drm_crtc.c-->
793 </sect1>
794
795 <sect1>
796 <title>Framebuffer management</title>
797 <para>
798 Clients need to provide a framebuffer object which provides a source
799 of pixels for a CRTC to deliver to the encoder(s) and ultimately the
800 connector(s). A framebuffer is fundamentally a driver-specific memory
801 object, made into an opaque handle by the DRM's addfb() function.
802 Once a framebuffer has been created this way, it may be passed to the
803 KMS mode setting routines for use in a completed configuration.
804 </para>
805 </sect1> 2348 </sect1>
806 2349
807 <sect1> 2350 <sect1>
@@ -812,15 +2355,24 @@ void intel_crt_init(struct drm_device *dev)
812 </para> 2355 </para>
813 </sect1> 2356 </sect1>
814 2357
2358 <!-- Internals: suspend/resume -->
2359
815 <sect1> 2360 <sect1>
816 <title>Suspend/resume</title> 2361 <title>Suspend/Resume</title>
2362 <para>
2363 The DRM core provides some suspend/resume code, but drivers wanting full
2364 suspend/resume support should provide save() and restore() functions.
2365 These are called at suspend, hibernate, or resume time, and should perform
2366 any state save or restore required by your device across suspend or
2367 hibernate states.
2368 </para>
2369 <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);
2370int (*resume) (struct drm_device *);</synopsis>
817 <para> 2371 <para>
818 The DRM core provides some suspend/resume code, but drivers 2372 Those are legacy suspend and resume methods. New driver should use the
819 wanting full suspend/resume support should provide save() and 2373 power management interface provided by their bus type (usually through
820 restore() functions. These are called at suspend, 2374 the struct <structname>device_driver</structname> dev_pm_ops) and set
821 hibernate, or resume time, and should perform any state save or 2375 these methods to NULL.
822 restore required by your device across suspend or hibernate
823 states.
824 </para> 2376 </para>
825 </sect1> 2377 </sect1>
826 2378
@@ -833,6 +2385,35 @@ void intel_crt_init(struct drm_device *dev)
833 </sect1> 2385 </sect1>
834 </chapter> 2386 </chapter>
835 2387
2388<!-- TODO
2389
2390- Add a glossary
2391- Document the struct_mutex catch-all lock
2392- Document connector properties
2393
2394- Why is the load method optional?
2395- What are drivers supposed to set the initial display state to, and how?
2396 Connector's DPMS states are not initialized and are thus equal to
2397 DRM_MODE_DPMS_ON. The fbcon compatibility layer calls
2398 drm_helper_disable_unused_functions(), which disables unused encoders and
2399 CRTCs, but doesn't touch the connectors' DPMS state, and
2400 drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers
2401 that don't implement (or just don't use) fbcon compatibility need to call
2402 those functions themselves?
2403- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset()
2404 around mode setting. Should this be done in the DRM core?
2405- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset()
2406 call and never set back to 0. It seems to be safe to permanently set it to 1
2407 in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as
2408 well. This should be investigated.
2409- crtc and connector .save and .restore operations are only used internally in
2410 drivers, should they be removed from the core?
2411- encoder mid-layer .save and .restore operations are only used internally in
2412 drivers, should they be removed from the core?
2413- encoder mid-layer .detect operation is only used internally in drivers,
2414 should it be removed from the core?
2415-->
2416
836 <!-- External interfaces --> 2417 <!-- External interfaces -->
837 2418
838 <chapter id="drmExternals"> 2419 <chapter id="drmExternals">
@@ -853,6 +2434,42 @@ void intel_crt_init(struct drm_device *dev)
853 Cover generic ioctls and sysfs layout here. We only need high-level 2434 Cover generic ioctls and sysfs layout here. We only need high-level
854 info, since man pages should cover the rest. 2435 info, since man pages should cover the rest.
855 </para> 2436 </para>
2437
2438 <!-- External: vblank handling -->
2439
2440 <sect1>
2441 <title>VBlank event handling</title>
2442 <para>
2443 The DRM core exposes two vertical blank related ioctls:
2444 <variablelist>
2445 <varlistentry>
2446 <term>DRM_IOCTL_WAIT_VBLANK</term>
2447 <listitem>
2448 <para>
2449 This takes a struct drm_wait_vblank structure as its argument,
2450 and it is used to block or request a signal when a specified
2451 vblank event occurs.
2452 </para>
2453 </listitem>
2454 </varlistentry>
2455 <varlistentry>
2456 <term>DRM_IOCTL_MODESET_CTL</term>
2457 <listitem>
2458 <para>
2459 This should be called by application level drivers before and
2460 after mode setting, since on many devices the vertical blank
2461 counter is reset at that time. Internally, the DRM snapshots
2462 the last vblank count when the ioctl is called with the
2463 _DRM_PRE_MODESET command, so that the counter won't go backwards
2464 (which is dealt with when _DRM_POST_MODESET is used).
2465 </para>
2466 </listitem>
2467 </varlistentry>
2468 </variablelist>
2469<!--!Edrivers/char/drm/drm_irq.c-->
2470 </para>
2471 </sect1>
2472
856 </chapter> 2473 </chapter>
857 2474
858 <!-- API reference --> 2475 <!-- API reference -->
generated by cgit v1.2.2 (git 2.25.0) at 2024-10-31 23:39:40 -0400