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