1 ========================= 1 =========================
2 Kernel Mode Setting (KMS) 2 Kernel Mode Setting (KMS)
3 ========================= 3 =========================
4 4
5 Drivers must initialize the mode setting core 5 Drivers must initialize the mode setting core by calling
6 drmm_mode_config_init() on the DRM device. The !! 6 :c:func:`drm_mode_config_init()` on the DRM device. The function
7 initializes the :c:type:`struct drm_device <dr 7 initializes the :c:type:`struct drm_device <drm_device>`
8 mode_config field and never fails. Once done, 8 mode_config field and never fails. Once done, mode configuration must
9 be setup by initializing the following fields. 9 be setup by initializing the following fields.
10 10
11 - int min_width, min_height; int max_width, m 11 - int min_width, min_height; int max_width, max_height;
12 Minimum and maximum width and height of the 12 Minimum and maximum width and height of the frame buffers in pixel
13 units. 13 units.
14 14
15 - struct drm_mode_config_funcs \*funcs; 15 - struct drm_mode_config_funcs \*funcs;
16 Mode setting functions. 16 Mode setting functions.
17 17
18 Overview !! 18 Mode Configuration
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 19
153 KMS Core Structures and Functions 20 KMS Core Structures and Functions
154 ================================= 21 =================================
155 22
156 .. kernel-doc:: include/drm/drm_mode_config.h <<
157 :internal: <<
158 <<
159 .. kernel-doc:: drivers/gpu/drm/drm_mode_confi 23 .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c
160 :export: 24 :export:
161 25
162 .. _kms_base_object_abstraction: !! 26 .. kernel-doc:: include/drm/drm_mode_config.h
>> 27 :internal:
163 28
164 Modeset Base Object Abstraction 29 Modeset Base Object Abstraction
165 =============================== 30 ===============================
166 31
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 32 .. kernel-doc:: include/drm/drm_mode_object.h
189 :internal: 33 :internal:
190 34
191 .. kernel-doc:: drivers/gpu/drm/drm_mode_objec 35 .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c
192 :export: 36 :export:
193 37
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 38 Atomic Mode Setting Function Reference
292 -------------------------------------- !! 39 ======================================
293 <<
294 .. kernel-doc:: include/drm/drm_atomic.h <<
295 :internal: <<
296 40
297 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c 41 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
298 :export: 42 :export:
299 43
300 Atomic Mode Setting IOCTL and UAPI Functions !! 44 .. kernel-doc:: include/drm/drm_atomic.h
301 -------------------------------------------- !! 45 :internal:
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 46
309 CRTC Abstraction 47 CRTC Abstraction
310 ================ 48 ================
311 49
312 .. kernel-doc:: drivers/gpu/drm/drm_crtc.c 50 .. 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: 51 :export:
329 52
330 .. kernel-doc:: include/drm/drm_color_mgmt.h !! 53 .. kernel-doc:: include/drm/drm_crtc.h
331 :internal: 54 :internal:
332 55
333 Frame Buffer Abstraction 56 Frame Buffer Abstraction
334 ======================== 57 ========================
335 58
336 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe 59 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
337 :doc: overview 60 :doc: overview
338 61
339 Frame Buffer Functions Reference 62 Frame Buffer Functions Reference
340 -------------------------------- 63 --------------------------------
341 64
342 .. kernel-doc:: include/drm/drm_framebuffer.h <<
343 :internal: <<
344 <<
345 .. kernel-doc:: drivers/gpu/drm/drm_framebuffe 65 .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c
346 :export: 66 :export:
347 67
>> 68 .. kernel-doc:: include/drm/drm_framebuffer.h
>> 69 :internal:
>> 70
348 DRM Format Handling 71 DRM Format Handling
349 =================== 72 ===================
350 73
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 74 .. kernel-doc:: include/drm/drm_fourcc.h
358 :internal: 75 :internal:
359 76
360 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c 77 .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
361 :export: 78 :export:
362 79
363 .. _kms_dumb_buffer_objects: <<
364 <<
365 Dumb Buffer Objects 80 Dumb Buffer Objects
366 =================== 81 ===================
367 82
368 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffe 83 .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
369 :doc: overview 84 :doc: overview
370 85
371 Plane Abstraction 86 Plane Abstraction
372 ================= 87 =================
373 88
374 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 89 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
375 :doc: overview 90 :doc: overview
376 91
377 Plane Functions Reference 92 Plane Functions Reference
378 ------------------------- 93 -------------------------
379 94
380 .. kernel-doc:: include/drm/drm_plane.h 95 .. kernel-doc:: include/drm/drm_plane.h
381 :internal: 96 :internal:
382 97
383 .. kernel-doc:: drivers/gpu/drm/drm_plane.c 98 .. kernel-doc:: drivers/gpu/drm/drm_plane.c
384 :export: 99 :export:
385 100
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 101 Display Modes Function Reference
417 ================================ 102 ================================
418 103
419 .. kernel-doc:: include/drm/drm_modes.h 104 .. kernel-doc:: include/drm/drm_modes.h
420 :internal: 105 :internal:
421 106
422 .. kernel-doc:: drivers/gpu/drm/drm_modes.c 107 .. kernel-doc:: drivers/gpu/drm/drm_modes.c
423 :export: 108 :export:
424 109
425 Connector Abstraction 110 Connector Abstraction
426 ===================== 111 =====================
427 112
428 .. kernel-doc:: drivers/gpu/drm/drm_connector. 113 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
429 :doc: overview 114 :doc: overview
430 115
431 Connector Functions Reference 116 Connector Functions Reference
432 ----------------------------- 117 -----------------------------
433 118
434 .. kernel-doc:: include/drm/drm_connector.h 119 .. kernel-doc:: include/drm/drm_connector.h
435 :internal: 120 :internal:
436 121
437 .. kernel-doc:: drivers/gpu/drm/drm_connector. 122 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
438 :export: 123 :export:
439 124
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 125 Encoder Abstraction
453 =================== 126 ===================
454 127
455 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 128 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
456 :doc: overview 129 :doc: overview
457 130
458 Encoder Functions Reference 131 Encoder Functions Reference
459 --------------------------- 132 ---------------------------
460 133
461 .. kernel-doc:: include/drm/drm_encoder.h 134 .. kernel-doc:: include/drm/drm_encoder.h
462 :internal: 135 :internal:
463 136
464 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c 137 .. kernel-doc:: drivers/gpu/drm/drm_encoder.c
465 :export: 138 :export:
466 139
>> 140 KMS Initialization and Cleanup
>> 141 ==============================
>> 142
>> 143 A KMS device is abstracted and exposed as a set of planes, CRTCs,
>> 144 encoders and connectors. KMS drivers must thus create and initialize all
>> 145 those objects at load time after initializing mode setting.
>> 146
>> 147 CRTCs (:c:type:`struct drm_crtc <drm_crtc>`)
>> 148 --------------------------------------------
>> 149
>> 150 A CRTC is an abstraction representing a part of the chip that contains a
>> 151 pointer to a scanout buffer. Therefore, the number of CRTCs available
>> 152 determines how many independent scanout buffers can be active at any
>> 153 given time. The CRTC structure contains several fields to support this:
>> 154 a pointer to some video memory (abstracted as a frame buffer object), a
>> 155 display mode, and an (x, y) offset into the video memory to support
>> 156 panning or configurations where one piece of video memory spans multiple
>> 157 CRTCs.
>> 158
>> 159 CRTC Initialization
>> 160 ~~~~~~~~~~~~~~~~~~~
>> 161
>> 162 A KMS device must create and register at least one struct
>> 163 :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is
>> 164 allocated and zeroed by the driver, possibly as part of a larger
>> 165 structure, and registered with a call to :c:func:`drm_crtc_init()`
>> 166 with a pointer to CRTC functions.
>> 167
>> 168
>> 169 Cleanup
>> 170 -------
>> 171
>> 172 The DRM core manages its objects' lifetime. When an object is not needed
>> 173 anymore the core calls its destroy function, which must clean up and
>> 174 free 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
>> 181 have 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
>> 185 Connectors state change detection must be cleanup up with a call to
>> 186 :c:func:`drm_kms_helper_poll_fini()`.
>> 187
>> 188 Output 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
>> 230 In the example above (taken from the i915 driver), a CRTC, connector and
>> 231 encoder combination is created. A device-specific i2c bus is also
>> 232 created for fetching EDID data and performing monitor detection. Once
>> 233 the process is complete, the new connector is registered with sysfs to
>> 234 make its properties available to applications.
>> 235
467 KMS Locking 236 KMS Locking
468 =========== 237 ===========
469 238
470 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo 239 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
471 :doc: kms locking 240 :doc: kms locking
472 241
473 .. kernel-doc:: include/drm/drm_modeset_lock.h 242 .. kernel-doc:: include/drm/drm_modeset_lock.h
474 :internal: 243 :internal:
475 244
476 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lo 245 .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c
477 :export: 246 :export:
478 247
479 KMS Properties 248 KMS Properties
480 ============== 249 ==============
481 250
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 251 Property Types and Blob Property Support
522 ---------------------------------------- 252 ----------------------------------------
523 253
524 .. kernel-doc:: drivers/gpu/drm/drm_property.c 254 .. kernel-doc:: drivers/gpu/drm/drm_property.c
525 :doc: overview 255 :doc: overview
526 256
527 .. kernel-doc:: include/drm/drm_property.h 257 .. kernel-doc:: include/drm/drm_property.h
528 :internal: 258 :internal:
529 259
530 .. kernel-doc:: drivers/gpu/drm/drm_property.c 260 .. kernel-doc:: drivers/gpu/drm/drm_property.c
531 :export: 261 :export:
532 262
533 .. _standard_connector_properties: <<
534 <<
535 Standard Connector Properties 263 Standard Connector Properties
536 ----------------------------- 264 -----------------------------
537 265
538 .. kernel-doc:: drivers/gpu/drm/drm_connector. 266 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
539 :doc: standard connector properties 267 :doc: standard connector properties
540 268
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 269 Plane Composition Properties
568 ---------------------------- 270 ----------------------------
569 271
570 .. kernel-doc:: drivers/gpu/drm/drm_blend.c 272 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
571 :doc: overview 273 :doc: overview
572 274
573 .. _damage_tracking_properties: !! 275 .. kernel-doc:: drivers/gpu/drm/drm_blend.c
574 !! 276 :export:
575 Damage Tracking Properties <<
576 -------------------------- <<
577 <<
578 .. kernel-doc:: drivers/gpu/drm/drm_plane.c <<
579 :doc: damage tracking <<
580 277
581 Color Management Properties 278 Color Management Properties
582 --------------------------- 279 ---------------------------
583 280
584 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt 281 .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
585 :doc: overview 282 :doc: overview
586 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
587 Tile Group Property 290 Tile Group Property
588 ------------------- 291 -------------------
589 292
590 .. kernel-doc:: drivers/gpu/drm/drm_connector. 293 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
591 :doc: Tile group 294 :doc: Tile group
592 295
593 Explicit Fencing Properties 296 Explicit Fencing Properties
594 --------------------------- 297 ---------------------------
595 298
596 .. kernel-doc:: drivers/gpu/drm/drm_atomic_uap !! 299 .. kernel-doc:: drivers/gpu/drm/drm_atomic.c
597 :doc: explicit fencing properties 300 :doc: explicit fencing properties
598 301
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 302 Existing KMS Properties
613 ----------------------- 303 -----------------------
614 304
615 The following table gives description of drm p !! 305 The following table gives description of drm properties exposed by
616 modules/drivers. Because this table is very un !! 306 various modules/drivers.
617 properties here. Instead document them in a se <<
618 307
619 .. csv-table:: 308 .. csv-table::
620 :header-rows: 1 309 :header-rows: 1
621 :file: kms-properties.csv 310 :file: kms-properties.csv
622 311
623 Vertical Blanking 312 Vertical Blanking
624 ================= 313 =================
625 314
626 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c !! 315 Vertical blanking plays a major role in graphics rendering. To achieve
627 :doc: vblank handling !! 316 tear-free display, users must synchronize page flips and/or rendering to
>> 317 vertical blanking. The DRM API offers ioctls to perform page flips
>> 318 synchronized to vertical blanking and wait for vertical blanking.
>> 319
>> 320 The DRM core handles most of the vertical blanking management logic,
>> 321 which involves filtering out spurious interrupts, keeping race-free
>> 322 blanking counters, coping with counter wrap-around and resets and
>> 323 keeping use counts. It relies on the driver to generate vertical
>> 324 blanking interrupts and optionally provide a hardware vertical blanking
>> 325 counter. 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
>> 338 Drivers must initialize the vertical blanking handling core with a call
>> 339 to :c:func:`drm_vblank_init()` in their load operation.
>> 340
>> 341 Vertical blanking interrupts can be enabled by the DRM core or by
>> 342 drivers themselves (for instance to handle page flipping operations).
>> 343 The DRM core maintains a vertical blanking use count to ensure that the
>> 344 interrupts are not disabled while a user still needs them. To increment
>> 345 the use count, drivers call :c:func:`drm_vblank_get()`. Upon
>> 346 return vertical blanking interrupts are guaranteed to be enabled.
>> 347
>> 348 To decrement the use count drivers call
>> 349 :c:func:`drm_vblank_put()`. Only when the use count drops to zero
>> 350 will the DRM core disable the vertical blanking interrupts after a delay
>> 351 by scheduling a timer. The delay is accessible through the
>> 352 vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global
>> 353 variable and expressed in milliseconds. Its default value is 5000 ms.
>> 354 Zero means never disable, and a negative value means disable
>> 355 immediately. Drivers may override the behaviour by setting the
>> 356 :c:type:`struct drm_device <drm_device>`
>> 357 vblank_disable_immediate flag, which when set causes vblank interrupts
>> 358 to be disabled immediately regardless of the drm_vblank_offdelay
>> 359 value. The flag should only be set if there's a properly working
>> 360 hardware vblank counter present.
>> 361
>> 362 When a vertical blanking interrupt occurs drivers only need to call the
>> 363 :c:func:`drm_handle_vblank()` function to account for the
>> 364 interrupt.
>> 365
>> 366 Resources allocated by :c:func:`drm_vblank_init()` must be freed
>> 367 with a call to :c:func:`drm_vblank_cleanup()` in the driver unload
>> 368 operation handler.
628 369
629 Vertical Blanking and Interrupt Handling Funct 370 Vertical Blanking and Interrupt Handling Functions Reference
630 ---------------------------------------------- 371 ------------------------------------------------------------
631 372
632 .. kernel-doc:: include/drm/drm_vblank.h !! 373 .. kernel-doc:: drivers/gpu/drm/drm_irq.c
633 :internal: <<
634 <<
635 .. kernel-doc:: drivers/gpu/drm/drm_vblank.c <<
636 :export: 374 :export:
637 375
638 Vertical Blank Work !! 376 .. kernel-doc:: include/drm/drm_irq.h
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: 377 :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.