xref: /openbmc/linux/Documentation/gpu/drm-kms.rst (revision 5d0e4d78)
1=========================
2Kernel Mode Setting (KMS)
3=========================
4
5Drivers must initialize the mode setting core by calling
6:c:func:`drm_mode_config_init()` on the DRM device. The function
7initializes the :c:type:`struct drm_device <drm_device>`
8mode_config field and never fails. Once done, mode configuration must
9be setup by initializing the following fields.
10
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.
14
15-  struct drm_mode_config_funcs \*funcs;
16   Mode setting functions.
17
18Overview
19========
20
21.. kernel-render:: DOT
22   :alt: KMS Display Pipeline
23   :caption: KMS Display Pipeline Overview
24
25   digraph "KMS" {
26      node [shape=box]
27
28      subgraph cluster_static {
29          style=dashed
30          label="Static Objects"
31
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      }
38
39      subgraph cluster_user_created {
40          style=dashed
41          label="Userspace-Created"
42
43          node [shape=oval]
44          "drm_framebuffer 1" -> "drm_plane A"
45          "drm_framebuffer 2" -> "drm_plane B"
46      }
47
48      subgraph cluster_connector {
49          style=dashed
50          label="Hotpluggable"
51
52          "drm_encoder A" -> "drm_connector A"
53          "drm_encoder B" -> "drm_connector B"
54      }
55   }
56
57The basic object structure KMS presents to userspace is fairly simple.
58Framebuffers (represented by :c:type:`struct drm_framebuffer <drm_framebuffer>`,
59see `Frame Buffer Abstraction`_) feed into planes. One or more (or even no)
60planes feed their pixel data into a CRTC (represented by :c:type:`struct
61drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise
62blending step is explained in more detail in `Plane Composition Properties`_ and
63related chapters.
64
65For the output routing the first step is encoders (represented by
66:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
67are really just internal artifacts of the helper libraries used to implement KMS
68drivers. Besides that they make it unecessarily more complicated for userspace
69to figure out which connections between a CRTC and a connector are possible, and
70what kind of cloning is supported, they serve no purpose in the userspace API.
71Unfortunately encoders have been exposed to userspace, hence can't remove them
72at this point.  Futhermore the exposed restrictions are often wrongly set by
73drivers, and in many cases not powerful enough to express the real restrictions.
74A CRTC can be connected to multiple encoders, and for an active CRTC there must
75be at least one encoder.
76
77The final, and real, endpoint in the display chain is the connector (represented
78by :c:type:`struct drm_connector <drm_connector>`, see `Connector
79Abstraction`_). Connectors can have different possible encoders, but the kernel
80driver selects which encoder to use for each connector. The use case is DVI,
81which could switch between an analog and a digital encoder. Encoders can also
82drive multiple different connectors. There is exactly one active connector for
83every active encoder.
84
85Internally the output pipeline is a bit more complex and matches today's
86hardware more closely:
87
88.. kernel-render:: DOT
89   :alt: KMS Output Pipeline
90   :caption: KMS Output Pipeline
91
92   digraph "Output Pipeline" {
93      node [shape=box]
94
95      subgraph {
96          "drm_crtc" [bgcolor=grey style=filled]
97      }
98
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          }
108
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      }
116
117      "drm_crtc" -> "drm_encoder A"
118      "drm_crtc" -> "drm_encoder B"
119      "drm_crtc" -> "drm_encoder C"
120
121
122      subgraph cluster_output {
123          style=dashed
124          label="Outputs"
125
126          "drm_encoder A" -> "drm_connector A";
127          "drm_bridge B" -> "drm_connector B";
128          "drm_bridge C2" -> "drm_connector C";
129
130          "drm_panel"
131      }
132   }
133
134Internally two additional helper objects come into play. First, to be able to
135share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
136more :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
138changed, which means the cross-bar (if there is any) needs to be mapped between
139the CRTC and any encoders. Often for drivers with bridges there's no code left
140at the encoder level. Atomic drivers can leave out all the encoder callbacks to
141essentially only leave a dummy routing object behind, which is needed for
142backwards compatibility since encoders are exposed to userspace.
143
144The 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
146point, but are generally linked to the driver private structure that embeds
147:c:type:`struct drm_connector <drm_connector>`.
148
149Note that currently the bridge chaining and interactions with connectors and
150panels are still in-flux and not really fully sorted out yet.
151
152KMS Core Structures and Functions
153=================================
154
155.. kernel-doc:: include/drm/drm_mode_config.h
156   :internal:
157
158.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
159   :export:
160
161Modeset Base Object Abstraction
162===============================
163
164.. kernel-render:: DOT
165   :alt: Mode Objects and Properties
166   :caption: Mode Objects and Properties
167
168   digraph {
169      node [shape=box]
170
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   }
175
176The 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,
178which are especially important for the atomic IOCTL (see `Atomic Mode
179Setting`_). The somewhat surprising part here is that properties are not
180directly instantiated on each object, but free-standing mode objects themselves,
181represented by :c:type:`struct drm_property <drm_property>`, which only specify
182the type and value range of a property. Any given property can be attached
183multiple times to different objects using :c:func:`drm_object_attach_property()
184<drm_object_attach_property>`.
185
186.. kernel-doc:: include/drm/drm_mode_object.h
187   :internal:
188
189.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
190   :export:
191
192Atomic Mode Setting
193===================
194
195
196.. kernel-render:: DOT
197   :alt: Mode Objects and Properties
198   :caption: Mode Objects and Properties
199
200   digraph {
201      node [shape=box]
202
203      subgraph cluster_state {
204          style=dashed
205          label="Free-standing state"
206
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      }
213
214      subgraph cluster_current {
215          style=dashed
216          label="Current state"
217
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"
223
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      }
230
231      "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
232      "duplicated drm_plane_state A" -> "drm_device"[style=invis]
233   }
234
235Atomic provides transactional modeset (including planes) updates, but a
236bit differently from the usual transactional approach of try-commit and
237rollback:
238
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.
242
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.
247
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.
253
254Taken all together there's two consequences for the atomic design:
255
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.
263
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.
270
271Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
272coverage of specific topics.
273
274Atomic Mode Setting Function Reference
275--------------------------------------
276
277.. kernel-doc:: include/drm/drm_atomic.h
278   :internal:
279
280.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
281   :export:
282
283CRTC Abstraction
284================
285
286.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
287   :doc: overview
288
289CRTC Functions Reference
290--------------------------------
291
292.. kernel-doc:: include/drm/drm_crtc.h
293   :internal:
294
295.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
296   :export:
297
298Frame Buffer Abstraction
299========================
300
301.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
302   :doc: overview
303
304Frame Buffer Functions Reference
305--------------------------------
306
307.. kernel-doc:: include/drm/drm_framebuffer.h
308   :internal:
309
310.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
311   :export:
312
313DRM Format Handling
314===================
315
316.. kernel-doc:: include/drm/drm_fourcc.h
317   :internal:
318
319.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
320   :export:
321
322Dumb Buffer Objects
323===================
324
325.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
326   :doc: overview
327
328Plane Abstraction
329=================
330
331.. kernel-doc:: drivers/gpu/drm/drm_plane.c
332   :doc: overview
333
334Plane Functions Reference
335-------------------------
336
337.. kernel-doc:: include/drm/drm_plane.h
338   :internal:
339
340.. kernel-doc:: drivers/gpu/drm/drm_plane.c
341   :export:
342
343Display Modes Function Reference
344================================
345
346.. kernel-doc:: include/drm/drm_modes.h
347   :internal:
348
349.. kernel-doc:: drivers/gpu/drm/drm_modes.c
350   :export:
351
352Connector Abstraction
353=====================
354
355.. kernel-doc:: drivers/gpu/drm/drm_connector.c
356   :doc: overview
357
358Connector Functions Reference
359-----------------------------
360
361.. kernel-doc:: include/drm/drm_connector.h
362   :internal:
363
364.. kernel-doc:: drivers/gpu/drm/drm_connector.c
365   :export:
366
367Encoder Abstraction
368===================
369
370.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
371   :doc: overview
372
373Encoder Functions Reference
374---------------------------
375
376.. kernel-doc:: include/drm/drm_encoder.h
377   :internal:
378
379.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
380   :export:
381
382KMS Initialization and Cleanup
383==============================
384
385A KMS device is abstracted and exposed as a set of planes, CRTCs,
386encoders and connectors. KMS drivers must thus create and initialize all
387those objects at load time after initializing mode setting.
388
389CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
390--------------------------------------------
391
392A CRTC is an abstraction representing a part of the chip that contains a
393pointer to a scanout buffer. Therefore, the number of CRTCs available
394determines how many independent scanout buffers can be active at any
395given time. The CRTC structure contains several fields to support this:
396a pointer to some video memory (abstracted as a frame buffer object), a
397display mode, and an (x, y) offset into the video memory to support
398panning or configurations where one piece of video memory spans multiple
399CRTCs.
400
401CRTC Initialization
402~~~~~~~~~~~~~~~~~~~
403
404A KMS device must create and register at least one struct
405:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
406allocated and zeroed by the driver, possibly as part of a larger
407structure, and registered with a call to :c:func:`drm_crtc_init()`
408with a pointer to CRTC functions.
409
410
411Cleanup
412-------
413
414The DRM core manages its objects' lifetime. When an object is not needed
415anymore the core calls its destroy function, which must clean up and
416free 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
423have 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()`.
426
427Connectors state change detection must be cleanup up with a call to
428:c:func:`drm_kms_helper_poll_fini()`.
429
430Output discovery and initialization example
431-------------------------------------------
432
433.. code-block:: c
434
435    void intel_crt_init(struct drm_device *dev)
436    {
437        struct drm_connector *connector;
438        struct intel_output *intel_output;
439
440        intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
441        if (!intel_output)
442            return;
443
444        connector = &intel_output->base;
445        drm_connector_init(dev, &intel_output->base,
446                   &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
447
448        drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
449                 DRM_MODE_ENCODER_DAC);
450
451        drm_mode_connector_attach_encoder(&intel_output->base,
452                          &intel_output->enc);
453
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        }
461
462        intel_output->type = INTEL_OUTPUT_ANALOG;
463        connector->interlace_allowed = 0;
464        connector->doublescan_allowed = 0;
465
466        drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
467        drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
468
469        drm_connector_register(connector);
470    }
471
472In the example above (taken from the i915 driver), a CRTC, connector and
473encoder combination is created. A device-specific i2c bus is also
474created for fetching EDID data and performing monitor detection. Once
475the process is complete, the new connector is registered with sysfs to
476make its properties available to applications.
477
478KMS Locking
479===========
480
481.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
482   :doc: kms locking
483
484.. kernel-doc:: include/drm/drm_modeset_lock.h
485   :internal:
486
487.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
488   :export:
489
490KMS Properties
491==============
492
493Property Types and Blob Property Support
494----------------------------------------
495
496.. kernel-doc:: drivers/gpu/drm/drm_property.c
497   :doc: overview
498
499.. kernel-doc:: include/drm/drm_property.h
500   :internal:
501
502.. kernel-doc:: drivers/gpu/drm/drm_property.c
503   :export:
504
505Standard Connector Properties
506-----------------------------
507
508.. kernel-doc:: drivers/gpu/drm/drm_connector.c
509   :doc: standard connector properties
510
511Plane Composition Properties
512----------------------------
513
514.. kernel-doc:: drivers/gpu/drm/drm_blend.c
515   :doc: overview
516
517.. kernel-doc:: drivers/gpu/drm/drm_blend.c
518   :export:
519
520Color Management Properties
521---------------------------
522
523.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
524   :doc: overview
525
526.. kernel-doc:: include/drm/drm_color_mgmt.h
527   :internal:
528
529.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
530   :export:
531
532Tile Group Property
533-------------------
534
535.. kernel-doc:: drivers/gpu/drm/drm_connector.c
536   :doc: Tile group
537
538Explicit Fencing Properties
539---------------------------
540
541.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
542   :doc: explicit fencing properties
543
544Existing KMS Properties
545-----------------------
546
547The following table gives description of drm properties exposed by
548various modules/drivers.
549
550.. csv-table::
551   :header-rows: 1
552   :file: kms-properties.csv
553
554Vertical Blanking
555=================
556
557Vertical blanking plays a major role in graphics rendering. To achieve
558tear-free display, users must synchronize page flips and/or rendering to
559vertical blanking. The DRM API offers ioctls to perform page flips
560synchronized to vertical blanking and wait for vertical blanking.
561
562The DRM core handles most of the vertical blanking management logic,
563which involves filtering out spurious interrupts, keeping race-free
564blanking counters, coping with counter wrap-around and resets and
565keeping use counts. It relies on the driver to generate vertical
566blanking interrupts and optionally provide a hardware vertical blanking
567counter. Drivers must implement the following operations.
568
569-  int (\*enable_vblank) (struct drm_device \*dev, int crtc); void
570   (\*disable_vblank) (struct drm_device \*dev, int crtc);
571   Enable or disable vertical blanking interrupts for the given CRTC.
572
573-  u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc);
574   Retrieve the value of the vertical blanking counter for the given
575   CRTC. If the hardware maintains a vertical blanking counter its value
576   should be returned. Otherwise drivers can use the
577   :c:func:`drm_vblank_count()` helper function to handle this
578   operation.
579
580Drivers must initialize the vertical blanking handling core with a call
581to :c:func:`drm_vblank_init()` in their load operation.
582
583Vertical blanking interrupts can be enabled by the DRM core or by
584drivers themselves (for instance to handle page flipping operations).
585The DRM core maintains a vertical blanking use count to ensure that the
586interrupts are not disabled while a user still needs them. To increment
587the use count, drivers call :c:func:`drm_vblank_get()`. Upon
588return vertical blanking interrupts are guaranteed to be enabled.
589
590To decrement the use count drivers call
591:c:func:`drm_vblank_put()`. Only when the use count drops to zero
592will the DRM core disable the vertical blanking interrupts after a delay
593by scheduling a timer. The delay is accessible through the
594vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global
595variable and expressed in milliseconds. Its default value is 5000 ms.
596Zero means never disable, and a negative value means disable
597immediately. Drivers may override the behaviour by setting the
598:c:type:`struct drm_device <drm_device>`
599vblank_disable_immediate flag, which when set causes vblank interrupts
600to be disabled immediately regardless of the drm_vblank_offdelay
601value. The flag should only be set if there's a properly working
602hardware vblank counter present.
603
604When a vertical blanking interrupt occurs drivers only need to call the
605:c:func:`drm_handle_vblank()` function to account for the
606interrupt.
607
608Resources allocated by :c:func:`drm_vblank_init()` must be freed
609with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
610operation handler.
611
612Vertical Blanking and Interrupt Handling Functions Reference
613------------------------------------------------------------
614
615.. kernel-doc:: include/drm/drm_vblank.h
616   :internal:
617
618.. kernel-doc:: drivers/gpu/drm/drm_vblank.c
619   :export:
620