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. One or more (or even no)
60 planes feed their pixel data into a CRTC (represented by :c:type:`struct
61 drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise
62 blending step is explained in more detail in `Plane Composition Properties`_ and
65 For the output routing the first step is encoders (represented by
66 :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
67 are really just internal artifacts of the helper libraries used to implement KMS
68 drivers. Besides that they make it unecessarily more complicated for userspace
69 to figure out which connections between a CRTC and a connector are possible, and
70 what kind of cloning is supported, they serve no purpose in the userspace API.
71 Unfortunately encoders have been exposed to userspace, hence can't remove them
72 at this point. Futhermore the exposed restrictions are often wrongly set by
73 drivers, and in many cases not powerful enough to express the real restrictions.
74 A CRTC can be connected to multiple encoders, and for an active CRTC there must
75 be at least one encoder.
77 The final, and real, endpoint in the display chain is the connector (represented
78 by :c:type:`struct drm_connector <drm_connector>`, see `Connector
79 Abstraction`_). Connectors can have different possible encoders, but the kernel
80 driver selects which encoder to use for each connector. The use case is DVI,
81 which could switch between an analog and a digital encoder. Encoders can also
82 drive multiple different connectors. There is exactly one active connector for
85 Internally the output pipeline is a bit more complex and matches today's
86 hardware more closely:
88 .. kernel-render:: DOT
89 :alt: KMS Output Pipeline
90 :caption: KMS Output Pipeline
92 digraph "Output Pipeline" {
96 "drm_crtc" [bgcolor=grey style=filled]
99 subgraph cluster_internal {
101 label="Internal Pipeline"
103 node [bgcolor=grey style=filled]
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";
117 "drm_crtc" -> "drm_encoder A"
118 "drm_crtc" -> "drm_encoder B"
119 "drm_crtc" -> "drm_encoder C"
122 subgraph cluster_output {
126 "drm_encoder A" -> "drm_connector A";
127 "drm_bridge B" -> "drm_connector B";
128 "drm_bridge C2" -> "drm_connector C";
134 Internally two additional helper objects come into play. First, to be able to
135 share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
136 more :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
138 changed, which means the cross-bar (if there is any) needs to be mapped between
139 the CRTC and any encoders. Often for drivers with bridges there's no code left
140 at the encoder level. Atomic drivers can leave out all the encoder callbacks to
141 essentially only leave a dummy routing object behind, which is needed for
142 backwards compatibility since encoders are exposed to userspace.
144 The 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
146 point, but are generally linked to the driver private structure that embeds
147 :c:type:`struct drm_connector <drm_connector>`.
149 Note that currently the bridge chaining and interactions with connectors and
150 panels are still in-flux and not really fully sorted out yet.
152 KMS Core Structures and Functions
153 =================================
155 .. kernel-doc:: include/drm/drm_mode_config.h
158 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
161 Modeset Base Object Abstraction
162 ===============================
164 .. kernel-render:: DOT
165 :alt: Mode Objects and Properties
166 :caption: Mode Objects and Properties
171 "drm_property A" -> "drm_mode_object A"
172 "drm_property A" -> "drm_mode_object B"
173 "drm_property B" -> "drm_mode_object A"
176 The 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,
178 which are especially important for the atomic IOCTL (see `Atomic Mode
179 Setting`_). The somewhat surprising part here is that properties are not
180 directly instantiated on each object, but free-standing mode objects themselves,
181 represented by :c:type:`struct drm_property <drm_property>`, which only specify
182 the type and value range of a property. Any given property can be attached
183 multiple times to different objects using :c:func:`drm_object_attach_property()
184 <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.
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.
271 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
272 coverage of specific topics.
274 Handling Driver Private State
275 -----------------------------
277 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
278 :doc: handling driver private state
280 Atomic Mode Setting Function Reference
281 --------------------------------------
283 .. kernel-doc:: include/drm/drm_atomic.h
286 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
289 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
295 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
298 CRTC Functions Reference
299 --------------------------------
301 .. kernel-doc:: include/drm/drm_crtc.h
304 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
307 Frame Buffer Abstraction
308 ========================
310 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
313 Frame Buffer Functions Reference
314 --------------------------------
316 .. kernel-doc:: include/drm/drm_framebuffer.h
319 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
325 .. kernel-doc:: include/drm/drm_fourcc.h
328 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
334 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
340 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
343 Plane Functions Reference
344 -------------------------
346 .. kernel-doc:: include/drm/drm_plane.h
349 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
352 Display Modes Function Reference
353 ================================
355 .. kernel-doc:: include/drm/drm_modes.h
358 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
361 Connector Abstraction
362 =====================
364 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
367 Connector Functions Reference
368 -----------------------------
370 .. kernel-doc:: include/drm/drm_connector.h
373 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
379 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
382 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
388 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
391 Encoder Functions Reference
392 ---------------------------
394 .. kernel-doc:: include/drm/drm_encoder.h
397 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
400 KMS Initialization and Cleanup
401 ==============================
403 A KMS device is abstracted and exposed as a set of planes, CRTCs,
404 encoders and connectors. KMS drivers must thus create and initialize all
405 those objects at load time after initializing mode setting.
407 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
408 --------------------------------------------
410 A CRTC is an abstraction representing a part of the chip that contains a
411 pointer to a scanout buffer. Therefore, the number of CRTCs available
412 determines how many independent scanout buffers can be active at any
413 given time. The CRTC structure contains several fields to support this:
414 a pointer to some video memory (abstracted as a frame buffer object), a
415 display mode, and an (x, y) offset into the video memory to support
416 panning or configurations where one piece of video memory spans multiple
422 A KMS device must create and register at least one struct
423 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
424 allocated and zeroed by the driver, possibly as part of a larger
425 structure, and registered with a call to :c:func:`drm_crtc_init()`
426 with a pointer to CRTC functions.
432 The DRM core manages its objects' lifetime. When an object is not needed
433 anymore the core calls its destroy function, which must clean up and
434 free every resource allocated for the object. Every
435 :c:func:`drm_\*_init()` call must be matched with a corresponding
436 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
437 (:c:func:`drm_crtc_cleanup()`), planes
438 (:c:func:`drm_plane_cleanup()`), encoders
439 (:c:func:`drm_encoder_cleanup()`) and connectors
440 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
441 have been added to sysfs must be removed by a call to
442 :c:func:`drm_connector_unregister()` before calling
443 :c:func:`drm_connector_cleanup()`.
445 Connectors state change detection must be cleanup up with a call to
446 :c:func:`drm_kms_helper_poll_fini()`.
448 Output discovery and initialization example
449 -------------------------------------------
453 void intel_crt_init(struct drm_device *dev)
455 struct drm_connector *connector;
456 struct intel_output *intel_output;
458 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
462 connector = &intel_output->base;
463 drm_connector_init(dev, &intel_output->base,
464 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
466 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
467 DRM_MODE_ENCODER_DAC);
469 drm_connector_attach_encoder(&intel_output->base,
472 /* Set up the DDC bus. */
473 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
474 if (!intel_output->ddc_bus) {
475 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
480 intel_output->type = INTEL_OUTPUT_ANALOG;
481 connector->interlace_allowed = 0;
482 connector->doublescan_allowed = 0;
484 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
485 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
487 drm_connector_register(connector);
490 In the example above (taken from the i915 driver), a CRTC, connector and
491 encoder combination is created. A device-specific i2c bus is also
492 created for fetching EDID data and performing monitor detection. Once
493 the process is complete, the new connector is registered with sysfs to
494 make its properties available to applications.
499 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
502 .. kernel-doc:: include/drm/drm_modeset_lock.h
505 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
511 Property Types and Blob Property Support
512 ----------------------------------------
514 .. kernel-doc:: drivers/gpu/drm/drm_property.c
517 .. kernel-doc:: include/drm/drm_property.h
520 .. kernel-doc:: drivers/gpu/drm/drm_property.c
523 Standard Connector Properties
524 -----------------------------
526 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
527 :doc: standard connector properties
529 HDMI Specific Connector Properties
530 ----------------------------------
532 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
533 :doc: HDMI connector properties
535 Plane Composition Properties
536 ----------------------------
538 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
541 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
544 Color Management Properties
545 ---------------------------
547 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
550 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
556 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
559 Explicit Fencing Properties
560 ---------------------------
562 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
563 :doc: explicit fencing properties
565 Existing KMS Properties
566 -----------------------
568 The following table gives description of drm properties exposed by various
569 modules/drivers. Because this table is very unwieldy, do not add any new
570 properties here. Instead document them in a section above.
574 :file: kms-properties.csv
579 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
580 :doc: vblank handling
582 Vertical Blanking and Interrupt Handling Functions Reference
583 ------------------------------------------------------------
585 .. kernel-doc:: include/drm/drm_vblank.h
588 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c