1 =========================
2 Kernel Mode Setting (KMS)
3 =========================
5 Drivers must initialize the mode setting core by calling
6 drmm_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 drm_object_attach_property().
186 .. kernel-doc:: include/drm/drm_mode_object.h
189 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
196 .. kernel-render:: DOT
197 :alt: Mode Objects and Properties
198 :caption: Mode Objects and Properties
203 subgraph cluster_state {
205 label="Free-standing state"
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"
214 subgraph cluster_current {
216 label="Current state"
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"
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"
231 "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
232 "duplicated drm_plane_state A" -> "drm_device"[style=invis]
235 Atomic provides transactional modeset (including planes) updates, but a
236 bit differently from the usual transactional approach of try-commit and
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.
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.
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
254 Taken all together there's two consequences for the atomic design:
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, see :c:type:`struct
263 drm_private_state<drm_private_state>`.
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 Locking of atomic state structures is internally using :c:type:`struct
273 drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
274 exposed to drivers, instead the right locks should be automatically acquired by
275 any function that duplicates or peeks into a state, like e.g.
276 drm_atomic_get_crtc_state(). Locking only protects the software data
277 structure, ordering of committing state changes to hardware is sequenced using
278 :c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
280 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
281 coverage of specific topics.
283 Handling Driver Private State
284 -----------------------------
286 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
287 :doc: handling driver private state
289 Atomic Mode Setting Function Reference
290 --------------------------------------
292 .. kernel-doc:: include/drm/drm_atomic.h
295 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
298 Atomic Mode Setting IOCTL and UAPI Functions
299 --------------------------------------------
301 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
304 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
310 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
313 CRTC Functions Reference
314 --------------------------------
316 .. kernel-doc:: include/drm/drm_crtc.h
319 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
322 Frame Buffer Abstraction
323 ========================
325 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
328 Frame Buffer Functions Reference
329 --------------------------------
331 .. kernel-doc:: include/drm/drm_framebuffer.h
334 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
340 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
343 Format Functions Reference
344 --------------------------
346 .. kernel-doc:: include/drm/drm_fourcc.h
349 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
355 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
361 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
364 Plane Functions Reference
365 -------------------------
367 .. kernel-doc:: include/drm/drm_plane.h
370 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
373 Display Modes Function Reference
374 ================================
376 .. kernel-doc:: include/drm/drm_modes.h
379 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
382 Connector Abstraction
383 =====================
385 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
388 Connector Functions Reference
389 -----------------------------
391 .. kernel-doc:: include/drm/drm_connector.h
394 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
400 .. kernel-doc:: include/drm/drm_writeback.h
403 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
406 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
412 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
415 Encoder Functions Reference
416 ---------------------------
418 .. kernel-doc:: include/drm/drm_encoder.h
421 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
427 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
430 .. kernel-doc:: include/drm/drm_modeset_lock.h
433 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
439 Property Types and Blob Property Support
440 ----------------------------------------
442 .. kernel-doc:: drivers/gpu/drm/drm_property.c
445 .. kernel-doc:: include/drm/drm_property.h
448 .. kernel-doc:: drivers/gpu/drm/drm_property.c
451 Standard Connector Properties
452 -----------------------------
454 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
455 :doc: standard connector properties
457 HDMI Specific Connector Properties
458 ----------------------------------
460 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
461 :doc: HDMI connector properties
463 Standard CRTC Properties
464 ------------------------
466 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
467 :doc: standard CRTC properties
469 Plane Composition Properties
470 ----------------------------
472 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
475 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
481 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
484 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
487 .. kernel-doc:: include/drm/drm_damage_helper.h
490 Color Management Properties
491 ---------------------------
493 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
496 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
499 .. kernel-doc:: include/drm/drm_color_mgmt.h
505 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
508 Explicit Fencing Properties
509 ---------------------------
511 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
512 :doc: explicit fencing properties
515 Variable Refresh Properties
516 ---------------------------
518 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
519 :doc: Variable refresh properties
521 Existing KMS Properties
522 -----------------------
524 The following table gives description of drm properties exposed by various
525 modules/drivers. Because this table is very unwieldy, do not add any new
526 properties here. Instead document them in a section above.
530 :file: kms-properties.csv
535 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
536 :doc: vblank handling
538 Vertical Blanking and Interrupt Handling Functions Reference
539 ------------------------------------------------------------
541 .. kernel-doc:: include/drm/drm_vblank.h
544 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
550 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
553 Vertical Blank Work Functions Reference
554 ---------------------------------------
556 .. kernel-doc:: include/drm/drm_vblank_work.h
559 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c