652 lines · plain
1=========================2Kernel Mode Setting (KMS)3=========================4 5Drivers must initialize the mode setting core by calling6drmm_mode_config_init() on the DRM device. The function7initializes the :c:type:`struct drm_device <drm_device>`8mode_config field and never fails. Once done, mode configuration must9be 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 pixel13 units.14 15- struct drm_mode_config_funcs \*funcs;16 Mode setting functions.17 18Overview19========20 21.. kernel-render:: DOT22 :alt: KMS Display Pipeline23 :caption: KMS Display Pipeline Overview24 25 digraph "KMS" {26 node [shape=box]27 28 subgraph cluster_static {29 style=dashed30 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=dashed41 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=dashed50 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 by60:c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more61details. One or more (or even no) planes feed their pixel data into a CRTC62(represented by :c:type:`struct drm_crtc <drm_crtc>`, see `CRTC Abstraction`_)63for blending. The precise blending step is explained in more detail in `Plane64Composition Properties`_ and related chapters.65 66For the output routing the first step is encoders (represented by67:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those68are really just internal artifacts of the helper libraries used to implement KMS69drivers. Besides that they make it unnecessarily more complicated for userspace70to figure out which connections between a CRTC and a connector are possible, and71what kind of cloning is supported, they serve no purpose in the userspace API.72Unfortunately encoders have been exposed to userspace, hence can't remove them73at this point. Furthermore the exposed restrictions are often wrongly set by74drivers, 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 must76be at least one encoder.77 78The final, and real, endpoint in the display chain is the connector (represented79by :c:type:`struct drm_connector <drm_connector>`, see `Connector80Abstraction`_). Connectors can have different possible encoders, but the kernel81driver 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 also83drive multiple different connectors. There is exactly one active connector for84every active encoder.85 86Internally the output pipeline is a bit more complex and matches today's87hardware more closely:88 89.. kernel-render:: DOT90 :alt: KMS Output Pipeline91 :caption: KMS Output Pipeline92 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=dashed102 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=dashed125 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 to136share code for encoders (sometimes on the same SoC, sometimes off-chip) one or137more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge138<drm_bridge>`) can be linked to an encoder. This link is static and cannot be139changed, which means the cross-bar (if there is any) needs to be mapped between140the CRTC and any encoders. Often for drivers with bridges there's no code left141at the encoder level. Atomic drivers can leave out all the encoder callbacks to142essentially only leave a dummy routing object behind, which is needed for143backwards compatibility since encoders are exposed to userspace.144 145The second object is for panels, represented by :c:type:`struct drm_panel146<drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding147point, but are generally linked to the driver private structure that embeds148:c:type:`struct drm_connector <drm_connector>`.149 150Note that currently the bridge chaining and interactions with connectors and151panels are still in-flux and not really fully sorted out yet.152 153KMS Core Structures and Functions154=================================155 156.. kernel-doc:: include/drm/drm_mode_config.h157 :internal:158 159.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c160 :export:161 162.. _kms_base_object_abstraction:163 164Modeset Base Object Abstraction165===============================166 167.. kernel-render:: DOT168 :alt: Mode Objects and Properties169 :caption: Mode Objects and Properties170 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 179The base structure for all KMS objects is :c:type:`struct drm_mode_object180<drm_mode_object>`. One of the base services it provides is tracking properties,181which are especially important for the atomic IOCTL (see `Atomic Mode182Setting`_). The somewhat surprising part here is that properties are not183directly instantiated on each object, but free-standing mode objects themselves,184represented by :c:type:`struct drm_property <drm_property>`, which only specify185the type and value range of a property. Any given property can be attached186multiple times to different objects using drm_object_attach_property().187 188.. kernel-doc:: include/drm/drm_mode_object.h189 :internal:190 191.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c192 :export:193 194Atomic Mode Setting195===================196 197 198.. kernel-render:: DOT199 :alt: Mode Objects and Properties200 :caption: Mode Objects and Properties201 202 digraph {203 node [shape=box]204 205 subgraph cluster_state {206 style=dashed207 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=dashed218 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 237Atomic provides transactional modeset (including planes) updates, but a238bit differently from the usual transactional approach of try-commit and239rollback:240 241- Firstly, no hardware changes are allowed when the commit would fail. This242 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows243 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 for247 correctness of the atomic_check code becomes really hard with that: Rolling248 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, atomic251 updates need to be incremental and be able to execute in parallel. Hardware252 doesn't always allow it, but where possible plane updates on different CRTCs253 should not interfere, and not get stalled due to output routing changing on254 different CRTCs.255 256Taken 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:`struct260 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct261 drm_connector_state <drm_connector_state>` for connectors. These are the only262 objects with userspace-visible and settable state. For internal state drivers263 can subclass these structures through embedding, or add entirely new state264 structures for their globally shared hardware functions, see :c:type:`struct265 drm_private_state<drm_private_state>`.266 267- An atomic update is assembled and validated as an entirely free-standing pile268 of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`269 container. Driver private state structures are also tracked in the same270 structure; see the next chapter. Only when a state is committed is it applied271 to the driver and modeset objects. This way rolling back an update boils down272 to releasing memory and unreferencing objects like framebuffers.273 274Locking of atomic state structures is internally using :c:type:`struct275drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be276exposed to drivers, instead the right locks should be automatically acquired by277any function that duplicates or peeks into a state, like e.g.278drm_atomic_get_crtc_state(). Locking only protects the software data279structure, ordering of committing state changes to hardware is sequenced using280:c:type:`struct drm_crtc_commit <drm_crtc_commit>`.281 282Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed283coverage of specific topics.284 285Handling Driver Private State286-----------------------------287 288.. kernel-doc:: drivers/gpu/drm/drm_atomic.c289 :doc: handling driver private state290 291Atomic Mode Setting Function Reference292--------------------------------------293 294.. kernel-doc:: include/drm/drm_atomic.h295 :internal:296 297.. kernel-doc:: drivers/gpu/drm/drm_atomic.c298 :export:299 300Atomic Mode Setting IOCTL and UAPI Functions301--------------------------------------------302 303.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c304 :doc: overview305 306.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c307 :export:308 309CRTC Abstraction310================311 312.. kernel-doc:: drivers/gpu/drm/drm_crtc.c313 :doc: overview314 315CRTC Functions Reference316--------------------------------317 318.. kernel-doc:: include/drm/drm_crtc.h319 :internal:320 321.. kernel-doc:: drivers/gpu/drm/drm_crtc.c322 :export:323 324Color Management Functions Reference325------------------------------------326 327.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c328 :export:329 330.. kernel-doc:: include/drm/drm_color_mgmt.h331 :internal:332 333Frame Buffer Abstraction334========================335 336.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c337 :doc: overview338 339Frame Buffer Functions Reference340--------------------------------341 342.. kernel-doc:: include/drm/drm_framebuffer.h343 :internal:344 345.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c346 :export:347 348DRM Format Handling349===================350 351.. kernel-doc:: include/uapi/drm/drm_fourcc.h352 :doc: overview353 354Format Functions Reference355--------------------------356 357.. kernel-doc:: include/drm/drm_fourcc.h358 :internal:359 360.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c361 :export:362 363.. _kms_dumb_buffer_objects:364 365Dumb Buffer Objects366===================367 368.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c369 :doc: overview370 371Plane Abstraction372=================373 374.. kernel-doc:: drivers/gpu/drm/drm_plane.c375 :doc: overview376 377Plane Functions Reference378-------------------------379 380.. kernel-doc:: include/drm/drm_plane.h381 :internal:382 383.. kernel-doc:: drivers/gpu/drm/drm_plane.c384 :export:385 386Plane Composition Functions Reference387-------------------------------------388 389.. kernel-doc:: drivers/gpu/drm/drm_blend.c390 :export:391 392Plane Damage Tracking Functions Reference393-----------------------------------------394 395.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c396 :export:397 398.. kernel-doc:: include/drm/drm_damage_helper.h399 :internal:400 401Plane Panic Feature402-------------------403 404.. kernel-doc:: drivers/gpu/drm/drm_panic.c405 :doc: overview406 407Plane Panic Functions Reference408-------------------------------409 410.. kernel-doc:: include/drm/drm_panic.h411 :internal:412 413.. kernel-doc:: drivers/gpu/drm/drm_panic.c414 :export:415 416Display Modes Function Reference417================================418 419.. kernel-doc:: include/drm/drm_modes.h420 :internal:421 422.. kernel-doc:: drivers/gpu/drm/drm_modes.c423 :export:424 425Connector Abstraction426=====================427 428.. kernel-doc:: drivers/gpu/drm/drm_connector.c429 :doc: overview430 431Connector Functions Reference432-----------------------------433 434.. kernel-doc:: include/drm/drm_connector.h435 :internal:436 437.. kernel-doc:: drivers/gpu/drm/drm_connector.c438 :export:439 440Writeback Connectors441--------------------442 443.. kernel-doc:: drivers/gpu/drm/drm_writeback.c444 :doc: overview445 446.. kernel-doc:: include/drm/drm_writeback.h447 :internal:448 449.. kernel-doc:: drivers/gpu/drm/drm_writeback.c450 :export:451 452Encoder Abstraction453===================454 455.. kernel-doc:: drivers/gpu/drm/drm_encoder.c456 :doc: overview457 458Encoder Functions Reference459---------------------------460 461.. kernel-doc:: include/drm/drm_encoder.h462 :internal:463 464.. kernel-doc:: drivers/gpu/drm/drm_encoder.c465 :export:466 467KMS Locking468===========469 470.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c471 :doc: kms locking472 473.. kernel-doc:: include/drm/drm_modeset_lock.h474 :internal:475 476.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c477 :export:478 479KMS Properties480==============481 482This section of the documentation is primarily aimed at user-space developers.483For the driver APIs, see the other sections.484 485Requirements486------------487 488KMS drivers might need to add extra properties to support new features. Each489new property introduced in a driver needs to meet a few requirements, in490addition 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 that501 property on the object it attaches to.502 503* Its content must be decoded by the core and provided in the object's504 associated state structure. That includes anything drivers might want505 to precompute, like struct drm_clip_rect for planes.506 507* Its initial state must match the behavior prior to the property508 introduction. This might be a fixed value matching what the hardware509 does, or it may be inherited from the state the firmware left the510 system in during boot.511 512* An IGT test must be submitted where reasonable.513 514For historical reasons, non-standard, driver-specific properties exist. If a KMS515driver wants to add support for one of those properties, the requirements for516new properties apply where possible. Additionally, the documented behavior must517match the de facto semantics of the existing property to ensure compatibility.518Developers of the driver that first added the property should help with those519tasks and must ACK the documented behavior if possible.520 521Property Types and Blob Property Support522----------------------------------------523 524.. kernel-doc:: drivers/gpu/drm/drm_property.c525 :doc: overview526 527.. kernel-doc:: include/drm/drm_property.h528 :internal:529 530.. kernel-doc:: drivers/gpu/drm/drm_property.c531 :export:532 533.. _standard_connector_properties:534 535Standard Connector Properties536-----------------------------537 538.. kernel-doc:: drivers/gpu/drm/drm_connector.c539 :doc: standard connector properties540 541HDMI Specific Connector Properties542----------------------------------543 544.. kernel-doc:: drivers/gpu/drm/drm_connector.c545 :doc: HDMI connector properties546 547Analog TV Specific Connector Properties548---------------------------------------549 550.. kernel-doc:: drivers/gpu/drm/drm_connector.c551 :doc: Analog TV Connector Properties552 553Standard CRTC Properties554------------------------555 556.. kernel-doc:: drivers/gpu/drm/drm_crtc.c557 :doc: standard CRTC properties558 559Standard Plane Properties560-------------------------561 562.. kernel-doc:: drivers/gpu/drm/drm_plane.c563 :doc: standard plane properties564 565.. _plane_composition_properties:566 567Plane Composition Properties568----------------------------569 570.. kernel-doc:: drivers/gpu/drm/drm_blend.c571 :doc: overview572 573.. _damage_tracking_properties:574 575Damage Tracking Properties576--------------------------577 578.. kernel-doc:: drivers/gpu/drm/drm_plane.c579 :doc: damage tracking580 581Color Management Properties582---------------------------583 584.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c585 :doc: overview586 587Tile Group Property588-------------------589 590.. kernel-doc:: drivers/gpu/drm/drm_connector.c591 :doc: Tile group592 593Explicit Fencing Properties594---------------------------595 596.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c597 :doc: explicit fencing properties598 599 600Variable Refresh Properties601---------------------------602 603.. kernel-doc:: drivers/gpu/drm/drm_connector.c604 :doc: Variable refresh properties605 606Cursor Hotspot Properties607---------------------------608 609.. kernel-doc:: drivers/gpu/drm/drm_plane.c610 :doc: hotspot properties611 612Existing KMS Properties613-----------------------614 615The following table gives description of drm properties exposed by various616modules/drivers. Because this table is very unwieldy, do not add any new617properties here. Instead document them in a section above.618 619.. csv-table::620 :header-rows: 1621 :file: kms-properties.csv622 623Vertical Blanking624=================625 626.. kernel-doc:: drivers/gpu/drm/drm_vblank.c627 :doc: vblank handling628 629Vertical Blanking and Interrupt Handling Functions Reference630------------------------------------------------------------631 632.. kernel-doc:: include/drm/drm_vblank.h633 :internal:634 635.. kernel-doc:: drivers/gpu/drm/drm_vblank.c636 :export:637 638Vertical Blank Work639===================640 641.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c642 :doc: vblank works643 644Vertical Blank Work Functions Reference645---------------------------------------646 647.. kernel-doc:: include/drm/drm_vblank_work.h648 :internal:649 650.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c651 :export:652