Documentation/gpu/drm-kms.rst

   1 =========================
   2 Kernel Mode Setting (KMS)
   3 =========================
   4
   5 Drivers must initialize the mode setting core by calling
   6 drmm_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 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, see :c:type:`struct
 263   drm_private_state<drm_private_state>`.
 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 Locking of atomic state structures is internally using :c:type:`struct
 273 drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
 274 exposed to drivers, instead the right locks should be automatically acquired by
 275 any function that duplicates or peeks into a state, like e.g.
 276 drm_atomic_get_crtc_state().  Locking only protects the software data
 277 structure, ordering of committing state changes to hardware is sequenced using
 278 :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
 279
 280 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
 281 coverage of specific topics.
 282
 283 Handling Driver Private State
 284 -----------------------------
 285
 286 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 287    :doc: handling driver private state
 288
 289 Atomic Mode Setting Function Reference
 290 --------------------------------------
 291
 292 .. kernel-doc:: include/drm/drm_atomic.h
 293    :internal:
 294
 295 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
 296    :export:
 297
 298 Atomic Mode Setting IOCTL and UAPI Functions
 299 --------------------------------------------
 300
 301 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 302    :doc: overview
 303
 304 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 305    :export:
 306
 307 CRTC Abstraction
 308 ================
 309
 310 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 311    :doc: overview
 312
 313 CRTC Functions Reference
 314 --------------------------------
 315
 316 .. kernel-doc:: include/drm/drm_crtc.h
 317    :internal:
 318
 319 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
 320    :export:
 321
 322 Frame Buffer Abstraction
 323 ========================
 324
 325 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 326    :doc: overview
 327
 328 Frame Buffer Functions Reference
 329 --------------------------------
 330
 331 .. kernel-doc:: include/drm/drm_framebuffer.h
 332    :internal:
 333
 334 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
 335    :export:
 336
 337 DRM Format Handling
 338 ===================
 339
 340 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
 341    :doc: overview
 342
 343 Format Functions Reference
 344 --------------------------
 345
 346 .. kernel-doc:: include/drm/drm_fourcc.h
 347    :internal:
 348
 349 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
 350    :export:
 351
 352 Dumb Buffer Objects
 353 ===================
 354
 355 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
 356    :doc: overview
 357
 358 Plane Abstraction
 359 =================
 360
 361 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 362    :doc: overview
 363
 364 Plane Functions Reference
 365 -------------------------
 366
 367 .. kernel-doc:: include/drm/drm_plane.h
 368    :internal:
 369
 370 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
 371    :export:
 372
 373 Display Modes Function Reference
 374 ================================
 375
 376 .. kernel-doc:: include/drm/drm_modes.h
 377    :internal:
 378
 379 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
 380    :export:
 381
 382 Connector Abstraction
 383 =====================
 384
 385 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 386    :doc: overview
 387
 388 Connector Functions Reference
 389 -----------------------------
 390
 391 .. kernel-doc:: include/drm/drm_connector.h
 392    :internal:
 393
 394 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 395    :export:
 396
 397 Writeback Connectors
 398 --------------------
 399
 400 .. kernel-doc:: include/drm/drm_writeback.h
 401   :internal:
 402
 403 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 404   :doc: overview
 405
 406 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
 407   :export:
 408
 409 Encoder Abstraction
 410 ===================
 411
 412 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 413    :doc: overview
 414
 415 Encoder Functions Reference
 416 ---------------------------
 417
 418 .. kernel-doc:: include/drm/drm_encoder.h
 419    :internal:
 420
 421 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
 422    :export:
 423
 424 KMS Locking
 425 ===========
 426
 427 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 428    :doc: kms locking
 429
 430 .. kernel-doc:: include/drm/drm_modeset_lock.h
 431    :internal:
 432
 433 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
 434    :export:
 435
 436 KMS Properties
 437 ==============
 438
 439 Property Types and Blob Property Support
 440 ----------------------------------------
 441
 442 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 443    :doc: overview
 444
 445 .. kernel-doc:: include/drm/drm_property.h
 446    :internal:
 447
 448 .. kernel-doc:: drivers/gpu/drm/drm_property.c
 449    :export:
 450
 451 Standard Connector Properties
 452 -----------------------------
 453
 454 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 455    :doc: standard connector properties
 456
 457 HDMI Specific Connector Properties
 458 ----------------------------------
 459
 460 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 461    :doc: HDMI connector properties
 462
 463 Plane Composition Properties
 464 ----------------------------
 465
 466 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 467    :doc: overview
 468
 469 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
 470    :export:
 471
 472 FB_DAMAGE_CLIPS
 473 ~~~~~~~~~~~~~~~
 474
 475 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
 476    :doc: overview
 477
 478 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
 479    :export:
 480
 481 .. kernel-doc:: include/drm/drm_damage_helper.h
 482    :internal:
 483
 484 Color Management Properties
 485 ---------------------------
 486
 487 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 488    :doc: overview
 489
 490 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
 491    :export:
 492
 493 .. kernel-doc:: include/drm/drm_color_mgmt.h
 494    :internal:
 495
 496 Tile Group Property
 497 -------------------
 498
 499 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 500    :doc: Tile group
 501
 502 Explicit Fencing Properties
 503 ---------------------------
 504
 505 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
 506    :doc: explicit fencing properties
 507
 508
 509 Variable Refresh Properties
 510 ---------------------------
 511
 512 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
 513    :doc: Variable refresh properties
 514
 515 Existing KMS Properties
 516 -----------------------
 517
 518 The following table gives description of drm properties exposed by various
 519 modules/drivers. Because this table is very unwieldy, do not add any new
 520 properties here. Instead document them in a section above.
 521
 522 .. csv-table::
 523    :header-rows: 1
 524    :file: kms-properties.csv
 525
 526 Vertical Blanking
 527 =================
 528
 529 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 530    :doc: vblank handling
 531
 532 Vertical Blanking and Interrupt Handling Functions Reference
 533 ------------------------------------------------------------
 534
 535 .. kernel-doc:: include/drm/drm_vblank.h
 536    :internal:
 537
 538 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
 539    :export: