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 | |
35 | drivers in the kernel can make use of DRM functions to make | |
36 | tasks like memory management, interrupt handling and DMA easier, | |
37 | and provide a uniform interface to applications. | |
38 | </para> | |
39 | <para> | |
40 | A note on versions: this guide covers features found in the DRM | |
41 | tree, including the TTM memory manager, output configuration and | |
42 | mode setting, and the new vblank internals, in addition to all | |
43 | the regular features found in current kernels. | |
44 | </para> | |
45 | <para> | |
46 | [Insert diagram of typical DRM stack here] | |
47 | </para> | |
48 | </chapter> | |
49 | ||
50 | <!-- Internals --> | |
51 | ||
52 | <chapter id="drmInternals"> | |
53 | <title>DRM Internals</title> | |
54 | <para> | |
55 | This chapter documents DRM internals relevant to driver authors | |
56 | and developers working to add support for the latest features to | |
57 | existing drivers. | |
58 | </para> | |
59 | <para> | |
60 | First, we'll go over some typical driver initialization | |
61 | requirements, like setting up command buffers, creating an | |
62 | initial output configuration, and initializing core services. | |
63 | Subsequent sections will cover core internals in more detail, | |
64 | providing implementation notes and examples. | |
65 | </para> | |
66 | <para> | |
67 | The DRM layer provides several services to graphics drivers, | |
68 | many of them driven by the application interfaces it provides | |
69 | through libdrm, the library that wraps most of the DRM ioctls. | |
70 | These include vblank event handling, memory | |
71 | management, output management, framebuffer management, command | |
72 | submission & fencing, suspend/resume support, and DMA | |
73 | services. | |
74 | </para> | |
75 | <para> | |
76 | The core of every DRM driver is struct drm_device. Drivers | |
77 | will typically statically initialize a drm_device structure, | |
78 | then pass it to drm_init() at load time. | |
79 | </para> | |
80 | ||
81 | <!-- Internals: driver init --> | |
82 | ||
83 | <sect1> | |
84 | <title>Driver initialization</title> | |
85 | <para> | |
86 | Before calling the DRM initialization routines, the driver must | |
87 | first create and fill out a struct drm_device structure. | |
88 | </para> | |
89 | <programlisting> | |
90 | static struct drm_driver driver = { | |
91 | /* don't use mtrr's here, the Xserver or user space app should | |
92 | * deal with them for intel hardware. | |
93 | */ | |
94 | .driver_features = | |
95 | DRIVER_USE_AGP | DRIVER_REQUIRE_AGP | | |
96 | DRIVER_HAVE_IRQ | DRIVER_IRQ_SHARED | DRIVER_MODESET, | |
97 | .load = i915_driver_load, | |
98 | .unload = i915_driver_unload, | |
99 | .firstopen = i915_driver_firstopen, | |
100 | .lastclose = i915_driver_lastclose, | |
101 | .preclose = i915_driver_preclose, | |
102 | .save = i915_save, | |
103 | .restore = i915_restore, | |
104 | .device_is_agp = i915_driver_device_is_agp, | |
105 | .get_vblank_counter = i915_get_vblank_counter, | |
106 | .enable_vblank = i915_enable_vblank, | |
107 | .disable_vblank = i915_disable_vblank, | |
108 | .irq_preinstall = i915_driver_irq_preinstall, | |
109 | .irq_postinstall = i915_driver_irq_postinstall, | |
110 | .irq_uninstall = i915_driver_irq_uninstall, | |
111 | .irq_handler = i915_driver_irq_handler, | |
112 | .reclaim_buffers = drm_core_reclaim_buffers, | |
113 | .get_map_ofs = drm_core_get_map_ofs, | |
114 | .get_reg_ofs = drm_core_get_reg_ofs, | |
115 | .fb_probe = intelfb_probe, | |
116 | .fb_remove = intelfb_remove, | |
117 | .fb_resize = intelfb_resize, | |
118 | .master_create = i915_master_create, | |
119 | .master_destroy = i915_master_destroy, | |
120 | #if defined(CONFIG_DEBUG_FS) | |
121 | .debugfs_init = i915_debugfs_init, | |
122 | .debugfs_cleanup = i915_debugfs_cleanup, | |
123 | #endif | |
124 | .gem_init_object = i915_gem_init_object, | |
125 | .gem_free_object = i915_gem_free_object, | |
126 | .gem_vm_ops = &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 | |
157 | sets several flags indicating what core features it supports. | |
158 | We'll 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 a IRQ | |
207 | handler, DRIVER_IRQ_SHARED indicates whether the device & | |
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 | If the driver queues DMA requests and completes them | |
218 | asynchronously, this flag should be set. 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 we'll see, 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> | |
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> | |
272 | Note that the tasks performed at driver load time must not | |
273 | conflict with DRM client requirements. For instance, if user | |
274 | level mode setting drivers are in use, it would be problematic | |
275 | to perform output discovery & configuration at load time. | |
276 | Likewise, if pre-memory management aware user level drivers are | |
277 | in use, memory management and command buffer setup may need to | |
278 | be omitted. These requirements are driver specific, and care | |
279 | needs to be taken to keep both old and new applications and | |
280 | libraries working. The i915 driver supports the "modeset" | |
281 | module parameter to control whether advanced features are | |
282 | enabled at load time or in legacy fashion. If compatibility is | |
283 | a concern (e.g. with drivers converted over to the new interfaces | |
284 | from the old ones), care must be taken to prevent incompatible | |
285 | device initialization and control with the currently active | |
286 | userspace drivers. | |
287 | </para> | |
288 | ||
289 | <sect2> | |
290 | <title>Driver private & performance counters</title> | |
291 | <para> | |
292 | The driver private hangs off the main drm_device structure and | |
293 | can be used for tracking various device specific bits of | |
294 | information, like register offsets, command buffer status, | |
295 | register state for suspend/resume, etc. At load time, a | |
296 | driver can simply allocate one and set drm_device.dev_priv | |
297 | appropriately; at unload the driver can free it and set | |
298 | drm_device.dev_priv to NULL. | |
299 | </para> | |
300 | <para> | |
301 | The DRM supports several counters which can be used for rough | |
302 | performance characterization. Note that the DRM stat counter | |
303 | system is not often used by applications, and supporting | |
304 | additional counters is completely optional. | |
305 | </para> | |
306 | <para> | |
307 | These interfaces are deprecated and should not be used. If performance | |
308 | monitoring is desired, the developer should investigate and | |
309 | potentially enhance the kernel perf and tracing infrastructure to export | |
310 | GPU related performance information to performance monitoring | |
311 | tools and applications. | |
312 | </para> | |
313 | </sect2> | |
314 | ||
315 | <sect2> | |
316 | <title>Configuring the device</title> | |
317 | <para> | |
318 | Obviously, device configuration will be device specific. | |
319 | However, there are several common operations: finding a | |
320 | device's PCI resources, mapping them, and potentially setting | |
321 | up an IRQ handler. | |
322 | </para> | |
323 | <para> | |
324 | Finding & mapping resources is fairly straightforward. The | |
325 | DRM wrapper functions, drm_get_resource_start() and | |
326 | drm_get_resource_len() can be used to find BARs on the given | |
327 | drm_device struct. Once those values have been retrieved, the | |
328 | driver load function can call drm_addmap() to create a new | |
329 | mapping for the BAR in question. Note you'll probably want a | |
330 | drm_local_map_t in your driver private structure to track any | |
331 | mappings you create. | |
332 | <!-- !Fdrivers/gpu/drm/drm_bufs.c drm_get_resource_* --> | |
333 | <!-- !Finclude/drm/drmP.h drm_local_map_t --> | |
334 | </para> | |
335 | <para> | |
336 | if compatibility with other operating systems isn't a concern | |
337 | (DRM drivers can run under various BSD variants and OpenSolaris), | |
338 | native Linux calls can be used for the above, e.g. pci_resource_* | |
339 | and iomap*/iounmap. See the Linux device driver book for more | |
340 | info. | |
341 | </para> | |
342 | <para> | |
343 | Once you have a register map, you can use the DRM_READn() and | |
344 | DRM_WRITEn() macros to access the registers on your device, or | |
345 | use driver specific versions to offset into your MMIO space | |
346 | relative to a driver specific base pointer (see I915_READ for | |
347 | example). | |
348 | </para> | |
349 | <para> | |
350 | If your device supports interrupt generation, you may want to | |
351 | setup an interrupt handler at driver load time as well. This | |
352 | is done using the drm_irq_install() function. If your device | |
353 | supports vertical blank interrupts, it should call | |
354 | drm_vblank_init() to initialize the core vblank handling code before | |
355 | enabling interrupts on your device. This ensures the vblank related | |
356 | structures are allocated and allows the core to handle vblank events. | |
357 | </para> | |
358 | <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> | |
359 | <para> | |
360 | Once your interrupt handler is registered (it'll use your | |
361 | drm_driver.irq_handler as the actual interrupt handling | |
362 | function), you can safely enable interrupts on your device, | |
363 | assuming any other state your interrupt handler uses is also | |
364 | initialized. | |
365 | </para> | |
366 | <para> | |
367 | Another task that may be necessary during configuration is | |
368 | mapping the video BIOS. On many devices, the VBIOS describes | |
369 | device configuration, LCD panel timings (if any), and contains | |
370 | flags indicating device state. Mapping the BIOS can be done | |
371 | using the pci_map_rom() call, a convenience function that | |
372 | takes care of mapping the actual ROM, whether it has been | |
373 | shadowed into memory (typically at address 0xc0000) or exists | |
374 | on the PCI device in the ROM BAR. Note that once you've | |
375 | mapped the ROM and extracted any necessary information, be | |
376 | sure to unmap it; on many devices the ROM address decoder is | |
377 | shared with other BARs, so leaving it mapped can cause | |
378 | undesired behavior like hangs or memory corruption. | |
379 | <!--!Fdrivers/pci/rom.c pci_map_rom--> | |
380 | </para> | |
381 | </sect2> | |
382 | ||
383 | <sect2> | |
384 | <title>Memory manager initialization</title> | |
385 | <para> | |
386 | In order to allocate command buffers, cursor memory, scanout | |
387 | buffers, etc., as well as support the latest features provided | |
388 | by packages like Mesa and the X.Org X server, your driver | |
389 | should support a memory manager. | |
390 | </para> | |
391 | <para> | |
392 | If your driver supports memory management (it should!), you'll | |
ce04cc08 | 393 | need to set that up at load time as well. How you initialize |
2d2ef822 JB |
394 | it depends on which memory manager you're using, TTM or GEM. |
395 | </para> | |
396 | <sect3> | |
397 | <title>TTM initialization</title> | |
398 | <para> | |
399 | TTM (for Translation Table Manager) manages video memory and | |
400 | aperture space for graphics devices. TTM supports both UMA devices | |
401 | and devices with dedicated video RAM (VRAM), i.e. most discrete | |
402 | graphics devices. If your device has dedicated RAM, supporting | |
ce04cc08 | 403 | TTM is desirable. TTM also integrates tightly with your |
2d2ef822 JB |
404 | driver specific buffer execution function. See the radeon |
405 | driver for examples. | |
406 | </para> | |
407 | <para> | |
408 | The core TTM structure is the ttm_bo_driver struct. It contains | |
409 | several fields with function pointers for initializing the TTM, | |
410 | allocating and freeing memory, waiting for command completion | |
411 | and fence synchronization, and memory migration. See the | |
412 | radeon_ttm.c file for an example of usage. | |
413 | </para> | |
414 | <para> | |
415 | The ttm_global_reference structure is made up of several fields: | |
416 | </para> | |
417 | <programlisting> | |
418 | struct ttm_global_reference { | |
419 | enum ttm_global_types global_type; | |
420 | size_t size; | |
421 | void *object; | |
422 | int (*init) (struct ttm_global_reference *); | |
423 | void (*release) (struct ttm_global_reference *); | |
424 | }; | |
425 | </programlisting> | |
426 | <para> | |
427 | There should be one global reference structure for your memory | |
428 | manager as a whole, and there will be others for each object | |
429 | created by the memory manager at runtime. Your global TTM should | |
430 | have a type of TTM_GLOBAL_TTM_MEM. The size field for the global | |
431 | object should be sizeof(struct ttm_mem_global), and the init and | |
432 | release hooks should point at your driver specific init and | |
433 | release routines, which will probably eventually call | |
434 | ttm_mem_global_init and ttm_mem_global_release respectively. | |
435 | </para> | |
436 | <para> | |
437 | Once your global TTM accounting structure is set up and initialized | |
438 | (done by calling ttm_global_item_ref on the global object you | |
439 | just created), you'll need to create a buffer object TTM to | |
440 | provide a pool for buffer object allocation by clients and the | |
441 | kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, | |
442 | and its size should be sizeof(struct ttm_bo_global). Again, | |
443 | driver specific init and release functions can be provided, | |
444 | likely eventually calling ttm_bo_global_init and | |
445 | ttm_bo_global_release, respectively. Also like the previous | |
446 | object, ttm_global_item_ref is used to create an initial reference | |
ce04cc08 | 447 | count for the TTM, which will call your initialization function. |
2d2ef822 JB |
448 | </para> |
449 | </sect3> | |
450 | <sect3> | |
451 | <title>GEM initialization</title> | |
452 | <para> | |
453 | GEM is an alternative to TTM, designed specifically for UMA | |
454 | devices. It has simpler initialization and execution requirements | |
455 | than TTM, but has no VRAM management capability. Core GEM | |
456 | initialization is comprised of a basic drm_mm_init call to create | |
457 | a GTT DRM MM object, which provides an address space pool for | |
458 | object allocation. In a KMS configuration, the driver will | |
459 | need to allocate and initialize a command ring buffer following | |
460 | basic GEM initialization. Most UMA devices have a so-called | |
461 | "stolen" memory region, which provides space for the initial | |
462 | framebuffer and large, contiguous memory regions required by the | |
463 | device. This space is not typically managed by GEM, and must | |
464 | be initialized separately into its own DRM MM object. | |
465 | </para> | |
466 | <para> | |
467 | Initialization will be driver specific, and will depend on | |
468 | the architecture of the device. In the case of Intel | |
469 | integrated graphics chips like 965GM, GEM initialization can | |
470 | be done by calling the internal GEM init function, | |
471 | i915_gem_do_init(). Since the 965GM is a UMA device | |
472 | (i.e. it doesn't have dedicated VRAM), GEM will manage | |
473 | making regular RAM available for GPU operations. Memory set | |
474 | aside by the BIOS (called "stolen" memory by the i915 | |
475 | driver) will be managed by the DRM memrange allocator; the | |
476 | rest of the aperture will be managed by GEM. | |
477 | <programlisting> | |
478 | /* Basic memrange allocator for stolen space (aka vram) */ | |
479 | drm_memrange_init(&dev_priv->vram, 0, prealloc_size); | |
480 | /* Let GEM Manage from end of prealloc space to end of aperture */ | |
481 | i915_gem_do_init(dev, prealloc_size, agp_size); | |
482 | </programlisting> | |
483 | <!--!Edrivers/char/drm/drm_memrange.c--> | |
484 | </para> | |
485 | <para> | |
486 | Once the memory manager has been set up, we can allocate the | |
487 | command buffer. In the i915 case, this is also done with a | |
488 | GEM function, i915_gem_init_ringbuffer(). | |
489 | </para> | |
490 | </sect3> | |
491 | </sect2> | |
492 | ||
493 | <sect2> | |
494 | <title>Output configuration</title> | |
495 | <para> | |
496 | The final initialization task is output configuration. This involves | |
497 | finding and initializing the CRTCs, encoders and connectors | |
498 | for your device, creating an initial configuration and | |
499 | registering a framebuffer console driver. | |
500 | </para> | |
501 | <sect3> | |
502 | <title>Output discovery and initialization</title> | |
503 | <para> | |
504 | Several core functions exist to create CRTCs, encoders and | |
505 | connectors, namely drm_crtc_init(), drm_connector_init() and | |
506 | drm_encoder_init(), along with several "helper" functions to | |
507 | perform common tasks. | |
508 | </para> | |
509 | <para> | |
510 | Connectors should be registered with sysfs once they've been | |
511 | detected and initialized, using the | |
512 | drm_sysfs_connector_add() function. Likewise, when they're | |
513 | removed from the system, they should be destroyed with | |
514 | drm_sysfs_connector_remove(). | |
515 | </para> | |
516 | <programlisting> | |
517 | <![CDATA[ | |
518 | void intel_crt_init(struct drm_device *dev) | |
519 | { | |
520 | struct drm_connector *connector; | |
521 | struct intel_output *intel_output; | |
522 | ||
523 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
524 | if (!intel_output) | |
525 | return; | |
526 | ||
527 | connector = &intel_output->base; | |
528 | drm_connector_init(dev, &intel_output->base, | |
529 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
530 | ||
531 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
532 | DRM_MODE_ENCODER_DAC); | |
533 | ||
534 | drm_mode_connector_attach_encoder(&intel_output->base, | |
535 | &intel_output->enc); | |
536 | ||
537 | /* Set up the DDC bus. */ | |
538 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
539 | if (!intel_output->ddc_bus) { | |
540 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
541 | "failed.\n"); | |
542 | return; | |
543 | } | |
544 | ||
545 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
546 | connector->interlace_allowed = 0; | |
547 | connector->doublescan_allowed = 0; | |
548 | ||
549 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
550 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
551 | ||
552 | drm_sysfs_connector_add(connector); | |
553 | } | |
554 | ]]> | |
555 | </programlisting> | |
556 | <para> | |
557 | In the example above (again, taken from the i915 driver), a | |
558 | CRT connector and encoder combination is created. A device | |
559 | specific i2c bus is also created, for fetching EDID data and | |
560 | performing monitor detection. Once the process is complete, | |
ce04cc08 | 561 | the new connector is registered with sysfs, to make its |
2d2ef822 JB |
562 | properties available to applications. |
563 | </para> | |
564 | <sect4> | |
565 | <title>Helper functions and core functions</title> | |
566 | <para> | |
567 | Since many PC-class graphics devices have similar display output | |
568 | designs, the DRM provides a set of helper functions to make | |
569 | output management easier. The core helper routines handle | |
570 | encoder re-routing and disabling of unused functions following | |
571 | mode set. Using the helpers is optional, but recommended for | |
572 | devices with PC-style architectures (i.e. a set of display planes | |
573 | for feeding pixels to encoders which are in turn routed to | |
574 | connectors). Devices with more complex requirements needing | |
575 | finer grained management can opt to use the core callbacks | |
576 | directly. | |
577 | </para> | |
578 | <para> | |
579 | [Insert typical diagram here.] [Insert OMAP style config here.] | |
580 | </para> | |
581 | </sect4> | |
582 | <para> | |
583 | For each encoder, CRTC and connector, several functions must | |
584 | be provided, depending on the object type. Encoder objects | |
ce04cc08 | 585 | need to provide a DPMS (basically on/off) function, mode fixup |
2d2ef822 JB |
586 | (for converting requested modes into native hardware timings), |
587 | and prepare, set and commit functions for use by the core DRM | |
588 | helper functions. Connector helpers need to provide mode fetch and | |
589 | validity functions as well as an encoder matching function for | |
ce04cc08 | 590 | returning an ideal encoder for a given connector. The core |
2d2ef822 JB |
591 | connector functions include a DPMS callback, (deprecated) |
592 | save/restore routines, detection, mode probing, property handling, | |
593 | and cleanup functions. | |
594 | </para> | |
595 | <!--!Edrivers/char/drm/drm_crtc.h--> | |
596 | <!--!Edrivers/char/drm/drm_crtc.c--> | |
597 | <!--!Edrivers/char/drm/drm_crtc_helper.c--> | |
598 | </sect3> | |
599 | </sect2> | |
600 | </sect1> | |
601 | ||
602 | <!-- Internals: vblank handling --> | |
603 | ||
604 | <sect1> | |
605 | <title>VBlank event handling</title> | |
606 | <para> | |
607 | The DRM core exposes two vertical blank related ioctls: | |
608 | DRM_IOCTL_WAIT_VBLANK and DRM_IOCTL_MODESET_CTL. | |
609 | <!--!Edrivers/char/drm/drm_irq.c--> | |
610 | </para> | |
611 | <para> | |
612 | DRM_IOCTL_WAIT_VBLANK takes a struct drm_wait_vblank structure | |
613 | as its argument, and is used to block or request a signal when a | |
614 | specified vblank event occurs. | |
615 | </para> | |
616 | <para> | |
617 | DRM_IOCTL_MODESET_CTL should be called by application level | |
618 | drivers before and after mode setting, since on many devices the | |
619 | vertical blank counter will be reset at that time. Internally, | |
620 | the DRM snapshots the last vblank count when the ioctl is called | |
621 | with the _DRM_PRE_MODESET command so that the counter won't go | |
622 | backwards (which is dealt with when _DRM_POST_MODESET is used). | |
623 | </para> | |
624 | <para> | |
625 | To support the functions above, the DRM core provides several | |
626 | helper functions for tracking vertical blank counters, and | |
627 | requires drivers to provide several callbacks: | |
628 | get_vblank_counter(), enable_vblank() and disable_vblank(). The | |
629 | core uses get_vblank_counter() to keep the counter accurate | |
630 | across interrupt disable periods. It should return the current | |
631 | vertical blank event count, which is often tracked in a device | |
632 | register. The enable and disable vblank callbacks should enable | |
633 | and disable vertical blank interrupts, respectively. In the | |
634 | absence of DRM clients waiting on vblank events, the core DRM | |
635 | code will use the disable_vblank() function to disable | |
636 | interrupts, which saves power. They'll be re-enabled again when | |
637 | a client calls the vblank wait ioctl above. | |
638 | </para> | |
639 | <para> | |
640 | Devices that don't provide a count register can simply use an | |
641 | internal atomic counter incremented on every vertical blank | |
642 | interrupt, and can make their enable and disable vblank | |
643 | functions into no-ops. | |
644 | </para> | |
645 | </sect1> | |
646 | ||
647 | <sect1> | |
648 | <title>Memory management</title> | |
649 | <para> | |
650 | The memory manager lies at the heart of many DRM operations, and | |
651 | is also required to support advanced client features like OpenGL | |
652 | pbuffers. The DRM currently contains two memory managers, TTM | |
653 | and GEM. | |
654 | </para> | |
655 | ||
656 | <sect2> | |
657 | <title>The Translation Table Manager (TTM)</title> | |
658 | <para> | |
659 | TTM was developed by Tungsten Graphics, primarily by Thomas | |
660 | Hellström, and is intended to be a flexible, high performance | |
661 | graphics memory manager. | |
662 | </para> | |
663 | <para> | |
664 | Drivers wishing to support TTM must fill out a drm_bo_driver | |
665 | structure. | |
666 | </para> | |
667 | <para> | |
668 | TTM design background and information belongs here. | |
669 | </para> | |
670 | </sect2> | |
671 | ||
672 | <sect2> | |
673 | <title>The Graphics Execution Manager (GEM)</title> | |
674 | <para> | |
675 | GEM is an Intel project, authored by Eric Anholt and Keith | |
676 | Packard. It provides simpler interfaces than TTM, and is well | |
677 | suited for UMA devices. | |
678 | </para> | |
679 | <para> | |
680 | GEM-enabled drivers must provide gem_init_object() and | |
681 | gem_free_object() callbacks to support the core memory | |
682 | allocation routines. They should also provide several driver | |
683 | specific ioctls to support command execution, pinning, buffer | |
684 | read & write, mapping, and domain ownership transfers. | |
685 | </para> | |
686 | <para> | |
687 | On a fundamental level, GEM involves several operations: memory | |
688 | allocation and freeing, command execution, and aperture management | |
689 | at command execution time. Buffer object allocation is relatively | |
690 | straightforward and largely provided by Linux's shmem layer, which | |
691 | provides memory to back each object. When mapped into the GTT | |
692 | or used in a command buffer, the backing pages for an object are | |
693 | flushed to memory and marked write combined so as to be coherent | |
694 | with the GPU. Likewise, when the GPU finishes rendering to an object, | |
695 | if the CPU accesses it, it must be made coherent with the CPU's view | |
696 | of memory, usually involving GPU cache flushing of various kinds. | |
697 | This core CPU<->GPU coherency management is provided by the GEM | |
698 | set domain function, which evaluates an object's current domain and | |
699 | performs any necessary flushing or synchronization to put the object | |
700 | into the desired coherency domain (note that the object may be busy, | |
701 | i.e. an active render target; in that case the set domain function | |
702 | will block the client and wait for rendering to complete before | |
703 | performing any necessary flushing operations). | |
704 | </para> | |
705 | <para> | |
706 | Perhaps the most important GEM function is providing a command | |
707 | execution interface to clients. Client programs construct command | |
708 | buffers containing references to previously allocated memory objects | |
709 | and submit them to GEM. At that point, GEM will take care to bind | |
710 | all the objects into the GTT, execute the buffer, and provide | |
711 | necessary synchronization between clients accessing the same buffers. | |
712 | This often involves evicting some objects from the GTT and re-binding | |
713 | others (a fairly expensive operation), and providing relocation | |
714 | support which hides fixed GTT offsets from clients. Clients must | |
715 | take care not to submit command buffers that reference more objects | |
716 | than can fit in the GTT or GEM will reject them and no rendering | |
717 | will occur. Similarly, if several objects in the buffer require | |
718 | fence registers to be allocated for correct rendering (e.g. 2D blits | |
719 | on pre-965 chips), care must be taken not to require more fence | |
720 | registers than are available to the client. Such resource management | |
721 | should be abstracted from the client in libdrm. | |
722 | </para> | |
723 | </sect2> | |
724 | ||
725 | </sect1> | |
726 | ||
727 | <!-- Output management --> | |
728 | <sect1> | |
729 | <title>Output management</title> | |
730 | <para> | |
731 | At the core of the DRM output management code is a set of | |
732 | structures representing CRTCs, encoders and connectors. | |
733 | </para> | |
734 | <para> | |
735 | A CRTC is an abstraction representing a part of the chip that | |
736 | contains a pointer to a scanout buffer. Therefore, the number | |
737 | of CRTCs available determines how many independent scanout | |
738 | buffers can be active at any given time. The CRTC structure | |
739 | contains several fields to support this: a pointer to some video | |
740 | memory, a display mode, and an (x, y) offset into the video | |
741 | memory to support panning or configurations where one piece of | |
742 | video memory spans multiple CRTCs. | |
743 | </para> | |
744 | <para> | |
745 | An encoder takes pixel data from a CRTC and converts it to a | |
746 | format suitable for any attached connectors. On some devices, | |
747 | it may be possible to have a CRTC send data to more than one | |
748 | encoder. In that case, both encoders would receive data from | |
749 | the same scanout buffer, resulting in a "cloned" display | |
750 | configuration across the connectors attached to each encoder. | |
751 | </para> | |
752 | <para> | |
753 | A connector is the final destination for pixel data on a device, | |
754 | and usually connects directly to an external display device like | |
755 | a monitor or laptop panel. A connector can only be attached to | |
756 | one encoder at a time. The connector is also the structure | |
757 | where information about the attached display is kept, so it | |
758 | contains fields for display data, EDID data, DPMS & | |
759 | connection status, and information about modes supported on the | |
760 | attached displays. | |
761 | </para> | |
762 | <!--!Edrivers/char/drm/drm_crtc.c--> | |
763 | </sect1> | |
764 | ||
765 | <sect1> | |
766 | <title>Framebuffer management</title> | |
767 | <para> | |
768 | In order to set a mode on a given CRTC, encoder and connector | |
769 | configuration, clients need to provide a framebuffer object which | |
770 | will provide a source of pixels for the CRTC to deliver to the encoder(s) | |
771 | and ultimately the connector(s) in the configuration. A framebuffer | |
772 | is fundamentally a driver specific memory object, made into an opaque | |
773 | handle by the DRM addfb function. Once an fb has been created this | |
774 | way it can be passed to the KMS mode setting routines for use in | |
775 | a configuration. | |
776 | </para> | |
777 | </sect1> | |
778 | ||
779 | <sect1> | |
780 | <title>Command submission & fencing</title> | |
781 | <para> | |
782 | This should cover a few device specific command submission | |
783 | implementations. | |
784 | </para> | |
785 | </sect1> | |
786 | ||
787 | <sect1> | |
788 | <title>Suspend/resume</title> | |
789 | <para> | |
790 | The DRM core provides some suspend/resume code, but drivers | |
791 | wanting full suspend/resume support should provide save() and | |
792 | restore() functions. These will be called at suspend, | |
793 | hibernate, or resume time, and should perform any state save or | |
794 | restore required by your device across suspend or hibernate | |
795 | states. | |
796 | </para> | |
797 | </sect1> | |
798 | ||
799 | <sect1> | |
800 | <title>DMA services</title> | |
801 | <para> | |
802 | This should cover how DMA mapping etc. is supported by the core. | |
803 | These functions are deprecated and should not be used. | |
804 | </para> | |
805 | </sect1> | |
806 | </chapter> | |
807 | ||
808 | <!-- External interfaces --> | |
809 | ||
810 | <chapter id="drmExternals"> | |
811 | <title>Userland interfaces</title> | |
812 | <para> | |
813 | The DRM core exports several interfaces to applications, | |
814 | generally intended to be used through corresponding libdrm | |
815 | wrapper functions. In addition, drivers export device specific | |
816 | interfaces for use by userspace drivers & device aware | |
817 | applications through ioctls and sysfs files. | |
818 | </para> | |
819 | <para> | |
820 | External interfaces include: memory mapping, context management, | |
821 | DMA operations, AGP management, vblank control, fence | |
822 | management, memory management, and output management. | |
823 | </para> | |
824 | <para> | |
825 | Cover generic ioctls and sysfs layout here. Only need high | |
826 | level info, since man pages will cover the rest. | |
827 | </para> | |
828 | </chapter> | |
829 | ||
830 | <!-- API reference --> | |
831 | ||
832 | <appendix id="drmDriverApi"> | |
833 | <title>DRM Driver API</title> | |
834 | <para> | |
835 | Include auto-generated API reference here (need to reference it | |
836 | from paragraphs above too). | |
837 | </para> | |
838 | </appendix> | |
839 | ||
840 | </book> |