diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2011-11-08 21:33:11 -0500 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2011-11-08 21:33:11 -0500 |
commit | c8c27c955ac633c0d783ec65f65176c82809f04d (patch) | |
tree | c20837439bd8f12dad4ba3b0ebe77cedf0cfff29 /Documentation/DocBook | |
parent | 98393b8ff2ca98b5b984e73a291b81b326e25184 (diff) | |
parent | 5c24d8b2bf99ee93049a6f8154ef9cd7897a6e36 (diff) |
Merge branch 'docs-move' of git://git.kernel.org/pub/scm/linux/kernel/git/rdunlap/linux-docs
* 'docs-move' of git://git.kernel.org/pub/scm/linux/kernel/git/rdunlap/linux-docs: (45 commits)
DocBook/drm: Clean up a todo-note
DocBook/drm: `device aware' -> `device-aware'
DocBook/drm: `(device|driver) specific' -> `(device|driver)-specific'
DocBook/drm: Clean up the paragraph on framebuffer objects
DocBook/drm: Use `; otherwise,'
DocBook/drm: Better flow with `, and then'
DocBook/drm: Refer to the domain-setting function as a device-specific ioctl
DocBook/drm: Improve flow of GPU/CPU coherence sentence
DocBook/drm: Use an <itemizelist> for fundamental GEM operations
DocBook/drm: Insert a comma
DocBook/drm: Use a <variablelist> for vblank ioctls
DocBook/drm: Use an itemizedlist for what an encoder needs to provide
DocBook/drm: Insert `the' for readability, and change `set' to `setting'
DocBook/drm: Remove extraneous commas
DocBook/drm: Use a colon
DocBook/drm: Clarify `final initialization' via better formatting
DocBook/drm: Remove redundancy
DocBook/drm: Insert `it' for smooth reading
DocBook/drm: The word `so-called'; I do not think it connotes what you think it connotes
DocBook/drm: Use a singular subject for grammatical cleanliness
...
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/drm.tmpl | 308 |
1 files changed, 168 insertions, 140 deletions
diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index c27915893974..196b8b9dba11 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl | |||
@@ -32,7 +32,7 @@ | |||
32 | The Linux DRM layer contains code intended to support the needs | 32 | The Linux DRM layer contains code intended to support the needs |
33 | of complex graphics devices, usually containing programmable | 33 | of complex graphics devices, usually containing programmable |
34 | pipelines well suited to 3D graphics acceleration. Graphics | 34 | pipelines well suited to 3D graphics acceleration. Graphics |
35 | drivers in the kernel can make use of DRM functions to make | 35 | drivers in the kernel may make use of DRM functions to make |
36 | tasks like memory management, interrupt handling and DMA easier, | 36 | tasks like memory management, interrupt handling and DMA easier, |
37 | and provide a uniform interface to applications. | 37 | and provide a uniform interface to applications. |
38 | </para> | 38 | </para> |
@@ -57,10 +57,10 @@ | |||
57 | existing drivers. | 57 | existing drivers. |
58 | </para> | 58 | </para> |
59 | <para> | 59 | <para> |
60 | First, we'll go over some typical driver initialization | 60 | First, we go over some typical driver initialization |
61 | requirements, like setting up command buffers, creating an | 61 | requirements, like setting up command buffers, creating an |
62 | initial output configuration, and initializing core services. | 62 | initial output configuration, and initializing core services. |
63 | Subsequent sections will cover core internals in more detail, | 63 | Subsequent sections cover core internals in more detail, |
64 | providing implementation notes and examples. | 64 | providing implementation notes and examples. |
65 | </para> | 65 | </para> |
66 | <para> | 66 | <para> |
@@ -74,7 +74,7 @@ | |||
74 | </para> | 74 | </para> |
75 | <para> | 75 | <para> |
76 | The core of every DRM driver is struct drm_driver. Drivers | 76 | The core of every DRM driver is struct drm_driver. Drivers |
77 | will typically statically initialize a drm_driver structure, | 77 | typically statically initialize a drm_driver structure, |
78 | then pass it to drm_init() at load time. | 78 | then pass it to drm_init() at load time. |
79 | </para> | 79 | </para> |
80 | 80 | ||
@@ -88,8 +88,8 @@ | |||
88 | </para> | 88 | </para> |
89 | <programlisting> | 89 | <programlisting> |
90 | static struct drm_driver driver = { | 90 | static struct drm_driver driver = { |
91 | /* don't use mtrr's here, the Xserver or user space app should | 91 | /* Don't use MTRRs here; the Xserver or userspace app should |
92 | * deal with them for intel hardware. | 92 | * deal with them for Intel hardware. |
93 | */ | 93 | */ |
94 | .driver_features = | 94 | .driver_features = |
95 | DRIVER_USE_AGP | DRIVER_REQUIRE_AGP | | 95 | DRIVER_USE_AGP | DRIVER_REQUIRE_AGP | |
@@ -154,8 +154,8 @@ | |||
154 | </programlisting> | 154 | </programlisting> |
155 | <para> | 155 | <para> |
156 | In the example above, taken from the i915 DRM driver, the driver | 156 | In the example above, taken from the i915 DRM driver, the driver |
157 | sets several flags indicating what core features it supports. | 157 | sets several flags indicating what core features it supports; |
158 | We'll go over the individual callbacks in later sections. Since | 158 | we go over the individual callbacks in later sections. Since |
159 | flags indicate which features your driver supports to the DRM | 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, | 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, | 161 | like DRIVER_MODESET can be set later based on user supplied parameters, |
@@ -203,8 +203,8 @@ | |||
203 | <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> | 203 | <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> |
204 | <listitem> | 204 | <listitem> |
205 | <para> | 205 | <para> |
206 | DRIVER_HAVE_IRQ indicates whether the driver has a IRQ | 206 | DRIVER_HAVE_IRQ indicates whether the driver has an IRQ |
207 | handler, DRIVER_IRQ_SHARED indicates whether the device & | 207 | handler. DRIVER_IRQ_SHARED indicates whether the device & |
208 | handler support shared IRQs (note that this is required of | 208 | handler support shared IRQs (note that this is required of |
209 | PCI drivers). | 209 | PCI drivers). |
210 | </para> | 210 | </para> |
@@ -214,8 +214,8 @@ | |||
214 | <term>DRIVER_DMA_QUEUE</term> | 214 | <term>DRIVER_DMA_QUEUE</term> |
215 | <listitem> | 215 | <listitem> |
216 | <para> | 216 | <para> |
217 | If the driver queues DMA requests and completes them | 217 | Should be set if the driver queues DMA requests and completes them |
218 | asynchronously, this flag should be set. Deprecated. | 218 | asynchronously. Deprecated. |
219 | </para> | 219 | </para> |
220 | </listitem> | 220 | </listitem> |
221 | </varlistentry> | 221 | </varlistentry> |
@@ -238,7 +238,7 @@ | |||
238 | </variablelist> | 238 | </variablelist> |
239 | <para> | 239 | <para> |
240 | In this specific case, the driver requires AGP and supports | 240 | In this specific case, the driver requires AGP and supports |
241 | IRQs. DMA, as we'll see, is handled by device specific ioctls | 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 | 242 | in this case. It also supports the kernel mode setting APIs, though |
243 | unlike in the actual i915 driver source, this example unconditionally | 243 | unlike in the actual i915 driver source, this example unconditionally |
244 | exports KMS capability. | 244 | exports KMS capability. |
@@ -269,36 +269,34 @@ | |||
269 | initial output configuration. | 269 | initial output configuration. |
270 | </para> | 270 | </para> |
271 | <para> | 271 | <para> |
272 | Note that the tasks performed at driver load time must not | 272 | If compatibility is a concern (e.g. with drivers converted over |
273 | conflict with DRM client requirements. For instance, if user | 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 | ||
274 | level mode setting drivers are in use, it would be problematic | 276 | level mode setting drivers are in use, it would be problematic |
275 | to perform output discovery & configuration at load time. | 277 | to perform output discovery & configuration at load time. |
276 | Likewise, if pre-memory management aware user level drivers are | 278 | Likewise, if user-level drivers unaware of memory management are |
277 | in use, memory management and command buffer setup may need to | 279 | in use, memory management and command buffer setup may need to |
278 | be omitted. These requirements are driver specific, and care | 280 | be omitted. These requirements are driver-specific, and care |
279 | needs to be taken to keep both old and new applications and | 281 | needs to be taken to keep both old and new applications and |
280 | libraries working. The i915 driver supports the "modeset" | 282 | libraries working. The i915 driver supports the "modeset" |
281 | module parameter to control whether advanced features are | 283 | module parameter to control whether advanced features are |
282 | enabled at load time or in legacy fashion. If compatibility is | 284 | enabled at load time or in legacy fashion. |
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> | 285 | </para> |
288 | 286 | ||
289 | <sect2> | 287 | <sect2> |
290 | <title>Driver private & performance counters</title> | 288 | <title>Driver private & performance counters</title> |
291 | <para> | 289 | <para> |
292 | The driver private hangs off the main drm_device structure and | 290 | The driver private hangs off the main drm_device structure and |
293 | can be used for tracking various device specific bits of | 291 | can be used for tracking various device-specific bits of |
294 | information, like register offsets, command buffer status, | 292 | information, like register offsets, command buffer status, |
295 | register state for suspend/resume, etc. At load time, a | 293 | register state for suspend/resume, etc. At load time, a |
296 | driver can simply allocate one and set drm_device.dev_priv | 294 | driver may simply allocate one and set drm_device.dev_priv |
297 | appropriately; at unload the driver can free it and set | 295 | appropriately; it should be freed and drm_device.dev_priv set |
298 | drm_device.dev_priv to NULL. | 296 | to NULL when the driver is unloaded. |
299 | </para> | 297 | </para> |
300 | <para> | 298 | <para> |
301 | The DRM supports several counters which can be used for rough | 299 | The DRM supports several counters which may be used for rough |
302 | performance characterization. Note that the DRM stat counter | 300 | performance characterization. Note that the DRM stat counter |
303 | system is not often used by applications, and supporting | 301 | system is not often used by applications, and supporting |
304 | additional counters is completely optional. | 302 | additional counters is completely optional. |
@@ -307,15 +305,15 @@ | |||
307 | These interfaces are deprecated and should not be used. If performance | 305 | These interfaces are deprecated and should not be used. If performance |
308 | monitoring is desired, the developer should investigate and | 306 | monitoring is desired, the developer should investigate and |
309 | potentially enhance the kernel perf and tracing infrastructure to export | 307 | potentially enhance the kernel perf and tracing infrastructure to export |
310 | GPU related performance information to performance monitoring | 308 | GPU related performance information for consumption by performance |
311 | tools and applications. | 309 | monitoring tools and applications. |
312 | </para> | 310 | </para> |
313 | </sect2> | 311 | </sect2> |
314 | 312 | ||
315 | <sect2> | 313 | <sect2> |
316 | <title>Configuring the device</title> | 314 | <title>Configuring the device</title> |
317 | <para> | 315 | <para> |
318 | Obviously, device configuration will be device specific. | 316 | Obviously, device configuration is device-specific. |
319 | However, there are several common operations: finding a | 317 | However, there are several common operations: finding a |
320 | device's PCI resources, mapping them, and potentially setting | 318 | device's PCI resources, mapping them, and potentially setting |
321 | up an IRQ handler. | 319 | up an IRQ handler. |
@@ -323,10 +321,10 @@ | |||
323 | <para> | 321 | <para> |
324 | Finding & mapping resources is fairly straightforward. The | 322 | Finding & mapping resources is fairly straightforward. The |
325 | DRM wrapper functions, drm_get_resource_start() and | 323 | DRM wrapper functions, drm_get_resource_start() and |
326 | drm_get_resource_len() can be used to find BARs on the given | 324 | drm_get_resource_len(), may be used to find BARs on the given |
327 | drm_device struct. Once those values have been retrieved, the | 325 | drm_device struct. Once those values have been retrieved, the |
328 | driver load function can call drm_addmap() to create a new | 326 | driver load function can call drm_addmap() to create a new |
329 | mapping for the BAR in question. Note you'll probably want a | 327 | mapping for the BAR in question. Note that you probably want a |
330 | drm_local_map_t in your driver private structure to track any | 328 | drm_local_map_t in your driver private structure to track any |
331 | mappings you create. | 329 | mappings you create. |
332 | <!-- !Fdrivers/gpu/drm/drm_bufs.c drm_get_resource_* --> | 330 | <!-- !Fdrivers/gpu/drm/drm_bufs.c drm_get_resource_* --> |
@@ -335,20 +333,20 @@ | |||
335 | <para> | 333 | <para> |
336 | if compatibility with other operating systems isn't a concern | 334 | if compatibility with other operating systems isn't a concern |
337 | (DRM drivers can run under various BSD variants and OpenSolaris), | 335 | (DRM drivers can run under various BSD variants and OpenSolaris), |
338 | native Linux calls can be used for the above, e.g. pci_resource_* | 336 | native Linux calls may be used for the above, e.g. pci_resource_* |
339 | and iomap*/iounmap. See the Linux device driver book for more | 337 | and iomap*/iounmap. See the Linux device driver book for more |
340 | info. | 338 | info. |
341 | </para> | 339 | </para> |
342 | <para> | 340 | <para> |
343 | Once you have a register map, you can use the DRM_READn() and | 341 | Once you have a register map, you may use the DRM_READn() and |
344 | DRM_WRITEn() macros to access the registers on your device, or | 342 | DRM_WRITEn() macros to access the registers on your device, or |
345 | use driver specific versions to offset into your MMIO space | 343 | use driver-specific versions to offset into your MMIO space |
346 | relative to a driver specific base pointer (see I915_READ for | 344 | relative to a driver-specific base pointer (see I915_READ for |
347 | example). | 345 | an example). |
348 | </para> | 346 | </para> |
349 | <para> | 347 | <para> |
350 | If your device supports interrupt generation, you may want to | 348 | If your device supports interrupt generation, you may want to |
351 | setup an interrupt handler at driver load time as well. This | 349 | set up an interrupt handler when the driver is loaded. This |
352 | is done using the drm_irq_install() function. If your device | 350 | is done using the drm_irq_install() function. If your device |
353 | supports vertical blank interrupts, it should call | 351 | supports vertical blank interrupts, it should call |
354 | drm_vblank_init() to initialize the core vblank handling code before | 352 | drm_vblank_init() to initialize the core vblank handling code before |
@@ -357,7 +355,7 @@ | |||
357 | </para> | 355 | </para> |
358 | <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> | 356 | <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> |
359 | <para> | 357 | <para> |
360 | Once your interrupt handler is registered (it'll use your | 358 | Once your interrupt handler is registered (it uses your |
361 | drm_driver.irq_handler as the actual interrupt handling | 359 | drm_driver.irq_handler as the actual interrupt handling |
362 | function), you can safely enable interrupts on your device, | 360 | function), you can safely enable interrupts on your device, |
363 | assuming any other state your interrupt handler uses is also | 361 | assuming any other state your interrupt handler uses is also |
@@ -371,10 +369,10 @@ | |||
371 | using the pci_map_rom() call, a convenience function that | 369 | using the pci_map_rom() call, a convenience function that |
372 | takes care of mapping the actual ROM, whether it has been | 370 | takes care of mapping the actual ROM, whether it has been |
373 | shadowed into memory (typically at address 0xc0000) or exists | 371 | shadowed into memory (typically at address 0xc0000) or exists |
374 | on the PCI device in the ROM BAR. Note that once you've | 372 | on the PCI device in the ROM BAR. Note that after the ROM |
375 | mapped the ROM and extracted any necessary information, be | 373 | has been mapped and any necessary information has been extracted, |
376 | sure to unmap it; on many devices the ROM address decoder is | 374 | it should be unmapped; on many devices, the ROM address decoder is |
377 | shared with other BARs, so leaving it mapped can cause | 375 | shared with other BARs, so leaving it mapped could cause |
378 | undesired behavior like hangs or memory corruption. | 376 | undesired behavior like hangs or memory corruption. |
379 | <!--!Fdrivers/pci/rom.c pci_map_rom--> | 377 | <!--!Fdrivers/pci/rom.c pci_map_rom--> |
380 | </para> | 378 | </para> |
@@ -389,9 +387,9 @@ | |||
389 | should support a memory manager. | 387 | should support a memory manager. |
390 | </para> | 388 | </para> |
391 | <para> | 389 | <para> |
392 | If your driver supports memory management (it should!), you'll | 390 | If your driver supports memory management (it should!), you |
393 | need to set that up at load time as well. How you initialize | 391 | need to set that up at load time as well. How you initialize |
394 | it depends on which memory manager you're using, TTM or GEM. | 392 | it depends on which memory manager you're using: TTM or GEM. |
395 | </para> | 393 | </para> |
396 | <sect3> | 394 | <sect3> |
397 | <title>TTM initialization</title> | 395 | <title>TTM initialization</title> |
@@ -401,7 +399,7 @@ | |||
401 | and devices with dedicated video RAM (VRAM), i.e. most discrete | 399 | and devices with dedicated video RAM (VRAM), i.e. most discrete |
402 | graphics devices. If your device has dedicated RAM, supporting | 400 | graphics devices. If your device has dedicated RAM, supporting |
403 | TTM is desirable. TTM also integrates tightly with your | 401 | TTM is desirable. TTM also integrates tightly with your |
404 | driver specific buffer execution function. See the radeon | 402 | driver-specific buffer execution function. See the radeon |
405 | driver for examples. | 403 | driver for examples. |
406 | </para> | 404 | </para> |
407 | <para> | 405 | <para> |
@@ -429,21 +427,21 @@ | |||
429 | created by the memory manager at runtime. Your global TTM should | 427 | 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 | 428 | 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 | 429 | object should be sizeof(struct ttm_mem_global), and the init and |
432 | release hooks should point at your driver specific init and | 430 | release hooks should point at your driver-specific init and |
433 | release routines, which will probably eventually call | 431 | release routines, which probably eventually call |
434 | ttm_mem_global_init and ttm_mem_global_release respectively. | 432 | ttm_mem_global_init and ttm_mem_global_release, respectively. |
435 | </para> | 433 | </para> |
436 | <para> | 434 | <para> |
437 | Once your global TTM accounting structure is set up and initialized | 435 | Once your global TTM accounting structure is set up and initialized |
438 | (done by calling ttm_global_item_ref on the global object you | 436 | by calling ttm_global_item_ref() on it, |
439 | just created), you'll need to create a buffer object TTM to | 437 | you need to create a buffer object TTM to |
440 | provide a pool for buffer object allocation by clients and the | 438 | 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, | 439 | 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, | 440 | and its size should be sizeof(struct ttm_bo_global). Again, |
443 | driver specific init and release functions can be provided, | 441 | driver-specific init and release functions may be provided, |
444 | likely eventually calling ttm_bo_global_init and | 442 | likely eventually calling ttm_bo_global_init() and |
445 | ttm_bo_global_release, respectively. Also like the previous | 443 | ttm_bo_global_release(), respectively. Also, like the previous |
446 | object, ttm_global_item_ref is used to create an initial reference | 444 | object, ttm_global_item_ref() is used to create an initial reference |
447 | count for the TTM, which will call your initialization function. | 445 | count for the TTM, which will call your initialization function. |
448 | </para> | 446 | </para> |
449 | </sect3> | 447 | </sect3> |
@@ -453,27 +451,26 @@ | |||
453 | GEM is an alternative to TTM, designed specifically for UMA | 451 | GEM is an alternative to TTM, designed specifically for UMA |
454 | devices. It has simpler initialization and execution requirements | 452 | devices. It has simpler initialization and execution requirements |
455 | than TTM, but has no VRAM management capability. Core GEM | 453 | than TTM, but has no VRAM management capability. Core GEM |
456 | initialization is comprised of a basic drm_mm_init call to create | 454 | is initialized by calling drm_mm_init() to create |
457 | a GTT DRM MM object, which provides an address space pool for | 455 | a GTT DRM MM object, which provides an address space pool for |
458 | object allocation. In a KMS configuration, the driver will | 456 | object allocation. In a KMS configuration, the driver |
459 | need to allocate and initialize a command ring buffer following | 457 | needs to allocate and initialize a command ring buffer following |
460 | basic GEM initialization. Most UMA devices have a so-called | 458 | core GEM initialization. A UMA device usually has what is called a |
461 | "stolen" memory region, which provides space for the initial | 459 | "stolen" memory region, which provides space for the initial |
462 | framebuffer and large, contiguous memory regions required by the | 460 | framebuffer and large, contiguous memory regions required by the |
463 | device. This space is not typically managed by GEM, and must | 461 | device. This space is not typically managed by GEM, and it must |
464 | be initialized separately into its own DRM MM object. | 462 | be initialized separately into its own DRM MM object. |
465 | </para> | 463 | </para> |
466 | <para> | 464 | <para> |
467 | Initialization will be driver specific, and will depend on | 465 | Initialization is driver-specific. In the case of Intel |
468 | the architecture of the device. In the case of Intel | ||
469 | integrated graphics chips like 965GM, GEM initialization can | 466 | integrated graphics chips like 965GM, GEM initialization can |
470 | be done by calling the internal GEM init function, | 467 | be done by calling the internal GEM init function, |
471 | i915_gem_do_init(). Since the 965GM is a UMA device | 468 | i915_gem_do_init(). Since the 965GM is a UMA device |
472 | (i.e. it doesn't have dedicated VRAM), GEM will manage | 469 | (i.e. it doesn't have dedicated VRAM), GEM manages |
473 | making regular RAM available for GPU operations. Memory set | 470 | making regular RAM available for GPU operations. Memory set |
474 | aside by the BIOS (called "stolen" memory by the i915 | 471 | aside by the BIOS (called "stolen" memory by the i915 |
475 | driver) will be managed by the DRM memrange allocator; the | 472 | driver) is managed by the DRM memrange allocator; the |
476 | rest of the aperture will be managed by GEM. | 473 | rest of the aperture is managed by GEM. |
477 | <programlisting> | 474 | <programlisting> |
478 | /* Basic memrange allocator for stolen space (aka vram) */ | 475 | /* Basic memrange allocator for stolen space (aka vram) */ |
479 | drm_memrange_init(&dev_priv->vram, 0, prealloc_size); | 476 | drm_memrange_init(&dev_priv->vram, 0, prealloc_size); |
@@ -483,7 +480,7 @@ | |||
483 | <!--!Edrivers/char/drm/drm_memrange.c--> | 480 | <!--!Edrivers/char/drm/drm_memrange.c--> |
484 | </para> | 481 | </para> |
485 | <para> | 482 | <para> |
486 | Once the memory manager has been set up, we can allocate the | 483 | Once the memory manager has been set up, we may allocate the |
487 | command buffer. In the i915 case, this is also done with a | 484 | command buffer. In the i915 case, this is also done with a |
488 | GEM function, i915_gem_init_ringbuffer(). | 485 | GEM function, i915_gem_init_ringbuffer(). |
489 | </para> | 486 | </para> |
@@ -493,16 +490,25 @@ | |||
493 | <sect2> | 490 | <sect2> |
494 | <title>Output configuration</title> | 491 | <title>Output configuration</title> |
495 | <para> | 492 | <para> |
496 | The final initialization task is output configuration. This involves | 493 | The final initialization task is output configuration. This involves: |
497 | finding and initializing the CRTCs, encoders and connectors | 494 | <itemizedlist> |
498 | for your device, creating an initial configuration and | 495 | <listitem> |
499 | registering a framebuffer console driver. | 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> | ||
500 | </para> | 506 | </para> |
501 | <sect3> | 507 | <sect3> |
502 | <title>Output discovery and initialization</title> | 508 | <title>Output discovery and initialization</title> |
503 | <para> | 509 | <para> |
504 | Several core functions exist to create CRTCs, encoders and | 510 | Several core functions exist to create CRTCs, encoders, and |
505 | connectors, namely drm_crtc_init(), drm_connector_init() and | 511 | connectors, namely: drm_crtc_init(), drm_connector_init(), and |
506 | drm_encoder_init(), along with several "helper" functions to | 512 | drm_encoder_init(), along with several "helper" functions to |
507 | perform common tasks. | 513 | perform common tasks. |
508 | </para> | 514 | </para> |
@@ -555,10 +561,10 @@ void intel_crt_init(struct drm_device *dev) | |||
555 | </programlisting> | 561 | </programlisting> |
556 | <para> | 562 | <para> |
557 | In the example above (again, taken from the i915 driver), a | 563 | In the example above (again, taken from the i915 driver), a |
558 | CRT connector and encoder combination is created. A device | 564 | CRT connector and encoder combination is created. A device-specific |
559 | specific i2c bus is also created, for fetching EDID data and | 565 | i2c bus is also created for fetching EDID data and |
560 | performing monitor detection. Once the process is complete, | 566 | performing monitor detection. Once the process is complete, |
561 | the new connector is registered with sysfs, to make its | 567 | the new connector is registered with sysfs to make its |
562 | properties available to applications. | 568 | properties available to applications. |
563 | </para> | 569 | </para> |
564 | <sect4> | 570 | <sect4> |
@@ -567,12 +573,12 @@ void intel_crt_init(struct drm_device *dev) | |||
567 | Since many PC-class graphics devices have similar display output | 573 | Since many PC-class graphics devices have similar display output |
568 | designs, the DRM provides a set of helper functions to make | 574 | designs, the DRM provides a set of helper functions to make |
569 | output management easier. The core helper routines handle | 575 | output management easier. The core helper routines handle |
570 | encoder re-routing and disabling of unused functions following | 576 | encoder re-routing and the disabling of unused functions following |
571 | mode set. Using the helpers is optional, but recommended for | 577 | mode setting. Using the helpers is optional, but recommended for |
572 | devices with PC-style architectures (i.e. a set of display planes | 578 | devices with PC-style architectures (i.e. a set of display planes |
573 | for feeding pixels to encoders which are in turn routed to | 579 | for feeding pixels to encoders which are in turn routed to |
574 | connectors). Devices with more complex requirements needing | 580 | connectors). Devices with more complex requirements needing |
575 | finer grained management can opt to use the core callbacks | 581 | finer grained management may opt to use the core callbacks |
576 | directly. | 582 | directly. |
577 | </para> | 583 | </para> |
578 | <para> | 584 | <para> |
@@ -580,17 +586,25 @@ void intel_crt_init(struct drm_device *dev) | |||
580 | </para> | 586 | </para> |
581 | </sect4> | 587 | </sect4> |
582 | <para> | 588 | <para> |
583 | For each encoder, CRTC and connector, several functions must | 589 | Each encoder object needs to provide: |
584 | be provided, depending on the object type. Encoder objects | 590 | <itemizedlist> |
585 | need to provide a DPMS (basically on/off) function, mode fixup | 591 | <listitem> |
586 | (for converting requested modes into native hardware timings), | 592 | A DPMS (basically on/off) function. |
587 | and prepare, set and commit functions for use by the core DRM | 593 | </listitem> |
588 | helper functions. Connector helpers need to provide mode fetch and | 594 | <listitem> |
589 | validity functions as well as an encoder matching function for | 595 | A mode-fixup function (for converting requested modes into |
590 | returning an ideal encoder for a given connector. The core | 596 | native hardware timings). |
591 | connector functions include a DPMS callback, (deprecated) | 597 | </listitem> |
592 | save/restore routines, detection, mode probing, property handling, | 598 | <listitem> |
593 | and cleanup functions. | 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. | ||
594 | </para> | 608 | </para> |
595 | <!--!Edrivers/char/drm/drm_crtc.h--> | 609 | <!--!Edrivers/char/drm/drm_crtc.h--> |
596 | <!--!Edrivers/char/drm/drm_crtc.c--> | 610 | <!--!Edrivers/char/drm/drm_crtc.c--> |
@@ -605,23 +619,34 @@ void intel_crt_init(struct drm_device *dev) | |||
605 | <title>VBlank event handling</title> | 619 | <title>VBlank event handling</title> |
606 | <para> | 620 | <para> |
607 | The DRM core exposes two vertical blank related ioctls: | 621 | The DRM core exposes two vertical blank related ioctls: |
608 | DRM_IOCTL_WAIT_VBLANK and DRM_IOCTL_MODESET_CTL. | 622 | <variablelist> |
623 | <varlistentry> | ||
624 | <term>DRM_IOCTL_WAIT_VBLANK</term> | ||
625 | <listitem> | ||
626 | <para> | ||
627 | This takes a struct drm_wait_vblank structure as its argument, | ||
628 | and it is used to block or request a signal when a specified | ||
629 | vblank event occurs. | ||
630 | </para> | ||
631 | </listitem> | ||
632 | </varlistentry> | ||
633 | <varlistentry> | ||
634 | <term>DRM_IOCTL_MODESET_CTL</term> | ||
635 | <listitem> | ||
636 | <para> | ||
637 | This should be called by application level drivers before and | ||
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> | ||
609 | <!--!Edrivers/char/drm/drm_irq.c--> | 647 | <!--!Edrivers/char/drm/drm_irq.c--> |
610 | </para> | 648 | </para> |
611 | <para> | 649 | <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 | 650 | To support the functions above, the DRM core provides several |
626 | helper functions for tracking vertical blank counters, and | 651 | helper functions for tracking vertical blank counters, and |
627 | requires drivers to provide several callbacks: | 652 | requires drivers to provide several callbacks: |
@@ -632,24 +657,24 @@ void intel_crt_init(struct drm_device *dev) | |||
632 | register. The enable and disable vblank callbacks should enable | 657 | register. The enable and disable vblank callbacks should enable |
633 | and disable vertical blank interrupts, respectively. In the | 658 | and disable vertical blank interrupts, respectively. In the |
634 | absence of DRM clients waiting on vblank events, the core DRM | 659 | absence of DRM clients waiting on vblank events, the core DRM |
635 | code will use the disable_vblank() function to disable | 660 | code uses the disable_vblank() function to disable |
636 | interrupts, which saves power. They'll be re-enabled again when | 661 | interrupts, which saves power. They are re-enabled again when |
637 | a client calls the vblank wait ioctl above. | 662 | a client calls the vblank wait ioctl above. |
638 | </para> | 663 | </para> |
639 | <para> | 664 | <para> |
640 | Devices that don't provide a count register can simply use an | 665 | A device that doesn't provide a count register may simply use an |
641 | internal atomic counter incremented on every vertical blank | 666 | internal atomic counter incremented on every vertical blank |
642 | interrupt, and can make their enable and disable vblank | 667 | interrupt (and then treat the enable_vblank() and disable_vblank() |
643 | functions into no-ops. | 668 | callbacks as no-ops). |
644 | </para> | 669 | </para> |
645 | </sect1> | 670 | </sect1> |
646 | 671 | ||
647 | <sect1> | 672 | <sect1> |
648 | <title>Memory management</title> | 673 | <title>Memory management</title> |
649 | <para> | 674 | <para> |
650 | The memory manager lies at the heart of many DRM operations, and | 675 | The memory manager lies at the heart of many DRM operations; it |
651 | is also required to support advanced client features like OpenGL | 676 | is required to support advanced client features like OpenGL |
652 | pbuffers. The DRM currently contains two memory managers, TTM | 677 | pbuffers. The DRM currently contains two memory managers: TTM |
653 | and GEM. | 678 | and GEM. |
654 | </para> | 679 | </para> |
655 | 680 | ||
@@ -679,41 +704,46 @@ void intel_crt_init(struct drm_device *dev) | |||
679 | <para> | 704 | <para> |
680 | GEM-enabled drivers must provide gem_init_object() and | 705 | GEM-enabled drivers must provide gem_init_object() and |
681 | gem_free_object() callbacks to support the core memory | 706 | gem_free_object() callbacks to support the core memory |
682 | allocation routines. They should also provide several driver | 707 | allocation routines. They should also provide several driver-specific |
683 | specific ioctls to support command execution, pinning, buffer | 708 | ioctls to support command execution, pinning, buffer |
684 | read & write, mapping, and domain ownership transfers. | 709 | read & write, mapping, and domain ownership transfers. |
685 | </para> | 710 | </para> |
686 | <para> | 711 | <para> |
687 | On a fundamental level, GEM involves several operations: memory | 712 | On a fundamental level, GEM involves several operations: |
688 | allocation and freeing, command execution, and aperture management | 713 | <itemizedlist> |
689 | at command execution time. Buffer object allocation is relatively | 714 | <listitem>Memory allocation and freeing</listitem> |
715 | <listitem>Command execution</listitem> | ||
716 | <listitem>Aperture management at command execution time</listitem> | ||
717 | </itemizedlist> | ||
718 | Buffer object allocation is relatively | ||
690 | straightforward and largely provided by Linux's shmem layer, which | 719 | straightforward and largely provided by Linux's shmem layer, which |
691 | provides memory to back each object. When mapped into the GTT | 720 | 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 | 721 | 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 | 722 | 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, | 723 | with the GPU. Likewise, if the CPU accesses an object after the GPU |
695 | if the CPU accesses it, it must be made coherent with the CPU's view | 724 | has finished rendering to the object, then the object must be made |
725 | coherent with the CPU's view | ||
696 | of memory, usually involving GPU cache flushing of various kinds. | 726 | of memory, usually involving GPU cache flushing of various kinds. |
697 | This core CPU<->GPU coherency management is provided by the GEM | 727 | This core CPU<->GPU coherency management is provided by a |
698 | set domain function, which evaluates an object's current domain and | 728 | device-specific ioctl, which evaluates an object's current domain and |
699 | performs any necessary flushing or synchronization to put the object | 729 | performs any necessary flushing or synchronization to put the object |
700 | into the desired coherency domain (note that the object may be busy, | 730 | 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 | 731 | i.e. an active render target; in that case, setting the domain |
702 | will block the client and wait for rendering to complete before | 732 | blocks the client and waits for rendering to complete before |
703 | performing any necessary flushing operations). | 733 | performing any necessary flushing operations). |
704 | </para> | 734 | </para> |
705 | <para> | 735 | <para> |
706 | Perhaps the most important GEM function is providing a command | 736 | Perhaps the most important GEM function is providing a command |
707 | execution interface to clients. Client programs construct command | 737 | execution interface to clients. Client programs construct command |
708 | buffers containing references to previously allocated memory objects | 738 | buffers containing references to previously allocated memory objects, |
709 | and submit them to GEM. At that point, GEM will take care to bind | 739 | and then submit them to GEM. At that point, GEM takes care to bind |
710 | all the objects into the GTT, execute the buffer, and provide | 740 | all the objects into the GTT, execute the buffer, and provide |
711 | necessary synchronization between clients accessing the same buffers. | 741 | necessary synchronization between clients accessing the same buffers. |
712 | This often involves evicting some objects from the GTT and re-binding | 742 | This often involves evicting some objects from the GTT and re-binding |
713 | others (a fairly expensive operation), and providing relocation | 743 | others (a fairly expensive operation), and providing relocation |
714 | support which hides fixed GTT offsets from clients. Clients must | 744 | support which hides fixed GTT offsets from clients. Clients must |
715 | take care not to submit command buffers that reference more objects | 745 | 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 | 746 | than can fit in the GTT; otherwise, GEM will reject them and no rendering |
717 | will occur. Similarly, if several objects in the buffer require | 747 | will occur. Similarly, if several objects in the buffer require |
718 | fence registers to be allocated for correct rendering (e.g. 2D blits | 748 | 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 | 749 | on pre-965 chips), care must be taken not to require more fence |
@@ -729,7 +759,7 @@ void intel_crt_init(struct drm_device *dev) | |||
729 | <title>Output management</title> | 759 | <title>Output management</title> |
730 | <para> | 760 | <para> |
731 | At the core of the DRM output management code is a set of | 761 | At the core of the DRM output management code is a set of |
732 | structures representing CRTCs, encoders and connectors. | 762 | structures representing CRTCs, encoders, and connectors. |
733 | </para> | 763 | </para> |
734 | <para> | 764 | <para> |
735 | A CRTC is an abstraction representing a part of the chip that | 765 | A CRTC is an abstraction representing a part of the chip that |
@@ -765,21 +795,19 @@ void intel_crt_init(struct drm_device *dev) | |||
765 | <sect1> | 795 | <sect1> |
766 | <title>Framebuffer management</title> | 796 | <title>Framebuffer management</title> |
767 | <para> | 797 | <para> |
768 | In order to set a mode on a given CRTC, encoder and connector | 798 | Clients need to provide a framebuffer object which provides a source |
769 | configuration, clients need to provide a framebuffer object which | 799 | of pixels for a CRTC to deliver to the encoder(s) and ultimately the |
770 | will provide a source of pixels for the CRTC to deliver to the encoder(s) | 800 | connector(s). A framebuffer is fundamentally a driver-specific memory |
771 | and ultimately the connector(s) in the configuration. A framebuffer | 801 | object, made into an opaque handle by the DRM's addfb() function. |
772 | is fundamentally a driver specific memory object, made into an opaque | 802 | Once a framebuffer has been created this way, it may be passed to the |
773 | handle by the DRM addfb function. Once an fb has been created this | 803 | KMS mode setting routines for use in a completed configuration. |
774 | way it can be passed to the KMS mode setting routines for use in | ||
775 | a configuration. | ||
776 | </para> | 804 | </para> |
777 | </sect1> | 805 | </sect1> |
778 | 806 | ||
779 | <sect1> | 807 | <sect1> |
780 | <title>Command submission & fencing</title> | 808 | <title>Command submission & fencing</title> |
781 | <para> | 809 | <para> |
782 | This should cover a few device specific command submission | 810 | This should cover a few device-specific command submission |
783 | implementations. | 811 | implementations. |
784 | </para> | 812 | </para> |
785 | </sect1> | 813 | </sect1> |
@@ -789,7 +817,7 @@ void intel_crt_init(struct drm_device *dev) | |||
789 | <para> | 817 | <para> |
790 | The DRM core provides some suspend/resume code, but drivers | 818 | The DRM core provides some suspend/resume code, but drivers |
791 | wanting full suspend/resume support should provide save() and | 819 | wanting full suspend/resume support should provide save() and |
792 | restore() functions. These will be called at suspend, | 820 | restore() functions. These are called at suspend, |
793 | hibernate, or resume time, and should perform any state save or | 821 | hibernate, or resume time, and should perform any state save or |
794 | restore required by your device across suspend or hibernate | 822 | restore required by your device across suspend or hibernate |
795 | states. | 823 | states. |
@@ -812,8 +840,8 @@ void intel_crt_init(struct drm_device *dev) | |||
812 | <para> | 840 | <para> |
813 | The DRM core exports several interfaces to applications, | 841 | The DRM core exports several interfaces to applications, |
814 | generally intended to be used through corresponding libdrm | 842 | generally intended to be used through corresponding libdrm |
815 | wrapper functions. In addition, drivers export device specific | 843 | wrapper functions. In addition, drivers export device-specific |
816 | interfaces for use by userspace drivers & device aware | 844 | interfaces for use by userspace drivers & device-aware |
817 | applications through ioctls and sysfs files. | 845 | applications through ioctls and sysfs files. |
818 | </para> | 846 | </para> |
819 | <para> | 847 | <para> |
@@ -822,8 +850,8 @@ void intel_crt_init(struct drm_device *dev) | |||
822 | management, memory management, and output management. | 850 | management, memory management, and output management. |
823 | </para> | 851 | </para> |
824 | <para> | 852 | <para> |
825 | Cover generic ioctls and sysfs layout here. Only need high | 853 | Cover generic ioctls and sysfs layout here. We only need high-level |
826 | level info, since man pages will cover the rest. | 854 | info, since man pages should cover the rest. |
827 | </para> | 855 | </para> |
828 | </chapter> | 856 | </chapter> |
829 | 857 | ||