Loading...
1=========================
2Kernel Mode Setting (KMS)
3=========================
4
5Drivers must initialize the mode setting core by calling
6drmm_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. Planes are represented by
60:c:type:`struct drm_plane <drm_plane>`, see `Plane Abstraction`_ for more
61details. 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`_)
63for blending. The precise blending step is explained in more detail in `Plane
64Composition Properties`_ and related chapters.
65
66For the output routing the first step is encoders (represented by
67:c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those
68are really just internal artifacts of the helper libraries used to implement KMS
69drivers. Besides that they make it unnecessarily more complicated for userspace
70to figure out which connections between a CRTC and a connector are possible, and
71what kind of cloning is supported, they serve no purpose in the userspace API.
72Unfortunately encoders have been exposed to userspace, hence can't remove them
73at this point. Furthermore the exposed restrictions are often wrongly set by
74drivers, and in many cases not powerful enough to express the real restrictions.
75A CRTC can be connected to multiple encoders, and for an active CRTC there must
76be at least one encoder.
77
78The final, and real, endpoint in the display chain is the connector (represented
79by :c:type:`struct drm_connector <drm_connector>`, see `Connector
80Abstraction`_). Connectors can have different possible encoders, but the kernel
81driver selects which encoder to use for each connector. The use case is DVI,
82which could switch between an analog and a digital encoder. Encoders can also
83drive multiple different connectors. There is exactly one active connector for
84every active encoder.
85
86Internally the output pipeline is a bit more complex and matches today's
87hardware 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
135Internally two additional helper objects come into play. First, to be able to
136share code for encoders (sometimes on the same SoC, sometimes off-chip) one or
137more :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
139changed, which means the cross-bar (if there is any) needs to be mapped between
140the CRTC and any encoders. Often for drivers with bridges there's no code left
141at the encoder level. Atomic drivers can leave out all the encoder callbacks to
142essentially only leave a dummy routing object behind, which is needed for
143backwards compatibility since encoders are exposed to userspace.
144
145The 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
147point, but are generally linked to the driver private structure that embeds
148:c:type:`struct drm_connector <drm_connector>`.
149
150Note that currently the bridge chaining and interactions with connectors and
151panels are still in-flux and not really fully sorted out yet.
152
153KMS 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.. _kms_base_object_abstraction:
163
164Modeset 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
179The base structure for all KMS objects is :c:type:`struct drm_mode_object
180<drm_mode_object>`. One of the base services it provides is tracking properties,
181which are especially important for the atomic IOCTL (see `Atomic Mode
182Setting`_). The somewhat surprising part here is that properties are not
183directly instantiated on each object, but free-standing mode objects themselves,
184represented by :c:type:`struct drm_property <drm_property>`, which only specify
185the type and value range of a property. Any given property can be attached
186multiple times to different objects using drm_object_attach_property().
187
188.. kernel-doc:: include/drm/drm_mode_object.h
189 :internal:
190
191.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
192 :export:
193
194Atomic 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 drm_plane_state A"
210 "drm_atomic_state" -> "duplicated drm_plane_state B"
211 "drm_atomic_state" -> "duplicated drm_crtc_state"
212 "drm_atomic_state" -> "duplicated drm_connector_state"
213 "drm_atomic_state" -> "duplicated driver private state"
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 object"
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_state"
230 "driver private object" -> "driver private state"
231 }
232
233 "drm_atomic_state" -> "drm_device" [label="atomic_commit"]
234 "duplicated drm_plane_state A" -> "drm_device"[style=invis]
235 }
236
237Atomic provides transactional modeset (including planes) updates, but a
238bit differently from the usual transactional approach of try-commit and
239rollback:
240
241- Firstly, no hardware changes are allowed when the commit would fail. This
242 allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows
243 userspace to explore whether certain configurations would work or not.
244
245- This would still allow setting and rollback of just the software state,
246 simplifying conversion of existing drivers. But auditing drivers for
247 correctness of the atomic_check code becomes really hard with that: Rolling
248 back changes in data structures all over the place is hard to get right.
249
250- Lastly, for backwards compatibility and to support all use-cases, atomic
251 updates need to be incremental and be able to execute in parallel. Hardware
252 doesn't always allow it, but where possible plane updates on different CRTCs
253 should not interfere, and not get stalled due to output routing changing on
254 different CRTCs.
255
256Taken all together there's two consequences for the atomic design:
257
258- The overall state is split up into per-object state structures:
259 :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct
260 drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct
261 drm_connector_state <drm_connector_state>` for connectors. These are the only
262 objects with userspace-visible and settable state. For internal state drivers
263 can subclass these structures through embedding, or add entirely new state
264 structures for their globally shared hardware functions, see :c:type:`struct
265 drm_private_state<drm_private_state>`.
266
267- An atomic update is assembled and validated as an entirely free-standing pile
268 of structures within the :c:type:`drm_atomic_state <drm_atomic_state>`
269 container. Driver private state structures are also tracked in the same
270 structure; see the next chapter. Only when a state is committed is it applied
271 to the driver and modeset objects. This way rolling back an update boils down
272 to releasing memory and unreferencing objects like framebuffers.
273
274Locking of atomic state structures is internally using :c:type:`struct
275drm_modeset_lock <drm_modeset_lock>`. As a general rule the locking shouldn't be
276exposed to drivers, instead the right locks should be automatically acquired by
277any function that duplicates or peeks into a state, like e.g.
278drm_atomic_get_crtc_state(). Locking only protects the software data
279structure, ordering of committing state changes to hardware is sequenced using
280:c:type:`struct drm_crtc_commit <drm_crtc_commit>`.
281
282Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed
283coverage of specific topics.
284
285Handling Driver Private State
286-----------------------------
287
288.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
289 :doc: handling driver private state
290
291Atomic 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
300Atomic Mode Setting IOCTL and UAPI Functions
301--------------------------------------------
302
303.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
304 :doc: overview
305
306.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
307 :export:
308
309CRTC Abstraction
310================
311
312.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
313 :doc: overview
314
315CRTC 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
324Color Management Functions Reference
325------------------------------------
326
327.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
328 :export:
329
330.. kernel-doc:: include/drm/drm_color_mgmt.h
331 :internal:
332
333Frame Buffer Abstraction
334========================
335
336.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
337 :doc: overview
338
339Frame Buffer Functions Reference
340--------------------------------
341
342.. kernel-doc:: include/drm/drm_framebuffer.h
343 :internal:
344
345.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
346 :export:
347
348DRM Format Handling
349===================
350
351.. kernel-doc:: include/uapi/drm/drm_fourcc.h
352 :doc: overview
353
354Format 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
365Dumb Buffer Objects
366===================
367
368.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
369 :doc: overview
370
371Plane Abstraction
372=================
373
374.. kernel-doc:: drivers/gpu/drm/drm_plane.c
375 :doc: overview
376
377Plane 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
386Plane Composition Functions Reference
387-------------------------------------
388
389.. kernel-doc:: drivers/gpu/drm/drm_blend.c
390 :export:
391
392Plane Damage Tracking Functions Reference
393-----------------------------------------
394
395.. kernel-doc:: drivers/gpu/drm/drm_damage_helper.c
396 :export:
397
398.. kernel-doc:: include/drm/drm_damage_helper.h
399 :internal:
400
401Plane Panic Feature
402-------------------
403
404.. kernel-doc:: drivers/gpu/drm/drm_panic.c
405 :doc: overview
406
407Plane 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
416Display 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
425Connector Abstraction
426=====================
427
428.. kernel-doc:: drivers/gpu/drm/drm_connector.c
429 :doc: overview
430
431Connector Functions Reference
432-----------------------------
433
434.. kernel-doc:: include/drm/drm_connector.h
435 :internal:
436
437.. kernel-doc:: drivers/gpu/drm/drm_connector.c
438 :export:
439
440Writeback Connectors
441--------------------
442
443.. kernel-doc:: drivers/gpu/drm/drm_writeback.c
444 :doc: overview
445
446.. kernel-doc:: include/drm/drm_writeback.h
447 :internal:
448
449.. kernel-doc:: drivers/gpu/drm/drm_writeback.c
450 :export:
451
452Encoder Abstraction
453===================
454
455.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
456 :doc: overview
457
458Encoder 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
467KMS Locking
468===========
469
470.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
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_lock.c
477 :export:
478
479KMS Properties
480==============
481
482This section of the documentation is primarily aimed at user-space developers.
483For the driver APIs, see the other sections.
484
485Requirements
486------------
487
488KMS drivers might need to add extra properties to support new features. Each
489new property introduced in a driver needs to meet a few requirements, in
490addition 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 value name strings;
496 * What values are accepted, and what these values mean;
497 * What the property does and how it can be used;
498 * How the property might interact with other, existing properties.
499
500* It must provide a generic helper in the core code to register that
501 property on the object it attaches to.
502
503* Its content must be decoded by the core and provided in the object's
504 associated state structure. That includes anything drivers might want
505 to precompute, like struct drm_clip_rect for planes.
506
507* Its initial state must match the behavior prior to the property
508 introduction. This might be a fixed value matching what the hardware
509 does, or it may be inherited from the state the firmware left the
510 system in during boot.
511
512* An IGT test must be submitted where reasonable.
513
514For historical reasons, non-standard, driver-specific properties exist. If a KMS
515driver wants to add support for one of those properties, the requirements for
516new properties apply where possible. Additionally, the documented behavior must
517match the de facto semantics of the existing property to ensure compatibility.
518Developers of the driver that first added the property should help with those
519tasks and must ACK the documented behavior if possible.
520
521Property 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
535Standard Connector Properties
536-----------------------------
537
538.. kernel-doc:: drivers/gpu/drm/drm_connector.c
539 :doc: standard connector properties
540
541HDMI Specific Connector Properties
542----------------------------------
543
544.. kernel-doc:: drivers/gpu/drm/drm_connector.c
545 :doc: HDMI connector properties
546
547Analog TV Specific Connector Properties
548---------------------------------------
549
550.. kernel-doc:: drivers/gpu/drm/drm_connector.c
551 :doc: Analog TV Connector Properties
552
553Standard CRTC Properties
554------------------------
555
556.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
557 :doc: standard CRTC properties
558
559Standard Plane Properties
560-------------------------
561
562.. kernel-doc:: drivers/gpu/drm/drm_plane.c
563 :doc: standard plane properties
564
565.. _plane_composition_properties:
566
567Plane Composition Properties
568----------------------------
569
570.. kernel-doc:: drivers/gpu/drm/drm_blend.c
571 :doc: overview
572
573.. _damage_tracking_properties:
574
575Damage Tracking Properties
576--------------------------
577
578.. kernel-doc:: drivers/gpu/drm/drm_plane.c
579 :doc: damage tracking
580
581Color Management Properties
582---------------------------
583
584.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
585 :doc: overview
586
587Tile Group Property
588-------------------
589
590.. kernel-doc:: drivers/gpu/drm/drm_connector.c
591 :doc: Tile group
592
593Explicit Fencing Properties
594---------------------------
595
596.. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
597 :doc: explicit fencing properties
598
599
600Variable Refresh Properties
601---------------------------
602
603.. kernel-doc:: drivers/gpu/drm/drm_connector.c
604 :doc: Variable refresh properties
605
606Cursor Hotspot Properties
607---------------------------
608
609.. kernel-doc:: drivers/gpu/drm/drm_plane.c
610 :doc: hotspot properties
611
612Existing KMS Properties
613-----------------------
614
615The following table gives description of drm properties exposed by various
616modules/drivers. Because this table is very unwieldy, do not add any new
617properties here. Instead document them in a section above.
618
619.. csv-table::
620 :header-rows: 1
621 :file: kms-properties.csv
622
623Vertical Blanking
624=================
625
626.. kernel-doc:: drivers/gpu/drm/drm_vblank.c
627 :doc: vblank handling
628
629Vertical Blanking and Interrupt Handling Functions Reference
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
638Vertical Blank Work
639===================
640
641.. kernel-doc:: drivers/gpu/drm/drm_vblank_work.c
642 :doc: vblank works
643
644Vertical 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_work.c
651 :export:
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
18Mode Configuration
19
20KMS Core Structures and Functions
21=================================
22
23.. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
24 :export:
25
26.. kernel-doc:: include/drm/drm_mode_config.h
27 :internal:
28
29Modeset Base Object Abstraction
30===============================
31
32.. kernel-doc:: include/drm/drm_mode_object.h
33 :internal:
34
35.. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
36 :export:
37
38Atomic Mode Setting Function Reference
39======================================
40
41.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
42 :export:
43
44.. kernel-doc:: include/drm/drm_atomic.h
45 :internal:
46
47CRTC Abstraction
48================
49
50.. kernel-doc:: drivers/gpu/drm/drm_crtc.c
51 :export:
52
53.. kernel-doc:: include/drm/drm_crtc.h
54 :internal:
55
56Frame Buffer Abstraction
57========================
58
59.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
60 :doc: overview
61
62Frame Buffer Functions Reference
63--------------------------------
64
65.. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
66 :export:
67
68.. kernel-doc:: include/drm/drm_framebuffer.h
69 :internal:
70
71DRM Format Handling
72===================
73
74.. kernel-doc:: include/drm/drm_fourcc.h
75 :internal:
76
77.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
78 :export:
79
80Dumb Buffer Objects
81===================
82
83.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
84 :doc: overview
85
86Plane Abstraction
87=================
88
89.. kernel-doc:: drivers/gpu/drm/drm_plane.c
90 :doc: overview
91
92Plane Functions Reference
93-------------------------
94
95.. kernel-doc:: include/drm/drm_plane.h
96 :internal:
97
98.. kernel-doc:: drivers/gpu/drm/drm_plane.c
99 :export:
100
101Display Modes Function Reference
102================================
103
104.. kernel-doc:: include/drm/drm_modes.h
105 :internal:
106
107.. kernel-doc:: drivers/gpu/drm/drm_modes.c
108 :export:
109
110Connector Abstraction
111=====================
112
113.. kernel-doc:: drivers/gpu/drm/drm_connector.c
114 :doc: overview
115
116Connector Functions Reference
117-----------------------------
118
119.. kernel-doc:: include/drm/drm_connector.h
120 :internal:
121
122.. kernel-doc:: drivers/gpu/drm/drm_connector.c
123 :export:
124
125Encoder Abstraction
126===================
127
128.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
129 :doc: overview
130
131Encoder Functions Reference
132---------------------------
133
134.. kernel-doc:: include/drm/drm_encoder.h
135 :internal:
136
137.. kernel-doc:: drivers/gpu/drm/drm_encoder.c
138 :export:
139
140KMS Initialization and Cleanup
141==============================
142
143A KMS device is abstracted and exposed as a set of planes, CRTCs,
144encoders and connectors. KMS drivers must thus create and initialize all
145those objects at load time after initializing mode setting.
146
147CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
148--------------------------------------------
149
150A CRTC is an abstraction representing a part of the chip that contains a
151pointer to a scanout buffer. Therefore, the number of CRTCs available
152determines how many independent scanout buffers can be active at any
153given time. The CRTC structure contains several fields to support this:
154a pointer to some video memory (abstracted as a frame buffer object), a
155display mode, and an (x, y) offset into the video memory to support
156panning or configurations where one piece of video memory spans multiple
157CRTCs.
158
159CRTC Initialization
160~~~~~~~~~~~~~~~~~~~
161
162A KMS device must create and register at least one struct
163:c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
164allocated and zeroed by the driver, possibly as part of a larger
165structure, and registered with a call to :c:func:`drm_crtc_init()`
166with a pointer to CRTC functions.
167
168
169Cleanup
170-------
171
172The DRM core manages its objects' lifetime. When an object is not needed
173anymore the core calls its destroy function, which must clean up and
174free every resource allocated for the object. Every
175:c:func:`drm_\*_init()` call must be matched with a corresponding
176:c:func:`drm_\*_cleanup()` call to cleanup CRTCs
177(:c:func:`drm_crtc_cleanup()`), planes
178(:c:func:`drm_plane_cleanup()`), encoders
179(:c:func:`drm_encoder_cleanup()`) and connectors
180(:c:func:`drm_connector_cleanup()`). Furthermore, connectors that
181have been added to sysfs must be removed by a call to
182:c:func:`drm_connector_unregister()` before calling
183:c:func:`drm_connector_cleanup()`.
184
185Connectors state change detection must be cleanup up with a call to
186:c:func:`drm_kms_helper_poll_fini()`.
187
188Output discovery and initialization example
189-------------------------------------------
190
191.. code-block:: c
192
193 void intel_crt_init(struct drm_device *dev)
194 {
195 struct drm_connector *connector;
196 struct intel_output *intel_output;
197
198 intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
199 if (!intel_output)
200 return;
201
202 connector = &intel_output->base;
203 drm_connector_init(dev, &intel_output->base,
204 &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
205
206 drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
207 DRM_MODE_ENCODER_DAC);
208
209 drm_mode_connector_attach_encoder(&intel_output->base,
210 &intel_output->enc);
211
212 /* Set up the DDC bus. */
213 intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
214 if (!intel_output->ddc_bus) {
215 dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
216 "failed.\n");
217 return;
218 }
219
220 intel_output->type = INTEL_OUTPUT_ANALOG;
221 connector->interlace_allowed = 0;
222 connector->doublescan_allowed = 0;
223
224 drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
225 drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
226
227 drm_connector_register(connector);
228 }
229
230In the example above (taken from the i915 driver), a CRTC, connector and
231encoder combination is created. A device-specific i2c bus is also
232created for fetching EDID data and performing monitor detection. Once
233the process is complete, the new connector is registered with sysfs to
234make its properties available to applications.
235
236KMS Locking
237===========
238
239.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
240 :doc: kms locking
241
242.. kernel-doc:: include/drm/drm_modeset_lock.h
243 :internal:
244
245.. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
246 :export:
247
248KMS Properties
249==============
250
251Property Types and Blob Property Support
252----------------------------------------
253
254.. kernel-doc:: drivers/gpu/drm/drm_property.c
255 :doc: overview
256
257.. kernel-doc:: include/drm/drm_property.h
258 :internal:
259
260.. kernel-doc:: drivers/gpu/drm/drm_property.c
261 :export:
262
263Standard Connector Properties
264-----------------------------
265
266.. kernel-doc:: drivers/gpu/drm/drm_connector.c
267 :doc: standard connector properties
268
269Plane Composition Properties
270----------------------------
271
272.. kernel-doc:: drivers/gpu/drm/drm_blend.c
273 :doc: overview
274
275.. kernel-doc:: drivers/gpu/drm/drm_blend.c
276 :export:
277
278Color Management Properties
279---------------------------
280
281.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
282 :doc: overview
283
284.. kernel-doc:: include/drm/drm_color_mgmt.h
285 :internal:
286
287.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
288 :export:
289
290Tile Group Property
291-------------------
292
293.. kernel-doc:: drivers/gpu/drm/drm_connector.c
294 :doc: Tile group
295
296Explicit Fencing Properties
297---------------------------
298
299.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
300 :doc: explicit fencing properties
301
302Existing KMS Properties
303-----------------------
304
305The following table gives description of drm properties exposed by
306various modules/drivers.
307
308.. csv-table::
309 :header-rows: 1
310 :file: kms-properties.csv
311
312Vertical Blanking
313=================
314
315Vertical blanking plays a major role in graphics rendering. To achieve
316tear-free display, users must synchronize page flips and/or rendering to
317vertical blanking. The DRM API offers ioctls to perform page flips
318synchronized to vertical blanking and wait for vertical blanking.
319
320The DRM core handles most of the vertical blanking management logic,
321which involves filtering out spurious interrupts, keeping race-free
322blanking counters, coping with counter wrap-around and resets and
323keeping use counts. It relies on the driver to generate vertical
324blanking interrupts and optionally provide a hardware vertical blanking
325counter. Drivers must implement the following operations.
326
327- int (\*enable_vblank) (struct drm_device \*dev, int crtc); void
328 (\*disable_vblank) (struct drm_device \*dev, int crtc);
329 Enable or disable vertical blanking interrupts for the given CRTC.
330
331- u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc);
332 Retrieve the value of the vertical blanking counter for the given
333 CRTC. If the hardware maintains a vertical blanking counter its value
334 should be returned. Otherwise drivers can use the
335 :c:func:`drm_vblank_count()` helper function to handle this
336 operation.
337
338Drivers must initialize the vertical blanking handling core with a call
339to :c:func:`drm_vblank_init()` in their load operation.
340
341Vertical blanking interrupts can be enabled by the DRM core or by
342drivers themselves (for instance to handle page flipping operations).
343The DRM core maintains a vertical blanking use count to ensure that the
344interrupts are not disabled while a user still needs them. To increment
345the use count, drivers call :c:func:`drm_vblank_get()`. Upon
346return vertical blanking interrupts are guaranteed to be enabled.
347
348To decrement the use count drivers call
349:c:func:`drm_vblank_put()`. Only when the use count drops to zero
350will the DRM core disable the vertical blanking interrupts after a delay
351by scheduling a timer. The delay is accessible through the
352vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global
353variable and expressed in milliseconds. Its default value is 5000 ms.
354Zero means never disable, and a negative value means disable
355immediately. Drivers may override the behaviour by setting the
356:c:type:`struct drm_device <drm_device>`
357vblank_disable_immediate flag, which when set causes vblank interrupts
358to be disabled immediately regardless of the drm_vblank_offdelay
359value. The flag should only be set if there's a properly working
360hardware vblank counter present.
361
362When a vertical blanking interrupt occurs drivers only need to call the
363:c:func:`drm_handle_vblank()` function to account for the
364interrupt.
365
366Resources allocated by :c:func:`drm_vblank_init()` must be freed
367with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
368operation handler.
369
370Vertical Blanking and Interrupt Handling Functions Reference
371------------------------------------------------------------
372
373.. kernel-doc:: drivers/gpu/drm/drm_irq.c
374 :export:
375
376.. kernel-doc:: include/drm/drm_irq.h
377 :internal: