]>
Commit | Line | Data |
---|---|---|
2d2ef822 JB |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="drmDevelopersGuide"> | |
6 | <bookinfo> | |
7 | <title>Linux DRM Developer's Guide</title> | |
8 | ||
9cad9c95 LP |
9 | <authorgroup> |
10 | <author> | |
11 | <firstname>Jesse</firstname> | |
12 | <surname>Barnes</surname> | |
13 | <contrib>Initial version</contrib> | |
14 | <affiliation> | |
15 | <orgname>Intel Corporation</orgname> | |
16 | <address> | |
17 | <email>jesse.barnes@intel.com</email> | |
18 | </address> | |
19 | </affiliation> | |
20 | </author> | |
21 | <author> | |
22 | <firstname>Laurent</firstname> | |
23 | <surname>Pinchart</surname> | |
24 | <contrib>Driver internals</contrib> | |
25 | <affiliation> | |
26 | <orgname>Ideas on board SPRL</orgname> | |
27 | <address> | |
28 | <email>laurent.pinchart@ideasonboard.com</email> | |
29 | </address> | |
30 | </affiliation> | |
31 | </author> | |
3a05700d DV |
32 | <author> |
33 | <firstname>Daniel</firstname> | |
34 | <surname>Vetter</surname> | |
35 | <contrib>Contributions all over the place</contrib> | |
36 | <affiliation> | |
37 | <orgname>Intel Corporation</orgname> | |
38 | <address> | |
39 | <email>daniel.vetter@ffwll.ch</email> | |
40 | </address> | |
41 | </affiliation> | |
42 | </author> | |
9cad9c95 LP |
43 | </authorgroup> |
44 | ||
2d2ef822 JB |
45 | <copyright> |
46 | <year>2008-2009</year> | |
3a05700d | 47 | <year>2013-2014</year> |
9cad9c95 | 48 | <holder>Intel Corporation</holder> |
3a05700d DV |
49 | </copyright> |
50 | <copyright> | |
51 | <year>2012</year> | |
9cad9c95 | 52 | <holder>Laurent Pinchart</holder> |
2d2ef822 JB |
53 | </copyright> |
54 | ||
55 | <legalnotice> | |
56 | <para> | |
57 | The contents of this file may be used under the terms of the GNU | |
58 | General Public License version 2 (the "GPL") as distributed in | |
59 | the kernel source COPYING file. | |
60 | </para> | |
61 | </legalnotice> | |
9cad9c95 LP |
62 | |
63 | <revhistory> | |
64 | <!-- Put document revisions here, newest first. --> | |
65 | <revision> | |
66 | <revnumber>1.0</revnumber> | |
67 | <date>2012-07-13</date> | |
68 | <authorinitials>LP</authorinitials> | |
69 | <revremark>Added extensive documentation about driver internals. | |
70 | </revremark> | |
71 | </revision> | |
72 | </revhistory> | |
2d2ef822 JB |
73 | </bookinfo> |
74 | ||
75 | <toc></toc> | |
76 | ||
3519f70e DV |
77 | <part id="drmCore"> |
78 | <title>DRM Core</title> | |
79 | <partintro> | |
80 | <para> | |
81 | This first part of the DRM Developer's Guide documents core DRM code, | |
9a6594fc | 82 | helper libraries for writing drivers and generic userspace interfaces |
3519f70e DV |
83 | exposed by DRM drivers. |
84 | </para> | |
85 | </partintro> | |
2d2ef822 JB |
86 | |
87 | <chapter id="drmIntroduction"> | |
88 | <title>Introduction</title> | |
89 | <para> | |
90 | The Linux DRM layer contains code intended to support the needs | |
91 | of complex graphics devices, usually containing programmable | |
92 | pipelines well suited to 3D graphics acceleration. Graphics | |
f11aca04 | 93 | drivers in the kernel may make use of DRM functions to make |
2d2ef822 JB |
94 | tasks like memory management, interrupt handling and DMA easier, |
95 | and provide a uniform interface to applications. | |
96 | </para> | |
97 | <para> | |
98 | A note on versions: this guide covers features found in the DRM | |
99 | tree, including the TTM memory manager, output configuration and | |
100 | mode setting, and the new vblank internals, in addition to all | |
101 | the regular features found in current kernels. | |
102 | </para> | |
103 | <para> | |
104 | [Insert diagram of typical DRM stack here] | |
105 | </para> | |
106 | </chapter> | |
107 | ||
108 | <!-- Internals --> | |
109 | ||
110 | <chapter id="drmInternals"> | |
111 | <title>DRM Internals</title> | |
112 | <para> | |
113 | This chapter documents DRM internals relevant to driver authors | |
114 | and developers working to add support for the latest features to | |
115 | existing drivers. | |
116 | </para> | |
117 | <para> | |
a78f6787 | 118 | First, we go over some typical driver initialization |
2d2ef822 JB |
119 | requirements, like setting up command buffers, creating an |
120 | initial output configuration, and initializing core services. | |
a78f6787 | 121 | Subsequent sections cover core internals in more detail, |
2d2ef822 JB |
122 | providing implementation notes and examples. |
123 | </para> | |
124 | <para> | |
125 | The DRM layer provides several services to graphics drivers, | |
126 | many of them driven by the application interfaces it provides | |
127 | through libdrm, the library that wraps most of the DRM ioctls. | |
128 | These include vblank event handling, memory | |
129 | management, output management, framebuffer management, command | |
130 | submission & fencing, suspend/resume support, and DMA | |
131 | services. | |
132 | </para> | |
2d2ef822 JB |
133 | |
134 | <!-- Internals: driver init --> | |
135 | ||
136 | <sect1> | |
9cad9c95 LP |
137 | <title>Driver Initialization</title> |
138 | <para> | |
139 | At the core of every DRM driver is a <structname>drm_driver</structname> | |
140 | structure. Drivers typically statically initialize a drm_driver structure, | |
141 | and then pass it to one of the <function>drm_*_init()</function> functions | |
142 | to register it with the DRM subsystem. | |
2d2ef822 | 143 | </para> |
b528ae71 TR |
144 | <para> |
145 | Newer drivers that no longer require a <structname>drm_bus</structname> | |
146 | structure can alternatively use the low-level device initialization and | |
147 | registration functions such as <function>drm_dev_alloc()</function> and | |
148 | <function>drm_dev_register()</function> directly. | |
149 | </para> | |
9cad9c95 LP |
150 | <para> |
151 | The <structname>drm_driver</structname> structure contains static | |
152 | information that describes the driver and features it supports, and | |
153 | pointers to methods that the DRM core will call to implement the DRM API. | |
154 | We will first go through the <structname>drm_driver</structname> static | |
155 | information fields, and will then describe individual operations in | |
156 | details as they get used in later sections. | |
2d2ef822 | 157 | </para> |
2d2ef822 | 158 | <sect2> |
9cad9c95 LP |
159 | <title>Driver Information</title> |
160 | <sect3> | |
161 | <title>Driver Features</title> | |
162 | <para> | |
163 | Drivers inform the DRM core about their requirements and supported | |
164 | features by setting appropriate flags in the | |
165 | <structfield>driver_features</structfield> field. Since those flags | |
166 | influence the DRM core behaviour since registration time, most of them | |
167 | must be set to registering the <structname>drm_driver</structname> | |
168 | instance. | |
169 | </para> | |
170 | <synopsis>u32 driver_features;</synopsis> | |
171 | <variablelist> | |
172 | <title>Driver Feature Flags</title> | |
173 | <varlistentry> | |
174 | <term>DRIVER_USE_AGP</term> | |
175 | <listitem><para> | |
176 | Driver uses AGP interface, the DRM core will manage AGP resources. | |
177 | </para></listitem> | |
178 | </varlistentry> | |
179 | <varlistentry> | |
180 | <term>DRIVER_REQUIRE_AGP</term> | |
181 | <listitem><para> | |
182 | Driver needs AGP interface to function. AGP initialization failure | |
183 | will become a fatal error. | |
184 | </para></listitem> | |
185 | </varlistentry> | |
9cad9c95 LP |
186 | <varlistentry> |
187 | <term>DRIVER_PCI_DMA</term> | |
188 | <listitem><para> | |
189 | Driver is capable of PCI DMA, mapping of PCI DMA buffers to | |
190 | userspace will be enabled. Deprecated. | |
191 | </para></listitem> | |
192 | </varlistentry> | |
193 | <varlistentry> | |
194 | <term>DRIVER_SG</term> | |
195 | <listitem><para> | |
196 | Driver can perform scatter/gather DMA, allocation and mapping of | |
197 | scatter/gather buffers will be enabled. Deprecated. | |
198 | </para></listitem> | |
199 | </varlistentry> | |
200 | <varlistentry> | |
201 | <term>DRIVER_HAVE_DMA</term> | |
202 | <listitem><para> | |
203 | Driver supports DMA, the userspace DMA API will be supported. | |
204 | Deprecated. | |
205 | </para></listitem> | |
206 | </varlistentry> | |
207 | <varlistentry> | |
208 | <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> | |
209 | <listitem><para> | |
02b62985 LP |
210 | DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler |
211 | managed by the DRM Core. The core will support simple IRQ handler | |
212 | installation when the flag is set. The installation process is | |
213 | described in <xref linkend="drm-irq-registration"/>.</para> | |
214 | <para>DRIVER_IRQ_SHARED indicates whether the device & handler | |
215 | support shared IRQs (note that this is required of PCI drivers). | |
9cad9c95 LP |
216 | </para></listitem> |
217 | </varlistentry> | |
9cad9c95 LP |
218 | <varlistentry> |
219 | <term>DRIVER_GEM</term> | |
220 | <listitem><para> | |
221 | Driver use the GEM memory manager. | |
222 | </para></listitem> | |
223 | </varlistentry> | |
224 | <varlistentry> | |
225 | <term>DRIVER_MODESET</term> | |
226 | <listitem><para> | |
227 | Driver supports mode setting interfaces (KMS). | |
228 | </para></listitem> | |
229 | </varlistentry> | |
230 | <varlistentry> | |
231 | <term>DRIVER_PRIME</term> | |
232 | <listitem><para> | |
233 | Driver implements DRM PRIME buffer sharing. | |
234 | </para></listitem> | |
235 | </varlistentry> | |
1793126f DH |
236 | <varlistentry> |
237 | <term>DRIVER_RENDER</term> | |
238 | <listitem><para> | |
239 | Driver supports dedicated render nodes. | |
240 | </para></listitem> | |
241 | </varlistentry> | |
9cad9c95 LP |
242 | </variablelist> |
243 | </sect3> | |
244 | <sect3> | |
245 | <title>Major, Minor and Patchlevel</title> | |
246 | <synopsis>int major; | |
247 | int minor; | |
248 | int patchlevel;</synopsis> | |
249 | <para> | |
250 | The DRM core identifies driver versions by a major, minor and patch | |
251 | level triplet. The information is printed to the kernel log at | |
252 | initialization time and passed to userspace through the | |
253 | DRM_IOCTL_VERSION ioctl. | |
254 | </para> | |
255 | <para> | |
256 | The major and minor numbers are also used to verify the requested driver | |
257 | API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes | |
258 | between minor versions, applications can call DRM_IOCTL_SET_VERSION to | |
259 | select a specific version of the API. If the requested major isn't equal | |
260 | to the driver major, or the requested minor is larger than the driver | |
261 | minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise | |
262 | the driver's set_version() method will be called with the requested | |
263 | version. | |
264 | </para> | |
265 | </sect3> | |
266 | <sect3> | |
267 | <title>Name, Description and Date</title> | |
268 | <synopsis>char *name; | |
269 | char *desc; | |
270 | char *date;</synopsis> | |
271 | <para> | |
272 | The driver name is printed to the kernel log at initialization time, | |
273 | used for IRQ registration and passed to userspace through | |
274 | DRM_IOCTL_VERSION. | |
275 | </para> | |
276 | <para> | |
277 | The driver description is a purely informative string passed to | |
278 | userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by | |
279 | the kernel. | |
280 | </para> | |
281 | <para> | |
282 | The driver date, formatted as YYYYMMDD, is meant to identify the date of | |
283 | the latest modification to the driver. However, as most drivers fail to | |
284 | update it, its value is mostly useless. The DRM core prints it to the | |
285 | kernel log at initialization time and passes it to userspace through the | |
286 | DRM_IOCTL_VERSION ioctl. | |
287 | </para> | |
288 | </sect3> | |
289 | </sect2> | |
c6a1af8a TR |
290 | <sect2> |
291 | <title>Device Registration</title> | |
292 | <para> | |
293 | A number of functions are provided to help with device registration. | |
d4f68a75 | 294 | The functions deal with PCI and platform devices, respectively. |
c6a1af8a TR |
295 | </para> |
296 | !Edrivers/gpu/drm/drm_pci.c | |
c6a1af8a | 297 | !Edrivers/gpu/drm/drm_platform.c |
b528ae71 TR |
298 | <para> |
299 | New drivers that no longer rely on the services provided by the | |
300 | <structname>drm_bus</structname> structure can call the low-level | |
301 | device registration functions directly. The | |
302 | <function>drm_dev_alloc()</function> function can be used to allocate | |
303 | and initialize a new <structname>drm_device</structname> structure. | |
304 | Drivers will typically want to perform some additional setup on this | |
305 | structure, such as allocating driver-specific data and storing a | |
306 | pointer to it in the DRM device's <structfield>dev_private</structfield> | |
307 | field. Drivers should also set the device's unique name using the | |
308 | <function>drm_dev_set_unique()</function> function. After it has been | |
309 | set up a device can be registered with the DRM subsystem by calling | |
310 | <function>drm_dev_register()</function>. This will cause the device to | |
311 | be exposed to userspace and will call the driver's | |
312 | <structfield>.load()</structfield> implementation. When a device is | |
313 | removed, the DRM device can safely be unregistered and freed by calling | |
314 | <function>drm_dev_unregister()</function> followed by a call to | |
315 | <function>drm_dev_unref()</function>. | |
316 | </para> | |
25196484 | 317 | !Edrivers/gpu/drm/drm_drv.c |
c6a1af8a | 318 | </sect2> |
9cad9c95 LP |
319 | <sect2> |
320 | <title>Driver Load</title> | |
2d2ef822 | 321 | <para> |
9cad9c95 LP |
322 | The <methodname>load</methodname> method is the driver and device |
323 | initialization entry point. The method is responsible for allocating and | |
e1f8ebdc DV |
324 | initializing driver private data, performing resource allocation and |
325 | mapping (e.g. acquiring | |
9cad9c95 LP |
326 | clocks, mapping registers or allocating command buffers), initializing |
327 | the memory manager (<xref linkend="drm-memory-management"/>), installing | |
328 | the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up | |
329 | vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode | |
330 | setting (<xref linkend="drm-mode-setting"/>) and initial output | |
331 | configuration (<xref linkend="drm-kms-init"/>). | |
2d2ef822 | 332 | </para> |
9cad9c95 LP |
333 | <note><para> |
334 | If compatibility is a concern (e.g. with drivers converted over from | |
335 | User Mode Setting to Kernel Mode Setting), care must be taken to prevent | |
336 | device initialization and control that is incompatible with currently | |
337 | active userspace drivers. For instance, if user level mode setting | |
338 | drivers are in use, it would be problematic to perform output discovery | |
339 | & configuration at load time. Likewise, if user-level drivers | |
340 | unaware of memory management are in use, memory management and command | |
341 | buffer setup may need to be omitted. These requirements are | |
342 | driver-specific, and care needs to be taken to keep both old and new | |
343 | applications and libraries working. | |
344 | </para></note> | |
345 | <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis> | |
2d2ef822 | 346 | <para> |
9cad9c95 LP |
347 | The method takes two arguments, a pointer to the newly created |
348 | <structname>drm_device</structname> and flags. The flags are used to | |
349 | pass the <structfield>driver_data</structfield> field of the device id | |
350 | corresponding to the device passed to <function>drm_*_init()</function>. | |
351 | Only PCI devices currently use this, USB and platform DRM drivers have | |
352 | their <methodname>load</methodname> method called with flags to 0. | |
2d2ef822 | 353 | </para> |
9cad9c95 | 354 | <sect3> |
e1f8ebdc | 355 | <title>Driver Private Data</title> |
9cad9c95 LP |
356 | <para> |
357 | The driver private hangs off the main | |
358 | <structname>drm_device</structname> structure and can be used for | |
359 | tracking various device-specific bits of information, like register | |
360 | offsets, command buffer status, register state for suspend/resume, etc. | |
361 | At load time, a driver may simply allocate one and set | |
362 | <structname>drm_device</structname>.<structfield>dev_priv</structfield> | |
363 | appropriately; it should be freed and | |
364 | <structname>drm_device</structname>.<structfield>dev_priv</structfield> | |
365 | set to NULL when the driver is unloaded. | |
366 | </para> | |
9cad9c95 LP |
367 | </sect3> |
368 | <sect3 id="drm-irq-registration"> | |
369 | <title>IRQ Registration</title> | |
370 | <para> | |
371 | The DRM core tries to facilitate IRQ handler registration and | |
372 | unregistration by providing <function>drm_irq_install</function> and | |
373 | <function>drm_irq_uninstall</function> functions. Those functions only | |
02b62985 LP |
374 | support a single interrupt per device, devices that use more than one |
375 | IRQs need to be handled manually. | |
9cad9c95 | 376 | </para> |
02b62985 LP |
377 | <sect4> |
378 | <title>Managed IRQ Registration</title> | |
02b62985 LP |
379 | <para> |
380 | <function>drm_irq_install</function> starts by calling the | |
381 | <methodname>irq_preinstall</methodname> driver operation. The operation | |
382 | is optional and must make sure that the interrupt will not get fired by | |
383 | clearing all pending interrupt flags or disabling the interrupt. | |
384 | </para> | |
385 | <para> | |
bb0f1b5c | 386 | The passed-in IRQ will then be requested by a call to |
02b62985 LP |
387 | <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver |
388 | feature flag is set, a shared (IRQF_SHARED) IRQ handler will be | |
389 | requested. | |
390 | </para> | |
391 | <para> | |
392 | The IRQ handler function must be provided as the mandatory irq_handler | |
393 | driver operation. It will get passed directly to | |
394 | <function>request_irq</function> and thus has the same prototype as all | |
395 | IRQ handlers. It will get called with a pointer to the DRM device as the | |
396 | second argument. | |
397 | </para> | |
398 | <para> | |
399 | Finally the function calls the optional | |
400 | <methodname>irq_postinstall</methodname> driver operation. The operation | |
401 | usually enables interrupts (excluding the vblank interrupt, which is | |
402 | enabled separately), but drivers may choose to enable/disable interrupts | |
403 | at a different time. | |
404 | </para> | |
405 | <para> | |
406 | <function>drm_irq_uninstall</function> is similarly used to uninstall an | |
407 | IRQ handler. It starts by waking up all processes waiting on a vblank | |
408 | interrupt to make sure they don't hang, and then calls the optional | |
409 | <methodname>irq_uninstall</methodname> driver operation. The operation | |
410 | must disable all hardware interrupts. Finally the function frees the IRQ | |
411 | by calling <function>free_irq</function>. | |
412 | </para> | |
413 | </sect4> | |
414 | <sect4> | |
415 | <title>Manual IRQ Registration</title> | |
416 | <para> | |
417 | Drivers that require multiple interrupt handlers can't use the managed | |
418 | IRQ registration functions. In that case IRQs must be registered and | |
419 | unregistered manually (usually with the <function>request_irq</function> | |
420 | and <function>free_irq</function> functions, or their devm_* equivalent). | |
421 | </para> | |
422 | <para> | |
423 | When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ | |
424 | driver feature flag, and must not provide the | |
425 | <methodname>irq_handler</methodname> driver operation. They must set the | |
426 | <structname>drm_device</structname> <structfield>irq_enabled</structfield> | |
427 | field to 1 upon registration of the IRQs, and clear it to 0 after | |
428 | unregistering the IRQs. | |
429 | </para> | |
430 | </sect4> | |
9cad9c95 LP |
431 | </sect3> |
432 | <sect3> | |
433 | <title>Memory Manager Initialization</title> | |
434 | <para> | |
435 | Every DRM driver requires a memory manager which must be initialized at | |
436 | load time. DRM currently contains two memory managers, the Translation | |
437 | Table Manager (TTM) and the Graphics Execution Manager (GEM). | |
438 | This document describes the use of the GEM memory manager only. See | |
439 | <xref linkend="drm-memory-management"/> for details. | |
440 | </para> | |
441 | </sect3> | |
442 | <sect3> | |
443 | <title>Miscellaneous Device Configuration</title> | |
444 | <para> | |
445 | Another task that may be necessary for PCI devices during configuration | |
446 | is mapping the video BIOS. On many devices, the VBIOS describes device | |
447 | configuration, LCD panel timings (if any), and contains flags indicating | |
448 | device state. Mapping the BIOS can be done using the pci_map_rom() call, | |
449 | a convenience function that takes care of mapping the actual ROM, | |
450 | whether it has been shadowed into memory (typically at address 0xc0000) | |
451 | or exists on the PCI device in the ROM BAR. Note that after the ROM has | |
452 | been mapped and any necessary information has been extracted, it should | |
453 | be unmapped; on many devices, the ROM address decoder is shared with | |
454 | other BARs, so leaving it mapped could cause undesired behaviour like | |
455 | hangs or memory corruption. | |
456 | <!--!Fdrivers/pci/rom.c pci_map_rom--> | |
457 | </para> | |
458 | </sect3> | |
2d2ef822 | 459 | </sect2> |
9cad9c95 | 460 | </sect1> |
2d2ef822 | 461 | |
9cad9c95 | 462 | <!-- Internals: memory management --> |
2d2ef822 | 463 | |
9cad9c95 LP |
464 | <sect1 id="drm-memory-management"> |
465 | <title>Memory management</title> | |
466 | <para> | |
467 | Modern Linux systems require large amount of graphics memory to store | |
468 | frame buffers, textures, vertices and other graphics-related data. Given | |
469 | the very dynamic nature of many of that data, managing graphics memory | |
470 | efficiently is thus crucial for the graphics stack and plays a central | |
471 | role in the DRM infrastructure. | |
472 | </para> | |
473 | <para> | |
474 | The DRM core includes two memory managers, namely Translation Table Maps | |
475 | (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory | |
476 | manager to be developed and tried to be a one-size-fits-them all | |
f884ab15 | 477 | solution. It provides a single userspace API to accommodate the need of |
9cad9c95 LP |
478 | all hardware, supporting both Unified Memory Architecture (UMA) devices |
479 | and devices with dedicated video RAM (i.e. most discrete video cards). | |
480 | This resulted in a large, complex piece of code that turned out to be | |
481 | hard to use for driver development. | |
482 | </para> | |
483 | <para> | |
484 | GEM started as an Intel-sponsored project in reaction to TTM's | |
485 | complexity. Its design philosophy is completely different: instead of | |
486 | providing a solution to every graphics memory-related problems, GEM | |
487 | identified common code between drivers and created a support library to | |
488 | share it. GEM has simpler initialization and execution requirements than | |
9a6594fc | 489 | TTM, but has no video RAM management capabilities and is thus limited to |
9cad9c95 LP |
490 | UMA devices. |
491 | </para> | |
2d2ef822 | 492 | <sect2> |
9cad9c95 | 493 | <title>The Translation Table Manager (TTM)</title> |
2d2ef822 | 494 | <para> |
79058100 | 495 | TTM design background and information belongs here. |
2d2ef822 JB |
496 | </para> |
497 | <sect3> | |
79058100 | 498 | <title>TTM initialization</title> |
9cad9c95 LP |
499 | <warning><para>This section is outdated.</para></warning> |
500 | <para> | |
501 | Drivers wishing to support TTM must fill out a drm_bo_driver | |
502 | structure. The structure contains several fields with function | |
503 | pointers for initializing the TTM, allocating and freeing memory, | |
504 | waiting for command completion and fence synchronization, and memory | |
505 | migration. See the radeon_ttm.c file for an example of usage. | |
79058100 TR |
506 | </para> |
507 | <para> | |
508 | The ttm_global_reference structure is made up of several fields: | |
509 | </para> | |
510 | <programlisting> | |
511 | struct ttm_global_reference { | |
512 | enum ttm_global_types global_type; | |
513 | size_t size; | |
514 | void *object; | |
515 | int (*init) (struct ttm_global_reference *); | |
516 | void (*release) (struct ttm_global_reference *); | |
517 | }; | |
518 | </programlisting> | |
519 | <para> | |
520 | There should be one global reference structure for your memory | |
521 | manager as a whole, and there will be others for each object | |
522 | created by the memory manager at runtime. Your global TTM should | |
523 | have a type of TTM_GLOBAL_TTM_MEM. The size field for the global | |
524 | object should be sizeof(struct ttm_mem_global), and the init and | |
525 | release hooks should point at your driver-specific init and | |
526 | release routines, which probably eventually call | |
527 | ttm_mem_global_init and ttm_mem_global_release, respectively. | |
528 | </para> | |
529 | <para> | |
530 | Once your global TTM accounting structure is set up and initialized | |
531 | by calling ttm_global_item_ref() on it, | |
532 | you need to create a buffer object TTM to | |
533 | provide a pool for buffer object allocation by clients and the | |
534 | kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, | |
535 | and its size should be sizeof(struct ttm_bo_global). Again, | |
536 | driver-specific init and release functions may be provided, | |
537 | likely eventually calling ttm_bo_global_init() and | |
538 | ttm_bo_global_release(), respectively. Also, like the previous | |
539 | object, ttm_global_item_ref() is used to create an initial reference | |
540 | count for the TTM, which will call your initialization function. | |
541 | </para> | |
2d2ef822 | 542 | </sect3> |
9cad9c95 LP |
543 | </sect2> |
544 | <sect2 id="drm-gem"> | |
545 | <title>The Graphics Execution Manager (GEM)</title> | |
546 | <para> | |
547 | The GEM design approach has resulted in a memory manager that doesn't | |
548 | provide full coverage of all (or even all common) use cases in its | |
549 | userspace or kernel API. GEM exposes a set of standard memory-related | |
550 | operations to userspace and a set of helper functions to drivers, and let | |
551 | drivers implement hardware-specific operations with their own private API. | |
552 | </para> | |
553 | <para> | |
554 | The GEM userspace API is described in the | |
555 | <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics | |
556 | Execution Manager</citetitle></ulink> article on LWN. While slightly | |
557 | outdated, the document provides a good overview of the GEM API principles. | |
558 | Buffer allocation and read and write operations, described as part of the | |
559 | common GEM API, are currently implemented using driver-specific ioctls. | |
560 | </para> | |
561 | <para> | |
562 | GEM is data-agnostic. It manages abstract buffer objects without knowing | |
563 | what individual buffers contain. APIs that require knowledge of buffer | |
564 | contents or purpose, such as buffer allocation or synchronization | |
565 | primitives, are thus outside of the scope of GEM and must be implemented | |
566 | using driver-specific ioctls. | |
567 | </para> | |
568 | <para> | |
79058100 TR |
569 | On a fundamental level, GEM involves several operations: |
570 | <itemizedlist> | |
571 | <listitem>Memory allocation and freeing</listitem> | |
572 | <listitem>Command execution</listitem> | |
573 | <listitem>Aperture management at command execution time</listitem> | |
574 | </itemizedlist> | |
575 | Buffer object allocation is relatively straightforward and largely | |
9cad9c95 LP |
576 | provided by Linux's shmem layer, which provides memory to back each |
577 | object. | |
578 | </para> | |
579 | <para> | |
580 | Device-specific operations, such as command execution, pinning, buffer | |
79058100 | 581 | read & write, mapping, and domain ownership transfers are left to |
9cad9c95 LP |
582 | driver-specific ioctls. |
583 | </para> | |
584 | <sect3> | |
585 | <title>GEM Initialization</title> | |
586 | <para> | |
587 | Drivers that use GEM must set the DRIVER_GEM bit in the struct | |
588 | <structname>drm_driver</structname> | |
589 | <structfield>driver_features</structfield> field. The DRM core will | |
590 | then automatically initialize the GEM core before calling the | |
591 | <methodname>load</methodname> operation. Behind the scene, this will | |
592 | create a DRM Memory Manager object which provides an address space | |
593 | pool for object allocation. | |
594 | </para> | |
595 | <para> | |
596 | In a KMS configuration, drivers need to allocate and initialize a | |
597 | command ring buffer following core GEM initialization if required by | |
598 | the hardware. UMA devices usually have what is called a "stolen" | |
599 | memory region, which provides space for the initial framebuffer and | |
600 | large, contiguous memory regions required by the device. This space is | |
601 | typically not managed by GEM, and must be initialized separately into | |
602 | its own DRM MM object. | |
603 | </para> | |
604 | </sect3> | |
2d2ef822 | 605 | <sect3> |
9cad9c95 LP |
606 | <title>GEM Objects Creation</title> |
607 | <para> | |
608 | GEM splits creation of GEM objects and allocation of the memory that | |
609 | backs them in two distinct operations. | |
610 | </para> | |
611 | <para> | |
612 | GEM objects are represented by an instance of struct | |
613 | <structname>drm_gem_object</structname>. Drivers usually need to extend | |
614 | GEM objects with private information and thus create a driver-specific | |
615 | GEM object structure type that embeds an instance of struct | |
616 | <structname>drm_gem_object</structname>. | |
617 | </para> | |
618 | <para> | |
619 | To create a GEM object, a driver allocates memory for an instance of its | |
620 | specific GEM object type and initializes the embedded struct | |
621 | <structname>drm_gem_object</structname> with a call to | |
622 | <function>drm_gem_object_init</function>. The function takes a pointer to | |
623 | the DRM device, a pointer to the GEM object and the buffer object size | |
624 | in bytes. | |
625 | </para> | |
626 | <para> | |
627 | GEM uses shmem to allocate anonymous pageable memory. | |
628 | <function>drm_gem_object_init</function> will create an shmfs file of | |
629 | the requested size and store it into the struct | |
630 | <structname>drm_gem_object</structname> <structfield>filp</structfield> | |
631 | field. The memory is used as either main storage for the object when the | |
632 | graphics hardware uses system memory directly or as a backing store | |
633 | otherwise. | |
634 | </para> | |
635 | <para> | |
636 | Drivers are responsible for the actual physical pages allocation by | |
637 | calling <function>shmem_read_mapping_page_gfp</function> for each page. | |
638 | Note that they can decide to allocate pages when initializing the GEM | |
639 | object, or to delay allocation until the memory is needed (for instance | |
640 | when a page fault occurs as a result of a userspace memory access or | |
641 | when the driver needs to start a DMA transfer involving the memory). | |
642 | </para> | |
643 | <para> | |
644 | Anonymous pageable memory allocation is not always desired, for instance | |
645 | when the hardware requires physically contiguous system memory as is | |
646 | often the case in embedded devices. Drivers can create GEM objects with | |
647 | no shmfs backing (called private GEM objects) by initializing them with | |
648 | a call to <function>drm_gem_private_object_init</function> instead of | |
649 | <function>drm_gem_object_init</function>. Storage for private GEM | |
650 | objects must be managed by drivers. | |
651 | </para> | |
652 | <para> | |
653 | Drivers that do not need to extend GEM objects with private information | |
654 | can call the <function>drm_gem_object_alloc</function> function to | |
655 | allocate and initialize a struct <structname>drm_gem_object</structname> | |
656 | instance. The GEM core will call the optional driver | |
657 | <methodname>gem_init_object</methodname> operation after initializing | |
658 | the GEM object with <function>drm_gem_object_init</function>. | |
659 | <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis> | |
660 | </para> | |
661 | <para> | |
662 | No alloc-and-init function exists for private GEM objects. | |
663 | </para> | |
664 | </sect3> | |
665 | <sect3> | |
666 | <title>GEM Objects Lifetime</title> | |
667 | <para> | |
668 | All GEM objects are reference-counted by the GEM core. References can be | |
669 | acquired and release by <function>calling drm_gem_object_reference</function> | |
670 | and <function>drm_gem_object_unreference</function> respectively. The | |
671 | caller must hold the <structname>drm_device</structname> | |
672 | <structfield>struct_mutex</structfield> lock. As a convenience, GEM | |
673 | provides the <function>drm_gem_object_reference_unlocked</function> and | |
674 | <function>drm_gem_object_unreference_unlocked</function> functions that | |
675 | can be called without holding the lock. | |
676 | </para> | |
677 | <para> | |
678 | When the last reference to a GEM object is released the GEM core calls | |
679 | the <structname>drm_driver</structname> | |
680 | <methodname>gem_free_object</methodname> operation. That operation is | |
681 | mandatory for GEM-enabled drivers and must free the GEM object and all | |
682 | associated resources. | |
683 | </para> | |
684 | <para> | |
685 | <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis> | |
686 | Drivers are responsible for freeing all GEM object resources, including | |
687 | the resources created by the GEM core. If an mmap offset has been | |
688 | created for the object (in which case | |
689 | <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield> | |
690 | is not NULL) it must be freed by a call to | |
691 | <function>drm_gem_free_mmap_offset</function>. The shmfs backing store | |
692 | must be released by calling <function>drm_gem_object_release</function> | |
693 | (that function can safely be called if no shmfs backing store has been | |
694 | created). | |
695 | </para> | |
696 | </sect3> | |
697 | <sect3> | |
698 | <title>GEM Objects Naming</title> | |
699 | <para> | |
700 | Communication between userspace and the kernel refers to GEM objects | |
701 | using local handles, global names or, more recently, file descriptors. | |
702 | All of those are 32-bit integer values; the usual Linux kernel limits | |
703 | apply to the file descriptors. | |
704 | </para> | |
705 | <para> | |
706 | GEM handles are local to a DRM file. Applications get a handle to a GEM | |
707 | object through a driver-specific ioctl, and can use that handle to refer | |
708 | to the GEM object in other standard or driver-specific ioctls. Closing a | |
709 | DRM file handle frees all its GEM handles and dereferences the | |
710 | associated GEM objects. | |
711 | </para> | |
712 | <para> | |
713 | To create a handle for a GEM object drivers call | |
714 | <function>drm_gem_handle_create</function>. The function takes a pointer | |
715 | to the DRM file and the GEM object and returns a locally unique handle. | |
716 | When the handle is no longer needed drivers delete it with a call to | |
717 | <function>drm_gem_handle_delete</function>. Finally the GEM object | |
718 | associated with a handle can be retrieved by a call to | |
719 | <function>drm_gem_object_lookup</function>. | |
720 | </para> | |
721 | <para> | |
722 | Handles don't take ownership of GEM objects, they only take a reference | |
723 | to the object that will be dropped when the handle is destroyed. To | |
724 | avoid leaking GEM objects, drivers must make sure they drop the | |
725 | reference(s) they own (such as the initial reference taken at object | |
726 | creation time) as appropriate, without any special consideration for the | |
727 | handle. For example, in the particular case of combined GEM object and | |
728 | handle creation in the implementation of the | |
729 | <methodname>dumb_create</methodname> operation, drivers must drop the | |
730 | initial reference to the GEM object before returning the handle. | |
731 | </para> | |
732 | <para> | |
733 | GEM names are similar in purpose to handles but are not local to DRM | |
734 | files. They can be passed between processes to reference a GEM object | |
735 | globally. Names can't be used directly to refer to objects in the DRM | |
736 | API, applications must convert handles to names and names to handles | |
737 | using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls | |
738 | respectively. The conversion is handled by the DRM core without any | |
739 | driver-specific support. | |
740 | </para> | |
79058100 TR |
741 | <para> |
742 | GEM also supports buffer sharing with dma-buf file descriptors through | |
743 | PRIME. GEM-based drivers must use the provided helpers functions to | |
744 | implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. | |
745 | Since sharing file descriptors is inherently more secure than the | |
746 | easily guessable and global GEM names it is the preferred buffer | |
747 | sharing mechanism. Sharing buffers through GEM names is only supported | |
748 | for legacy userspace. Furthermore PRIME also allows cross-device | |
749 | buffer sharing since it is based on dma-bufs. | |
750 | </para> | |
9cad9c95 LP |
751 | </sect3> |
752 | <sect3 id="drm-gem-objects-mapping"> | |
753 | <title>GEM Objects Mapping</title> | |
754 | <para> | |
755 | Because mapping operations are fairly heavyweight GEM favours | |
756 | read/write-like access to buffers, implemented through driver-specific | |
757 | ioctls, over mapping buffers to userspace. However, when random access | |
758 | to the buffer is needed (to perform software rendering for instance), | |
759 | direct access to the object can be more efficient. | |
760 | </para> | |
761 | <para> | |
762 | The mmap system call can't be used directly to map GEM objects, as they | |
763 | don't have their own file handle. Two alternative methods currently | |
764 | co-exist to map GEM objects to userspace. The first method uses a | |
765 | driver-specific ioctl to perform the mapping operation, calling | |
766 | <function>do_mmap</function> under the hood. This is often considered | |
767 | dubious, seems to be discouraged for new GEM-enabled drivers, and will | |
768 | thus not be described here. | |
769 | </para> | |
770 | <para> | |
771 | The second method uses the mmap system call on the DRM file handle. | |
772 | <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd, | |
773 | off_t offset);</synopsis> | |
774 | DRM identifies the GEM object to be mapped by a fake offset passed | |
775 | through the mmap offset argument. Prior to being mapped, a GEM object | |
776 | must thus be associated with a fake offset. To do so, drivers must call | |
777 | <function>drm_gem_create_mmap_offset</function> on the object. The | |
778 | function allocates a fake offset range from a pool and stores the | |
779 | offset divided by PAGE_SIZE in | |
780 | <literal>obj->map_list.hash.key</literal>. Care must be taken not to | |
781 | call <function>drm_gem_create_mmap_offset</function> if a fake offset | |
782 | has already been allocated for the object. This can be tested by | |
783 | <literal>obj->map_list.map</literal> being non-NULL. | |
784 | </para> | |
785 | <para> | |
786 | Once allocated, the fake offset value | |
787 | (<literal>obj->map_list.hash.key << PAGE_SHIFT</literal>) | |
788 | must be passed to the application in a driver-specific way and can then | |
789 | be used as the mmap offset argument. | |
790 | </para> | |
791 | <para> | |
792 | The GEM core provides a helper method <function>drm_gem_mmap</function> | |
793 | to handle object mapping. The method can be set directly as the mmap | |
794 | file operation handler. It will look up the GEM object based on the | |
795 | offset value and set the VMA operations to the | |
796 | <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield> | |
797 | field. Note that <function>drm_gem_mmap</function> doesn't map memory to | |
798 | userspace, but relies on the driver-provided fault handler to map pages | |
799 | individually. | |
800 | </para> | |
801 | <para> | |
802 | To use <function>drm_gem_mmap</function>, drivers must fill the struct | |
803 | <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield> | |
804 | field with a pointer to VM operations. | |
805 | </para> | |
806 | <para> | |
807 | <synopsis>struct vm_operations_struct *gem_vm_ops | |
808 | ||
809 | struct vm_operations_struct { | |
810 | void (*open)(struct vm_area_struct * area); | |
811 | void (*close)(struct vm_area_struct * area); | |
812 | int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf); | |
813 | };</synopsis> | |
814 | </para> | |
815 | <para> | |
816 | The <methodname>open</methodname> and <methodname>close</methodname> | |
817 | operations must update the GEM object reference count. Drivers can use | |
818 | the <function>drm_gem_vm_open</function> and | |
819 | <function>drm_gem_vm_close</function> helper functions directly as open | |
820 | and close handlers. | |
821 | </para> | |
822 | <para> | |
823 | The fault operation handler is responsible for mapping individual pages | |
824 | to userspace when a page fault occurs. Depending on the memory | |
825 | allocation scheme, drivers can allocate pages at fault time, or can | |
826 | decide to allocate memory for the GEM object at the time the object is | |
827 | created. | |
828 | </para> | |
829 | <para> | |
830 | Drivers that want to map the GEM object upfront instead of handling page | |
831 | faults can implement their own mmap file operation handler. | |
832 | </para> | |
833 | </sect3> | |
9cad9c95 LP |
834 | <sect3> |
835 | <title>Memory Coherency</title> | |
836 | <para> | |
837 | When mapped to the device or used in a command buffer, backing pages | |
838 | for an object are flushed to memory and marked write combined so as to | |
839 | be coherent with the GPU. Likewise, if the CPU accesses an object | |
840 | after the GPU has finished rendering to the object, then the object | |
841 | must be made coherent with the CPU's view of memory, usually involving | |
842 | GPU cache flushing of various kinds. This core CPU<->GPU | |
843 | coherency management is provided by a device-specific ioctl, which | |
844 | evaluates an object's current domain and performs any necessary | |
845 | flushing or synchronization to put the object into the desired | |
846 | coherency domain (note that the object may be busy, i.e. an active | |
847 | render target; in that case, setting the domain blocks the client and | |
848 | waits for rendering to complete before performing any necessary | |
849 | flushing operations). | |
850 | </para> | |
851 | </sect3> | |
852 | <sect3> | |
853 | <title>Command Execution</title> | |
854 | <para> | |
79058100 | 855 | Perhaps the most important GEM function for GPU devices is providing a |
9cad9c95 LP |
856 | command execution interface to clients. Client programs construct |
857 | command buffers containing references to previously allocated memory | |
858 | objects, and then submit them to GEM. At that point, GEM takes care to | |
859 | bind all the objects into the GTT, execute the buffer, and provide | |
860 | necessary synchronization between clients accessing the same buffers. | |
861 | This often involves evicting some objects from the GTT and re-binding | |
862 | others (a fairly expensive operation), and providing relocation | |
863 | support which hides fixed GTT offsets from clients. Clients must take | |
864 | care not to submit command buffers that reference more objects than | |
865 | can fit in the GTT; otherwise, GEM will reject them and no rendering | |
866 | will occur. Similarly, if several objects in the buffer require fence | |
867 | registers to be allocated for correct rendering (e.g. 2D blits on | |
868 | pre-965 chips), care must be taken not to require more fence registers | |
869 | than are available to the client. Such resource management should be | |
870 | abstracted from the client in libdrm. | |
871 | </para> | |
2d2ef822 | 872 | </sect3> |
251261db | 873 | <sect3> |
89d61fc0 DV |
874 | <title>GEM Function Reference</title> |
875 | !Edrivers/gpu/drm/drm_gem.c | |
251261db | 876 | </sect3> |
79058100 TR |
877 | </sect2> |
878 | <sect2> | |
879 | <title>VMA Offset Manager</title> | |
4c5acf3c DV |
880 | !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager |
881 | !Edrivers/gpu/drm/drm_vma_manager.c | |
882 | !Iinclude/drm/drm_vma_manager.h | |
79058100 TR |
883 | </sect2> |
884 | <sect2 id="drm-prime-support"> | |
885 | <title>PRIME Buffer Sharing</title> | |
886 | <para> | |
887 | PRIME is the cross device buffer sharing framework in drm, originally | |
888 | created for the OPTIMUS range of multi-gpu platforms. To userspace | |
889 | PRIME buffers are dma-buf based file descriptors. | |
890 | </para> | |
891 | <sect3> | |
892 | <title>Overview and Driver Interface</title> | |
893 | <para> | |
894 | Similar to GEM global names, PRIME file descriptors are | |
895 | also used to share buffer objects across processes. They offer | |
896 | additional security: as file descriptors must be explicitly sent over | |
897 | UNIX domain sockets to be shared between applications, they can't be | |
898 | guessed like the globally unique GEM names. | |
899 | </para> | |
900 | <para> | |
901 | Drivers that support the PRIME | |
902 | API must set the DRIVER_PRIME bit in the struct | |
903 | <structname>drm_driver</structname> | |
904 | <structfield>driver_features</structfield> field, and implement the | |
905 | <methodname>prime_handle_to_fd</methodname> and | |
906 | <methodname>prime_fd_to_handle</methodname> operations. | |
907 | </para> | |
908 | <para> | |
909 | <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, | |
910 | struct drm_file *file_priv, uint32_t handle, | |
911 | uint32_t flags, int *prime_fd); | |
251261db | 912 | int (*prime_fd_to_handle)(struct drm_device *dev, |
79058100 TR |
913 | struct drm_file *file_priv, int prime_fd, |
914 | uint32_t *handle);</synopsis> | |
915 | Those two operations convert a handle to a PRIME file descriptor and | |
916 | vice versa. Drivers must use the kernel dma-buf buffer sharing framework | |
917 | to manage the PRIME file descriptors. Similar to the mode setting | |
918 | API PRIME is agnostic to the underlying buffer object manager, as | |
919 | long as handles are 32bit unsigned integers. | |
920 | </para> | |
921 | <para> | |
922 | While non-GEM drivers must implement the operations themselves, GEM | |
923 | drivers must use the <function>drm_gem_prime_handle_to_fd</function> | |
924 | and <function>drm_gem_prime_fd_to_handle</function> helper functions. | |
925 | Those helpers rely on the driver | |
926 | <methodname>gem_prime_export</methodname> and | |
927 | <methodname>gem_prime_import</methodname> operations to create a dma-buf | |
928 | instance from a GEM object (dma-buf exporter role) and to create a GEM | |
929 | object from a dma-buf instance (dma-buf importer role). | |
930 | </para> | |
931 | <para> | |
932 | <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, | |
933 | struct drm_gem_object *obj, | |
934 | int flags); | |
251261db | 935 | struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, |
79058100 TR |
936 | struct dma_buf *dma_buf);</synopsis> |
937 | These two operations are mandatory for GEM drivers that support | |
938 | PRIME. | |
939 | </para> | |
251261db | 940 | </sect3> |
79058100 TR |
941 | <sect3> |
942 | <title>PRIME Helper Functions</title> | |
943 | !Pdrivers/gpu/drm/drm_prime.c PRIME Helpers | |
944 | </sect3> | |
945 | </sect2> | |
946 | <sect2> | |
947 | <title>PRIME Function References</title> | |
39cc344a | 948 | !Edrivers/gpu/drm/drm_prime.c |
79058100 TR |
949 | </sect2> |
950 | <sect2> | |
951 | <title>DRM MM Range Allocator</title> | |
952 | <sect3> | |
953 | <title>Overview</title> | |
93110be6 | 954 | !Pdrivers/gpu/drm/drm_mm.c Overview |
79058100 TR |
955 | </sect3> |
956 | <sect3> | |
957 | <title>LRU Scan/Eviction Support</title> | |
93110be6 | 958 | !Pdrivers/gpu/drm/drm_mm.c lru scan roaster |
79058100 | 959 | </sect3> |
93110be6 | 960 | </sect2> |
79058100 TR |
961 | <sect2> |
962 | <title>DRM MM Range Allocator Function References</title> | |
e18c0412 DV |
963 | !Edrivers/gpu/drm/drm_mm.c |
964 | !Iinclude/drm/drm_mm.h | |
79058100 | 965 | </sect2> |
d7883f87 TR |
966 | <sect2> |
967 | <title>CMA Helper Functions Reference</title> | |
968 | !Pdrivers/gpu/drm/drm_gem_cma_helper.c cma helpers | |
969 | !Edrivers/gpu/drm/drm_gem_cma_helper.c | |
970 | !Iinclude/drm/drm_gem_cma_helper.h | |
971 | </sect2> | |
9cad9c95 LP |
972 | </sect1> |
973 | ||
974 | <!-- Internals: mode setting --> | |
2d2ef822 | 975 | |
9cad9c95 LP |
976 | <sect1 id="drm-mode-setting"> |
977 | <title>Mode Setting</title> | |
978 | <para> | |
979 | Drivers must initialize the mode setting core by calling | |
980 | <function>drm_mode_config_init</function> on the DRM device. The function | |
981 | initializes the <structname>drm_device</structname> | |
982 | <structfield>mode_config</structfield> field and never fails. Once done, | |
983 | mode configuration must be setup by initializing the following fields. | |
984 | </para> | |
985 | <itemizedlist> | |
986 | <listitem> | |
987 | <synopsis>int min_width, min_height; | |
988 | int max_width, max_height;</synopsis> | |
989 | <para> | |
990 | Minimum and maximum width and height of the frame buffers in pixel | |
991 | units. | |
992 | </para> | |
993 | </listitem> | |
994 | <listitem> | |
995 | <synopsis>struct drm_mode_config_funcs *funcs;</synopsis> | |
996 | <para>Mode setting functions.</para> | |
997 | </listitem> | |
998 | </itemizedlist> | |
3ec0db81 DV |
999 | <sect2> |
1000 | <title>Display Modes Function Reference</title> | |
f5aabb97 | 1001 | !Iinclude/drm/drm_modes.h |
3ec0db81 | 1002 | !Edrivers/gpu/drm/drm_modes.c |
cc4ceb48 DV |
1003 | </sect2> |
1004 | <sect2> | |
1005 | <title>Atomic Mode Setting Function Reference</title> | |
1006 | !Edrivers/gpu/drm/drm_atomic.c | |
3ec0db81 | 1007 | </sect2> |
2d2ef822 | 1008 | <sect2> |
9cad9c95 LP |
1009 | <title>Frame Buffer Creation</title> |
1010 | <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, | |
1011 | struct drm_file *file_priv, | |
1012 | struct drm_mode_fb_cmd2 *mode_cmd);</synopsis> | |
2d2ef822 | 1013 | <para> |
9cad9c95 LP |
1014 | Frame buffers are abstract memory objects that provide a source of |
1015 | pixels to scanout to a CRTC. Applications explicitly request the | |
1016 | creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and | |
1017 | receive an opaque handle that can be passed to the KMS CRTC control, | |
1018 | plane configuration and page flip functions. | |
1019 | </para> | |
1020 | <para> | |
1021 | Frame buffers rely on the underneath memory manager for low-level memory | |
1022 | operations. When creating a frame buffer applications pass a memory | |
1023 | handle (or a list of memory handles for multi-planar formats) through | |
065a5027 DV |
1024 | the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using |
1025 | GEM as their userspace buffer management interface this would be a GEM | |
1026 | handle. Drivers are however free to use their own backing storage object | |
1027 | handles, e.g. vmwgfx directly exposes special TTM handles to userspace | |
1028 | and so expects TTM handles in the create ioctl and not GEM handles. | |
9cad9c95 LP |
1029 | </para> |
1030 | <para> | |
1031 | Drivers must first validate the requested frame buffer parameters passed | |
1032 | through the mode_cmd argument. In particular this is where invalid | |
1033 | sizes, pixel formats or pitches can be caught. | |
1034 | </para> | |
1035 | <para> | |
1036 | If the parameters are deemed valid, drivers then create, initialize and | |
1037 | return an instance of struct <structname>drm_framebuffer</structname>. | |
1038 | If desired the instance can be embedded in a larger driver-specific | |
5d7a9515 DV |
1039 | structure. Drivers must fill its <structfield>width</structfield>, |
1040 | <structfield>height</structfield>, <structfield>pitches</structfield>, | |
1041 | <structfield>offsets</structfield>, <structfield>depth</structfield>, | |
1042 | <structfield>bits_per_pixel</structfield> and | |
1043 | <structfield>pixel_format</structfield> fields from the values passed | |
1044 | through the <parameter>drm_mode_fb_cmd2</parameter> argument. They | |
1045 | should call the <function>drm_helper_mode_fill_fb_struct</function> | |
1046 | helper function to do so. | |
1047 | </para> | |
1048 | ||
1049 | <para> | |
065a5027 | 1050 | The initialization of the new framebuffer instance is finalized with a |
5d7a9515 DV |
1051 | call to <function>drm_framebuffer_init</function> which takes a pointer |
1052 | to DRM frame buffer operations (struct | |
1053 | <structname>drm_framebuffer_funcs</structname>). Note that this function | |
1054 | publishes the framebuffer and so from this point on it can be accessed | |
1055 | concurrently from other threads. Hence it must be the last step in the | |
1056 | driver's framebuffer initialization sequence. Frame buffer operations | |
1057 | are | |
9cad9c95 LP |
1058 | <itemizedlist> |
1059 | <listitem> | |
1060 | <synopsis>int (*create_handle)(struct drm_framebuffer *fb, | |
1061 | struct drm_file *file_priv, unsigned int *handle);</synopsis> | |
1062 | <para> | |
1063 | Create a handle to the frame buffer underlying memory object. If | |
1064 | the frame buffer uses a multi-plane format, the handle will | |
1065 | reference the memory object associated with the first plane. | |
1066 | </para> | |
1067 | <para> | |
1068 | Drivers call <function>drm_gem_handle_create</function> to create | |
1069 | the handle. | |
1070 | </para> | |
1071 | </listitem> | |
1072 | <listitem> | |
1073 | <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis> | |
1074 | <para> | |
1075 | Destroy the frame buffer object and frees all associated | |
1076 | resources. Drivers must call | |
1077 | <function>drm_framebuffer_cleanup</function> to free resources | |
1078 | allocated by the DRM core for the frame buffer object, and must | |
1079 | make sure to unreference all memory objects associated with the | |
1080 | frame buffer. Handles created by the | |
1081 | <methodname>create_handle</methodname> operation are released by | |
1082 | the DRM core. | |
1083 | </para> | |
1084 | </listitem> | |
1085 | <listitem> | |
1086 | <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer, | |
1087 | struct drm_file *file_priv, unsigned flags, unsigned color, | |
1088 | struct drm_clip_rect *clips, unsigned num_clips);</synopsis> | |
1089 | <para> | |
1090 | This optional operation notifies the driver that a region of the | |
1091 | frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB | |
1092 | ioctl call. | |
1093 | </para> | |
1094 | </listitem> | |
1095 | </itemizedlist> | |
1096 | </para> | |
1097 | <para> | |
5d7a9515 DV |
1098 | The lifetime of a drm framebuffer is controlled with a reference count, |
1099 | drivers can grab additional references with | |
9ee984a5 | 1100 | <function>drm_framebuffer_reference</function>and drop them |
5d7a9515 DV |
1101 | again with <function>drm_framebuffer_unreference</function>. For |
1102 | driver-private framebuffers for which the last reference is never | |
1103 | dropped (e.g. for the fbdev framebuffer when the struct | |
1104 | <structname>drm_framebuffer</structname> is embedded into the fbdev | |
1105 | helper struct) drivers can manually clean up a framebuffer at module | |
1106 | unload time with | |
1107 | <function>drm_framebuffer_unregister_private</function>. | |
9ee984a5 | 1108 | </para> |
9cad9c95 | 1109 | </sect2> |
065a5027 DV |
1110 | <sect2> |
1111 | <title>Dumb Buffer Objects</title> | |
1112 | <para> | |
1113 | The KMS API doesn't standardize backing storage object creation and | |
1114 | leaves it to driver-specific ioctls. Furthermore actually creating a | |
1115 | buffer object even for GEM-based drivers is done through a | |
1116 | driver-specific ioctl - GEM only has a common userspace interface for | |
1117 | sharing and destroying objects. While not an issue for full-fledged | |
1118 | graphics stacks that include device-specific userspace components (in | |
1119 | libdrm for instance), this limit makes DRM-based early boot graphics | |
1120 | unnecessarily complex. | |
1121 | </para> | |
1122 | <para> | |
1123 | Dumb objects partly alleviate the problem by providing a standard | |
1124 | API to create dumb buffers suitable for scanout, which can then be used | |
1125 | to create KMS frame buffers. | |
1126 | </para> | |
1127 | <para> | |
1128 | To support dumb objects drivers must implement the | |
1129 | <methodname>dumb_create</methodname>, | |
1130 | <methodname>dumb_destroy</methodname> and | |
1131 | <methodname>dumb_map_offset</methodname> operations. | |
1132 | </para> | |
1133 | <itemizedlist> | |
1134 | <listitem> | |
1135 | <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, | |
1136 | struct drm_mode_create_dumb *args);</synopsis> | |
1137 | <para> | |
1138 | The <methodname>dumb_create</methodname> operation creates a driver | |
1139 | object (GEM or TTM handle) suitable for scanout based on the | |
1140 | width, height and depth from the struct | |
1141 | <structname>drm_mode_create_dumb</structname> argument. It fills the | |
1142 | argument's <structfield>handle</structfield>, | |
1143 | <structfield>pitch</structfield> and <structfield>size</structfield> | |
1144 | fields with a handle for the newly created object and its line | |
1145 | pitch and size in bytes. | |
1146 | </para> | |
1147 | </listitem> | |
1148 | <listitem> | |
1149 | <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, | |
1150 | uint32_t handle);</synopsis> | |
1151 | <para> | |
1152 | The <methodname>dumb_destroy</methodname> operation destroys a dumb | |
1153 | object created by <methodname>dumb_create</methodname>. | |
1154 | </para> | |
1155 | </listitem> | |
1156 | <listitem> | |
1157 | <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, | |
1158 | uint32_t handle, uint64_t *offset);</synopsis> | |
1159 | <para> | |
1160 | The <methodname>dumb_map_offset</methodname> operation associates an | |
1161 | mmap fake offset with the object given by the handle and returns | |
1162 | it. Drivers must use the | |
1163 | <function>drm_gem_create_mmap_offset</function> function to | |
1164 | associate the fake offset as described in | |
1165 | <xref linkend="drm-gem-objects-mapping"/>. | |
1166 | </para> | |
1167 | </listitem> | |
1168 | </itemizedlist> | |
1169 | <para> | |
1170 | Note that dumb objects may not be used for gpu acceleration, as has been | |
1171 | attempted on some ARM embedded platforms. Such drivers really must have | |
1172 | a hardware-specific ioctl to allocate suitable buffer objects. | |
1173 | </para> | |
1174 | </sect2> | |
9cad9c95 LP |
1175 | <sect2> |
1176 | <title>Output Polling</title> | |
1177 | <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis> | |
1178 | <para> | |
1179 | This operation notifies the driver that the status of one or more | |
1180 | connectors has changed. Drivers that use the fb helper can just call the | |
1181 | <function>drm_fb_helper_hotplug_event</function> function to handle this | |
1182 | operation. | |
1183 | </para> | |
1184 | </sect2> | |
5d7a9515 DV |
1185 | <sect2> |
1186 | <title>Locking</title> | |
1187 | <para> | |
1188 | Beside some lookup structures with their own locking (which is hidden | |
1189 | behind the interface functions) most of the modeset state is protected | |
1190 | by the <code>dev-<mode_config.lock</code> mutex and additionally | |
1191 | per-crtc locks to allow cursor updates, pageflips and similar operations | |
1192 | to occur concurrently with background tasks like output detection. | |
1193 | Operations which cross domains like a full modeset always grab all | |
1194 | locks. Drivers there need to protect resources shared between crtcs with | |
1195 | additional locking. They also need to be careful to always grab the | |
1196 | relevant crtc locks if a modset functions touches crtc state, e.g. for | |
1197 | load detection (which does only grab the <code>mode_config.lock</code> | |
1198 | to allow concurrent screen updates on live crtcs). | |
1199 | </para> | |
1200 | </sect2> | |
9cad9c95 LP |
1201 | </sect1> |
1202 | ||
1203 | <!-- Internals: kms initialization and cleanup --> | |
1204 | ||
1205 | <sect1 id="drm-kms-init"> | |
1206 | <title>KMS Initialization and Cleanup</title> | |
1207 | <para> | |
1208 | A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders | |
1209 | and connectors. KMS drivers must thus create and initialize all those | |
1210 | objects at load time after initializing mode setting. | |
1211 | </para> | |
1212 | <sect2> | |
1213 | <title>CRTCs (struct <structname>drm_crtc</structname>)</title> | |
1214 | <para> | |
1215 | A CRTC is an abstraction representing a part of the chip that contains a | |
1216 | pointer to a scanout buffer. Therefore, the number of CRTCs available | |
1217 | determines how many independent scanout buffers can be active at any | |
1218 | given time. The CRTC structure contains several fields to support this: | |
1219 | a pointer to some video memory (abstracted as a frame buffer object), a | |
1220 | display mode, and an (x, y) offset into the video memory to support | |
1221 | panning or configurations where one piece of video memory spans multiple | |
1222 | CRTCs. | |
2d2ef822 JB |
1223 | </para> |
1224 | <sect3> | |
9cad9c95 LP |
1225 | <title>CRTC Initialization</title> |
1226 | <para> | |
1227 | A KMS device must create and register at least one struct | |
1228 | <structname>drm_crtc</structname> instance. The instance is allocated | |
1229 | and zeroed by the driver, possibly as part of a larger structure, and | |
1230 | registered with a call to <function>drm_crtc_init</function> with a | |
1231 | pointer to CRTC functions. | |
1232 | </para> | |
1233 | </sect3> | |
6efa1f2f | 1234 | <sect3 id="drm-kms-crtcops"> |
9cad9c95 LP |
1235 | <title>CRTC Operations</title> |
1236 | <sect4> | |
1237 | <title>Set Configuration</title> | |
1238 | <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis> | |
1239 | <para> | |
1240 | Apply a new CRTC configuration to the device. The configuration | |
1241 | specifies a CRTC, a frame buffer to scan out from, a (x,y) position in | |
1242 | the frame buffer, a display mode and an array of connectors to drive | |
1243 | with the CRTC if possible. | |
1244 | </para> | |
1245 | <para> | |
1246 | If the frame buffer specified in the configuration is NULL, the driver | |
1247 | must detach all encoders connected to the CRTC and all connectors | |
1248 | attached to those encoders and disable them. | |
1249 | </para> | |
1250 | <para> | |
1251 | This operation is called with the mode config lock held. | |
1252 | </para> | |
1253 | <note><para> | |
aa4cd910 DV |
1254 | Note that the drm core has no notion of restoring the mode setting |
1255 | state after resume, since all resume handling is in the full | |
1256 | responsibility of the driver. The common mode setting helper library | |
1257 | though provides a helper which can be used for this: | |
1258 | <function>drm_helper_resume_force_mode</function>. | |
9cad9c95 LP |
1259 | </para></note> |
1260 | </sect4> | |
1261 | <sect4> | |
1262 | <title>Page Flipping</title> | |
1263 | <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, | |
1264 | struct drm_pending_vblank_event *event);</synopsis> | |
1265 | <para> | |
1266 | Schedule a page flip to the given frame buffer for the CRTC. This | |
1267 | operation is called with the mode config mutex held. | |
1268 | </para> | |
1269 | <para> | |
1270 | Page flipping is a synchronization mechanism that replaces the frame | |
1271 | buffer being scanned out by the CRTC with a new frame buffer during | |
1272 | vertical blanking, avoiding tearing. When an application requests a page | |
1273 | flip the DRM core verifies that the new frame buffer is large enough to | |
1274 | be scanned out by the CRTC in the currently configured mode and then | |
1275 | calls the CRTC <methodname>page_flip</methodname> operation with a | |
1276 | pointer to the new frame buffer. | |
1277 | </para> | |
1278 | <para> | |
1279 | The <methodname>page_flip</methodname> operation schedules a page flip. | |
f884ab15 | 1280 | Once any pending rendering targeting the new frame buffer has |
9cad9c95 LP |
1281 | completed, the CRTC will be reprogrammed to display that frame buffer |
1282 | after the next vertical refresh. The operation must return immediately | |
1283 | without waiting for rendering or page flip to complete and must block | |
1284 | any new rendering to the frame buffer until the page flip completes. | |
1285 | </para> | |
8cf1e981 TR |
1286 | <para> |
1287 | If a page flip can be successfully scheduled the driver must set the | |
1288 | <code>drm_crtc-<fb</code> field to the new framebuffer pointed to | |
1289 | by <code>fb</code>. This is important so that the reference counting | |
1290 | on framebuffers stays balanced. | |
1291 | </para> | |
9cad9c95 LP |
1292 | <para> |
1293 | If a page flip is already pending, the | |
1294 | <methodname>page_flip</methodname> operation must return | |
1295 | -<errorname>EBUSY</errorname>. | |
1296 | </para> | |
1297 | <para> | |
1298 | To synchronize page flip to vertical blanking the driver will likely | |
1299 | need to enable vertical blanking interrupts. It should call | |
1300 | <function>drm_vblank_get</function> for that purpose, and call | |
1301 | <function>drm_vblank_put</function> after the page flip completes. | |
1302 | </para> | |
1303 | <para> | |
1304 | If the application has requested to be notified when page flip completes | |
1305 | the <methodname>page_flip</methodname> operation will be called with a | |
1306 | non-NULL <parameter>event</parameter> argument pointing to a | |
1307 | <structname>drm_pending_vblank_event</structname> instance. Upon page | |
c6eefa17 RC |
1308 | flip completion the driver must call <methodname>drm_send_vblank_event</methodname> |
1309 | to fill in the event and send to wake up any waiting processes. | |
1310 | This can be performed with | |
9cad9c95 | 1311 | <programlisting><![CDATA[ |
9cad9c95 | 1312 | spin_lock_irqsave(&dev->event_lock, flags); |
c6eefa17 RC |
1313 | ... |
1314 | drm_send_vblank_event(dev, pipe, event); | |
9cad9c95 LP |
1315 | spin_unlock_irqrestore(&dev->event_lock, flags); |
1316 | ]]></programlisting> | |
1317 | </para> | |
1318 | <note><para> | |
1319 | FIXME: Could drivers that don't need to wait for rendering to complete | |
1320 | just add the event to <literal>dev->vblank_event_list</literal> and | |
1321 | let the DRM core handle everything, as for "normal" vertical blanking | |
1322 | events? | |
1323 | </para></note> | |
1324 | <para> | |
1325 | While waiting for the page flip to complete, the | |
1326 | <literal>event->base.link</literal> list head can be used freely by | |
1327 | the driver to store the pending event in a driver-specific list. | |
1328 | </para> | |
1329 | <para> | |
1330 | If the file handle is closed before the event is signaled, drivers must | |
1331 | take care to destroy the event in their | |
1332 | <methodname>preclose</methodname> operation (and, if needed, call | |
1333 | <function>drm_vblank_put</function>). | |
1334 | </para> | |
1335 | </sect4> | |
1336 | <sect4> | |
1337 | <title>Miscellaneous</title> | |
1338 | <itemizedlist> | |
421cda3e LP |
1339 | <listitem> |
1340 | <synopsis>void (*set_property)(struct drm_crtc *crtc, | |
1341 | struct drm_property *property, uint64_t value);</synopsis> | |
1342 | <para> | |
1343 | Set the value of the given CRTC property to | |
1344 | <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> | |
1345 | for more information about properties. | |
1346 | </para> | |
1347 | </listitem> | |
9cad9c95 LP |
1348 | <listitem> |
1349 | <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, | |
1350 | uint32_t start, uint32_t size);</synopsis> | |
1351 | <para> | |
1352 | Apply a gamma table to the device. The operation is optional. | |
1353 | </para> | |
1354 | </listitem> | |
1355 | <listitem> | |
1356 | <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis> | |
1357 | <para> | |
1358 | Destroy the CRTC when not needed anymore. See | |
1359 | <xref linkend="drm-kms-init"/>. | |
1360 | </para> | |
1361 | </listitem> | |
1362 | </itemizedlist> | |
1363 | </sect4> | |
1364 | </sect3> | |
1365 | </sect2> | |
1366 | <sect2> | |
1367 | <title>Planes (struct <structname>drm_plane</structname>)</title> | |
1368 | <para> | |
1369 | A plane represents an image source that can be blended with or overlayed | |
1370 | on top of a CRTC during the scanout process. Planes are associated with | |
1371 | a frame buffer to crop a portion of the image memory (source) and | |
1372 | optionally scale it to a destination size. The result is then blended | |
1373 | with or overlayed on top of a CRTC. | |
1374 | </para> | |
6efa1f2f MR |
1375 | <para> |
1376 | The DRM core recognizes three types of planes: | |
1377 | <itemizedlist> | |
1378 | <listitem> | |
1379 | DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC. Primary | |
1380 | planes are the planes operated upon by by CRTC modesetting and flipping | |
1381 | operations described in <xref linkend="drm-kms-crtcops"/>. | |
1382 | </listitem> | |
1383 | <listitem> | |
1384 | DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC. Cursor | |
1385 | planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and | |
1386 | DRM_IOCTL_MODE_CURSOR2 ioctls. | |
1387 | </listitem> | |
1388 | <listitem> | |
1389 | DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes. | |
1390 | Some drivers refer to these types of planes as "sprites" internally. | |
1391 | </listitem> | |
1392 | </itemizedlist> | |
1393 | For compatibility with legacy userspace, only overlay planes are made | |
1394 | available to userspace by default. Userspace clients may set the | |
1395 | DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that | |
1396 | they wish to receive a universal plane list containing all plane types. | |
1397 | </para> | |
9cad9c95 LP |
1398 | <sect3> |
1399 | <title>Plane Initialization</title> | |
1400 | <para> | |
6efa1f2f | 1401 | To create a plane, a KMS drivers allocates and |
9cad9c95 LP |
1402 | zeroes an instances of struct <structname>drm_plane</structname> |
1403 | (possibly as part of a larger structure) and registers it with a call | |
6efa1f2f | 1404 | to <function>drm_universal_plane_init</function>. The function takes a bitmask |
9cad9c95 | 1405 | of the CRTCs that can be associated with the plane, a pointer to the |
6efa1f2f MR |
1406 | plane functions, a list of format supported formats, and the type of |
1407 | plane (primary, cursor, or overlay) being initialized. | |
1408 | </para> | |
1409 | <para> | |
1410 | Cursor and overlay planes are optional. All drivers should provide | |
1411 | one primary plane per CRTC (although this requirement may change in | |
1412 | the future); drivers that do not wish to provide special handling for | |
1413 | primary planes may make use of the helper functions described in | |
1414 | <xref linkend="drm-kms-planehelpers"/> to create and register a | |
1415 | primary plane with standard capabilities. | |
9cad9c95 LP |
1416 | </para> |
1417 | </sect3> | |
1418 | <sect3> | |
1419 | <title>Plane Operations</title> | |
1420 | <itemizedlist> | |
1421 | <listitem> | |
1422 | <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, | |
1423 | struct drm_framebuffer *fb, int crtc_x, int crtc_y, | |
1424 | unsigned int crtc_w, unsigned int crtc_h, | |
1425 | uint32_t src_x, uint32_t src_y, | |
1426 | uint32_t src_w, uint32_t src_h);</synopsis> | |
1427 | <para> | |
1428 | Enable and configure the plane to use the given CRTC and frame buffer. | |
1429 | </para> | |
1430 | <para> | |
1431 | The source rectangle in frame buffer memory coordinates is given by | |
1432 | the <parameter>src_x</parameter>, <parameter>src_y</parameter>, | |
1433 | <parameter>src_w</parameter> and <parameter>src_h</parameter> | |
1434 | parameters (as 16.16 fixed point values). Devices that don't support | |
1435 | subpixel plane coordinates can ignore the fractional part. | |
1436 | </para> | |
1437 | <para> | |
1438 | The destination rectangle in CRTC coordinates is given by the | |
1439 | <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>, | |
1440 | <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter> | |
1441 | parameters (as integer values). Devices scale the source rectangle to | |
1442 | the destination rectangle. If scaling is not supported, and the source | |
1443 | rectangle size doesn't match the destination rectangle size, the | |
1444 | driver must return a -<errorname>EINVAL</errorname> error. | |
1445 | </para> | |
1446 | </listitem> | |
1447 | <listitem> | |
1448 | <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis> | |
1449 | <para> | |
1450 | Disable the plane. The DRM core calls this method in response to a | |
1451 | DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. | |
1452 | Disabled planes must not be processed by the CRTC. | |
1453 | </para> | |
1454 | </listitem> | |
1455 | <listitem> | |
1456 | <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis> | |
1457 | <para> | |
1458 | Destroy the plane when not needed anymore. See | |
1459 | <xref linkend="drm-kms-init"/>. | |
1460 | </para> | |
1461 | </listitem> | |
1462 | </itemizedlist> | |
1463 | </sect3> | |
1464 | </sect2> | |
1465 | <sect2> | |
1466 | <title>Encoders (struct <structname>drm_encoder</structname>)</title> | |
1467 | <para> | |
1468 | An encoder takes pixel data from a CRTC and converts it to a format | |
1469 | suitable for any attached connectors. On some devices, it may be | |
1470 | possible to have a CRTC send data to more than one encoder. In that | |
1471 | case, both encoders would receive data from the same scanout buffer, | |
1472 | resulting in a "cloned" display configuration across the connectors | |
1473 | attached to each encoder. | |
1474 | </para> | |
1475 | <sect3> | |
1476 | <title>Encoder Initialization</title> | |
1477 | <para> | |
1478 | As for CRTCs, a KMS driver must create, initialize and register at | |
1479 | least one struct <structname>drm_encoder</structname> instance. The | |
1480 | instance is allocated and zeroed by the driver, possibly as part of a | |
1481 | larger structure. | |
1482 | </para> | |
1483 | <para> | |
1484 | Drivers must initialize the struct <structname>drm_encoder</structname> | |
1485 | <structfield>possible_crtcs</structfield> and | |
1486 | <structfield>possible_clones</structfield> fields before registering the | |
1487 | encoder. Both fields are bitmasks of respectively the CRTCs that the | |
1488 | encoder can be connected to, and sibling encoders candidate for cloning. | |
1489 | </para> | |
1490 | <para> | |
1491 | After being initialized, the encoder must be registered with a call to | |
1492 | <function>drm_encoder_init</function>. The function takes a pointer to | |
1493 | the encoder functions and an encoder type. Supported types are | |
1494 | <itemizedlist> | |
1495 | <listitem> | |
1496 | DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A | |
1497 | </listitem> | |
1498 | <listitem> | |
1499 | DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort | |
1500 | </listitem> | |
1501 | <listitem> | |
1502 | DRM_MODE_ENCODER_LVDS for display panels | |
1503 | </listitem> | |
1504 | <listitem> | |
1505 | DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component, | |
1506 | SCART) | |
1507 | </listitem> | |
1508 | <listitem> | |
1509 | DRM_MODE_ENCODER_VIRTUAL for virtual machine displays | |
1510 | </listitem> | |
1511 | </itemizedlist> | |
1512 | </para> | |
1513 | <para> | |
1514 | Encoders must be attached to a CRTC to be used. DRM drivers leave | |
1515 | encoders unattached at initialization time. Applications (or the fbdev | |
1516 | compatibility layer when implemented) are responsible for attaching the | |
1517 | encoders they want to use to a CRTC. | |
1518 | </para> | |
1519 | </sect3> | |
1520 | <sect3> | |
1521 | <title>Encoder Operations</title> | |
1522 | <itemizedlist> | |
1523 | <listitem> | |
1524 | <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis> | |
1525 | <para> | |
1526 | Called to destroy the encoder when not needed anymore. See | |
1527 | <xref linkend="drm-kms-init"/>. | |
1528 | </para> | |
1529 | </listitem> | |
421cda3e LP |
1530 | <listitem> |
1531 | <synopsis>void (*set_property)(struct drm_plane *plane, | |
1532 | struct drm_property *property, uint64_t value);</synopsis> | |
1533 | <para> | |
1534 | Set the value of the given plane property to | |
1535 | <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> | |
1536 | for more information about properties. | |
1537 | </para> | |
1538 | </listitem> | |
9cad9c95 LP |
1539 | </itemizedlist> |
1540 | </sect3> | |
1541 | </sect2> | |
1542 | <sect2> | |
1543 | <title>Connectors (struct <structname>drm_connector</structname>)</title> | |
1544 | <para> | |
1545 | A connector is the final destination for pixel data on a device, and | |
1546 | usually connects directly to an external display device like a monitor | |
1547 | or laptop panel. A connector can only be attached to one encoder at a | |
1548 | time. The connector is also the structure where information about the | |
1549 | attached display is kept, so it contains fields for display data, EDID | |
1550 | data, DPMS & connection status, and information about modes | |
1551 | supported on the attached displays. | |
1552 | </para> | |
1553 | <sect3> | |
1554 | <title>Connector Initialization</title> | |
1555 | <para> | |
1556 | Finally a KMS driver must create, initialize, register and attach at | |
1557 | least one struct <structname>drm_connector</structname> instance. The | |
1558 | instance is created as other KMS objects and initialized by setting the | |
1559 | following fields. | |
1560 | </para> | |
1561 | <variablelist> | |
1562 | <varlistentry> | |
1563 | <term><structfield>interlace_allowed</structfield></term> | |
1564 | <listitem><para> | |
1565 | Whether the connector can handle interlaced modes. | |
1566 | </para></listitem> | |
1567 | </varlistentry> | |
1568 | <varlistentry> | |
1569 | <term><structfield>doublescan_allowed</structfield></term> | |
1570 | <listitem><para> | |
1571 | Whether the connector can handle doublescan. | |
1572 | </para></listitem> | |
1573 | </varlistentry> | |
1574 | <varlistentry> | |
1575 | <term><structfield>display_info | |
1576 | </structfield></term> | |
1577 | <listitem><para> | |
1578 | Display information is filled from EDID information when a display | |
1579 | is detected. For non hot-pluggable displays such as flat panels in | |
1580 | embedded systems, the driver should initialize the | |
1581 | <structfield>display_info</structfield>.<structfield>width_mm</structfield> | |
1582 | and | |
1583 | <structfield>display_info</structfield>.<structfield>height_mm</structfield> | |
1584 | fields with the physical size of the display. | |
1585 | </para></listitem> | |
1586 | </varlistentry> | |
1587 | <varlistentry> | |
1588 | <term id="drm-kms-connector-polled"><structfield>polled</structfield></term> | |
1589 | <listitem><para> | |
1590 | Connector polling mode, a combination of | |
1591 | <variablelist> | |
1592 | <varlistentry> | |
1593 | <term>DRM_CONNECTOR_POLL_HPD</term> | |
1594 | <listitem><para> | |
1595 | The connector generates hotplug events and doesn't need to be | |
1596 | periodically polled. The CONNECT and DISCONNECT flags must not | |
1597 | be set together with the HPD flag. | |
1598 | </para></listitem> | |
1599 | </varlistentry> | |
1600 | <varlistentry> | |
1601 | <term>DRM_CONNECTOR_POLL_CONNECT</term> | |
1602 | <listitem><para> | |
1603 | Periodically poll the connector for connection. | |
1604 | </para></listitem> | |
1605 | </varlistentry> | |
1606 | <varlistentry> | |
1607 | <term>DRM_CONNECTOR_POLL_DISCONNECT</term> | |
1608 | <listitem><para> | |
1609 | Periodically poll the connector for disconnection. | |
1610 | </para></listitem> | |
1611 | </varlistentry> | |
1612 | </variablelist> | |
1613 | Set to 0 for connectors that don't support connection status | |
1614 | discovery. | |
1615 | </para></listitem> | |
1616 | </varlistentry> | |
1617 | </variablelist> | |
1618 | <para> | |
1619 | The connector is then registered with a call to | |
1620 | <function>drm_connector_init</function> with a pointer to the connector | |
1621 | functions and a connector type, and exposed through sysfs with a call to | |
34ea3d38 | 1622 | <function>drm_connector_register</function>. |
9cad9c95 LP |
1623 | </para> |
1624 | <para> | |
1625 | Supported connector types are | |
1626 | <itemizedlist> | |
1627 | <listitem>DRM_MODE_CONNECTOR_VGA</listitem> | |
1628 | <listitem>DRM_MODE_CONNECTOR_DVII</listitem> | |
1629 | <listitem>DRM_MODE_CONNECTOR_DVID</listitem> | |
1630 | <listitem>DRM_MODE_CONNECTOR_DVIA</listitem> | |
1631 | <listitem>DRM_MODE_CONNECTOR_Composite</listitem> | |
1632 | <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem> | |
1633 | <listitem>DRM_MODE_CONNECTOR_LVDS</listitem> | |
1634 | <listitem>DRM_MODE_CONNECTOR_Component</listitem> | |
1635 | <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem> | |
1636 | <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem> | |
1637 | <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem> | |
1638 | <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem> | |
1639 | <listitem>DRM_MODE_CONNECTOR_TV</listitem> | |
1640 | <listitem>DRM_MODE_CONNECTOR_eDP</listitem> | |
1641 | <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem> | |
1642 | </itemizedlist> | |
1643 | </para> | |
1644 | <para> | |
1645 | Connectors must be attached to an encoder to be used. For devices that | |
1646 | map connectors to encoders 1:1, the connector should be attached at | |
1647 | initialization time with a call to | |
1648 | <function>drm_mode_connector_attach_encoder</function>. The driver must | |
1649 | also set the <structname>drm_connector</structname> | |
1650 | <structfield>encoder</structfield> field to point to the attached | |
1651 | encoder. | |
1652 | </para> | |
1653 | <para> | |
1654 | Finally, drivers must initialize the connectors state change detection | |
1655 | with a call to <function>drm_kms_helper_poll_init</function>. If at | |
1656 | least one connector is pollable but can't generate hotplug interrupts | |
1657 | (indicated by the DRM_CONNECTOR_POLL_CONNECT and | |
1658 | DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will | |
1659 | automatically be queued to periodically poll for changes. Connectors | |
1660 | that can generate hotplug interrupts must be marked with the | |
1661 | DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must | |
1662 | call <function>drm_helper_hpd_irq_event</function>. The function will | |
1663 | queue a delayed work to check the state of all connectors, but no | |
1664 | periodic polling will be done. | |
1665 | </para> | |
1666 | </sect3> | |
1667 | <sect3> | |
1668 | <title>Connector Operations</title> | |
1669 | <note><para> | |
1670 | Unless otherwise state, all operations are mandatory. | |
1671 | </para></note> | |
1672 | <sect4> | |
1673 | <title>DPMS</title> | |
1674 | <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis> | |
1675 | <para> | |
1676 | The DPMS operation sets the power state of a connector. The mode | |
1677 | argument is one of | |
1678 | <itemizedlist> | |
1679 | <listitem><para>DRM_MODE_DPMS_ON</para></listitem> | |
1680 | <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem> | |
1681 | <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem> | |
1682 | <listitem><para>DRM_MODE_DPMS_OFF</para></listitem> | |
1683 | </itemizedlist> | |
1684 | </para> | |
1685 | <para> | |
1686 | In all but DPMS_ON mode the encoder to which the connector is attached | |
1687 | should put the display in low-power mode by driving its signals | |
1688 | appropriately. If more than one connector is attached to the encoder | |
1689 | care should be taken not to change the power state of other displays as | |
1690 | a side effect. Low-power mode should be propagated to the encoders and | |
1691 | CRTCs when all related connectors are put in low-power mode. | |
1692 | </para> | |
1693 | </sect4> | |
1694 | <sect4> | |
1695 | <title>Modes</title> | |
1696 | <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, | |
1697 | uint32_t max_height);</synopsis> | |
1698 | <para> | |
1699 | Fill the mode list with all supported modes for the connector. If the | |
1700 | <parameter>max_width</parameter> and <parameter>max_height</parameter> | |
1701 | arguments are non-zero, the implementation must ignore all modes wider | |
1702 | than <parameter>max_width</parameter> or higher than | |
1703 | <parameter>max_height</parameter>. | |
1704 | </para> | |
1705 | <para> | |
1706 | The connector must also fill in this operation its | |
1707 | <structfield>display_info</structfield> | |
1708 | <structfield>width_mm</structfield> and | |
1709 | <structfield>height_mm</structfield> fields with the connected display | |
1710 | physical size in millimeters. The fields should be set to 0 if the value | |
1711 | isn't known or is not applicable (for instance for projector devices). | |
1712 | </para> | |
1713 | </sect4> | |
1714 | <sect4> | |
1715 | <title>Connection Status</title> | |
1716 | <para> | |
1717 | The connection status is updated through polling or hotplug events when | |
1718 | supported (see <xref linkend="drm-kms-connector-polled"/>). The status | |
1719 | value is reported to userspace through ioctls and must not be used | |
1720 | inside the driver, as it only gets initialized by a call to | |
1721 | <function>drm_mode_getconnector</function> from userspace. | |
1722 | </para> | |
1723 | <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector, | |
1724 | bool force);</synopsis> | |
1725 | <para> | |
1726 | Check to see if anything is attached to the connector. The | |
1727 | <parameter>force</parameter> parameter is set to false whilst polling or | |
1728 | to true when checking the connector due to user request. | |
1729 | <parameter>force</parameter> can be used by the driver to avoid | |
1730 | expensive, destructive operations during automated probing. | |
1731 | </para> | |
1732 | <para> | |
1733 | Return connector_status_connected if something is connected to the | |
1734 | connector, connector_status_disconnected if nothing is connected and | |
1735 | connector_status_unknown if the connection state isn't known. | |
1736 | </para> | |
1737 | <para> | |
1738 | Drivers should only return connector_status_connected if the connection | |
1739 | status has really been probed as connected. Connectors that can't detect | |
1740 | the connection status, or failed connection status probes, should return | |
1741 | connector_status_unknown. | |
1742 | </para> | |
1743 | </sect4> | |
1744 | <sect4> | |
1745 | <title>Miscellaneous</title> | |
1746 | <itemizedlist> | |
421cda3e LP |
1747 | <listitem> |
1748 | <synopsis>void (*set_property)(struct drm_connector *connector, | |
1749 | struct drm_property *property, uint64_t value);</synopsis> | |
1750 | <para> | |
1751 | Set the value of the given connector property to | |
1752 | <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> | |
1753 | for more information about properties. | |
1754 | </para> | |
1755 | </listitem> | |
9cad9c95 LP |
1756 | <listitem> |
1757 | <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis> | |
1758 | <para> | |
1759 | Destroy the connector when not needed anymore. See | |
1760 | <xref linkend="drm-kms-init"/>. | |
1761 | </para> | |
1762 | </listitem> | |
1763 | </itemizedlist> | |
1764 | </sect4> | |
1765 | </sect3> | |
1766 | </sect2> | |
1767 | <sect2> | |
1768 | <title>Cleanup</title> | |
1769 | <para> | |
1770 | The DRM core manages its objects' lifetime. When an object is not needed | |
1771 | anymore the core calls its destroy function, which must clean up and | |
1772 | free every resource allocated for the object. Every | |
1773 | <function>drm_*_init</function> call must be matched with a | |
1774 | corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs | |
1775 | (<function>drm_crtc_cleanup</function>), planes | |
1776 | (<function>drm_plane_cleanup</function>), encoders | |
1777 | (<function>drm_encoder_cleanup</function>) and connectors | |
1778 | (<function>drm_connector_cleanup</function>). Furthermore, connectors | |
1779 | that have been added to sysfs must be removed by a call to | |
34ea3d38 | 1780 | <function>drm_connector_unregister</function> before calling |
9cad9c95 LP |
1781 | <function>drm_connector_cleanup</function>. |
1782 | </para> | |
1783 | <para> | |
1784 | Connectors state change detection must be cleanup up with a call to | |
1785 | <function>drm_kms_helper_poll_fini</function>. | |
1786 | </para> | |
1787 | </sect2> | |
1788 | <sect2> | |
1789 | <title>Output discovery and initialization example</title> | |
1790 | <programlisting><![CDATA[ | |
2d2ef822 JB |
1791 | void intel_crt_init(struct drm_device *dev) |
1792 | { | |
1793 | struct drm_connector *connector; | |
1794 | struct intel_output *intel_output; | |
1795 | ||
1796 | intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL); | |
1797 | if (!intel_output) | |
1798 | return; | |
1799 | ||
1800 | connector = &intel_output->base; | |
1801 | drm_connector_init(dev, &intel_output->base, | |
1802 | &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA); | |
1803 | ||
1804 | drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs, | |
1805 | DRM_MODE_ENCODER_DAC); | |
1806 | ||
1807 | drm_mode_connector_attach_encoder(&intel_output->base, | |
1808 | &intel_output->enc); | |
1809 | ||
1810 | /* Set up the DDC bus. */ | |
1811 | intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A"); | |
1812 | if (!intel_output->ddc_bus) { | |
1813 | dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration " | |
1814 | "failed.\n"); | |
1815 | return; | |
1816 | } | |
1817 | ||
1818 | intel_output->type = INTEL_OUTPUT_ANALOG; | |
1819 | connector->interlace_allowed = 0; | |
1820 | connector->doublescan_allowed = 0; | |
1821 | ||
1822 | drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs); | |
1823 | drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); | |
1824 | ||
34ea3d38 | 1825 | drm_connector_register(connector); |
9cad9c95 LP |
1826 | }]]></programlisting> |
1827 | <para> | |
1828 | In the example above (taken from the i915 driver), a CRTC, connector and | |
1829 | encoder combination is created. A device-specific i2c bus is also | |
1830 | created for fetching EDID data and performing monitor detection. Once | |
1831 | the process is complete, the new connector is registered with sysfs to | |
1832 | make its properties available to applications. | |
1833 | </para> | |
2d2ef822 | 1834 | </sect2> |
065a50ed DV |
1835 | <sect2> |
1836 | <title>KMS API Functions</title> | |
1837 | !Edrivers/gpu/drm/drm_crtc.c | |
3bf0401c DV |
1838 | </sect2> |
1839 | <sect2> | |
1840 | <title>KMS Data Structures</title> | |
1841 | !Iinclude/drm/drm_crtc.h | |
065a50ed | 1842 | </sect2> |
51fd371b RC |
1843 | <sect2> |
1844 | <title>KMS Locking</title> | |
1845 | !Pdrivers/gpu/drm/drm_modeset_lock.c kms locking | |
1846 | !Iinclude/drm/drm_modeset_lock.h | |
1847 | !Edrivers/gpu/drm/drm_modeset_lock.c | |
1848 | </sect2> | |
2d2ef822 JB |
1849 | </sect1> |
1850 | ||
e4949f29 | 1851 | <!-- Internals: kms helper functions --> |
2d2ef822 JB |
1852 | |
1853 | <sect1> | |
e4949f29 | 1854 | <title>Mode Setting Helper Functions</title> |
2d2ef822 | 1855 | <para> |
6efa1f2f | 1856 | The plane, CRTC, encoder and connector functions provided by the drivers |
9cad9c95 LP |
1857 | implement the DRM API. They're called by the DRM core and ioctl handlers |
1858 | to handle device state changes and configuration request. As implementing | |
1859 | those functions often requires logic not specific to drivers, mid-layer | |
1860 | helper functions are available to avoid duplicating boilerplate code. | |
1861 | </para> | |
1862 | <para> | |
1863 | The DRM core contains one mid-layer implementation. The mid-layer provides | |
6efa1f2f MR |
1864 | implementations of several plane, CRTC, encoder and connector functions |
1865 | (called from the top of the mid-layer) that pre-process requests and call | |
9cad9c95 LP |
1866 | lower-level functions provided by the driver (at the bottom of the |
1867 | mid-layer). For instance, the | |
1868 | <function>drm_crtc_helper_set_config</function> function can be used to | |
1869 | fill the struct <structname>drm_crtc_funcs</structname> | |
1870 | <structfield>set_config</structfield> field. When called, it will split | |
1871 | the <methodname>set_config</methodname> operation in smaller, simpler | |
1872 | operations and call the driver to handle them. | |
2d2ef822 | 1873 | </para> |
2d2ef822 | 1874 | <para> |
9cad9c95 LP |
1875 | To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>, |
1876 | <function>drm_encoder_helper_add</function> and | |
1877 | <function>drm_connector_helper_add</function> functions to install their | |
1878 | mid-layer bottom operations handlers, and fill the | |
1879 | <structname>drm_crtc_funcs</structname>, | |
1880 | <structname>drm_encoder_funcs</structname> and | |
1881 | <structname>drm_connector_funcs</structname> structures with pointers to | |
1882 | the mid-layer top API functions. Installing the mid-layer bottom operation | |
1883 | handlers is best done right after registering the corresponding KMS object. | |
2d2ef822 JB |
1884 | </para> |
1885 | <para> | |
9cad9c95 LP |
1886 | The mid-layer is not split between CRTC, encoder and connector operations. |
1887 | To use it, a driver must provide bottom functions for all of the three KMS | |
1888 | entities. | |
2d2ef822 | 1889 | </para> |
9cad9c95 LP |
1890 | <sect2> |
1891 | <title>Helper Functions</title> | |
1892 | <itemizedlist> | |
1893 | <listitem> | |
1894 | <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis> | |
1895 | <para> | |
1896 | The <function>drm_crtc_helper_set_config</function> helper function | |
1897 | is a CRTC <methodname>set_config</methodname> implementation. It | |
1898 | first tries to locate the best encoder for each connector by calling | |
1899 | the connector <methodname>best_encoder</methodname> helper | |
1900 | operation. | |
1901 | </para> | |
1902 | <para> | |
1903 | After locating the appropriate encoders, the helper function will | |
1904 | call the <methodname>mode_fixup</methodname> encoder and CRTC helper | |
1905 | operations to adjust the requested mode, or reject it completely in | |
1906 | which case an error will be returned to the application. If the new | |
1907 | configuration after mode adjustment is identical to the current | |
1908 | configuration the helper function will return without performing any | |
1909 | other operation. | |
1910 | </para> | |
1911 | <para> | |
1912 | If the adjusted mode is identical to the current mode but changes to | |
1913 | the frame buffer need to be applied, the | |
1914 | <function>drm_crtc_helper_set_config</function> function will call | |
1915 | the CRTC <methodname>mode_set_base</methodname> helper operation. If | |
1916 | the adjusted mode differs from the current mode, or if the | |
1917 | <methodname>mode_set_base</methodname> helper operation is not | |
1918 | provided, the helper function performs a full mode set sequence by | |
1919 | calling the <methodname>prepare</methodname>, | |
1920 | <methodname>mode_set</methodname> and | |
1921 | <methodname>commit</methodname> CRTC and encoder helper operations, | |
1922 | in that order. | |
1923 | </para> | |
1924 | </listitem> | |
1925 | <listitem> | |
1926 | <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis> | |
1927 | <para> | |
1928 | The <function>drm_helper_connector_dpms</function> helper function | |
1929 | is a connector <methodname>dpms</methodname> implementation that | |
1930 | tracks power state of connectors. To use the function, drivers must | |
1931 | provide <methodname>dpms</methodname> helper operations for CRTCs | |
1932 | and encoders to apply the DPMS state to the device. | |
1933 | </para> | |
1934 | <para> | |
1935 | The mid-layer doesn't track the power state of CRTCs and encoders. | |
1936 | The <methodname>dpms</methodname> helper operations can thus be | |
1937 | called with a mode identical to the currently active mode. | |
1938 | </para> | |
1939 | </listitem> | |
1940 | <listitem> | |
1941 | <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector, | |
1942 | uint32_t maxX, uint32_t maxY);</synopsis> | |
1943 | <para> | |
1944 | The <function>drm_helper_probe_single_connector_modes</function> helper | |
1945 | function is a connector <methodname>fill_modes</methodname> | |
1946 | implementation that updates the connection status for the connector | |
1947 | and then retrieves a list of modes by calling the connector | |
1948 | <methodname>get_modes</methodname> helper operation. | |
1949 | </para> | |
1950 | <para> | |
1951 | The function filters out modes larger than | |
1952 | <parameter>max_width</parameter> and <parameter>max_height</parameter> | |
f9b0e251 AH |
1953 | if specified. It then calls the optional connector |
1954 | <methodname>mode_valid</methodname> helper operation for each mode in | |
9cad9c95 LP |
1955 | the probed list to check whether the mode is valid for the connector. |
1956 | </para> | |
1957 | </listitem> | |
1958 | </itemizedlist> | |
1959 | </sect2> | |
1960 | <sect2> | |
1961 | <title>CRTC Helper Operations</title> | |
1962 | <itemizedlist> | |
1963 | <listitem id="drm-helper-crtc-mode-fixup"> | |
1964 | <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc, | |
1965 | const struct drm_display_mode *mode, | |
1966 | struct drm_display_mode *adjusted_mode);</synopsis> | |
1967 | <para> | |
1968 | Let CRTCs adjust the requested mode or reject it completely. This | |
1969 | operation returns true if the mode is accepted (possibly after being | |
1970 | adjusted) or false if it is rejected. | |
1971 | </para> | |
1972 | <para> | |
1973 | The <methodname>mode_fixup</methodname> operation should reject the | |
1974 | mode if it can't reasonably use it. The definition of "reasonable" | |
1975 | is currently fuzzy in this context. One possible behaviour would be | |
1976 | to set the adjusted mode to the panel timings when a fixed-mode | |
1977 | panel is used with hardware capable of scaling. Another behaviour | |
1978 | would be to accept any input mode and adjust it to the closest mode | |
1979 | supported by the hardware (FIXME: This needs to be clarified). | |
1980 | </para> | |
1981 | </listitem> | |
1982 | <listitem> | |
1983 | <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, | |
1984 | struct drm_framebuffer *old_fb)</synopsis> | |
1985 | <para> | |
1986 | Move the CRTC on the current frame buffer (stored in | |
1987 | <literal>crtc->fb</literal>) to position (x,y). Any of the frame | |
1988 | buffer, x position or y position may have been modified. | |
1989 | </para> | |
1990 | <para> | |
1991 | This helper operation is optional. If not provided, the | |
1992 | <function>drm_crtc_helper_set_config</function> function will fall | |
1993 | back to the <methodname>mode_set</methodname> helper operation. | |
1994 | </para> | |
1995 | <note><para> | |
1996 | FIXME: Why are x and y passed as arguments, as they can be accessed | |
1997 | through <literal>crtc->x</literal> and | |
1998 | <literal>crtc->y</literal>? | |
1999 | </para></note> | |
2000 | </listitem> | |
2001 | <listitem> | |
2002 | <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis> | |
2003 | <para> | |
2004 | Prepare the CRTC for mode setting. This operation is called after | |
2005 | validating the requested mode. Drivers use it to perform | |
2006 | device-specific operations required before setting the new mode. | |
2007 | </para> | |
2008 | </listitem> | |
2009 | <listitem> | |
2010 | <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, | |
2011 | struct drm_display_mode *adjusted_mode, int x, int y, | |
2012 | struct drm_framebuffer *old_fb);</synopsis> | |
2013 | <para> | |
2014 | Set a new mode, position and frame buffer. Depending on the device | |
2015 | requirements, the mode can be stored internally by the driver and | |
2016 | applied in the <methodname>commit</methodname> operation, or | |
2017 | programmed to the hardware immediately. | |
2018 | </para> | |
2019 | <para> | |
2020 | The <methodname>mode_set</methodname> operation returns 0 on success | |
2021 | or a negative error code if an error occurs. | |
2022 | </para> | |
2023 | </listitem> | |
2024 | <listitem> | |
2025 | <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis> | |
2026 | <para> | |
2027 | Commit a mode. This operation is called after setting the new mode. | |
2028 | Upon return the device must use the new mode and be fully | |
2029 | operational. | |
2030 | </para> | |
2031 | </listitem> | |
2032 | </itemizedlist> | |
2033 | </sect2> | |
2034 | <sect2> | |
2035 | <title>Encoder Helper Operations</title> | |
2036 | <itemizedlist> | |
2037 | <listitem> | |
2038 | <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder, | |
2039 | const struct drm_display_mode *mode, | |
2040 | struct drm_display_mode *adjusted_mode);</synopsis> | |
9cad9c95 LP |
2041 | <para> |
2042 | Let encoders adjust the requested mode or reject it completely. This | |
2043 | operation returns true if the mode is accepted (possibly after being | |
2044 | adjusted) or false if it is rejected. See the | |
2045 | <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper | |
2046 | operation</link> for an explanation of the allowed adjustments. | |
2047 | </para> | |
2048 | </listitem> | |
2049 | <listitem> | |
2050 | <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis> | |
2051 | <para> | |
2052 | Prepare the encoder for mode setting. This operation is called after | |
2053 | validating the requested mode. Drivers use it to perform | |
2054 | device-specific operations required before setting the new mode. | |
2055 | </para> | |
2056 | </listitem> | |
2057 | <listitem> | |
2058 | <synopsis>void (*mode_set)(struct drm_encoder *encoder, | |
2059 | struct drm_display_mode *mode, | |
2060 | struct drm_display_mode *adjusted_mode);</synopsis> | |
2061 | <para> | |
2062 | Set a new mode. Depending on the device requirements, the mode can | |
2063 | be stored internally by the driver and applied in the | |
2064 | <methodname>commit</methodname> operation, or programmed to the | |
2065 | hardware immediately. | |
2066 | </para> | |
2067 | </listitem> | |
2068 | <listitem> | |
2069 | <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis> | |
2070 | <para> | |
2071 | Commit a mode. This operation is called after setting the new mode. | |
2072 | Upon return the device must use the new mode and be fully | |
2073 | operational. | |
2074 | </para> | |
2075 | </listitem> | |
2076 | </itemizedlist> | |
2077 | </sect2> | |
2078 | <sect2> | |
2079 | <title>Connector Helper Operations</title> | |
2080 | <itemizedlist> | |
2081 | <listitem> | |
2082 | <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis> | |
2083 | <para> | |
2084 | Return a pointer to the best encoder for the connecter. Device that | |
2085 | map connectors to encoders 1:1 simply return the pointer to the | |
2086 | associated encoder. This operation is mandatory. | |
2087 | </para> | |
2088 | </listitem> | |
2089 | <listitem> | |
2090 | <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis> | |
2091 | <para> | |
2092 | Fill the connector's <structfield>probed_modes</structfield> list | |
2093 | by parsing EDID data with <function>drm_add_edid_modes</function> or | |
2094 | calling <function>drm_mode_probed_add</function> directly for every | |
2095 | supported mode and return the number of modes it has detected. This | |
2096 | operation is mandatory. | |
2097 | </para> | |
2098 | <para> | |
2099 | When adding modes manually the driver creates each mode with a call to | |
2100 | <function>drm_mode_create</function> and must fill the following fields. | |
2101 | <itemizedlist> | |
2102 | <listitem> | |
2103 | <synopsis>__u32 type;</synopsis> | |
2104 | <para> | |
2105 | Mode type bitmask, a combination of | |
2106 | <variablelist> | |
2107 | <varlistentry> | |
2108 | <term>DRM_MODE_TYPE_BUILTIN</term> | |
2109 | <listitem><para>not used?</para></listitem> | |
2110 | </varlistentry> | |
2111 | <varlistentry> | |
2112 | <term>DRM_MODE_TYPE_CLOCK_C</term> | |
2113 | <listitem><para>not used?</para></listitem> | |
2114 | </varlistentry> | |
2115 | <varlistentry> | |
2116 | <term>DRM_MODE_TYPE_CRTC_C</term> | |
2117 | <listitem><para>not used?</para></listitem> | |
2118 | </varlistentry> | |
2119 | <varlistentry> | |
2120 | <term> | |
2121 | DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector | |
2122 | </term> | |
2123 | <listitem> | |
2124 | <para>not used?</para> | |
2125 | </listitem> | |
2126 | </varlistentry> | |
2127 | <varlistentry> | |
2128 | <term>DRM_MODE_TYPE_DEFAULT</term> | |
2129 | <listitem><para>not used?</para></listitem> | |
2130 | </varlistentry> | |
2131 | <varlistentry> | |
2132 | <term>DRM_MODE_TYPE_USERDEF</term> | |
2133 | <listitem><para>not used?</para></listitem> | |
2134 | </varlistentry> | |
2135 | <varlistentry> | |
2136 | <term>DRM_MODE_TYPE_DRIVER</term> | |
2137 | <listitem> | |
2138 | <para> | |
2139 | The mode has been created by the driver (as opposed to | |
2140 | to user-created modes). | |
2141 | </para> | |
2142 | </listitem> | |
2143 | </varlistentry> | |
2144 | </variablelist> | |
2145 | Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they | |
2146 | create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred | |
2147 | mode. | |
2148 | </para> | |
2149 | </listitem> | |
2150 | <listitem> | |
2151 | <synopsis>__u32 clock;</synopsis> | |
2152 | <para>Pixel clock frequency in kHz unit</para> | |
2153 | </listitem> | |
2154 | <listitem> | |
2155 | <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal; | |
2156 | __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis> | |
2157 | <para>Horizontal and vertical timing information</para> | |
2158 | <screen><![CDATA[ | |
2159 | Active Front Sync Back | |
2160 | Region Porch Porch | |
2161 | <-----------------------><----------------><-------------><--------------> | |
2162 | ||
2163 | //////////////////////| | |
2164 | ////////////////////// | | |
2165 | ////////////////////// |.................. ................ | |
2166 | _______________ | |
2167 | ||
2168 | <----- [hv]display -----> | |
2169 | <------------- [hv]sync_start ------------> | |
2170 | <--------------------- [hv]sync_end ---------------------> | |
2171 | <-------------------------------- [hv]total -----------------------------> | |
2172 | ]]></screen> | |
2173 | </listitem> | |
2174 | <listitem> | |
2175 | <synopsis>__u16 hskew; | |
2176 | __u16 vscan;</synopsis> | |
2177 | <para>Unknown</para> | |
2178 | </listitem> | |
2179 | <listitem> | |
2180 | <synopsis>__u32 flags;</synopsis> | |
2181 | <para> | |
2182 | Mode flags, a combination of | |
2183 | <variablelist> | |
2184 | <varlistentry> | |
2185 | <term>DRM_MODE_FLAG_PHSYNC</term> | |
2186 | <listitem><para> | |
2187 | Horizontal sync is active high | |
2188 | </para></listitem> | |
2189 | </varlistentry> | |
2190 | <varlistentry> | |
2191 | <term>DRM_MODE_FLAG_NHSYNC</term> | |
2192 | <listitem><para> | |
2193 | Horizontal sync is active low | |
2194 | </para></listitem> | |
2195 | </varlistentry> | |
2196 | <varlistentry> | |
2197 | <term>DRM_MODE_FLAG_PVSYNC</term> | |
2198 | <listitem><para> | |
2199 | Vertical sync is active high | |
2200 | </para></listitem> | |
2201 | </varlistentry> | |
2202 | <varlistentry> | |
2203 | <term>DRM_MODE_FLAG_NVSYNC</term> | |
2204 | <listitem><para> | |
2205 | Vertical sync is active low | |
2206 | </para></listitem> | |
2207 | </varlistentry> | |
2208 | <varlistentry> | |
2209 | <term>DRM_MODE_FLAG_INTERLACE</term> | |
2210 | <listitem><para> | |
2211 | Mode is interlaced | |
2212 | </para></listitem> | |
2213 | </varlistentry> | |
2214 | <varlistentry> | |
2215 | <term>DRM_MODE_FLAG_DBLSCAN</term> | |
2216 | <listitem><para> | |
2217 | Mode uses doublescan | |
2218 | </para></listitem> | |
2219 | </varlistentry> | |
2220 | <varlistentry> | |
2221 | <term>DRM_MODE_FLAG_CSYNC</term> | |
2222 | <listitem><para> | |
2223 | Mode uses composite sync | |
2224 | </para></listitem> | |
2225 | </varlistentry> | |
2226 | <varlistentry> | |
2227 | <term>DRM_MODE_FLAG_PCSYNC</term> | |
2228 | <listitem><para> | |
2229 | Composite sync is active high | |
2230 | </para></listitem> | |
2231 | </varlistentry> | |
2232 | <varlistentry> | |
2233 | <term>DRM_MODE_FLAG_NCSYNC</term> | |
2234 | <listitem><para> | |
2235 | Composite sync is active low | |
2236 | </para></listitem> | |
2237 | </varlistentry> | |
2238 | <varlistentry> | |
2239 | <term>DRM_MODE_FLAG_HSKEW</term> | |
2240 | <listitem><para> | |
2241 | hskew provided (not used?) | |
2242 | </para></listitem> | |
2243 | </varlistentry> | |
2244 | <varlistentry> | |
2245 | <term>DRM_MODE_FLAG_BCAST</term> | |
2246 | <listitem><para> | |
2247 | not used? | |
2248 | </para></listitem> | |
2249 | </varlistentry> | |
2250 | <varlistentry> | |
2251 | <term>DRM_MODE_FLAG_PIXMUX</term> | |
2252 | <listitem><para> | |
2253 | not used? | |
2254 | </para></listitem> | |
2255 | </varlistentry> | |
2256 | <varlistentry> | |
2257 | <term>DRM_MODE_FLAG_DBLCLK</term> | |
2258 | <listitem><para> | |
2259 | not used? | |
2260 | </para></listitem> | |
2261 | </varlistentry> | |
2262 | <varlistentry> | |
2263 | <term>DRM_MODE_FLAG_CLKDIV2</term> | |
2264 | <listitem><para> | |
2265 | ? | |
2266 | </para></listitem> | |
2267 | </varlistentry> | |
2268 | </variablelist> | |
2269 | </para> | |
2270 | <para> | |
2271 | Note that modes marked with the INTERLACE or DBLSCAN flags will be | |
2272 | filtered out by | |
2273 | <function>drm_helper_probe_single_connector_modes</function> if | |
2274 | the connector's <structfield>interlace_allowed</structfield> or | |
2275 | <structfield>doublescan_allowed</structfield> field is set to 0. | |
2276 | </para> | |
2277 | </listitem> | |
2278 | <listitem> | |
2279 | <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis> | |
2280 | <para> | |
2281 | Mode name. The driver must call | |
2282 | <function>drm_mode_set_name</function> to fill the mode name from | |
2283 | <structfield>hdisplay</structfield>, | |
2284 | <structfield>vdisplay</structfield> and interlace flag after | |
2285 | filling the corresponding fields. | |
2286 | </para> | |
2287 | </listitem> | |
2288 | </itemizedlist> | |
2289 | </para> | |
2290 | <para> | |
2291 | The <structfield>vrefresh</structfield> value is computed by | |
2292 | <function>drm_helper_probe_single_connector_modes</function>. | |
2293 | </para> | |
2294 | <para> | |
2295 | When parsing EDID data, <function>drm_add_edid_modes</function> fill the | |
2296 | connector <structfield>display_info</structfield> | |
2297 | <structfield>width_mm</structfield> and | |
2298 | <structfield>height_mm</structfield> fields. When creating modes | |
2299 | manually the <methodname>get_modes</methodname> helper operation must | |
2300 | set the <structfield>display_info</structfield> | |
2301 | <structfield>width_mm</structfield> and | |
2302 | <structfield>height_mm</structfield> fields if they haven't been set | |
065a5027 | 2303 | already (for instance at initialization time when a fixed-size panel is |
9cad9c95 LP |
2304 | attached to the connector). The mode <structfield>width_mm</structfield> |
2305 | and <structfield>height_mm</structfield> fields are only used internally | |
2306 | during EDID parsing and should not be set when creating modes manually. | |
2307 | </para> | |
2308 | </listitem> | |
2309 | <listitem> | |
2310 | <synopsis>int (*mode_valid)(struct drm_connector *connector, | |
2311 | struct drm_display_mode *mode);</synopsis> | |
2312 | <para> | |
2313 | Verify whether a mode is valid for the connector. Return MODE_OK for | |
2314 | supported modes and one of the enum drm_mode_status values (MODE_*) | |
f9b0e251 | 2315 | for unsupported modes. This operation is optional. |
9cad9c95 LP |
2316 | </para> |
2317 | <para> | |
2318 | As the mode rejection reason is currently not used beside for | |
2319 | immediately removing the unsupported mode, an implementation can | |
2320 | return MODE_BAD regardless of the exact reason why the mode is not | |
2321 | valid. | |
2322 | </para> | |
2323 | <note><para> | |
2324 | Note that the <methodname>mode_valid</methodname> helper operation is | |
2325 | only called for modes detected by the device, and | |
2326 | <emphasis>not</emphasis> for modes set by the user through the CRTC | |
2327 | <methodname>set_config</methodname> operation. | |
2328 | </para></note> | |
2329 | </listitem> | |
2330 | </itemizedlist> | |
2331 | </sect2> | |
3150c7d0 DV |
2332 | <sect2> |
2333 | <title>Atomic Modeset Helper Functions Reference</title> | |
2334 | <sect3> | |
2335 | <title>Overview</title> | |
2336 | !Pdrivers/gpu/drm/drm_atomic_helper.c overview | |
2337 | </sect3> | |
2338 | <sect3> | |
2339 | <title>Implementing Asynchronous Atomic Commit</title> | |
2340 | !Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit | |
2341 | </sect3> | |
2342 | <sect3> | |
2343 | <title>Atomic State Reset and Initialization</title> | |
2344 | !Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization | |
2345 | </sect3> | |
dd275956 | 2346 | !Iinclude/drm/drm_atomic_helper.h |
3150c7d0 DV |
2347 | !Edrivers/gpu/drm/drm_atomic_helper.c |
2348 | </sect2> | |
0d4ed4c8 DV |
2349 | <sect2> |
2350 | <title>Modeset Helper Functions Reference</title> | |
2351 | !Edrivers/gpu/drm/drm_crtc_helper.c | |
3150c7d0 | 2352 | !Pdrivers/gpu/drm/drm_crtc_helper.c overview |
8d754544 DV |
2353 | </sect2> |
2354 | <sect2> | |
2355 | <title>Output Probing Helper Functions Reference</title> | |
2356 | !Pdrivers/gpu/drm/drm_probe_helper.c output probing helper overview | |
2357 | !Edrivers/gpu/drm/drm_probe_helper.c | |
0d4ed4c8 | 2358 | </sect2> |
d0ddc033 DV |
2359 | <sect2> |
2360 | <title>fbdev Helper Functions Reference</title> | |
2361 | !Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers | |
2362 | !Edrivers/gpu/drm/drm_fb_helper.c | |
207fd329 | 2363 | !Iinclude/drm/drm_fb_helper.h |
d0ddc033 | 2364 | </sect2> |
28164fda DV |
2365 | <sect2> |
2366 | <title>Display Port Helper Functions Reference</title> | |
2367 | !Pdrivers/gpu/drm/drm_dp_helper.c dp helpers | |
2368 | !Iinclude/drm/drm_dp_helper.h | |
2369 | !Edrivers/gpu/drm/drm_dp_helper.c | |
ad7f8a1f DA |
2370 | </sect2> |
2371 | <sect2> | |
2372 | <title>Display Port MST Helper Functions Reference</title> | |
2373 | !Pdrivers/gpu/drm/drm_dp_mst_topology.c dp mst helper | |
2374 | !Iinclude/drm/drm_dp_mst_helper.h | |
2375 | !Edrivers/gpu/drm/drm_dp_mst_topology.c | |
009081e0 TR |
2376 | </sect2> |
2377 | <sect2> | |
2378 | <title>MIPI DSI Helper Functions Reference</title> | |
2379 | !Pdrivers/gpu/drm/drm_mipi_dsi.c dsi helpers | |
2380 | !Iinclude/drm/drm_mipi_dsi.h | |
2381 | !Edrivers/gpu/drm/drm_mipi_dsi.c | |
28164fda | 2382 | </sect2> |
5e308591 TR |
2383 | <sect2> |
2384 | <title>EDID Helper Functions Reference</title> | |
2385 | !Edrivers/gpu/drm/drm_edid.c | |
2386 | </sect2> | |
03973536 VS |
2387 | <sect2> |
2388 | <title>Rectangle Utilities Reference</title> | |
2389 | !Pinclude/drm/drm_rect.h rect utils | |
2390 | !Iinclude/drm/drm_rect.h | |
2391 | !Edrivers/gpu/drm/drm_rect.c | |
cabaafc7 RC |
2392 | </sect2> |
2393 | <sect2> | |
2394 | <title>Flip-work Helper Reference</title> | |
2395 | !Pinclude/drm/drm_flip_work.h flip utils | |
2396 | !Iinclude/drm/drm_flip_work.h | |
2397 | !Edrivers/gpu/drm/drm_flip_work.c | |
03973536 | 2398 | </sect2> |
2d123f46 DV |
2399 | <sect2> |
2400 | <title>HDMI Infoframes Helper Reference</title> | |
2401 | <para> | |
2402 | Strictly speaking this is not a DRM helper library but generally useable | |
2403 | by any driver interfacing with HDMI outputs like v4l or alsa drivers. | |
2404 | But it nicely fits into the overall topic of mode setting helper | |
2405 | libraries and hence is also included here. | |
2406 | </para> | |
2407 | !Iinclude/linux/hdmi.h | |
2408 | !Edrivers/video/hdmi.c | |
2409 | </sect2> | |
6efa1f2f MR |
2410 | <sect2> |
2411 | <title id="drm-kms-planehelpers">Plane Helper Reference</title> | |
3150c7d0 DV |
2412 | !Edrivers/gpu/drm/drm_plane_helper.c |
2413 | !Pdrivers/gpu/drm/drm_plane_helper.c overview | |
6efa1f2f | 2414 | </sect2> |
2d2ef822 JB |
2415 | </sect1> |
2416 | ||
421cda3e LP |
2417 | <!-- Internals: kms properties --> |
2418 | ||
2419 | <sect1 id="drm-kms-properties"> | |
2420 | <title>KMS Properties</title> | |
2421 | <para> | |
2422 | Drivers may need to expose additional parameters to applications than | |
2423 | those described in the previous sections. KMS supports attaching | |
2424 | properties to CRTCs, connectors and planes and offers a userspace API to | |
2425 | list, get and set the property values. | |
2426 | </para> | |
2427 | <para> | |
2428 | Properties are identified by a name that uniquely defines the property | |
2429 | purpose, and store an associated value. For all property types except blob | |
2430 | properties the value is a 64-bit unsigned integer. | |
2431 | </para> | |
2432 | <para> | |
2433 | KMS differentiates between properties and property instances. Drivers | |
2434 | first create properties and then create and associate individual instances | |
2435 | of those properties to objects. A property can be instantiated multiple | |
2436 | times and associated with different objects. Values are stored in property | |
9a6594fc | 2437 | instances, and all other property information are stored in the property |
421cda3e LP |
2438 | and shared between all instances of the property. |
2439 | </para> | |
2440 | <para> | |
2441 | Every property is created with a type that influences how the KMS core | |
2442 | handles the property. Supported property types are | |
2443 | <variablelist> | |
2444 | <varlistentry> | |
2445 | <term>DRM_MODE_PROP_RANGE</term> | |
2446 | <listitem><para>Range properties report their minimum and maximum | |
2447 | admissible values. The KMS core verifies that values set by | |
2448 | application fit in that range.</para></listitem> | |
2449 | </varlistentry> | |
2450 | <varlistentry> | |
2451 | <term>DRM_MODE_PROP_ENUM</term> | |
2452 | <listitem><para>Enumerated properties take a numerical value that | |
2453 | ranges from 0 to the number of enumerated values defined by the | |
2454 | property minus one, and associate a free-formed string name to each | |
2455 | value. Applications can retrieve the list of defined value-name pairs | |
2456 | and use the numerical value to get and set property instance values. | |
2457 | </para></listitem> | |
2458 | </varlistentry> | |
2459 | <varlistentry> | |
2460 | <term>DRM_MODE_PROP_BITMASK</term> | |
2461 | <listitem><para>Bitmask properties are enumeration properties that | |
2462 | additionally restrict all enumerated values to the 0..63 range. | |
2463 | Bitmask property instance values combine one or more of the | |
2464 | enumerated bits defined by the property.</para></listitem> | |
2465 | </varlistentry> | |
2466 | <varlistentry> | |
2467 | <term>DRM_MODE_PROP_BLOB</term> | |
2468 | <listitem><para>Blob properties store a binary blob without any format | |
2469 | restriction. The binary blobs are created as KMS standalone objects, | |
2470 | and blob property instance values store the ID of their associated | |
2471 | blob object.</para> | |
2472 | <para>Blob properties are only used for the connector EDID property | |
2473 | and cannot be created by drivers.</para></listitem> | |
2474 | </varlistentry> | |
2475 | </variablelist> | |
2476 | </para> | |
2477 | <para> | |
2478 | To create a property drivers call one of the following functions depending | |
2479 | on the property type. All property creation functions take property flags | |
2480 | and name, as well as type-specific arguments. | |
2481 | <itemizedlist> | |
2482 | <listitem> | |
2483 | <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags, | |
2484 | const char *name, | |
2485 | uint64_t min, uint64_t max);</synopsis> | |
2486 | <para>Create a range property with the given minimum and maximum | |
2487 | values.</para> | |
2488 | </listitem> | |
2489 | <listitem> | |
2490 | <synopsis>struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags, | |
2491 | const char *name, | |
2492 | const struct drm_prop_enum_list *props, | |
2493 | int num_values);</synopsis> | |
2494 | <para>Create an enumerated property. The <parameter>props</parameter> | |
2495 | argument points to an array of <parameter>num_values</parameter> | |
2496 | value-name pairs.</para> | |
2497 | </listitem> | |
2498 | <listitem> | |
2499 | <synopsis>struct drm_property *drm_property_create_bitmask(struct drm_device *dev, | |
2500 | int flags, const char *name, | |
2501 | const struct drm_prop_enum_list *props, | |
2502 | int num_values);</synopsis> | |
2503 | <para>Create a bitmask property. The <parameter>props</parameter> | |
2504 | argument points to an array of <parameter>num_values</parameter> | |
2505 | value-name pairs.</para> | |
2506 | </listitem> | |
2507 | </itemizedlist> | |
2508 | </para> | |
2509 | <para> | |
2510 | Properties can additionally be created as immutable, in which case they | |
2511 | will be read-only for applications but can be modified by the driver. To | |
2512 | create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE | |
2513 | flag at property creation time. | |
2514 | </para> | |
2515 | <para> | |
2516 | When no array of value-name pairs is readily available at property | |
2517 | creation time for enumerated or range properties, drivers can create | |
2518 | the property using the <function>drm_property_create</function> function | |
2519 | and manually add enumeration value-name pairs by calling the | |
2520 | <function>drm_property_add_enum</function> function. Care must be taken to | |
2521 | properly specify the property type through the <parameter>flags</parameter> | |
2522 | argument. | |
2523 | </para> | |
2524 | <para> | |
2525 | After creating properties drivers can attach property instances to CRTC, | |
2526 | connector and plane objects by calling the | |
2527 | <function>drm_object_attach_property</function>. The function takes a | |
2528 | pointer to the target object, a pointer to the previously created property | |
2529 | and an initial instance value. | |
2530 | </para> | |
6c6a3996 SK |
2531 | <sect2> |
2532 | <title>Existing KMS Properties</title> | |
2533 | <para> | |
2534 | The following table gives description of drm properties exposed by various | |
2535 | modules/drivers. | |
2536 | </para> | |
2537 | <table border="1" cellpadding="0" cellspacing="0"> | |
2538 | <tbody> | |
2539 | <tr style="font-weight: bold;"> | |
2540 | <td valign="top" >Owner Module/Drivers</td> | |
2541 | <td valign="top" >Group</td> | |
2542 | <td valign="top" >Property Name</td> | |
2543 | <td valign="top" >Type</td> | |
2544 | <td valign="top" >Property Values</td> | |
2545 | <td valign="top" >Object attached</td> | |
2546 | <td valign="top" >Description/Restrictions</td> | |
2547 | </tr> | |
2548 | <tr> | |
5bb2bbf5 | 2549 | <td rowspan="23" valign="top" >DRM</td> |
cc7096fb | 2550 | <td rowspan="3" valign="top" >Generic</td> |
6c6a3996 SK |
2551 | <td valign="top" >“EDID”</td> |
2552 | <td valign="top" >BLOB | IMMUTABLE</td> | |
2553 | <td valign="top" >0</td> | |
2554 | <td valign="top" >Connector</td> | |
2555 | <td valign="top" >Contains id of edid blob ptr object.</td> | |
2556 | </tr> | |
2557 | <tr> | |
2558 | <td valign="top" >“DPMS”</td> | |
2559 | <td valign="top" >ENUM</td> | |
2560 | <td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td> | |
2561 | <td valign="top" >Connector</td> | |
2562 | <td valign="top" >Contains DPMS operation mode value.</td> | |
2563 | </tr> | |
2564 | <tr> | |
cc7096fb DA |
2565 | <td valign="top" >“PATH”</td> |
2566 | <td valign="top" >BLOB | IMMUTABLE</td> | |
2567 | <td valign="top" >0</td> | |
2568 | <td valign="top" >Connector</td> | |
2569 | <td valign="top" >Contains topology path to a connector.</td> | |
2570 | </tr> | |
2571 | <tr> | |
59748616 DL |
2572 | <td rowspan="1" valign="top" >Plane</td> |
2573 | <td valign="top" >“type”</td> | |
2574 | <td valign="top" >ENUM | IMMUTABLE</td> | |
2575 | <td valign="top" >{ "Overlay", "Primary", "Cursor" }</td> | |
2576 | <td valign="top" >Plane</td> | |
2577 | <td valign="top" >Plane type</td> | |
2578 | </tr> | |
2579 | <tr> | |
6c6a3996 SK |
2580 | <td rowspan="2" valign="top" >DVI-I</td> |
2581 | <td valign="top" >“subconnector”</td> | |
2582 | <td valign="top" >ENUM</td> | |
2583 | <td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td> | |
2584 | <td valign="top" >Connector</td> | |
2585 | <td valign="top" >TBD</td> | |
2586 | </tr> | |
2587 | <tr> | |
2588 | <td valign="top" >“select subconnector”</td> | |
2589 | <td valign="top" >ENUM</td> | |
2590 | <td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td> | |
2591 | <td valign="top" >Connector</td> | |
2592 | <td valign="top" >TBD</td> | |
2593 | </tr> | |
2594 | <tr> | |
2595 | <td rowspan="13" valign="top" >TV</td> | |
2596 | <td valign="top" >“subconnector”</td> | |
2597 | <td valign="top" >ENUM</td> | |
2598 | <td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td> | |
2599 | <td valign="top" >Connector</td> | |
2600 | <td valign="top" >TBD</td> | |
2601 | </tr> | |
2602 | <tr> | |
2603 | <td valign="top" >“select subconnector”</td> | |
2604 | <td valign="top" >ENUM</td> | |
2605 | <td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td> | |
2606 | <td valign="top" >Connector</td> | |
2607 | <td valign="top" >TBD</td> | |
2608 | </tr> | |
2609 | <tr> | |
2610 | <td valign="top" >“mode”</td> | |
2611 | <td valign="top" >ENUM</td> | |
2612 | <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> | |
2613 | <td valign="top" >Connector</td> | |
2614 | <td valign="top" >TBD</td> | |
2615 | </tr> | |
2616 | <tr> | |
2617 | <td valign="top" >“left margin”</td> | |
2618 | <td valign="top" >RANGE</td> | |
2619 | <td valign="top" >Min=0, Max=100</td> | |
2620 | <td valign="top" >Connector</td> | |
2621 | <td valign="top" >TBD</td> | |
2622 | </tr> | |
2623 | <tr> | |
2624 | <td valign="top" >“right margin”</td> | |
2625 | <td valign="top" >RANGE</td> | |
2626 | <td valign="top" >Min=0, Max=100</td> | |
2627 | <td valign="top" >Connector</td> | |
2628 | <td valign="top" >TBD</td> | |
2629 | </tr> | |
2630 | <tr> | |
2631 | <td valign="top" >“top margin”</td> | |
2632 | <td valign="top" >RANGE</td> | |
2633 | <td valign="top" >Min=0, Max=100</td> | |
2634 | <td valign="top" >Connector</td> | |
2635 | <td valign="top" >TBD</td> | |
2636 | </tr> | |
2637 | <tr> | |
2638 | <td valign="top" >“bottom margin”</td> | |
2639 | <td valign="top" >RANGE</td> | |
2640 | <td valign="top" >Min=0, Max=100</td> | |
2641 | <td valign="top" >Connector</td> | |
2642 | <td valign="top" >TBD</td> | |
2643 | </tr> | |
2644 | <tr> | |
2645 | <td valign="top" >“brightness”</td> | |
2646 | <td valign="top" >RANGE</td> | |
2647 | <td valign="top" >Min=0, Max=100</td> | |
2648 | <td valign="top" >Connector</td> | |
2649 | <td valign="top" >TBD</td> | |
2650 | </tr> | |
2651 | <tr> | |
2652 | <td valign="top" >“contrast”</td> | |
2653 | <td valign="top" >RANGE</td> | |
2654 | <td valign="top" >Min=0, Max=100</td> | |
2655 | <td valign="top" >Connector</td> | |
2656 | <td valign="top" >TBD</td> | |
2657 | </tr> | |
2658 | <tr> | |
2659 | <td valign="top" >“flicker reduction”</td> | |
2660 | <td valign="top" >RANGE</td> | |
2661 | <td valign="top" >Min=0, Max=100</td> | |
2662 | <td valign="top" >Connector</td> | |
2663 | <td valign="top" >TBD</td> | |
2664 | </tr> | |
2665 | <tr> | |
2666 | <td valign="top" >“overscan”</td> | |
2667 | <td valign="top" >RANGE</td> | |
2668 | <td valign="top" >Min=0, Max=100</td> | |
2669 | <td valign="top" >Connector</td> | |
2670 | <td valign="top" >TBD</td> | |
2671 | </tr> | |
2672 | <tr> | |
2673 | <td valign="top" >“saturation”</td> | |
2674 | <td valign="top" >RANGE</td> | |
2675 | <td valign="top" >Min=0, Max=100</td> | |
2676 | <td valign="top" >Connector</td> | |
2677 | <td valign="top" >TBD</td> | |
2678 | </tr> | |
2679 | <tr> | |
2680 | <td valign="top" >“hue”</td> | |
2681 | <td valign="top" >RANGE</td> | |
2682 | <td valign="top" >Min=0, Max=100</td> | |
2683 | <td valign="top" >Connector</td> | |
2684 | <td valign="top" >TBD</td> | |
2685 | </tr> | |
2686 | <tr> | |
5bb2bbf5 DA |
2687 | <td rowspan="2" valign="top" >Virtual GPU</td> |
2688 | <td valign="top" >“suggested X”</td> | |
2689 | <td valign="top" >RANGE</td> | |
2690 | <td valign="top" >Min=0, Max=0xffffffff</td> | |
2691 | <td valign="top" >Connector</td> | |
2692 | <td valign="top" >property to suggest an X offset for a connector</td> | |
2693 | </tr> | |
2694 | <tr> | |
2695 | <td valign="top" >“suggested Y”</td> | |
2696 | <td valign="top" >RANGE</td> | |
2697 | <td valign="top" >Min=0, Max=0xffffffff</td> | |
2698 | <td valign="top" >Connector</td> | |
2699 | <td valign="top" >property to suggest an Y offset for a connector</td> | |
2700 | </tr> | |
2701 | <tr> | |
726a280d | 2702 | <td rowspan="3" valign="top" >Optional</td> |
6c6a3996 SK |
2703 | <td valign="top" >“scaling mode”</td> |
2704 | <td valign="top" >ENUM</td> | |
2705 | <td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td> | |
2706 | <td valign="top" >Connector</td> | |
2707 | <td valign="top" >TBD</td> | |
2708 | </tr> | |
2709 | <tr> | |
726a280d VK |
2710 | <td valign="top" >"aspect ratio"</td> |
2711 | <td valign="top" >ENUM</td> | |
2712 | <td valign="top" >{ "None", "4:3", "16:9" }</td> | |
2713 | <td valign="top" >Connector</td> | |
2714 | <td valign="top" >DRM property to set aspect ratio from user space app. | |
2715 | This enum is made generic to allow addition of custom aspect | |
2716 | ratios.</td> | |
2717 | </tr> | |
2718 | <tr> | |
6c6a3996 SK |
2719 | <td valign="top" >“dirty”</td> |
2720 | <td valign="top" >ENUM | IMMUTABLE</td> | |
2721 | <td valign="top" >{ "Off", "On", "Annotate" }</td> | |
2722 | <td valign="top" >Connector</td> | |
2723 | <td valign="top" >TBD</td> | |
2724 | </tr> | |
2725 | <tr> | |
d4ef41ce | 2726 | <td rowspan="21" valign="top" >i915</td> |
4ba08faa | 2727 | <td rowspan="2" valign="top" >Generic</td> |
6c6a3996 SK |
2728 | <td valign="top" >"Broadcast RGB"</td> |
2729 | <td valign="top" >ENUM</td> | |
2730 | <td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td> | |
2731 | <td valign="top" >Connector</td> | |
2732 | <td valign="top" >TBD</td> | |
2733 | </tr> | |
2734 | <tr> | |
2735 | <td valign="top" >“audio”</td> | |
2736 | <td valign="top" >ENUM</td> | |
2737 | <td valign="top" >{ "force-dvi", "off", "auto", "on" }</td> | |
2738 | <td valign="top" >Connector</td> | |
2739 | <td valign="top" >TBD</td> | |
2740 | </tr> | |
2741 | <tr> | |
d4ef41ce SK |
2742 | <td rowspan="1" valign="top" >Plane</td> |
2743 | <td valign="top" >“rotation”</td> | |
2744 | <td valign="top" >BITMASK</td> | |
2745 | <td valign="top" >{ 0, "rotate-0" }, { 2, "rotate-180" }</td> | |
2746 | <td valign="top" >Plane</td> | |
2747 | <td valign="top" >TBD</td> | |
2748 | </tr> | |
2749 | <tr> | |
6c6a3996 SK |
2750 | <td rowspan="17" valign="top" >SDVO-TV</td> |
2751 | <td valign="top" >“mode”</td> | |
2752 | <td valign="top" >ENUM</td> | |
2753 | <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> | |
2754 | <td valign="top" >Connector</td> | |
2755 | <td valign="top" >TBD</td> | |
2756 | </tr> | |
2757 | <tr> | |
2758 | <td valign="top" >"left_margin"</td> | |
2759 | <td valign="top" >RANGE</td> | |
2760 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2761 | <td valign="top" >Connector</td> | |
2762 | <td valign="top" >TBD</td> | |
2763 | </tr> | |
2764 | <tr> | |
2765 | <td valign="top" >"right_margin"</td> | |
2766 | <td valign="top" >RANGE</td> | |
2767 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2768 | <td valign="top" >Connector</td> | |
2769 | <td valign="top" >TBD</td> | |
2770 | </tr> | |
2771 | <tr> | |
2772 | <td valign="top" >"top_margin"</td> | |
2773 | <td valign="top" >RANGE</td> | |
2774 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2775 | <td valign="top" >Connector</td> | |
2776 | <td valign="top" >TBD</td> | |
2777 | </tr> | |
2778 | <tr> | |
2779 | <td valign="top" >"bottom_margin"</td> | |
2780 | <td valign="top" >RANGE</td> | |
2781 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2782 | <td valign="top" >Connector</td> | |
2783 | <td valign="top" >TBD</td> | |
2784 | </tr> | |
2785 | <tr> | |
2786 | <td valign="top" >“hpos”</td> | |
2787 | <td valign="top" >RANGE</td> | |
2788 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2789 | <td valign="top" >Connector</td> | |
2790 | <td valign="top" >TBD</td> | |
2791 | </tr> | |
2792 | <tr> | |
2793 | <td valign="top" >“vpos”</td> | |
2794 | <td valign="top" >RANGE</td> | |
2795 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2796 | <td valign="top" >Connector</td> | |
2797 | <td valign="top" >TBD</td> | |
2798 | </tr> | |
2799 | <tr> | |
2800 | <td valign="top" >“contrast”</td> | |
2801 | <td valign="top" >RANGE</td> | |
2802 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2803 | <td valign="top" >Connector</td> | |
2804 | <td valign="top" >TBD</td> | |
2805 | </tr> | |
2806 | <tr> | |
2807 | <td valign="top" >“saturation”</td> | |
2808 | <td valign="top" >RANGE</td> | |
2809 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2810 | <td valign="top" >Connector</td> | |
2811 | <td valign="top" >TBD</td> | |
2812 | </tr> | |
2813 | <tr> | |
2814 | <td valign="top" >“hue”</td> | |
2815 | <td valign="top" >RANGE</td> | |
2816 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2817 | <td valign="top" >Connector</td> | |
2818 | <td valign="top" >TBD</td> | |
2819 | </tr> | |
2820 | <tr> | |
2821 | <td valign="top" >“sharpness”</td> | |
2822 | <td valign="top" >RANGE</td> | |
2823 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2824 | <td valign="top" >Connector</td> | |
2825 | <td valign="top" >TBD</td> | |
2826 | </tr> | |
2827 | <tr> | |
2828 | <td valign="top" >“flicker_filter”</td> | |
2829 | <td valign="top" >RANGE</td> | |
2830 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2831 | <td valign="top" >Connector</td> | |
2832 | <td valign="top" >TBD</td> | |
2833 | </tr> | |
2834 | <tr> | |
2835 | <td valign="top" >“flicker_filter_adaptive”</td> | |
2836 | <td valign="top" >RANGE</td> | |
2837 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2838 | <td valign="top" >Connector</td> | |
2839 | <td valign="top" >TBD</td> | |
2840 | </tr> | |
2841 | <tr> | |
2842 | <td valign="top" >“flicker_filter_2d”</td> | |
2843 | <td valign="top" >RANGE</td> | |
2844 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2845 | <td valign="top" >Connector</td> | |
2846 | <td valign="top" >TBD</td> | |
2847 | </tr> | |
2848 | <tr> | |
2849 | <td valign="top" >“tv_chroma_filter”</td> | |
2850 | <td valign="top" >RANGE</td> | |
2851 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2852 | <td valign="top" >Connector</td> | |
2853 | <td valign="top" >TBD</td> | |
2854 | </tr> | |
2855 | <tr> | |
2856 | <td valign="top" >“tv_luma_filter”</td> | |
2857 | <td valign="top" >RANGE</td> | |
2858 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2859 | <td valign="top" >Connector</td> | |
2860 | <td valign="top" >TBD</td> | |
2861 | </tr> | |
2862 | <tr> | |
2863 | <td valign="top" >“dot_crawl”</td> | |
2864 | <td valign="top" >RANGE</td> | |
2865 | <td valign="top" >Min=0, Max=1</td> | |
2866 | <td valign="top" >Connector</td> | |
2867 | <td valign="top" >TBD</td> | |
2868 | </tr> | |
2869 | <tr> | |
2870 | <td valign="top" >SDVO-TV/LVDS</td> | |
2871 | <td valign="top" >“brightness”</td> | |
2872 | <td valign="top" >RANGE</td> | |
2873 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2874 | <td valign="top" >Connector</td> | |
2875 | <td valign="top" >TBD</td> | |
2876 | </tr> | |
2877 | <tr> | |
4ba08faa SK |
2878 | <td rowspan="2" valign="top" >CDV gma-500</td> |
2879 | <td rowspan="2" valign="top" >Generic</td> | |
6c6a3996 SK |
2880 | <td valign="top" >"Broadcast RGB"</td> |
2881 | <td valign="top" >ENUM</td> | |
2882 | <td valign="top" >{ “Full”, “Limited 16:235” }</td> | |
2883 | <td valign="top" >Connector</td> | |
2884 | <td valign="top" >TBD</td> | |
2885 | </tr> | |
2886 | <tr> | |
2887 | <td valign="top" >"Broadcast RGB"</td> | |
2888 | <td valign="top" >ENUM</td> | |
2889 | <td valign="top" >{ “off”, “auto”, “on” }</td> | |
2890 | <td valign="top" >Connector</td> | |
2891 | <td valign="top" >TBD</td> | |
2892 | </tr> | |
2893 | <tr> | |
4ba08faa SK |
2894 | <td rowspan="19" valign="top" >Poulsbo</td> |
2895 | <td rowspan="1" valign="top" >Generic</td> | |
6c6a3996 SK |
2896 | <td valign="top" >“backlight”</td> |
2897 | <td valign="top" >RANGE</td> | |
2898 | <td valign="top" >Min=0, Max=100</td> | |
2899 | <td valign="top" >Connector</td> | |
2900 | <td valign="top" >TBD</td> | |
2901 | </tr> | |
2902 | <tr> | |
6c6a3996 SK |
2903 | <td rowspan="17" valign="top" >SDVO-TV</td> |
2904 | <td valign="top" >“mode”</td> | |
2905 | <td valign="top" >ENUM</td> | |
2906 | <td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td> | |
2907 | <td valign="top" >Connector</td> | |
2908 | <td valign="top" >TBD</td> | |
2909 | </tr> | |
2910 | <tr> | |
2911 | <td valign="top" >"left_margin"</td> | |
2912 | <td valign="top" >RANGE</td> | |
2913 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2914 | <td valign="top" >Connector</td> | |
2915 | <td valign="top" >TBD</td> | |
2916 | </tr> | |
2917 | <tr> | |
2918 | <td valign="top" >"right_margin"</td> | |
2919 | <td valign="top" >RANGE</td> | |
2920 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2921 | <td valign="top" >Connector</td> | |
2922 | <td valign="top" >TBD</td> | |
2923 | </tr> | |
2924 | <tr> | |
2925 | <td valign="top" >"top_margin"</td> | |
2926 | <td valign="top" >RANGE</td> | |
2927 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2928 | <td valign="top" >Connector</td> | |
2929 | <td valign="top" >TBD</td> | |
2930 | </tr> | |
2931 | <tr> | |
2932 | <td valign="top" >"bottom_margin"</td> | |
2933 | <td valign="top" >RANGE</td> | |
2934 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2935 | <td valign="top" >Connector</td> | |
2936 | <td valign="top" >TBD</td> | |
2937 | </tr> | |
2938 | <tr> | |
2939 | <td valign="top" >“hpos”</td> | |
2940 | <td valign="top" >RANGE</td> | |
2941 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2942 | <td valign="top" >Connector</td> | |
2943 | <td valign="top" >TBD</td> | |
2944 | </tr> | |
2945 | <tr> | |
2946 | <td valign="top" >“vpos”</td> | |
2947 | <td valign="top" >RANGE</td> | |
2948 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2949 | <td valign="top" >Connector</td> | |
2950 | <td valign="top" >TBD</td> | |
2951 | </tr> | |
2952 | <tr> | |
2953 | <td valign="top" >“contrast”</td> | |
2954 | <td valign="top" >RANGE</td> | |
2955 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2956 | <td valign="top" >Connector</td> | |
2957 | <td valign="top" >TBD</td> | |
2958 | </tr> | |
2959 | <tr> | |
2960 | <td valign="top" >“saturation”</td> | |
2961 | <td valign="top" >RANGE</td> | |
2962 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2963 | <td valign="top" >Connector</td> | |
2964 | <td valign="top" >TBD</td> | |
2965 | </tr> | |
2966 | <tr> | |
2967 | <td valign="top" >“hue”</td> | |
2968 | <td valign="top" >RANGE</td> | |
2969 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2970 | <td valign="top" >Connector</td> | |
2971 | <td valign="top" >TBD</td> | |
2972 | </tr> | |
2973 | <tr> | |
2974 | <td valign="top" >“sharpness”</td> | |
2975 | <td valign="top" >RANGE</td> | |
2976 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2977 | <td valign="top" >Connector</td> | |
2978 | <td valign="top" >TBD</td> | |
2979 | </tr> | |
2980 | <tr> | |
2981 | <td valign="top" >“flicker_filter”</td> | |
2982 | <td valign="top" >RANGE</td> | |
2983 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2984 | <td valign="top" >Connector</td> | |
2985 | <td valign="top" >TBD</td> | |
2986 | </tr> | |
2987 | <tr> | |
2988 | <td valign="top" >“flicker_filter_adaptive”</td> | |
2989 | <td valign="top" >RANGE</td> | |
2990 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2991 | <td valign="top" >Connector</td> | |
2992 | <td valign="top" >TBD</td> | |
2993 | </tr> | |
2994 | <tr> | |
2995 | <td valign="top" >“flicker_filter_2d”</td> | |
2996 | <td valign="top" >RANGE</td> | |
2997 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
2998 | <td valign="top" >Connector</td> | |
2999 | <td valign="top" >TBD</td> | |
3000 | </tr> | |
3001 | <tr> | |
3002 | <td valign="top" >“tv_chroma_filter”</td> | |
3003 | <td valign="top" >RANGE</td> | |
3004 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
3005 | <td valign="top" >Connector</td> | |
3006 | <td valign="top" >TBD</td> | |
3007 | </tr> | |
3008 | <tr> | |
3009 | <td valign="top" >“tv_luma_filter”</td> | |
3010 | <td valign="top" >RANGE</td> | |
3011 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
3012 | <td valign="top" >Connector</td> | |
3013 | <td valign="top" >TBD</td> | |
3014 | </tr> | |
3015 | <tr> | |
3016 | <td valign="top" >“dot_crawl”</td> | |
3017 | <td valign="top" >RANGE</td> | |
3018 | <td valign="top" >Min=0, Max=1</td> | |
3019 | <td valign="top" >Connector</td> | |
3020 | <td valign="top" >TBD</td> | |
3021 | </tr> | |
3022 | <tr> | |
3023 | <td valign="top" >SDVO-TV/LVDS</td> | |
3024 | <td valign="top" >“brightness”</td> | |
3025 | <td valign="top" >RANGE</td> | |
3026 | <td valign="top" >Min=0, Max= SDVO dependent</td> | |
3027 | <td valign="top" >Connector</td> | |
3028 | <td valign="top" >TBD</td> | |
3029 | </tr> | |
3030 | <tr> | |
3031 | <td rowspan="11" valign="top" >armada</td> | |
3032 | <td rowspan="2" valign="top" >CRTC</td> | |
3033 | <td valign="top" >"CSC_YUV"</td> | |
3034 | <td valign="top" >ENUM</td> | |
3035 | <td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td> | |
3036 | <td valign="top" >CRTC</td> | |
3037 | <td valign="top" >TBD</td> | |
3038 | </tr> | |
3039 | <tr> | |
3040 | <td valign="top" >"CSC_RGB"</td> | |
3041 | <td valign="top" >ENUM</td> | |
3042 | <td valign="top" >{ "Auto", "Computer system", "Studio" }</td> | |
3043 | <td valign="top" >CRTC</td> | |
3044 | <td valign="top" >TBD</td> | |
3045 | </tr> | |
3046 | <tr> | |
3047 | <td rowspan="9" valign="top" >Overlay</td> | |
3048 | <td valign="top" >"colorkey"</td> | |
3049 | <td valign="top" >RANGE</td> | |
3050 | <td valign="top" >Min=0, Max=0xffffff</td> | |
3051 | <td valign="top" >Plane</td> | |
3052 | <td valign="top" >TBD</td> | |
3053 | </tr> | |
3054 | <tr> | |
3055 | <td valign="top" >"colorkey_min"</td> | |
3056 | <td valign="top" >RANGE</td> | |
3057 | <td valign="top" >Min=0, Max=0xffffff</td> | |
3058 | <td valign="top" >Plane</td> | |
3059 | <td valign="top" >TBD</td> | |
3060 | </tr> | |
3061 | <tr> | |
3062 | <td valign="top" >"colorkey_max"</td> | |
3063 | <td valign="top" >RANGE</td> | |
3064 | <td valign="top" >Min=0, Max=0xffffff</td> | |
3065 | <td valign="top" >Plane</td> | |
3066 | <td valign="top" >TBD</td> | |
3067 | </tr> | |
3068 | <tr> | |
3069 | <td valign="top" >"colorkey_val"</td> | |
3070 | <td valign="top" >RANGE</td> | |
3071 | <td valign="top" >Min=0, Max=0xffffff</td> | |
3072 | <td valign="top" >Plane</td> | |
3073 | <td valign="top" >TBD</td> | |
3074 | </tr> | |
3075 | <tr> | |
3076 | <td valign="top" >"colorkey_alpha"</td> | |
3077 | <td valign="top" >RANGE</td> | |
3078 | <td valign="top" >Min=0, Max=0xffffff</td> | |
3079 | <td valign="top" >Plane</td> | |
3080 | <td valign="top" >TBD</td> | |
3081 | </tr> | |
3082 | <tr> | |
3083 | <td valign="top" >"colorkey_mode"</td> | |
3084 | <td valign="top" >ENUM</td> | |
3085 | <td valign="top" >{ "disabled", "Y component", "U component" | |
3086 | , "V component", "RGB", “R component", "G component", "B component" }</td> | |
3087 | <td valign="top" >Plane</td> | |
3088 | <td valign="top" >TBD</td> | |
3089 | </tr> | |
3090 | <tr> | |
3091 | <td valign="top" >"brightness"</td> | |
3092 | <td valign="top" >RANGE</td> | |
3093 | <td valign="top" >Min=0, Max=256 + 255</td> | |
3094 | <td valign="top" >Plane</td> | |
3095 | <td valign="top" >TBD</td> | |
3096 | </tr> | |
3097 | <tr> | |
3098 | <td valign="top" >"contrast"</td> | |
3099 | <td valign="top" >RANGE</td> | |
3100 | <td valign="top" >Min=0, Max=0x7fff</td> | |
3101 | <td valign="top" >Plane</td> | |
3102 | <td valign="top" >TBD</td> | |
3103 | </tr> | |
3104 | <tr> | |
3105 | <td valign="top" >"saturation"</td> | |
3106 | <td valign="top" >RANGE</td> | |
3107 | <td valign="top" >Min=0, Max=0x7fff</td> | |
3108 | <td valign="top" >Plane</td> | |
3109 | <td valign="top" >TBD</td> | |
3110 | </tr> | |
3111 | <tr> | |
3112 | <td rowspan="2" valign="top" >exynos</td> | |
3113 | <td valign="top" >CRTC</td> | |
3114 | <td valign="top" >“mode”</td> | |
3115 | <td valign="top" >ENUM</td> | |
3116 | <td valign="top" >{ "normal", "blank" }</td> | |
3117 | <td valign="top" >CRTC</td> | |
3118 | <td valign="top" >TBD</td> | |
3119 | </tr> | |
3120 | <tr> | |
3121 | <td valign="top" >Overlay</td> | |
3122 | <td valign="top" >“zpos”</td> | |
3123 | <td valign="top" >RANGE</td> | |
3124 | <td valign="top" >Min=0, Max=MAX_PLANE-1</td> | |
3125 | <td valign="top" >Plane</td> | |
3126 | <td valign="top" >TBD</td> | |
3127 | </tr> | |
3128 | <tr> | |
4ba08faa | 3129 | <td rowspan="2" valign="top" >i2c/ch7006_drv</td> |
6c6a3996 SK |
3130 | <td valign="top" >Generic</td> |
3131 | <td valign="top" >“scale”</td> | |
3132 | <td valign="top" >RANGE</td> | |
3133 | <td valign="top" >Min=0, Max=2</td> | |
3134 | <td valign="top" >Connector</td> | |
3135 | <td valign="top" >TBD</td> | |
3136 | </tr> | |
3137 | <tr> | |
4ba08faa | 3138 | <td rowspan="1" valign="top" >TV</td> |
6c6a3996 SK |
3139 | <td valign="top" >“mode”</td> |
3140 | <td valign="top" >ENUM</td> | |
3141 | <td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc" | |
3142 | , "PAL-60", "NTSC-M", "NTSC-J" }</td> | |
3143 | <td valign="top" >Connector</td> | |
3144 | <td valign="top" >TBD</td> | |
3145 | </tr> | |
3146 | <tr> | |
4ba08faa | 3147 | <td rowspan="15" valign="top" >nouveau</td> |
6c6a3996 SK |
3148 | <td rowspan="6" valign="top" >NV10 Overlay</td> |
3149 | <td valign="top" >"colorkey"</td> | |
3150 | <td valign="top" >RANGE</td> | |
3151 | <td valign="top" >Min=0, Max=0x01ffffff</td> | |
3152 | <td valign="top" >Plane</td> | |
3153 | <td valign="top" >TBD</td> | |
3154 | </tr> | |
3155 | <tr> | |
3156 | <td valign="top" >“contrast”</td> | |
3157 | <td valign="top" >RANGE</td> | |
3158 | <td valign="top" >Min=0, Max=8192-1</td> | |
3159 | <td valign="top" >Plane</td> | |
3160 | <td valign="top" >TBD</td> | |
3161 | </tr> | |
3162 | <tr> | |
3163 | <td valign="top" >“brightness”</td> | |
3164 | <td valign="top" >RANGE</td> | |
3165 | <td valign="top" >Min=0, Max=1024</td> | |
3166 | <td valign="top" >Plane</td> | |
3167 | <td valign="top" >TBD</td> | |
3168 | </tr> | |
3169 | <tr> | |
3170 | <td valign="top" >“hue”</td> | |
3171 | <td valign="top" >RANGE</td> | |
3172 | <td valign="top" >Min=0, Max=359</td> | |
3173 | <td valign="top" >Plane</td> | |
3174 | <td valign="top" >TBD</td> | |
3175 | </tr> | |
3176 | <tr> | |
3177 | <td valign="top" >“saturation”</td> | |
3178 | <td valign="top" >RANGE</td> | |
3179 | <td valign="top" >Min=0, Max=8192-1</td> | |
3180 | <td valign="top" >Plane</td> | |
3181 | <td valign="top" >TBD</td> | |
3182 | </tr> | |
3183 | <tr> | |
3184 | <td valign="top" >“iturbt_709”</td> | |
3185 | <td valign="top" >RANGE</td> | |
3186 | <td valign="top" >Min=0, Max=1</td> | |
3187 | <td valign="top" >Plane</td> | |
3188 | <td valign="top" >TBD</td> | |
3189 | </tr> | |
3190 | <tr> | |
3191 | <td rowspan="2" valign="top" >Nv04 Overlay</td> | |
3192 | <td valign="top" >“colorkey”</td> | |
3193 | <td valign="top" >RANGE</td> | |
3194 | <td valign="top" >Min=0, Max=0x01ffffff</td> | |
3195 | <td valign="top" >Plane</td> | |
3196 | <td valign="top" >TBD</td> | |
3197 | </tr> | |
3198 | <tr> | |
3199 | <td valign="top" >“brightness”</td> | |
3200 | <td valign="top" >RANGE</td> | |
3201 | <td valign="top" >Min=0, Max=1024</td> | |
3202 | <td valign="top" >Plane</td> | |
3203 | <td valign="top" >TBD</td> | |
3204 | </tr> | |
3205 | <tr> | |
3206 | <td rowspan="7" valign="top" >Display</td> | |
3207 | <td valign="top" >“dithering mode”</td> | |
3208 | <td valign="top" >ENUM</td> | |
3209 | <td valign="top" >{ "auto", "off", "on" }</td> | |
3210 | <td valign="top" >Connector</td> | |
3211 | <td valign="top" >TBD</td> | |
3212 | </tr> | |
3213 | <tr> | |
3214 | <td valign="top" >“dithering depth”</td> | |
3215 | <td valign="top" >ENUM</td> | |
3216 | <td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td> | |
3217 | <td valign="top" >Connector</td> | |
3218 | <td valign="top" >TBD</td> | |
3219 | </tr> | |
3220 | <tr> | |
3221 | <td valign="top" >“underscan”</td> | |
3222 | <td valign="top" >ENUM</td> | |
3223 | <td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td> | |
3224 | <td valign="top" >Connector</td> | |
3225 | <td valign="top" >TBD</td> | |
3226 | </tr> | |
3227 | <tr> | |
3228 | <td valign="top" >“underscan hborder”</td> | |
3229 | <td valign="top" >RANGE</td> | |
3230 | <td valign="top" >Min=0, Max=128</td> | |
3231 | <td valign="top" >Connector</td> | |
3232 | <td valign="top" >TBD</td> | |
3233 | </tr> | |
3234 | <tr> | |
3235 | <td valign="top" >“underscan vborder”</td> | |
3236 | <td valign="top" >RANGE</td> | |
3237 | <td valign="top" >Min=0, Max=128</td> | |
3238 | <td valign="top" >Connector</td> | |
3239 | <td valign="top" >TBD</td> | |
3240 | </tr> | |
3241 | <tr> | |
3242 | <td valign="top" >“vibrant hue”</td> | |
3243 | <td valign="top" >RANGE</td> | |
3244 | <td valign="top" >Min=0, Max=180</td> | |
3245 | <td valign="top" >Connector</td> | |
3246 | <td valign="top" >TBD</td> | |
3247 | </tr> | |
3248 | <tr> | |
3249 | <td valign="top" >“color vibrance”</td> | |
3250 | <td valign="top" >RANGE</td> | |
3251 | <td valign="top" >Min=0, Max=200</td> | |
3252 | <td valign="top" >Connector</td> | |
3253 | <td valign="top" >TBD</td> | |
3254 | </tr> | |
3255 | <tr> | |
6c6a3996 SK |
3256 | <td rowspan="2" valign="top" >omap</td> |
3257 | <td rowspan="2" valign="top" >Generic</td> | |
3258 | <td valign="top" >“rotation”</td> | |
3259 | <td valign="top" >BITMASK</td> | |
3260 | <td valign="top" >{ 0, "rotate-0" }, | |
3261 | { 1, "rotate-90" }, | |
3262 | { 2, "rotate-180" }, | |
3263 | { 3, "rotate-270" }, | |
3264 | { 4, "reflect-x" }, | |
3265 | { 5, "reflect-y" }</td> | |
3266 | <td valign="top" >CRTC, Plane</td> | |
3267 | <td valign="top" >TBD</td> | |
3268 | </tr> | |
3269 | <tr> | |
3270 | <td valign="top" >“zorder”</td> | |
3271 | <td valign="top" >RANGE</td> | |
3272 | <td valign="top" >Min=0, Max=3</td> | |
3273 | <td valign="top" >CRTC, Plane</td> | |
3274 | <td valign="top" >TBD</td> | |
3275 | </tr> | |
3276 | <tr> | |
3277 | <td valign="top" >qxl</td> | |
3278 | <td valign="top" >Generic</td> | |
3279 | <td valign="top" >“hotplug_mode_update"</td> | |
3280 | <td valign="top" >RANGE</td> | |
3281 | <td valign="top" >Min=0, Max=1</td> | |
3282 | <td valign="top" >Connector</td> | |
3283 | <td valign="top" >TBD</td> | |
3284 | </tr> | |
3285 | <tr> | |
4ba08faa | 3286 | <td rowspan="9" valign="top" >radeon</td> |
6c6a3996 SK |
3287 | <td valign="top" >DVI-I</td> |
3288 | <td valign="top" >“coherent”</td> | |
3289 | <td valign="top" >RANGE</td> | |
3290 | <td valign="top" >Min=0, Max=1</td> | |
3291 | <td valign="top" >Connector</td> | |
3292 | <td valign="top" >TBD</td> | |
3293 | </tr> | |
3294 | <tr> | |
3295 | <td valign="top" >DAC enable load detect</td> | |
3296 | <td valign="top" >“load detection”</td> | |
3297 | <td valign="top" >RANGE</td> | |
3298 | <td valign="top" >Min=0, Max=1</td> | |
3299 | <td valign="top" >Connector</td> | |
3300 | <td valign="top" >TBD</td> | |
3301 | </tr> | |
3302 | <tr> | |
3303 | <td valign="top" >TV Standard</td> | |
3304 | <td valign="top" >"tv standard"</td> | |
3305 | <td valign="top" >ENUM</td> | |
3306 | <td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j" | |
3307 | , "scart-pal", "pal-cn", "secam" }</td> | |
3308 | <td valign="top" >Connector</td> | |
3309 | <td valign="top" >TBD</td> | |
3310 | </tr> | |
3311 | <tr> | |
3312 | <td valign="top" >legacy TMDS PLL detect</td> | |
3313 | <td valign="top" >"tmds_pll"</td> | |
3314 | <td valign="top" >ENUM</td> | |
3315 | <td valign="top" >{ "driver", "bios" }</td> | |
3316 | <td valign="top" >-</td> | |
3317 | <td valign="top" >TBD</td> | |
3318 | </tr> | |
3319 | <tr> | |
3320 | <td rowspan="3" valign="top" >Underscan</td> | |
3321 | <td valign="top" >"underscan"</td> | |
3322 | <td valign="top" >ENUM</td> | |
3323 | <td valign="top" >{ "off", "on", "auto" }</td> | |
3324 | <td valign="top" >Connector</td> | |
3325 | <td valign="top" >TBD</td> | |
3326 | </tr> | |
3327 | <tr> | |
3328 | <td valign="top" >"underscan hborder"</td> | |
3329 | <td valign="top" >RANGE</td> | |
3330 | <td valign="top" >Min=0, Max=128</td> | |
3331 | <td valign="top" >Connector</td> | |
3332 | <td valign="top" >TBD</td> | |
3333 | </tr> | |
3334 | <tr> | |
3335 | <td valign="top" >"underscan vborder"</td> | |
3336 | <td valign="top" >RANGE</td> | |
3337 | <td valign="top" >Min=0, Max=128</td> | |
3338 | <td valign="top" >Connector</td> | |
3339 | <td valign="top" >TBD</td> | |
3340 | </tr> | |
3341 | <tr> | |
3342 | <td valign="top" >Audio</td> | |
3343 | <td valign="top" >“audio”</td> | |
3344 | <td valign="top" >ENUM</td> | |
3345 | <td valign="top" >{ "off", "on", "auto" }</td> | |
3346 | <td valign="top" >Connector</td> | |
3347 | <td valign="top" >TBD</td> | |
3348 | </tr> | |
3349 | <tr> | |
3350 | <td valign="top" >FMT Dithering</td> | |
3351 | <td valign="top" >“dither”</td> | |
3352 | <td valign="top" >ENUM</td> | |
3353 | <td valign="top" >{ "off", "on" }</td> | |
3354 | <td valign="top" >Connector</td> | |
3355 | <td valign="top" >TBD</td> | |
3356 | </tr> | |
3357 | <tr> | |
6c6a3996 SK |
3358 | <td rowspan="3" valign="top" >rcar-du</td> |
3359 | <td rowspan="3" valign="top" >Generic</td> | |
3360 | <td valign="top" >"alpha"</td> | |
3361 | <td valign="top" >RANGE</td> | |
3362 | <td valign="top" >Min=0, Max=255</td> | |
3363 | <td valign="top" >Plane</td> | |
3364 | <td valign="top" >TBD</td> | |
3365 | </tr> | |
3366 | <tr> | |
3367 | <td valign="top" >"colorkey"</td> | |
3368 | <td valign="top" >RANGE</td> | |
3369 | <td valign="top" >Min=0, Max=0x01ffffff</td> | |
3370 | <td valign="top" >Plane</td> | |
3371 | <td valign="top" >TBD</td> | |
3372 | </tr> | |
3373 | <tr> | |
3374 | <td valign="top" >"zpos"</td> | |
3375 | <td valign="top" >RANGE</td> | |
3376 | <td valign="top" >Min=1, Max=7</td> | |
3377 | <td valign="top" >Plane</td> | |
3378 | <td valign="top" >TBD</td> | |
3379 | </tr> | |
3380 | </tbody> | |
3381 | </table> | |
3382 | </sect2> | |
2d2ef822 JB |
3383 | </sect1> |
3384 | ||
9cad9c95 LP |
3385 | <!-- Internals: vertical blanking --> |
3386 | ||
3387 | <sect1 id="drm-vertical-blank"> | |
3388 | <title>Vertical Blanking</title> | |
3389 | <para> | |
3390 | Vertical blanking plays a major role in graphics rendering. To achieve | |
3391 | tear-free display, users must synchronize page flips and/or rendering to | |
3392 | vertical blanking. The DRM API offers ioctls to perform page flips | |
3393 | synchronized to vertical blanking and wait for vertical blanking. | |
3394 | </para> | |
3395 | <para> | |
3396 | The DRM core handles most of the vertical blanking management logic, which | |
3397 | involves filtering out spurious interrupts, keeping race-free blanking | |
3398 | counters, coping with counter wrap-around and resets and keeping use | |
3399 | counts. It relies on the driver to generate vertical blanking interrupts | |
3400 | and optionally provide a hardware vertical blanking counter. Drivers must | |
3401 | implement the following operations. | |
3402 | </para> | |
3403 | <itemizedlist> | |
3404 | <listitem> | |
3405 | <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc); | |
3406 | void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis> | |
3407 | <para> | |
3408 | Enable or disable vertical blanking interrupts for the given CRTC. | |
3409 | </para> | |
3410 | </listitem> | |
3411 | <listitem> | |
3412 | <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis> | |
3413 | <para> | |
3414 | Retrieve the value of the vertical blanking counter for the given | |
3415 | CRTC. If the hardware maintains a vertical blanking counter its value | |
3416 | should be returned. Otherwise drivers can use the | |
3417 | <function>drm_vblank_count</function> helper function to handle this | |
3418 | operation. | |
3419 | </para> | |
3420 | </listitem> | |
3421 | </itemizedlist> | |
2d2ef822 | 3422 | <para> |
9cad9c95 LP |
3423 | Drivers must initialize the vertical blanking handling core with a call to |
3424 | <function>drm_vblank_init</function> in their | |
3425 | <methodname>load</methodname> operation. The function will set the struct | |
3426 | <structname>drm_device</structname> | |
3427 | <structfield>vblank_disable_allowed</structfield> field to 0. This will | |
3428 | keep vertical blanking interrupts enabled permanently until the first mode | |
3429 | set operation, where <structfield>vblank_disable_allowed</structfield> is | |
3430 | set to 1. The reason behind this is not clear. Drivers can set the field | |
3431 | to 1 after <function>calling drm_vblank_init</function> to make vertical | |
3432 | blanking interrupts dynamically managed from the beginning. | |
2d2ef822 | 3433 | </para> |
9cad9c95 LP |
3434 | <para> |
3435 | Vertical blanking interrupts can be enabled by the DRM core or by drivers | |
3436 | themselves (for instance to handle page flipping operations). The DRM core | |
3437 | maintains a vertical blanking use count to ensure that the interrupts are | |
3438 | not disabled while a user still needs them. To increment the use count, | |
3439 | drivers call <function>drm_vblank_get</function>. Upon return vertical | |
3440 | blanking interrupts are guaranteed to be enabled. | |
3441 | </para> | |
3442 | <para> | |
3443 | To decrement the use count drivers call | |
3444 | <function>drm_vblank_put</function>. Only when the use count drops to zero | |
3445 | will the DRM core disable the vertical blanking interrupts after a delay | |
3446 | by scheduling a timer. The delay is accessible through the vblankoffdelay | |
3447 | module parameter or the <varname>drm_vblank_offdelay</varname> global | |
3448 | variable and expressed in milliseconds. Its default value is 5000 ms. | |
4ed0ce3d | 3449 | Zero means never disable, and a negative value means disable immediately. |
00185e66 VS |
3450 | Drivers may override the behaviour by setting the |
3451 | <structname>drm_device</structname> | |
3452 | <structfield>vblank_disable_immediate</structfield> flag, which when set | |
3453 | causes vblank interrupts to be disabled immediately regardless of the | |
3454 | drm_vblank_offdelay value. The flag should only be set if there's a | |
3455 | properly working hardware vblank counter present. | |
9cad9c95 LP |
3456 | </para> |
3457 | <para> | |
3458 | When a vertical blanking interrupt occurs drivers only need to call the | |
3459 | <function>drm_handle_vblank</function> function to account for the | |
3460 | interrupt. | |
3461 | </para> | |
3462 | <para> | |
3463 | Resources allocated by <function>drm_vblank_init</function> must be freed | |
3464 | with a call to <function>drm_vblank_cleanup</function> in the driver | |
3465 | <methodname>unload</methodname> operation handler. | |
3466 | </para> | |
f5752b38 DV |
3467 | <sect2> |
3468 | <title>Vertical Blanking and Interrupt Handling Functions Reference</title> | |
3469 | !Edrivers/gpu/drm/drm_irq.c | |
d743ecf3 | 3470 | !Finclude/drm/drmP.h drm_crtc_vblank_waitqueue |
f5752b38 | 3471 | </sect2> |
9cad9c95 LP |
3472 | </sect1> |
3473 | ||
3474 | <!-- Internals: open/close, file operations and ioctls --> | |
2d2ef822 | 3475 | |
9cad9c95 LP |
3476 | <sect1> |
3477 | <title>Open/Close, File Operations and IOCTLs</title> | |
2d2ef822 | 3478 | <sect2> |
9cad9c95 LP |
3479 | <title>Open and Close</title> |
3480 | <synopsis>int (*firstopen) (struct drm_device *); | |
3481 | void (*lastclose) (struct drm_device *); | |
3482 | int (*open) (struct drm_device *, struct drm_file *); | |
3483 | void (*preclose) (struct drm_device *, struct drm_file *); | |
3484 | void (*postclose) (struct drm_device *, struct drm_file *);</synopsis> | |
3485 | <abstract>Open and close handlers. None of those methods are mandatory. | |
3486 | </abstract> | |
2d2ef822 | 3487 | <para> |
9cad9c95 | 3488 | The <methodname>firstopen</methodname> method is called by the DRM core |
7d14bb6b DV |
3489 | for legacy UMS (User Mode Setting) drivers only when an application |
3490 | opens a device that has no other opened file handle. UMS drivers can | |
3491 | implement it to acquire device resources. KMS drivers can't use the | |
3492 | method and must acquire resources in the <methodname>load</methodname> | |
3493 | method instead. | |
2d2ef822 JB |
3494 | </para> |
3495 | <para> | |
7d14bb6b DV |
3496 | Similarly the <methodname>lastclose</methodname> method is called when |
3497 | the last application holding a file handle opened on the device closes | |
3498 | it, for both UMS and KMS drivers. Additionally, the method is also | |
3499 | called at module unload time or, for hot-pluggable devices, when the | |
3500 | device is unplugged. The <methodname>firstopen</methodname> and | |
9cad9c95 | 3501 | <methodname>lastclose</methodname> calls can thus be unbalanced. |
2d2ef822 JB |
3502 | </para> |
3503 | <para> | |
9cad9c95 LP |
3504 | The <methodname>open</methodname> method is called every time the device |
3505 | is opened by an application. Drivers can allocate per-file private data | |
3506 | in this method and store them in the struct | |
3507 | <structname>drm_file</structname> <structfield>driver_priv</structfield> | |
3508 | field. Note that the <methodname>open</methodname> method is called | |
3509 | before <methodname>firstopen</methodname>. | |
3510 | </para> | |
3511 | <para> | |
3512 | The close operation is split into <methodname>preclose</methodname> and | |
3513 | <methodname>postclose</methodname> methods. Drivers must stop and | |
3514 | cleanup all per-file operations in the <methodname>preclose</methodname> | |
3515 | method. For instance pending vertical blanking and page flip events must | |
3516 | be cancelled. No per-file operation is allowed on the file handle after | |
3517 | returning from the <methodname>preclose</methodname> method. | |
3518 | </para> | |
3519 | <para> | |
3520 | Finally the <methodname>postclose</methodname> method is called as the | |
3521 | last step of the close operation, right before calling the | |
3522 | <methodname>lastclose</methodname> method if no other open file handle | |
3523 | exists for the device. Drivers that have allocated per-file private data | |
3524 | in the <methodname>open</methodname> method should free it here. | |
3525 | </para> | |
3526 | <para> | |
3527 | The <methodname>lastclose</methodname> method should restore CRTC and | |
3528 | plane properties to default value, so that a subsequent open of the | |
7d14bb6b DV |
3529 | device will not inherit state from the previous user. It can also be |
3530 | used to execute delayed power switching state changes, e.g. in | |
3531 | conjunction with the vga-switcheroo infrastructure. Beyond that KMS | |
3532 | drivers should not do any further cleanup. Only legacy UMS drivers might | |
3533 | need to clean up device state so that the vga console or an independent | |
3534 | fbdev driver could take over. | |
2d2ef822 JB |
3535 | </para> |
3536 | </sect2> | |
2d2ef822 | 3537 | <sect2> |
9cad9c95 LP |
3538 | <title>File Operations</title> |
3539 | <synopsis>const struct file_operations *fops</synopsis> | |
3540 | <abstract>File operations for the DRM device node.</abstract> | |
2d2ef822 | 3541 | <para> |
9cad9c95 LP |
3542 | Drivers must define the file operations structure that forms the DRM |
3543 | userspace API entry point, even though most of those operations are | |
3544 | implemented in the DRM core. The <methodname>open</methodname>, | |
3545 | <methodname>release</methodname> and <methodname>ioctl</methodname> | |
3546 | operations are handled by | |
3547 | <programlisting> | |
3548 | .owner = THIS_MODULE, | |
3549 | .open = drm_open, | |
3550 | .release = drm_release, | |
3551 | .unlocked_ioctl = drm_ioctl, | |
3552 | #ifdef CONFIG_COMPAT | |
3553 | .compat_ioctl = drm_compat_ioctl, | |
3554 | #endif | |
3555 | </programlisting> | |
2d2ef822 JB |
3556 | </para> |
3557 | <para> | |
9cad9c95 LP |
3558 | Drivers that implement private ioctls that requires 32/64bit |
3559 | compatibility support must provide their own | |
3560 | <methodname>compat_ioctl</methodname> handler that processes private | |
3561 | ioctls and calls <function>drm_compat_ioctl</function> for core ioctls. | |
2d2ef822 JB |
3562 | </para> |
3563 | <para> | |
9cad9c95 LP |
3564 | The <methodname>read</methodname> and <methodname>poll</methodname> |
3565 | operations provide support for reading DRM events and polling them. They | |
3566 | are implemented by | |
3567 | <programlisting> | |
3568 | .poll = drm_poll, | |
3569 | .read = drm_read, | |
9cad9c95 LP |
3570 | .llseek = no_llseek, |
3571 | </programlisting> | |
3572 | </para> | |
3573 | <para> | |
3574 | The memory mapping implementation varies depending on how the driver | |
3575 | manages memory. Pre-GEM drivers will use <function>drm_mmap</function>, | |
3576 | while GEM-aware drivers will use <function>drm_gem_mmap</function>. See | |
3577 | <xref linkend="drm-gem"/>. | |
3578 | <programlisting> | |
3579 | .mmap = drm_gem_mmap, | |
3580 | </programlisting> | |
3581 | </para> | |
3582 | <para> | |
3583 | No other file operation is supported by the DRM API. | |
3584 | </para> | |
3585 | </sect2> | |
3586 | <sect2> | |
3587 | <title>IOCTLs</title> | |
3588 | <synopsis>struct drm_ioctl_desc *ioctls; | |
3589 | int num_ioctls;</synopsis> | |
3590 | <abstract>Driver-specific ioctls descriptors table.</abstract> | |
3591 | <para> | |
3592 | Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls | |
3593 | descriptors table is indexed by the ioctl number offset from the base | |
3594 | value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the | |
3595 | table entries. | |
3596 | </para> | |
3597 | <para> | |
3598 | <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting> | |
3599 | <para> | |
3600 | <parameter>ioctl</parameter> is the ioctl name. Drivers must define | |
3601 | the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number | |
3602 | offset from DRM_COMMAND_BASE and the ioctl number respectively. The | |
3603 | first macro is private to the device while the second must be exposed | |
3604 | to userspace in a public header. | |
3605 | </para> | |
3606 | <para> | |
3607 | <parameter>func</parameter> is a pointer to the ioctl handler function | |
3608 | compatible with the <type>drm_ioctl_t</type> type. | |
3609 | <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data, | |
3610 | struct drm_file *file_priv);</programlisting> | |
3611 | </para> | |
3612 | <para> | |
3613 | <parameter>flags</parameter> is a bitmask combination of the following | |
3614 | values. It restricts how the ioctl is allowed to be called. | |
3615 | <itemizedlist> | |
3616 | <listitem><para> | |
3617 | DRM_AUTH - Only authenticated callers allowed | |
3618 | </para></listitem> | |
3619 | <listitem><para> | |
3620 | DRM_MASTER - The ioctl can only be called on the master file | |
3621 | handle | |
3622 | </para></listitem> | |
3623 | <listitem><para> | |
3624 | DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed | |
3625 | </para></listitem> | |
3626 | <listitem><para> | |
3627 | DRM_CONTROL_ALLOW - The ioctl can only be called on a control | |
3628 | device | |
3629 | </para></listitem> | |
3630 | <listitem><para> | |
3631 | DRM_UNLOCKED - The ioctl handler will be called without locking | |
3632 | the DRM global mutex | |
3633 | </para></listitem> | |
3634 | </itemizedlist> | |
3635 | </para> | |
2d2ef822 JB |
3636 | </para> |
3637 | </sect2> | |
2d2ef822 | 3638 | </sect1> |
2d2ef822 | 3639 | <sect1> |
4c6e2dfe | 3640 | <title>Legacy Support Code</title> |
2d2ef822 | 3641 | <para> |
9a6594fc | 3642 | The section very briefly covers some of the old legacy support code which |
4c6e2dfe DV |
3643 | is only used by old DRM drivers which have done a so-called shadow-attach |
3644 | to the underlying device instead of registering as a real driver. This | |
9a6594fc | 3645 | also includes some of the old generic buffer management and command |
4c6e2dfe | 3646 | submission code. Do not use any of this in new and modern drivers. |
2d2ef822 | 3647 | </para> |
2d2ef822 | 3648 | |
4c6e2dfe DV |
3649 | <sect2> |
3650 | <title>Legacy Suspend/Resume</title> | |
3651 | <para> | |
3652 | The DRM core provides some suspend/resume code, but drivers wanting full | |
3653 | suspend/resume support should provide save() and restore() functions. | |
3654 | These are called at suspend, hibernate, or resume time, and should perform | |
3655 | any state save or restore required by your device across suspend or | |
3656 | hibernate states. | |
3657 | </para> | |
3658 | <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); | |
3659 | int (*resume) (struct drm_device *);</synopsis> | |
3660 | <para> | |
3661 | Those are legacy suspend and resume methods which | |
3662 | <emphasis>only</emphasis> work with the legacy shadow-attach driver | |
3663 | registration functions. New driver should use the power management | |
3664 | interface provided by their bus type (usually through | |
3665 | the struct <structname>device_driver</structname> dev_pm_ops) and set | |
3666 | these methods to NULL. | |
3667 | </para> | |
3668 | </sect2> | |
3669 | ||
3670 | <sect2> | |
3671 | <title>Legacy DMA Services</title> | |
3672 | <para> | |
3673 | This should cover how DMA mapping etc. is supported by the core. | |
3674 | These functions are deprecated and should not be used. | |
3675 | </para> | |
3676 | </sect2> | |
2d2ef822 JB |
3677 | </sect1> |
3678 | </chapter> | |
3679 | ||
9cad9c95 LP |
3680 | <!-- TODO |
3681 | ||
3682 | - Add a glossary | |
3683 | - Document the struct_mutex catch-all lock | |
3684 | - Document connector properties | |
3685 | ||
3686 | - Why is the load method optional? | |
3687 | - What are drivers supposed to set the initial display state to, and how? | |
3688 | Connector's DPMS states are not initialized and are thus equal to | |
3689 | DRM_MODE_DPMS_ON. The fbcon compatibility layer calls | |
3690 | drm_helper_disable_unused_functions(), which disables unused encoders and | |
3691 | CRTCs, but doesn't touch the connectors' DPMS state, and | |
3692 | drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers | |
3693 | that don't implement (or just don't use) fbcon compatibility need to call | |
3694 | those functions themselves? | |
3695 | - KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset() | |
3696 | around mode setting. Should this be done in the DRM core? | |
3697 | - vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset() | |
3698 | call and never set back to 0. It seems to be safe to permanently set it to 1 | |
3699 | in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as | |
3700 | well. This should be investigated. | |
3701 | - crtc and connector .save and .restore operations are only used internally in | |
3702 | drivers, should they be removed from the core? | |
3703 | - encoder mid-layer .save and .restore operations are only used internally in | |
3704 | drivers, should they be removed from the core? | |
3705 | - encoder mid-layer .detect operation is only used internally in drivers, | |
3706 | should it be removed from the core? | |
3707 | --> | |
3708 | ||
2d2ef822 JB |
3709 | <!-- External interfaces --> |
3710 | ||
3711 | <chapter id="drmExternals"> | |
3712 | <title>Userland interfaces</title> | |
3713 | <para> | |
3714 | The DRM core exports several interfaces to applications, | |
3715 | generally intended to be used through corresponding libdrm | |
a5294e01 | 3716 | wrapper functions. In addition, drivers export device-specific |
7f0925ac | 3717 | interfaces for use by userspace drivers & device-aware |
2d2ef822 JB |
3718 | applications through ioctls and sysfs files. |
3719 | </para> | |
3720 | <para> | |
3721 | External interfaces include: memory mapping, context management, | |
3722 | DMA operations, AGP management, vblank control, fence | |
3723 | management, memory management, and output management. | |
3724 | </para> | |
3725 | <para> | |
bcd3cfc1 MW |
3726 | Cover generic ioctls and sysfs layout here. We only need high-level |
3727 | info, since man pages should cover the rest. | |
2d2ef822 | 3728 | </para> |
9cad9c95 | 3729 | |
1793126f DH |
3730 | <!-- External: render nodes --> |
3731 | ||
3732 | <sect1> | |
3733 | <title>Render nodes</title> | |
3734 | <para> | |
3735 | DRM core provides multiple character-devices for user-space to use. | |
3736 | Depending on which device is opened, user-space can perform a different | |
3737 | set of operations (mainly ioctls). The primary node is always created | |
00153aeb DV |
3738 | and called card<num>. Additionally, a currently |
3739 | unused control node, called controlD<num> is also | |
1793126f DH |
3740 | created. The primary node provides all legacy operations and |
3741 | historically was the only interface used by userspace. With KMS, the | |
3742 | control node was introduced. However, the planned KMS control interface | |
3743 | has never been written and so the control node stays unused to date. | |
3744 | </para> | |
3745 | <para> | |
3746 | With the increased use of offscreen renderers and GPGPU applications, | |
3747 | clients no longer require running compositors or graphics servers to | |
3748 | make use of a GPU. But the DRM API required unprivileged clients to | |
3749 | authenticate to a DRM-Master prior to getting GPU access. To avoid this | |
3750 | step and to grant clients GPU access without authenticating, render | |
3751 | nodes were introduced. Render nodes solely serve render clients, that | |
3752 | is, no modesetting or privileged ioctls can be issued on render nodes. | |
3753 | Only non-global rendering commands are allowed. If a driver supports | |
00153aeb | 3754 | render nodes, it must advertise it via the DRIVER_RENDER |
1793126f DH |
3755 | DRM driver capability. If not supported, the primary node must be used |
3756 | for render clients together with the legacy drmAuth authentication | |
3757 | procedure. | |
3758 | </para> | |
3759 | <para> | |
3760 | If a driver advertises render node support, DRM core will create a | |
00153aeb | 3761 | separate render node called renderD<num>. There will |
1793126f | 3762 | be one render node per device. No ioctls except PRIME-related ioctls |
00153aeb | 3763 | will be allowed on this node. Especially GEM_OPEN will be |
1793126f DH |
3764 | explicitly prohibited. Render nodes are designed to avoid the |
3765 | buffer-leaks, which occur if clients guess the flink names or mmap | |
3766 | offsets on the legacy interface. Additionally to this basic interface, | |
3767 | drivers must mark their driver-dependent render-only ioctls as | |
00153aeb | 3768 | DRM_RENDER_ALLOW so render clients can use them. Driver |
1793126f DH |
3769 | authors must be careful not to allow any privileged ioctls on render |
3770 | nodes. | |
3771 | </para> | |
3772 | <para> | |
3773 | With render nodes, user-space can now control access to the render node | |
3774 | via basic file-system access-modes. A running graphics server which | |
3775 | authenticates clients on the privileged primary/legacy node is no longer | |
3776 | required. Instead, a client can open the render node and is immediately | |
3777 | granted GPU access. Communication between clients (or servers) is done | |
3778 | via PRIME. FLINK from render node to legacy node is not supported. New | |
3779 | clients must not use the insecure FLINK interface. | |
3780 | </para> | |
3781 | <para> | |
3782 | Besides dropping all modeset/global ioctls, render nodes also drop the | |
3783 | DRM-Master concept. There is no reason to associate render clients with | |
3784 | a DRM-Master as they are independent of any graphics server. Besides, | |
3785 | they must work without any running master, anyway. | |
3786 | Drivers must be able to run without a master object if they support | |
3787 | render nodes. If, on the other hand, a driver requires shared state | |
3788 | between clients which is visible to user-space and accessible beyond | |
3789 | open-file boundaries, they cannot support render nodes. | |
3790 | </para> | |
3791 | </sect1> | |
3792 | ||
9cad9c95 LP |
3793 | <!-- External: vblank handling --> |
3794 | ||
3795 | <sect1> | |
3796 | <title>VBlank event handling</title> | |
3797 | <para> | |
3798 | The DRM core exposes two vertical blank related ioctls: | |
3799 | <variablelist> | |
3800 | <varlistentry> | |
3801 | <term>DRM_IOCTL_WAIT_VBLANK</term> | |
3802 | <listitem> | |
3803 | <para> | |
3804 | This takes a struct drm_wait_vblank structure as its argument, | |
3805 | and it is used to block or request a signal when a specified | |
3806 | vblank event occurs. | |
3807 | </para> | |
3808 | </listitem> | |
3809 | </varlistentry> | |
3810 | <varlistentry> | |
3811 | <term>DRM_IOCTL_MODESET_CTL</term> | |
3812 | <listitem> | |
3813 | <para> | |
8edffbb9 DV |
3814 | This was only used for user-mode-settind drivers around |
3815 | modesetting changes to allow the kernel to update the vblank | |
3816 | interrupt after mode setting, since on many devices the vertical | |
3817 | blank counter is reset to 0 at some point during modeset. Modern | |
3818 | drivers should not call this any more since with kernel mode | |
3819 | setting it is a no-op. | |
9cad9c95 LP |
3820 | </para> |
3821 | </listitem> | |
3822 | </varlistentry> | |
3823 | </variablelist> | |
9cad9c95 LP |
3824 | </para> |
3825 | </sect1> | |
3826 | ||
2d2ef822 | 3827 | </chapter> |
3519f70e DV |
3828 | </part> |
3829 | <part id="drmDrivers"> | |
3830 | <title>DRM Drivers</title> | |
2d2ef822 | 3831 | |
3519f70e DV |
3832 | <partintro> |
3833 | <para> | |
3834 | This second part of the DRM Developer's Guide documents driver code, | |
3835 | implementation details and also all the driver-specific userspace | |
3836 | interfaces. Especially since all hardware-acceleration interfaces to | |
3837 | userspace are driver specific for efficiency and other reasons these | |
3838 | interfaces can be rather substantial. Hence every driver has its own | |
3839 | chapter. | |
3840 | </para> | |
3841 | </partintro> | |
2d2ef822 | 3842 | |
3519f70e DV |
3843 | <chapter id="drmI915"> |
3844 | <title>drm/i915 Intel GFX Driver</title> | |
2d2ef822 | 3845 | <para> |
3519f70e DV |
3846 | The drm/i915 driver supports all (with the exception of some very early |
3847 | models) integrated GFX chipsets with both Intel display and rendering | |
3848 | blocks. This excludes a set of SoC platforms with an SGX rendering unit, | |
3849 | those have basic support through the gma500 drm driver. | |
2d2ef822 | 3850 | </para> |
e4e7684f DV |
3851 | <sect1> |
3852 | <title>Core Driver Infrastructure</title> | |
3853 | <para> | |
3854 | This section covers core driver infrastructure used by both the display | |
3855 | and the GEM parts of the driver. | |
3856 | </para> | |
3857 | <sect2> | |
3858 | <title>Runtime Power Management</title> | |
3859 | !Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm | |
3860 | !Idrivers/gpu/drm/i915/intel_runtime_pm.c | |
3861 | </sect2> | |
fca52a55 DV |
3862 | <sect2> |
3863 | <title>Interrupt Handling</title> | |
3864 | !Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling | |
3865 | !Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init | |
3866 | !Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_fini | |
3867 | !Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts | |
3868 | !Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts | |
3869 | </sect2> | |
e4e7684f | 3870 | </sect1> |
3519f70e DV |
3871 | <sect1> |
3872 | <title>Display Hardware Handling</title> | |
3873 | <para> | |
3874 | This section covers everything related to the display hardware including | |
3875 | the mode setting infrastructure, plane, sprite and cursor handling and | |
3876 | display, output probing and related topics. | |
3877 | </para> | |
3878 | <sect2> | |
3879 | <title>Mode Setting Infrastructure</title> | |
3880 | <para> | |
3881 | The i915 driver is thus far the only DRM driver which doesn't use the | |
3882 | common DRM helper code to implement mode setting sequences. Thus it | |
3883 | has its own tailor-made infrastructure for executing a display | |
3884 | configuration change. | |
3885 | </para> | |
3886 | </sect2> | |
b680c37a DV |
3887 | <sect2> |
3888 | <title>Frontbuffer Tracking</title> | |
3889 | !Pdrivers/gpu/drm/i915/intel_frontbuffer.c frontbuffer tracking | |
3890 | !Idrivers/gpu/drm/i915/intel_frontbuffer.c | |
3891 | !Fdrivers/gpu/drm/i915/intel_drv.h intel_frontbuffer_flip | |
3892 | !Fdrivers/gpu/drm/i915/i915_gem.c i915_gem_track_fb | |
ef07388e DV |
3893 | </sect2> |
3894 | <sect2> | |
3895 | <title>Display FIFO Underrun Reporting</title> | |
3896 | !Pdrivers/gpu/drm/i915/intel_fifo_underrun.c fifo underrun handling | |
3897 | !Idrivers/gpu/drm/i915/intel_fifo_underrun.c | |
b680c37a | 3898 | </sect2> |
3519f70e DV |
3899 | <sect2> |
3900 | <title>Plane Configuration</title> | |
3901 | <para> | |
3902 | This section covers plane configuration and composition with the | |
3903 | primary plane, sprites, cursors and overlays. This includes the | |
3904 | infrastructure to do atomic vsync'ed updates of all this state and | |
3905 | also tightly coupled topics like watermark setup and computation, | |
3906 | framebuffer compression and panel self refresh. | |
3907 | </para> | |
3908 | </sect2> | |
3909 | <sect2> | |
3910 | <title>Output Probing</title> | |
3911 | <para> | |
3912 | This section covers output probing and related infrastructure like the | |
3913 | hotplug interrupt storm detection and mitigation code. Note that the | |
3914 | i915 driver still uses most of the common DRM helper code for output | |
3915 | probing, so those sections fully apply. | |
3916 | </para> | |
3917 | </sect2> | |
28855d2a JN |
3918 | <sect2> |
3919 | <title>High Definition Audio</title> | |
3920 | !Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port | |
3921 | !Idrivers/gpu/drm/i915/intel_audio.c | |
b2b89f55 RV |
3922 | </sect2> |
3923 | <sect2> | |
3924 | <title>Panel Self Refresh PSR (PSR/SRD)</title> | |
3925 | !Pdrivers/gpu/drm/i915/intel_psr.c Panel Self Refresh (PSR/SRD) | |
3926 | !Idrivers/gpu/drm/i915/intel_psr.c | |
94b83957 RV |
3927 | </sect2> |
3928 | <sect2> | |
3929 | <title>Frame Buffer Compression (FBC)</title> | |
3930 | !Pdrivers/gpu/drm/i915/intel_fbc.c Frame Buffer Compression (FBC) | |
3931 | !Idrivers/gpu/drm/i915/intel_fbc.c | |
28855d2a | 3932 | </sect2> |
0e767189 VS |
3933 | <sect2> |
3934 | <title>DPIO</title> | |
3935 | !Pdrivers/gpu/drm/i915/i915_reg.h DPIO | |
111a9c14 VS |
3936 | <table id="dpiox2"> |
3937 | <title>Dual channel PHY (VLV/CHV)</title> | |
3938 | <tgroup cols="8"> | |
3939 | <colspec colname="c0" /> | |
3940 | <colspec colname="c1" /> | |
3941 | <colspec colname="c2" /> | |
3942 | <colspec colname="c3" /> | |
3943 | <colspec colname="c4" /> | |
3944 | <colspec colname="c5" /> | |
3945 | <colspec colname="c6" /> | |
3946 | <colspec colname="c7" /> | |
3947 | <spanspec spanname="ch0" namest="c0" nameend="c3" /> | |
3948 | <spanspec spanname="ch1" namest="c4" nameend="c7" /> | |
3949 | <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" /> | |
3950 | <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" /> | |
3951 | <spanspec spanname="ch1pcs01" namest="c4" nameend="c5" /> | |
3952 | <spanspec spanname="ch1pcs23" namest="c6" nameend="c7" /> | |
3953 | <thead> | |
3954 | <row> | |
3955 | <entry spanname="ch0">CH0</entry> | |
3956 | <entry spanname="ch1">CH1</entry> | |
3957 | </row> | |
3958 | </thead> | |
3959 | <tbody valign="top" align="center"> | |
3960 | <row> | |
3961 | <entry spanname="ch0">CMN/PLL/REF</entry> | |
3962 | <entry spanname="ch1">CMN/PLL/REF</entry> | |
3963 | </row> | |
3964 | <row> | |
3965 | <entry spanname="ch0pcs01">PCS01</entry> | |
3966 | <entry spanname="ch0pcs23">PCS23</entry> | |
3967 | <entry spanname="ch1pcs01">PCS01</entry> | |
3968 | <entry spanname="ch1pcs23">PCS23</entry> | |
3969 | </row> | |
3970 | <row> | |
3971 | <entry>TX0</entry> | |
3972 | <entry>TX1</entry> | |
3973 | <entry>TX2</entry> | |
3974 | <entry>TX3</entry> | |
3975 | <entry>TX0</entry> | |
3976 | <entry>TX1</entry> | |
3977 | <entry>TX2</entry> | |
3978 | <entry>TX3</entry> | |
3979 | </row> | |
3980 | <row> | |
3981 | <entry spanname="ch0">DDI0</entry> | |
3982 | <entry spanname="ch1">DDI1</entry> | |
3983 | </row> | |
3984 | </tbody> | |
3985 | </tgroup> | |
3986 | </table> | |
3987 | <table id="dpiox1"> | |
3988 | <title>Single channel PHY (CHV)</title> | |
3989 | <tgroup cols="4"> | |
3990 | <colspec colname="c0" /> | |
3991 | <colspec colname="c1" /> | |
3992 | <colspec colname="c2" /> | |
3993 | <colspec colname="c3" /> | |
3994 | <spanspec spanname="ch0" namest="c0" nameend="c3" /> | |
3995 | <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" /> | |
3996 | <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" /> | |
3997 | <thead> | |
3998 | <row> | |
3999 | <entry spanname="ch0">CH0</entry> | |
4000 | </row> | |
4001 | </thead> | |
4002 | <tbody valign="top" align="center"> | |
4003 | <row> | |
4004 | <entry spanname="ch0">CMN/PLL/REF</entry> | |
4005 | </row> | |
4006 | <row> | |
4007 | <entry spanname="ch0pcs01">PCS01</entry> | |
4008 | <entry spanname="ch0pcs23">PCS23</entry> | |
4009 | </row> | |
4010 | <row> | |
4011 | <entry>TX0</entry> | |
4012 | <entry>TX1</entry> | |
4013 | <entry>TX2</entry> | |
4014 | <entry>TX3</entry> | |
4015 | </row> | |
4016 | <row> | |
4017 | <entry spanname="ch0">DDI2</entry> | |
4018 | </row> | |
4019 | </tbody> | |
4020 | </tgroup> | |
4021 | </table> | |
0e767189 | 4022 | </sect2> |
3519f70e | 4023 | </sect1> |
2d2ef822 | 4024 | |
3519f70e DV |
4025 | <sect1> |
4026 | <title>Memory Management and Command Submission</title> | |
4027 | <para> | |
4028 | This sections covers all things related to the GEM implementation in the | |
4029 | i915 driver. | |
4030 | </para> | |
122b2505 DV |
4031 | <sect2> |
4032 | <title>Batchbuffer Parsing</title> | |
4033 | !Pdrivers/gpu/drm/i915/i915_cmd_parser.c batch buffer command parser | |
4034 | !Idrivers/gpu/drm/i915/i915_cmd_parser.c | |
493018dc BV |
4035 | </sect2> |
4036 | <sect2> | |
4037 | <title>Batchbuffer Pools</title> | |
4038 | !Pdrivers/gpu/drm/i915/i915_gem_batch_pool.c batch pool | |
4039 | !Idrivers/gpu/drm/i915/i915_gem_batch_pool.c | |
122b2505 | 4040 | </sect2> |
73e4d07f OM |
4041 | <sect2> |
4042 | <title>Logical Rings, Logical Ring Contexts and Execlists</title> | |
4043 | !Pdrivers/gpu/drm/i915/intel_lrc.c Logical Rings, Logical Ring Contexts and Execlists | |
4044 | !Idrivers/gpu/drm/i915/intel_lrc.c | |
4045 | </sect2> | |
45f8f69a TU |
4046 | <sect2> |
4047 | <title>Global GTT views</title> | |
4048 | !Pdrivers/gpu/drm/i915/i915_gem_gtt.c Global GTT views | |
4049 | !Idrivers/gpu/drm/i915/i915_gem_gtt.c | |
4050 | </sect2> | |
3519f70e | 4051 | </sect1> |
198c974d DCS |
4052 | |
4053 | <sect1> | |
4054 | <title> Tracing </title> | |
4055 | <para> | |
4056 | This sections covers all things related to the tracepoints implemented in | |
4057 | the i915 driver. | |
4058 | </para> | |
4059 | <sect2> | |
4060 | <title> i915_ppgtt_create and i915_ppgtt_release </title> | |
4061 | !Pdrivers/gpu/drm/i915/i915_trace.h i915_ppgtt_create and i915_ppgtt_release tracepoints | |
4062 | </sect2> | |
4063 | <sect2> | |
4064 | <title> i915_context_create and i915_context_free </title> | |
4065 | !Pdrivers/gpu/drm/i915/i915_trace.h i915_context_create and i915_context_free tracepoints | |
4066 | </sect2> | |
4067 | <sect2> | |
4068 | <title> switch_mm </title> | |
4069 | !Pdrivers/gpu/drm/i915/i915_trace.h switch_mm tracepoint | |
4070 | </sect2> | |
4071 | </sect1> | |
4072 | ||
3519f70e | 4073 | </chapter> |
fca52a55 | 4074 | !Cdrivers/gpu/drm/i915/i915_irq.c |
3519f70e | 4075 | </part> |
2d2ef822 | 4076 | </book> |