Linux 4.15.6
[linux/fpc-iii.git] / Documentation / gpu / drm-kms.rst
blob307284125d7aa964522f85ea6fb34247e67c9de2
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
13    units.
15 -  struct drm_mode_config_funcs \*funcs;
16    Mode setting functions.
18 Overview
19 ========
21 .. kernel-render:: DOT
22    :alt: KMS Display Pipeline
23    :caption: KMS Display Pipeline Overview
25    digraph "KMS" {
26       node [shape=box]
28       subgraph cluster_static {
29           style=dashed
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"
37       }
39       subgraph cluster_user_created {
40           style=dashed
41           label="Userspace-Created"
43           node [shape=oval]
44           "drm_framebuffer 1" -> "drm_plane A"
45           "drm_framebuffer 2" -> "drm_plane B"
46       }
48       subgraph cluster_connector {
49           style=dashed
50           label="Hotpluggable"
52           "drm_encoder A" -> "drm_connector A"
53           "drm_encoder B" -> "drm_connector B"
54       }
55    }
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
63 related chapters.
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
83 every active encoder.
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" {
93       node [shape=box]
95       subgraph {
96           "drm_crtc" [bgcolor=grey style=filled]
97       }
99       subgraph cluster_internal {
100           style=dashed
101           label="Internal Pipeline"
102           {
103               node [bgcolor=grey style=filled]
104               "drm_encoder A";
105               "drm_encoder B";
106               "drm_encoder C";
107           }
109           {
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";
114           }
115       }
117       "drm_crtc" -> "drm_encoder A"
118       "drm_crtc" -> "drm_encoder B"
119       "drm_crtc" -> "drm_encoder C"
122       subgraph cluster_output {
123           style=dashed
124           label="Outputs"
126           "drm_encoder A" -> "drm_connector A";
127           "drm_bridge B" -> "drm_connector B";
128           "drm_bridge C2" -> "drm_connector C";
130           "drm_panel"
131       }
132    }
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
156    :internal:
158 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
159    :export:
161 Modeset Base Object Abstraction
162 ===============================
164 .. kernel-render:: DOT
165    :alt: Mode Objects and Properties
166    :caption: Mode Objects and Properties
168    digraph {
169       node [shape=box]
171       "drm_property A" -> "drm_mode_object A"
172       "drm_property A" -> "drm_mode_object B"
173       "drm_property B" -> "drm_mode_object A"
174    }
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
187    :internal:
189 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
190    :export:
192 Atomic Mode Setting
193 ===================
196 .. kernel-render:: DOT
197    :alt: Mode Objects and Properties
198    :caption: Mode Objects and Properties
200    digraph {
201       node [shape=box]
203       subgraph cluster_state {
204           style=dashed
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"
212       }
214       subgraph cluster_current {
215           style=dashed
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"
229       }
231       "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
232       "duplicated drm_plane_state A" -> "drm_device"[style=invis]
233    }
235 Atomic provides transactional modeset (including planes) updates, but a
236 bit differently from the usual transactional approach of try-commit and
237 rollback:
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
252   different CRTCs.
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. Again drivers can subclass that container for their own state
267   structure tracking needs. Only when a state is committed is it applied to the
268   driver and modeset objects. This way rolling back an update boils down to
269   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 Atomic Mode Setting Function Reference
275 --------------------------------------
277 .. kernel-doc:: include/drm/drm_atomic.h
278    :internal:
280 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
281    :export:
283 CRTC Abstraction
284 ================
286 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
287    :doc: overview
289 CRTC Functions Reference
290 --------------------------------
292 .. kernel-doc:: include/drm/drm_crtc.h
293    :internal:
295 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
296    :export:
298 Frame Buffer Abstraction
299 ========================
301 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
302    :doc: overview
304 Frame Buffer Functions Reference
305 --------------------------------
307 .. kernel-doc:: include/drm/drm_framebuffer.h
308    :internal:
310 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
311    :export:
313 DRM Format Handling
314 ===================
316 .. kernel-doc:: include/drm/drm_fourcc.h
317    :internal:
319 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
320    :export:
322 Dumb Buffer Objects
323 ===================
325 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
326    :doc: overview
328 Plane Abstraction
329 =================
331 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
332    :doc: overview
334 Plane Functions Reference
335 -------------------------
337 .. kernel-doc:: include/drm/drm_plane.h
338    :internal:
340 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
341    :export:
343 Display Modes Function Reference
344 ================================
346 .. kernel-doc:: include/drm/drm_modes.h
347    :internal:
349 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
350    :export:
352 Connector Abstraction
353 =====================
355 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
356    :doc: overview
358 Connector Functions Reference
359 -----------------------------
361 .. kernel-doc:: include/drm/drm_connector.h
362    :internal:
364 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
365    :export:
367 Encoder Abstraction
368 ===================
370 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
371    :doc: overview
373 Encoder Functions Reference
374 ---------------------------
376 .. kernel-doc:: include/drm/drm_encoder.h
377    :internal:
379 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
380    :export:
382 KMS Initialization and Cleanup
383 ==============================
385 A KMS device is abstracted and exposed as a set of planes, CRTCs,
386 encoders and connectors. KMS drivers must thus create and initialize all
387 those objects at load time after initializing mode setting.
389 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
390 --------------------------------------------
392 A CRTC is an abstraction representing a part of the chip that contains a
393 pointer to a scanout buffer. Therefore, the number of CRTCs available
394 determines how many independent scanout buffers can be active at any
395 given time. The CRTC structure contains several fields to support this:
396 a pointer to some video memory (abstracted as a frame buffer object), a
397 display mode, and an (x, y) offset into the video memory to support
398 panning or configurations where one piece of video memory spans multiple
399 CRTCs.
401 CRTC Initialization
402 ~~~~~~~~~~~~~~~~~~~
404 A KMS device must create and register at least one struct
405 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
406 allocated and zeroed by the driver, possibly as part of a larger
407 structure, and registered with a call to :c:func:`drm_crtc_init()`
408 with a pointer to CRTC functions.
411 Cleanup
412 -------
414 The DRM core manages its objects' lifetime. When an object is not needed
415 anymore the core calls its destroy function, which must clean up and
416 free every resource allocated for the object. Every
417 :c:func:`drm_\*_init()` call must be matched with a corresponding
418 :c:func:`drm_\*_cleanup()` call to cleanup CRTCs
419 (:c:func:`drm_crtc_cleanup()`), planes
420 (:c:func:`drm_plane_cleanup()`), encoders
421 (:c:func:`drm_encoder_cleanup()`) and connectors
422 (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
423 have been added to sysfs must be removed by a call to
424 :c:func:`drm_connector_unregister()` before calling
425 :c:func:`drm_connector_cleanup()`.
427 Connectors state change detection must be cleanup up with a call to
428 :c:func:`drm_kms_helper_poll_fini()`.
430 Output discovery and initialization example
431 -------------------------------------------
433 .. code-block:: c
435     void intel_crt_init(struct drm_device *dev)
436     {
437         struct drm_connector *connector;
438         struct intel_output *intel_output;
440         intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
441         if (!intel_output)
442             return;
444         connector = &intel_output->base;
445         drm_connector_init(dev, &intel_output->base,
446                    &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
448         drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
449                  DRM_MODE_ENCODER_DAC);
451         drm_mode_connector_attach_encoder(&intel_output->base,
452                           &intel_output->enc);
454         /* Set up the DDC bus. */
455         intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
456         if (!intel_output->ddc_bus) {
457             dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
458                    "failed.\n");
459             return;
460         }
462         intel_output->type = INTEL_OUTPUT_ANALOG;
463         connector->interlace_allowed = 0;
464         connector->doublescan_allowed = 0;
466         drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
467         drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
469         drm_connector_register(connector);
470     }
472 In the example above (taken from the i915 driver), a CRTC, connector and
473 encoder combination is created. A device-specific i2c bus is also
474 created for fetching EDID data and performing monitor detection. Once
475 the process is complete, the new connector is registered with sysfs to
476 make its properties available to applications.
478 KMS Locking
479 ===========
481 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
482    :doc: kms locking
484 .. kernel-doc:: include/drm/drm_modeset_lock.h
485    :internal:
487 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
488    :export:
490 KMS Properties
491 ==============
493 Property Types and Blob Property Support
494 ----------------------------------------
496 .. kernel-doc:: drivers/gpu/drm/drm_property.c
497    :doc: overview
499 .. kernel-doc:: include/drm/drm_property.h
500    :internal:
502 .. kernel-doc:: drivers/gpu/drm/drm_property.c
503    :export:
505 Standard Connector Properties
506 -----------------------------
508 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
509    :doc: standard connector properties
511 Plane Composition Properties
512 ----------------------------
514 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
515    :doc: overview
517 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
518    :export:
520 Color Management Properties
521 ---------------------------
523 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
524    :doc: overview
526 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
527    :export:
529 Tile Group Property
530 -------------------
532 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
533    :doc: Tile group
535 Explicit Fencing Properties
536 ---------------------------
538 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
539    :doc: explicit fencing properties
541 Existing KMS Properties
542 -----------------------
544 The following table gives description of drm properties exposed by
545 various modules/drivers.
547 .. csv-table::
548    :header-rows: 1
549    :file: kms-properties.csv
551 Vertical Blanking
552 =================
554 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
555    :doc: vblank handling
557 Vertical Blanking and Interrupt Handling Functions Reference
558 ------------------------------------------------------------
560 .. kernel-doc:: include/drm/drm_vblank.h
561    :internal:
563 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
564    :export: