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