]>
Commit | Line | Data |
---|---|---|
1 | ========================= | |
2 | Kernel Mode Setting (KMS) | |
3 | ========================= | |
4 | ||
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 | ||
18 | Modeset Base Object Abstraction | |
19 | =============================== | |
20 | ||
21 | .. kernel-doc:: include/drm/drm_mode_object.h | |
22 | :internal: | |
23 | ||
24 | .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c | |
25 | :export: | |
26 | ||
27 | KMS Data Structures | |
28 | =================== | |
29 | ||
30 | .. kernel-doc:: include/drm/drm_crtc.h | |
31 | :internal: | |
32 | ||
33 | KMS API Functions | |
34 | ================= | |
35 | ||
36 | .. kernel-doc:: drivers/gpu/drm/drm_crtc.c | |
37 | :export: | |
38 | ||
39 | Atomic Mode Setting Function Reference | |
40 | ====================================== | |
41 | ||
42 | .. kernel-doc:: drivers/gpu/drm/drm_atomic.c | |
43 | :export: | |
44 | ||
45 | .. kernel-doc:: include/drm/drm_atomic.h | |
46 | :internal: | |
47 | ||
48 | Frame Buffer Abstraction | |
49 | ======================== | |
50 | ||
51 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c | |
52 | :doc: overview | |
53 | ||
54 | Frame Buffer Functions Reference | |
55 | -------------------------------- | |
56 | ||
57 | .. kernel-doc:: drivers/gpu/drm/drm_framebuffer.c | |
58 | :export: | |
59 | ||
60 | .. kernel-doc:: include/drm/drm_framebuffer.h | |
61 | :internal: | |
62 | ||
63 | DRM Format Handling | |
64 | =================== | |
65 | ||
66 | .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c | |
67 | :export: | |
68 | ||
69 | Dumb Buffer Objects | |
70 | =================== | |
71 | ||
72 | The KMS API doesn't standardize backing storage object creation and | |
73 | leaves it to driver-specific ioctls. Furthermore actually creating a | |
74 | buffer object even for GEM-based drivers is done through a | |
75 | driver-specific ioctl - GEM only has a common userspace interface for | |
76 | sharing and destroying objects. While not an issue for full-fledged | |
77 | graphics stacks that include device-specific userspace components (in | |
78 | libdrm for instance), this limit makes DRM-based early boot graphics | |
79 | unnecessarily complex. | |
80 | ||
81 | Dumb objects partly alleviate the problem by providing a standard API to | |
82 | create dumb buffers suitable for scanout, which can then be used to | |
83 | create KMS frame buffers. | |
84 | ||
85 | To support dumb objects drivers must implement the dumb_create, | |
86 | dumb_destroy and dumb_map_offset operations. | |
87 | ||
88 | - int (\*dumb_create)(struct drm_file \*file_priv, struct | |
89 | drm_device \*dev, struct drm_mode_create_dumb \*args); | |
90 | The dumb_create operation creates a driver object (GEM or TTM | |
91 | handle) suitable for scanout based on the width, height and depth | |
92 | from the struct :c:type:`struct drm_mode_create_dumb | |
93 | <drm_mode_create_dumb>` argument. It fills the argument's | |
94 | handle, pitch and size fields with a handle for the newly created | |
95 | object and its line pitch and size in bytes. | |
96 | ||
97 | - int (\*dumb_destroy)(struct drm_file \*file_priv, struct | |
98 | drm_device \*dev, uint32_t handle); | |
99 | The dumb_destroy operation destroys a dumb object created by | |
100 | dumb_create. | |
101 | ||
102 | - int (\*dumb_map_offset)(struct drm_file \*file_priv, struct | |
103 | drm_device \*dev, uint32_t handle, uint64_t \*offset); | |
104 | The dumb_map_offset operation associates an mmap fake offset with | |
105 | the object given by the handle and returns it. Drivers must use the | |
106 | :c:func:`drm_gem_create_mmap_offset()` function to associate | |
107 | the fake offset as described in ?. | |
108 | ||
109 | Note that dumb objects may not be used for gpu acceleration, as has been | |
110 | attempted on some ARM embedded platforms. Such drivers really must have | |
111 | a hardware-specific ioctl to allocate suitable buffer objects. | |
112 | ||
113 | Display Modes Function Reference | |
114 | ================================ | |
115 | ||
116 | .. kernel-doc:: include/drm/drm_modes.h | |
117 | :internal: | |
118 | ||
119 | .. kernel-doc:: drivers/gpu/drm/drm_modes.c | |
120 | :export: | |
121 | ||
122 | Connector Abstraction | |
123 | ===================== | |
124 | ||
125 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
126 | :doc: overview | |
127 | ||
128 | Connector Functions Reference | |
129 | ----------------------------- | |
130 | ||
131 | .. kernel-doc:: include/drm/drm_connector.h | |
132 | :internal: | |
133 | ||
134 | .. kernel-doc:: drivers/gpu/drm/drm_connector.c | |
135 | :export: | |
136 | ||
137 | Encoder Abstraction | |
138 | =================== | |
139 | ||
140 | .. kernel-doc:: drivers/gpu/drm/drm_encoder.c | |
141 | :doc: overview | |
142 | ||
143 | Encoder Functions Reference | |
144 | --------------------------- | |
145 | ||
146 | .. kernel-doc:: include/drm/drm_encoder.h | |
147 | :internal: | |
148 | ||
149 | .. kernel-doc:: drivers/gpu/drm/drm_encoder.c | |
150 | :export: | |
151 | ||
152 | KMS Initialization and Cleanup | |
153 | ============================== | |
154 | ||
155 | A KMS device is abstracted and exposed as a set of planes, CRTCs, | |
156 | encoders and connectors. KMS drivers must thus create and initialize all | |
157 | those objects at load time after initializing mode setting. | |
158 | ||
159 | CRTCs (:c:type:`struct drm_crtc <drm_crtc>`) | |
160 | -------------------------------------------- | |
161 | ||
162 | A CRTC is an abstraction representing a part of the chip that contains a | |
163 | pointer to a scanout buffer. Therefore, the number of CRTCs available | |
164 | determines how many independent scanout buffers can be active at any | |
165 | given time. The CRTC structure contains several fields to support this: | |
166 | a pointer to some video memory (abstracted as a frame buffer object), a | |
167 | display mode, and an (x, y) offset into the video memory to support | |
168 | panning or configurations where one piece of video memory spans multiple | |
169 | CRTCs. | |
170 | ||
171 | CRTC Initialization | |
172 | ~~~~~~~~~~~~~~~~~~~ | |
173 | ||
174 | A KMS device must create and register at least one struct | |
175 | :c:type:`struct drm_crtc <drm_crtc>` instance. The instance is | |
176 | allocated and zeroed by the driver, possibly as part of a larger | |
177 | structure, and registered with a call to :c:func:`drm_crtc_init()` | |
178 | with a pointer to CRTC functions. | |
179 | ||
180 | Planes (:c:type:`struct drm_plane <drm_plane>`) | |
181 | ----------------------------------------------- | |
182 | ||
183 | A plane represents an image source that can be blended with or overlayed | |
184 | on top of a CRTC during the scanout process. Planes are associated with | |
185 | a frame buffer to crop a portion of the image memory (source) and | |
186 | optionally scale it to a destination size. The result is then blended | |
187 | with or overlayed on top of a CRTC. | |
188 | ||
189 | The DRM core recognizes three types of planes: | |
190 | ||
191 | - DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. | |
192 | Primary planes are the planes operated upon by CRTC modesetting and | |
193 | flipping operations described in the page_flip hook in | |
194 | :c:type:`struct drm_crtc_funcs <drm_crtc_funcs>`. | |
195 | - DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. | |
196 | Cursor planes are the planes operated upon by the | |
197 | DRM_IOCTL_MODE_CURSOR and DRM_IOCTL_MODE_CURSOR2 ioctls. | |
198 | - DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor | |
199 | planes. Some drivers refer to these types of planes as "sprites" | |
200 | internally. | |
201 | ||
202 | For compatibility with legacy userspace, only overlay planes are made | |
203 | available to userspace by default. Userspace clients may set the | |
204 | DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate | |
205 | that they wish to receive a universal plane list containing all plane | |
206 | types. | |
207 | ||
208 | Plane Initialization | |
209 | ~~~~~~~~~~~~~~~~~~~~ | |
210 | ||
211 | To create a plane, a KMS drivers allocates and zeroes an instances of | |
212 | :c:type:`struct drm_plane <drm_plane>` (possibly as part of a | |
213 | larger structure) and registers it with a call to | |
214 | :c:func:`drm_universal_plane_init()`. The function takes a | |
215 | bitmask of the CRTCs that can be associated with the plane, a pointer to | |
216 | the plane functions, a list of format supported formats, and the type of | |
217 | plane (primary, cursor, or overlay) being initialized. | |
218 | ||
219 | Cursor and overlay planes are optional. All drivers should provide one | |
220 | primary plane per CRTC (although this requirement may change in the | |
221 | future); drivers that do not wish to provide special handling for | |
222 | primary planes may make use of the helper functions described in ? to | |
223 | create and register a primary plane with standard capabilities. | |
224 | ||
225 | Cleanup | |
226 | ------- | |
227 | ||
228 | The DRM core manages its objects' lifetime. When an object is not needed | |
229 | anymore the core calls its destroy function, which must clean up and | |
230 | free every resource allocated for the object. Every | |
231 | :c:func:`drm_\*_init()` call must be matched with a corresponding | |
232 | :c:func:`drm_\*_cleanup()` call to cleanup CRTCs | |
233 | (:c:func:`drm_crtc_cleanup()`), planes | |
234 | (:c:func:`drm_plane_cleanup()`), encoders | |
235 | (:c:func:`drm_encoder_cleanup()`) and connectors | |
236 | (:c:func:`drm_connector_cleanup()`). Furthermore, connectors that | |
237 | have been added to sysfs must be removed by a call to | |
238 | :c:func:`drm_connector_unregister()` before calling | |
239 | :c:func:`drm_connector_cleanup()`. | |
240 | ||
241 | Connectors state change detection must be cleanup up with a call to | |
242 | :c:func:`drm_kms_helper_poll_fini()`. | |
243 | ||
244 | Output discovery and initialization example | |
245 | ------------------------------------------- | |
246 | ||
247 | :: | |
248 | ||
249 | void intel_crt_init(struct drm_device *dev) | |
250 | { | |
251 | struct drm_connector *connector; | |
252 | struct intel_output *intel_output; | |
253 | ||
254 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
255 | if (!intel_output) | |
256 | return; | |
257 | ||
258 | connector = &intel_output->base; | |
259 | drm_connector_init(dev, &intel_output->base, | |
260 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
261 | ||
262 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
263 | DRM_MODE_ENCODER_DAC); | |
264 | ||
265 | drm_mode_connector_attach_encoder(&intel_output->base, | |
266 | &intel_output->enc); | |
267 | ||
268 | /* Set up the DDC bus. */ | |
269 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
270 | if (!intel_output->ddc_bus) { | |
271 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
272 | "failed.\n"); | |
273 | return; | |
274 | } | |
275 | ||
276 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
277 | connector->interlace_allowed = 0; | |
278 | connector->doublescan_allowed = 0; | |
279 | ||
280 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
281 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
282 | ||
283 | drm_connector_register(connector); | |
284 | } | |
285 | ||
286 | In the example above (taken from the i915 driver), a CRTC, connector and | |
287 | encoder combination is created. A device-specific i2c bus is also | |
288 | created for fetching EDID data and performing monitor detection. Once | |
289 | the process is complete, the new connector is registered with sysfs to | |
290 | make its properties available to applications. | |
291 | ||
292 | KMS Locking | |
293 | =========== | |
294 | ||
295 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
296 | :doc: kms locking | |
297 | ||
298 | .. kernel-doc:: include/drm/drm_modeset_lock.h | |
299 | :internal: | |
300 | ||
301 | .. kernel-doc:: drivers/gpu/drm/drm_modeset_lock.c | |
302 | :export: | |
303 | ||
304 | KMS Properties | |
305 | ============== | |
306 | ||
307 | Property Types and Blob Property Support | |
308 | ---------------------------------------- | |
309 | ||
310 | .. kernel-doc:: drivers/gpu/drm/drm_property.c | |
311 | :doc: overview | |
312 | ||
313 | .. kernel-doc:: include/drm/drm_property.h | |
314 | :internal: | |
315 | ||
316 | .. kernel-doc:: drivers/gpu/drm/drm_property.c | |
317 | :export: | |
318 | ||
319 | Blending and Z-Position properties | |
320 | ---------------------------------- | |
321 | ||
322 | .. kernel-doc:: drivers/gpu/drm/drm_blend.c | |
323 | :export: | |
324 | ||
325 | Existing KMS Properties | |
326 | ----------------------- | |
327 | ||
328 | The following table gives description of drm properties exposed by | |
329 | various modules/drivers. | |
330 | ||
331 | .. csv-table:: | |
332 | :header-rows: 1 | |
333 | :file: kms-properties.csv | |
334 | ||
335 | Vertical Blanking | |
336 | ================= | |
337 | ||
338 | Vertical blanking plays a major role in graphics rendering. To achieve | |
339 | tear-free display, users must synchronize page flips and/or rendering to | |
340 | vertical blanking. The DRM API offers ioctls to perform page flips | |
341 | synchronized to vertical blanking and wait for vertical blanking. | |
342 | ||
343 | The DRM core handles most of the vertical blanking management logic, | |
344 | which involves filtering out spurious interrupts, keeping race-free | |
345 | blanking counters, coping with counter wrap-around and resets and | |
346 | keeping use counts. It relies on the driver to generate vertical | |
347 | blanking interrupts and optionally provide a hardware vertical blanking | |
348 | counter. Drivers must implement the following operations. | |
349 | ||
350 | - int (\*enable_vblank) (struct drm_device \*dev, int crtc); void | |
351 | (\*disable_vblank) (struct drm_device \*dev, int crtc); | |
352 | Enable or disable vertical blanking interrupts for the given CRTC. | |
353 | ||
354 | - u32 (\*get_vblank_counter) (struct drm_device \*dev, int crtc); | |
355 | Retrieve the value of the vertical blanking counter for the given | |
356 | CRTC. If the hardware maintains a vertical blanking counter its value | |
357 | should be returned. Otherwise drivers can use the | |
358 | :c:func:`drm_vblank_count()` helper function to handle this | |
359 | operation. | |
360 | ||
361 | Drivers must initialize the vertical blanking handling core with a call | |
362 | to :c:func:`drm_vblank_init()` in their load operation. | |
363 | ||
364 | Vertical blanking interrupts can be enabled by the DRM core or by | |
365 | drivers themselves (for instance to handle page flipping operations). | |
366 | The DRM core maintains a vertical blanking use count to ensure that the | |
367 | interrupts are not disabled while a user still needs them. To increment | |
368 | the use count, drivers call :c:func:`drm_vblank_get()`. Upon | |
369 | return vertical blanking interrupts are guaranteed to be enabled. | |
370 | ||
371 | To decrement the use count drivers call | |
372 | :c:func:`drm_vblank_put()`. Only when the use count drops to zero | |
373 | will the DRM core disable the vertical blanking interrupts after a delay | |
374 | by scheduling a timer. The delay is accessible through the | |
375 | vblankoffdelay module parameter or the ``drm_vblank_offdelay`` global | |
376 | variable and expressed in milliseconds. Its default value is 5000 ms. | |
377 | Zero means never disable, and a negative value means disable | |
378 | immediately. Drivers may override the behaviour by setting the | |
379 | :c:type:`struct drm_device <drm_device>` | |
380 | vblank_disable_immediate flag, which when set causes vblank interrupts | |
381 | to be disabled immediately regardless of the drm_vblank_offdelay | |
382 | value. The flag should only be set if there's a properly working | |
383 | hardware vblank counter present. | |
384 | ||
385 | When a vertical blanking interrupt occurs drivers only need to call the | |
386 | :c:func:`drm_handle_vblank()` function to account for the | |
387 | interrupt. | |
388 | ||
389 | Resources allocated by :c:func:`drm_vblank_init()` must be freed | |
390 | with a call to :c:func:`drm_vblank_cleanup()` in the driver unload | |
391 | operation handler. | |
392 | ||
393 | Vertical Blanking and Interrupt Handling Functions Reference | |
394 | ------------------------------------------------------------ | |
395 | ||
396 | .. kernel-doc:: drivers/gpu/drm/drm_irq.c | |
397 | :export: | |
398 | ||
399 | .. kernel-doc:: include/drm/drm_irq.h | |
400 | :internal: |