Documentation/gpu/drm-kms.rst

   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 unecessarily 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.  Futhermore 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 embeddeding, 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 Dumb Buffer Objects
 364 ===================
 365
 366 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
 367    :doc: overview
 368
 369 Plane Abstraction
 370 =================
 371
 372 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 373    :doc: overview
 374
 375 Plane Functions Reference
 376 -------------------------
 377
 378 .. kernel-doc:: include/drm/drm_plane.h
 379    :internal:
 380
 381 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 382    :export:
 383
 384 Plane Composition Functions Reference
 385 -------------------------------------
 386
 387 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 388    :export:
 389
 390 Plane Damage Tracking Functions Reference
 391 -----------------------------------------
 392
 393 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
 394    :export:
 395
 396 .. kernel-doc:: include/drm/drm_damage_helper.h
 397    :internal:
 398
 399 Display Modes Function Reference
 400 ================================
 401
 402 .. kernel-doc:: include/drm/drm_modes.h
 403    :internal:
 404
 405 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 406    :export:
 407
 408 Connector Abstraction
 409 =====================
 410
 411 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 412    :doc: overview
 413
 414 Connector Functions Reference
 415 -----------------------------
 416
 417 .. kernel-doc:: include/drm/drm_connector.h
 418    :internal:
 419
 420 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 421    :export:
 422
 423 Writeback Connectors
 424 --------------------
 425
 426 .. kernel-doc:: include/drm/drm_writeback.h
 427   :internal:
 428
 429 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 430   :doc: overview
 431
 432 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 433   :export:
 434
 435 Encoder Abstraction
 436 ===================
 437
 438 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 439    :doc: overview
 440
 441 Encoder Functions Reference
 442 ---------------------------
 443
 444 .. kernel-doc:: include/drm/drm_encoder.h
 445    :internal:
 446
 447 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 448    :export:
 449
 450 KMS Locking
 451 ===========
 452
 453 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 454    :doc: kms locking
 455
 456 .. kernel-doc:: include/drm/drm_modeset_lock.h
 457    :internal:
 458
 459 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 460    :export:
 461
 462 KMS Properties
 463 ==============
 464
 465 This section of the documentation is primarily aimed at user-space developers.
 466 For the driver APIs, see the other sections.
 467
 468 Requirements
 469 ------------
 470
 471 KMS drivers might need to add extra properties to support new features. Each
 472 new property introduced in a driver needs to meet a few requirements, in
 473 addition to the one mentioned above:
 474
 475 * It must be standardized, documenting:
 476
 477   * The full, exact, name string;
 478   * If the property is an enum, all the valid value name strings;
 479   * What values are accepted, and what these values mean;
 480   * What the property does and how it can be used;
 481   * How the property might interact with other, existing properties.
 482
 483 * It must provide a generic helper in the core code to register that
 484   property on the object it attaches to.
 485
 486 * Its content must be decoded by the core and provided in the object's
 487   associated state structure. That includes anything drivers might want
 488   to precompute, like struct drm_clip_rect for planes.
 489
 490 * Its initial state must match the behavior prior to the property
 491   introduction. This might be a fixed value matching what the hardware
 492   does, or it may be inherited from the state the firmware left the
 493   system in during boot.
 494
 495 * An IGT test must be submitted where reasonable.
 496
 497 Property Types and Blob Property Support
 498 ----------------------------------------
 499
 500 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 501    :doc: overview
 502
 503 .. kernel-doc:: include/drm/drm_property.h
 504    :internal:
 505
 506 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 507    :export:
 508
 509 Standard Connector Properties
 510 -----------------------------
 511
 512 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 513    :doc: standard connector properties
 514
 515 HDMI Specific Connector Properties
 516 ----------------------------------
 517
 518 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 519    :doc: HDMI connector properties
 520
 521 Standard CRTC Properties
 522 ------------------------
 523
 524 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 525    :doc: standard CRTC properties
 526
 527 Standard Plane Properties
 528 -------------------------
 529
 530 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 531    :doc: standard plane properties
 532
 533 Plane Composition Properties
 534 ----------------------------
 535
 536 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 537    :doc: overview
 538
 539 Damage Tracking Properties
 540 --------------------------
 541
 542 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 543    :doc: damage tracking
 544
 545 Color Management Properties
 546 ---------------------------
 547
 548 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 549    :doc: overview
 550
 551 Tile Group Property
 552 -------------------
 553
 554 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 555    :doc: Tile group
 556
 557 Explicit Fencing Properties
 558 ---------------------------
 559
 560 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 561    :doc: explicit fencing properties
 562
 563
 564 Variable Refresh Properties
 565 ---------------------------
 566
 567 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 568    :doc: Variable refresh properties
 569
 570 Existing KMS Properties
 571 -----------------------
 572
 573 The following table gives description of drm properties exposed by various
 574 modules/drivers. Because this table is very unwieldy, do not add any new
 575 properties here. Instead document them in a section above.
 576
 577 .. csv-table::
 578    :header-rows: 1
 579    :file: kms-properties.csv
 580
 581 Vertical Blanking
 582 =================
 583
 584 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 585    :doc: vblank handling
 586
 587 Vertical Blanking and Interrupt Handling Functions Reference
 588 ------------------------------------------------------------
 589
 590 .. kernel-doc:: include/drm/drm_vblank.h
 591    :internal:
 592
 593 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 594    :export:
 595
 596 Vertical Blank Work
 597 ===================
 598
 599 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
 600    :doc: vblank works
 601
 602 Vertical Blank Work Functions Reference
 603 ---------------------------------------
 604
 605 .. kernel-doc:: include/drm/drm_vblank_work.h
 606    :internal:
 607
 608 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
 609    :export: