Commit | Line | Data |
---|---|---|
2d2ef822 JB |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="drmDevelopersGuide"> | |
6 | <bookinfo> | |
7 | <title>Linux DRM Developer's Guide</title> | |
8 | ||
9 | <copyright> | |
10 | <year>2008-2009</year> | |
11 | <holder> | |
12 | Intel Corporation (Jesse Barnes <jesse.barnes@intel.com>) | |
13 | </holder> | |
14 | </copyright> | |
15 | ||
16 | <legalnotice> | |
17 | <para> | |
18 | The contents of this file may be used under the terms of the GNU | |
19 | General Public License version 2 (the "GPL") as distributed in | |
20 | the kernel source COPYING file. | |
21 | </para> | |
22 | </legalnotice> | |
23 | </bookinfo> | |
24 | ||
25 | <toc></toc> | |
26 | ||
27 | <!-- Introduction --> | |
28 | ||
29 | <chapter id="drmIntroduction"> | |
30 | <title>Introduction</title> | |
31 | <para> | |
32 | The Linux DRM layer contains code intended to support the needs | |
33 | of complex graphics devices, usually containing programmable | |
34 | pipelines well suited to 3D graphics acceleration. Graphics | |
f11aca04 | 35 | drivers in the kernel may make use of DRM functions to make |
2d2ef822 JB |
36 | tasks like memory management, interrupt handling and DMA easier, |
37 | and provide a uniform interface to applications. | |
38 | </para> | |
39 | <para> | |
40 | A note on versions: this guide covers features found in the DRM | |
41 | tree, including the TTM memory manager, output configuration and | |
42 | mode setting, and the new vblank internals, in addition to all | |
43 | the regular features found in current kernels. | |
44 | </para> | |
45 | <para> | |
46 | [Insert diagram of typical DRM stack here] | |
47 | </para> | |
48 | </chapter> | |
49 | ||
50 | <!-- Internals --> | |
51 | ||
52 | <chapter id="drmInternals"> | |
53 | <title>DRM Internals</title> | |
54 | <para> | |
55 | This chapter documents DRM internals relevant to driver authors | |
56 | and developers working to add support for the latest features to | |
57 | existing drivers. | |
58 | </para> | |
59 | <para> | |
a78f6787 | 60 | First, we go over some typical driver initialization |
2d2ef822 JB |
61 | requirements, like setting up command buffers, creating an |
62 | initial output configuration, and initializing core services. | |
a78f6787 | 63 | Subsequent sections cover core internals in more detail, |
2d2ef822 JB |
64 | providing implementation notes and examples. |
65 | </para> | |
66 | <para> | |
67 | The DRM layer provides several services to graphics drivers, | |
68 | many of them driven by the application interfaces it provides | |
69 | through libdrm, the library that wraps most of the DRM ioctls. | |
70 | These include vblank event handling, memory | |
71 | management, output management, framebuffer management, command | |
72 | submission & fencing, suspend/resume support, and DMA | |
73 | services. | |
74 | </para> | |
75 | <para> | |
bd91572e | 76 | The core of every DRM driver is struct drm_driver. Drivers |
a78f6787 | 77 | typically statically initialize a drm_driver structure, |
2d2ef822 JB |
78 | then pass it to drm_init() at load time. |
79 | </para> | |
80 | ||
81 | <!-- Internals: driver init --> | |
82 | ||
83 | <sect1> | |
84 | <title>Driver initialization</title> | |
85 | <para> | |
86 | Before calling the DRM initialization routines, the driver must | |
bd91572e | 87 | first create and fill out a struct drm_driver structure. |
2d2ef822 JB |
88 | </para> |
89 | <programlisting> | |
90 | static struct drm_driver driver = { | |
0c54781b MW |
91 | /* Don't use MTRRs here; the Xserver or userspace app should |
92 | * deal with them for Intel hardware. | |
2d2ef822 JB |
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 = &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 | |
dc880abe | 139 | .llseek = noop_llseek, |
2d2ef822 JB |
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 | |
2c267e9e MW |
157 | sets several flags indicating what core features it supports; |
158 | we go over the individual callbacks in later sections. Since | |
2d2ef822 JB |
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> | |
02391f1f | 206 | DRIVER_HAVE_IRQ indicates whether the driver has an IRQ |
b1f95bdc | 207 | handler. DRIVER_IRQ_SHARED indicates whether the device & |
2d2ef822 JB |
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> | |
80c84e6f MW |
217 | Should be set if the driver queues DMA requests and completes them |
218 | asynchronously. Deprecated. | |
2d2ef822 JB |
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 | |
a78f6787 | 241 | IRQs. DMA, as discussed later, is handled by device specific ioctls |
2d2ef822 JB |
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> | |
246 | </sect1> | |
247 | ||
248 | <!-- Internals: driver load --> | |
249 | ||
250 | <sect1> | |
251 | <title>Driver load</title> | |
252 | <para> | |
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 & command | |
268 | buffers), initializing the memory manager, and setting up the | |
269 | initial output configuration. | |
270 | </para> | |
271 | <para> | |
6e375f44 MW |
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 | |
2d2ef822 JB |
276 | level mode setting drivers are in use, it would be problematic |
277 | to perform output discovery & configuration at load time. | |
58f1d652 | 278 | Likewise, if user-level drivers unaware of memory management are |
2d2ef822 JB |
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 | |
6e375f44 | 284 | enabled at load time or in legacy fashion. |
2d2ef822 JB |
285 | </para> |
286 | ||
287 | <sect2> | |
288 | <title>Driver private & performance counters</title> | |
289 | <para> | |
290 | The driver private hangs off the main drm_device structure and | |
291 | can be used for tracking various device specific bits of | |
292 | information, like register offsets, command buffer status, | |
293 | register state for suspend/resume, etc. At load time, a | |
f11aca04 | 294 | driver may simply allocate one and set drm_device.dev_priv |
06fa7b80 MW |
295 | appropriately; it should be freed and drm_device.dev_priv set |
296 | to NULL when the driver is unloaded. | |
2d2ef822 JB |
297 | </para> |
298 | <para> | |
f11aca04 | 299 | The DRM supports several counters which may be used for rough |
2d2ef822 JB |
300 | performance characterization. Note that the DRM stat counter |
301 | system is not often used by applications, and supporting | |
302 | additional counters is completely optional. | |
303 | </para> | |
304 | <para> | |
305 | These interfaces are deprecated and should not be used. If performance | |
306 | monitoring is desired, the developer should investigate and | |
307 | potentially enhance the kernel perf and tracing infrastructure to export | |
57a15fd6 MW |
308 | GPU related performance information for consumption by performance |
309 | monitoring tools and applications. | |
2d2ef822 JB |
310 | </para> |
311 | </sect2> | |
312 | ||
313 | <sect2> | |
314 | <title>Configuring the device</title> | |
315 | <para> | |
a78f6787 | 316 | Obviously, device configuration is device specific. |
2d2ef822 JB |
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 & mapping resources is fairly straightforward. The | |
323 | DRM wrapper functions, drm_get_resource_start() and | |
8814630f | 324 | drm_get_resource_len(), may be used to find BARs on the given |
2d2ef822 JB |
325 | drm_device struct. Once those values have been retrieved, the |
326 | driver load function can call drm_addmap() to create a new | |
8814630f | 327 | mapping for the BAR in question. Note that you probably want a |
2d2ef822 JB |
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), | |
f11aca04 | 336 | native Linux calls may be used for the above, e.g. pci_resource_* |
2d2ef822 JB |
337 | and iomap*/iounmap. See the Linux device driver book for more |
338 | info. | |
339 | </para> | |
340 | <para> | |
f11aca04 | 341 | Once you have a register map, you may use the DRM_READn() and |
2d2ef822 JB |
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 | |
f07faf69 | 345 | an example). |
2d2ef822 JB |
346 | </para> |
347 | <para> | |
348 | If your device supports interrupt generation, you may want to | |
bb49a6a1 | 349 | set up an interrupt handler when the driver is loaded. This |
2d2ef822 JB |
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> | |
a78f6787 | 358 | Once your interrupt handler is registered (it uses your |
2d2ef822 JB |
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 | |
9c2416ad MW |
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, | |
118bdd70 | 374 | it should be unmapped; on many devices, the ROM address decoder is |
8d36ffae | 375 | shared with other BARs, so leaving it mapped could cause |
2d2ef822 JB |
376 | undesired behavior like hangs or memory corruption. |
377 | <!--!Fdrivers/pci/rom.c pci_map_rom--> | |
378 | </para> | |
379 | </sect2> | |
380 | ||
381 | <sect2> | |
382 | <title>Memory manager initialization</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> | |
a78f6787 | 390 | If your driver supports memory management (it should!), you |
ce04cc08 | 391 | need to set that up at load time as well. How you initialize |
eb2b8d42 | 392 | it depends on which memory manager you're using: TTM or GEM. |
2d2ef822 JB |
393 | </para> |
394 | <sect3> | |
395 | <title>TTM initialization</title> | |
396 | <para> | |
397 | TTM (for Translation Table Manager) manages video memory and | |
398 | aperture space for graphics devices. TTM supports both UMA devices | |
399 | and devices with dedicated video RAM (VRAM), i.e. most discrete | |
400 | graphics devices. If your device has dedicated RAM, supporting | |
ce04cc08 | 401 | TTM is desirable. TTM also integrates tightly with your |
2d2ef822 JB |
402 | driver specific buffer execution function. See the radeon |
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> | |
412 | <para> | |
413 | The ttm_global_reference structure is made up of several fields: | |
414 | </para> | |
415 | <programlisting> | |
416 | struct ttm_global_reference { | |
417 | enum ttm_global_types global_type; | |
418 | size_t size; | |
419 | void *object; | |
420 | int (*init) (struct ttm_global_reference *); | |
421 | void (*release) (struct ttm_global_reference *); | |
422 | }; | |
423 | </programlisting> | |
424 | <para> | |
425 | There should be one global reference structure for your memory | |
426 | manager as a whole, and there will be others for each object | |
427 | created by the memory manager at runtime. Your global TTM should | |
428 | have a type of TTM_GLOBAL_TTM_MEM. The size field for the global | |
429 | object should be sizeof(struct ttm_mem_global), and the init and | |
430 | release hooks should point at your driver specific init and | |
a78f6787 | 431 | release routines, which probably eventually call |
005d7f4a | 432 | ttm_mem_global_init and ttm_mem_global_release, respectively. |
2d2ef822 JB |
433 | </para> |
434 | <para> | |
435 | Once your global TTM accounting structure is set up and initialized | |
ae63d793 | 436 | by calling ttm_global_item_ref() on it, |
1c86de22 | 437 | you need to create a buffer object TTM to |
2d2ef822 JB |
438 | provide a pool for buffer object allocation by clients and the |
439 | kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, | |
440 | and its size should be sizeof(struct ttm_bo_global). Again, | |
f11aca04 | 441 | driver specific init and release functions may be provided, |
ae63d793 MW |
442 | likely eventually calling ttm_bo_global_init() and |
443 | ttm_bo_global_release(), respectively. Also, like the previous | |
444 | object, ttm_global_item_ref() is used to create an initial reference | |
ce04cc08 | 445 | count for the TTM, which will call your initialization function. |
2d2ef822 JB |
446 | </para> |
447 | </sect3> | |
448 | <sect3> | |
449 | <title>GEM initialization</title> | |
450 | <para> | |
451 | GEM is an alternative to TTM, designed specifically for UMA | |
452 | devices. It has simpler initialization and execution requirements | |
453 | than TTM, but has no VRAM management capability. Core GEM | |
049cc903 | 454 | is initialized by calling drm_mm_init() to create |
2d2ef822 | 455 | a GTT DRM MM object, which provides an address space pool for |
a78f6787 MW |
456 | object allocation. In a KMS configuration, the driver |
457 | needs to allocate and initialize a command ring buffer following | |
9029bd7a | 458 | core GEM initialization. A UMA device usually has what is called a |
2d2ef822 JB |
459 | "stolen" memory region, which provides space for the initial |
460 | framebuffer and large, contiguous memory regions required by the | |
1dbd39c3 | 461 | device. This space is not typically managed by GEM, and it must |
2d2ef822 JB |
462 | be initialized separately into its own DRM MM object. |
463 | </para> | |
464 | <para> | |
3bf7df61 | 465 | Initialization is driver specific. In the case of Intel |
2d2ef822 JB |
466 | integrated graphics chips like 965GM, GEM initialization can |
467 | be done by calling the internal GEM init function, | |
468 | i915_gem_do_init(). Since the 965GM is a UMA device | |
a78f6787 | 469 | (i.e. it doesn't have dedicated VRAM), GEM manages |
2d2ef822 JB |
470 | making regular RAM available for GPU operations. Memory set |
471 | aside by the BIOS (called "stolen" memory by the i915 | |
a78f6787 MW |
472 | driver) is managed by the DRM memrange allocator; the |
473 | rest of the aperture is managed by GEM. | |
2d2ef822 JB |
474 | <programlisting> |
475 | /* Basic memrange allocator for stolen space (aka vram) */ | |
476 | drm_memrange_init(&dev_priv->vram, 0, prealloc_size); | |
477 | /* Let GEM Manage from end of prealloc space to end of aperture */ | |
478 | i915_gem_do_init(dev, prealloc_size, agp_size); | |
479 | </programlisting> | |
480 | <!--!Edrivers/char/drm/drm_memrange.c--> | |
481 | </para> | |
482 | <para> | |
f11aca04 | 483 | Once the memory manager has been set up, we may allocate the |
2d2ef822 JB |
484 | command buffer. In the i915 case, this is also done with a |
485 | GEM function, i915_gem_init_ringbuffer(). | |
486 | </para> | |
487 | </sect3> | |
488 | </sect2> | |
489 | ||
490 | <sect2> | |
491 | <title>Output configuration</title> | |
492 | <para> | |
327d6fb9 MW |
493 | The final initialization task is output configuration. This involves: |
494 | <itemizedlist> | |
495 | <listitem> | |
496 | Finding and initializing the CRTCs, encoders, and connectors | |
497 | for the device. | |
498 | </listitem> | |
499 | <listitem> | |
500 | Creating an initial configuration. | |
501 | </listitem> | |
502 | <listitem> | |
503 | Registering a framebuffer console driver. | |
504 | </listitem> | |
505 | </itemizedlist> | |
2d2ef822 JB |
506 | </para> |
507 | <sect3> | |
508 | <title>Output discovery and initialization</title> | |
509 | <para> | |
005d7f4a MW |
510 | Several core functions exist to create CRTCs, encoders, and |
511 | connectors, namely drm_crtc_init(), drm_connector_init(), and | |
2d2ef822 JB |
512 | drm_encoder_init(), along with several "helper" functions to |
513 | perform common tasks. | |
514 | </para> | |
515 | <para> | |
516 | Connectors should be registered with sysfs once they've been | |
517 | detected and initialized, using the | |
518 | drm_sysfs_connector_add() function. Likewise, when they're | |
519 | removed from the system, they should be destroyed with | |
520 | drm_sysfs_connector_remove(). | |
521 | </para> | |
522 | <programlisting> | |
523 | <![CDATA[ | |
524 | void intel_crt_init(struct drm_device *dev) | |
525 | { | |
526 | struct drm_connector *connector; | |
527 | struct intel_output *intel_output; | |
528 | ||
529 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
530 | if (!intel_output) | |
531 | return; | |
532 | ||
533 | connector = &intel_output->base; | |
534 | drm_connector_init(dev, &intel_output->base, | |
535 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
536 | ||
537 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
538 | DRM_MODE_ENCODER_DAC); | |
539 | ||
540 | drm_mode_connector_attach_encoder(&intel_output->base, | |
541 | &intel_output->enc); | |
542 | ||
543 | /* Set up the DDC bus. */ | |
544 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
545 | if (!intel_output->ddc_bus) { | |
546 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
547 | "failed.\n"); | |
548 | return; | |
549 | } | |
550 | ||
551 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
552 | connector->interlace_allowed = 0; | |
553 | connector->doublescan_allowed = 0; | |
554 | ||
555 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
556 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
557 | ||
558 | drm_sysfs_connector_add(connector); | |
559 | } | |
560 | ]]> | |
561 | </programlisting> | |
562 | <para> | |
563 | In the example above (again, taken from the i915 driver), a | |
564 | CRT connector and encoder combination is created. A device | |
565 | specific i2c bus is also created, for fetching EDID data and | |
566 | performing monitor detection. Once the process is complete, | |
ce04cc08 | 567 | the new connector is registered with sysfs, to make its |
2d2ef822 JB |
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 disabling of unused functions following | |
577 | mode set. 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 | |
f11aca04 | 581 | finer grained management may opt to use the core callbacks |
2d2ef822 JB |
582 | directly. |
583 | </para> | |
584 | <para> | |
585 | [Insert typical diagram here.] [Insert OMAP style config here.] | |
586 | </para> | |
587 | </sect4> | |
588 | <para> | |
005d7f4a | 589 | For each encoder, CRTC, and connector, several functions must |
2d2ef822 | 590 | be provided, depending on the object type. Encoder objects |
ce04cc08 | 591 | need to provide a DPMS (basically on/off) function, mode fixup |
2d2ef822 JB |
592 | (for converting requested modes into native hardware timings), |
593 | and prepare, set and commit functions for use by the core DRM | |
594 | helper functions. Connector helpers need to provide mode fetch and | |
595 | validity functions as well as an encoder matching function for | |
ce04cc08 | 596 | returning an ideal encoder for a given connector. The core |
2d2ef822 JB |
597 | connector functions include a DPMS callback, (deprecated) |
598 | save/restore routines, detection, mode probing, property handling, | |
599 | and cleanup functions. | |
600 | </para> | |
601 | <!--!Edrivers/char/drm/drm_crtc.h--> | |
602 | <!--!Edrivers/char/drm/drm_crtc.c--> | |
603 | <!--!Edrivers/char/drm/drm_crtc_helper.c--> | |
604 | </sect3> | |
605 | </sect2> | |
606 | </sect1> | |
607 | ||
608 | <!-- Internals: vblank handling --> | |
609 | ||
610 | <sect1> | |
611 | <title>VBlank event handling</title> | |
612 | <para> | |
613 | The DRM core exposes two vertical blank related ioctls: | |
614 | DRM_IOCTL_WAIT_VBLANK and DRM_IOCTL_MODESET_CTL. | |
615 | <!--!Edrivers/char/drm/drm_irq.c--> | |
616 | </para> | |
617 | <para> | |
618 | DRM_IOCTL_WAIT_VBLANK takes a struct drm_wait_vblank structure | |
619 | as its argument, and is used to block or request a signal when a | |
620 | specified vblank event occurs. | |
621 | </para> | |
622 | <para> | |
623 | DRM_IOCTL_MODESET_CTL should be called by application level | |
118bdd70 | 624 | drivers before and after mode setting, since on many devices, the |
a78f6787 | 625 | vertical blank counter is reset at that time. Internally, |
2d2ef822 JB |
626 | the DRM snapshots the last vblank count when the ioctl is called |
627 | with the _DRM_PRE_MODESET command so that the counter won't go | |
628 | backwards (which is dealt with when _DRM_POST_MODESET is used). | |
629 | </para> | |
630 | <para> | |
631 | To support the functions above, the DRM core provides several | |
632 | helper functions for tracking vertical blank counters, and | |
633 | requires drivers to provide several callbacks: | |
634 | get_vblank_counter(), enable_vblank() and disable_vblank(). The | |
635 | core uses get_vblank_counter() to keep the counter accurate | |
636 | across interrupt disable periods. It should return the current | |
637 | vertical blank event count, which is often tracked in a device | |
638 | register. The enable and disable vblank callbacks should enable | |
639 | and disable vertical blank interrupts, respectively. In the | |
640 | absence of DRM clients waiting on vblank events, the core DRM | |
a78f6787 MW |
641 | code uses the disable_vblank() function to disable |
642 | interrupts, which saves power. They are re-enabled again when | |
2d2ef822 JB |
643 | a client calls the vblank wait ioctl above. |
644 | </para> | |
645 | <para> | |
54f2cb8f | 646 | A device that doesn't provide a count register may simply use an |
2d2ef822 | 647 | internal atomic counter incremented on every vertical blank |
54f2cb8f MW |
648 | interrupt (and then treat the enable_vblank() and disable_vblank() |
649 | callbacks as no-ops). | |
2d2ef822 JB |
650 | </para> |
651 | </sect1> | |
652 | ||
653 | <sect1> | |
654 | <title>Memory management</title> | |
655 | <para> | |
2c267e9e MW |
656 | The memory manager lies at the heart of many DRM operations; it |
657 | is required to support advanced client features like OpenGL | |
eb2b8d42 | 658 | pbuffers. The DRM currently contains two memory managers: TTM |
2d2ef822 JB |
659 | and GEM. |
660 | </para> | |
661 | ||
662 | <sect2> | |
663 | <title>The Translation Table Manager (TTM)</title> | |
664 | <para> | |
665 | TTM was developed by Tungsten Graphics, primarily by Thomas | |
666 | Hellström, and is intended to be a flexible, high performance | |
667 | graphics memory manager. | |
668 | </para> | |
669 | <para> | |
670 | Drivers wishing to support TTM must fill out a drm_bo_driver | |
671 | structure. | |
672 | </para> | |
673 | <para> | |
674 | TTM design background and information belongs here. | |
675 | </para> | |
676 | </sect2> | |
677 | ||
678 | <sect2> | |
679 | <title>The Graphics Execution Manager (GEM)</title> | |
680 | <para> | |
681 | GEM is an Intel project, authored by Eric Anholt and Keith | |
682 | Packard. It provides simpler interfaces than TTM, and is well | |
683 | suited for UMA devices. | |
684 | </para> | |
685 | <para> | |
686 | GEM-enabled drivers must provide gem_init_object() and | |
687 | gem_free_object() callbacks to support the core memory | |
688 | allocation routines. They should also provide several driver | |
689 | specific ioctls to support command execution, pinning, buffer | |
690 | read & write, mapping, and domain ownership transfers. | |
691 | </para> | |
692 | <para> | |
693 | On a fundamental level, GEM involves several operations: memory | |
694 | allocation and freeing, command execution, and aperture management | |
695 | at command execution time. Buffer object allocation is relatively | |
696 | straightforward and largely provided by Linux's shmem layer, which | |
697 | provides memory to back each object. When mapped into the GTT | |
698 | or used in a command buffer, the backing pages for an object are | |
699 | flushed to memory and marked write combined so as to be coherent | |
700 | with the GPU. Likewise, when the GPU finishes rendering to an object, | |
701 | if the CPU accesses it, it must be made coherent with the CPU's view | |
702 | of memory, usually involving GPU cache flushing of various kinds. | |
703 | This core CPU<->GPU coherency management is provided by the GEM | |
704 | set domain function, which evaluates an object's current domain and | |
705 | performs any necessary flushing or synchronization to put the object | |
706 | into the desired coherency domain (note that the object may be busy, | |
118bdd70 | 707 | i.e. an active render target; in that case, the set domain function |
a78f6787 | 708 | blocks the client and waits for rendering to complete before |
2d2ef822 JB |
709 | performing any necessary flushing operations). |
710 | </para> | |
711 | <para> | |
712 | Perhaps the most important GEM function is providing a command | |
713 | execution interface to clients. Client programs construct command | |
714 | buffers containing references to previously allocated memory objects | |
a78f6787 | 715 | and submit them to GEM. At that point, GEM takes care to bind |
2d2ef822 JB |
716 | all the objects into the GTT, execute the buffer, and provide |
717 | necessary synchronization between clients accessing the same buffers. | |
718 | This often involves evicting some objects from the GTT and re-binding | |
719 | others (a fairly expensive operation), and providing relocation | |
720 | support which hides fixed GTT offsets from clients. Clients must | |
721 | take care not to submit command buffers that reference more objects | |
722 | than can fit in the GTT or GEM will reject them and no rendering | |
723 | will occur. Similarly, if several objects in the buffer require | |
724 | fence registers to be allocated for correct rendering (e.g. 2D blits | |
725 | on pre-965 chips), care must be taken not to require more fence | |
726 | registers than are available to the client. Such resource management | |
727 | should be abstracted from the client in libdrm. | |
728 | </para> | |
729 | </sect2> | |
730 | ||
731 | </sect1> | |
732 | ||
733 | <!-- Output management --> | |
734 | <sect1> | |
735 | <title>Output management</title> | |
736 | <para> | |
737 | At the core of the DRM output management code is a set of | |
005d7f4a | 738 | structures representing CRTCs, encoders, and connectors. |
2d2ef822 JB |
739 | </para> |
740 | <para> | |
741 | A CRTC is an abstraction representing a part of the chip that | |
742 | contains a pointer to a scanout buffer. Therefore, the number | |
743 | of CRTCs available determines how many independent scanout | |
744 | buffers can be active at any given time. The CRTC structure | |
745 | contains several fields to support this: a pointer to some video | |
746 | memory, a display mode, and an (x, y) offset into the video | |
747 | memory to support panning or configurations where one piece of | |
748 | video memory spans multiple CRTCs. | |
749 | </para> | |
750 | <para> | |
751 | An encoder takes pixel data from a CRTC and converts it to a | |
752 | format suitable for any attached connectors. On some devices, | |
753 | it may be possible to have a CRTC send data to more than one | |
754 | encoder. In that case, both encoders would receive data from | |
755 | the same scanout buffer, resulting in a "cloned" display | |
756 | configuration across the connectors attached to each encoder. | |
757 | </para> | |
758 | <para> | |
759 | A connector is the final destination for pixel data on a device, | |
760 | and usually connects directly to an external display device like | |
761 | a monitor or laptop panel. A connector can only be attached to | |
762 | one encoder at a time. The connector is also the structure | |
763 | where information about the attached display is kept, so it | |
764 | contains fields for display data, EDID data, DPMS & | |
765 | connection status, and information about modes supported on the | |
766 | attached displays. | |
767 | </para> | |
768 | <!--!Edrivers/char/drm/drm_crtc.c--> | |
769 | </sect1> | |
770 | ||
771 | <sect1> | |
772 | <title>Framebuffer management</title> | |
773 | <para> | |
774 | In order to set a mode on a given CRTC, encoder and connector | |
775 | configuration, clients need to provide a framebuffer object which | |
a78f6787 | 776 | provides a source of pixels for the CRTC to deliver to the encoder(s) |
2d2ef822 JB |
777 | and ultimately the connector(s) in the configuration. A framebuffer |
778 | is fundamentally a driver specific memory object, made into an opaque | |
779 | handle by the DRM addfb function. Once an fb has been created this | |
780 | way it can be passed to the KMS mode setting routines for use in | |
781 | a configuration. | |
782 | </para> | |
783 | </sect1> | |
784 | ||
785 | <sect1> | |
786 | <title>Command submission & fencing</title> | |
787 | <para> | |
788 | This should cover a few device specific command submission | |
789 | implementations. | |
790 | </para> | |
791 | </sect1> | |
792 | ||
793 | <sect1> | |
794 | <title>Suspend/resume</title> | |
795 | <para> | |
796 | The DRM core provides some suspend/resume code, but drivers | |
797 | wanting full suspend/resume support should provide save() and | |
a78f6787 | 798 | restore() functions. These are called at suspend, |
2d2ef822 JB |
799 | hibernate, or resume time, and should perform any state save or |
800 | restore required by your device across suspend or hibernate | |
801 | states. | |
802 | </para> | |
803 | </sect1> | |
804 | ||
805 | <sect1> | |
806 | <title>DMA services</title> | |
807 | <para> | |
808 | This should cover how DMA mapping etc. is supported by the core. | |
809 | These functions are deprecated and should not be used. | |
810 | </para> | |
811 | </sect1> | |
812 | </chapter> | |
813 | ||
814 | <!-- External interfaces --> | |
815 | ||
816 | <chapter id="drmExternals"> | |
817 | <title>Userland interfaces</title> | |
818 | <para> | |
819 | The DRM core exports several interfaces to applications, | |
820 | generally intended to be used through corresponding libdrm | |
821 | wrapper functions. In addition, drivers export device specific | |
822 | interfaces for use by userspace drivers & device aware | |
823 | applications through ioctls and sysfs files. | |
824 | </para> | |
825 | <para> | |
826 | External interfaces include: memory mapping, context management, | |
827 | DMA operations, AGP management, vblank control, fence | |
828 | management, memory management, and output management. | |
829 | </para> | |
830 | <para> | |
831 | Cover generic ioctls and sysfs layout here. Only need high | |
a78f6787 | 832 | level info, since man pages should cover the rest. |
2d2ef822 JB |
833 | </para> |
834 | </chapter> | |
835 | ||
836 | <!-- API reference --> | |
837 | ||
838 | <appendix id="drmDriverApi"> | |
839 | <title>DRM Driver API</title> | |
840 | <para> | |
841 | Include auto-generated API reference here (need to reference it | |
842 | from paragraphs above too). | |
843 | </para> | |
844 | </appendix> | |
845 | ||
846 | </book> |