drm-kms.rst (18350B)
1========================= 2Kernel Mode Setting (KMS) 3========================= 4 5Drivers must initialize the mode setting core by calling 6drmm_mode_config_init() on the DRM device. The function 7initializes the :c:type:`struct drm_device <drm_device>` 8mode_config field and never fails. Once done, mode configuration must 9be 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 18Overview 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 57The basic object structure KMS presents to userspace is fairly simple. 58Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`, 59see `Frame Buffer Abstraction`_) feed into planes. Planes are represented by 60:c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more 61details. 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`_) 63for blending. The precise blending step is explained in more detail in `Plane 64Composition Properties`_ and related chapters. 65 66For the output routing the first step is encoders (represented by 67:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those 68are really just internal artifacts of the helper libraries used to implement KMS 69drivers. Besides that they make it unecessarily more complicated for userspace 70to figure out which connections between a CRTC and a connector are possible, and 71what kind of cloning is supported, they serve no purpose in the userspace API. 72Unfortunately encoders have been exposed to userspace, hence can't remove them 73at this point. Futhermore the exposed restrictions are often wrongly set by 74drivers, and in many cases not powerful enough to express the real restrictions. 75A CRTC can be connected to multiple encoders, and for an active CRTC there must 76be at least one encoder. 77 78The final, and real, endpoint in the display chain is the connector (represented 79by :c:type:`struct drm_connector <drm_connector>`, see `Connector 80Abstraction`_). Connectors can have different possible encoders, but the kernel 81driver selects which encoder to use for each connector. The use case is DVI, 82which could switch between an analog and a digital encoder. Encoders can also 83drive multiple different connectors. There is exactly one active connector for 84every active encoder. 85 86Internally the output pipeline is a bit more complex and matches today's 87hardware 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 135Internally two additional helper objects come into play. First, to be able to 136share code for encoders (sometimes on the same SoC, sometimes off-chip) one or 137more :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 139changed, which means the cross-bar (if there is any) needs to be mapped between 140the CRTC and any encoders. Often for drivers with bridges there's no code left 141at the encoder level. Atomic drivers can leave out all the encoder callbacks to 142essentially only leave a dummy routing object behind, which is needed for 143backwards compatibility since encoders are exposed to userspace. 144 145The 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 147point, but are generally linked to the driver private structure that embeds 148:c:type:`struct drm_connector <drm_connector>`. 149 150Note that currently the bridge chaining and interactions with connectors and 151panels are still in-flux and not really fully sorted out yet. 152 153KMS 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.. _kms_base_object_abstraction: 163 164Modeset Base Object Abstraction 165=============================== 166 167.. kernel-render:: DOT 168 :alt: Mode Objects and Properties 169 :caption: Mode Objects and Properties 170 171 digraph { 172 node [shape=box] 173 174 "drm_property A" -> "drm_mode_object A" 175 "drm_property A" -> "drm_mode_object B" 176 "drm_property B" -> "drm_mode_object A" 177 } 178 179The base structure for all KMS objects is :c:type:`struct drm_mode_object 180<drm_mode_object>`. One of the base services it provides is tracking properties, 181which are especially important for the atomic IOCTL (see `Atomic Mode 182Setting`_). The somewhat surprising part here is that properties are not 183directly instantiated on each object, but free-standing mode objects themselves, 184represented by :c:type:`struct drm_property <drm_property>`, which only specify 185the type and value range of a property. Any given property can be attached 186multiple times to different objects using drm_object_attach_property(). 187 188.. kernel-doc:: include/drm/drm_mode_object.h 189 :internal: 190 191.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c 192 :export: 193 194Atomic Mode Setting 195=================== 196 197 198.. kernel-render:: DOT 199 :alt: Mode Objects and Properties 200 :caption: Mode Objects and Properties 201 202 digraph { 203 node [shape=box] 204 205 subgraph cluster_state { 206 style=dashed 207 label="Free-standing state" 208 209 "drm_atomic_state" -> "duplicated drm_plane_state A" 210 "drm_atomic_state" -> "duplicated drm_plane_state B" 211 "drm_atomic_state" -> "duplicated drm_crtc_state" 212 "drm_atomic_state" -> "duplicated drm_connector_state" 213 "drm_atomic_state" -> "duplicated driver private state" 214 } 215 216 subgraph cluster_current { 217 style=dashed 218 label="Current state" 219 220 "drm_device" -> "drm_plane A" 221 "drm_device" -> "drm_plane B" 222 "drm_device" -> "drm_crtc" 223 "drm_device" -> "drm_connector" 224 "drm_device" -> "driver private object" 225 226 "drm_plane A" -> "drm_plane_state A" 227 "drm_plane B" -> "drm_plane_state B" 228 "drm_crtc" -> "drm_crtc_state" 229 "drm_connector" -> "drm_connector_state" 230 "driver private object" -> "driver private state" 231 } 232 233 "drm_atomic_state" -> "drm_device" [label="atomic_commit"] 234 "duplicated drm_plane_state A" -> "drm_device"[style=invis] 235 } 236 237Atomic provides transactional modeset (including planes) updates, but a 238bit differently from the usual transactional approach of try-commit and 239rollback: 240 241- Firstly, no hardware changes are allowed when the commit would fail. This 242 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows 243 userspace to explore whether certain configurations would work or not. 244 245- This would still allow setting and rollback of just the software state, 246 simplifying conversion of existing drivers. But auditing drivers for 247 correctness of the atomic_check code becomes really hard with that: Rolling 248 back changes in data structures all over the place is hard to get right. 249 250- Lastly, for backwards compatibility and to support all use-cases, atomic 251 updates need to be incremental and be able to execute in parallel. Hardware 252 doesn't always allow it, but where possible plane updates on different CRTCs 253 should not interfere, and not get stalled due to output routing changing on 254 different CRTCs. 255 256Taken all together there's two consequences for the atomic design: 257 258- The overall state is split up into per-object state structures: 259 :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct 260 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct 261 drm_connector_state <drm_connector_state>` for connectors. These are the only 262 objects with userspace-visible and settable state. For internal state drivers 263 can subclass these structures through embeddeding, or add entirely new state 264 structures for their globally shared hardware functions, see :c:type:`struct 265 drm_private_state<drm_private_state>`. 266 267- An atomic update is assembled and validated as an entirely free-standing pile 268 of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` 269 container. Driver private state structures are also tracked in the same 270 structure; see the next chapter. Only when a state is committed is it applied 271 to the driver and modeset objects. This way rolling back an update boils down 272 to releasing memory and unreferencing objects like framebuffers. 273 274Locking of atomic state structures is internally using :c:type:`struct 275drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be 276exposed to drivers, instead the right locks should be automatically acquired by 277any function that duplicates or peeks into a state, like e.g. 278drm_atomic_get_crtc_state(). Locking only protects the software data 279structure, ordering of committing state changes to hardware is sequenced using 280:c:type:`struct drm_crtc_commit <drm_crtc_commit>`. 281 282Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed 283coverage of specific topics. 284 285Handling Driver Private State 286----------------------------- 287 288.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 289 :doc: handling driver private state 290 291Atomic Mode Setting Function Reference 292-------------------------------------- 293 294.. kernel-doc:: include/drm/drm_atomic.h 295 :internal: 296 297.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 298 :export: 299 300Atomic Mode Setting IOCTL and UAPI Functions 301-------------------------------------------- 302 303.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 304 :doc: overview 305 306.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 307 :export: 308 309CRTC Abstraction 310================ 311 312.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 313 :doc: overview 314 315CRTC Functions Reference 316-------------------------------- 317 318.. kernel-doc:: include/drm/drm_crtc.h 319 :internal: 320 321.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 322 :export: 323 324Color Management Functions Reference 325------------------------------------ 326 327.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 328 :export: 329 330.. kernel-doc:: include/drm/drm_color_mgmt.h 331 :internal: 332 333Frame Buffer Abstraction 334======================== 335 336.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 337 :doc: overview 338 339Frame Buffer Functions Reference 340-------------------------------- 341 342.. kernel-doc:: include/drm/drm_framebuffer.h 343 :internal: 344 345.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 346 :export: 347 348DRM Format Handling 349=================== 350 351.. kernel-doc:: include/uapi/drm/drm_fourcc.h 352 :doc: overview 353 354Format Functions Reference 355-------------------------- 356 357.. kernel-doc:: include/drm/drm_fourcc.h 358 :internal: 359 360.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 361 :export: 362 363Dumb Buffer Objects 364=================== 365 366.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 367 :doc: overview 368 369Plane Abstraction 370================= 371 372.. kernel-doc:: drivers/gpu/drm/drm_plane.c 373 :doc: overview 374 375Plane Functions Reference 376------------------------- 377 378.. kernel-doc:: include/drm/drm_plane.h 379 :internal: 380 381.. kernel-doc:: drivers/gpu/drm/drm_plane.c 382 :export: 383 384Plane Composition Functions Reference 385------------------------------------- 386 387.. kernel-doc:: drivers/gpu/drm/drm_blend.c 388 :export: 389 390Plane Damage Tracking Functions Reference 391----------------------------------------- 392 393.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c 394 :export: 395 396.. kernel-doc:: include/drm/drm_damage_helper.h 397 :internal: 398 399Display Modes Function Reference 400================================ 401 402.. kernel-doc:: include/drm/drm_modes.h 403 :internal: 404 405.. kernel-doc:: drivers/gpu/drm/drm_modes.c 406 :export: 407 408Connector Abstraction 409===================== 410 411.. kernel-doc:: drivers/gpu/drm/drm_connector.c 412 :doc: overview 413 414Connector Functions Reference 415----------------------------- 416 417.. kernel-doc:: include/drm/drm_connector.h 418 :internal: 419 420.. kernel-doc:: drivers/gpu/drm/drm_connector.c 421 :export: 422 423Writeback Connectors 424-------------------- 425 426.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 427 :doc: overview 428 429.. kernel-doc:: include/drm/drm_writeback.h 430 :internal: 431 432.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 433 :export: 434 435Encoder Abstraction 436=================== 437 438.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 439 :doc: overview 440 441Encoder Functions Reference 442--------------------------- 443 444.. kernel-doc:: include/drm/drm_encoder.h 445 :internal: 446 447.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 448 :export: 449 450KMS Locking 451=========== 452 453.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 454 :doc: kms locking 455 456.. kernel-doc:: include/drm/drm_modeset_lock.h 457 :internal: 458 459.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 460 :export: 461 462KMS Properties 463============== 464 465This section of the documentation is primarily aimed at user-space developers. 466For the driver APIs, see the other sections. 467 468Requirements 469------------ 470 471KMS drivers might need to add extra properties to support new features. Each 472new property introduced in a driver needs to meet a few requirements, in 473addition to the one mentioned above: 474 475* It must be standardized, documenting: 476 477 * The full, exact, name string; 478 * If the property is an enum, all the valid value name strings; 479 * What values are accepted, and what these values mean; 480 * What the property does and how it can be used; 481 * How the property might interact with other, existing properties. 482 483* It must provide a generic helper in the core code to register that 484 property on the object it attaches to. 485 486* Its content must be decoded by the core and provided in the object's 487 associated state structure. That includes anything drivers might want 488 to precompute, like struct drm_clip_rect for planes. 489 490* Its initial state must match the behavior prior to the property 491 introduction. This might be a fixed value matching what the hardware 492 does, or it may be inherited from the state the firmware left the 493 system in during boot. 494 495* An IGT test must be submitted where reasonable. 496 497Property Types and Blob Property Support 498---------------------------------------- 499 500.. kernel-doc:: drivers/gpu/drm/drm_property.c 501 :doc: overview 502 503.. kernel-doc:: include/drm/drm_property.h 504 :internal: 505 506.. kernel-doc:: drivers/gpu/drm/drm_property.c 507 :export: 508 509.. _standard_connector_properties: 510 511Standard Connector Properties 512----------------------------- 513 514.. kernel-doc:: drivers/gpu/drm/drm_connector.c 515 :doc: standard connector properties 516 517HDMI Specific Connector Properties 518---------------------------------- 519 520.. kernel-doc:: drivers/gpu/drm/drm_connector.c 521 :doc: HDMI connector properties 522 523Standard CRTC Properties 524------------------------ 525 526.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 527 :doc: standard CRTC properties 528 529Standard Plane Properties 530------------------------- 531 532.. kernel-doc:: drivers/gpu/drm/drm_plane.c 533 :doc: standard plane properties 534 535Plane Composition Properties 536---------------------------- 537 538.. kernel-doc:: drivers/gpu/drm/drm_blend.c 539 :doc: overview 540 541Damage Tracking Properties 542-------------------------- 543 544.. kernel-doc:: drivers/gpu/drm/drm_plane.c 545 :doc: damage tracking 546 547Color Management Properties 548--------------------------- 549 550.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 551 :doc: overview 552 553Tile Group Property 554------------------- 555 556.. kernel-doc:: drivers/gpu/drm/drm_connector.c 557 :doc: Tile group 558 559Explicit Fencing Properties 560--------------------------- 561 562.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 563 :doc: explicit fencing properties 564 565 566Variable Refresh Properties 567--------------------------- 568 569.. kernel-doc:: drivers/gpu/drm/drm_connector.c 570 :doc: Variable refresh properties 571 572Existing KMS Properties 573----------------------- 574 575The following table gives description of drm properties exposed by various 576modules/drivers. Because this table is very unwieldy, do not add any new 577properties here. Instead document them in a section above. 578 579.. csv-table:: 580 :header-rows: 1 581 :file: kms-properties.csv 582 583Vertical Blanking 584================= 585 586.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 587 :doc: vblank handling 588 589Vertical Blanking and Interrupt Handling Functions Reference 590------------------------------------------------------------ 591 592.. kernel-doc:: include/drm/drm_vblank.h 593 :internal: 594 595.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 596 :export: 597 598Vertical Blank Work 599=================== 600 601.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 602 :doc: vblank works 603 604Vertical Blank Work Functions Reference 605--------------------------------------- 606 607.. kernel-doc:: include/drm/drm_vblank_work.h 608 :internal: 609 610.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 611 :export: