0001 =========================
0002 Kernel Mode Setting (KMS)
0003 =========================
0004
0005 Drivers must initialize the mode setting core by calling
0006 drmm_mode_config_init() on the DRM device. The function
0007 initializes the :c:type:`struct drm_device <drm_device>`
0008 mode_config field and never fails. Once done, mode configuration must
0009 be setup by initializing the following fields.
0010
0011 - int min_width, min_height; int max_width, max_height;
0012 Minimum and maximum width and height of the frame buffers in pixel
0013 units.
0014
0015 - struct drm_mode_config_funcs \*funcs;
0016 Mode setting functions.
0017
0018 Overview
0019 ========
0020
0021 .. kernel-render:: DOT
0022 :alt: KMS Display Pipeline
0023 :caption: KMS Display Pipeline Overview
0024
0025 digraph "KMS" {
0026 node [shape=box]
0027
0028 subgraph cluster_static {
0029 style=dashed
0030 label="Static Objects"
0031
0032 node [bgcolor=grey style=filled]
0033 "drm_plane A" -> "drm_crtc"
0034 "drm_plane B" -> "drm_crtc"
0035 "drm_crtc" -> "drm_encoder A"
0036 "drm_crtc" -> "drm_encoder B"
0037 }
0038
0039 subgraph cluster_user_created {
0040 style=dashed
0041 label="Userspace-Created"
0042
0043 node [shape=oval]
0044 "drm_framebuffer 1" -> "drm_plane A"
0045 "drm_framebuffer 2" -> "drm_plane B"
0046 }
0047
0048 subgraph cluster_connector {
0049 style=dashed
0050 label="Hotpluggable"
0051
0052 "drm_encoder A" -> "drm_connector A"
0053 "drm_encoder B" -> "drm_connector B"
0054 }
0055 }
0056
0057 The basic object structure KMS presents to userspace is fairly simple.
0058 Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`,
0059 see `Frame Buffer Abstraction`_) feed into planes. Planes are represented by
0060 :c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more
0061 details. One or more (or even no) planes feed their pixel data into a CRTC
0062 (represented by :c:type:`struct drm_crtc <drm_crtc>`, see `CRTC Abstraction`_)
0063 for blending. The precise blending step is explained in more detail in `Plane
0064 Composition Properties`_ and related chapters.
0065
0066 For the output routing the first step is encoders (represented by
0067 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
0068 are really just internal artifacts of the helper libraries used to implement KMS
0069 drivers. Besides that they make it unecessarily more complicated for userspace
0070 to figure out which connections between a CRTC and a connector are possible, and
0071 what kind of cloning is supported, they serve no purpose in the userspace API.
0072 Unfortunately encoders have been exposed to userspace, hence can't remove them
0073 at this point. Futhermore the exposed restrictions are often wrongly set by
0074 drivers, and in many cases not powerful enough to express the real restrictions.
0075 A CRTC can be connected to multiple encoders, and for an active CRTC there must
0076 be at least one encoder.
0077
0078 The final, and real, endpoint in the display chain is the connector (represented
0079 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
0080 Abstraction`_). Connectors can have different possible encoders, but the kernel
0081 driver selects which encoder to use for each connector. The use case is DVI,
0082 which could switch between an analog and a digital encoder. Encoders can also
0083 drive multiple different connectors. There is exactly one active connector for
0084 every active encoder.
0085
0086 Internally the output pipeline is a bit more complex and matches today's
0087 hardware more closely:
0088
0089 .. kernel-render:: DOT
0090 :alt: KMS Output Pipeline
0091 :caption: KMS Output Pipeline
0092
0093 digraph "Output Pipeline" {
0094 node [shape=box]
0095
0096 subgraph {
0097 "drm_crtc" [bgcolor=grey style=filled]
0098 }
0099
0100 subgraph cluster_internal {
0101 style=dashed
0102 label="Internal Pipeline"
0103 {
0104 node [bgcolor=grey style=filled]
0105 "drm_encoder A";
0106 "drm_encoder B";
0107 "drm_encoder C";
0108 }
0109
0110 {
0111 node [bgcolor=grey style=filled]
0112 "drm_encoder B" -> "drm_bridge B"
0113 "drm_encoder C" -> "drm_bridge C1"
0114 "drm_bridge C1" -> "drm_bridge C2";
0115 }
0116 }
0117
0118 "drm_crtc" -> "drm_encoder A"
0119 "drm_crtc" -> "drm_encoder B"
0120 "drm_crtc" -> "drm_encoder C"
0121
0122
0123 subgraph cluster_output {
0124 style=dashed
0125 label="Outputs"
0126
0127 "drm_encoder A" -> "drm_connector A";
0128 "drm_bridge B" -> "drm_connector B";
0129 "drm_bridge C2" -> "drm_connector C";
0130
0131 "drm_panel"
0132 }
0133 }
0134
0135 Internally two additional helper objects come into play. First, to be able to
0136 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
0137 more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge
0138 <drm_bridge>`) can be linked to an encoder. This link is static and cannot be
0139 changed, which means the cross-bar (if there is any) needs to be mapped between
0140 the CRTC and any encoders. Often for drivers with bridges there's no code left
0141 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
0142 essentially only leave a dummy routing object behind, which is needed for
0143 backwards compatibility since encoders are exposed to userspace.
0144
0145 The second object is for panels, represented by :c:type:`struct drm_panel
0146 <drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding
0147 point, but are generally linked to the driver private structure that embeds
0148 :c:type:`struct drm_connector <drm_connector>`.
0149
0150 Note that currently the bridge chaining and interactions with connectors and
0151 panels are still in-flux and not really fully sorted out yet.
0152
0153 KMS Core Structures and Functions
0154 =================================
0155
0156 .. kernel-doc:: include/drm/drm_mode_config.h
0157 :internal:
0158
0159 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
0160 :export:
0161
0162 .. _kms_base_object_abstraction:
0163
0164 Modeset Base Object Abstraction
0165 ===============================
0166
0167 .. kernel-render:: DOT
0168 :alt: Mode Objects and Properties
0169 :caption: Mode Objects and Properties
0170
0171 digraph {
0172 node [shape=box]
0173
0174 "drm_property A" -> "drm_mode_object A"
0175 "drm_property A" -> "drm_mode_object B"
0176 "drm_property B" -> "drm_mode_object A"
0177 }
0178
0179 The base structure for all KMS objects is :c:type:`struct drm_mode_object
0180 <drm_mode_object>`. One of the base services it provides is tracking properties,
0181 which are especially important for the atomic IOCTL (see `Atomic Mode
0182 Setting`_). The somewhat surprising part here is that properties are not
0183 directly instantiated on each object, but free-standing mode objects themselves,
0184 represented by :c:type:`struct drm_property <drm_property>`, which only specify
0185 the type and value range of a property. Any given property can be attached
0186 multiple times to different objects using drm_object_attach_property().
0187
0188 .. kernel-doc:: include/drm/drm_mode_object.h
0189 :internal:
0190
0191 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
0192 :export:
0193
0194 Atomic Mode Setting
0195 ===================
0196
0197
0198 .. kernel-render:: DOT
0199 :alt: Mode Objects and Properties
0200 :caption: Mode Objects and Properties
0201
0202 digraph {
0203 node [shape=box]
0204
0205 subgraph cluster_state {
0206 style=dashed
0207 label="Free-standing state"
0208
0209 "drm_atomic_state" -> "duplicated drm_plane_state A"
0210 "drm_atomic_state" -> "duplicated drm_plane_state B"
0211 "drm_atomic_state" -> "duplicated drm_crtc_state"
0212 "drm_atomic_state" -> "duplicated drm_connector_state"
0213 "drm_atomic_state" -> "duplicated driver private state"
0214 }
0215
0216 subgraph cluster_current {
0217 style=dashed
0218 label="Current state"
0219
0220 "drm_device" -> "drm_plane A"
0221 "drm_device" -> "drm_plane B"
0222 "drm_device" -> "drm_crtc"
0223 "drm_device" -> "drm_connector"
0224 "drm_device" -> "driver private object"
0225
0226 "drm_plane A" -> "drm_plane_state A"
0227 "drm_plane B" -> "drm_plane_state B"
0228 "drm_crtc" -> "drm_crtc_state"
0229 "drm_connector" -> "drm_connector_state"
0230 "driver private object" -> "driver private state"
0231 }
0232
0233 "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
0234 "duplicated drm_plane_state A" -> "drm_device"[style=invis]
0235 }
0236
0237 Atomic provides transactional modeset (including planes) updates, but a
0238 bit differently from the usual transactional approach of try-commit and
0239 rollback:
0240
0241 - Firstly, no hardware changes are allowed when the commit would fail. This
0242 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
0243 userspace to explore whether certain configurations would work or not.
0244
0245 - This would still allow setting and rollback of just the software state,
0246 simplifying conversion of existing drivers. But auditing drivers for
0247 correctness of the atomic_check code becomes really hard with that: Rolling
0248 back changes in data structures all over the place is hard to get right.
0249
0250 - Lastly, for backwards compatibility and to support all use-cases, atomic
0251 updates need to be incremental and be able to execute in parallel. Hardware
0252 doesn't always allow it, but where possible plane updates on different CRTCs
0253 should not interfere, and not get stalled due to output routing changing on
0254 different CRTCs.
0255
0256 Taken all together there's two consequences for the atomic design:
0257
0258 - The overall state is split up into per-object state structures:
0259 :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
0260 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
0261 drm_connector_state <drm_connector_state>` for connectors. These are the only
0262 objects with userspace-visible and settable state. For internal state drivers
0263 can subclass these structures through embeddeding, or add entirely new state
0264 structures for their globally shared hardware functions, see :c:type:`struct
0265 drm_private_state<drm_private_state>`.
0266
0267 - An atomic update is assembled and validated as an entirely free-standing pile
0268 of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
0269 container. Driver private state structures are also tracked in the same
0270 structure; see the next chapter. Only when a state is committed is it applied
0271 to the driver and modeset objects. This way rolling back an update boils down
0272 to releasing memory and unreferencing objects like framebuffers.
0273
0274 Locking of atomic state structures is internally using :c:type:`struct
0275 drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
0276 exposed to drivers, instead the right locks should be automatically acquired by
0277 any function that duplicates or peeks into a state, like e.g.
0278 drm_atomic_get_crtc_state(). Locking only protects the software data
0279 structure, ordering of committing state changes to hardware is sequenced using
0280 :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
0281
0282 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
0283 coverage of specific topics.
0284
0285 Handling Driver Private State
0286 -----------------------------
0287
0288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
0289 :doc: handling driver private state
0290
0291 Atomic Mode Setting Function Reference
0292 --------------------------------------
0293
0294 .. kernel-doc:: include/drm/drm_atomic.h
0295 :internal:
0296
0297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
0298 :export:
0299
0300 Atomic Mode Setting IOCTL and UAPI Functions
0301 --------------------------------------------
0302
0303 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
0304 :doc: overview
0305
0306 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
0307 :export:
0308
0309 CRTC Abstraction
0310 ================
0311
0312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
0313 :doc: overview
0314
0315 CRTC Functions Reference
0316 --------------------------------
0317
0318 .. kernel-doc:: include/drm/drm_crtc.h
0319 :internal:
0320
0321 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
0322 :export:
0323
0324 Color Management Functions Reference
0325 ------------------------------------
0326
0327 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
0328 :export:
0329
0330 .. kernel-doc:: include/drm/drm_color_mgmt.h
0331 :internal:
0332
0333 Frame Buffer Abstraction
0334 ========================
0335
0336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
0337 :doc: overview
0338
0339 Frame Buffer Functions Reference
0340 --------------------------------
0341
0342 .. kernel-doc:: include/drm/drm_framebuffer.h
0343 :internal:
0344
0345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
0346 :export:
0347
0348 DRM Format Handling
0349 ===================
0350
0351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
0352 :doc: overview
0353
0354 Format Functions Reference
0355 --------------------------
0356
0357 .. kernel-doc:: include/drm/drm_fourcc.h
0358 :internal:
0359
0360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
0361 :export:
0362
0363 Dumb Buffer Objects
0364 ===================
0365
0366 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
0367 :doc: overview
0368
0369 Plane Abstraction
0370 =================
0371
0372 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
0373 :doc: overview
0374
0375 Plane Functions Reference
0376 -------------------------
0377
0378 .. kernel-doc:: include/drm/drm_plane.h
0379 :internal:
0380
0381 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
0382 :export:
0383
0384 Plane Composition Functions Reference
0385 -------------------------------------
0386
0387 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
0388 :export:
0389
0390 Plane Damage Tracking Functions Reference
0391 -----------------------------------------
0392
0393 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
0394 :export:
0395
0396 .. kernel-doc:: include/drm/drm_damage_helper.h
0397 :internal:
0398
0399 Display Modes Function Reference
0400 ================================
0401
0402 .. kernel-doc:: include/drm/drm_modes.h
0403 :internal:
0404
0405 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
0406 :export:
0407
0408 Connector Abstraction
0409 =====================
0410
0411 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
0412 :doc: overview
0413
0414 Connector Functions Reference
0415 -----------------------------
0416
0417 .. kernel-doc:: include/drm/drm_connector.h
0418 :internal:
0419
0420 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
0421 :export:
0422
0423 Writeback Connectors
0424 --------------------
0425
0426 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
0427 :doc: overview
0428
0429 .. kernel-doc:: include/drm/drm_writeback.h
0430 :internal:
0431
0432 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
0433 :export:
0434
0435 Encoder Abstraction
0436 ===================
0437
0438 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
0439 :doc: overview
0440
0441 Encoder Functions Reference
0442 ---------------------------
0443
0444 .. kernel-doc:: include/drm/drm_encoder.h
0445 :internal:
0446
0447 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
0448 :export:
0449
0450 KMS Locking
0451 ===========
0452
0453 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
0454 :doc: kms locking
0455
0456 .. kernel-doc:: include/drm/drm_modeset_lock.h
0457 :internal:
0458
0459 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
0460 :export:
0461
0462 KMS Properties
0463 ==============
0464
0465 This section of the documentation is primarily aimed at user-space developers.
0466 For the driver APIs, see the other sections.
0467
0468 Requirements
0469 ------------
0470
0471 KMS drivers might need to add extra properties to support new features. Each
0472 new property introduced in a driver needs to meet a few requirements, in
0473 addition to the one mentioned above:
0474
0475 * It must be standardized, documenting:
0476
0477 * The full, exact, name string;
0478 * If the property is an enum, all the valid value name strings;
0479 * What values are accepted, and what these values mean;
0480 * What the property does and how it can be used;
0481 * How the property might interact with other, existing properties.
0482
0483 * It must provide a generic helper in the core code to register that
0484 property on the object it attaches to.
0485
0486 * Its content must be decoded by the core and provided in the object's
0487 associated state structure. That includes anything drivers might want
0488 to precompute, like struct drm_clip_rect for planes.
0489
0490 * Its initial state must match the behavior prior to the property
0491 introduction. This might be a fixed value matching what the hardware
0492 does, or it may be inherited from the state the firmware left the
0493 system in during boot.
0494
0495 * An IGT test must be submitted where reasonable.
0496
0497 Property Types and Blob Property Support
0498 ----------------------------------------
0499
0500 .. kernel-doc:: drivers/gpu/drm/drm_property.c
0501 :doc: overview
0502
0503 .. kernel-doc:: include/drm/drm_property.h
0504 :internal:
0505
0506 .. kernel-doc:: drivers/gpu/drm/drm_property.c
0507 :export:
0508
0509 .. _standard_connector_properties:
0510
0511 Standard Connector Properties
0512 -----------------------------
0513
0514 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
0515 :doc: standard connector properties
0516
0517 HDMI Specific Connector Properties
0518 ----------------------------------
0519
0520 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
0521 :doc: HDMI connector properties
0522
0523 Standard CRTC Properties
0524 ------------------------
0525
0526 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
0527 :doc: standard CRTC properties
0528
0529 Standard Plane Properties
0530 -------------------------
0531
0532 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
0533 :doc: standard plane properties
0534
0535 Plane Composition Properties
0536 ----------------------------
0537
0538 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
0539 :doc: overview
0540
0541 Damage Tracking Properties
0542 --------------------------
0543
0544 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
0545 :doc: damage tracking
0546
0547 Color Management Properties
0548 ---------------------------
0549
0550 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
0551 :doc: overview
0552
0553 Tile Group Property
0554 -------------------
0555
0556 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
0557 :doc: Tile group
0558
0559 Explicit Fencing Properties
0560 ---------------------------
0561
0562 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
0563 :doc: explicit fencing properties
0564
0565
0566 Variable Refresh Properties
0567 ---------------------------
0568
0569 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
0570 :doc: Variable refresh properties
0571
0572 Existing KMS Properties
0573 -----------------------
0574
0575 The following table gives description of drm properties exposed by various
0576 modules/drivers. Because this table is very unwieldy, do not add any new
0577 properties here. Instead document them in a section above.
0578
0579 .. csv-table::
0580 :header-rows: 1
0581 :file: kms-properties.csv
0582
0583 Vertical Blanking
0584 =================
0585
0586 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
0587 :doc: vblank handling
0588
0589 Vertical Blanking and Interrupt Handling Functions Reference
0590 ------------------------------------------------------------
0591
0592 .. kernel-doc:: include/drm/drm_vblank.h
0593 :internal:
0594
0595 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
0596 :export:
0597
0598 Vertical Blank Work
0599 ===================
0600
0601 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
0602 :doc: vblank works
0603
0604 Vertical Blank Work Functions Reference
0605 ---------------------------------------
0606
0607 .. kernel-doc:: include/drm/drm_vblank_work.h
0608 :internal:
0609
0610 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
0611 :export:
