device-dax/kmem: use struct_size()
[linux-2.6-microblaze.git] / Documentation / gpu / drm-kms.rst
1 =========================
2 Kernel Mode Setting (KMS)
3 =========================
4
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.
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
18 Overview
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
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.
65
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.
77
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
84 every active encoder.
85
86 Internally the output pipeline is a bit more complex and matches today's
87 hardware more closely:
88
89 .. kernel-render:: DOT
90    :alt: KMS Output Pipeline
91    :caption: KMS Output Pipeline
92
93    digraph "Output Pipeline" {
94       node [shape=box]
95
96       subgraph {
97           "drm_crtc" [bgcolor=grey style=filled]
98       }
99
100       subgraph cluster_internal {
101           style=dashed
102           label="Internal Pipeline"
103           {
104               node [bgcolor=grey style=filled]
105               "drm_encoder A";
106               "drm_encoder B";
107               "drm_encoder C";
108           }
109
110           {
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";
115           }
116       }
117
118       "drm_crtc" -> "drm_encoder A"
119       "drm_crtc" -> "drm_encoder B"
120       "drm_crtc" -> "drm_encoder C"
121
122
123       subgraph cluster_output {
124           style=dashed
125           label="Outputs"
126
127           "drm_encoder A" -> "drm_connector A";
128           "drm_bridge B" -> "drm_connector B";
129           "drm_bridge C2" -> "drm_connector C";
130
131           "drm_panel"
132       }
133    }
134
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.
144
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>`.
149
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.
152
153 KMS Core Structures and Functions
154 =================================
155
156 .. kernel-doc:: include/drm/drm_mode_config.h
157    :internal:
158
159 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
160    :export:
161
162 Modeset Base Object Abstraction
163 ===============================
164
165 .. kernel-render:: DOT
166    :alt: Mode Objects and Properties
167    :caption: Mode Objects and Properties
168
169    digraph {
170       node [shape=box]
171
172       "drm_property A" -> "drm_mode_object A"
173       "drm_property A" -> "drm_mode_object B"
174       "drm_property B" -> "drm_mode_object A"
175    }
176
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().
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
192 Atomic 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
235 Atomic provides transactional modeset (including planes) updates, but a
236 bit differently from the usual transactional approach of try-commit and
237 rollback:
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
254 Taken 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, see :c:type:`struct
263   drm_private_state<drm_private_state>`.
264
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.
271
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>`.
279
280 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
281 coverage of specific topics.
282
283 Handling Driver Private State
284 -----------------------------
285
286 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
287    :doc: handling driver private state
288
289 Atomic Mode Setting Function Reference
290 --------------------------------------
291
292 .. kernel-doc:: include/drm/drm_atomic.h
293    :internal:
294
295 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
296    :export:
297
298 Atomic Mode Setting IOCTL and UAPI Functions
299 --------------------------------------------
300
301 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
302    :doc: overview
303
304 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
305    :export:
306
307 CRTC Abstraction
308 ================
309
310 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
311    :doc: overview
312
313 CRTC Functions Reference
314 --------------------------------
315
316 .. kernel-doc:: include/drm/drm_crtc.h
317    :internal:
318
319 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
320    :export:
321
322 Frame Buffer Abstraction
323 ========================
324
325 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
326    :doc: overview
327
328 Frame Buffer Functions Reference
329 --------------------------------
330
331 .. kernel-doc:: include/drm/drm_framebuffer.h
332    :internal:
333
334 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
335    :export:
336
337 DRM Format Handling
338 ===================
339
340 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
341    :doc: overview
342
343 Format Functions Reference
344 --------------------------
345
346 .. kernel-doc:: include/drm/drm_fourcc.h
347    :internal:
348
349 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
350    :export:
351
352 Dumb Buffer Objects
353 ===================
354
355 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
356    :doc: overview
357
358 Plane Abstraction
359 =================
360
361 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
362    :doc: overview
363
364 Plane Functions Reference
365 -------------------------
366
367 .. kernel-doc:: include/drm/drm_plane.h
368    :internal:
369
370 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
371    :export:
372
373 Display Modes Function Reference
374 ================================
375
376 .. kernel-doc:: include/drm/drm_modes.h
377    :internal:
378
379 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
380    :export:
381
382 Connector Abstraction
383 =====================
384
385 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
386    :doc: overview
387
388 Connector Functions Reference
389 -----------------------------
390
391 .. kernel-doc:: include/drm/drm_connector.h
392    :internal:
393
394 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
395    :export:
396
397 Writeback Connectors
398 --------------------
399
400 .. kernel-doc:: include/drm/drm_writeback.h
401   :internal:
402
403 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
404   :doc: overview
405
406 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
407   :export:
408
409 Encoder Abstraction
410 ===================
411
412 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
413    :doc: overview
414
415 Encoder Functions Reference
416 ---------------------------
417
418 .. kernel-doc:: include/drm/drm_encoder.h
419    :internal:
420
421 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
422    :export:
423
424 KMS Locking
425 ===========
426
427 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
428    :doc: kms locking
429
430 .. kernel-doc:: include/drm/drm_modeset_lock.h
431    :internal:
432
433 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
434    :export:
435
436 KMS Properties
437 ==============
438
439 Property Types and Blob Property Support
440 ----------------------------------------
441
442 .. kernel-doc:: drivers/gpu/drm/drm_property.c
443    :doc: overview
444
445 .. kernel-doc:: include/drm/drm_property.h
446    :internal:
447
448 .. kernel-doc:: drivers/gpu/drm/drm_property.c
449    :export:
450
451 Standard Connector Properties
452 -----------------------------
453
454 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
455    :doc: standard connector properties
456
457 HDMI Specific Connector Properties
458 ----------------------------------
459
460 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
461    :doc: HDMI connector properties
462
463 Standard CRTC Properties
464 ------------------------
465
466 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
467    :doc: standard CRTC properties
468
469 Plane Composition Properties
470 ----------------------------
471
472 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
473    :doc: overview
474
475 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
476    :export:
477
478 FB_DAMAGE_CLIPS
479 ~~~~~~~~~~~~~~~
480
481 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
482    :doc: overview
483
484 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
485    :export:
486
487 .. kernel-doc:: include/drm/drm_damage_helper.h
488    :internal:
489
490 Color Management Properties
491 ---------------------------
492
493 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
494    :doc: overview
495
496 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
497    :export:
498
499 .. kernel-doc:: include/drm/drm_color_mgmt.h
500    :internal:
501
502 Tile Group Property
503 -------------------
504
505 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
506    :doc: Tile group
507
508 Explicit Fencing Properties
509 ---------------------------
510
511 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
512    :doc: explicit fencing properties
513
514
515 Variable Refresh Properties
516 ---------------------------
517
518 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
519    :doc: Variable refresh properties
520
521 Existing KMS Properties
522 -----------------------
523
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.
527
528 .. csv-table::
529    :header-rows: 1
530    :file: kms-properties.csv
531
532 Vertical Blanking
533 =================
534
535 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
536    :doc: vblank handling
537
538 Vertical Blanking and Interrupt Handling Functions Reference
539 ------------------------------------------------------------
540
541 .. kernel-doc:: include/drm/drm_vblank.h
542    :internal:
543
544 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
545    :export:
546
547 Vertical Blank Work
548 ===================
549
550 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
551    :doc: vblank works
552
553 Vertical Blank Work Functions Reference
554 ---------------------------------------
555
556 .. kernel-doc:: include/drm/drm_vblank_work.h
557    :internal:
558
559 .. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
560    :export: