Commit | Line | Data |
---|---|---|
2fa91d15 JN |
1 | ========================= |
2 | Kernel Mode Setting (KMS) | |
3 | ========================= | |
4 | ||
2fa91d15 JN |
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 | ||
2564d0b0 DV |
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. One or more (or even no) | |
60 | planes feed their pixel data into a CRTC (represented by :c:type:`struct | |
61 | drm_crtc <drm_crtc>`, see `CRTC Abstraction`_) for blending. The precise | |
62 | blending step is explained in more detail in `Plane Composition Properties`_ and | |
63 | related chapters. | |
64 | ||
65 | For the output routing the first step is encoders (represented by | |
66 | :c:type:`struct drm_encoder <drm_encoder>`, see `Encoder Abstraction`_). Those | |
67 | are really just internal artifacts of the helper libraries used to implement KMS | |
68 | drivers. Besides that they make it unecessarily more complicated for userspace | |
69 | to figure out which connections between a CRTC and a connector are possible, and | |
70 | what kind of cloning is supported, they serve no purpose in the userspace API. | |
71 | Unfortunately encoders have been exposed to userspace, hence can't remove them | |
72 | at this point. Futhermore the exposed restrictions are often wrongly set by | |
73 | drivers, and in many cases not powerful enough to express the real restrictions. | |
74 | A CRTC can be connected to multiple encoders, and for an active CRTC there must | |
75 | be at least one encoder. | |
76 | ||
77 | The final, and real, endpoint in the display chain is the connector (represented | |
78 | by :c:type:`struct drm_connector <drm_connector>`, see `Connector | |
79 | Abstraction`_). Connectors can have different possible encoders, but the kernel | |
80 | driver selects which encoder to use for each connector. The use case is DVI, | |
81 | which could switch between an analog and a digital encoder. Encoders can also | |
82 | drive multiple different connectors. There is exactly one active connector for | |
83 | every active encoder. | |
84 | ||
85 | Internally the output pipeline is a bit more complex and matches today's | |
86 | hardware more closely: | |
87 | ||
88 | .. kernel-render:: DOT | |
89 | :alt: KMS Output Pipeline | |
90 | :caption: KMS Output Pipeline | |
91 | ||
92 | digraph "Output Pipeline" { | |
93 | node [shape=box] | |
94 | ||
95 | subgraph { | |
96 | "drm_crtc" [bgcolor=grey style=filled] | |
97 | } | |
98 | ||
99 | subgraph cluster_internal { | |
100 | style=dashed | |
101 | label="Internal Pipeline" | |
102 | { | |
103 | node [bgcolor=grey style=filled] | |
104 | "drm_encoder A"; | |
105 | "drm_encoder B"; | |
106 | "drm_encoder C"; | |
107 | } | |
108 | ||
109 | { | |
110 | node [bgcolor=grey style=filled] | |
111 | "drm_encoder B" -> "drm_bridge B" | |
112 | "drm_encoder C" -> "drm_bridge C1" | |
113 | "drm_bridge C1" -> "drm_bridge C2"; | |
114 | } | |
115 | } | |
116 | ||
117 | "drm_crtc" -> "drm_encoder A" | |
118 | "drm_crtc" -> "drm_encoder B" | |
119 | "drm_crtc" -> "drm_encoder C" | |
120 | ||
121 | ||
122 | subgraph cluster_output { | |
123 | style=dashed | |
124 | label="Outputs" | |
125 | ||
126 | "drm_encoder A" -> "drm_connector A"; | |
127 | "drm_bridge B" -> "drm_connector B"; | |
128 | "drm_bridge C2" -> "drm_connector C"; | |
129 | ||
130 | "drm_panel" | |
131 | } | |
132 | } | |
133 | ||
134 | Internally two additional helper objects come into play. First, to be able to | |
135 | share code for encoders (sometimes on the same SoC, sometimes off-chip) one or | |
136 | more :ref:`drm_bridges` (represented by :c:type:`struct drm_bridge | |
137 | <drm_bridge>`) can be linked to an encoder. This link is static and cannot be | |
138 | changed, which means the cross-bar (if there is any) needs to be mapped between | |
139 | the CRTC and any encoders. Often for drivers with bridges there's no code left | |
140 | at the encoder level. Atomic drivers can leave out all the encoder callbacks to | |
141 | essentially only leave a dummy routing object behind, which is needed for | |
142 | backwards compatibility since encoders are exposed to userspace. | |
143 | ||
144 | The second object is for panels, represented by :c:type:`struct drm_panel | |
145 | <drm_panel>`, see :ref:`drm_panel_helper`. Panels do not have a fixed binding | |
146 | point, but are generally linked to the driver private structure that embeds | |
147 | :c:type:`struct drm_connector <drm_connector>`. | |
148 | ||
149 | Note that currently the bridge chaining and interactions with connectors and | |
150 | panels are still in-flux and not really fully sorted out yet. | |
949619f3 | 151 | |
28575f16 DV |
152 | KMS Core Structures and Functions |
153 | ================================= | |
949619f3 | 154 | |
28575f16 | 155 | .. kernel-doc:: include/drm/drm_mode_config.h |
2fa91d15 JN |
156 | :internal: |
157 | ||
1ea35768 DV |
158 | .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c |
159 | :export: | |
160 | ||
28575f16 DV |
161 | Modeset Base Object Abstraction |
162 | =============================== | |
311b62d9 | 163 | |
b2b82c26 DV |
164 | .. kernel-render:: DOT |
165 | :alt: Mode Objects and Properties | |
166 | :caption: Mode Objects and Properties | |
167 | ||
168 | digraph { | |
169 | node [shape=box] | |
170 | ||
171 | "drm_property A" -> "drm_mode_object A" | |
172 | "drm_property A" -> "drm_mode_object B" | |
173 | "drm_property B" -> "drm_mode_object A" | |
174 | } | |
175 | ||
176 | The base structure for all KMS objects is :c:type:`struct drm_mode_object | |
177 | <drm_mode_object>`. One of the base services it provides is tracking properties, | |
178 | which are especially important for the atomic IOCTL (see `Atomic Mode | |
179 | Setting`_). The somewhat surprising part here is that properties are not | |
180 | directly instantiated on each object, but free-standing mode objects themselves, | |
181 | represented by :c:type:`struct drm_property <drm_property>`, which only specify | |
182 | the type and value range of a property. Any given property can be attached | |
183 | multiple times to different objects using :c:func:`drm_object_attach_property() | |
184 | <drm_object_attach_property>`. | |
185 | ||
28575f16 DV |
186 | .. kernel-doc:: include/drm/drm_mode_object.h |
187 | :internal: | |
188 | ||
189 | .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c | |
2fa91d15 JN |
190 | :export: |
191 | ||
4a8e2292 DV |
192 | Atomic Mode Setting |
193 | =================== | |
194 | ||
195 | ||
196 | .. kernel-render:: DOT | |
197 | :alt: Mode Objects and Properties | |
198 | :caption: Mode Objects and Properties | |
199 | ||
200 | digraph { | |
201 | node [shape=box] | |
202 | ||
203 | subgraph cluster_state { | |
204 | style=dashed | |
205 | label="Free-standing state" | |
206 | ||
207 | "drm_atomic_state" -> "duplicated drm_plane_state A" | |
208 | "drm_atomic_state" -> "duplicated drm_plane_state B" | |
209 | "drm_atomic_state" -> "duplicated drm_crtc_state" | |
210 | "drm_atomic_state" -> "duplicated drm_connector_state" | |
211 | "drm_atomic_state" -> "duplicated driver private state" | |
212 | } | |
213 | ||
214 | subgraph cluster_current { | |
215 | style=dashed | |
216 | label="Current state" | |
217 | ||
218 | "drm_device" -> "drm_plane A" | |
219 | "drm_device" -> "drm_plane B" | |
220 | "drm_device" -> "drm_crtc" | |
221 | "drm_device" -> "drm_connector" | |
222 | "drm_device" -> "driver private object" | |
223 | ||
224 | "drm_plane A" -> "drm_plane_state A" | |
225 | "drm_plane B" -> "drm_plane_state B" | |
226 | "drm_crtc" -> "drm_crtc_state" | |
227 | "drm_connector" -> "drm_connector_state" | |
228 | "driver private object" -> "driver private state" | |
229 | } | |
230 | ||
231 | "drm_atomic_state" -> "drm_device" [label="atomic_commit"] | |
232 | "duplicated drm_plane_state A" -> "drm_device"[style=invis] | |
233 | } | |
234 | ||
235 | Atomic provides transactional modeset (including planes) updates, but a | |
236 | bit differently from the usual transactional approach of try-commit and | |
237 | rollback: | |
238 | ||
239 | - Firstly, no hardware changes are allowed when the commit would fail. This | |
240 | allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows | |
241 | userspace to explore whether certain configurations would work or not. | |
242 | ||
243 | - This would still allow setting and rollback of just the software state, | |
244 | simplifying conversion of existing drivers. But auditing drivers for | |
245 | correctness of the atomic_check code becomes really hard with that: Rolling | |
246 | back changes in data structures all over the place is hard to get right. | |
247 | ||
248 | - Lastly, for backwards compatibility and to support all use-cases, atomic | |
249 | updates need to be incremental and be able to execute in parallel. Hardware | |
250 | doesn't always allow it, but where possible plane updates on different CRTCs | |
251 | should not interfere, and not get stalled due to output routing changing on | |
252 | different CRTCs. | |
253 | ||
254 | Taken all together there's two consequences for the atomic design: | |
255 | ||
256 | - The overall state is split up into per-object state structures: | |
257 | :c:type:`struct drm_plane_state <drm_plane_state>` for planes, :c:type:`struct | |
258 | drm_crtc_state <drm_crtc_state>` for CRTCs and :c:type:`struct | |
259 | drm_connector_state <drm_connector_state>` for connectors. These are the only | |
260 | objects with userspace-visible and settable state. For internal state drivers | |
261 | can subclass these structures through embeddeding, or add entirely new state | |
262 | structures for their globally shared hardware functions. | |
263 | ||
264 | - An atomic update is assembled and validated as an entirely free-standing pile | |
265 | of structures within the :c:type:`drm_atomic_state <drm_atomic_state>` | |
266 | container. Again drivers can subclass that container for their own state | |
267 | structure tracking needs. Only when a state is committed is it applied to the | |
268 | driver and modeset objects. This way rolling back an update boils down to | |
269 | releasing memory and unreferencing objects like framebuffers. | |
270 | ||
271 | Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed | |
272 | coverage of specific topics. | |
273 | ||
2fa91d15 | 274 | Atomic Mode Setting Function Reference |
4a8e2292 | 275 | -------------------------------------- |
2fa91d15 | 276 | |
5d070be6 | 277 | .. kernel-doc:: include/drm/drm_atomic.h |
2fa91d15 JN |
278 | :internal: |
279 | ||
1ea35768 DV |
280 | .. kernel-doc:: drivers/gpu/drm/drm_atomic.c |
281 | :export: | |
282 | ||
28575f16 DV |
283 | CRTC Abstraction |
284 | ================ | |
285 | ||
286 | .. kernel-doc:: drivers/gpu/drm/drm_crtc.c | |
d5d487eb DV |
287 | :doc: overview |
288 | ||
289 | CRTC Functions Reference | |
290 | -------------------------------- | |
28575f16 DV |
291 | |
292 | .. kernel-doc:: include/drm/drm_crtc.h | |
293 | :internal: | |
294 | ||
d5d487eb DV |
295 | .. kernel-doc:: drivers/gpu/drm/drm_crtc.c |
296 | :export: | |
297 | ||
2fa91d15 | 298 | Frame Buffer Abstraction |
311b62d9 | 299 | ======================== |
2fa91d15 | 300 | |
750fb8c4 DV |
301 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c |
302 | :doc: overview | |
2fa91d15 | 303 | |
7520a277 DV |
304 | Frame Buffer Functions Reference |
305 | -------------------------------- | |
306 | ||
7520a277 DV |
307 | .. kernel-doc:: include/drm/drm_framebuffer.h |
308 | :internal: | |
309 | ||
1ea35768 DV |
310 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c |
311 | :export: | |
312 | ||
2fa91d15 | 313 | DRM Format Handling |
311b62d9 | 314 | =================== |
2fa91d15 | 315 | |
84770cc2 LP |
316 | .. kernel-doc:: include/drm/drm_fourcc.h |
317 | :internal: | |
318 | ||
2fa91d15 JN |
319 | .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c |
320 | :export: | |
321 | ||
322 | Dumb Buffer Objects | |
311b62d9 | 323 | =================== |
2fa91d15 | 324 | |
4f93624e DV |
325 | .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c |
326 | :doc: overview | |
2fa91d15 | 327 | |
43968d7b DV |
328 | Plane Abstraction |
329 | ================= | |
330 | ||
532b3671 DV |
331 | .. kernel-doc:: drivers/gpu/drm/drm_plane.c |
332 | :doc: overview | |
333 | ||
43968d7b DV |
334 | Plane Functions Reference |
335 | ------------------------- | |
336 | ||
337 | .. kernel-doc:: include/drm/drm_plane.h | |
338 | :internal: | |
339 | ||
340 | .. kernel-doc:: drivers/gpu/drm/drm_plane.c | |
341 | :export: | |
342 | ||
311b62d9 DV |
343 | Display Modes Function Reference |
344 | ================================ | |
2fa91d15 | 345 | |
311b62d9 DV |
346 | .. kernel-doc:: include/drm/drm_modes.h |
347 | :internal: | |
348 | ||
349 | .. kernel-doc:: drivers/gpu/drm/drm_modes.c | |
350 | :export: | |
2fa91d15 | 351 | |
ae2a6da8 DV |
352 | Connector Abstraction |
353 | ===================== | |
354 | ||
355 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
356 | :doc: overview | |
357 | ||
358 | Connector Functions Reference | |
359 | ----------------------------- | |
52217195 DV |
360 | |
361 | .. kernel-doc:: include/drm/drm_connector.h | |
362 | :internal: | |
363 | ||
364 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
365 | :export: | |
366 | ||
321a95ae DV |
367 | Encoder Abstraction |
368 | =================== | |
369 | ||
e03e6de0 DV |
370 | .. kernel-doc:: drivers/gpu/drm/drm_encoder.c |
371 | :doc: overview | |
372 | ||
373 | Encoder Functions Reference | |
374 | --------------------------- | |
375 | ||
321a95ae DV |
376 | .. kernel-doc:: include/drm/drm_encoder.h |
377 | :internal: | |
378 | ||
379 | .. kernel-doc:: drivers/gpu/drm/drm_encoder.c | |
380 | :export: | |
381 | ||
2fa91d15 JN |
382 | KMS Initialization and Cleanup |
383 | ============================== | |
384 | ||
385 | A KMS device is abstracted and exposed as a set of planes, CRTCs, | |
386 | encoders and connectors. KMS drivers must thus create and initialize all | |
387 | those objects at load time after initializing mode setting. | |
388 | ||
389 | CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) | |
390 | -------------------------------------------- | |
391 | ||
392 | A CRTC is an abstraction representing a part of the chip that contains a | |
393 | pointer to a scanout buffer. Therefore, the number of CRTCs available | |
394 | determines how many independent scanout buffers can be active at any | |
395 | given time. The CRTC structure contains several fields to support this: | |
396 | a pointer to some video memory (abstracted as a frame buffer object), a | |
397 | display mode, and an (x, y) offset into the video memory to support | |
398 | panning or configurations where one piece of video memory spans multiple | |
399 | CRTCs. | |
400 | ||
401 | CRTC Initialization | |
402 | ~~~~~~~~~~~~~~~~~~~ | |
403 | ||
404 | A KMS device must create and register at least one struct | |
405 | :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is | |
406 | allocated and zeroed by the driver, possibly as part of a larger | |
407 | structure, and registered with a call to :c:func:`drm_crtc_init()` | |
408 | with a pointer to CRTC functions. | |
409 | ||
2fa91d15 | 410 | |
2fa91d15 JN |
411 | Cleanup |
412 | ------- | |
413 | ||
414 | The DRM core manages its objects' lifetime. When an object is not needed | |
415 | anymore the core calls its destroy function, which must clean up and | |
416 | free every resource allocated for the object. Every | |
417 | :c:func:`drm_\*_init()` call must be matched with a corresponding | |
418 | :c:func:`drm_\*_cleanup()` call to cleanup CRTCs | |
419 | (:c:func:`drm_crtc_cleanup()`), planes | |
420 | (:c:func:`drm_plane_cleanup()`), encoders | |
421 | (:c:func:`drm_encoder_cleanup()`) and connectors | |
422 | (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that | |
423 | have been added to sysfs must be removed by a call to | |
424 | :c:func:`drm_connector_unregister()` before calling | |
425 | :c:func:`drm_connector_cleanup()`. | |
426 | ||
427 | Connectors state change detection must be cleanup up with a call to | |
428 | :c:func:`drm_kms_helper_poll_fini()`. | |
429 | ||
430 | Output discovery and initialization example | |
431 | ------------------------------------------- | |
432 | ||
29849a69 | 433 | .. code-block:: c |
2fa91d15 JN |
434 | |
435 | void intel_crt_init(struct drm_device *dev) | |
436 | { | |
437 | struct drm_connector *connector; | |
438 | struct intel_output *intel_output; | |
439 | ||
440 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
441 | if (!intel_output) | |
442 | return; | |
443 | ||
444 | connector = &intel_output->base; | |
445 | drm_connector_init(dev, &intel_output->base, | |
446 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
447 | ||
448 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
449 | DRM_MODE_ENCODER_DAC); | |
450 | ||
451 | drm_mode_connector_attach_encoder(&intel_output->base, | |
452 | &intel_output->enc); | |
453 | ||
454 | /* Set up the DDC bus. */ | |
455 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
456 | if (!intel_output->ddc_bus) { | |
457 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
458 | "failed.\n"); | |
459 | return; | |
460 | } | |
461 | ||
462 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
463 | connector->interlace_allowed = 0; | |
464 | connector->doublescan_allowed = 0; | |
465 | ||
466 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
467 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
468 | ||
469 | drm_connector_register(connector); | |
470 | } | |
471 | ||
472 | In the example above (taken from the i915 driver), a CRTC, connector and | |
473 | encoder combination is created. A device-specific i2c bus is also | |
474 | created for fetching EDID data and performing monitor detection. Once | |
475 | the process is complete, the new connector is registered with sysfs to | |
476 | make its properties available to applications. | |
477 | ||
2fa91d15 | 478 | KMS Locking |
311b62d9 | 479 | =========== |
2fa91d15 JN |
480 | |
481 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
482 | :doc: kms locking | |
483 | ||
484 | .. kernel-doc:: include/drm/drm_modeset_lock.h | |
485 | :internal: | |
486 | ||
487 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
488 | :export: | |
489 | ||
490 | KMS Properties | |
491 | ============== | |
492 | ||
59e71ee7 DV |
493 | Property Types and Blob Property Support |
494 | ---------------------------------------- | |
495 | ||
c8458c7e DV |
496 | .. kernel-doc:: drivers/gpu/drm/drm_property.c |
497 | :doc: overview | |
498 | ||
59e71ee7 DV |
499 | .. kernel-doc:: include/drm/drm_property.h |
500 | :internal: | |
501 | ||
502 | .. kernel-doc:: drivers/gpu/drm/drm_property.c | |
503 | :export: | |
504 | ||
4ada6f22 DV |
505 | Standard Connector Properties |
506 | ----------------------------- | |
507 | ||
508 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
509 | :doc: standard connector properties | |
510 | ||
1e4d84c6 DV |
511 | Plane Composition Properties |
512 | ---------------------------- | |
513 | ||
514 | .. kernel-doc:: drivers/gpu/drm/drm_blend.c | |
515 | :doc: overview | |
52a9fcda DV |
516 | |
517 | .. kernel-doc:: drivers/gpu/drm/drm_blend.c | |
518 | :export: | |
519 | ||
a6acccf8 DV |
520 | Color Management Properties |
521 | --------------------------- | |
522 | ||
523 | .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c | |
524 | :doc: overview | |
525 | ||
526 | .. kernel-doc:: include/drm/drm_color_mgmt.h | |
527 | :internal: | |
528 | ||
529 | .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c | |
530 | :export: | |
531 | ||
9498c19b DV |
532 | Tile Group Property |
533 | ------------------- | |
534 | ||
535 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
536 | :doc: Tile group | |
537 | ||
9a83a71a GP |
538 | Explicit Fencing Properties |
539 | --------------------------- | |
540 | ||
541 | .. kernel-doc:: drivers/gpu/drm/drm_atomic.c | |
542 | :doc: explicit fencing properties | |
543 | ||
2fa91d15 JN |
544 | Existing KMS Properties |
545 | ----------------------- | |
546 | ||
547 | The following table gives description of drm properties exposed by | |
548 | various modules/drivers. | |
549 | ||
550 | .. csv-table:: | |
551 | :header-rows: 1 | |
552 | :file: kms-properties.csv | |
553 | ||
554 | Vertical Blanking | |
555 | ================= | |
556 | ||
557 | Vertical blanking plays a major role in graphics rendering. To achieve | |
558 | tear-free display, users must synchronize page flips and/or rendering to | |
559 | vertical blanking. The DRM API offers ioctls to perform page flips | |
560 | synchronized to vertical blanking and wait for vertical blanking. | |
561 | ||
562 | The DRM core handles most of the vertical blanking management logic, | |
563 | which involves filtering out spurious interrupts, keeping race-free | |
564 | blanking counters, coping with counter wrap-around and resets and | |
565 | keeping use counts. It relies on the driver to generate vertical | |
566 | blanking interrupts and optionally provide a hardware vertical blanking | |
567 | counter. Drivers must implement the following operations. | |
568 | ||
569 | - int (\*enable_vblank) (struct drm_device \*dev, int crtc); void | |
570 | (\*disable_vblank) (struct drm_device \*dev, int crtc); | |
571 | Enable or disable vertical blanking interrupts for the given CRTC. | |
572 | ||
573 | - u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); | |
574 | Retrieve the value of the vertical blanking counter for the given | |
575 | CRTC. If the hardware maintains a vertical blanking counter its value | |
576 | should be returned. Otherwise drivers can use the | |
577 | :c:func:`drm_vblank_count()` helper function to handle this | |
578 | operation. | |
579 | ||
580 | Drivers must initialize the vertical blanking handling core with a call | |
581 | to :c:func:`drm_vblank_init()` in their load operation. | |
582 | ||
583 | Vertical blanking interrupts can be enabled by the DRM core or by | |
584 | drivers themselves (for instance to handle page flipping operations). | |
585 | The DRM core maintains a vertical blanking use count to ensure that the | |
586 | interrupts are not disabled while a user still needs them. To increment | |
587 | the use count, drivers call :c:func:`drm_vblank_get()`. Upon | |
588 | return vertical blanking interrupts are guaranteed to be enabled. | |
589 | ||
590 | To decrement the use count drivers call | |
591 | :c:func:`drm_vblank_put()`. Only when the use count drops to zero | |
592 | will the DRM core disable the vertical blanking interrupts after a delay | |
593 | by scheduling a timer. The delay is accessible through the | |
594 | vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global | |
595 | variable and expressed in milliseconds. Its default value is 5000 ms. | |
596 | Zero means never disable, and a negative value means disable | |
597 | immediately. Drivers may override the behaviour by setting the | |
598 | :c:type:`struct drm_device <drm_device>` | |
599 | vblank_disable_immediate flag, which when set causes vblank interrupts | |
600 | to be disabled immediately regardless of the drm_vblank_offdelay | |
601 | value. The flag should only be set if there's a properly working | |
602 | hardware vblank counter present. | |
603 | ||
604 | When a vertical blanking interrupt occurs drivers only need to call the | |
605 | :c:func:`drm_handle_vblank()` function to account for the | |
606 | interrupt. | |
607 | ||
608 | Resources allocated by :c:func:`drm_vblank_init()` must be freed | |
609 | with a call to :c:func:`drm_vblank_cleanup()` in the driver unload | |
610 | operation handler. | |
611 | ||
612 | Vertical Blanking and Interrupt Handling Functions Reference | |
613 | ------------------------------------------------------------ | |
614 | ||
3ed4351a | 615 | .. kernel-doc:: include/drm/drm_vblank.h |
34a67dd7 | 616 | :internal: |
1ea35768 | 617 | |
3ed4351a | 618 | .. kernel-doc:: drivers/gpu/drm/drm_vblank.c |
1ea35768 | 619 | :export: |