~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/gpu/drm-kms.rst

Version: ~ [ linux-6.11.5 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.58 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.114 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.169 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.228 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.284 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.322 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.9 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

  1 =========================
  2 Kernel Mode Setting (KMS)
  3 =========================
  4 
  5 Drivers must initialize the mode setting core by calling
  6 drmm_mode_config_init() on the DRM device. The function
  7 initializes the :c:type:`struct drm_device <drm_device>`
  8 mode_config field and never fails. Once done, mode configuration must
  9 be setup by initializing the following fields.
 10 
 11 -  int min_width, min_height; int max_width, max_height;
 12    Minimum and maximum width and height of the frame buffers in pixel
 13    units.
 14 
 15 -  struct drm_mode_config_funcs \*funcs;
 16    Mode setting functions.
 17 
 18 Overview
 19 ========
 20 
 21 .. kernel-render:: DOT
 22    :alt: KMS Display Pipeline
 23    :caption: KMS Display Pipeline Overview
 24 
 25    digraph "KMS" {
 26       node [shape=box]
 27 
 28       subgraph cluster_static {
 29           style=dashed
 30           label="Static Objects"
 31 
 32           node [bgcolor=grey style=filled]
 33           "drm_plane A" -> "drm_crtc"
 34           "drm_plane B" -> "drm_crtc"
 35           "drm_crtc" -> "drm_encoder A"
 36           "drm_crtc" -> "drm_encoder B"
 37       }
 38 
 39       subgraph cluster_user_created {
 40           style=dashed
 41           label="Userspace-Created"
 42 
 43           node [shape=oval]
 44           "drm_framebuffer 1" -> "drm_plane A"
 45           "drm_framebuffer 2" -> "drm_plane B"
 46       }
 47 
 48       subgraph cluster_connector {
 49           style=dashed
 50           label="Hotpluggable"
 51 
 52           "drm_encoder A" -> "drm_connector A"
 53           "drm_encoder B" -> "drm_connector B"
 54       }
 55    }
 56 
 57 The basic object structure KMS presents to userspace is fairly simple.
 58 Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`,
 59 see `Frame Buffer Abstraction`_) feed into planes. Planes are represented by
 60 :c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more
 61 details. One or more (or even no) planes feed their pixel data into a CRTC
 62 (represented by :c:type:`struct drm_crtc <drm_crtc>`, see `CRTC Abstraction`_)
 63 for blending. The precise blending step is explained in more detail in `Plane
 64 Composition Properties`_ and related chapters.
 65 
 66 For the output routing the first step is encoders (represented by
 67 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
 68 are really just internal artifacts of the helper libraries used to implement KMS
 69 drivers. Besides that they make it unnecessarily more complicated for userspace
 70 to figure out which connections between a CRTC and a connector are possible, and
 71 what kind of cloning is supported, they serve no purpose in the userspace API.
 72 Unfortunately encoders have been exposed to userspace, hence can't remove them
 73 at this point.  Furthermore the exposed restrictions are often wrongly set by
 74 drivers, and in many cases not powerful enough to express the real restrictions.
 75 A CRTC can be connected to multiple encoders, and for an active CRTC there must
 76 be at least one encoder.
 77 
 78 The final, and real, endpoint in the display chain is the connector (represented
 79 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
 80 Abstraction`_). Connectors can have different possible encoders, but the kernel
 81 driver selects which encoder to use for each connector. The use case is DVI,
 82 which could switch between an analog and a digital encoder. Encoders can also
 83 drive multiple different connectors. There is exactly one active connector for
 84 every active encoder.
 85 
 86 Internally the output pipeline is a bit more complex and matches today's
 87 hardware more closely:
 88 
 89 .. kernel-render:: DOT
 90    :alt: KMS Output Pipeline
 91    :caption: KMS Output Pipeline
 92 
 93    digraph "Output Pipeline" {
 94       node [shape=box]
 95 
 96       subgraph {
 97           "drm_crtc" [bgcolor=grey style=filled]
 98       }
 99 
100       subgraph cluster_internal {
101           style=dashed
102           label="Internal Pipeline"
103           {
104               node [bgcolor=grey style=filled]
105               "drm_encoder A";
106               "drm_encoder B";
107               "drm_encoder C";
108           }
109 
110           {
111               node [bgcolor=grey style=filled]
112               "drm_encoder B" -> "drm_bridge B"
113               "drm_encoder C" -> "drm_bridge C1"
114               "drm_bridge C1" -> "drm_bridge C2";
115           }
116       }
117 
118       "drm_crtc" -> "drm_encoder A"
119       "drm_crtc" -> "drm_encoder B"
120       "drm_crtc" -> "drm_encoder C"
121 
122 
123       subgraph cluster_output {
124           style=dashed
125           label="Outputs"
126 
127           "drm_encoder A" -> "drm_connector A";
128           "drm_bridge B" -> "drm_connector B";
129           "drm_bridge C2" -> "drm_connector C";
130 
131           "drm_panel"
132       }
133    }
134 
135 Internally two additional helper objects come into play. First, to be able to
136 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
137 more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge
138 <drm_bridge>`) can be linked to an encoder. This link is static and cannot be
139 changed, which means the cross-bar (if there is any) needs to be mapped between
140 the CRTC and any encoders. Often for drivers with bridges there's no code left
141 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
142 essentially only leave a dummy routing object behind, which is needed for
143 backwards compatibility since encoders are exposed to userspace.
144 
145 The second object is for panels, represented by :c:type:`struct drm_panel
146 <drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding
147 point, but are generally linked to the driver private structure that embeds
148 :c:type:`struct drm_connector <drm_connector>`.
149 
150 Note that currently the bridge chaining and interactions with connectors and
151 panels are still in-flux and not really fully sorted out yet.
152 
153 KMS Core Structures and Functions
154 =================================
155 
156 .. kernel-doc:: include/drm/drm_mode_config.h
157    :internal:
158 
159 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
160    :export:
161 
162 .. _kms_base_object_abstraction:
163 
164 Modeset Base Object Abstraction
165 ===============================
166 
167 .. kernel-render:: DOT
168    :alt: Mode Objects and Properties
169    :caption: Mode Objects and Properties
170 
171    digraph {
172       node [shape=box]
173 
174       "drm_property A" -> "drm_mode_object A"
175       "drm_property A" -> "drm_mode_object B"
176       "drm_property B" -> "drm_mode_object A"
177    }
178 
179 The base structure for all KMS objects is :c:type:`struct drm_mode_object
180 <drm_mode_object>`. One of the base services it provides is tracking properties,
181 which are especially important for the atomic IOCTL (see `Atomic Mode
182 Setting`_). The somewhat surprising part here is that properties are not
183 directly instantiated on each object, but free-standing mode objects themselves,
184 represented by :c:type:`struct drm_property <drm_property>`, which only specify
185 the type and value range of a property. Any given property can be attached
186 multiple times to different objects using drm_object_attach_property().
187 
188 .. kernel-doc:: include/drm/drm_mode_object.h
189    :internal:
190 
191 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
192    :export:
193 
194 Atomic Mode Setting
195 ===================
196 
197 
198 .. kernel-render:: DOT
199    :alt: Mode Objects and Properties
200    :caption: Mode Objects and Properties
201 
202    digraph {
203       node [shape=box]
204 
205       subgraph cluster_state {
206           style=dashed
207           label="Free-standing state"
208 
209           "drm_atomic_state" -> "duplicated drm_plane_state A"
210           "drm_atomic_state" -> "duplicated drm_plane_state B"
211           "drm_atomic_state" -> "duplicated drm_crtc_state"
212           "drm_atomic_state" -> "duplicated drm_connector_state"
213           "drm_atomic_state" -> "duplicated driver private state"
214       }
215 
216       subgraph cluster_current {
217           style=dashed
218           label="Current state"
219 
220           "drm_device" -> "drm_plane A"
221           "drm_device" -> "drm_plane B"
222           "drm_device" -> "drm_crtc"
223           "drm_device" -> "drm_connector"
224           "drm_device" -> "driver private object"
225 
226           "drm_plane A" -> "drm_plane_state A"
227           "drm_plane B" -> "drm_plane_state B"
228           "drm_crtc" -> "drm_crtc_state"
229           "drm_connector" -> "drm_connector_state"
230           "driver private object" -> "driver private state"
231       }
232 
233       "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
234       "duplicated drm_plane_state A" -> "drm_device"[style=invis]
235    }
236 
237 Atomic provides transactional modeset (including planes) updates, but a
238 bit differently from the usual transactional approach of try-commit and
239 rollback:
240 
241 - Firstly, no hardware changes are allowed when the commit would fail. This
242   allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
243   userspace to explore whether certain configurations would work or not.
244 
245 - This would still allow setting and rollback of just the software state,
246   simplifying conversion of existing drivers. But auditing drivers for
247   correctness of the atomic_check code becomes really hard with that: Rolling
248   back changes in data structures all over the place is hard to get right.
249 
250 - Lastly, for backwards compatibility and to support all use-cases, atomic
251   updates need to be incremental and be able to execute in parallel. Hardware
252   doesn't always allow it, but where possible plane updates on different CRTCs
253   should not interfere, and not get stalled due to output routing changing on
254   different CRTCs.
255 
256 Taken all together there's two consequences for the atomic design:
257 
258 - The overall state is split up into per-object state structures:
259   :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
260   drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
261   drm_connector_state <drm_connector_state>` for connectors. These are the only
262   objects with userspace-visible and settable state. For internal state drivers
263   can subclass these structures through embedding, or add entirely new state
264   structures for their globally shared hardware functions, see :c:type:`struct
265   drm_private_state<drm_private_state>`.
266 
267 - An atomic update is assembled and validated as an entirely free-standing pile
268   of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
269   container. Driver private state structures are also tracked in the same
270   structure; see the next chapter.  Only when a state is committed is it applied
271   to the driver and modeset objects. This way rolling back an update boils down
272   to releasing memory and unreferencing objects like framebuffers.
273 
274 Locking of atomic state structures is internally using :c:type:`struct
275 drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
276 exposed to drivers, instead the right locks should be automatically acquired by
277 any function that duplicates or peeks into a state, like e.g.
278 drm_atomic_get_crtc_state().  Locking only protects the software data
279 structure, ordering of committing state changes to hardware is sequenced using
280 :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
281 
282 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
283 coverage of specific topics.
284 
285 Handling Driver Private State
286 -----------------------------
287 
288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
289    :doc: handling driver private state
290 
291 Atomic Mode Setting Function Reference
292 --------------------------------------
293 
294 .. kernel-doc:: include/drm/drm_atomic.h
295    :internal:
296 
297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
298    :export:
299 
300 Atomic Mode Setting IOCTL and UAPI Functions
301 --------------------------------------------
302 
303 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
304    :doc: overview
305 
306 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
307    :export:
308 
309 CRTC Abstraction
310 ================
311 
312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
313    :doc: overview
314 
315 CRTC Functions Reference
316 --------------------------------
317 
318 .. kernel-doc:: include/drm/drm_crtc.h
319    :internal:
320 
321 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
322    :export:
323 
324 Color Management Functions Reference
325 ------------------------------------
326 
327 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
328    :export:
329 
330 .. kernel-doc:: include/drm/drm_color_mgmt.h
331    :internal:
332 
333 Frame Buffer Abstraction
334 ========================
335 
336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
337    :doc: overview
338 
339 Frame Buffer Functions Reference
340 --------------------------------
341 
342 .. kernel-doc:: include/drm/drm_framebuffer.h
343    :internal:
344 
345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
346    :export:
347 
348 DRM Format Handling
349 ===================
350 
351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
352    :doc: overview
353 
354 Format Functions Reference
355 --------------------------
356 
357 .. kernel-doc:: include/drm/drm_fourcc.h
358    :internal:
359 
360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
361    :export:
362 
363 .. _kms_dumb_buffer_objects:
364 
365 Dumb Buffer Objects
366 ===================
367 
368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
369    :doc: overview
370 
371 Plane Abstraction
372 =================
373 
374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
375    :doc: overview
376 
377 Plane Functions Reference
378 -------------------------
379 
380 .. kernel-doc:: include/drm/drm_plane.h
381    :internal:
382 
383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
384    :export:
385 
386 Plane Composition Functions Reference
387 -------------------------------------
388 
389 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
390    :export:
391 
392 Plane Damage Tracking Functions Reference
393 -----------------------------------------
394 
395 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
396    :export:
397 
398 .. kernel-doc:: include/drm/drm_damage_helper.h
399    :internal:
400 
401 Plane Panic Feature
402 -------------------
403 
404 .. kernel-doc:: drivers/gpu/drm/drm_panic.c
405    :doc: overview
406 
407 Plane Panic Functions Reference
408 -------------------------------
409 
410 .. kernel-doc:: include/drm/drm_panic.h
411    :internal:
412 
413 .. kernel-doc:: drivers/gpu/drm/drm_panic.c
414    :export:
415 
416 Display Modes Function Reference
417 ================================
418 
419 .. kernel-doc:: include/drm/drm_modes.h
420    :internal:
421 
422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
423    :export:
424 
425 Connector Abstraction
426 =====================
427 
428 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
429    :doc: overview
430 
431 Connector Functions Reference
432 -----------------------------
433 
434 .. kernel-doc:: include/drm/drm_connector.h
435    :internal:
436 
437 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
438    :export:
439 
440 Writeback Connectors
441 --------------------
442 
443 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
444   :doc: overview
445 
446 .. kernel-doc:: include/drm/drm_writeback.h
447   :internal:
448 
449 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
450   :export:
451 
452 Encoder Abstraction
453 ===================
454 
455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
456    :doc: overview
457 
458 Encoder Functions Reference
459 ---------------------------
460 
461 .. kernel-doc:: include/drm/drm_encoder.h
462    :internal:
463 
464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
465    :export:
466 
467 KMS Locking
468 ===========
469 
470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
471    :doc: kms locking
472 
473 .. kernel-doc:: include/drm/drm_modeset_lock.h
474    :internal:
475 
476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
477    :export:
478 
479 KMS Properties
480 ==============
481 
482 This section of the documentation is primarily aimed at user-space developers.
483 For the driver APIs, see the other sections.
484 
485 Requirements
486 ------------
487 
488 KMS drivers might need to add extra properties to support new features. Each
489 new property introduced in a driver needs to meet a few requirements, in
490 addition to the one mentioned above:
491 
492 * It must be standardized, documenting:
493 
494   * The full, exact, name string;
495   * If the property is an enum, all the valid value name strings;
496   * What values are accepted, and what these values mean;
497   * What the property does and how it can be used;
498   * How the property might interact with other, existing properties.
499 
500 * It must provide a generic helper in the core code to register that
501   property on the object it attaches to.
502 
503 * Its content must be decoded by the core and provided in the object's
504   associated state structure. That includes anything drivers might want
505   to precompute, like struct drm_clip_rect for planes.
506 
507 * Its initial state must match the behavior prior to the property
508   introduction. This might be a fixed value matching what the hardware
509   does, or it may be inherited from the state the firmware left the
510   system in during boot.
511 
512 * An IGT test must be submitted where reasonable.
513 
514 For historical reasons, non-standard, driver-specific properties exist. If a KMS
515 driver wants to add support for one of those properties, the requirements for
516 new properties apply where possible. Additionally, the documented behavior must
517 match the de facto semantics of the existing property to ensure compatibility.
518 Developers of the driver that first added the property should help with those
519 tasks and must ACK the documented behavior if possible.
520 
521 Property Types and Blob Property Support
522 ----------------------------------------
523 
524 .. kernel-doc:: drivers/gpu/drm/drm_property.c
525    :doc: overview
526 
527 .. kernel-doc:: include/drm/drm_property.h
528    :internal:
529 
530 .. kernel-doc:: drivers/gpu/drm/drm_property.c
531    :export:
532 
533 .. _standard_connector_properties:
534 
535 Standard Connector Properties
536 -----------------------------
537 
538 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
539    :doc: standard connector properties
540 
541 HDMI Specific Connector Properties
542 ----------------------------------
543 
544 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
545    :doc: HDMI connector properties
546 
547 Analog TV Specific Connector Properties
548 ---------------------------------------
549 
550 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
551    :doc: Analog TV Connector Properties
552 
553 Standard CRTC Properties
554 ------------------------
555 
556 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
557    :doc: standard CRTC properties
558 
559 Standard Plane Properties
560 -------------------------
561 
562 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
563    :doc: standard plane properties
564 
565 .. _plane_composition_properties:
566 
567 Plane Composition Properties
568 ----------------------------
569 
570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
571    :doc: overview
572 
573 .. _damage_tracking_properties:
574 
575 Damage Tracking Properties
576 --------------------------
577 
578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
579    :doc: damage tracking
580 
581 Color Management Properties
582 ---------------------------
583 
584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
585    :doc: overview
586 
587 Tile Group Property
588 -------------------
589 
590 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
591    :doc: Tile group
592 
593 Explicit Fencing Properties
594 ---------------------------
595 
596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
597    :doc: explicit fencing properties
598 
599 
600 Variable Refresh Properties
601 ---------------------------
602 
603 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
604    :doc: Variable refresh properties
605 
606 Cursor Hotspot Properties
607 ---------------------------
608 
609 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
610    :doc: hotspot properties
611 
612 Existing KMS Properties
613 -----------------------
614 
615 The following table gives description of drm properties exposed by various
616 modules/drivers. Because this table is very unwieldy, do not add any new
617 properties here. Instead document them in a section above.
618 
619 .. csv-table::
620    :header-rows: 1
621    :file: kms-properties.csv
622 
623 Vertical Blanking
624 =================
625 
626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
627    :doc: vblank handling
628 
629 Vertical Blanking and Interrupt Handling Functions Reference
630 ------------------------------------------------------------
631 
632 .. kernel-doc:: include/drm/drm_vblank.h
633    :internal:
634 
635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
636    :export:
637 
638 Vertical Blank Work
639 ===================
640 
641 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
642    :doc: vblank works
643 
644 Vertical Blank Work Functions Reference
645 ---------------------------------------
646 
647 .. kernel-doc:: include/drm/drm_vblank_work.h
648    :internal:
649 
650 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
651    :export:

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php