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 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 291    :internal:
 292
 293 CRTC Abstraction
 294 ================
 295
 296 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 297    :doc: overview
 298
 299 CRTC Functions Reference
 300 --------------------------------
 301
 302 .. kernel-doc:: include/drm/drm_crtc.h
 303    :internal:
 304
 305 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 306    :export:
 307
 308 Frame Buffer Abstraction
 309 ========================
 310
 311 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 312    :doc: overview
 313
 314 Frame Buffer Functions Reference
 315 --------------------------------
 316
 317 .. kernel-doc:: include/drm/drm_framebuffer.h
 318    :internal:
 319
 320 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 321    :export:
 322
 323 DRM Format Handling
 324 ===================
 325
 326 .. kernel-doc:: include/drm/drm_fourcc.h
 327    :internal:
 328
 329 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
 330    :export:
 331
 332 Dumb Buffer Objects
 333 ===================
 334
 335 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
 336    :doc: overview
 337
 338 Plane Abstraction
 339 =================
 340
 341 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 342    :doc: overview
 343
 344 Plane Functions Reference
 345 -------------------------
 346
 347 .. kernel-doc:: include/drm/drm_plane.h
 348    :internal:
 349
 350 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 351    :export:
 352
 353 Display Modes Function Reference
 354 ================================
 355
 356 .. kernel-doc:: include/drm/drm_modes.h
 357    :internal:
 358
 359 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 360    :export:
 361
 362 Connector Abstraction
 363 =====================
 364
 365 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 366    :doc: overview
 367
 368 Connector Functions Reference
 369 -----------------------------
 370
 371 .. kernel-doc:: include/drm/drm_connector.h
 372    :internal:
 373
 374 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 375    :export:
 376
 377 Writeback Connectors
 378 --------------------
 379
 380 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 381   :doc: overview
 382
 383 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 384   :export:
 385
 386 Encoder Abstraction
 387 ===================
 388
 389 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 390    :doc: overview
 391
 392 Encoder Functions Reference
 393 ---------------------------
 394
 395 .. kernel-doc:: include/drm/drm_encoder.h
 396    :internal:
 397
 398 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 399    :export:
 400
 401 KMS Initialization and Cleanup
 402 ==============================
 403
 404 A KMS device is abstracted and exposed as a set of planes, CRTCs,
 405 encoders and connectors. KMS drivers must thus create and initialize all
 406 those objects at load time after initializing mode setting.
 407
 408 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
 409 --------------------------------------------
 410
 411 A CRTC is an abstraction representing a part of the chip that contains a
 412 pointer to a scanout buffer. Therefore, the number of CRTCs available
 413 determines how many independent scanout buffers can be active at any
 414 given time. The CRTC structure contains several fields to support this:
 415 a pointer to some video memory (abstracted as a frame buffer object), a
 416 display mode, and an (x, y) offset into the video memory to support
 417 panning or configurations where one piece of video memory spans multiple
 418 CRTCs.
 419
 420 CRTC Initialization
 421 ~~~~~~~~~~~~~~~~~~~
 422
 423 A KMS device must create and register at least one struct
 424 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
 425 allocated and zeroed by the driver, possibly as part of a larger
 426 structure, and registered with a call to :c:func:`drm_crtc_init()`
 427 with a pointer to CRTC functions.
 428
 429
 430 Cleanup
 431 -------
 432
 433 The DRM core manages its objects' lifetime. When an object is not needed
 434 anymore the core calls its destroy function, which must clean up and
 435 free every resource allocated for the object. Every
 436 :c:func:`drm_\*_init()` call must be matched with a corresponding
 437 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
 438 (:c:func:`drm_crtc_cleanup()`), planes
 439 (:c:func:`drm_plane_cleanup()`), encoders
 440 (:c:func:`drm_encoder_cleanup()`) and connectors
 441 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
 442 have been added to sysfs must be removed by a call to
 443 :c:func:`drm_connector_unregister()` before calling
 444 :c:func:`drm_connector_cleanup()`.
 445
 446 Connectors state change detection must be cleanup up with a call to
 447 :c:func:`drm_kms_helper_poll_fini()`.
 448
 449 Output discovery and initialization example
 450 -------------------------------------------
 451
 452 .. code-block:: c
 453
 454     void intel_crt_init(struct drm_device *dev)
 455     {
 456         struct drm_connector *connector;
 457         struct intel_output *intel_output;
 458
 459         intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
 460         if (!intel_output)
 461             return;
 462
 463         connector = &intel_output->base;
 464         drm_connector_init(dev, &intel_output->base,
 465                    &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
 466
 467         drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
 468                  DRM_MODE_ENCODER_DAC);
 469
 470         drm_connector_attach_encoder(&intel_output->base,
 471                           &intel_output->enc);
 472
 473         /* Set up the DDC bus. */
 474         intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
 475         if (!intel_output->ddc_bus) {
 476             dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
 477                    "failed.\n");
 478             return;
 479         }
 480
 481         intel_output->type = INTEL_OUTPUT_ANALOG;
 482         connector->interlace_allowed = 0;
 483         connector->doublescan_allowed = 0;
 484
 485         drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
 486         drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
 487
 488         drm_connector_register(connector);
 489     }
 490
 491 In the example above (taken from the i915 driver), a CRTC, connector and
 492 encoder combination is created. A device-specific i2c bus is also
 493 created for fetching EDID data and performing monitor detection. Once
 494 the process is complete, the new connector is registered with sysfs to
 495 make its properties available to applications.
 496
 497 KMS Locking
 498 ===========
 499
 500 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 501    :doc: kms locking
 502
 503 .. kernel-doc:: include/drm/drm_modeset_lock.h
 504    :internal:
 505
 506 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 507    :export:
 508
 509 KMS Properties
 510 ==============
 511
 512 Property Types and Blob Property Support
 513 ----------------------------------------
 514
 515 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 516    :doc: overview
 517
 518 .. kernel-doc:: include/drm/drm_property.h
 519    :internal:
 520
 521 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 522    :export:
 523
 524 Standard Connector Properties
 525 -----------------------------
 526
 527 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 528    :doc: standard connector properties
 529
 530 HDMI Specific Connector Properties
 531 ----------------------------------
 532
 533 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 534    :doc: HDMI connector properties
 535
 536 Plane Composition Properties
 537 ----------------------------
 538
 539 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 540    :doc: overview
 541
 542 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 543    :export:
 544
 545 Color Management Properties
 546 ---------------------------
 547
 548 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 549    :doc: overview
 550
 551 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 552    :export:
 553
 554 Tile Group Property
 555 -------------------
 556
 557 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 558    :doc: Tile group
 559
 560 Explicit Fencing Properties
 561 ---------------------------
 562
 563 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 564    :doc: explicit fencing properties
 565
 566 Existing KMS Properties
 567 -----------------------
 568
 569 The following table gives description of drm properties exposed by various
 570 modules/drivers. Because this table is very unwieldy, do not add any new
 571 properties here. Instead document them in a section above.
 572
 573 .. csv-table::
 574    :header-rows: 1
 575    :file: kms-properties.csv
 576
 577 Vertical Blanking
 578 =================
 579
 580 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 581    :doc: vblank handling
 582
 583 Vertical Blanking and Interrupt Handling Functions Reference
 584 ------------------------------------------------------------
 585
 586 .. kernel-doc:: include/drm/drm_vblank.h
 587    :internal:
 588
 589 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 590    :export: