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