]>
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 | ||
28575f16 | 18 | Mode Configuration |
949619f3 | 19 | |
28575f16 DV |
20 | KMS Core Structures and Functions |
21 | ================================= | |
949619f3 | 22 | |
28575f16 | 23 | .. kernel-doc:: drivers/gpu/drm/drm_mode_config.c |
949619f3 DV |
24 | :export: |
25 | ||
28575f16 | 26 | .. kernel-doc:: include/drm/drm_mode_config.h |
2fa91d15 JN |
27 | :internal: |
28 | ||
28575f16 DV |
29 | Modeset Base Object Abstraction |
30 | =============================== | |
311b62d9 | 31 | |
28575f16 DV |
32 | .. kernel-doc:: include/drm/drm_mode_object.h |
33 | :internal: | |
34 | ||
35 | .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c | |
2fa91d15 JN |
36 | :export: |
37 | ||
38 | Atomic Mode Setting Function Reference | |
311b62d9 | 39 | ====================================== |
2fa91d15 JN |
40 | |
41 | .. kernel-doc:: drivers/gpu/drm/drm_atomic.c | |
42 | :export: | |
43 | ||
5d070be6 | 44 | .. kernel-doc:: include/drm/drm_atomic.h |
2fa91d15 JN |
45 | :internal: |
46 | ||
28575f16 DV |
47 | CRTC Abstraction |
48 | ================ | |
49 | ||
50 | .. kernel-doc:: drivers/gpu/drm/drm_crtc.c | |
d5d487eb DV |
51 | :doc: overview |
52 | ||
53 | CRTC Functions Reference | |
54 | -------------------------------- | |
28575f16 DV |
55 | |
56 | .. kernel-doc:: include/drm/drm_crtc.h | |
57 | :internal: | |
58 | ||
d5d487eb DV |
59 | .. kernel-doc:: drivers/gpu/drm/drm_crtc.c |
60 | :export: | |
61 | ||
2fa91d15 | 62 | Frame Buffer Abstraction |
311b62d9 | 63 | ======================== |
2fa91d15 | 64 | |
750fb8c4 DV |
65 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c |
66 | :doc: overview | |
2fa91d15 | 67 | |
7520a277 DV |
68 | Frame Buffer Functions Reference |
69 | -------------------------------- | |
70 | ||
71 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c | |
72 | :export: | |
73 | ||
74 | .. kernel-doc:: include/drm/drm_framebuffer.h | |
75 | :internal: | |
76 | ||
2fa91d15 | 77 | DRM Format Handling |
311b62d9 | 78 | =================== |
2fa91d15 | 79 | |
84770cc2 LP |
80 | .. kernel-doc:: include/drm/drm_fourcc.h |
81 | :internal: | |
82 | ||
2fa91d15 JN |
83 | .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c |
84 | :export: | |
85 | ||
86 | Dumb Buffer Objects | |
311b62d9 | 87 | =================== |
2fa91d15 | 88 | |
4f93624e DV |
89 | .. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c |
90 | :doc: overview | |
2fa91d15 | 91 | |
43968d7b DV |
92 | Plane Abstraction |
93 | ================= | |
94 | ||
532b3671 DV |
95 | .. kernel-doc:: drivers/gpu/drm/drm_plane.c |
96 | :doc: overview | |
97 | ||
43968d7b DV |
98 | Plane Functions Reference |
99 | ------------------------- | |
100 | ||
101 | .. kernel-doc:: include/drm/drm_plane.h | |
102 | :internal: | |
103 | ||
104 | .. kernel-doc:: drivers/gpu/drm/drm_plane.c | |
105 | :export: | |
106 | ||
311b62d9 DV |
107 | Display Modes Function Reference |
108 | ================================ | |
2fa91d15 | 109 | |
311b62d9 DV |
110 | .. kernel-doc:: include/drm/drm_modes.h |
111 | :internal: | |
112 | ||
113 | .. kernel-doc:: drivers/gpu/drm/drm_modes.c | |
114 | :export: | |
2fa91d15 | 115 | |
ae2a6da8 DV |
116 | Connector Abstraction |
117 | ===================== | |
118 | ||
119 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
120 | :doc: overview | |
121 | ||
122 | Connector Functions Reference | |
123 | ----------------------------- | |
52217195 DV |
124 | |
125 | .. kernel-doc:: include/drm/drm_connector.h | |
126 | :internal: | |
127 | ||
128 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
129 | :export: | |
130 | ||
321a95ae DV |
131 | Encoder Abstraction |
132 | =================== | |
133 | ||
e03e6de0 DV |
134 | .. kernel-doc:: drivers/gpu/drm/drm_encoder.c |
135 | :doc: overview | |
136 | ||
137 | Encoder Functions Reference | |
138 | --------------------------- | |
139 | ||
321a95ae DV |
140 | .. kernel-doc:: include/drm/drm_encoder.h |
141 | :internal: | |
142 | ||
143 | .. kernel-doc:: drivers/gpu/drm/drm_encoder.c | |
144 | :export: | |
145 | ||
2fa91d15 JN |
146 | KMS Initialization and Cleanup |
147 | ============================== | |
148 | ||
149 | A KMS device is abstracted and exposed as a set of planes, CRTCs, | |
150 | encoders and connectors. KMS drivers must thus create and initialize all | |
151 | those objects at load time after initializing mode setting. | |
152 | ||
153 | CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) | |
154 | -------------------------------------------- | |
155 | ||
156 | A CRTC is an abstraction representing a part of the chip that contains a | |
157 | pointer to a scanout buffer. Therefore, the number of CRTCs available | |
158 | determines how many independent scanout buffers can be active at any | |
159 | given time. The CRTC structure contains several fields to support this: | |
160 | a pointer to some video memory (abstracted as a frame buffer object), a | |
161 | display mode, and an (x, y) offset into the video memory to support | |
162 | panning or configurations where one piece of video memory spans multiple | |
163 | CRTCs. | |
164 | ||
165 | CRTC Initialization | |
166 | ~~~~~~~~~~~~~~~~~~~ | |
167 | ||
168 | A KMS device must create and register at least one struct | |
169 | :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is | |
170 | allocated and zeroed by the driver, possibly as part of a larger | |
171 | structure, and registered with a call to :c:func:`drm_crtc_init()` | |
172 | with a pointer to CRTC functions. | |
173 | ||
2fa91d15 | 174 | |
2fa91d15 JN |
175 | Cleanup |
176 | ------- | |
177 | ||
178 | The DRM core manages its objects' lifetime. When an object is not needed | |
179 | anymore the core calls its destroy function, which must clean up and | |
180 | free every resource allocated for the object. Every | |
181 | :c:func:`drm_\*_init()` call must be matched with a corresponding | |
182 | :c:func:`drm_\*_cleanup()` call to cleanup CRTCs | |
183 | (:c:func:`drm_crtc_cleanup()`), planes | |
184 | (:c:func:`drm_plane_cleanup()`), encoders | |
185 | (:c:func:`drm_encoder_cleanup()`) and connectors | |
186 | (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that | |
187 | have been added to sysfs must be removed by a call to | |
188 | :c:func:`drm_connector_unregister()` before calling | |
189 | :c:func:`drm_connector_cleanup()`. | |
190 | ||
191 | Connectors state change detection must be cleanup up with a call to | |
192 | :c:func:`drm_kms_helper_poll_fini()`. | |
193 | ||
194 | Output discovery and initialization example | |
195 | ------------------------------------------- | |
196 | ||
29849a69 | 197 | .. code-block:: c |
2fa91d15 JN |
198 | |
199 | void intel_crt_init(struct drm_device *dev) | |
200 | { | |
201 | struct drm_connector *connector; | |
202 | struct intel_output *intel_output; | |
203 | ||
204 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
205 | if (!intel_output) | |
206 | return; | |
207 | ||
208 | connector = &intel_output->base; | |
209 | drm_connector_init(dev, &intel_output->base, | |
210 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
211 | ||
212 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
213 | DRM_MODE_ENCODER_DAC); | |
214 | ||
215 | drm_mode_connector_attach_encoder(&intel_output->base, | |
216 | &intel_output->enc); | |
217 | ||
218 | /* Set up the DDC bus. */ | |
219 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
220 | if (!intel_output->ddc_bus) { | |
221 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
222 | "failed.\n"); | |
223 | return; | |
224 | } | |
225 | ||
226 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
227 | connector->interlace_allowed = 0; | |
228 | connector->doublescan_allowed = 0; | |
229 | ||
230 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
231 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
232 | ||
233 | drm_connector_register(connector); | |
234 | } | |
235 | ||
236 | In the example above (taken from the i915 driver), a CRTC, connector and | |
237 | encoder combination is created. A device-specific i2c bus is also | |
238 | created for fetching EDID data and performing monitor detection. Once | |
239 | the process is complete, the new connector is registered with sysfs to | |
240 | make its properties available to applications. | |
241 | ||
2fa91d15 | 242 | KMS Locking |
311b62d9 | 243 | =========== |
2fa91d15 JN |
244 | |
245 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
246 | :doc: kms locking | |
247 | ||
248 | .. kernel-doc:: include/drm/drm_modeset_lock.h | |
249 | :internal: | |
250 | ||
251 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
252 | :export: | |
253 | ||
254 | KMS Properties | |
255 | ============== | |
256 | ||
59e71ee7 DV |
257 | Property Types and Blob Property Support |
258 | ---------------------------------------- | |
259 | ||
c8458c7e DV |
260 | .. kernel-doc:: drivers/gpu/drm/drm_property.c |
261 | :doc: overview | |
262 | ||
59e71ee7 DV |
263 | .. kernel-doc:: include/drm/drm_property.h |
264 | :internal: | |
265 | ||
266 | .. kernel-doc:: drivers/gpu/drm/drm_property.c | |
267 | :export: | |
268 | ||
4ada6f22 DV |
269 | Standard Connector Properties |
270 | ----------------------------- | |
271 | ||
272 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
273 | :doc: standard connector properties | |
274 | ||
1e4d84c6 DV |
275 | Plane Composition Properties |
276 | ---------------------------- | |
277 | ||
278 | .. kernel-doc:: drivers/gpu/drm/drm_blend.c | |
279 | :doc: overview | |
52a9fcda DV |
280 | |
281 | .. kernel-doc:: drivers/gpu/drm/drm_blend.c | |
282 | :export: | |
283 | ||
a6acccf8 DV |
284 | Color Management Properties |
285 | --------------------------- | |
286 | ||
287 | .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c | |
288 | :doc: overview | |
289 | ||
290 | .. kernel-doc:: include/drm/drm_color_mgmt.h | |
291 | :internal: | |
292 | ||
293 | .. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c | |
294 | :export: | |
295 | ||
9498c19b DV |
296 | Tile Group Property |
297 | ------------------- | |
298 | ||
299 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
300 | :doc: Tile group | |
301 | ||
9a83a71a GP |
302 | Explicit Fencing Properties |
303 | --------------------------- | |
304 | ||
305 | .. kernel-doc:: drivers/gpu/drm/drm_atomic.c | |
306 | :doc: explicit fencing properties | |
307 | ||
2fa91d15 JN |
308 | Existing KMS Properties |
309 | ----------------------- | |
310 | ||
311 | The following table gives description of drm properties exposed by | |
312 | various modules/drivers. | |
313 | ||
314 | .. csv-table:: | |
315 | :header-rows: 1 | |
316 | :file: kms-properties.csv | |
317 | ||
318 | Vertical Blanking | |
319 | ================= | |
320 | ||
321 | Vertical blanking plays a major role in graphics rendering. To achieve | |
322 | tear-free display, users must synchronize page flips and/or rendering to | |
323 | vertical blanking. The DRM API offers ioctls to perform page flips | |
324 | synchronized to vertical blanking and wait for vertical blanking. | |
325 | ||
326 | The DRM core handles most of the vertical blanking management logic, | |
327 | which involves filtering out spurious interrupts, keeping race-free | |
328 | blanking counters, coping with counter wrap-around and resets and | |
329 | keeping use counts. It relies on the driver to generate vertical | |
330 | blanking interrupts and optionally provide a hardware vertical blanking | |
331 | counter. Drivers must implement the following operations. | |
332 | ||
333 | - int (\*enable_vblank) (struct drm_device \*dev, int crtc); void | |
334 | (\*disable_vblank) (struct drm_device \*dev, int crtc); | |
335 | Enable or disable vertical blanking interrupts for the given CRTC. | |
336 | ||
337 | - u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); | |
338 | Retrieve the value of the vertical blanking counter for the given | |
339 | CRTC. If the hardware maintains a vertical blanking counter its value | |
340 | should be returned. Otherwise drivers can use the | |
341 | :c:func:`drm_vblank_count()` helper function to handle this | |
342 | operation. | |
343 | ||
344 | Drivers must initialize the vertical blanking handling core with a call | |
345 | to :c:func:`drm_vblank_init()` in their load operation. | |
346 | ||
347 | Vertical blanking interrupts can be enabled by the DRM core or by | |
348 | drivers themselves (for instance to handle page flipping operations). | |
349 | The DRM core maintains a vertical blanking use count to ensure that the | |
350 | interrupts are not disabled while a user still needs them. To increment | |
351 | the use count, drivers call :c:func:`drm_vblank_get()`. Upon | |
352 | return vertical blanking interrupts are guaranteed to be enabled. | |
353 | ||
354 | To decrement the use count drivers call | |
355 | :c:func:`drm_vblank_put()`. Only when the use count drops to zero | |
356 | will the DRM core disable the vertical blanking interrupts after a delay | |
357 | by scheduling a timer. The delay is accessible through the | |
358 | vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global | |
359 | variable and expressed in milliseconds. Its default value is 5000 ms. | |
360 | Zero means never disable, and a negative value means disable | |
361 | immediately. Drivers may override the behaviour by setting the | |
362 | :c:type:`struct drm_device <drm_device>` | |
363 | vblank_disable_immediate flag, which when set causes vblank interrupts | |
364 | to be disabled immediately regardless of the drm_vblank_offdelay | |
365 | value. The flag should only be set if there's a properly working | |
366 | hardware vblank counter present. | |
367 | ||
368 | When a vertical blanking interrupt occurs drivers only need to call the | |
369 | :c:func:`drm_handle_vblank()` function to account for the | |
370 | interrupt. | |
371 | ||
372 | Resources allocated by :c:func:`drm_vblank_init()` must be freed | |
373 | with a call to :c:func:`drm_vblank_cleanup()` in the driver unload | |
374 | operation handler. | |
375 | ||
376 | Vertical Blanking and Interrupt Handling Functions Reference | |
377 | ------------------------------------------------------------ | |
378 | ||
379 | .. kernel-doc:: drivers/gpu/drm/drm_irq.c | |
380 | :export: | |
381 | ||
34a67dd7 DV |
382 | .. kernel-doc:: include/drm/drm_irq.h |
383 | :internal: |