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. One or more (or even no)
  60 planes feed their pixel data into a CRTC (represented by :c:type:`struct
  61 drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise
  62 blending step is explained in more detail in `Plane Composition Properties`_ and
  63 related chapters.
  64
  65 For the output routing the first step is encoders (represented by
  66 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
  67 are really just internal artifacts of the helper libraries used to implement KMS
  68 drivers. Besides that they make it unecessarily more complicated for userspace
  69 to figure out which connections between a CRTC and a connector are possible, and
  70 what kind of cloning is supported, they serve no purpose in the userspace API.
  71 Unfortunately encoders have been exposed to userspace, hence can't remove them
  72 at this point.  Futhermore the exposed restrictions are often wrongly set by
  73 drivers, and in many cases not powerful enough to express the real restrictions.
  74 A CRTC can be connected to multiple encoders, and for an active CRTC there must
  75 be at least one encoder.
  76
  77 The final, and real, endpoint in the display chain is the connector (represented
  78 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
  79 Abstraction`_). Connectors can have different possible encoders, but the kernel
  80 driver selects which encoder to use for each connector. The use case is DVI,
  81 which could switch between an analog and a digital encoder. Encoders can also
  82 drive multiple different connectors. There is exactly one active connector for
  83 every active encoder.
  84
  85 Internally the output pipeline is a bit more complex and matches today's
  86 hardware more closely:
  87
  88 .. kernel-render:: DOT
  89    :alt: KMS Output Pipeline
  90    :caption: KMS Output Pipeline
  91
  92    digraph "Output Pipeline" {
  93       node [shape=box]
  94
  95       subgraph {
  96           "drm_crtc" [bgcolor=grey style=filled]
  97       }
  98
  99       subgraph cluster_internal {
 100           style=dashed
 101           label="Internal Pipeline"
 102           {
 103               node [bgcolor=grey style=filled]
 104               "drm_encoder A";
 105               "drm_encoder B";
 106               "drm_encoder C";
 107           }
 108
 109           {
 110               node [bgcolor=grey style=filled]
 111               "drm_encoder B" -> "drm_bridge B"
 112               "drm_encoder C" -> "drm_bridge C1"
 113               "drm_bridge C1" -> "drm_bridge C2";
 114           }
 115       }
 116
 117       "drm_crtc" -> "drm_encoder A"
 118       "drm_crtc" -> "drm_encoder B"
 119       "drm_crtc" -> "drm_encoder C"
 120
 121
 122       subgraph cluster_output {
 123           style=dashed
 124           label="Outputs"
 125
 126           "drm_encoder A" -> "drm_connector A";
 127           "drm_bridge B" -> "drm_connector B";
 128           "drm_bridge C2" -> "drm_connector C";
 129
 130           "drm_panel"
 131       }
 132    }
 133
 134 Internally two additional helper objects come into play. First, to be able to
 135 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
 136 more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge
 137 <drm_bridge>`) can be linked to an encoder. This link is static and cannot be
 138 changed, which means the cross-bar (if there is any) needs to be mapped between
 139 the CRTC and any encoders. Often for drivers with bridges there's no code left
 140 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
 141 essentially only leave a dummy routing object behind, which is needed for
 142 backwards compatibility since encoders are exposed to userspace.
 143
 144 The second object is for panels, represented by :c:type:`struct drm_panel
 145 <drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding
 146 point, but are generally linked to the driver private structure that embeds
 147 :c:type:`struct drm_connector <drm_connector>`.
 148
 149 Note that currently the bridge chaining and interactions with connectors and
 150 panels are still in-flux and not really fully sorted out yet.
 151
 152 KMS Core Structures and Functions
 153 =================================
 154
 155 .. kernel-doc:: include/drm/drm_mode_config.h
 156    :internal:
 157
 158 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
 159    :export:
 160
 161 Modeset Base Object Abstraction
 162 ===============================
 163
 164 .. kernel-render:: DOT
 165    :alt: Mode Objects and Properties
 166    :caption: Mode Objects and Properties
 167
 168    digraph {
 169       node [shape=box]
 170
 171       "drm_property A" -> "drm_mode_object A"
 172       "drm_property A" -> "drm_mode_object B"
 173       "drm_property B" -> "drm_mode_object A"
 174    }
 175
 176 The base structure for all KMS objects is :c:type:`struct drm_mode_object
 177 <drm_mode_object>`. One of the base services it provides is tracking properties,
 178 which are especially important for the atomic IOCTL (see `Atomic Mode
 179 Setting`_). The somewhat surprising part here is that properties are not
 180 directly instantiated on each object, but free-standing mode objects themselves,
 181 represented by :c:type:`struct drm_property <drm_property>`, which only specify
 182 the type and value range of a property. Any given property can be attached
 183 multiple times to different objects using :c:func:`drm_object_attach_property()
 184 <drm_object_attach_property>`.
 185
 186 .. kernel-doc:: include/drm/drm_mode_object.h
 187    :internal:
 188
 189 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
 190    :export:
 191
 192 Atomic Mode Setting
 193 ===================
 194
 195
 196 .. kernel-render:: DOT
 197    :alt: Mode Objects and Properties
 198    :caption: Mode Objects and Properties
 199
 200    digraph {
 201       node [shape=box]
 202
 203       subgraph cluster_state {
 204           style=dashed
 205           label="Free-standing state"
 206
 207           "drm_atomic_state" -> "duplicated drm_plane_state A"
 208           "drm_atomic_state" -> "duplicated drm_plane_state B"
 209           "drm_atomic_state" -> "duplicated drm_crtc_state"
 210           "drm_atomic_state" -> "duplicated drm_connector_state"
 211           "drm_atomic_state" -> "duplicated driver private state"
 212       }
 213
 214       subgraph cluster_current {
 215           style=dashed
 216           label="Current state"
 217
 218           "drm_device" -> "drm_plane A"
 219           "drm_device" -> "drm_plane B"
 220           "drm_device" -> "drm_crtc"
 221           "drm_device" -> "drm_connector"
 222           "drm_device" -> "driver private object"
 223
 224           "drm_plane A" -> "drm_plane_state A"
 225           "drm_plane B" -> "drm_plane_state B"
 226           "drm_crtc" -> "drm_crtc_state"
 227           "drm_connector" -> "drm_connector_state"
 228           "driver private object" -> "driver private state"
 229       }
 230
 231       "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
 232       "duplicated drm_plane_state A" -> "drm_device"[style=invis]
 233    }
 234
 235 Atomic provides transactional modeset (including planes) updates, but a
 236 bit differently from the usual transactional approach of try-commit and
 237 rollback:
 238
 239 - Firstly, no hardware changes are allowed when the commit would fail. This
 240   allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
 241   userspace to explore whether certain configurations would work or not.
 242
 243 - This would still allow setting and rollback of just the software state,
 244   simplifying conversion of existing drivers. But auditing drivers for
 245   correctness of the atomic_check code becomes really hard with that: Rolling
 246   back changes in data structures all over the place is hard to get right.
 247
 248 - Lastly, for backwards compatibility and to support all use-cases, atomic
 249   updates need to be incremental and be able to execute in parallel. Hardware
 250   doesn't always allow it, but where possible plane updates on different CRTCs
 251   should not interfere, and not get stalled due to output routing changing on
 252   different CRTCs.
 253
 254 Taken all together there's two consequences for the atomic design:
 255
 256 - The overall state is split up into per-object state structures:
 257   :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
 258   drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
 259   drm_connector_state <drm_connector_state>` for connectors. These are the only
 260   objects with userspace-visible and settable state. For internal state drivers
 261   can subclass these structures through embeddeding, or add entirely new state
 262   structures for their globally shared hardware functions.
 263
 264 - An atomic update is assembled and validated as an entirely free-standing pile
 265   of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
 266   container. Driver private state structures are also tracked in the same
 267   structure; see the next chapter.  Only when a state is committed is it applied
 268   to the driver and modeset objects. This way rolling back an update boils down
 269   to releasing memory and unreferencing objects like framebuffers.
 270
 271 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
 272 coverage of specific topics.
 273
 274 Handling Driver Private State
 275 -----------------------------
 276
 277 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 278    :doc: handling driver private state
 279
 280 Atomic Mode Setting Function Reference
 281 --------------------------------------
 282
 283 .. kernel-doc:: include/drm/drm_atomic.h
 284    :internal:
 285
 286 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 287    :export:
 288
 289 CRTC Abstraction
 290 ================
 291
 292 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 293    :doc: overview
 294
 295 CRTC Functions Reference
 296 --------------------------------
 297
 298 .. kernel-doc:: include/drm/drm_crtc.h
 299    :internal:
 300
 301 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 302    :export:
 303
 304 Frame Buffer Abstraction
 305 ========================
 306
 307 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 308    :doc: overview
 309
 310 Frame Buffer Functions Reference
 311 --------------------------------
 312
 313 .. kernel-doc:: include/drm/drm_framebuffer.h
 314    :internal:
 315
 316 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 317    :export:
 318
 319 DRM Format Handling
 320 ===================
 321
 322 .. kernel-doc:: include/drm/drm_fourcc.h
 323    :internal:
 324
 325 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
 326    :export:
 327
 328 Dumb Buffer Objects
 329 ===================
 330
 331 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
 332    :doc: overview
 333
 334 Plane Abstraction
 335 =================
 336
 337 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 338    :doc: overview
 339
 340 Plane Functions Reference
 341 -------------------------
 342
 343 .. kernel-doc:: include/drm/drm_plane.h
 344    :internal:
 345
 346 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 347    :export:
 348
 349 Display Modes Function Reference
 350 ================================
 351
 352 .. kernel-doc:: include/drm/drm_modes.h
 353    :internal:
 354
 355 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 356    :export:
 357
 358 Connector Abstraction
 359 =====================
 360
 361 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 362    :doc: overview
 363
 364 Connector Functions Reference
 365 -----------------------------
 366
 367 .. kernel-doc:: include/drm/drm_connector.h
 368    :internal:
 369
 370 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 371    :export:
 372
 373 Encoder Abstraction
 374 ===================
 375
 376 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 377    :doc: overview
 378
 379 Encoder Functions Reference
 380 ---------------------------
 381
 382 .. kernel-doc:: include/drm/drm_encoder.h
 383    :internal:
 384
 385 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 386    :export:
 387
 388 KMS Initialization and Cleanup
 389 ==============================
 390
 391 A KMS device is abstracted and exposed as a set of planes, CRTCs,
 392 encoders and connectors. KMS drivers must thus create and initialize all
 393 those objects at load time after initializing mode setting.
 394
 395 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
 396 --------------------------------------------
 397
 398 A CRTC is an abstraction representing a part of the chip that contains a
 399 pointer to a scanout buffer. Therefore, the number of CRTCs available
 400 determines how many independent scanout buffers can be active at any
 401 given time. The CRTC structure contains several fields to support this:
 402 a pointer to some video memory (abstracted as a frame buffer object), a
 403 display mode, and an (x, y) offset into the video memory to support
 404 panning or configurations where one piece of video memory spans multiple
 405 CRTCs.
 406
 407 CRTC Initialization
 408 ~~~~~~~~~~~~~~~~~~~
 409
 410 A KMS device must create and register at least one struct
 411 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
 412 allocated and zeroed by the driver, possibly as part of a larger
 413 structure, and registered with a call to :c:func:`drm_crtc_init()`
 414 with a pointer to CRTC functions.
 415
 416
 417 Cleanup
 418 -------
 419
 420 The DRM core manages its objects' lifetime. When an object is not needed
 421 anymore the core calls its destroy function, which must clean up and
 422 free every resource allocated for the object. Every
 423 :c:func:`drm_\*_init()` call must be matched with a corresponding
 424 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
 425 (:c:func:`drm_crtc_cleanup()`), planes
 426 (:c:func:`drm_plane_cleanup()`), encoders
 427 (:c:func:`drm_encoder_cleanup()`) and connectors
 428 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
 429 have been added to sysfs must be removed by a call to
 430 :c:func:`drm_connector_unregister()` before calling
 431 :c:func:`drm_connector_cleanup()`.
 432
 433 Connectors state change detection must be cleanup up with a call to
 434 :c:func:`drm_kms_helper_poll_fini()`.
 435
 436 Output discovery and initialization example
 437 -------------------------------------------
 438
 439 .. code-block:: c
 440
 441     void intel_crt_init(struct drm_device *dev)
 442     {
 443         struct drm_connector *connector;
 444         struct intel_output *intel_output;
 445
 446         intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
 447         if (!intel_output)
 448             return;
 449
 450         connector = &intel_output->base;
 451         drm_connector_init(dev, &intel_output->base,
 452                    &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
 453
 454         drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
 455                  DRM_MODE_ENCODER_DAC);
 456
 457         drm_mode_connector_attach_encoder(&intel_output->base,
 458                           &intel_output->enc);
 459
 460         /* Set up the DDC bus. */
 461         intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
 462         if (!intel_output->ddc_bus) {
 463             dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
 464                    "failed.\n");
 465             return;
 466         }
 467
 468         intel_output->type = INTEL_OUTPUT_ANALOG;
 469         connector->interlace_allowed = 0;
 470         connector->doublescan_allowed = 0;
 471
 472         drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
 473         drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
 474
 475         drm_connector_register(connector);
 476     }
 477
 478 In the example above (taken from the i915 driver), a CRTC, connector and
 479 encoder combination is created. A device-specific i2c bus is also
 480 created for fetching EDID data and performing monitor detection. Once
 481 the process is complete, the new connector is registered with sysfs to
 482 make its properties available to applications.
 483
 484 KMS Locking
 485 ===========
 486
 487 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 488    :doc: kms locking
 489
 490 .. kernel-doc:: include/drm/drm_modeset_lock.h
 491    :internal:
 492
 493 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 494    :export:
 495
 496 KMS Properties
 497 ==============
 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
 514 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 515    :doc: standard connector properties
 516
 517 Plane Composition Properties
 518 ----------------------------
 519
 520 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 521    :doc: overview
 522
 523 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 524    :export:
 525
 526 Color Management Properties
 527 ---------------------------
 528
 529 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 530    :doc: overview
 531
 532 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 533    :export:
 534
 535 Tile Group Property
 536 -------------------
 537
 538 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 539    :doc: Tile group
 540
 541 Explicit Fencing Properties
 542 ---------------------------
 543
 544 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 545    :doc: explicit fencing properties
 546
 547 Existing KMS Properties
 548 -----------------------
 549
 550 The following table gives description of drm properties exposed by
 551 various modules/drivers.
 552
 553 .. csv-table::
 554    :header-rows: 1
 555    :file: kms-properties.csv
 556
 557 Vertical Blanking
 558 =================
 559
 560 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 561    :doc: vblank handling
 562
 563 Vertical Blanking and Interrupt Handling Functions Reference
 564 ------------------------------------------------------------
 565
 566 .. kernel-doc:: include/drm/drm_vblank.h
 567    :internal:
 568
 569 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 570    :export: