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. One or more (or even no) 60planes feed their pixel data into a CRTC (represented by :c:type:`struct 61drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise 62blending step is explained in more detail in `Plane Composition Properties`_ and 63related chapters. 64 65For the output routing the first step is encoders (represented by 66:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those 67are really just internal artifacts of the helper libraries used to implement KMS 68drivers. Besides that they make it unecessarily more complicated for userspace 69to figure out which connections between a CRTC and a connector are possible, and 70what kind of cloning is supported, they serve no purpose in the userspace API. 71Unfortunately encoders have been exposed to userspace, hence can't remove them 72at this point. Futhermore the exposed restrictions are often wrongly set by 73drivers, and in many cases not powerful enough to express the real restrictions. 74A CRTC can be connected to multiple encoders, and for an active CRTC there must 75be at least one encoder. 76 77The final, and real, endpoint in the display chain is the connector (represented 78by :c:type:`struct drm_connector <drm_connector>`, see `Connector 79Abstraction`_). Connectors can have different possible encoders, but the kernel 80driver selects which encoder to use for each connector. The use case is DVI, 81which could switch between an analog and a digital encoder. Encoders can also 82drive multiple different connectors. There is exactly one active connector for 83every active encoder. 84 85Internally the output pipeline is a bit more complex and matches today's 86hardware 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 134Internally two additional helper objects come into play. First, to be able to 135share code for encoders (sometimes on the same SoC, sometimes off-chip) one or 136more :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 138changed, which means the cross-bar (if there is any) needs to be mapped between 139the CRTC and any encoders. Often for drivers with bridges there's no code left 140at the encoder level. Atomic drivers can leave out all the encoder callbacks to 141essentially only leave a dummy routing object behind, which is needed for 142backwards compatibility since encoders are exposed to userspace. 143 144The 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 146point, but are generally linked to the driver private structure that embeds 147:c:type:`struct drm_connector <drm_connector>`. 148 149Note that currently the bridge chaining and interactions with connectors and 150panels are still in-flux and not really fully sorted out yet. 151 152KMS 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 161Modeset 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 176The 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, 178which are especially important for the atomic IOCTL (see `Atomic Mode 179Setting`_). The somewhat surprising part here is that properties are not 180directly instantiated on each object, but free-standing mode objects themselves, 181represented by :c:type:`struct drm_property <drm_property>`, which only specify 182the type and value range of a property. Any given property can be attached 183multiple 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 192Atomic 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 235Atomic provides transactional modeset (including planes) updates, but a 236bit differently from the usual transactional approach of try-commit and 237rollback: 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 254Taken 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 271Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed 272coverage of specific topics. 273 274Handling Driver Private State 275----------------------------- 276 277.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 278 :doc: handling driver private state 279 280Atomic 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 292CRTC Abstraction 293================ 294 295.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 296 :doc: overview 297 298CRTC 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 307Frame Buffer Abstraction 308======================== 309 310.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 311 :doc: overview 312 313Frame 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 322DRM 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 331Dumb Buffer Objects 332=================== 333 334.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 335 :doc: overview 336 337Plane Abstraction 338================= 339 340.. kernel-doc:: drivers/gpu/drm/drm_plane.c 341 :doc: overview 342 343Plane 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 352Display 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 361Connector Abstraction 362===================== 363 364.. kernel-doc:: drivers/gpu/drm/drm_connector.c 365 :doc: overview 366 367Connector 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 376Writeback Connectors 377-------------------- 378 379.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 380 :doc: overview 381 382.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 383 :export: 384 385Encoder Abstraction 386=================== 387 388.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 389 :doc: overview 390 391Encoder Functions Reference 392--------------------------- 393 394.. kernel-doc:: include/drm/drm_encoder.h 395 :internal: 396 397.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 398 :export: 399 400KMS Initialization and Cleanup 401============================== 402 403A KMS device is abstracted and exposed as a set of planes, CRTCs, 404encoders and connectors. KMS drivers must thus create and initialize all 405those objects at load time after initializing mode setting. 406 407CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) 408-------------------------------------------- 409 410A CRTC is an abstraction representing a part of the chip that contains a 411pointer to a scanout buffer. Therefore, the number of CRTCs available 412determines how many independent scanout buffers can be active at any 413given time. The CRTC structure contains several fields to support this: 414a pointer to some video memory (abstracted as a frame buffer object), a 415display mode, and an (x, y) offset into the video memory to support 416panning or configurations where one piece of video memory spans multiple 417CRTCs. 418 419CRTC Initialization 420~~~~~~~~~~~~~~~~~~~ 421 422A KMS device must create and register at least one struct 423:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is 424allocated and zeroed by the driver, possibly as part of a larger 425structure, and registered with a call to :c:func:`drm_crtc_init()` 426with a pointer to CRTC functions. 427 428 429Cleanup 430------- 431 432The DRM core manages its objects' lifetime. When an object is not needed 433anymore the core calls its destroy function, which must clean up and 434free every resource allocated for the object. Every 435:c:func:`drm_\*_init()` call must be matched with a corresponding 436:c:func:`drm_\*_cleanup()` call to cleanup CRTCs 437(:c:func:`drm_crtc_cleanup()`), planes 438(:c:func:`drm_plane_cleanup()`), encoders 439(:c:func:`drm_encoder_cleanup()`) and connectors 440(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that 441have been added to sysfs must be removed by a call to 442:c:func:`drm_connector_unregister()` before calling 443:c:func:`drm_connector_cleanup()`. 444 445Connectors state change detection must be cleanup up with a call to 446:c:func:`drm_kms_helper_poll_fini()`. 447 448Output discovery and initialization example 449------------------------------------------- 450 451.. code-block:: c 452 453 void intel_crt_init(struct drm_device *dev) 454 { 455 struct drm_connector *connector; 456 struct intel_output *intel_output; 457 458 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); 459 if (!intel_output) 460 return; 461 462 connector = &intel_output->base; 463 drm_connector_init(dev, &intel_output->base, 464 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); 465 466 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, 467 DRM_MODE_ENCODER_DAC); 468 469 drm_mode_connector_attach_encoder(&intel_output->base, 470 &intel_output->enc); 471 472 /* Set up the DDC bus. */ 473 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); 474 if (!intel_output->ddc_bus) { 475 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " 476 "failed.\n"); 477 return; 478 } 479 480 intel_output->type = INTEL_OUTPUT_ANALOG; 481 connector->interlace_allowed = 0; 482 connector->doublescan_allowed = 0; 483 484 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); 485 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); 486 487 drm_connector_register(connector); 488 } 489 490In the example above (taken from the i915 driver), a CRTC, connector and 491encoder combination is created. A device-specific i2c bus is also 492created for fetching EDID data and performing monitor detection. Once 493the process is complete, the new connector is registered with sysfs to 494make its properties available to applications. 495 496KMS Locking 497=========== 498 499.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 500 :doc: kms locking 501 502.. kernel-doc:: include/drm/drm_modeset_lock.h 503 :internal: 504 505.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 506 :export: 507 508KMS Properties 509============== 510 511Property Types and Blob Property Support 512---------------------------------------- 513 514.. kernel-doc:: drivers/gpu/drm/drm_property.c 515 :doc: overview 516 517.. kernel-doc:: include/drm/drm_property.h 518 :internal: 519 520.. kernel-doc:: drivers/gpu/drm/drm_property.c 521 :export: 522 523Standard Connector Properties 524----------------------------- 525 526.. kernel-doc:: drivers/gpu/drm/drm_connector.c 527 :doc: standard connector properties 528 529HDMI Specific Connector Properties 530---------------------------------- 531 532.. kernel-doc:: drivers/gpu/drm/drm_connector.c 533 :doc: HDMI connector properties 534 535Plane Composition Properties 536---------------------------- 537 538.. kernel-doc:: drivers/gpu/drm/drm_blend.c 539 :doc: overview 540 541.. kernel-doc:: drivers/gpu/drm/drm_blend.c 542 :export: 543 544Color Management Properties 545--------------------------- 546 547.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 548 :doc: overview 549 550.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 551 :export: 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.c 563 :doc: explicit fencing properties 564 565Existing KMS Properties 566----------------------- 567 568The following table gives description of drm properties exposed by various 569modules/drivers. Because this table is very unwieldy, do not add any new 570properties here. Instead document them in a section above. 571 572.. csv-table:: 573 :header-rows: 1 574 :file: kms-properties.csv 575 576Vertical Blanking 577================= 578 579.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 580 :doc: vblank handling 581 582Vertical Blanking and Interrupt Handling Functions Reference 583------------------------------------------------------------ 584 585.. kernel-doc:: include/drm/drm_vblank.h 586 :internal: 587 588.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 589 :export: 590