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 | ||
311b62d9 DV |
18 | KMS Data Structures |
19 | =================== | |
2fa91d15 | 20 | |
311b62d9 | 21 | .. kernel-doc:: include/drm/drm_crtc.h |
2fa91d15 JN |
22 | :internal: |
23 | ||
311b62d9 DV |
24 | KMS API Functions |
25 | ================= | |
26 | ||
27 | .. kernel-doc:: drivers/gpu/drm/drm_crtc.c | |
2fa91d15 JN |
28 | :export: |
29 | ||
30 | Atomic Mode Setting Function Reference | |
311b62d9 | 31 | ====================================== |
2fa91d15 JN |
32 | |
33 | .. kernel-doc:: drivers/gpu/drm/drm_atomic.c | |
34 | :export: | |
35 | ||
5d070be6 | 36 | .. kernel-doc:: include/drm/drm_atomic.h |
2fa91d15 JN |
37 | :internal: |
38 | ||
39 | Frame Buffer Abstraction | |
311b62d9 | 40 | ======================== |
2fa91d15 JN |
41 | |
42 | Frame buffers are abstract memory objects that provide a source of | |
43 | pixels to scanout to a CRTC. Applications explicitly request the | |
44 | creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls | |
45 | and receive an opaque handle that can be passed to the KMS CRTC control, | |
46 | plane configuration and page flip functions. | |
47 | ||
48 | Frame buffers rely on the underneath memory manager for low-level memory | |
49 | operations. When creating a frame buffer applications pass a memory | |
50 | handle (or a list of memory handles for multi-planar formats) through | |
51 | the ``drm_mode_fb_cmd2`` argument. For drivers using GEM as their | |
52 | userspace buffer management interface this would be a GEM handle. | |
53 | Drivers are however free to use their own backing storage object | |
54 | handles, e.g. vmwgfx directly exposes special TTM handles to userspace | |
55 | and so expects TTM handles in the create ioctl and not GEM handles. | |
56 | ||
57 | The lifetime of a drm framebuffer is controlled with a reference count, | |
58 | drivers can grab additional references with | |
59 | :c:func:`drm_framebuffer_reference()`and drop them again with | |
60 | :c:func:`drm_framebuffer_unreference()`. For driver-private | |
61 | framebuffers for which the last reference is never dropped (e.g. for the | |
62 | fbdev framebuffer when the struct :c:type:`struct drm_framebuffer | |
63 | <drm_framebuffer>` is embedded into the fbdev helper struct) | |
64 | drivers can manually clean up a framebuffer at module unload time with | |
65 | :c:func:`drm_framebuffer_unregister_private()`. | |
66 | ||
7520a277 DV |
67 | Frame Buffer Functions Reference |
68 | -------------------------------- | |
69 | ||
70 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c | |
71 | :export: | |
72 | ||
73 | .. kernel-doc:: include/drm/drm_framebuffer.h | |
74 | :internal: | |
75 | ||
2fa91d15 | 76 | DRM Format Handling |
311b62d9 | 77 | =================== |
2fa91d15 | 78 | |
2fa91d15 JN |
79 | .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c |
80 | :export: | |
81 | ||
82 | Dumb Buffer Objects | |
311b62d9 | 83 | =================== |
2fa91d15 JN |
84 | |
85 | The KMS API doesn't standardize backing storage object creation and | |
86 | leaves it to driver-specific ioctls. Furthermore actually creating a | |
87 | buffer object even for GEM-based drivers is done through a | |
88 | driver-specific ioctl - GEM only has a common userspace interface for | |
89 | sharing and destroying objects. While not an issue for full-fledged | |
90 | graphics stacks that include device-specific userspace components (in | |
91 | libdrm for instance), this limit makes DRM-based early boot graphics | |
92 | unnecessarily complex. | |
93 | ||
94 | Dumb objects partly alleviate the problem by providing a standard API to | |
95 | create dumb buffers suitable for scanout, which can then be used to | |
96 | create KMS frame buffers. | |
97 | ||
98 | To support dumb objects drivers must implement the dumb_create, | |
99 | dumb_destroy and dumb_map_offset operations. | |
100 | ||
101 | - int (\*dumb_create)(struct drm_file \*file_priv, struct | |
102 | drm_device \*dev, struct drm_mode_create_dumb \*args); | |
103 | The dumb_create operation creates a driver object (GEM or TTM | |
104 | handle) suitable for scanout based on the width, height and depth | |
105 | from the struct :c:type:`struct drm_mode_create_dumb | |
106 | <drm_mode_create_dumb>` argument. It fills the argument's | |
107 | handle, pitch and size fields with a handle for the newly created | |
108 | object and its line pitch and size in bytes. | |
109 | ||
110 | - int (\*dumb_destroy)(struct drm_file \*file_priv, struct | |
111 | drm_device \*dev, uint32_t handle); | |
112 | The dumb_destroy operation destroys a dumb object created by | |
113 | dumb_create. | |
114 | ||
115 | - int (\*dumb_map_offset)(struct drm_file \*file_priv, struct | |
116 | drm_device \*dev, uint32_t handle, uint64_t \*offset); | |
117 | The dumb_map_offset operation associates an mmap fake offset with | |
118 | the object given by the handle and returns it. Drivers must use the | |
119 | :c:func:`drm_gem_create_mmap_offset()` function to associate | |
120 | the fake offset as described in ?. | |
121 | ||
122 | Note that dumb objects may not be used for gpu acceleration, as has been | |
123 | attempted on some ARM embedded platforms. Such drivers really must have | |
124 | a hardware-specific ioctl to allocate suitable buffer objects. | |
125 | ||
311b62d9 DV |
126 | Display Modes Function Reference |
127 | ================================ | |
2fa91d15 | 128 | |
311b62d9 DV |
129 | .. kernel-doc:: include/drm/drm_modes.h |
130 | :internal: | |
131 | ||
132 | .. kernel-doc:: drivers/gpu/drm/drm_modes.c | |
133 | :export: | |
2fa91d15 JN |
134 | |
135 | KMS Initialization and Cleanup | |
136 | ============================== | |
137 | ||
138 | A KMS device is abstracted and exposed as a set of planes, CRTCs, | |
139 | encoders and connectors. KMS drivers must thus create and initialize all | |
140 | those objects at load time after initializing mode setting. | |
141 | ||
142 | CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) | |
143 | -------------------------------------------- | |
144 | ||
145 | A CRTC is an abstraction representing a part of the chip that contains a | |
146 | pointer to a scanout buffer. Therefore, the number of CRTCs available | |
147 | determines how many independent scanout buffers can be active at any | |
148 | given time. The CRTC structure contains several fields to support this: | |
149 | a pointer to some video memory (abstracted as a frame buffer object), a | |
150 | display mode, and an (x, y) offset into the video memory to support | |
151 | panning or configurations where one piece of video memory spans multiple | |
152 | CRTCs. | |
153 | ||
154 | CRTC Initialization | |
155 | ~~~~~~~~~~~~~~~~~~~ | |
156 | ||
157 | A KMS device must create and register at least one struct | |
158 | :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is | |
159 | allocated and zeroed by the driver, possibly as part of a larger | |
160 | structure, and registered with a call to :c:func:`drm_crtc_init()` | |
161 | with a pointer to CRTC functions. | |
162 | ||
163 | Planes (:c:type:`struct drm_plane <drm_plane>`) | |
164 | ----------------------------------------------- | |
165 | ||
166 | A plane represents an image source that can be blended with or overlayed | |
167 | on top of a CRTC during the scanout process. Planes are associated with | |
168 | a frame buffer to crop a portion of the image memory (source) and | |
169 | optionally scale it to a destination size. The result is then blended | |
170 | with or overlayed on top of a CRTC. | |
171 | ||
172 | The DRM core recognizes three types of planes: | |
173 | ||
174 | - DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. | |
175 | Primary planes are the planes operated upon by CRTC modesetting and | |
176 | flipping operations described in the page_flip hook in | |
177 | :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>`. | |
178 | - DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. | |
179 | Cursor planes are the planes operated upon by the | |
180 | DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 ioctls. | |
181 | - DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor | |
182 | planes. Some drivers refer to these types of planes as "sprites" | |
183 | internally. | |
184 | ||
185 | For compatibility with legacy userspace, only overlay planes are made | |
186 | available to userspace by default. Userspace clients may set the | |
187 | DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate | |
188 | that they wish to receive a universal plane list containing all plane | |
189 | types. | |
190 | ||
191 | Plane Initialization | |
192 | ~~~~~~~~~~~~~~~~~~~~ | |
193 | ||
194 | To create a plane, a KMS drivers allocates and zeroes an instances of | |
195 | :c:type:`struct drm_plane <drm_plane>` (possibly as part of a | |
196 | larger structure) and registers it with a call to | |
197 | :c:func:`drm_universal_plane_init()`. The function takes a | |
198 | bitmask of the CRTCs that can be associated with the plane, a pointer to | |
199 | the plane functions, a list of format supported formats, and the type of | |
200 | plane (primary, cursor, or overlay) being initialized. | |
201 | ||
202 | Cursor and overlay planes are optional. All drivers should provide one | |
203 | primary plane per CRTC (although this requirement may change in the | |
204 | future); drivers that do not wish to provide special handling for | |
205 | primary planes may make use of the helper functions described in ? to | |
206 | create and register a primary plane with standard capabilities. | |
207 | ||
208 | Encoders (:c:type:`struct drm_encoder <drm_encoder>`) | |
209 | ----------------------------------------------------- | |
210 | ||
211 | An encoder takes pixel data from a CRTC and converts it to a format | |
212 | suitable for any attached connectors. On some devices, it may be | |
213 | possible to have a CRTC send data to more than one encoder. In that | |
214 | case, both encoders would receive data from the same scanout buffer, | |
215 | resulting in a "cloned" display configuration across the connectors | |
216 | attached to each encoder. | |
217 | ||
218 | Encoder Initialization | |
219 | ~~~~~~~~~~~~~~~~~~~~~~ | |
220 | ||
221 | As for CRTCs, a KMS driver must create, initialize and register at least | |
222 | one :c:type:`struct drm_encoder <drm_encoder>` instance. The | |
223 | instance is allocated and zeroed by the driver, possibly as part of a | |
224 | larger structure. | |
225 | ||
226 | Drivers must initialize the :c:type:`struct drm_encoder | |
227 | <drm_encoder>` possible_crtcs and possible_clones fields before | |
228 | registering the encoder. Both fields are bitmasks of respectively the | |
229 | CRTCs that the encoder can be connected to, and sibling encoders | |
230 | candidate for cloning. | |
231 | ||
232 | After being initialized, the encoder must be registered with a call to | |
233 | :c:func:`drm_encoder_init()`. The function takes a pointer to the | |
234 | encoder functions and an encoder type. Supported types are | |
235 | ||
236 | - DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A | |
237 | - DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort | |
238 | - DRM_MODE_ENCODER_LVDS for display panels | |
239 | - DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, | |
240 | Component, SCART) | |
241 | - DRM_MODE_ENCODER_VIRTUAL for virtual machine displays | |
242 | ||
243 | Encoders must be attached to a CRTC to be used. DRM drivers leave | |
244 | encoders unattached at initialization time. Applications (or the fbdev | |
245 | compatibility layer when implemented) are responsible for attaching the | |
246 | encoders they want to use to a CRTC. | |
247 | ||
248 | Connectors (:c:type:`struct drm_connector <drm_connector>`) | |
249 | ----------------------------------------------------------- | |
250 | ||
251 | A connector is the final destination for pixel data on a device, and | |
252 | usually connects directly to an external display device like a monitor | |
253 | or laptop panel. A connector can only be attached to one encoder at a | |
254 | time. The connector is also the structure where information about the | |
255 | attached display is kept, so it contains fields for display data, EDID | |
256 | data, DPMS & connection status, and information about modes supported on | |
257 | the attached displays. | |
258 | ||
259 | Connector Initialization | |
260 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
261 | ||
262 | Finally a KMS driver must create, initialize, register and attach at | |
263 | least one :c:type:`struct drm_connector <drm_connector>` | |
264 | instance. The instance is created as other KMS objects and initialized | |
265 | by setting the following fields. | |
266 | ||
267 | interlace_allowed | |
268 | Whether the connector can handle interlaced modes. | |
269 | ||
270 | doublescan_allowed | |
271 | Whether the connector can handle doublescan. | |
272 | ||
273 | display_info | |
274 | Display information is filled from EDID information when a display | |
275 | is detected. For non hot-pluggable displays such as flat panels in | |
276 | embedded systems, the driver should initialize the | |
277 | display_info.width_mm and display_info.height_mm fields with the | |
278 | physical size of the display. | |
279 | ||
280 | polled | |
281 | Connector polling mode, a combination of | |
282 | ||
283 | DRM_CONNECTOR_POLL_HPD | |
284 | The connector generates hotplug events and doesn't need to be | |
285 | periodically polled. The CONNECT and DISCONNECT flags must not | |
286 | be set together with the HPD flag. | |
287 | ||
288 | DRM_CONNECTOR_POLL_CONNECT | |
289 | Periodically poll the connector for connection. | |
290 | ||
291 | DRM_CONNECTOR_POLL_DISCONNECT | |
292 | Periodically poll the connector for disconnection. | |
293 | ||
294 | Set to 0 for connectors that don't support connection status | |
295 | discovery. | |
296 | ||
297 | The connector is then registered with a call to | |
298 | :c:func:`drm_connector_init()` with a pointer to the connector | |
299 | functions and a connector type, and exposed through sysfs with a call to | |
300 | :c:func:`drm_connector_register()`. | |
301 | ||
302 | Supported connector types are | |
303 | ||
304 | - DRM_MODE_CONNECTOR_VGA | |
305 | - DRM_MODE_CONNECTOR_DVII | |
306 | - DRM_MODE_CONNECTOR_DVID | |
307 | - DRM_MODE_CONNECTOR_DVIA | |
308 | - DRM_MODE_CONNECTOR_Composite | |
309 | - DRM_MODE_CONNECTOR_SVIDEO | |
310 | - DRM_MODE_CONNECTOR_LVDS | |
311 | - DRM_MODE_CONNECTOR_Component | |
312 | - DRM_MODE_CONNECTOR_9PinDIN | |
313 | - DRM_MODE_CONNECTOR_DisplayPort | |
314 | - DRM_MODE_CONNECTOR_HDMIA | |
315 | - DRM_MODE_CONNECTOR_HDMIB | |
316 | - DRM_MODE_CONNECTOR_TV | |
317 | - DRM_MODE_CONNECTOR_eDP | |
318 | - DRM_MODE_CONNECTOR_VIRTUAL | |
319 | ||
320 | Connectors must be attached to an encoder to be used. For devices that | |
321 | map connectors to encoders 1:1, the connector should be attached at | |
322 | initialization time with a call to | |
323 | :c:func:`drm_mode_connector_attach_encoder()`. The driver must | |
324 | also set the :c:type:`struct drm_connector <drm_connector>` | |
325 | encoder field to point to the attached encoder. | |
326 | ||
327 | Finally, drivers must initialize the connectors state change detection | |
328 | with a call to :c:func:`drm_kms_helper_poll_init()`. If at least | |
329 | one connector is pollable but can't generate hotplug interrupts | |
330 | (indicated by the DRM_CONNECTOR_POLL_CONNECT and | |
331 | DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will | |
332 | automatically be queued to periodically poll for changes. Connectors | |
333 | that can generate hotplug interrupts must be marked with the | |
334 | DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must | |
335 | call :c:func:`drm_helper_hpd_irq_event()`. The function will | |
336 | queue a delayed work to check the state of all connectors, but no | |
337 | periodic polling will be done. | |
338 | ||
339 | Connector Operations | |
340 | ~~~~~~~~~~~~~~~~~~~~ | |
341 | ||
342 | **Note** | |
343 | ||
344 | Unless otherwise state, all operations are mandatory. | |
345 | ||
346 | DPMS | |
347 | '''' | |
348 | ||
349 | void (\*dpms)(struct drm_connector \*connector, int mode); | |
350 | The DPMS operation sets the power state of a connector. The mode | |
351 | argument is one of | |
352 | ||
353 | - DRM_MODE_DPMS_ON | |
354 | ||
355 | - DRM_MODE_DPMS_STANDBY | |
356 | ||
357 | - DRM_MODE_DPMS_SUSPEND | |
358 | ||
359 | - DRM_MODE_DPMS_OFF | |
360 | ||
361 | In all but DPMS_ON mode the encoder to which the connector is attached | |
362 | should put the display in low-power mode by driving its signals | |
363 | appropriately. If more than one connector is attached to the encoder | |
364 | care should be taken not to change the power state of other displays as | |
365 | a side effect. Low-power mode should be propagated to the encoders and | |
366 | CRTCs when all related connectors are put in low-power mode. | |
367 | ||
368 | Modes | |
369 | ''''' | |
370 | ||
371 | int (\*fill_modes)(struct drm_connector \*connector, uint32_t | |
372 | max_width, uint32_t max_height); | |
373 | Fill the mode list with all supported modes for the connector. If the | |
374 | ``max_width`` and ``max_height`` arguments are non-zero, the | |
375 | implementation must ignore all modes wider than ``max_width`` or higher | |
376 | than ``max_height``. | |
377 | ||
378 | The connector must also fill in this operation its display_info | |
379 | width_mm and height_mm fields with the connected display physical size | |
380 | in millimeters. The fields should be set to 0 if the value isn't known | |
381 | or is not applicable (for instance for projector devices). | |
382 | ||
383 | Connection Status | |
384 | ''''''''''''''''' | |
385 | ||
386 | The connection status is updated through polling or hotplug events when | |
387 | supported (see ?). The status value is reported to userspace through | |
388 | ioctls and must not be used inside the driver, as it only gets | |
389 | initialized by a call to :c:func:`drm_mode_getconnector()` from | |
390 | userspace. | |
391 | ||
392 | enum drm_connector_status (\*detect)(struct drm_connector | |
393 | \*connector, bool force); | |
394 | Check to see if anything is attached to the connector. The ``force`` | |
395 | parameter is set to false whilst polling or to true when checking the | |
396 | connector due to user request. ``force`` can be used by the driver to | |
397 | avoid expensive, destructive operations during automated probing. | |
398 | ||
399 | Return connector_status_connected if something is connected to the | |
400 | connector, connector_status_disconnected if nothing is connected and | |
401 | connector_status_unknown if the connection state isn't known. | |
402 | ||
403 | Drivers should only return connector_status_connected if the | |
404 | connection status has really been probed as connected. Connectors that | |
405 | can't detect the connection status, or failed connection status probes, | |
406 | should return connector_status_unknown. | |
407 | ||
408 | Cleanup | |
409 | ------- | |
410 | ||
411 | The DRM core manages its objects' lifetime. When an object is not needed | |
412 | anymore the core calls its destroy function, which must clean up and | |
413 | free every resource allocated for the object. Every | |
414 | :c:func:`drm_\*_init()` call must be matched with a corresponding | |
415 | :c:func:`drm_\*_cleanup()` call to cleanup CRTCs | |
416 | (:c:func:`drm_crtc_cleanup()`), planes | |
417 | (:c:func:`drm_plane_cleanup()`), encoders | |
418 | (:c:func:`drm_encoder_cleanup()`) and connectors | |
419 | (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that | |
420 | have been added to sysfs must be removed by a call to | |
421 | :c:func:`drm_connector_unregister()` before calling | |
422 | :c:func:`drm_connector_cleanup()`. | |
423 | ||
424 | Connectors state change detection must be cleanup up with a call to | |
425 | :c:func:`drm_kms_helper_poll_fini()`. | |
426 | ||
427 | Output discovery and initialization example | |
428 | ------------------------------------------- | |
429 | ||
430 | :: | |
431 | ||
432 | void intel_crt_init(struct drm_device *dev) | |
433 | { | |
434 | struct drm_connector *connector; | |
435 | struct intel_output *intel_output; | |
436 | ||
437 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
438 | if (!intel_output) | |
439 | return; | |
440 | ||
441 | connector = &intel_output->base; | |
442 | drm_connector_init(dev, &intel_output->base, | |
443 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
444 | ||
445 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
446 | DRM_MODE_ENCODER_DAC); | |
447 | ||
448 | drm_mode_connector_attach_encoder(&intel_output->base, | |
449 | &intel_output->enc); | |
450 | ||
451 | /* Set up the DDC bus. */ | |
452 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
453 | if (!intel_output->ddc_bus) { | |
454 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
455 | "failed.\n"); | |
456 | return; | |
457 | } | |
458 | ||
459 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
460 | connector->interlace_allowed = 0; | |
461 | connector->doublescan_allowed = 0; | |
462 | ||
463 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
464 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
465 | ||
466 | drm_connector_register(connector); | |
467 | } | |
468 | ||
469 | In the example above (taken from the i915 driver), a CRTC, connector and | |
470 | encoder combination is created. A device-specific i2c bus is also | |
471 | created for fetching EDID data and performing monitor detection. Once | |
472 | the process is complete, the new connector is registered with sysfs to | |
473 | make its properties available to applications. | |
474 | ||
2fa91d15 | 475 | KMS Locking |
311b62d9 | 476 | =========== |
2fa91d15 JN |
477 | |
478 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
479 | :doc: kms locking | |
480 | ||
481 | .. kernel-doc:: include/drm/drm_modeset_lock.h | |
482 | :internal: | |
483 | ||
484 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
485 | :export: | |
486 | ||
487 | KMS Properties | |
488 | ============== | |
489 | ||
490 | Drivers may need to expose additional parameters to applications than | |
491 | those described in the previous sections. KMS supports attaching | |
492 | properties to CRTCs, connectors and planes and offers a userspace API to | |
493 | list, get and set the property values. | |
494 | ||
495 | Properties are identified by a name that uniquely defines the property | |
496 | purpose, and store an associated value. For all property types except | |
497 | blob properties the value is a 64-bit unsigned integer. | |
498 | ||
499 | KMS differentiates between properties and property instances. Drivers | |
500 | first create properties and then create and associate individual | |
501 | instances of those properties to objects. A property can be instantiated | |
502 | multiple times and associated with different objects. Values are stored | |
503 | in property instances, and all other property information are stored in | |
504 | the property and shared between all instances of the property. | |
505 | ||
506 | Every property is created with a type that influences how the KMS core | |
507 | handles the property. Supported property types are | |
508 | ||
509 | DRM_MODE_PROP_RANGE | |
510 | Range properties report their minimum and maximum admissible values. | |
511 | The KMS core verifies that values set by application fit in that | |
512 | range. | |
513 | ||
514 | DRM_MODE_PROP_ENUM | |
515 | Enumerated properties take a numerical value that ranges from 0 to | |
516 | the number of enumerated values defined by the property minus one, | |
517 | and associate a free-formed string name to each value. Applications | |
518 | can retrieve the list of defined value-name pairs and use the | |
519 | numerical value to get and set property instance values. | |
520 | ||
521 | DRM_MODE_PROP_BITMASK | |
522 | Bitmask properties are enumeration properties that additionally | |
523 | restrict all enumerated values to the 0..63 range. Bitmask property | |
524 | instance values combine one or more of the enumerated bits defined | |
525 | by the property. | |
526 | ||
527 | DRM_MODE_PROP_BLOB | |
528 | Blob properties store a binary blob without any format restriction. | |
529 | The binary blobs are created as KMS standalone objects, and blob | |
530 | property instance values store the ID of their associated blob | |
531 | object. | |
532 | ||
533 | Blob properties are only used for the connector EDID property and | |
534 | cannot be created by drivers. | |
535 | ||
536 | To create a property drivers call one of the following functions | |
537 | depending on the property type. All property creation functions take | |
538 | property flags and name, as well as type-specific arguments. | |
539 | ||
540 | - struct drm_property \*drm_property_create_range(struct | |
541 | drm_device \*dev, int flags, const char \*name, uint64_t min, | |
542 | uint64_t max); | |
543 | Create a range property with the given minimum and maximum values. | |
544 | ||
545 | - struct drm_property \*drm_property_create_enum(struct drm_device | |
546 | \*dev, int flags, const char \*name, const struct | |
547 | drm_prop_enum_list \*props, int num_values); | |
548 | Create an enumerated property. The ``props`` argument points to an | |
549 | array of ``num_values`` value-name pairs. | |
550 | ||
551 | - struct drm_property \*drm_property_create_bitmask(struct | |
552 | drm_device \*dev, int flags, const char \*name, const struct | |
553 | drm_prop_enum_list \*props, int num_values); | |
554 | Create a bitmask property. The ``props`` argument points to an array | |
555 | of ``num_values`` value-name pairs. | |
556 | ||
557 | Properties can additionally be created as immutable, in which case they | |
558 | will be read-only for applications but can be modified by the driver. To | |
559 | create an immutable property drivers must set the | |
560 | DRM_MODE_PROP_IMMUTABLE flag at property creation time. | |
561 | ||
562 | When no array of value-name pairs is readily available at property | |
563 | creation time for enumerated or range properties, drivers can create the | |
564 | property using the :c:func:`drm_property_create()` function and | |
565 | manually add enumeration value-name pairs by calling the | |
566 | :c:func:`drm_property_add_enum()` function. Care must be taken to | |
567 | properly specify the property type through the ``flags`` argument. | |
568 | ||
569 | After creating properties drivers can attach property instances to CRTC, | |
570 | connector and plane objects by calling the | |
571 | :c:func:`drm_object_attach_property()`. The function takes a | |
572 | pointer to the target object, a pointer to the previously created | |
573 | property and an initial instance value. | |
574 | ||
575 | Existing KMS Properties | |
576 | ----------------------- | |
577 | ||
578 | The following table gives description of drm properties exposed by | |
579 | various modules/drivers. | |
580 | ||
581 | .. csv-table:: | |
582 | :header-rows: 1 | |
583 | :file: kms-properties.csv | |
584 | ||
585 | Vertical Blanking | |
586 | ================= | |
587 | ||
588 | Vertical blanking plays a major role in graphics rendering. To achieve | |
589 | tear-free display, users must synchronize page flips and/or rendering to | |
590 | vertical blanking. The DRM API offers ioctls to perform page flips | |
591 | synchronized to vertical blanking and wait for vertical blanking. | |
592 | ||
593 | The DRM core handles most of the vertical blanking management logic, | |
594 | which involves filtering out spurious interrupts, keeping race-free | |
595 | blanking counters, coping with counter wrap-around and resets and | |
596 | keeping use counts. It relies on the driver to generate vertical | |
597 | blanking interrupts and optionally provide a hardware vertical blanking | |
598 | counter. Drivers must implement the following operations. | |
599 | ||
600 | - int (\*enable_vblank) (struct drm_device \*dev, int crtc); void | |
601 | (\*disable_vblank) (struct drm_device \*dev, int crtc); | |
602 | Enable or disable vertical blanking interrupts for the given CRTC. | |
603 | ||
604 | - u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); | |
605 | Retrieve the value of the vertical blanking counter for the given | |
606 | CRTC. If the hardware maintains a vertical blanking counter its value | |
607 | should be returned. Otherwise drivers can use the | |
608 | :c:func:`drm_vblank_count()` helper function to handle this | |
609 | operation. | |
610 | ||
611 | Drivers must initialize the vertical blanking handling core with a call | |
612 | to :c:func:`drm_vblank_init()` in their load operation. | |
613 | ||
614 | Vertical blanking interrupts can be enabled by the DRM core or by | |
615 | drivers themselves (for instance to handle page flipping operations). | |
616 | The DRM core maintains a vertical blanking use count to ensure that the | |
617 | interrupts are not disabled while a user still needs them. To increment | |
618 | the use count, drivers call :c:func:`drm_vblank_get()`. Upon | |
619 | return vertical blanking interrupts are guaranteed to be enabled. | |
620 | ||
621 | To decrement the use count drivers call | |
622 | :c:func:`drm_vblank_put()`. Only when the use count drops to zero | |
623 | will the DRM core disable the vertical blanking interrupts after a delay | |
624 | by scheduling a timer. The delay is accessible through the | |
625 | vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global | |
626 | variable and expressed in milliseconds. Its default value is 5000 ms. | |
627 | Zero means never disable, and a negative value means disable | |
628 | immediately. Drivers may override the behaviour by setting the | |
629 | :c:type:`struct drm_device <drm_device>` | |
630 | vblank_disable_immediate flag, which when set causes vblank interrupts | |
631 | to be disabled immediately regardless of the drm_vblank_offdelay | |
632 | value. The flag should only be set if there's a properly working | |
633 | hardware vblank counter present. | |
634 | ||
635 | When a vertical blanking interrupt occurs drivers only need to call the | |
636 | :c:func:`drm_handle_vblank()` function to account for the | |
637 | interrupt. | |
638 | ||
639 | Resources allocated by :c:func:`drm_vblank_init()` must be freed | |
640 | with a call to :c:func:`drm_vblank_cleanup()` in the driver unload | |
641 | operation handler. | |
642 | ||
643 | Vertical Blanking and Interrupt Handling Functions Reference | |
644 | ------------------------------------------------------------ | |
645 | ||
646 | .. kernel-doc:: drivers/gpu/drm/drm_irq.c | |
647 | :export: | |
648 | ||
34a67dd7 DV |
649 | .. kernel-doc:: include/drm/drm_irq.h |
650 | :internal: |