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 unnecessarily 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. Furthermore 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 .. _kms_base_object_abstraction: 163 164 Modeset 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 179 The 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, 181 which are especially important for the atomic IOCTL (see `Atomic Mode 182 Setting`_). The somewhat surprising part here is that properties are not 183 directly instantiated on each object, but free-standing mode objects themselves, 184 represented by :c:type:`struct drm_property <drm_property>`, which only specify 185 the type and value range of a property. Any given property can be attached 186 multiple 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 194 Atomic 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 237 Atomic provides transactional modeset (including planes) updates, but a 238 bit differently from the usual transactional approach of try-commit and 239 rollback: 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 256 Taken 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 embedding, 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 274 Locking of atomic state structures is internally using :c:type:`struct 275 drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be 276 exposed to drivers, instead the right locks should be automatically acquired by 277 any function that duplicates or peeks into a state, like e.g. 278 drm_atomic_get_crtc_state(). Locking only protects the software data 279 structure, ordering of committing state changes to hardware is sequenced using 280 :c:type:`struct drm_crtc_commit <drm_crtc_commit>`. 281 282 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed 283 coverage of specific topics. 284 285 Handling Driver Private State 286 ----------------------------- 287 288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c 289 :doc: handling driver private state 290 291 Atomic 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 300 Atomic 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 309 CRTC Abstraction 310 ================ 311 312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 313 :doc: overview 314 315 CRTC 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 324 Color 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 333 Frame Buffer Abstraction 334 ======================== 335 336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 337 :doc: overview 338 339 Frame 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 348 DRM Format Handling 349 =================== 350 351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h 352 :doc: overview 353 354 Format 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 363 .. _kms_dumb_buffer_objects: 364 365 Dumb Buffer Objects 366 =================== 367 368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 369 :doc: overview 370 371 Plane Abstraction 372 ================= 373 374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 375 :doc: overview 376 377 Plane Functions Reference 378 ------------------------- 379 380 .. kernel-doc:: include/drm/drm_plane.h 381 :internal: 382 383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 384 :export: 385 386 Plane Composition Functions Reference 387 ------------------------------------- 388 389 .. kernel-doc:: drivers/gpu/drm/drm_blend.c 390 :export: 391 392 Plane Damage Tracking Functions Reference 393 ----------------------------------------- 394 395 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c 396 :export: 397 398 .. kernel-doc:: include/drm/drm_damage_helper.h 399 :internal: 400 401 Plane Panic Feature 402 ------------------- 403 404 .. kernel-doc:: drivers/gpu/drm/drm_panic.c 405 :doc: overview 406 407 Plane Panic Functions Reference 408 ------------------------------- 409 410 .. kernel-doc:: include/drm/drm_panic.h 411 :internal: 412 413 .. kernel-doc:: drivers/gpu/drm/drm_panic.c 414 :export: 415 416 Display Modes Function Reference 417 ================================ 418 419 .. kernel-doc:: include/drm/drm_modes.h 420 :internal: 421 422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c 423 :export: 424 425 Connector Abstraction 426 ===================== 427 428 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 429 :doc: overview 430 431 Connector Functions Reference 432 ----------------------------- 433 434 .. kernel-doc:: include/drm/drm_connector.h 435 :internal: 436 437 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 438 :export: 439 440 Writeback Connectors 441 -------------------- 442 443 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c 444 :doc: overview 445 446 .. kernel-doc:: include/drm/drm_writeback.h 447 :internal: 448 449 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c 450 :export: 451 452 Encoder Abstraction 453 =================== 454 455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 456 :doc: overview 457 458 Encoder Functions Reference 459 --------------------------- 460 461 .. kernel-doc:: include/drm/drm_encoder.h 462 :internal: 463 464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 465 :export: 466 467 KMS Locking 468 =========== 469 470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 471 :doc: kms locking 472 473 .. kernel-doc:: include/drm/drm_modeset_lock.h 474 :internal: 475 476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 477 :export: 478 479 KMS Properties 480 ============== 481 482 This section of the documentation is primarily aimed at user-space developers. 483 For the driver APIs, see the other sections. 484 485 Requirements 486 ------------ 487 488 KMS drivers might need to add extra properties to support new features. Each 489 new property introduced in a driver needs to meet a few requirements, in 490 addition to the one mentioned above: 491 492 * It must be standardized, documenting: 493 494 * The full, exact, name string; 495 * If the property is an enum, all the valid value name strings; 496 * What values are accepted, and what these values mean; 497 * What the property does and how it can be used; 498 * How the property might interact with other, existing properties. 499 500 * It must provide a generic helper in the core code to register that 501 property on the object it attaches to. 502 503 * Its content must be decoded by the core and provided in the object's 504 associated state structure. That includes anything drivers might want 505 to precompute, like struct drm_clip_rect for planes. 506 507 * Its initial state must match the behavior prior to the property 508 introduction. This might be a fixed value matching what the hardware 509 does, or it may be inherited from the state the firmware left the 510 system in during boot. 511 512 * An IGT test must be submitted where reasonable. 513 514 For historical reasons, non-standard, driver-specific properties exist. If a KMS 515 driver wants to add support for one of those properties, the requirements for 516 new properties apply where possible. Additionally, the documented behavior must 517 match the de facto semantics of the existing property to ensure compatibility. 518 Developers of the driver that first added the property should help with those 519 tasks and must ACK the documented behavior if possible. 520 521 Property Types and Blob Property Support 522 ---------------------------------------- 523 524 .. kernel-doc:: drivers/gpu/drm/drm_property.c 525 :doc: overview 526 527 .. kernel-doc:: include/drm/drm_property.h 528 :internal: 529 530 .. kernel-doc:: drivers/gpu/drm/drm_property.c 531 :export: 532 533 .. _standard_connector_properties: 534 535 Standard Connector Properties 536 ----------------------------- 537 538 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 539 :doc: standard connector properties 540 541 HDMI Specific Connector Properties 542 ---------------------------------- 543 544 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 545 :doc: HDMI connector properties 546 547 Analog TV Specific Connector Properties 548 --------------------------------------- 549 550 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 551 :doc: Analog TV Connector Properties 552 553 Standard CRTC Properties 554 ------------------------ 555 556 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 557 :doc: standard CRTC properties 558 559 Standard Plane Properties 560 ------------------------- 561 562 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 563 :doc: standard plane properties 564 565 .. _plane_composition_properties: 566 567 Plane Composition Properties 568 ---------------------------- 569 570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c 571 :doc: overview 572 573 .. _damage_tracking_properties: 574 575 Damage Tracking Properties 576 -------------------------- 577 578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 579 :doc: damage tracking 580 581 Color Management Properties 582 --------------------------- 583 584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 585 :doc: overview 586 587 Tile Group Property 588 ------------------- 589 590 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 591 :doc: Tile group 592 593 Explicit Fencing Properties 594 --------------------------- 595 596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 597 :doc: explicit fencing properties 598 599 600 Variable Refresh Properties 601 --------------------------- 602 603 .. kernel-doc:: drivers/gpu/drm/drm_connector.c 604 :doc: Variable refresh properties 605 606 Cursor Hotspot Properties 607 --------------------------- 608 609 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 610 :doc: hotspot properties 611 612 Existing KMS Properties 613 ----------------------- 614 615 The following table gives description of drm properties exposed by various 616 modules/drivers. Because this table is very unwieldy, do not add any new 617 properties here. Instead document them in a section above. 618 619 .. csv-table:: 620 :header-rows: 1 621 :file: kms-properties.csv 622 623 Vertical Blanking 624 ================= 625 626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c 627 :doc: vblank handling 628 629 Vertical Blanking and Interrupt Handling Functions Reference 630 ------------------------------------------------------------ 631 632 .. kernel-doc:: include/drm/drm_vblank.h 633 :internal: 634 635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c 636 :export: 637 638 Vertical Blank Work 639 =================== 640 641 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 642 :doc: vblank works 643 644 Vertical Blank Work Functions Reference 645 --------------------------------------- 646 647 .. kernel-doc:: include/drm/drm_vblank_work.h 648 :internal: 649 650 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c 651 :export:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.