Documentation/gpu/drm-kms.rst

   1 =========================
   2 Kernel Mode Setting (KMS)
   3 =========================
   4
   5 Drivers must initialize the mode setting core by calling
   6 :c:func:`drm_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 Modeset Base Object Abstraction
 163 ===============================
 164
 165 .. kernel-render:: DOT
 166    :alt: Mode Objects and Properties
 167    :caption: Mode Objects and Properties
 168
 169    digraph {
 170       node [shape=box]
 171
 172       "drm_property A" -> "drm_mode_object A"
 173       "drm_property A" -> "drm_mode_object B"
 174       "drm_property B" -> "drm_mode_object A"
 175    }
 176
 177 The base structure for all KMS objects is :c:type:`struct drm_mode_object
 178 <drm_mode_object>`. One of the base services it provides is tracking properties,
 179 which are especially important for the atomic IOCTL (see `Atomic Mode
 180 Setting`_). The somewhat surprising part here is that properties are not
 181 directly instantiated on each object, but free-standing mode objects themselves,
 182 represented by :c:type:`struct drm_property <drm_property>`, which only specify
 183 the type and value range of a property. Any given property can be attached
 184 multiple times to different objects using :c:func:`drm_object_attach_property()
 185 <drm_object_attach_property>`.
 186
 187 .. kernel-doc:: include/drm/drm_mode_object.h
 188    :internal:
 189
 190 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
 191    :export:
 192
 193 Atomic Mode Setting
 194 ===================
 195
 196
 197 .. kernel-render:: DOT
 198    :alt: Mode Objects and Properties
 199    :caption: Mode Objects and Properties
 200
 201    digraph {
 202       node [shape=box]
 203
 204       subgraph cluster_state {
 205           style=dashed
 206           label="Free-standing state"
 207
 208           "drm_atomic_state" -> "duplicated drm_plane_state A"
 209           "drm_atomic_state" -> "duplicated drm_plane_state B"
 210           "drm_atomic_state" -> "duplicated drm_crtc_state"
 211           "drm_atomic_state" -> "duplicated drm_connector_state"
 212           "drm_atomic_state" -> "duplicated driver private state"
 213       }
 214
 215       subgraph cluster_current {
 216           style=dashed
 217           label="Current state"
 218
 219           "drm_device" -> "drm_plane A"
 220           "drm_device" -> "drm_plane B"
 221           "drm_device" -> "drm_crtc"
 222           "drm_device" -> "drm_connector"
 223           "drm_device" -> "driver private object"
 224
 225           "drm_plane A" -> "drm_plane_state A"
 226           "drm_plane B" -> "drm_plane_state B"
 227           "drm_crtc" -> "drm_crtc_state"
 228           "drm_connector" -> "drm_connector_state"
 229           "driver private object" -> "driver private state"
 230       }
 231
 232       "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
 233       "duplicated drm_plane_state A" -> "drm_device"[style=invis]
 234    }
 235
 236 Atomic provides transactional modeset (including planes) updates, but a
 237 bit differently from the usual transactional approach of try-commit and
 238 rollback:
 239
 240 - Firstly, no hardware changes are allowed when the commit would fail. This
 241   allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
 242   userspace to explore whether certain configurations would work or not.
 243
 244 - This would still allow setting and rollback of just the software state,
 245   simplifying conversion of existing drivers. But auditing drivers for
 246   correctness of the atomic_check code becomes really hard with that: Rolling
 247   back changes in data structures all over the place is hard to get right.
 248
 249 - Lastly, for backwards compatibility and to support all use-cases, atomic
 250   updates need to be incremental and be able to execute in parallel. Hardware
 251   doesn't always allow it, but where possible plane updates on different CRTCs
 252   should not interfere, and not get stalled due to output routing changing on
 253   different CRTCs.
 254
 255 Taken all together there's two consequences for the atomic design:
 256
 257 - The overall state is split up into per-object state structures:
 258   :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
 259   drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
 260   drm_connector_state <drm_connector_state>` for connectors. These are the only
 261   objects with userspace-visible and settable state. For internal state drivers
 262   can subclass these structures through embeddeding, or add entirely new state
 263   structures for their globally shared hardware functions.
 264
 265 - An atomic update is assembled and validated as an entirely free-standing pile
 266   of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
 267   container. Driver private state structures are also tracked in the same
 268   structure; see the next chapter.  Only when a state is committed is it applied
 269   to the driver and modeset objects. This way rolling back an update boils down
 270   to releasing memory and unreferencing objects like framebuffers.
 271
 272 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
 273 coverage of specific topics.
 274
 275 Handling Driver Private State
 276 -----------------------------
 277
 278 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 279    :doc: handling driver private state
 280
 281 Atomic Mode Setting Function Reference
 282 --------------------------------------
 283
 284 .. kernel-doc:: include/drm/drm_atomic.h
 285    :internal:
 286
 287 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 288    :export:
 289
 290 Atomic Mode Setting IOCTL and UAPI Functions
 291 --------------------------------------------
 292
 293 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 294    :doc: overview
 295
 296 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 297    :export:
 298
 299 CRTC Abstraction
 300 ================
 301
 302 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 303    :doc: overview
 304
 305 CRTC Functions Reference
 306 --------------------------------
 307
 308 .. kernel-doc:: include/drm/drm_crtc.h
 309    :internal:
 310
 311 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 312    :export:
 313
 314 Frame Buffer Abstraction
 315 ========================
 316
 317 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 318    :doc: overview
 319
 320 Frame Buffer Functions Reference
 321 --------------------------------
 322
 323 .. kernel-doc:: include/drm/drm_framebuffer.h
 324    :internal:
 325
 326 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 327    :export:
 328
 329 DRM Format Handling
 330 ===================
 331
 332 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
 333    :doc: overview
 334
 335 Format Functions Reference
 336 --------------------------
 337
 338 .. kernel-doc:: include/drm/drm_fourcc.h
 339    :internal:
 340
 341 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
 342    :export:
 343
 344 Dumb Buffer Objects
 345 ===================
 346
 347 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
 348    :doc: overview
 349
 350 Plane Abstraction
 351 =================
 352
 353 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 354    :doc: overview
 355
 356 Plane Functions Reference
 357 -------------------------
 358
 359 .. kernel-doc:: include/drm/drm_plane.h
 360    :internal:
 361
 362 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 363    :export:
 364
 365 Display Modes Function Reference
 366 ================================
 367
 368 .. kernel-doc:: include/drm/drm_modes.h
 369    :internal:
 370
 371 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 372    :export:
 373
 374 Connector Abstraction
 375 =====================
 376
 377 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 378    :doc: overview
 379
 380 Connector Functions Reference
 381 -----------------------------
 382
 383 .. kernel-doc:: include/drm/drm_connector.h
 384    :internal:
 385
 386 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 387    :export:
 388
 389 Writeback Connectors
 390 --------------------
 391
 392 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 393   :doc: overview
 394
 395 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 396   :export:
 397
 398 Encoder Abstraction
 399 ===================
 400
 401 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 402    :doc: overview
 403
 404 Encoder Functions Reference
 405 ---------------------------
 406
 407 .. kernel-doc:: include/drm/drm_encoder.h
 408    :internal:
 409
 410 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 411    :export:
 412
 413 KMS Initialization and Cleanup
 414 ==============================
 415
 416 A KMS device is abstracted and exposed as a set of planes, CRTCs,
 417 encoders and connectors. KMS drivers must thus create and initialize all
 418 those objects at load time after initializing mode setting.
 419
 420 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
 421 --------------------------------------------
 422
 423 A CRTC is an abstraction representing a part of the chip that contains a
 424 pointer to a scanout buffer. Therefore, the number of CRTCs available
 425 determines how many independent scanout buffers can be active at any
 426 given time. The CRTC structure contains several fields to support this:
 427 a pointer to some video memory (abstracted as a frame buffer object), a
 428 display mode, and an (x, y) offset into the video memory to support
 429 panning or configurations where one piece of video memory spans multiple
 430 CRTCs.
 431
 432 CRTC Initialization
 433 ~~~~~~~~~~~~~~~~~~~
 434
 435 A KMS device must create and register at least one struct
 436 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
 437 allocated and zeroed by the driver, possibly as part of a larger
 438 structure, and registered with a call to :c:func:`drm_crtc_init()`
 439 with a pointer to CRTC functions.
 440
 441
 442 Cleanup
 443 -------
 444
 445 The DRM core manages its objects' lifetime. When an object is not needed
 446 anymore the core calls its destroy function, which must clean up and
 447 free every resource allocated for the object. Every
 448 :c:func:`drm_\*_init()` call must be matched with a corresponding
 449 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
 450 (:c:func:`drm_crtc_cleanup()`), planes
 451 (:c:func:`drm_plane_cleanup()`), encoders
 452 (:c:func:`drm_encoder_cleanup()`) and connectors
 453 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
 454 have been added to sysfs must be removed by a call to
 455 :c:func:`drm_connector_unregister()` before calling
 456 :c:func:`drm_connector_cleanup()`.
 457
 458 Connectors state change detection must be cleanup up with a call to
 459 :c:func:`drm_kms_helper_poll_fini()`.
 460
 461 Output discovery and initialization example
 462 -------------------------------------------
 463
 464 .. code-block:: c
 465
 466     void intel_crt_init(struct drm_device *dev)
 467     {
 468         struct drm_connector *connector;
 469         struct intel_output *intel_output;
 470
 471         intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
 472         if (!intel_output)
 473             return;
 474
 475         connector = &intel_output->base;
 476         drm_connector_init(dev, &intel_output->base,
 477                    &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
 478
 479         drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
 480                  DRM_MODE_ENCODER_DAC);
 481
 482         drm_connector_attach_encoder(&intel_output->base,
 483                           &intel_output->enc);
 484
 485         /* Set up the DDC bus. */
 486         intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
 487         if (!intel_output->ddc_bus) {
 488             dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
 489                    "failed.\n");
 490             return;
 491         }
 492
 493         intel_output->type = INTEL_OUTPUT_ANALOG;
 494         connector->interlace_allowed = 0;
 495         connector->doublescan_allowed = 0;
 496
 497         drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
 498         drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
 499
 500         drm_connector_register(connector);
 501     }
 502
 503 In the example above (taken from the i915 driver), a CRTC, connector and
 504 encoder combination is created. A device-specific i2c bus is also
 505 created for fetching EDID data and performing monitor detection. Once
 506 the process is complete, the new connector is registered with sysfs to
 507 make its properties available to applications.
 508
 509 KMS Locking
 510 ===========
 511
 512 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 513    :doc: kms locking
 514
 515 .. kernel-doc:: include/drm/drm_modeset_lock.h
 516    :internal:
 517
 518 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 519    :export:
 520
 521 KMS Properties
 522 ==============
 523
 524 Property Types and Blob Property Support
 525 ----------------------------------------
 526
 527 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 528    :doc: overview
 529
 530 .. kernel-doc:: include/drm/drm_property.h
 531    :internal:
 532
 533 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 534    :export:
 535
 536 Standard Connector Properties
 537 -----------------------------
 538
 539 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 540    :doc: standard connector properties
 541
 542 HDMI Specific Connector Properties
 543 ----------------------------------
 544
 545 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 546    :doc: HDMI connector properties
 547
 548 Plane Composition Properties
 549 ----------------------------
 550
 551 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 552    :doc: overview
 553
 554 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 555    :export:
 556
 557 FB_DAMAGE_CLIPS
 558 ~~~~~~~~~~~~~~~
 559
 560 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
 561    :doc: overview
 562
 563 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
 564    :export:
 565
 566 .. kernel-doc:: include/drm/drm_damage_helper.h
 567    :internal:
 568
 569 Color Management Properties
 570 ---------------------------
 571
 572 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 573    :doc: overview
 574
 575 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 576    :export:
 577
 578 Tile Group Property
 579 -------------------
 580
 581 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 582    :doc: Tile group
 583
 584 Explicit Fencing Properties
 585 ---------------------------
 586
 587 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 588    :doc: explicit fencing properties
 589
 590
 591 Variable Refresh Properties
 592 ---------------------------
 593
 594 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 595    :doc: Variable refresh properties
 596
 597 Existing KMS Properties
 598 -----------------------
 599
 600 The following table gives description of drm properties exposed by various
 601 modules/drivers. Because this table is very unwieldy, do not add any new
 602 properties here. Instead document them in a section above.
 603
 604 .. csv-table::
 605    :header-rows: 1
 606    :file: kms-properties.csv
 607
 608 Vertical Blanking
 609 =================
 610
 611 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 612    :doc: vblank handling
 613
 614 Vertical Blanking and Interrupt Handling Functions Reference
 615 ------------------------------------------------------------
 616
 617 .. kernel-doc:: include/drm/drm_vblank.h
 618    :internal:
 619
 620 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 621    :export: