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. Again drivers can subclass that container for their own state
 267   structure tracking needs. Only when a state is committed is it applied to the
 268   driver and modeset objects. This way rolling back an update boils down to
 269   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 Atomic Mode Setting Function Reference
 275 --------------------------------------
 276
 277 .. kernel-doc:: include/drm/drm_atomic.h
 278    :internal:
 279
 280 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 281    :export:
 282
 283 CRTC Abstraction
 284 ================
 285
 286 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 287    :doc: overview
 288
 289 CRTC Functions Reference
 290 --------------------------------
 291
 292 .. kernel-doc:: include/drm/drm_crtc.h
 293    :internal:
 294
 295 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 296    :export:
 297
 298 Frame Buffer Abstraction
 299 ========================
 300
 301 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 302    :doc: overview
 303
 304 Frame Buffer Functions Reference
 305 --------------------------------
 306
 307 .. kernel-doc:: include/drm/drm_framebuffer.h
 308    :internal:
 309
 310 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 311    :export:
 312
 313 DRM Format Handling
 314 ===================
 315
 316 .. kernel-doc:: include/drm/drm_fourcc.h
 317    :internal:
 318
 319 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
 320    :export:
 321
 322 Dumb Buffer Objects
 323 ===================
 324
 325 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
 326    :doc: overview
 327
 328 Plane Abstraction
 329 =================
 330
 331 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 332    :doc: overview
 333
 334 Plane Functions Reference
 335 -------------------------
 336
 337 .. kernel-doc:: include/drm/drm_plane.h
 338    :internal:
 339
 340 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 341    :export:
 342
 343 Display Modes Function Reference
 344 ================================
 345
 346 .. kernel-doc:: include/drm/drm_modes.h
 347    :internal:
 348
 349 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 350    :export:
 351
 352 Connector Abstraction
 353 =====================
 354
 355 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 356    :doc: overview
 357
 358 Connector Functions Reference
 359 -----------------------------
 360
 361 .. kernel-doc:: include/drm/drm_connector.h
 362    :internal:
 363
 364 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 365    :export:
 366
 367 Encoder Abstraction
 368 ===================
 369
 370 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 371    :doc: overview
 372
 373 Encoder Functions Reference
 374 ---------------------------
 375
 376 .. kernel-doc:: include/drm/drm_encoder.h
 377    :internal:
 378
 379 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 380    :export:
 381
 382 KMS Initialization and Cleanup
 383 ==============================
 384
 385 A KMS device is abstracted and exposed as a set of planes, CRTCs,
 386 encoders and connectors. KMS drivers must thus create and initialize all
 387 those objects at load time after initializing mode setting.
 388
 389 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
 390 --------------------------------------------
 391
 392 A CRTC is an abstraction representing a part of the chip that contains a
 393 pointer to a scanout buffer. Therefore, the number of CRTCs available
 394 determines how many independent scanout buffers can be active at any
 395 given time. The CRTC structure contains several fields to support this:
 396 a pointer to some video memory (abstracted as a frame buffer object), a
 397 display mode, and an (x, y) offset into the video memory to support
 398 panning or configurations where one piece of video memory spans multiple
 399 CRTCs.
 400
 401 CRTC Initialization
 402 ~~~~~~~~~~~~~~~~~~~
 403
 404 A KMS device must create and register at least one struct
 405 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
 406 allocated and zeroed by the driver, possibly as part of a larger
 407 structure, and registered with a call to :c:func:`drm_crtc_init()`
 408 with a pointer to CRTC functions.
 409
 410
 411 Cleanup
 412 -------
 413
 414 The DRM core manages its objects' lifetime. When an object is not needed
 415 anymore the core calls its destroy function, which must clean up and
 416 free every resource allocated for the object. Every
 417 :c:func:`drm_\*_init()` call must be matched with a corresponding
 418 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
 419 (:c:func:`drm_crtc_cleanup()`), planes
 420 (:c:func:`drm_plane_cleanup()`), encoders
 421 (:c:func:`drm_encoder_cleanup()`) and connectors
 422 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
 423 have been added to sysfs must be removed by a call to
 424 :c:func:`drm_connector_unregister()` before calling
 425 :c:func:`drm_connector_cleanup()`.
 426
 427 Connectors state change detection must be cleanup up with a call to
 428 :c:func:`drm_kms_helper_poll_fini()`.
 429
 430 Output discovery and initialization example
 431 -------------------------------------------
 432
 433 .. code-block:: c
 434
 435     void intel_crt_init(struct drm_device *dev)
 436     {
 437         struct drm_connector *connector;
 438         struct intel_output *intel_output;
 439
 440         intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
 441         if (!intel_output)
 442             return;
 443
 444         connector = &intel_output->base;
 445         drm_connector_init(dev, &intel_output->base,
 446                    &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
 447
 448         drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
 449                  DRM_MODE_ENCODER_DAC);
 450
 451         drm_mode_connector_attach_encoder(&intel_output->base,
 452                           &intel_output->enc);
 453
 454         /* Set up the DDC bus. */
 455         intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
 456         if (!intel_output->ddc_bus) {
 457             dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
 458                    "failed.\n");
 459             return;
 460         }
 461
 462         intel_output->type = INTEL_OUTPUT_ANALOG;
 463         connector->interlace_allowed = 0;
 464         connector->doublescan_allowed = 0;
 465
 466         drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
 467         drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
 468
 469         drm_connector_register(connector);
 470     }
 471
 472 In the example above (taken from the i915 driver), a CRTC, connector and
 473 encoder combination is created. A device-specific i2c bus is also
 474 created for fetching EDID data and performing monitor detection. Once
 475 the process is complete, the new connector is registered with sysfs to
 476 make its properties available to applications.
 477
 478 KMS Locking
 479 ===========
 480
 481 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 482    :doc: kms locking
 483
 484 .. kernel-doc:: include/drm/drm_modeset_lock.h
 485    :internal:
 486
 487 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 488    :export:
 489
 490 KMS Properties
 491 ==============
 492
 493 Property Types and Blob Property Support
 494 ----------------------------------------
 495
 496 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 497    :doc: overview
 498
 499 .. kernel-doc:: include/drm/drm_property.h
 500    :internal:
 501
 502 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 503    :export:
 504
 505 Standard Connector Properties
 506 -----------------------------
 507
 508 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 509    :doc: standard connector properties
 510
 511 Plane Composition Properties
 512 ----------------------------
 513
 514 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 515    :doc: overview
 516
 517 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 518    :export:
 519
 520 Color Management Properties
 521 ---------------------------
 522
 523 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 524    :doc: overview
 525
 526 .. kernel-doc:: include/drm/drm_color_mgmt.h
 527    :internal:
 528
 529 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 530    :export:
 531
 532 Tile Group Property
 533 -------------------
 534
 535 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 536    :doc: Tile group
 537
 538 Explicit Fencing Properties
 539 ---------------------------
 540
 541 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 542    :doc: explicit fencing properties
 543
 544 Existing KMS Properties
 545 -----------------------
 546
 547 The following table gives description of drm properties exposed by
 548 various modules/drivers.
 549
 550 .. csv-table::
 551    :header-rows: 1
 552    :file: kms-properties.csv
 553
 554 Vertical Blanking
 555 =================
 556
 557 Vertical blanking plays a major role in graphics rendering. To achieve
 558 tear-free display, users must synchronize page flips and/or rendering to
 559 vertical blanking. The DRM API offers ioctls to perform page flips
 560 synchronized to vertical blanking and wait for vertical blanking.
 561
 562 The DRM core handles most of the vertical blanking management logic,
 563 which involves filtering out spurious interrupts, keeping race-free
 564 blanking counters, coping with counter wrap-around and resets and
 565 keeping use counts. It relies on the driver to generate vertical
 566 blanking interrupts and optionally provide a hardware vertical blanking
 567 counter. Drivers must implement the following operations.
 568
 569 -  int (\*enable_vblank) (struct drm_device \*dev, int crtc); void
 570    (\*disable_vblank) (struct drm_device \*dev, int crtc);
 571    Enable or disable vertical blanking interrupts for the given CRTC.
 572
 573 -  u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc);
 574    Retrieve the value of the vertical blanking counter for the given
 575    CRTC. If the hardware maintains a vertical blanking counter its value
 576    should be returned. Otherwise drivers can use the
 577    :c:func:`drm_vblank_count()` helper function to handle this
 578    operation.
 579
 580 Drivers must initialize the vertical blanking handling core with a call
 581 to :c:func:`drm_vblank_init()` in their load operation.
 582
 583 Vertical blanking interrupts can be enabled by the DRM core or by
 584 drivers themselves (for instance to handle page flipping operations).
 585 The DRM core maintains a vertical blanking use count to ensure that the
 586 interrupts are not disabled while a user still needs them. To increment
 587 the use count, drivers call :c:func:`drm_vblank_get()`. Upon
 588 return vertical blanking interrupts are guaranteed to be enabled.
 589
 590 To decrement the use count drivers call
 591 :c:func:`drm_vblank_put()`. Only when the use count drops to zero
 592 will the DRM core disable the vertical blanking interrupts after a delay
 593 by scheduling a timer. The delay is accessible through the
 594 vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global
 595 variable and expressed in milliseconds. Its default value is 5000 ms.
 596 Zero means never disable, and a negative value means disable
 597 immediately. Drivers may override the behaviour by setting the
 598 :c:type:`struct drm_device <drm_device>`
 599 vblank_disable_immediate flag, which when set causes vblank interrupts
 600 to be disabled immediately regardless of the drm_vblank_offdelay
 601 value. The flag should only be set if there's a properly working
 602 hardware vblank counter present.
 603
 604 When a vertical blanking interrupt occurs drivers only need to call the
 605 :c:func:`drm_handle_vblank()` function to account for the
 606 interrupt.
 607
 608 Resources allocated by :c:func:`drm_vblank_init()` must be freed
 609 with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
 610 operation handler.
 611
 612 Vertical Blanking and Interrupt Handling Functions Reference
 613 ------------------------------------------------------------
 614
 615 .. kernel-doc:: include/drm/drm_vblank.h
 616    :internal:
 617
 618 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 619    :export: