1 =========================
2 Kernel Mode Setting (KMS)
3 =========================
4
5 Drivers must initialize the mode setting core
6 drmm_mode_config_init() on the DRM device. The
7 initializes the :c:type:`struct drm_device <dr
8 mode_config field and never fails. Once done,
9 be setup by initializing the following fields.
10
11 - int min_width, min_height; int max_width, m
12 Minimum and maximum width and height of the
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 use
58 Framebuffers (represented by :c:type:`struct d
59 see `Frame Buffer Abstraction`_) feed into pla
60 :c:type:`struct drm_plane <drm_plane>`, see `P
61 details. One or more (or even no) planes feed
62 (represented by :c:type:`struct drm_crtc <drm_
63 for blending. The precise blending step is exp
64 Composition Properties`_ and related chapters.
65
66 For the output routing the first step is encod
67 :c:type:`struct drm_encoder <drm_encoder>`, se
68 are really just internal artifacts of the help
69 drivers. Besides that they make it unnecessari
70 to figure out which connections between a CRTC
71 what kind of cloning is supported, they serve
72 Unfortunately encoders have been exposed to us
73 at this point. Furthermore the exposed restri
74 drivers, and in many cases not powerful enough
75 A CRTC can be connected to multiple encoders,
76 be at least one encoder.
77
78 The final, and real, endpoint in the display c
79 by :c:type:`struct drm_connector <drm_connecto
80 Abstraction`_). Connectors can have different
81 driver selects which encoder to use for each c
82 which could switch between an analog and a dig
83 drive multiple different connectors. There is
84 every active encoder.
85
86 Internally the output pipeline is a bit more c
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=fille
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 C
114 "drm_bridge C1" -> "drm_bridge C
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
136 share code for encoders (sometimes on the same
137 more :ref:`drm_bridges` (represented by :c:typ
138 <drm_bridge>`) can be linked to an encoder. Th
139 changed, which means the cross-bar (if there i
140 the CRTC and any encoders. Often for drivers w
141 at the encoder level. Atomic drivers can leave
142 essentially only leave a dummy routing object
143 backwards compatibility since encoders are exp
144
145 The second object is for panels, represented b
146 <drm_panel>`, see :ref:`drm_panel_helper`. Pan
147 point, but are generally linked to the driver
148 :c:type:`struct drm_connector <drm_connector>`
149
150 Note that currently the bridge chaining and in
151 panels are still in-flux and not really fully
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_confi
160 :export:
161
162 .. _kms_base_object_abstraction:
163
164 Modeset Base Object Abstraction
165 ===============================
166
167 .. kernel-render:: DOT
168 :alt: Mode Objects and Properties
169 :caption: Mode Objects and Properties
170
171 digraph {
172 node [shape=box]
173
174 "drm_property A" -> "drm_mode_object A"
175 "drm_property A" -> "drm_mode_object B"
176 "drm_property B" -> "drm_mode_object A"
177 }
178
179 The base structure for all KMS objects is :c:t
180 <drm_mode_object>`. One of the base services i
181 which are especially important for the atomic
182 Setting`_). The somewhat surprising part here
183 directly instantiated on each object, but free
184 represented by :c:type:`struct drm_property <d
185 the type and value range of a property. Any gi
186 multiple times to different objects using drm_
187
188 .. kernel-doc:: include/drm/drm_mode_object.h
189 :internal:
190
191 .. kernel-doc:: drivers/gpu/drm/drm_mode_objec
192 :export:
193
194 Atomic Mode Setting
195 ===================
196
197
198 .. kernel-render:: DOT
199 :alt: Mode Objects and Properties
200 :caption: Mode Objects and Properties
201
202 digraph {
203 node [shape=box]
204
205 subgraph cluster_state {
206 style=dashed
207 label="Free-standing state"
208
209 "drm_atomic_state" -> "duplicated dr
210 "drm_atomic_state" -> "duplicated dr
211 "drm_atomic_state" -> "duplicated dr
212 "drm_atomic_state" -> "duplicated dr
213 "drm_atomic_state" -> "duplicated dr
214 }
215
216 subgraph cluster_current {
217 style=dashed
218 label="Current state"
219
220 "drm_device" -> "drm_plane A"
221 "drm_device" -> "drm_plane B"
222 "drm_device" -> "drm_crtc"
223 "drm_device" -> "drm_connector"
224 "drm_device" -> "driver private obje
225
226 "drm_plane A" -> "drm_plane_state A"
227 "drm_plane B" -> "drm_plane_state B"
228 "drm_crtc" -> "drm_crtc_state"
229 "drm_connector" -> "drm_connector_st
230 "driver private object" -> "driver p
231 }
232
233 "drm_atomic_state" -> "drm_device" [labe
234 "duplicated drm_plane_state A" -> "drm_d
235 }
236
237 Atomic provides transactional modeset (includi
238 bit differently from the usual transactional a
239 rollback:
240
241 - Firstly, no hardware changes are allowed whe
242 allows us to implement the DRM_MODE_ATOMIC_T
243 userspace to explore whether certain configu
244
245 - This would still allow setting and rollback
246 simplifying conversion of existing drivers.
247 correctness of the atomic_check code becomes
248 back changes in data structures all over the
249
250 - Lastly, for backwards compatibility and to s
251 updates need to be incremental and be able t
252 doesn't always allow it, but where possible
253 should not interfere, and not get stalled du
254 different CRTCs.
255
256 Taken all together there's two consequences fo
257
258 - The overall state is split up into per-objec
259 :c:type:`struct drm_plane_state <drm_plane_s
260 drm_crtc_state <drm_crtc_state>` for CRTCs a
261 drm_connector_state <drm_connector_state>` f
262 objects with userspace-visible and settable
263 can subclass these structures through embedd
264 structures for their globally shared hardwar
265 drm_private_state<drm_private_state>`.
266
267 - An atomic update is assembled and validated
268 of structures within the :c:type:`drm_atomic
269 container. Driver private state structures a
270 structure; see the next chapter. Only when
271 to the driver and modeset objects. This way
272 to releasing memory and unreferencing object
273
274 Locking of atomic state structures is internal
275 drm_modeset_lock <drm_modeset_lock>`. As a gen
276 exposed to drivers, instead the right locks sh
277 any function that duplicates or peeks into a s
278 drm_atomic_get_crtc_state(). Locking only pro
279 structure, ordering of committing state change
280 :c:type:`struct drm_crtc_commit <drm_crtc_comm
281
282 Read on in this chapter, and also in :ref:`drm
283 coverage of specific topics.
284
285 Handling Driver Private State
286 -----------------------------
287
288 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
289 :doc: handling driver private state
290
291 Atomic Mode Setting Function Reference
292 --------------------------------------
293
294 .. kernel-doc:: include/drm/drm_atomic.h
295 :internal:
296
297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
298 :export:
299
300 Atomic Mode Setting IOCTL and UAPI Functions
301 --------------------------------------------
302
303 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap
304 :doc: overview
305
306 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap
307 :export:
308
309 CRTC Abstraction
310 ================
311
312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
313 :doc: overview
314
315 CRTC Functions Reference
316 --------------------------------
317
318 .. kernel-doc:: include/drm/drm_crtc.h
319 :internal:
320
321 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
322 :export:
323
324 Color Management Functions Reference
325 ------------------------------------
326
327 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt
328 :export:
329
330 .. kernel-doc:: include/drm/drm_color_mgmt.h
331 :internal:
332
333 Frame Buffer Abstraction
334 ========================
335
336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe
337 :doc: overview
338
339 Frame Buffer Functions Reference
340 --------------------------------
341
342 .. kernel-doc:: include/drm/drm_framebuffer.h
343 :internal:
344
345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe
346 :export:
347
348 DRM Format Handling
349 ===================
350
351 .. kernel-doc:: include/uapi/drm/drm_fourcc.h
352 :doc: overview
353
354 Format Functions Reference
355 --------------------------
356
357 .. kernel-doc:: include/drm/drm_fourcc.h
358 :internal:
359
360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
361 :export:
362
363 .. _kms_dumb_buffer_objects:
364
365 Dumb Buffer Objects
366 ===================
367
368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffe
369 :doc: overview
370
371 Plane Abstraction
372 =================
373
374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
375 :doc: overview
376
377 Plane Functions Reference
378 -------------------------
379
380 .. kernel-doc:: include/drm/drm_plane.h
381 :internal:
382
383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
384 :export:
385
386 Plane Composition Functions Reference
387 -------------------------------------
388
389 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
390 :export:
391
392 Plane Damage Tracking Functions Reference
393 -----------------------------------------
394
395 .. kernel-doc:: drivers/gpu/drm/drm_damage_hel
396 :export:
397
398 .. kernel-doc:: include/drm/drm_damage_helper.
399 :internal:
400
401 Plane Panic Feature
402 -------------------
403
404 .. kernel-doc:: drivers/gpu/drm/drm_panic.c
405 :doc: overview
406
407 Plane Panic Functions Reference
408 -------------------------------
409
410 .. kernel-doc:: include/drm/drm_panic.h
411 :internal:
412
413 .. kernel-doc:: drivers/gpu/drm/drm_panic.c
414 :export:
415
416 Display Modes Function Reference
417 ================================
418
419 .. kernel-doc:: include/drm/drm_modes.h
420 :internal:
421
422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
423 :export:
424
425 Connector Abstraction
426 =====================
427
428 .. kernel-doc:: drivers/gpu/drm/drm_connector.
429 :doc: overview
430
431 Connector Functions Reference
432 -----------------------------
433
434 .. kernel-doc:: include/drm/drm_connector.h
435 :internal:
436
437 .. kernel-doc:: drivers/gpu/drm/drm_connector.
438 :export:
439
440 Writeback Connectors
441 --------------------
442
443 .. kernel-doc:: drivers/gpu/drm/drm_writeback.
444 :doc: overview
445
446 .. kernel-doc:: include/drm/drm_writeback.h
447 :internal:
448
449 .. kernel-doc:: drivers/gpu/drm/drm_writeback.
450 :export:
451
452 Encoder Abstraction
453 ===================
454
455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
456 :doc: overview
457
458 Encoder Functions Reference
459 ---------------------------
460
461 .. kernel-doc:: include/drm/drm_encoder.h
462 :internal:
463
464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
465 :export:
466
467 KMS Locking
468 ===========
469
470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo
471 :doc: kms locking
472
473 .. kernel-doc:: include/drm/drm_modeset_lock.h
474 :internal:
475
476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo
477 :export:
478
479 KMS Properties
480 ==============
481
482 This section of the documentation is primarily
483 For the driver APIs, see the other sections.
484
485 Requirements
486 ------------
487
488 KMS drivers might need to add extra properties
489 new property introduced in a driver needs to m
490 addition to the one mentioned above:
491
492 * It must be standardized, documenting:
493
494 * The full, exact, name string;
495 * If the property is an enum, all the valid
496 * What values are accepted, and what these v
497 * What the property does and how it can be u
498 * How the property might interact with other
499
500 * It must provide a generic helper in the core
501 property on the object it attaches to.
502
503 * Its content must be decoded by the core and
504 associated state structure. That includes an
505 to precompute, like struct drm_clip_rect for
506
507 * Its initial state must match the behavior pr
508 introduction. This might be a fixed value ma
509 does, or it may be inherited from the state
510 system in during boot.
511
512 * An IGT test must be submitted where reasonab
513
514 For historical reasons, non-standard, driver-s
515 driver wants to add support for one of those p
516 new properties apply where possible. Additiona
517 match the de facto semantics of the existing p
518 Developers of the driver that first added the
519 tasks and must ACK the documented behavior if
520
521 Property Types and Blob Property Support
522 ----------------------------------------
523
524 .. kernel-doc:: drivers/gpu/drm/drm_property.c
525 :doc: overview
526
527 .. kernel-doc:: include/drm/drm_property.h
528 :internal:
529
530 .. kernel-doc:: drivers/gpu/drm/drm_property.c
531 :export:
532
533 .. _standard_connector_properties:
534
535 Standard Connector Properties
536 -----------------------------
537
538 .. kernel-doc:: drivers/gpu/drm/drm_connector.
539 :doc: standard connector properties
540
541 HDMI Specific Connector Properties
542 ----------------------------------
543
544 .. kernel-doc:: drivers/gpu/drm/drm_connector.
545 :doc: HDMI connector properties
546
547 Analog TV Specific Connector Properties
548 ---------------------------------------
549
550 .. kernel-doc:: drivers/gpu/drm/drm_connector.
551 :doc: Analog TV Connector Properties
552
553 Standard CRTC Properties
554 ------------------------
555
556 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c
557 :doc: standard CRTC properties
558
559 Standard Plane Properties
560 -------------------------
561
562 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
563 :doc: standard plane properties
564
565 .. _plane_composition_properties:
566
567 Plane Composition Properties
568 ----------------------------
569
570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
571 :doc: overview
572
573 .. _damage_tracking_properties:
574
575 Damage Tracking Properties
576 --------------------------
577
578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
579 :doc: damage tracking
580
581 Color Management Properties
582 ---------------------------
583
584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt
585 :doc: overview
586
587 Tile Group Property
588 -------------------
589
590 .. kernel-doc:: drivers/gpu/drm/drm_connector.
591 :doc: Tile group
592
593 Explicit Fencing Properties
594 ---------------------------
595
596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap
597 :doc: explicit fencing properties
598
599
600 Variable Refresh Properties
601 ---------------------------
602
603 .. kernel-doc:: drivers/gpu/drm/drm_connector.
604 :doc: Variable refresh properties
605
606 Cursor Hotspot Properties
607 ---------------------------
608
609 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
610 :doc: hotspot properties
611
612 Existing KMS Properties
613 -----------------------
614
615 The following table gives description of drm p
616 modules/drivers. Because this table is very un
617 properties here. Instead document them in a se
618
619 .. csv-table::
620 :header-rows: 1
621 :file: kms-properties.csv
622
623 Vertical Blanking
624 =================
625
626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
627 :doc: vblank handling
628
629 Vertical Blanking and Interrupt Handling Funct
630 ----------------------------------------------
631
632 .. kernel-doc:: include/drm/drm_vblank.h
633 :internal:
634
635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c
636 :export:
637
638 Vertical Blank Work
639 ===================
640
641 .. kernel-doc:: drivers/gpu/drm/drm_vblank_wor
642 :doc: vblank works
643
644 Vertical Blank Work Functions Reference
645 ---------------------------------------
646
647 .. kernel-doc:: include/drm/drm_vblank_work.h
648 :internal:
649
650 .. kernel-doc:: drivers/gpu/drm/drm_vblank_wor
651 :export:
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.