1========================= 2Kernel Mode Setting (KMS) 3========================= 4 5Drivers must initialize the mode setting core by calling 6:c:func:`drm_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 162Modeset 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 177The 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, 179which are especially important for the atomic IOCTL (see `Atomic Mode 180Setting`_). The somewhat surprising part here is that properties are not 181directly instantiated on each object, but free-standing mode objects themselves, 182represented by :c:type:`struct drm_property <drm_property>`, which only specify 183the type and value range of a property. Any given property can be attached 184multiple times to different objects using :c:func:`drm_object_attach_property() 185<drm_object_attach_property>`. 186 187.. kernel-doc:: include/drm/drm_mode_object.h 188 :internal: 189 190.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c 191 :export: 192 193Atomic Mode Setting 194=================== 195 196 197.. kernel-render:: DOT 198 :alt: Mode Objects and Properties 199 :caption: Mode Objects and Properties 200 201 digraph { 202 node [shape=box] 203 204 subgraph cluster_state { 205 style=dashed 206 label="Free-standing state" 207 208 "drm_atomic_state" -> "duplicated drm_plane_state A" 209 "drm_atomic_state" -> "duplicated drm_plane_state B" 210 "drm_atomic_state" -> "duplicated drm_crtc_state" 211 "drm_atomic_state" -> "duplicated drm_connector_state" 212 "drm_atomic_state" -> "duplicated driver private state" 213 } 214 215 subgraph cluster_current { 216 style=dashed 217 label="Current state" 218 219 "drm_device" -> "drm_plane A" 220 "drm_device" -> "drm_plane B" 221 "drm_device" -> "drm_crtc" 222 "drm_device" -> "drm_connector" 223 "drm_device" -> "driver private object" 224 225 "drm_plane A" -> "drm_plane_state A" 226 "drm_plane B" -> "drm_plane_state B" 227 "drm_crtc" -> "drm_crtc_state" 228 "drm_connector" -> "drm_connector_state" 229 "driver private object" -> "driver private state" 230 } 231 232 "drm_atomic_state" -> "drm_device" [label="atomic_commit"] 233 "duplicated drm_plane_state A" -> "drm_device"[style=invis] 234 } 235 236Atomic provides transactional modeset (including planes) updates, but a 237bit differently from the usual transactional approach of try-commit and 238rollback: 239 240- Firstly, no hardware changes are allowed when the commit would fail. This 241 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows 242 userspace to explore whether certain configurations would work or not. 243 244- This would still allow setting and rollback of just the software state, 245 simplifying conversion of existing drivers. But auditing drivers for 246 correctness of the atomic_check code becomes really hard with that: Rolling 247 back changes in data structures all over the place is hard to get right. 248 249- Lastly, for backwards compatibility and to support all use-cases, atomic 250 updates need to be incremental and be able to execute in parallel. Hardware 251 doesn't always allow it, but where possible plane updates on different CRTCs 252 should not interfere, and not get stalled due to output routing changing on 253 different CRTCs. 254 255Taken all together there's two consequences for the atomic design: 256 257- The overall state is split up into per-object state structures: 258 :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct 259 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct 260 drm_connector_state <drm_connector_state>` for connectors. These are the only 261 objects with userspace-visible and settable state. For internal state drivers 262 can subclass these structures through embeddeding, or add entirely new state 263 structures for their globally shared hardware functions. 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 272Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed 273coverage of specific topics. 274 275Handling Driver Private State 276----------------------------- 277 278.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 279 :doc: handling driver private state 280 281Atomic Mode Setting Function Reference 282-------------------------------------- 283 284.. kernel-doc:: include/drm/drm_atomic.h 285 :internal: 286 287.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 288 :export: 289 290Atomic Mode Setting IOCTL and UAPI Functions 291-------------------------------------------- 292 293.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 294 :doc: overview 295 296.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 297 :export: 298 299CRTC Abstraction 300================ 301 302.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 303 :doc: overview 304 305CRTC Functions Reference 306-------------------------------- 307 308.. kernel-doc:: include/drm/drm_crtc.h 309 :internal: 310 311.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 312 :export: 313 314Frame Buffer Abstraction 315======================== 316 317.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 318 :doc: overview 319 320Frame Buffer Functions Reference 321-------------------------------- 322 323.. kernel-doc:: include/drm/drm_framebuffer.h 324 :internal: 325 326.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 327 :export: 328 329DRM Format Handling 330=================== 331 332.. kernel-doc:: include/uapi/drm/drm_fourcc.h 333 :doc: overview 334 335Format Functions Reference 336-------------------------- 337 338.. kernel-doc:: include/drm/drm_fourcc.h 339 :internal: 340 341.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 342 :export: 343 344Dumb Buffer Objects 345=================== 346 347.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 348 :doc: overview 349 350Plane Abstraction 351================= 352 353.. kernel-doc:: drivers/gpu/drm/drm_plane.c 354 :doc: overview 355 356Plane Functions Reference 357------------------------- 358 359.. kernel-doc:: include/drm/drm_plane.h 360 :internal: 361 362.. kernel-doc:: drivers/gpu/drm/drm_plane.c 363 :export: 364 365Display Modes Function Reference 366================================ 367 368.. kernel-doc:: include/drm/drm_modes.h 369 :internal: 370 371.. kernel-doc:: drivers/gpu/drm/drm_modes.c 372 :export: 373 374Connector Abstraction 375===================== 376 377.. kernel-doc:: drivers/gpu/drm/drm_connector.c 378 :doc: overview 379 380Connector Functions Reference 381----------------------------- 382 383.. kernel-doc:: include/drm/drm_connector.h 384 :internal: 385 386.. kernel-doc:: drivers/gpu/drm/drm_connector.c 387 :export: 388 389Writeback Connectors 390-------------------- 391 392.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 393 :doc: overview 394 395.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 396 :export: 397 398Encoder Abstraction 399=================== 400 401.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 402 :doc: overview 403 404Encoder Functions Reference 405--------------------------- 406 407.. kernel-doc:: include/drm/drm_encoder.h 408 :internal: 409 410.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 411 :export: 412 413KMS Initialization and Cleanup 414============================== 415 416A KMS device is abstracted and exposed as a set of planes, CRTCs, 417encoders and connectors. KMS drivers must thus create and initialize all 418those objects at load time after initializing mode setting. 419 420CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) 421-------------------------------------------- 422 423A CRTC is an abstraction representing a part of the chip that contains a 424pointer to a scanout buffer. Therefore, the number of CRTCs available 425determines how many independent scanout buffers can be active at any 426given time. The CRTC structure contains several fields to support this: 427a pointer to some video memory (abstracted as a frame buffer object), a 428display mode, and an (x, y) offset into the video memory to support 429panning or configurations where one piece of video memory spans multiple 430CRTCs. 431 432CRTC Initialization 433~~~~~~~~~~~~~~~~~~~ 434 435A KMS device must create and register at least one struct 436:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is 437allocated and zeroed by the driver, possibly as part of a larger 438structure, and registered with a call to :c:func:`drm_crtc_init()` 439with a pointer to CRTC functions. 440 441 442Cleanup 443------- 444 445The DRM core manages its objects' lifetime. When an object is not needed 446anymore the core calls its destroy function, which must clean up and 447free every resource allocated for the object. Every 448:c:func:`drm_\*_init()` call must be matched with a corresponding 449:c:func:`drm_\*_cleanup()` call to cleanup CRTCs 450(:c:func:`drm_crtc_cleanup()`), planes 451(:c:func:`drm_plane_cleanup()`), encoders 452(:c:func:`drm_encoder_cleanup()`) and connectors 453(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that 454have been added to sysfs must be removed by a call to 455:c:func:`drm_connector_unregister()` before calling 456:c:func:`drm_connector_cleanup()`. 457 458Connectors state change detection must be cleanup up with a call to 459:c:func:`drm_kms_helper_poll_fini()`. 460 461Output discovery and initialization example 462------------------------------------------- 463 464.. code-block:: c 465 466 void intel_crt_init(struct drm_device *dev) 467 { 468 struct drm_connector *connector; 469 struct intel_output *intel_output; 470 471 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); 472 if (!intel_output) 473 return; 474 475 connector = &intel_output->base; 476 drm_connector_init(dev, &intel_output->base, 477 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); 478 479 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, 480 DRM_MODE_ENCODER_DAC); 481 482 drm_connector_attach_encoder(&intel_output->base, 483 &intel_output->enc); 484 485 /* Set up the DDC bus. */ 486 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); 487 if (!intel_output->ddc_bus) { 488 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " 489 "failed.\n"); 490 return; 491 } 492 493 intel_output->type = INTEL_OUTPUT_ANALOG; 494 connector->interlace_allowed = 0; 495 connector->doublescan_allowed = 0; 496 497 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); 498 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); 499 500 drm_connector_register(connector); 501 } 502 503In the example above (taken from the i915 driver), a CRTC, connector and 504encoder combination is created. A device-specific i2c bus is also 505created for fetching EDID data and performing monitor detection. Once 506the process is complete, the new connector is registered with sysfs to 507make its properties available to applications. 508 509KMS Locking 510=========== 511 512.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 513 :doc: kms locking 514 515.. kernel-doc:: include/drm/drm_modeset_lock.h 516 :internal: 517 518.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 519 :export: 520 521KMS Properties 522============== 523 524Property Types and Blob Property Support 525---------------------------------------- 526 527.. kernel-doc:: drivers/gpu/drm/drm_property.c 528 :doc: overview 529 530.. kernel-doc:: include/drm/drm_property.h 531 :internal: 532 533.. kernel-doc:: drivers/gpu/drm/drm_property.c 534 :export: 535 536Standard Connector Properties 537----------------------------- 538 539.. kernel-doc:: drivers/gpu/drm/drm_connector.c 540 :doc: standard connector properties 541 542HDMI Specific Connector Properties 543---------------------------------- 544 545.. kernel-doc:: drivers/gpu/drm/drm_connector.c 546 :doc: HDMI connector properties 547 548Plane Composition Properties 549---------------------------- 550 551.. kernel-doc:: drivers/gpu/drm/drm_blend.c 552 :doc: overview 553 554.. kernel-doc:: drivers/gpu/drm/drm_blend.c 555 :export: 556 557Color Management Properties 558--------------------------- 559 560.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 561 :doc: overview 562 563.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 564 :export: 565 566Tile Group Property 567------------------- 568 569.. kernel-doc:: drivers/gpu/drm/drm_connector.c 570 :doc: Tile group 571 572Explicit Fencing Properties 573--------------------------- 574 575.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c 576 :doc: explicit fencing properties 577 578Existing KMS Properties 579----------------------- 580 581The following table gives description of drm properties exposed by various 582modules/drivers. Because this table is very unwieldy, do not add any new 583properties here. Instead document them in a section above. 584 585.. csv-table:: 586 :header-rows: 1 587 :file: kms-properties.csv 588 589Vertical Blanking 590================= 591 592.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 593 :doc: vblank handling 594 595Vertical Blanking and Interrupt Handling Functions Reference 596------------------------------------------------------------ 597 598.. kernel-doc:: include/drm/drm_vblank.h 599 :internal: 600 601.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 602 :export: 603