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 290.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 291 :internal: 292 293CRTC Abstraction 294================ 295 296.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 297 :doc: overview 298 299CRTC Functions Reference 300-------------------------------- 301 302.. kernel-doc:: include/drm/drm_crtc.h 303 :internal: 304 305.. kernel-doc:: drivers/gpu/drm/drm_crtc.c 306 :export: 307 308Frame Buffer Abstraction 309======================== 310 311.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 312 :doc: overview 313 314Frame Buffer Functions Reference 315-------------------------------- 316 317.. kernel-doc:: include/drm/drm_framebuffer.h 318 :internal: 319 320.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c 321 :export: 322 323DRM Format Handling 324=================== 325 326.. kernel-doc:: include/drm/drm_fourcc.h 327 :internal: 328 329.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 330 :export: 331 332Dumb Buffer Objects 333=================== 334 335.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c 336 :doc: overview 337 338Plane Abstraction 339================= 340 341.. kernel-doc:: drivers/gpu/drm/drm_plane.c 342 :doc: overview 343 344Plane Functions Reference 345------------------------- 346 347.. kernel-doc:: include/drm/drm_plane.h 348 :internal: 349 350.. kernel-doc:: drivers/gpu/drm/drm_plane.c 351 :export: 352 353Display Modes Function Reference 354================================ 355 356.. kernel-doc:: include/drm/drm_modes.h 357 :internal: 358 359.. kernel-doc:: drivers/gpu/drm/drm_modes.c 360 :export: 361 362Connector Abstraction 363===================== 364 365.. kernel-doc:: drivers/gpu/drm/drm_connector.c 366 :doc: overview 367 368Connector Functions Reference 369----------------------------- 370 371.. kernel-doc:: include/drm/drm_connector.h 372 :internal: 373 374.. kernel-doc:: drivers/gpu/drm/drm_connector.c 375 :export: 376 377Writeback Connectors 378-------------------- 379 380.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 381 :doc: overview 382 383.. kernel-doc:: drivers/gpu/drm/drm_writeback.c 384 :export: 385 386Encoder Abstraction 387=================== 388 389.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 390 :doc: overview 391 392Encoder Functions Reference 393--------------------------- 394 395.. kernel-doc:: include/drm/drm_encoder.h 396 :internal: 397 398.. kernel-doc:: drivers/gpu/drm/drm_encoder.c 399 :export: 400 401KMS Initialization and Cleanup 402============================== 403 404A KMS device is abstracted and exposed as a set of planes, CRTCs, 405encoders and connectors. KMS drivers must thus create and initialize all 406those objects at load time after initializing mode setting. 407 408CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) 409-------------------------------------------- 410 411A CRTC is an abstraction representing a part of the chip that contains a 412pointer to a scanout buffer. Therefore, the number of CRTCs available 413determines how many independent scanout buffers can be active at any 414given time. The CRTC structure contains several fields to support this: 415a pointer to some video memory (abstracted as a frame buffer object), a 416display mode, and an (x, y) offset into the video memory to support 417panning or configurations where one piece of video memory spans multiple 418CRTCs. 419 420CRTC Initialization 421~~~~~~~~~~~~~~~~~~~ 422 423A KMS device must create and register at least one struct 424:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is 425allocated and zeroed by the driver, possibly as part of a larger 426structure, and registered with a call to :c:func:`drm_crtc_init()` 427with a pointer to CRTC functions. 428 429 430Cleanup 431------- 432 433The DRM core manages its objects' lifetime. When an object is not needed 434anymore the core calls its destroy function, which must clean up and 435free every resource allocated for the object. Every 436:c:func:`drm_\*_init()` call must be matched with a corresponding 437:c:func:`drm_\*_cleanup()` call to cleanup CRTCs 438(:c:func:`drm_crtc_cleanup()`), planes 439(:c:func:`drm_plane_cleanup()`), encoders 440(:c:func:`drm_encoder_cleanup()`) and connectors 441(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that 442have been added to sysfs must be removed by a call to 443:c:func:`drm_connector_unregister()` before calling 444:c:func:`drm_connector_cleanup()`. 445 446Connectors state change detection must be cleanup up with a call to 447:c:func:`drm_kms_helper_poll_fini()`. 448 449Output discovery and initialization example 450------------------------------------------- 451 452.. code-block:: c 453 454 void intel_crt_init(struct drm_device *dev) 455 { 456 struct drm_connector *connector; 457 struct intel_output *intel_output; 458 459 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); 460 if (!intel_output) 461 return; 462 463 connector = &intel_output->base; 464 drm_connector_init(dev, &intel_output->base, 465 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); 466 467 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, 468 DRM_MODE_ENCODER_DAC); 469 470 drm_connector_attach_encoder(&intel_output->base, 471 &intel_output->enc); 472 473 /* Set up the DDC bus. */ 474 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); 475 if (!intel_output->ddc_bus) { 476 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " 477 "failed.\n"); 478 return; 479 } 480 481 intel_output->type = INTEL_OUTPUT_ANALOG; 482 connector->interlace_allowed = 0; 483 connector->doublescan_allowed = 0; 484 485 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); 486 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); 487 488 drm_connector_register(connector); 489 } 490 491In the example above (taken from the i915 driver), a CRTC, connector and 492encoder combination is created. A device-specific i2c bus is also 493created for fetching EDID data and performing monitor detection. Once 494the process is complete, the new connector is registered with sysfs to 495make its properties available to applications. 496 497KMS Locking 498=========== 499 500.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 501 :doc: kms locking 502 503.. kernel-doc:: include/drm/drm_modeset_lock.h 504 :internal: 505 506.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c 507 :export: 508 509KMS Properties 510============== 511 512Property Types and Blob Property Support 513---------------------------------------- 514 515.. kernel-doc:: drivers/gpu/drm/drm_property.c 516 :doc: overview 517 518.. kernel-doc:: include/drm/drm_property.h 519 :internal: 520 521.. kernel-doc:: drivers/gpu/drm/drm_property.c 522 :export: 523 524Standard Connector Properties 525----------------------------- 526 527.. kernel-doc:: drivers/gpu/drm/drm_connector.c 528 :doc: standard connector properties 529 530HDMI Specific Connector Properties 531---------------------------------- 532 533.. kernel-doc:: drivers/gpu/drm/drm_connector.c 534 :doc: HDMI connector properties 535 536Plane Composition Properties 537---------------------------- 538 539.. kernel-doc:: drivers/gpu/drm/drm_blend.c 540 :doc: overview 541 542.. kernel-doc:: drivers/gpu/drm/drm_blend.c 543 :export: 544 545Color Management Properties 546--------------------------- 547 548.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 549 :doc: overview 550 551.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c 552 :export: 553 554Tile Group Property 555------------------- 556 557.. kernel-doc:: drivers/gpu/drm/drm_connector.c 558 :doc: Tile group 559 560Explicit Fencing Properties 561--------------------------- 562 563.. kernel-doc:: drivers/gpu/drm/drm_atomic.c 564 :doc: explicit fencing properties 565 566Existing KMS Properties 567----------------------- 568 569The following table gives description of drm properties exposed by various 570modules/drivers. Because this table is very unwieldy, do not add any new 571properties here. Instead document them in a section above. 572 573.. csv-table:: 574 :header-rows: 1 575 :file: kms-properties.csv 576 577Vertical Blanking 578================= 579 580.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 581 :doc: vblank handling 582 583Vertical Blanking and Interrupt Handling Functions Reference 584------------------------------------------------------------ 585 586.. kernel-doc:: include/drm/drm_vblank.h 587 :internal: 588 589.. kernel-doc:: drivers/gpu/drm/drm_vblank.c 590 :export: 591