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