1 =========================
2 Kernel Mode Setting (KMS)
3 =========================
5 Drivers must initialize the mode setting core by calling
6 :c:func:`drm_mode_config_init()` on the DRM device. The function
7 initializes the :c:type:`struct drm_device <drm_device>`
8 mode_config field and never fails. Once done, mode configuration must
9 be setup by initializing the following fields.
11 - int min_width, min_height; int max_width, max_height;
12 Minimum and maximum width and height of the frame buffers in pixel
15 - struct drm_mode_config_funcs \*funcs;
16 Mode setting functions.
21 .. kernel-render:: DOT
22 :alt: KMS Display Pipeline
23 :caption: KMS Display Pipeline Overview
28 subgraph cluster_static {
30 label="Static Objects"
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"
39 subgraph cluster_user_created {
41 label="Userspace-Created"
44 "drm_framebuffer 1" -> "drm_plane A"
45 "drm_framebuffer 2" -> "drm_plane B"
48 subgraph cluster_connector {
52 "drm_encoder A" -> "drm_connector A"
53 "drm_encoder B" -> "drm_connector B"
57 The basic object structure KMS presents to userspace is fairly simple.
58 Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`,
59 see `Frame Buffer Abstraction`_) feed into planes. Planes are represented by
60 :c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more
61 details. 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`_)
63 for blending. The precise blending step is explained in more detail in `Plane
64 Composition Properties`_ and related chapters.
66 For the output routing the first step is encoders (represented by
67 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
68 are really just internal artifacts of the helper libraries used to implement KMS
69 drivers. Besides that they make it unecessarily more complicated for userspace
70 to figure out which connections between a CRTC and a connector are possible, and
71 what kind of cloning is supported, they serve no purpose in the userspace API.
72 Unfortunately encoders have been exposed to userspace, hence can't remove them
73 at this point. Futhermore the exposed restrictions are often wrongly set by
74 drivers, and in many cases not powerful enough to express the real restrictions.
75 A CRTC can be connected to multiple encoders, and for an active CRTC there must
76 be at least one encoder.
78 The final, and real, endpoint in the display chain is the connector (represented
79 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
80 Abstraction`_). Connectors can have different possible encoders, but the kernel
81 driver selects which encoder to use for each connector. The use case is DVI,
82 which could switch between an analog and a digital encoder. Encoders can also
83 drive multiple different connectors. There is exactly one active connector for
86 Internally the output pipeline is a bit more complex and matches today's
87 hardware more closely:
89 .. kernel-render:: DOT
90 :alt: KMS Output Pipeline
91 :caption: KMS Output Pipeline
93 digraph "Output Pipeline" {
97 "drm_crtc" [bgcolor=grey style=filled]
100 subgraph cluster_internal {
102 label="Internal Pipeline"
104 node [bgcolor=grey style=filled]
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";
118 "drm_crtc" -> "drm_encoder A"
119 "drm_crtc" -> "drm_encoder B"
120 "drm_crtc" -> "drm_encoder C"
123 subgraph cluster_output {
127 "drm_encoder A" -> "drm_connector A";
128 "drm_bridge B" -> "drm_connector B";
129 "drm_bridge C2" -> "drm_connector C";
135 Internally two additional helper objects come into play. First, to be able to
136 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
137 more :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
139 changed, which means the cross-bar (if there is any) needs to be mapped between
140 the CRTC and any encoders. Often for drivers with bridges there's no code left
141 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
142 essentially only leave a dummy routing object behind, which is needed for
143 backwards compatibility since encoders are exposed to userspace.
145 The 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
147 point, but are generally linked to the driver private structure that embeds
148 :c:type:`struct drm_connector <drm_connector>`.
150 Note that currently the bridge chaining and interactions with connectors and
151 panels are still in-flux and not really fully sorted out yet.
153 KMS Core Structures and Functions
154 =================================
156 .. kernel-doc:: include/drm/drm_mode_config.h
159 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
162 Modeset Base Object Abstraction
163 ===============================
165 .. kernel-render:: DOT
166 :alt: Mode Objects and Properties
167 :caption: Mode Objects and Properties
172 "drm_property A" -> "drm_mode_object A"
173 "drm_property A" -> "drm_mode_object B"
174 "drm_property B" -> "drm_mode_object A"
177 The 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,
179 which are especially important for the atomic IOCTL (see `Atomic Mode
180 Setting`_). The somewhat surprising part here is that properties are not
181 directly instantiated on each object, but free-standing mode objects themselves,
182 represented by :c:type:`struct drm_property <drm_property>`, which only specify
183 the type and value range of a property. Any given property can be attached
184 multiple times to different objects using :c:func:`drm_object_attach_property()
185 <drm_object_attach_property>`.
187 .. kernel-doc:: include/drm/drm_mode_object.h
190 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
197 .. kernel-render:: DOT
198 :alt: Mode Objects and Properties
199 :caption: Mode Objects and Properties
204 subgraph cluster_state {
206 label="Free-standing state"
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"
215 subgraph cluster_current {
217 label="Current state"
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"
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"
232 "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
233 "duplicated drm_plane_state A" -> "drm_device"[style=invis]
236 Atomic provides transactional modeset (including planes) updates, but a
237 bit differently from the usual transactional approach of try-commit and
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.
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.
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
255 Taken all together there's two consequences for the atomic design:
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.
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.
272 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
273 coverage of specific topics.
275 Handling Driver Private State
276 -----------------------------
278 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
279 :doc: handling driver private state
281 Atomic Mode Setting Function Reference
282 --------------------------------------
284 .. kernel-doc:: include/drm/drm_atomic.h
287 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
290 Atomic Mode Setting IOCTL and UAPI Functions
291 --------------------------------------------
293 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
296 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
302 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
305 CRTC Functions Reference
306 --------------------------------
308 .. kernel-doc:: include/drm/drm_crtc.h
311 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
314 Frame Buffer Abstraction
315 ========================
317 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
320 Frame Buffer Functions Reference
321 --------------------------------
323 .. kernel-doc:: include/drm/drm_framebuffer.h
326 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
332 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
335 Format Functions Reference
336 --------------------------
338 .. kernel-doc:: include/drm/drm_fourcc.h
341 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
347 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
353 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
356 Plane Functions Reference
357 -------------------------
359 .. kernel-doc:: include/drm/drm_plane.h
362 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
365 Display Modes Function Reference
366 ================================
368 .. kernel-doc:: include/drm/drm_modes.h
371 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
374 Connector Abstraction
375 =====================
377 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
380 Connector Functions Reference
381 -----------------------------
383 .. kernel-doc:: include/drm/drm_connector.h
386 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
392 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
395 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
401 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
404 Encoder Functions Reference
405 ---------------------------
407 .. kernel-doc:: include/drm/drm_encoder.h
410 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
416 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
419 .. kernel-doc:: include/drm/drm_modeset_lock.h
422 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
428 Property Types and Blob Property Support
429 ----------------------------------------
431 .. kernel-doc:: drivers/gpu/drm/drm_property.c
434 .. kernel-doc:: include/drm/drm_property.h
437 .. kernel-doc:: drivers/gpu/drm/drm_property.c
440 Standard Connector Properties
441 -----------------------------
443 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
444 :doc: standard connector properties
446 HDMI Specific Connector Properties
447 ----------------------------------
449 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
450 :doc: HDMI connector properties
452 Plane Composition Properties
453 ----------------------------
455 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
458 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
464 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
467 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
470 .. kernel-doc:: include/drm/drm_damage_helper.h
473 Color Management Properties
474 ---------------------------
476 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
479 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
485 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
488 Explicit Fencing Properties
489 ---------------------------
491 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
492 :doc: explicit fencing properties
495 Variable Refresh Properties
496 ---------------------------
498 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
499 :doc: Variable refresh properties
501 Existing KMS Properties
502 -----------------------
504 The following table gives description of drm properties exposed by various
505 modules/drivers. Because this table is very unwieldy, do not add any new
506 properties here. Instead document them in a section above.
510 :file: kms-properties.csv
515 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
516 :doc: vblank handling
518 Vertical Blanking and Interrupt Handling Functions Reference
519 ------------------------------------------------------------
521 .. kernel-doc:: include/drm/drm_vblank.h
524 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c