drm/via: set FOLL_PIN via pin_user_pages_fast()
[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 :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.
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 :c:func:`drm_object_attach_property()
185 <drm_object_attach_property>`.
186
187 .. kernel-doc:: include/drm/drm_mode_object.h
188    :internal:
189
190 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
191    :export:
192
193 Atomic Mode Setting
194 ===================
195
196
197 .. kernel-render:: DOT
198    :alt: Mode Objects and Properties
199    :caption: Mode Objects and Properties
200
201    digraph {
202       node [shape=box]
203
204       subgraph cluster_state {
205           style=dashed
206           label="Free-standing state"
207
208           "drm_atomic_state" -> "duplicated drm_plane_state A"
209           "drm_atomic_state" -> "duplicated drm_plane_state B"
210           "drm_atomic_state" -> "duplicated drm_crtc_state"
211           "drm_atomic_state" -> "duplicated drm_connector_state"
212           "drm_atomic_state" -> "duplicated driver private state"
213       }
214
215       subgraph cluster_current {
216           style=dashed
217           label="Current state"
218
219           "drm_device" -> "drm_plane A"
220           "drm_device" -> "drm_plane B"
221           "drm_device" -> "drm_crtc"
222           "drm_device" -> "drm_connector"
223           "drm_device" -> "driver private object"
224
225           "drm_plane A" -> "drm_plane_state A"
226           "drm_plane B" -> "drm_plane_state B"
227           "drm_crtc" -> "drm_crtc_state"
228           "drm_connector" -> "drm_connector_state"
229           "driver private object" -> "driver private state"
230       }
231
232       "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
233       "duplicated drm_plane_state A" -> "drm_device"[style=invis]
234    }
235
236 Atomic provides transactional modeset (including planes) updates, but a
237 bit differently from the usual transactional approach of try-commit and
238 rollback:
239
240 - Firstly, no hardware changes are allowed when the commit would fail. This
241   allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
242   userspace to explore whether certain configurations would work or not.
243
244 - This would still allow setting and rollback of just the software state,
245   simplifying conversion of existing drivers. But auditing drivers for
246   correctness of the atomic_check code becomes really hard with that: Rolling
247   back changes in data structures all over the place is hard to get right.
248
249 - Lastly, for backwards compatibility and to support all use-cases, atomic
250   updates need to be incremental and be able to execute in parallel. Hardware
251   doesn't always allow it, but where possible plane updates on different CRTCs
252   should not interfere, and not get stalled due to output routing changing on
253   different CRTCs.
254
255 Taken all together there's two consequences for the atomic design:
256
257 - The overall state is split up into per-object state structures:
258   :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
259   drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
260   drm_connector_state <drm_connector_state>` for connectors. These are the only
261   objects with userspace-visible and settable state. For internal state drivers
262   can subclass these structures through embeddeding, or add entirely new state
263   structures for their globally shared hardware functions.
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 Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
273 coverage of specific topics.
274
275 Handling Driver Private State
276 -----------------------------
277
278 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
279    :doc: handling driver private state
280
281 Atomic Mode Setting Function Reference
282 --------------------------------------
283
284 .. kernel-doc:: include/drm/drm_atomic.h
285    :internal:
286
287 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
288    :export:
289
290 Atomic Mode Setting IOCTL and UAPI Functions
291 --------------------------------------------
292
293 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
294    :doc: overview
295
296 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
297    :export:
298
299 CRTC Abstraction
300 ================
301
302 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
303    :doc: overview
304
305 CRTC Functions Reference
306 --------------------------------
307
308 .. kernel-doc:: include/drm/drm_crtc.h
309    :internal:
310
311 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
312    :export:
313
314 Frame Buffer Abstraction
315 ========================
316
317 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
318    :doc: overview
319
320 Frame Buffer Functions Reference
321 --------------------------------
322
323 .. kernel-doc:: include/drm/drm_framebuffer.h
324    :internal:
325
326 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
327    :export:
328
329 DRM Format Handling
330 ===================
331
332 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
333    :doc: overview
334
335 Format Functions Reference
336 --------------------------
337
338 .. kernel-doc:: include/drm/drm_fourcc.h
339    :internal:
340
341 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
342    :export:
343
344 Dumb Buffer Objects
345 ===================
346
347 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
348    :doc: overview
349
350 Plane Abstraction
351 =================
352
353 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
354    :doc: overview
355
356 Plane Functions Reference
357 -------------------------
358
359 .. kernel-doc:: include/drm/drm_plane.h
360    :internal:
361
362 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
363    :export:
364
365 Display Modes Function Reference
366 ================================
367
368 .. kernel-doc:: include/drm/drm_modes.h
369    :internal:
370
371 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
372    :export:
373
374 Connector Abstraction
375 =====================
376
377 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
378    :doc: overview
379
380 Connector Functions Reference
381 -----------------------------
382
383 .. kernel-doc:: include/drm/drm_connector.h
384    :internal:
385
386 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
387    :export:
388
389 Writeback Connectors
390 --------------------
391
392 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
393   :doc: overview
394
395 .. kernel-doc:: drivers/gpu/drm/drm_writeback.c
396   :export:
397
398 Encoder Abstraction
399 ===================
400
401 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
402    :doc: overview
403
404 Encoder Functions Reference
405 ---------------------------
406
407 .. kernel-doc:: include/drm/drm_encoder.h
408    :internal:
409
410 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
411    :export:
412
413 KMS Locking
414 ===========
415
416 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
417    :doc: kms locking
418
419 .. kernel-doc:: include/drm/drm_modeset_lock.h
420    :internal:
421
422 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
423    :export:
424
425 KMS Properties
426 ==============
427
428 Property Types and Blob Property Support
429 ----------------------------------------
430
431 .. kernel-doc:: drivers/gpu/drm/drm_property.c
432    :doc: overview
433
434 .. kernel-doc:: include/drm/drm_property.h
435    :internal:
436
437 .. kernel-doc:: drivers/gpu/drm/drm_property.c
438    :export:
439
440 Standard Connector Properties
441 -----------------------------
442
443 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
444    :doc: standard connector properties
445
446 HDMI Specific Connector Properties
447 ----------------------------------
448
449 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
450    :doc: HDMI connector properties
451
452 Plane Composition Properties
453 ----------------------------
454
455 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
456    :doc: overview
457
458 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
459    :export:
460
461 FB_DAMAGE_CLIPS
462 ~~~~~~~~~~~~~~~
463
464 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
465    :doc: overview
466
467 .. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
468    :export:
469
470 .. kernel-doc:: include/drm/drm_damage_helper.h
471    :internal:
472
473 Color Management Properties
474 ---------------------------
475
476 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
477    :doc: overview
478
479 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
480    :export:
481
482 Tile Group Property
483 -------------------
484
485 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
486    :doc: Tile group
487
488 Explicit Fencing Properties
489 ---------------------------
490
491 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
492    :doc: explicit fencing properties
493
494
495 Variable Refresh Properties
496 ---------------------------
497
498 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
499    :doc: Variable refresh properties
500
501 Existing KMS Properties
502 -----------------------
503
504 The following table gives description of drm properties exposed by various
505 modules/drivers. Because this table is very unwieldy, do not add any new
506 properties here. Instead document them in a section above.
507
508 .. csv-table::
509    :header-rows: 1
510    :file: kms-properties.csv
511
512 Vertical Blanking
513 =================
514
515 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
516    :doc: vblank handling
517
518 Vertical Blanking and Interrupt Handling Functions Reference
519 ------------------------------------------------------------
520
521 .. kernel-doc:: include/drm/drm_vblank.h
522    :internal:
523
524 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
525    :export: