1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
4
5<book id="drmDevelopersGuide">
6  <bookinfo>
7    <title>Linux DRM Developer's Guide</title>
8
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>
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>
43    </authorgroup>
44
45    <copyright>
46      <year>2008-2009</year>
47      <year>2013-2014</year>
48      <holder>Intel Corporation</holder>
49    </copyright>
50    <copyright>
51      <year>2012</year>
52      <holder>Laurent Pinchart</holder>
53    </copyright>
54
55    <legalnotice>
56      <para>
57	The contents of this file may be used under the terms of the GNU
58	General Public License version 2 (the "GPL") as distributed in
59	the kernel source COPYING file.
60      </para>
61    </legalnotice>
62
63    <revhistory>
64      <!-- Put document revisions here, newest first. -->
65      <revision>
66	<revnumber>1.0</revnumber>
67	<date>2012-07-13</date>
68	<authorinitials>LP</authorinitials>
69	<revremark>Added extensive documentation about driver internals.
70	</revremark>
71      </revision>
72    </revhistory>
73  </bookinfo>
74
75<toc></toc>
76
77<part id="drmCore">
78  <title>DRM Core</title>
79  <partintro>
80    <para>
81      This first part of the DRM Developer's Guide documents core DRM code,
82      helper libraries for writing drivers and generic userspace interfaces
83      exposed by DRM drivers.
84    </para>
85  </partintro>
86
87  <chapter id="drmIntroduction">
88    <title>Introduction</title>
89    <para>
90      The Linux DRM layer contains code intended to support the needs
91      of complex graphics devices, usually containing programmable
92      pipelines well suited to 3D graphics acceleration.  Graphics
93      drivers in the kernel may make use of DRM functions to make
94      tasks like memory management, interrupt handling and DMA easier,
95      and provide a uniform interface to applications.
96    </para>
97    <para>
98      A note on versions: this guide covers features found in the DRM
99      tree, including the TTM memory manager, output configuration and
100      mode setting, and the new vblank internals, in addition to all
101      the regular features found in current kernels.
102    </para>
103    <para>
104      [Insert diagram of typical DRM stack here]
105    </para>
106  </chapter>
107
108  <!-- Internals -->
109
110  <chapter id="drmInternals">
111    <title>DRM Internals</title>
112    <para>
113      This chapter documents DRM internals relevant to driver authors
114      and developers working to add support for the latest features to
115      existing drivers.
116    </para>
117    <para>
118      First, we go over some typical driver initialization
119      requirements, like setting up command buffers, creating an
120      initial output configuration, and initializing core services.
121      Subsequent sections cover core internals in more detail,
122      providing implementation notes and examples.
123    </para>
124    <para>
125      The DRM layer provides several services to graphics drivers,
126      many of them driven by the application interfaces it provides
127      through libdrm, the library that wraps most of the DRM ioctls.
128      These include vblank event handling, memory
129      management, output management, framebuffer management, command
130      submission &amp; fencing, suspend/resume support, and DMA
131      services.
132    </para>
133
134  <!-- Internals: driver init -->
135
136  <sect1>
137    <title>Driver Initialization</title>
138    <para>
139      At the core of every DRM driver is a <structname>drm_driver</structname>
140      structure. Drivers typically statically initialize a drm_driver structure,
141      and then pass it to one of the <function>drm_*_init()</function> functions
142      to register it with the DRM subsystem.
143    </para>
144    <para>
145      Newer drivers that no longer require a <structname>drm_bus</structname>
146      structure can alternatively use the low-level device initialization and
147      registration functions such as <function>drm_dev_alloc()</function> and
148      <function>drm_dev_register()</function> directly.
149    </para>
150    <para>
151      The <structname>drm_driver</structname> structure contains static
152      information that describes the driver and features it supports, and
153      pointers to methods that the DRM core will call to implement the DRM API.
154      We will first go through the <structname>drm_driver</structname> static
155      information fields, and will then describe individual operations in
156      details as they get used in later sections.
157    </para>
158    <sect2>
159      <title>Driver Information</title>
160      <sect3>
161        <title>Driver Features</title>
162        <para>
163          Drivers inform the DRM core about their requirements and supported
164          features by setting appropriate flags in the
165          <structfield>driver_features</structfield> field. Since those flags
166          influence the DRM core behaviour since registration time, most of them
167          must be set to registering the <structname>drm_driver</structname>
168          instance.
169        </para>
170        <synopsis>u32 driver_features;</synopsis>
171        <variablelist>
172          <title>Driver Feature Flags</title>
173          <varlistentry>
174            <term>DRIVER_USE_AGP</term>
175            <listitem><para>
176              Driver uses AGP interface, the DRM core will manage AGP resources.
177            </para></listitem>
178          </varlistentry>
179          <varlistentry>
180            <term>DRIVER_REQUIRE_AGP</term>
181            <listitem><para>
182              Driver needs AGP interface to function. AGP initialization failure
183              will become a fatal error.
184            </para></listitem>
185          </varlistentry>
186          <varlistentry>
187            <term>DRIVER_PCI_DMA</term>
188            <listitem><para>
189              Driver is capable of PCI DMA, mapping of PCI DMA buffers to
190              userspace will be enabled. Deprecated.
191            </para></listitem>
192          </varlistentry>
193          <varlistentry>
194            <term>DRIVER_SG</term>
195            <listitem><para>
196              Driver can perform scatter/gather DMA, allocation and mapping of
197              scatter/gather buffers will be enabled. Deprecated.
198            </para></listitem>
199          </varlistentry>
200          <varlistentry>
201            <term>DRIVER_HAVE_DMA</term>
202            <listitem><para>
203              Driver supports DMA, the userspace DMA API will be supported.
204              Deprecated.
205            </para></listitem>
206          </varlistentry>
207          <varlistentry>
208            <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
209            <listitem><para>
210              DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler
211              managed by the DRM Core. The core will support simple IRQ handler
212              installation when the flag is set. The installation process is
213              described in <xref linkend="drm-irq-registration"/>.</para>
214              <para>DRIVER_IRQ_SHARED indicates whether the device &amp; handler
215              support shared IRQs (note that this is required of PCI  drivers).
216            </para></listitem>
217          </varlistentry>
218          <varlistentry>
219            <term>DRIVER_GEM</term>
220            <listitem><para>
221              Driver use the GEM memory manager.
222            </para></listitem>
223          </varlistentry>
224          <varlistentry>
225            <term>DRIVER_MODESET</term>
226            <listitem><para>
227              Driver supports mode setting interfaces (KMS).
228            </para></listitem>
229          </varlistentry>
230          <varlistentry>
231            <term>DRIVER_PRIME</term>
232            <listitem><para>
233              Driver implements DRM PRIME buffer sharing.
234            </para></listitem>
235          </varlistentry>
236          <varlistentry>
237            <term>DRIVER_RENDER</term>
238            <listitem><para>
239              Driver supports dedicated render nodes.
240            </para></listitem>
241          </varlistentry>
242          <varlistentry>
243            <term>DRIVER_ATOMIC</term>
244            <listitem><para>
245              Driver supports atomic properties.  In this case the driver
246              must implement appropriate obj->atomic_get_property() vfuncs
247              for any modeset objects with driver specific properties.
248            </para></listitem>
249          </varlistentry>
250        </variablelist>
251      </sect3>
252      <sect3>
253        <title>Major, Minor and Patchlevel</title>
254        <synopsis>int major;
255int minor;
256int patchlevel;</synopsis>
257        <para>
258          The DRM core identifies driver versions by a major, minor and patch
259          level triplet. The information is printed to the kernel log at
260          initialization time and passed to userspace through the
261          DRM_IOCTL_VERSION ioctl.
262        </para>
263        <para>
264          The major and minor numbers are also used to verify the requested driver
265          API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes
266          between minor versions, applications can call DRM_IOCTL_SET_VERSION to
267          select a specific version of the API. If the requested major isn't equal
268          to the driver major, or the requested minor is larger than the driver
269          minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise
270          the driver's set_version() method will be called with the requested
271          version.
272        </para>
273      </sect3>
274      <sect3>
275        <title>Name, Description and Date</title>
276        <synopsis>char *name;
277char *desc;
278char *date;</synopsis>
279        <para>
280          The driver name is printed to the kernel log at initialization time,
281          used for IRQ registration and passed to userspace through
282          DRM_IOCTL_VERSION.
283        </para>
284        <para>
285          The driver description is a purely informative string passed to
286          userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
287          the kernel.
288        </para>
289        <para>
290          The driver date, formatted as YYYYMMDD, is meant to identify the date of
291          the latest modification to the driver. However, as most drivers fail to
292          update it, its value is mostly useless. The DRM core prints it to the
293          kernel log at initialization time and passes it to userspace through the
294          DRM_IOCTL_VERSION ioctl.
295        </para>
296      </sect3>
297    </sect2>
298    <sect2>
299      <title>Device Registration</title>
300      <para>
301        A number of functions are provided to help with device registration.
302        The functions deal with PCI and platform devices, respectively.
303      </para>
304<!-- drivers/gpu/drm/drm_pci.c -->
305<refentry id="API-drm-pci-alloc">
306<refentryinfo>
307 <title>LINUX</title>
308 <productname>Kernel Hackers Manual</productname>
309 <date>July 2017</date>
310</refentryinfo>
311<refmeta>
312 <refentrytitle><phrase>drm_pci_alloc</phrase></refentrytitle>
313 <manvolnum>9</manvolnum>
314 <refmiscinfo class="version">4.1.27</refmiscinfo>
315</refmeta>
316<refnamediv>
317 <refname>drm_pci_alloc</refname>
318 <refpurpose>
319  Allocate a PCI consistent memory block, for DMA.
320 </refpurpose>
321</refnamediv>
322<refsynopsisdiv>
323 <title>Synopsis</title>
324  <funcsynopsis><funcprototype>
325   <funcdef>drm_dma_handle_t * <function>drm_pci_alloc </function></funcdef>
326   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
327   <paramdef>size_t <parameter>size</parameter></paramdef>
328   <paramdef>size_t <parameter>align</parameter></paramdef>
329  </funcprototype></funcsynopsis>
330</refsynopsisdiv>
331<refsect1>
332 <title>Arguments</title>
333 <variablelist>
334  <varlistentry>
335   <term><parameter>dev</parameter></term>
336   <listitem>
337    <para>
338     DRM device
339    </para>
340   </listitem>
341  </varlistentry>
342  <varlistentry>
343   <term><parameter>size</parameter></term>
344   <listitem>
345    <para>
346     size of block to allocate
347    </para>
348   </listitem>
349  </varlistentry>
350  <varlistentry>
351   <term><parameter>align</parameter></term>
352   <listitem>
353    <para>
354     alignment of block
355    </para>
356   </listitem>
357  </varlistentry>
358 </variablelist>
359</refsect1>
360<refsect1>
361<title>Return</title>
362<para>
363   A handle to the allocated memory block on success or NULL on
364   failure.
365</para>
366</refsect1>
367</refentry>
368
369<refentry id="API-drm-pci-free">
370<refentryinfo>
371 <title>LINUX</title>
372 <productname>Kernel Hackers Manual</productname>
373 <date>July 2017</date>
374</refentryinfo>
375<refmeta>
376 <refentrytitle><phrase>drm_pci_free</phrase></refentrytitle>
377 <manvolnum>9</manvolnum>
378 <refmiscinfo class="version">4.1.27</refmiscinfo>
379</refmeta>
380<refnamediv>
381 <refname>drm_pci_free</refname>
382 <refpurpose>
383     Free a PCI consistent memory block
384 </refpurpose>
385</refnamediv>
386<refsynopsisdiv>
387 <title>Synopsis</title>
388  <funcsynopsis><funcprototype>
389   <funcdef>void <function>drm_pci_free </function></funcdef>
390   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
391   <paramdef>drm_dma_handle_t * <parameter>dmah</parameter></paramdef>
392  </funcprototype></funcsynopsis>
393</refsynopsisdiv>
394<refsect1>
395 <title>Arguments</title>
396 <variablelist>
397  <varlistentry>
398   <term><parameter>dev</parameter></term>
399   <listitem>
400    <para>
401     DRM device
402    </para>
403   </listitem>
404  </varlistentry>
405  <varlistentry>
406   <term><parameter>dmah</parameter></term>
407   <listitem>
408    <para>
409     handle to memory block
410    </para>
411   </listitem>
412  </varlistentry>
413 </variablelist>
414</refsect1>
415</refentry>
416
417<refentry id="API-drm-get-pci-dev">
418<refentryinfo>
419 <title>LINUX</title>
420 <productname>Kernel Hackers Manual</productname>
421 <date>July 2017</date>
422</refentryinfo>
423<refmeta>
424 <refentrytitle><phrase>drm_get_pci_dev</phrase></refentrytitle>
425 <manvolnum>9</manvolnum>
426 <refmiscinfo class="version">4.1.27</refmiscinfo>
427</refmeta>
428<refnamediv>
429 <refname>drm_get_pci_dev</refname>
430 <refpurpose>
431     Register a PCI device with the DRM subsystem
432 </refpurpose>
433</refnamediv>
434<refsynopsisdiv>
435 <title>Synopsis</title>
436  <funcsynopsis><funcprototype>
437   <funcdef>int <function>drm_get_pci_dev </function></funcdef>
438   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
439   <paramdef>const struct pci_device_id * <parameter>ent</parameter></paramdef>
440   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
441  </funcprototype></funcsynopsis>
442</refsynopsisdiv>
443<refsect1>
444 <title>Arguments</title>
445 <variablelist>
446  <varlistentry>
447   <term><parameter>pdev</parameter></term>
448   <listitem>
449    <para>
450     PCI device
451    </para>
452   </listitem>
453  </varlistentry>
454  <varlistentry>
455   <term><parameter>ent</parameter></term>
456   <listitem>
457    <para>
458     entry from the PCI ID table that matches <parameter>pdev</parameter>
459    </para>
460   </listitem>
461  </varlistentry>
462  <varlistentry>
463   <term><parameter>driver</parameter></term>
464   <listitem>
465    <para>
466     DRM device driver
467    </para>
468   </listitem>
469  </varlistentry>
470 </variablelist>
471</refsect1>
472<refsect1>
473<title>Description</title>
474<para>
475   Attempt to gets inter module <quote>drm</quote> information. If we are first
476   then register the character device and inter module information.
477   Try and register, if we fail to register, backout previous work.
478</para>
479</refsect1>
480<refsect1>
481<title>Return</title>
482<para>
483   0 on success or a negative error code on failure.
484</para>
485</refsect1>
486</refentry>
487
488<refentry id="API-drm-pci-init">
489<refentryinfo>
490 <title>LINUX</title>
491 <productname>Kernel Hackers Manual</productname>
492 <date>July 2017</date>
493</refentryinfo>
494<refmeta>
495 <refentrytitle><phrase>drm_pci_init</phrase></refentrytitle>
496 <manvolnum>9</manvolnum>
497 <refmiscinfo class="version">4.1.27</refmiscinfo>
498</refmeta>
499<refnamediv>
500 <refname>drm_pci_init</refname>
501 <refpurpose>
502     Register matching PCI devices with the DRM subsystem
503 </refpurpose>
504</refnamediv>
505<refsynopsisdiv>
506 <title>Synopsis</title>
507  <funcsynopsis><funcprototype>
508   <funcdef>int <function>drm_pci_init </function></funcdef>
509   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
510   <paramdef>struct pci_driver * <parameter>pdriver</parameter></paramdef>
511  </funcprototype></funcsynopsis>
512</refsynopsisdiv>
513<refsect1>
514 <title>Arguments</title>
515 <variablelist>
516  <varlistentry>
517   <term><parameter>driver</parameter></term>
518   <listitem>
519    <para>
520     DRM device driver
521    </para>
522   </listitem>
523  </varlistentry>
524  <varlistentry>
525   <term><parameter>pdriver</parameter></term>
526   <listitem>
527    <para>
528     PCI device driver
529    </para>
530   </listitem>
531  </varlistentry>
532 </variablelist>
533</refsect1>
534<refsect1>
535<title>Description</title>
536<para>
537   Initializes a drm_device structures, registering the stubs and initializing
538   the AGP device.
539</para>
540</refsect1>
541<refsect1>
542<title>Return</title>
543<para>
544   0 on success or a negative error code on failure.
545</para>
546</refsect1>
547</refentry>
548
549<refentry id="API-drm-pci-exit">
550<refentryinfo>
551 <title>LINUX</title>
552 <productname>Kernel Hackers Manual</productname>
553 <date>July 2017</date>
554</refentryinfo>
555<refmeta>
556 <refentrytitle><phrase>drm_pci_exit</phrase></refentrytitle>
557 <manvolnum>9</manvolnum>
558 <refmiscinfo class="version">4.1.27</refmiscinfo>
559</refmeta>
560<refnamediv>
561 <refname>drm_pci_exit</refname>
562 <refpurpose>
563     Unregister matching PCI devices from the DRM subsystem
564 </refpurpose>
565</refnamediv>
566<refsynopsisdiv>
567 <title>Synopsis</title>
568  <funcsynopsis><funcprototype>
569   <funcdef>void <function>drm_pci_exit </function></funcdef>
570   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
571   <paramdef>struct pci_driver * <parameter>pdriver</parameter></paramdef>
572  </funcprototype></funcsynopsis>
573</refsynopsisdiv>
574<refsect1>
575 <title>Arguments</title>
576 <variablelist>
577  <varlistentry>
578   <term><parameter>driver</parameter></term>
579   <listitem>
580    <para>
581     DRM device driver
582    </para>
583   </listitem>
584  </varlistentry>
585  <varlistentry>
586   <term><parameter>pdriver</parameter></term>
587   <listitem>
588    <para>
589     PCI device driver
590    </para>
591   </listitem>
592  </varlistentry>
593 </variablelist>
594</refsect1>
595<refsect1>
596<title>Description</title>
597<para>
598   Unregisters one or more devices matched by a PCI driver from the DRM
599   subsystem.
600</para>
601</refsect1>
602</refentry>
603
604<!-- drivers/gpu/drm/drm_platform.c -->
605<refentry id="API-drm-platform-init">
606<refentryinfo>
607 <title>LINUX</title>
608 <productname>Kernel Hackers Manual</productname>
609 <date>July 2017</date>
610</refentryinfo>
611<refmeta>
612 <refentrytitle><phrase>drm_platform_init</phrase></refentrytitle>
613 <manvolnum>9</manvolnum>
614 <refmiscinfo class="version">4.1.27</refmiscinfo>
615</refmeta>
616<refnamediv>
617 <refname>drm_platform_init</refname>
618 <refpurpose>
619  Register a platform device with the DRM subsystem
620 </refpurpose>
621</refnamediv>
622<refsynopsisdiv>
623 <title>Synopsis</title>
624  <funcsynopsis><funcprototype>
625   <funcdef>int <function>drm_platform_init </function></funcdef>
626   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
627   <paramdef>struct platform_device * <parameter>platform_device</parameter></paramdef>
628  </funcprototype></funcsynopsis>
629</refsynopsisdiv>
630<refsect1>
631 <title>Arguments</title>
632 <variablelist>
633  <varlistentry>
634   <term><parameter>driver</parameter></term>
635   <listitem>
636    <para>
637     DRM device driver
638    </para>
639   </listitem>
640  </varlistentry>
641  <varlistentry>
642   <term><parameter>platform_device</parameter></term>
643   <listitem>
644    <para>
645     platform device to register
646    </para>
647   </listitem>
648  </varlistentry>
649 </variablelist>
650</refsect1>
651<refsect1>
652<title>Description</title>
653<para>
654   Registers the specified DRM device driver and platform device with the DRM
655   subsystem, initializing a drm_device structure and calling the driver's
656   .<function>load</function> function.
657</para>
658</refsect1>
659<refsect1>
660<title>Return</title>
661<para>
662   0 on success or a negative error code on failure.
663</para>
664</refsect1>
665</refentry>
666
667      <para>
668        New drivers that no longer rely on the services provided by the
669        <structname>drm_bus</structname> structure can call the low-level
670        device registration functions directly. The
671        <function>drm_dev_alloc()</function> function can be used to allocate
672        and initialize a new <structname>drm_device</structname> structure.
673        Drivers will typically want to perform some additional setup on this
674        structure, such as allocating driver-specific data and storing a
675        pointer to it in the DRM device's <structfield>dev_private</structfield>
676        field. Drivers should also set the device's unique name using the
677        <function>drm_dev_set_unique()</function> function. After it has been
678        set up a device can be registered with the DRM subsystem by calling
679        <function>drm_dev_register()</function>. This will cause the device to
680        be exposed to userspace and will call the driver's
681        <structfield>.load()</structfield> implementation. When a device is
682        removed, the DRM device can safely be unregistered and freed by calling
683        <function>drm_dev_unregister()</function> followed by a call to
684        <function>drm_dev_unref()</function>.
685      </para>
686<!-- drivers/gpu/drm/drm_drv.c -->
687<refentry id="API-drm-put-dev">
688<refentryinfo>
689 <title>LINUX</title>
690 <productname>Kernel Hackers Manual</productname>
691 <date>July 2017</date>
692</refentryinfo>
693<refmeta>
694 <refentrytitle><phrase>drm_put_dev</phrase></refentrytitle>
695 <manvolnum>9</manvolnum>
696 <refmiscinfo class="version">4.1.27</refmiscinfo>
697</refmeta>
698<refnamediv>
699 <refname>drm_put_dev</refname>
700 <refpurpose>
701  Unregister and release a DRM device
702 </refpurpose>
703</refnamediv>
704<refsynopsisdiv>
705 <title>Synopsis</title>
706  <funcsynopsis><funcprototype>
707   <funcdef>void <function>drm_put_dev </function></funcdef>
708   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
709  </funcprototype></funcsynopsis>
710</refsynopsisdiv>
711<refsect1>
712 <title>Arguments</title>
713 <variablelist>
714  <varlistentry>
715   <term><parameter>dev</parameter></term>
716   <listitem>
717    <para>
718     DRM device
719    </para>
720   </listitem>
721  </varlistentry>
722 </variablelist>
723</refsect1>
724<refsect1>
725<title>Description</title>
726<para>
727   Called at module unload time or when a PCI device is unplugged.
728   </para><para>
729
730   Use of this function is discouraged. It will eventually go away completely.
731   Please use <function>drm_dev_unregister</function> and <function>drm_dev_unref</function> explicitly instead.
732   </para><para>
733
734   Cleans up all DRM device, calling <function>drm_lastclose</function>.
735</para>
736</refsect1>
737</refentry>
738
739<refentry id="API-drm-dev-alloc">
740<refentryinfo>
741 <title>LINUX</title>
742 <productname>Kernel Hackers Manual</productname>
743 <date>July 2017</date>
744</refentryinfo>
745<refmeta>
746 <refentrytitle><phrase>drm_dev_alloc</phrase></refentrytitle>
747 <manvolnum>9</manvolnum>
748 <refmiscinfo class="version">4.1.27</refmiscinfo>
749</refmeta>
750<refnamediv>
751 <refname>drm_dev_alloc</refname>
752 <refpurpose>
753     Allocate new DRM device
754 </refpurpose>
755</refnamediv>
756<refsynopsisdiv>
757 <title>Synopsis</title>
758  <funcsynopsis><funcprototype>
759   <funcdef>struct drm_device * <function>drm_dev_alloc </function></funcdef>
760   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
761   <paramdef>struct device * <parameter>parent</parameter></paramdef>
762  </funcprototype></funcsynopsis>
763</refsynopsisdiv>
764<refsect1>
765 <title>Arguments</title>
766 <variablelist>
767  <varlistentry>
768   <term><parameter>driver</parameter></term>
769   <listitem>
770    <para>
771     DRM driver to allocate device for
772    </para>
773   </listitem>
774  </varlistentry>
775  <varlistentry>
776   <term><parameter>parent</parameter></term>
777   <listitem>
778    <para>
779     Parent device object
780    </para>
781   </listitem>
782  </varlistentry>
783 </variablelist>
784</refsect1>
785<refsect1>
786<title>Description</title>
787<para>
788   Allocate and initialize a new DRM device. No device registration is done.
789   Call <function>drm_dev_register</function> to advertice the device to user space and register it
790   with other core subsystems.
791   </para><para>
792
793   The initial ref-count of the object is 1. Use <function>drm_dev_ref</function> and
794   <function>drm_dev_unref</function> to take and drop further ref-counts.
795   </para><para>
796
797   Note that for purely virtual devices <parameter>parent</parameter> can be NULL.
798</para>
799</refsect1>
800<refsect1>
801<title>RETURNS</title>
802<para>
803   Pointer to new DRM device, or NULL if out of memory.
804</para>
805</refsect1>
806</refentry>
807
808<refentry id="API-drm-dev-ref">
809<refentryinfo>
810 <title>LINUX</title>
811 <productname>Kernel Hackers Manual</productname>
812 <date>July 2017</date>
813</refentryinfo>
814<refmeta>
815 <refentrytitle><phrase>drm_dev_ref</phrase></refentrytitle>
816 <manvolnum>9</manvolnum>
817 <refmiscinfo class="version">4.1.27</refmiscinfo>
818</refmeta>
819<refnamediv>
820 <refname>drm_dev_ref</refname>
821 <refpurpose>
822     Take reference of a DRM device
823 </refpurpose>
824</refnamediv>
825<refsynopsisdiv>
826 <title>Synopsis</title>
827  <funcsynopsis><funcprototype>
828   <funcdef>void <function>drm_dev_ref </function></funcdef>
829   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
830  </funcprototype></funcsynopsis>
831</refsynopsisdiv>
832<refsect1>
833 <title>Arguments</title>
834 <variablelist>
835  <varlistentry>
836   <term><parameter>dev</parameter></term>
837   <listitem>
838    <para>
839     device to take reference of or NULL
840    </para>
841   </listitem>
842  </varlistentry>
843 </variablelist>
844</refsect1>
845<refsect1>
846<title>Description</title>
847<para>
848   This increases the ref-count of <parameter>dev</parameter> by one. You *must* already own a
849   reference when calling this. Use <function>drm_dev_unref</function> to drop this reference
850   again.
851   </para><para>
852
853   This function never fails. However, this function does not provide *any*
854   guarantee whether the device is alive or running. It only provides a
855   reference to the object and the memory associated with it.
856</para>
857</refsect1>
858</refentry>
859
860<refentry id="API-drm-dev-unref">
861<refentryinfo>
862 <title>LINUX</title>
863 <productname>Kernel Hackers Manual</productname>
864 <date>July 2017</date>
865</refentryinfo>
866<refmeta>
867 <refentrytitle><phrase>drm_dev_unref</phrase></refentrytitle>
868 <manvolnum>9</manvolnum>
869 <refmiscinfo class="version">4.1.27</refmiscinfo>
870</refmeta>
871<refnamediv>
872 <refname>drm_dev_unref</refname>
873 <refpurpose>
874     Drop reference of a DRM device
875 </refpurpose>
876</refnamediv>
877<refsynopsisdiv>
878 <title>Synopsis</title>
879  <funcsynopsis><funcprototype>
880   <funcdef>void <function>drm_dev_unref </function></funcdef>
881   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
882  </funcprototype></funcsynopsis>
883</refsynopsisdiv>
884<refsect1>
885 <title>Arguments</title>
886 <variablelist>
887  <varlistentry>
888   <term><parameter>dev</parameter></term>
889   <listitem>
890    <para>
891     device to drop reference of or NULL
892    </para>
893   </listitem>
894  </varlistentry>
895 </variablelist>
896</refsect1>
897<refsect1>
898<title>Description</title>
899<para>
900   This decreases the ref-count of <parameter>dev</parameter> by one. The device is destroyed if the
901   ref-count drops to zero.
902</para>
903</refsect1>
904</refentry>
905
906<refentry id="API-drm-dev-register">
907<refentryinfo>
908 <title>LINUX</title>
909 <productname>Kernel Hackers Manual</productname>
910 <date>July 2017</date>
911</refentryinfo>
912<refmeta>
913 <refentrytitle><phrase>drm_dev_register</phrase></refentrytitle>
914 <manvolnum>9</manvolnum>
915 <refmiscinfo class="version">4.1.27</refmiscinfo>
916</refmeta>
917<refnamediv>
918 <refname>drm_dev_register</refname>
919 <refpurpose>
920     Register DRM device
921 </refpurpose>
922</refnamediv>
923<refsynopsisdiv>
924 <title>Synopsis</title>
925  <funcsynopsis><funcprototype>
926   <funcdef>int <function>drm_dev_register </function></funcdef>
927   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
928   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
929  </funcprototype></funcsynopsis>
930</refsynopsisdiv>
931<refsect1>
932 <title>Arguments</title>
933 <variablelist>
934  <varlistentry>
935   <term><parameter>dev</parameter></term>
936   <listitem>
937    <para>
938     Device to register
939    </para>
940   </listitem>
941  </varlistentry>
942  <varlistentry>
943   <term><parameter>flags</parameter></term>
944   <listitem>
945    <para>
946     Flags passed to the driver's .<function>load</function> function
947    </para>
948   </listitem>
949  </varlistentry>
950 </variablelist>
951</refsect1>
952<refsect1>
953<title>Description</title>
954<para>
955   Register the DRM device <parameter>dev</parameter> with the system, advertise device to user-space
956   and start normal device operation. <parameter>dev</parameter> must be allocated via <function>drm_dev_alloc</function>
957   previously.
958   </para><para>
959
960   Never call this twice on any device!
961</para>
962</refsect1>
963<refsect1>
964<title>RETURNS</title>
965<para>
966   0 on success, negative error code on failure.
967</para>
968</refsect1>
969</refentry>
970
971<refentry id="API-drm-dev-unregister">
972<refentryinfo>
973 <title>LINUX</title>
974 <productname>Kernel Hackers Manual</productname>
975 <date>July 2017</date>
976</refentryinfo>
977<refmeta>
978 <refentrytitle><phrase>drm_dev_unregister</phrase></refentrytitle>
979 <manvolnum>9</manvolnum>
980 <refmiscinfo class="version">4.1.27</refmiscinfo>
981</refmeta>
982<refnamediv>
983 <refname>drm_dev_unregister</refname>
984 <refpurpose>
985     Unregister DRM device
986 </refpurpose>
987</refnamediv>
988<refsynopsisdiv>
989 <title>Synopsis</title>
990  <funcsynopsis><funcprototype>
991   <funcdef>void <function>drm_dev_unregister </function></funcdef>
992   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
993  </funcprototype></funcsynopsis>
994</refsynopsisdiv>
995<refsect1>
996 <title>Arguments</title>
997 <variablelist>
998  <varlistentry>
999   <term><parameter>dev</parameter></term>
1000   <listitem>
1001    <para>
1002     Device to unregister
1003    </para>
1004   </listitem>
1005  </varlistentry>
1006 </variablelist>
1007</refsect1>
1008<refsect1>
1009<title>Description</title>
1010<para>
1011   Unregister the DRM device from the system. This does the reverse of
1012   <function>drm_dev_register</function> but does not deallocate the device. The caller must call
1013   <function>drm_dev_unref</function> to drop their final reference.
1014</para>
1015</refsect1>
1016</refentry>
1017
1018<refentry id="API-drm-dev-set-unique">
1019<refentryinfo>
1020 <title>LINUX</title>
1021 <productname>Kernel Hackers Manual</productname>
1022 <date>July 2017</date>
1023</refentryinfo>
1024<refmeta>
1025 <refentrytitle><phrase>drm_dev_set_unique</phrase></refentrytitle>
1026 <manvolnum>9</manvolnum>
1027 <refmiscinfo class="version">4.1.27</refmiscinfo>
1028</refmeta>
1029<refnamediv>
1030 <refname>drm_dev_set_unique</refname>
1031 <refpurpose>
1032     Set the unique name of a DRM device
1033 </refpurpose>
1034</refnamediv>
1035<refsynopsisdiv>
1036 <title>Synopsis</title>
1037  <funcsynopsis><funcprototype>
1038   <funcdef>int <function>drm_dev_set_unique </function></funcdef>
1039   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
1040   <paramdef>const char * <parameter>fmt</parameter></paramdef>
1041   <paramdef> <parameter>...</parameter></paramdef>
1042  </funcprototype></funcsynopsis>
1043</refsynopsisdiv>
1044<refsect1>
1045 <title>Arguments</title>
1046 <variablelist>
1047  <varlistentry>
1048   <term><parameter>dev</parameter></term>
1049   <listitem>
1050    <para>
1051     device of which to set the unique name
1052    </para>
1053   </listitem>
1054  </varlistentry>
1055  <varlistentry>
1056   <term><parameter>fmt</parameter></term>
1057   <listitem>
1058    <para>
1059     format string for unique name
1060    </para>
1061   </listitem>
1062  </varlistentry>
1063  <varlistentry>
1064   <term><parameter>...</parameter></term>
1065   <listitem>
1066    <para>
1067     variable arguments
1068    </para>
1069   </listitem>
1070  </varlistentry>
1071 </variablelist>
1072</refsect1>
1073<refsect1>
1074<title>Description</title>
1075<para>
1076   Sets the unique name of a DRM device using the specified format string and
1077   a variable list of arguments. Drivers can use this at driver probe time if
1078   the unique name of the devices they drive is static.
1079</para>
1080</refsect1>
1081<refsect1>
1082<title>Return</title>
1083<para>
1084   0 on success or a negative error code on failure.
1085</para>
1086</refsect1>
1087</refentry>
1088
1089    </sect2>
1090    <sect2>
1091      <title>Driver Load</title>
1092      <para>
1093        The <methodname>load</methodname> method is the driver and device
1094        initialization entry point. The method is responsible for allocating and
1095	initializing driver private data, performing resource allocation and
1096	mapping (e.g. acquiring
1097        clocks, mapping registers or allocating command buffers), initializing
1098        the memory manager (<xref linkend="drm-memory-management"/>), installing
1099        the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up
1100        vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode
1101	setting (<xref linkend="drm-mode-setting"/>) and initial output
1102	configuration (<xref linkend="drm-kms-init"/>).
1103      </para>
1104      <note><para>
1105        If compatibility is a concern (e.g. with drivers converted over from
1106        User Mode Setting to Kernel Mode Setting), care must be taken to prevent
1107        device initialization and control that is incompatible with currently
1108        active userspace drivers. For instance, if user level mode setting
1109        drivers are in use, it would be problematic to perform output discovery
1110        &amp; configuration at load time. Likewise, if user-level drivers
1111        unaware of memory management are in use, memory management and command
1112        buffer setup may need to be omitted. These requirements are
1113        driver-specific, and care needs to be taken to keep both old and new
1114        applications and libraries working.
1115      </para></note>
1116      <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis>
1117      <para>
1118        The method takes two arguments, a pointer to the newly created
1119	<structname>drm_device</structname> and flags. The flags are used to
1120	pass the <structfield>driver_data</structfield> field of the device id
1121	corresponding to the device passed to <function>drm_*_init()</function>.
1122	Only PCI devices currently use this, USB and platform DRM drivers have
1123	their <methodname>load</methodname> method called with flags to 0.
1124      </para>
1125      <sect3>
1126        <title>Driver Private Data</title>
1127        <para>
1128          The driver private hangs off the main
1129          <structname>drm_device</structname> structure and can be used for
1130          tracking various device-specific bits of information, like register
1131          offsets, command buffer status, register state for suspend/resume, etc.
1132          At load time, a driver may simply allocate one and set
1133          <structname>drm_device</structname>.<structfield>dev_priv</structfield>
1134          appropriately; it should be freed and
1135          <structname>drm_device</structname>.<structfield>dev_priv</structfield>
1136          set to NULL when the driver is unloaded.
1137        </para>
1138      </sect3>
1139      <sect3 id="drm-irq-registration">
1140        <title>IRQ Registration</title>
1141        <para>
1142          The DRM core tries to facilitate IRQ handler registration and
1143          unregistration by providing <function>drm_irq_install</function> and
1144          <function>drm_irq_uninstall</function> functions. Those functions only
1145          support a single interrupt per device, devices that use more than one
1146          IRQs need to be handled manually.
1147        </para>
1148        <sect4>
1149          <title>Managed IRQ Registration</title>
1150          <para>
1151            <function>drm_irq_install</function> starts by calling the
1152            <methodname>irq_preinstall</methodname> driver operation. The operation
1153            is optional and must make sure that the interrupt will not get fired by
1154            clearing all pending interrupt flags or disabling the interrupt.
1155          </para>
1156          <para>
1157            The passed-in IRQ will then be requested by a call to
1158            <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
1159            feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
1160            requested.
1161          </para>
1162          <para>
1163            The IRQ handler function must be provided as the mandatory irq_handler
1164            driver operation. It will get passed directly to
1165            <function>request_irq</function> and thus has the same prototype as all
1166            IRQ handlers. It will get called with a pointer to the DRM device as the
1167            second argument.
1168          </para>
1169          <para>
1170            Finally the function calls the optional
1171            <methodname>irq_postinstall</methodname> driver operation. The operation
1172            usually enables interrupts (excluding the vblank interrupt, which is
1173            enabled separately), but drivers may choose to enable/disable interrupts
1174            at a different time.
1175          </para>
1176          <para>
1177            <function>drm_irq_uninstall</function> is similarly used to uninstall an
1178            IRQ handler. It starts by waking up all processes waiting on a vblank
1179            interrupt to make sure they don't hang, and then calls the optional
1180            <methodname>irq_uninstall</methodname> driver operation. The operation
1181            must disable all hardware interrupts. Finally the function frees the IRQ
1182            by calling <function>free_irq</function>.
1183          </para>
1184        </sect4>
1185        <sect4>
1186          <title>Manual IRQ Registration</title>
1187          <para>
1188            Drivers that require multiple interrupt handlers can't use the managed
1189            IRQ registration functions. In that case IRQs must be registered and
1190            unregistered manually (usually with the <function>request_irq</function>
1191            and <function>free_irq</function> functions, or their devm_* equivalent).
1192          </para>
1193          <para>
1194            When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ
1195            driver feature flag, and must not provide the
1196	    <methodname>irq_handler</methodname> driver operation. They must set the
1197	    <structname>drm_device</structname> <structfield>irq_enabled</structfield>
1198	    field to 1 upon registration of the IRQs, and clear it to 0 after
1199	    unregistering the IRQs.
1200          </para>
1201        </sect4>
1202      </sect3>
1203      <sect3>
1204        <title>Memory Manager Initialization</title>
1205        <para>
1206          Every DRM driver requires a memory manager which must be initialized at
1207          load time. DRM currently contains two memory managers, the Translation
1208          Table Manager (TTM) and the Graphics Execution Manager (GEM).
1209          This document describes the use of the GEM memory manager only. See
1210          <xref linkend="drm-memory-management"/> for details.
1211        </para>
1212      </sect3>
1213      <sect3>
1214        <title>Miscellaneous Device Configuration</title>
1215        <para>
1216          Another task that may be necessary for PCI devices during configuration
1217          is mapping the video BIOS. On many devices, the VBIOS describes device
1218          configuration, LCD panel timings (if any), and contains flags indicating
1219          device state. Mapping the BIOS can be done using the pci_map_rom() call,
1220          a convenience function that takes care of mapping the actual ROM,
1221          whether it has been shadowed into memory (typically at address 0xc0000)
1222          or exists on the PCI device in the ROM BAR. Note that after the ROM has
1223          been mapped and any necessary information has been extracted, it should
1224          be unmapped; on many devices, the ROM address decoder is shared with
1225          other BARs, so leaving it mapped could cause undesired behaviour like
1226          hangs or memory corruption.
1227  <!--!Fdrivers/pci/rom.c pci_map_rom-->
1228        </para>
1229      </sect3>
1230    </sect2>
1231  </sect1>
1232
1233  <!-- Internals: memory management -->
1234
1235  <sect1 id="drm-memory-management">
1236    <title>Memory management</title>
1237    <para>
1238      Modern Linux systems require large amount of graphics memory to store
1239      frame buffers, textures, vertices and other graphics-related data. Given
1240      the very dynamic nature of many of that data, managing graphics memory
1241      efficiently is thus crucial for the graphics stack and plays a central
1242      role in the DRM infrastructure.
1243    </para>
1244    <para>
1245      The DRM core includes two memory managers, namely Translation Table Maps
1246      (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory
1247      manager to be developed and tried to be a one-size-fits-them all
1248      solution. It provides a single userspace API to accommodate the need of
1249      all hardware, supporting both Unified Memory Architecture (UMA) devices
1250      and devices with dedicated video RAM (i.e. most discrete video cards).
1251      This resulted in a large, complex piece of code that turned out to be
1252      hard to use for driver development.
1253    </para>
1254    <para>
1255      GEM started as an Intel-sponsored project in reaction to TTM's
1256      complexity. Its design philosophy is completely different: instead of
1257      providing a solution to every graphics memory-related problems, GEM
1258      identified common code between drivers and created a support library to
1259      share it. GEM has simpler initialization and execution requirements than
1260      TTM, but has no video RAM management capabilities and is thus limited to
1261      UMA devices.
1262    </para>
1263    <sect2>
1264      <title>The Translation Table Manager (TTM)</title>
1265      <para>
1266        TTM design background and information belongs here.
1267      </para>
1268      <sect3>
1269        <title>TTM initialization</title>
1270        <warning><para>This section is outdated.</para></warning>
1271        <para>
1272          Drivers wishing to support TTM must fill out a drm_bo_driver
1273          structure. The structure contains several fields with function
1274          pointers for initializing the TTM, allocating and freeing memory,
1275          waiting for command completion and fence synchronization, and memory
1276          migration. See the radeon_ttm.c file for an example of usage.
1277        </para>
1278        <para>
1279          The ttm_global_reference structure is made up of several fields:
1280        </para>
1281        <programlisting>
1282          struct ttm_global_reference {
1283                  enum ttm_global_types global_type;
1284                  size_t size;
1285                  void *object;
1286                  int (*init) (struct ttm_global_reference *);
1287                  void (*release) (struct ttm_global_reference *);
1288          };
1289        </programlisting>
1290        <para>
1291          There should be one global reference structure for your memory
1292          manager as a whole, and there will be others for each object
1293          created by the memory manager at runtime.  Your global TTM should
1294          have a type of TTM_GLOBAL_TTM_MEM.  The size field for the global
1295          object should be sizeof(struct ttm_mem_global), and the init and
1296          release hooks should point at your driver-specific init and
1297          release routines, which probably eventually call
1298          ttm_mem_global_init and ttm_mem_global_release, respectively.
1299        </para>
1300        <para>
1301          Once your global TTM accounting structure is set up and initialized
1302          by calling ttm_global_item_ref() on it,
1303          you need to create a buffer object TTM to
1304          provide a pool for buffer object allocation by clients and the
1305          kernel itself.  The type of this object should be TTM_GLOBAL_TTM_BO,
1306          and its size should be sizeof(struct ttm_bo_global).  Again,
1307          driver-specific init and release functions may be provided,
1308          likely eventually calling ttm_bo_global_init() and
1309          ttm_bo_global_release(), respectively.  Also, like the previous
1310          object, ttm_global_item_ref() is used to create an initial reference
1311          count for the TTM, which will call your initialization function.
1312        </para>
1313      </sect3>
1314    </sect2>
1315    <sect2 id="drm-gem">
1316      <title>The Graphics Execution Manager (GEM)</title>
1317      <para>
1318        The GEM design approach has resulted in a memory manager that doesn't
1319        provide full coverage of all (or even all common) use cases in its
1320        userspace or kernel API. GEM exposes a set of standard memory-related
1321        operations to userspace and a set of helper functions to drivers, and let
1322        drivers implement hardware-specific operations with their own private API.
1323      </para>
1324      <para>
1325        The GEM userspace API is described in the
1326        <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics
1327        Execution Manager</citetitle></ulink> article on LWN. While slightly
1328        outdated, the document provides a good overview of the GEM API principles.
1329        Buffer allocation and read and write operations, described as part of the
1330        common GEM API, are currently implemented using driver-specific ioctls.
1331      </para>
1332      <para>
1333        GEM is data-agnostic. It manages abstract buffer objects without knowing
1334        what individual buffers contain. APIs that require knowledge of buffer
1335        contents or purpose, such as buffer allocation or synchronization
1336        primitives, are thus outside of the scope of GEM and must be implemented
1337        using driver-specific ioctls.
1338      </para>
1339      <para>
1340        On a fundamental level, GEM involves several operations:
1341        <itemizedlist>
1342          <listitem>Memory allocation and freeing</listitem>
1343          <listitem>Command execution</listitem>
1344          <listitem>Aperture management at command execution time</listitem>
1345        </itemizedlist>
1346        Buffer object allocation is relatively straightforward and largely
1347        provided by Linux's shmem layer, which provides memory to back each
1348        object.
1349      </para>
1350      <para>
1351        Device-specific operations, such as command execution, pinning, buffer
1352        read &amp; write, mapping, and domain ownership transfers are left to
1353        driver-specific ioctls.
1354      </para>
1355      <sect3>
1356        <title>GEM Initialization</title>
1357        <para>
1358          Drivers that use GEM must set the DRIVER_GEM bit in the struct
1359          <structname>drm_driver</structname>
1360          <structfield>driver_features</structfield> field. The DRM core will
1361          then automatically initialize the GEM core before calling the
1362          <methodname>load</methodname> operation. Behind the scene, this will
1363          create a DRM Memory Manager object which provides an address space
1364          pool for object allocation.
1365        </para>
1366        <para>
1367          In a KMS configuration, drivers need to allocate and initialize a
1368          command ring buffer following core GEM initialization if required by
1369          the hardware. UMA devices usually have what is called a "stolen"
1370          memory region, which provides space for the initial framebuffer and
1371          large, contiguous memory regions required by the device. This space is
1372          typically not managed by GEM, and must be initialized separately into
1373          its own DRM MM object.
1374        </para>
1375      </sect3>
1376      <sect3>
1377        <title>GEM Objects Creation</title>
1378        <para>
1379          GEM splits creation of GEM objects and allocation of the memory that
1380          backs them in two distinct operations.
1381        </para>
1382        <para>
1383          GEM objects are represented by an instance of struct
1384          <structname>drm_gem_object</structname>. Drivers usually need to extend
1385          GEM objects with private information and thus create a driver-specific
1386          GEM object structure type that embeds an instance of struct
1387          <structname>drm_gem_object</structname>.
1388        </para>
1389        <para>
1390          To create a GEM object, a driver allocates memory for an instance of its
1391          specific GEM object type and initializes the embedded struct
1392          <structname>drm_gem_object</structname> with a call to
1393          <function>drm_gem_object_init</function>. The function takes a pointer to
1394          the DRM device, a pointer to the GEM object and the buffer object size
1395          in bytes.
1396        </para>
1397        <para>
1398          GEM uses shmem to allocate anonymous pageable memory.
1399          <function>drm_gem_object_init</function> will create an shmfs file of
1400          the requested size and store it into the struct
1401          <structname>drm_gem_object</structname> <structfield>filp</structfield>
1402          field. The memory is used as either main storage for the object when the
1403          graphics hardware uses system memory directly or as a backing store
1404          otherwise.
1405        </para>
1406        <para>
1407          Drivers are responsible for the actual physical pages allocation by
1408          calling <function>shmem_read_mapping_page_gfp</function> for each page.
1409          Note that they can decide to allocate pages when initializing the GEM
1410          object, or to delay allocation until the memory is needed (for instance
1411          when a page fault occurs as a result of a userspace memory access or
1412          when the driver needs to start a DMA transfer involving the memory).
1413        </para>
1414        <para>
1415          Anonymous pageable memory allocation is not always desired, for instance
1416          when the hardware requires physically contiguous system memory as is
1417          often the case in embedded devices. Drivers can create GEM objects with
1418          no shmfs backing (called private GEM objects) by initializing them with
1419          a call to <function>drm_gem_private_object_init</function> instead of
1420          <function>drm_gem_object_init</function>. Storage for private GEM
1421          objects must be managed by drivers.
1422        </para>
1423        <para>
1424          Drivers that do not need to extend GEM objects with private information
1425          can call the <function>drm_gem_object_alloc</function> function to
1426          allocate and initialize a struct <structname>drm_gem_object</structname>
1427          instance. The GEM core will call the optional driver
1428          <methodname>gem_init_object</methodname> operation after initializing
1429          the GEM object with <function>drm_gem_object_init</function>.
1430          <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis>
1431        </para>
1432        <para>
1433          No alloc-and-init function exists for private GEM objects.
1434        </para>
1435      </sect3>
1436      <sect3>
1437        <title>GEM Objects Lifetime</title>
1438        <para>
1439          All GEM objects are reference-counted by the GEM core. References can be
1440          acquired and release by <function>calling drm_gem_object_reference</function>
1441          and <function>drm_gem_object_unreference</function> respectively. The
1442          caller must hold the <structname>drm_device</structname>
1443          <structfield>struct_mutex</structfield> lock. As a convenience, GEM
1444          provides the <function>drm_gem_object_reference_unlocked</function> and
1445          <function>drm_gem_object_unreference_unlocked</function> functions that
1446          can be called without holding the lock.
1447        </para>
1448        <para>
1449          When the last reference to a GEM object is released the GEM core calls
1450          the <structname>drm_driver</structname>
1451          <methodname>gem_free_object</methodname> operation. That operation is
1452          mandatory for GEM-enabled drivers and must free the GEM object and all
1453          associated resources.
1454        </para>
1455        <para>
1456          <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis>
1457          Drivers are responsible for freeing all GEM object resources, including
1458          the resources created by the GEM core. If an mmap offset has been
1459          created for the object (in which case
1460          <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield>
1461          is not NULL) it must be freed by a call to
1462          <function>drm_gem_free_mmap_offset</function>. The shmfs backing store
1463          must be released by calling <function>drm_gem_object_release</function>
1464          (that function can safely be called if no shmfs backing store has been
1465          created).
1466        </para>
1467      </sect3>
1468      <sect3>
1469        <title>GEM Objects Naming</title>
1470        <para>
1471          Communication between userspace and the kernel refers to GEM objects
1472          using local handles, global names or, more recently, file descriptors.
1473          All of those are 32-bit integer values; the usual Linux kernel limits
1474          apply to the file descriptors.
1475        </para>
1476        <para>
1477          GEM handles are local to a DRM file. Applications get a handle to a GEM
1478          object through a driver-specific ioctl, and can use that handle to refer
1479          to the GEM object in other standard or driver-specific ioctls. Closing a
1480          DRM file handle frees all its GEM handles and dereferences the
1481          associated GEM objects.
1482        </para>
1483        <para>
1484          To create a handle for a GEM object drivers call
1485          <function>drm_gem_handle_create</function>. The function takes a pointer
1486          to the DRM file and the GEM object and returns a locally unique handle.
1487          When the handle is no longer needed drivers delete it with a call to
1488          <function>drm_gem_handle_delete</function>. Finally the GEM object
1489          associated with a handle can be retrieved by a call to
1490          <function>drm_gem_object_lookup</function>.
1491        </para>
1492        <para>
1493          Handles don't take ownership of GEM objects, they only take a reference
1494          to the object that will be dropped when the handle is destroyed. To
1495          avoid leaking GEM objects, drivers must make sure they drop the
1496          reference(s) they own (such as the initial reference taken at object
1497          creation time) as appropriate, without any special consideration for the
1498          handle. For example, in the particular case of combined GEM object and
1499          handle creation in the implementation of the
1500          <methodname>dumb_create</methodname> operation, drivers must drop the
1501          initial reference to the GEM object before returning the handle.
1502        </para>
1503        <para>
1504          GEM names are similar in purpose to handles but are not local to DRM
1505          files. They can be passed between processes to reference a GEM object
1506          globally. Names can't be used directly to refer to objects in the DRM
1507          API, applications must convert handles to names and names to handles
1508          using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls
1509          respectively. The conversion is handled by the DRM core without any
1510          driver-specific support.
1511        </para>
1512        <para>
1513          GEM also supports buffer sharing with dma-buf file descriptors through
1514          PRIME. GEM-based drivers must use the provided helpers functions to
1515          implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />.
1516          Since sharing file descriptors is inherently more secure than the
1517          easily guessable and global GEM names it is the preferred buffer
1518          sharing mechanism. Sharing buffers through GEM names is only supported
1519          for legacy userspace. Furthermore PRIME also allows cross-device
1520          buffer sharing since it is based on dma-bufs.
1521        </para>
1522      </sect3>
1523      <sect3 id="drm-gem-objects-mapping">
1524        <title>GEM Objects Mapping</title>
1525        <para>
1526          Because mapping operations are fairly heavyweight GEM favours
1527          read/write-like access to buffers, implemented through driver-specific
1528          ioctls, over mapping buffers to userspace. However, when random access
1529          to the buffer is needed (to perform software rendering for instance),
1530          direct access to the object can be more efficient.
1531        </para>
1532        <para>
1533          The mmap system call can't be used directly to map GEM objects, as they
1534          don't have their own file handle. Two alternative methods currently
1535          co-exist to map GEM objects to userspace. The first method uses a
1536          driver-specific ioctl to perform the mapping operation, calling
1537          <function>do_mmap</function> under the hood. This is often considered
1538          dubious, seems to be discouraged for new GEM-enabled drivers, and will
1539          thus not be described here.
1540        </para>
1541        <para>
1542          The second method uses the mmap system call on the DRM file handle.
1543          <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd,
1544             off_t offset);</synopsis>
1545          DRM identifies the GEM object to be mapped by a fake offset passed
1546          through the mmap offset argument. Prior to being mapped, a GEM object
1547          must thus be associated with a fake offset. To do so, drivers must call
1548          <function>drm_gem_create_mmap_offset</function> on the object. The
1549          function allocates a fake offset range from a pool and stores the
1550          offset divided by PAGE_SIZE in
1551          <literal>obj-&gt;map_list.hash.key</literal>. Care must be taken not to
1552          call <function>drm_gem_create_mmap_offset</function> if a fake offset
1553          has already been allocated for the object. This can be tested by
1554          <literal>obj-&gt;map_list.map</literal> being non-NULL.
1555        </para>
1556        <para>
1557          Once allocated, the fake offset value
1558          (<literal>obj-&gt;map_list.hash.key &lt;&lt; PAGE_SHIFT</literal>)
1559          must be passed to the application in a driver-specific way and can then
1560          be used as the mmap offset argument.
1561        </para>
1562        <para>
1563          The GEM core provides a helper method <function>drm_gem_mmap</function>
1564          to handle object mapping. The method can be set directly as the mmap
1565          file operation handler. It will look up the GEM object based on the
1566          offset value and set the VMA operations to the
1567          <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
1568          field. Note that <function>drm_gem_mmap</function> doesn't map memory to
1569          userspace, but relies on the driver-provided fault handler to map pages
1570          individually.
1571        </para>
1572        <para>
1573          To use <function>drm_gem_mmap</function>, drivers must fill the struct
1574          <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
1575          field with a pointer to VM operations.
1576        </para>
1577        <para>
1578          <synopsis>struct vm_operations_struct *gem_vm_ops
1579
1580  struct vm_operations_struct {
1581          void (*open)(struct vm_area_struct * area);
1582          void (*close)(struct vm_area_struct * area);
1583          int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf);
1584  };</synopsis>
1585        </para>
1586        <para>
1587          The <methodname>open</methodname> and <methodname>close</methodname>
1588          operations must update the GEM object reference count. Drivers can use
1589          the <function>drm_gem_vm_open</function> and
1590          <function>drm_gem_vm_close</function> helper functions directly as open
1591          and close handlers.
1592        </para>
1593        <para>
1594          The fault operation handler is responsible for mapping individual pages
1595          to userspace when a page fault occurs. Depending on the memory
1596          allocation scheme, drivers can allocate pages at fault time, or can
1597          decide to allocate memory for the GEM object at the time the object is
1598          created.
1599        </para>
1600        <para>
1601          Drivers that want to map the GEM object upfront instead of handling page
1602          faults can implement their own mmap file operation handler.
1603        </para>
1604      </sect3>
1605      <sect3>
1606        <title>Memory Coherency</title>
1607        <para>
1608          When mapped to the device or used in a command buffer, backing pages
1609          for an object are flushed to memory and marked write combined so as to
1610          be coherent with the GPU. Likewise, if the CPU accesses an object
1611          after the GPU has finished rendering to the object, then the object
1612          must be made coherent with the CPU's view of memory, usually involving
1613          GPU cache flushing of various kinds. This core CPU&lt;-&gt;GPU
1614          coherency management is provided by a device-specific ioctl, which
1615          evaluates an object's current domain and performs any necessary
1616          flushing or synchronization to put the object into the desired
1617          coherency domain (note that the object may be busy, i.e. an active
1618          render target; in that case, setting the domain blocks the client and
1619          waits for rendering to complete before performing any necessary
1620          flushing operations).
1621        </para>
1622      </sect3>
1623      <sect3>
1624        <title>Command Execution</title>
1625        <para>
1626          Perhaps the most important GEM function for GPU devices is providing a
1627          command execution interface to clients. Client programs construct
1628          command buffers containing references to previously allocated memory
1629          objects, and then submit them to GEM. At that point, GEM takes care to
1630          bind all the objects into the GTT, execute the buffer, and provide
1631          necessary synchronization between clients accessing the same buffers.
1632          This often involves evicting some objects from the GTT and re-binding
1633          others (a fairly expensive operation), and providing relocation
1634          support which hides fixed GTT offsets from clients. Clients must take
1635          care not to submit command buffers that reference more objects than
1636          can fit in the GTT; otherwise, GEM will reject them and no rendering
1637          will occur. Similarly, if several objects in the buffer require fence
1638          registers to be allocated for correct rendering (e.g. 2D blits on
1639          pre-965 chips), care must be taken not to require more fence registers
1640          than are available to the client. Such resource management should be
1641          abstracted from the client in libdrm.
1642        </para>
1643      </sect3>
1644      <sect3>
1645        <title>GEM Function Reference</title>
1646<!-- drivers/gpu/drm/drm_gem.c -->
1647<refentry id="API-drm-gem-object-init">
1648<refentryinfo>
1649 <title>LINUX</title>
1650 <productname>Kernel Hackers Manual</productname>
1651 <date>July 2017</date>
1652</refentryinfo>
1653<refmeta>
1654 <refentrytitle><phrase>drm_gem_object_init</phrase></refentrytitle>
1655 <manvolnum>9</manvolnum>
1656 <refmiscinfo class="version">4.1.27</refmiscinfo>
1657</refmeta>
1658<refnamediv>
1659 <refname>drm_gem_object_init</refname>
1660 <refpurpose>
1661  initialize an allocated shmem-backed GEM object
1662 </refpurpose>
1663</refnamediv>
1664<refsynopsisdiv>
1665 <title>Synopsis</title>
1666  <funcsynopsis><funcprototype>
1667   <funcdef>int <function>drm_gem_object_init </function></funcdef>
1668   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
1669   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
1670   <paramdef>size_t <parameter>size</parameter></paramdef>
1671  </funcprototype></funcsynopsis>
1672</refsynopsisdiv>
1673<refsect1>
1674 <title>Arguments</title>
1675 <variablelist>
1676  <varlistentry>
1677   <term><parameter>dev</parameter></term>
1678   <listitem>
1679    <para>
1680     drm_device the object should be initialized for
1681    </para>
1682   </listitem>
1683  </varlistentry>
1684  <varlistentry>
1685   <term><parameter>obj</parameter></term>
1686   <listitem>
1687    <para>
1688     drm_gem_object to initialize
1689    </para>
1690   </listitem>
1691  </varlistentry>
1692  <varlistentry>
1693   <term><parameter>size</parameter></term>
1694   <listitem>
1695    <para>
1696     object size
1697    </para>
1698   </listitem>
1699  </varlistentry>
1700 </variablelist>
1701</refsect1>
1702<refsect1>
1703<title>Description</title>
1704<para>
1705   Initialize an already allocated GEM object of the specified size with
1706   shmfs backing store.
1707</para>
1708</refsect1>
1709</refentry>
1710
1711<refentry id="API-drm-gem-private-object-init">
1712<refentryinfo>
1713 <title>LINUX</title>
1714 <productname>Kernel Hackers Manual</productname>
1715 <date>July 2017</date>
1716</refentryinfo>
1717<refmeta>
1718 <refentrytitle><phrase>drm_gem_private_object_init</phrase></refentrytitle>
1719 <manvolnum>9</manvolnum>
1720 <refmiscinfo class="version">4.1.27</refmiscinfo>
1721</refmeta>
1722<refnamediv>
1723 <refname>drm_gem_private_object_init</refname>
1724 <refpurpose>
1725     initialize an allocated private GEM object
1726 </refpurpose>
1727</refnamediv>
1728<refsynopsisdiv>
1729 <title>Synopsis</title>
1730  <funcsynopsis><funcprototype>
1731   <funcdef>void <function>drm_gem_private_object_init </function></funcdef>
1732   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
1733   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
1734   <paramdef>size_t <parameter>size</parameter></paramdef>
1735  </funcprototype></funcsynopsis>
1736</refsynopsisdiv>
1737<refsect1>
1738 <title>Arguments</title>
1739 <variablelist>
1740  <varlistentry>
1741   <term><parameter>dev</parameter></term>
1742   <listitem>
1743    <para>
1744     drm_device the object should be initialized for
1745    </para>
1746   </listitem>
1747  </varlistentry>
1748  <varlistentry>
1749   <term><parameter>obj</parameter></term>
1750   <listitem>
1751    <para>
1752     drm_gem_object to initialize
1753    </para>
1754   </listitem>
1755  </varlistentry>
1756  <varlistentry>
1757   <term><parameter>size</parameter></term>
1758   <listitem>
1759    <para>
1760     object size
1761    </para>
1762   </listitem>
1763  </varlistentry>
1764 </variablelist>
1765</refsect1>
1766<refsect1>
1767<title>Description</title>
1768<para>
1769   Initialize an already allocated GEM object of the specified size with
1770   no GEM provided backing store. Instead the caller is responsible for
1771   backing the object and handling it.
1772</para>
1773</refsect1>
1774</refentry>
1775
1776<refentry id="API-drm-gem-handle-delete">
1777<refentryinfo>
1778 <title>LINUX</title>
1779 <productname>Kernel Hackers Manual</productname>
1780 <date>July 2017</date>
1781</refentryinfo>
1782<refmeta>
1783 <refentrytitle><phrase>drm_gem_handle_delete</phrase></refentrytitle>
1784 <manvolnum>9</manvolnum>
1785 <refmiscinfo class="version">4.1.27</refmiscinfo>
1786</refmeta>
1787<refnamediv>
1788 <refname>drm_gem_handle_delete</refname>
1789 <refpurpose>
1790     deletes the given file-private handle
1791 </refpurpose>
1792</refnamediv>
1793<refsynopsisdiv>
1794 <title>Synopsis</title>
1795  <funcsynopsis><funcprototype>
1796   <funcdef>int <function>drm_gem_handle_delete </function></funcdef>
1797   <paramdef>struct drm_file * <parameter>filp</parameter></paramdef>
1798   <paramdef>u32 <parameter>handle</parameter></paramdef>
1799  </funcprototype></funcsynopsis>
1800</refsynopsisdiv>
1801<refsect1>
1802 <title>Arguments</title>
1803 <variablelist>
1804  <varlistentry>
1805   <term><parameter>filp</parameter></term>
1806   <listitem>
1807    <para>
1808     drm file-private structure to use for the handle look up
1809    </para>
1810   </listitem>
1811  </varlistentry>
1812  <varlistentry>
1813   <term><parameter>handle</parameter></term>
1814   <listitem>
1815    <para>
1816     userspace handle to delete
1817    </para>
1818   </listitem>
1819  </varlistentry>
1820 </variablelist>
1821</refsect1>
1822<refsect1>
1823<title>Description</title>
1824<para>
1825   Removes the GEM handle from the <parameter>filp</parameter> lookup table and if this is the last
1826   handle also cleans up linked resources like GEM names.
1827</para>
1828</refsect1>
1829</refentry>
1830
1831<refentry id="API-drm-gem-dumb-destroy">
1832<refentryinfo>
1833 <title>LINUX</title>
1834 <productname>Kernel Hackers Manual</productname>
1835 <date>July 2017</date>
1836</refentryinfo>
1837<refmeta>
1838 <refentrytitle><phrase>drm_gem_dumb_destroy</phrase></refentrytitle>
1839 <manvolnum>9</manvolnum>
1840 <refmiscinfo class="version">4.1.27</refmiscinfo>
1841</refmeta>
1842<refnamediv>
1843 <refname>drm_gem_dumb_destroy</refname>
1844 <refpurpose>
1845     dumb fb callback helper for gem based drivers
1846 </refpurpose>
1847</refnamediv>
1848<refsynopsisdiv>
1849 <title>Synopsis</title>
1850  <funcsynopsis><funcprototype>
1851   <funcdef>int <function>drm_gem_dumb_destroy </function></funcdef>
1852   <paramdef>struct drm_file * <parameter>file</parameter></paramdef>
1853   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
1854   <paramdef>uint32_t <parameter>handle</parameter></paramdef>
1855  </funcprototype></funcsynopsis>
1856</refsynopsisdiv>
1857<refsect1>
1858 <title>Arguments</title>
1859 <variablelist>
1860  <varlistentry>
1861   <term><parameter>file</parameter></term>
1862   <listitem>
1863    <para>
1864     drm file-private structure to remove the dumb handle from
1865    </para>
1866   </listitem>
1867  </varlistentry>
1868  <varlistentry>
1869   <term><parameter>dev</parameter></term>
1870   <listitem>
1871    <para>
1872     corresponding drm_device
1873    </para>
1874   </listitem>
1875  </varlistentry>
1876  <varlistentry>
1877   <term><parameter>handle</parameter></term>
1878   <listitem>
1879    <para>
1880     the dumb handle to remove
1881    </para>
1882   </listitem>
1883  </varlistentry>
1884 </variablelist>
1885</refsect1>
1886<refsect1>
1887<title>Description</title>
1888<para>
1889   This implements the -&gt;dumb_destroy kms driver callback for drivers which use
1890   gem to manage their backing storage.
1891</para>
1892</refsect1>
1893</refentry>
1894
1895<refentry id="API-drm-gem-handle-create">
1896<refentryinfo>
1897 <title>LINUX</title>
1898 <productname>Kernel Hackers Manual</productname>
1899 <date>July 2017</date>
1900</refentryinfo>
1901<refmeta>
1902 <refentrytitle><phrase>drm_gem_handle_create</phrase></refentrytitle>
1903 <manvolnum>9</manvolnum>
1904 <refmiscinfo class="version">4.1.27</refmiscinfo>
1905</refmeta>
1906<refnamediv>
1907 <refname>drm_gem_handle_create</refname>
1908 <refpurpose>
1909     create a gem handle for an object
1910 </refpurpose>
1911</refnamediv>
1912<refsynopsisdiv>
1913 <title>Synopsis</title>
1914  <funcsynopsis><funcprototype>
1915   <funcdef>int <function>drm_gem_handle_create </function></funcdef>
1916   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
1917   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
1918   <paramdef>u32 * <parameter>handlep</parameter></paramdef>
1919  </funcprototype></funcsynopsis>
1920</refsynopsisdiv>
1921<refsect1>
1922 <title>Arguments</title>
1923 <variablelist>
1924  <varlistentry>
1925   <term><parameter>file_priv</parameter></term>
1926   <listitem>
1927    <para>
1928     drm file-private structure to register the handle for
1929    </para>
1930   </listitem>
1931  </varlistentry>
1932  <varlistentry>
1933   <term><parameter>obj</parameter></term>
1934   <listitem>
1935    <para>
1936     object to register
1937    </para>
1938   </listitem>
1939  </varlistentry>
1940  <varlistentry>
1941   <term><parameter>handlep</parameter></term>
1942   <listitem>
1943    <para>
1944     pionter to return the created handle to the caller
1945    </para>
1946   </listitem>
1947  </varlistentry>
1948 </variablelist>
1949</refsect1>
1950<refsect1>
1951<title>Description</title>
1952<para>
1953   Create a handle for this object. This adds a handle reference
1954   to the object, which includes a regular reference count. Callers
1955   will likely want to dereference the object afterwards.
1956</para>
1957</refsect1>
1958</refentry>
1959
1960<refentry id="API-drm-gem-free-mmap-offset">
1961<refentryinfo>
1962 <title>LINUX</title>
1963 <productname>Kernel Hackers Manual</productname>
1964 <date>July 2017</date>
1965</refentryinfo>
1966<refmeta>
1967 <refentrytitle><phrase>drm_gem_free_mmap_offset</phrase></refentrytitle>
1968 <manvolnum>9</manvolnum>
1969 <refmiscinfo class="version">4.1.27</refmiscinfo>
1970</refmeta>
1971<refnamediv>
1972 <refname>drm_gem_free_mmap_offset</refname>
1973 <refpurpose>
1974     release a fake mmap offset for an object
1975 </refpurpose>
1976</refnamediv>
1977<refsynopsisdiv>
1978 <title>Synopsis</title>
1979  <funcsynopsis><funcprototype>
1980   <funcdef>void <function>drm_gem_free_mmap_offset </function></funcdef>
1981   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
1982  </funcprototype></funcsynopsis>
1983</refsynopsisdiv>
1984<refsect1>
1985 <title>Arguments</title>
1986 <variablelist>
1987  <varlistentry>
1988   <term><parameter>obj</parameter></term>
1989   <listitem>
1990    <para>
1991     obj in question
1992    </para>
1993   </listitem>
1994  </varlistentry>
1995 </variablelist>
1996</refsect1>
1997<refsect1>
1998<title>Description</title>
1999<para>
2000   This routine frees fake offsets allocated by <function>drm_gem_create_mmap_offset</function>.
2001</para>
2002</refsect1>
2003</refentry>
2004
2005<refentry id="API-drm-gem-create-mmap-offset-size">
2006<refentryinfo>
2007 <title>LINUX</title>
2008 <productname>Kernel Hackers Manual</productname>
2009 <date>July 2017</date>
2010</refentryinfo>
2011<refmeta>
2012 <refentrytitle><phrase>drm_gem_create_mmap_offset_size</phrase></refentrytitle>
2013 <manvolnum>9</manvolnum>
2014 <refmiscinfo class="version">4.1.27</refmiscinfo>
2015</refmeta>
2016<refnamediv>
2017 <refname>drm_gem_create_mmap_offset_size</refname>
2018 <refpurpose>
2019     create a fake mmap offset for an object
2020 </refpurpose>
2021</refnamediv>
2022<refsynopsisdiv>
2023 <title>Synopsis</title>
2024  <funcsynopsis><funcprototype>
2025   <funcdef>int <function>drm_gem_create_mmap_offset_size </function></funcdef>
2026   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
2027   <paramdef>size_t <parameter>size</parameter></paramdef>
2028  </funcprototype></funcsynopsis>
2029</refsynopsisdiv>
2030<refsect1>
2031 <title>Arguments</title>
2032 <variablelist>
2033  <varlistentry>
2034   <term><parameter>obj</parameter></term>
2035   <listitem>
2036    <para>
2037     obj in question
2038    </para>
2039   </listitem>
2040  </varlistentry>
2041  <varlistentry>
2042   <term><parameter>size</parameter></term>
2043   <listitem>
2044    <para>
2045     the virtual size
2046    </para>
2047   </listitem>
2048  </varlistentry>
2049 </variablelist>
2050</refsect1>
2051<refsect1>
2052<title>Description</title>
2053<para>
2054   GEM memory mapping works by handing back to userspace a fake mmap offset
2055   it can use in a subsequent mmap(2) call.  The DRM core code then looks
2056   up the object based on the offset and sets up the various memory mapping
2057   structures.
2058   </para><para>
2059
2060   This routine allocates and attaches a fake offset for <parameter>obj</parameter>, in cases where
2061   the virtual size differs from the physical size (ie. obj-&gt;size).  Otherwise
2062   just use <function>drm_gem_create_mmap_offset</function>.
2063</para>
2064</refsect1>
2065</refentry>
2066
2067<refentry id="API-drm-gem-create-mmap-offset">
2068<refentryinfo>
2069 <title>LINUX</title>
2070 <productname>Kernel Hackers Manual</productname>
2071 <date>July 2017</date>
2072</refentryinfo>
2073<refmeta>
2074 <refentrytitle><phrase>drm_gem_create_mmap_offset</phrase></refentrytitle>
2075 <manvolnum>9</manvolnum>
2076 <refmiscinfo class="version">4.1.27</refmiscinfo>
2077</refmeta>
2078<refnamediv>
2079 <refname>drm_gem_create_mmap_offset</refname>
2080 <refpurpose>
2081     create a fake mmap offset for an object
2082 </refpurpose>
2083</refnamediv>
2084<refsynopsisdiv>
2085 <title>Synopsis</title>
2086  <funcsynopsis><funcprototype>
2087   <funcdef>int <function>drm_gem_create_mmap_offset </function></funcdef>
2088   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
2089  </funcprototype></funcsynopsis>
2090</refsynopsisdiv>
2091<refsect1>
2092 <title>Arguments</title>
2093 <variablelist>
2094  <varlistentry>
2095   <term><parameter>obj</parameter></term>
2096   <listitem>
2097    <para>
2098     obj in question
2099    </para>
2100   </listitem>
2101  </varlistentry>
2102 </variablelist>
2103</refsect1>
2104<refsect1>
2105<title>Description</title>
2106<para>
2107   GEM memory mapping works by handing back to userspace a fake mmap offset
2108   it can use in a subsequent mmap(2) call.  The DRM core code then looks
2109   up the object based on the offset and sets up the various memory mapping
2110   structures.
2111   </para><para>
2112
2113   This routine allocates and attaches a fake offset for <parameter>obj</parameter>.
2114</para>
2115</refsect1>
2116</refentry>
2117
2118<refentry id="API-drm-gem-get-pages">
2119<refentryinfo>
2120 <title>LINUX</title>
2121 <productname>Kernel Hackers Manual</productname>
2122 <date>July 2017</date>
2123</refentryinfo>
2124<refmeta>
2125 <refentrytitle><phrase>drm_gem_get_pages</phrase></refentrytitle>
2126 <manvolnum>9</manvolnum>
2127 <refmiscinfo class="version">4.1.27</refmiscinfo>
2128</refmeta>
2129<refnamediv>
2130 <refname>drm_gem_get_pages</refname>
2131 <refpurpose>
2132     helper to allocate backing pages for a GEM object from shmem
2133 </refpurpose>
2134</refnamediv>
2135<refsynopsisdiv>
2136 <title>Synopsis</title>
2137  <funcsynopsis><funcprototype>
2138   <funcdef>struct page ** <function>drm_gem_get_pages </function></funcdef>
2139   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
2140  </funcprototype></funcsynopsis>
2141</refsynopsisdiv>
2142<refsect1>
2143 <title>Arguments</title>
2144 <variablelist>
2145  <varlistentry>
2146   <term><parameter>obj</parameter></term>
2147   <listitem>
2148    <para>
2149     obj in question
2150    </para>
2151   </listitem>
2152  </varlistentry>
2153 </variablelist>
2154</refsect1>
2155<refsect1>
2156<title>Description</title>
2157<para>
2158   This reads the page-array of the shmem-backing storage of the given gem
2159   object. An array of pages is returned. If a page is not allocated or
2160   swapped-out, this will allocate/swap-in the required pages. Note that the
2161   whole object is covered by the page-array and pinned in memory.
2162   </para><para>
2163
2164   Use <function>drm_gem_put_pages</function> to release the array and unpin all pages.
2165   </para><para>
2166
2167   This uses the GFP-mask set on the shmem-mapping (see <function>mapping_set_gfp_mask</function>).
2168   If you require other GFP-masks, you have to do those allocations yourself.
2169   </para><para>
2170
2171   Note that you are not allowed to change gfp-zones during runtime. That is,
2172   <function>shmem_read_mapping_page_gfp</function> must be called with the same gfp_zone(gfp) as
2173   set during initialization. If you have special zone constraints, set them
2174   after <function>drm_gem_init_object</function> via <function>mapping_set_gfp_mask</function>. shmem-core takes care
2175   to keep pages in the required zone during swap-in.
2176</para>
2177</refsect1>
2178</refentry>
2179
2180<refentry id="API-drm-gem-put-pages">
2181<refentryinfo>
2182 <title>LINUX</title>
2183 <productname>Kernel Hackers Manual</productname>
2184 <date>July 2017</date>
2185</refentryinfo>
2186<refmeta>
2187 <refentrytitle><phrase>drm_gem_put_pages</phrase></refentrytitle>
2188 <manvolnum>9</manvolnum>
2189 <refmiscinfo class="version">4.1.27</refmiscinfo>
2190</refmeta>
2191<refnamediv>
2192 <refname>drm_gem_put_pages</refname>
2193 <refpurpose>
2194     helper to free backing pages for a GEM object
2195 </refpurpose>
2196</refnamediv>
2197<refsynopsisdiv>
2198 <title>Synopsis</title>
2199  <funcsynopsis><funcprototype>
2200   <funcdef>void <function>drm_gem_put_pages </function></funcdef>
2201   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
2202   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
2203   <paramdef>bool <parameter>dirty</parameter></paramdef>
2204   <paramdef>bool <parameter>accessed</parameter></paramdef>
2205  </funcprototype></funcsynopsis>
2206</refsynopsisdiv>
2207<refsect1>
2208 <title>Arguments</title>
2209 <variablelist>
2210  <varlistentry>
2211   <term><parameter>obj</parameter></term>
2212   <listitem>
2213    <para>
2214     obj in question
2215    </para>
2216   </listitem>
2217  </varlistentry>
2218  <varlistentry>
2219   <term><parameter>pages</parameter></term>
2220   <listitem>
2221    <para>
2222     pages to free
2223    </para>
2224   </listitem>
2225  </varlistentry>
2226  <varlistentry>
2227   <term><parameter>dirty</parameter></term>
2228   <listitem>
2229    <para>
2230     if true, pages will be marked as dirty
2231    </para>
2232   </listitem>
2233  </varlistentry>
2234  <varlistentry>
2235   <term><parameter>accessed</parameter></term>
2236   <listitem>
2237    <para>
2238     if true, the pages will be marked as accessed
2239    </para>
2240   </listitem>
2241  </varlistentry>
2242 </variablelist>
2243</refsect1>
2244</refentry>
2245
2246<refentry id="API-drm-gem-object-free">
2247<refentryinfo>
2248 <title>LINUX</title>
2249 <productname>Kernel Hackers Manual</productname>
2250 <date>July 2017</date>
2251</refentryinfo>
2252<refmeta>
2253 <refentrytitle><phrase>drm_gem_object_free</phrase></refentrytitle>
2254 <manvolnum>9</manvolnum>
2255 <refmiscinfo class="version">4.1.27</refmiscinfo>
2256</refmeta>
2257<refnamediv>
2258 <refname>drm_gem_object_free</refname>
2259 <refpurpose>
2260     free a GEM object
2261 </refpurpose>
2262</refnamediv>
2263<refsynopsisdiv>
2264 <title>Synopsis</title>
2265  <funcsynopsis><funcprototype>
2266   <funcdef>void <function>drm_gem_object_free </function></funcdef>
2267   <paramdef>struct kref * <parameter>kref</parameter></paramdef>
2268  </funcprototype></funcsynopsis>
2269</refsynopsisdiv>
2270<refsect1>
2271 <title>Arguments</title>
2272 <variablelist>
2273  <varlistentry>
2274   <term><parameter>kref</parameter></term>
2275   <listitem>
2276    <para>
2277     kref of the object to free
2278    </para>
2279   </listitem>
2280  </varlistentry>
2281 </variablelist>
2282</refsect1>
2283<refsect1>
2284<title>Description</title>
2285<para>
2286   Called after the last reference to the object has been lost.
2287   Must be called holding struct_ mutex
2288   </para><para>
2289
2290   Frees the object
2291</para>
2292</refsect1>
2293</refentry>
2294
2295<refentry id="API-drm-gem-mmap-obj">
2296<refentryinfo>
2297 <title>LINUX</title>
2298 <productname>Kernel Hackers Manual</productname>
2299 <date>July 2017</date>
2300</refentryinfo>
2301<refmeta>
2302 <refentrytitle><phrase>drm_gem_mmap_obj</phrase></refentrytitle>
2303 <manvolnum>9</manvolnum>
2304 <refmiscinfo class="version">4.1.27</refmiscinfo>
2305</refmeta>
2306<refnamediv>
2307 <refname>drm_gem_mmap_obj</refname>
2308 <refpurpose>
2309     memory map a GEM object
2310 </refpurpose>
2311</refnamediv>
2312<refsynopsisdiv>
2313 <title>Synopsis</title>
2314  <funcsynopsis><funcprototype>
2315   <funcdef>int <function>drm_gem_mmap_obj </function></funcdef>
2316   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
2317   <paramdef>unsigned long <parameter>obj_size</parameter></paramdef>
2318   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
2319  </funcprototype></funcsynopsis>
2320</refsynopsisdiv>
2321<refsect1>
2322 <title>Arguments</title>
2323 <variablelist>
2324  <varlistentry>
2325   <term><parameter>obj</parameter></term>
2326   <listitem>
2327    <para>
2328     the GEM object to map
2329    </para>
2330   </listitem>
2331  </varlistentry>
2332  <varlistentry>
2333   <term><parameter>obj_size</parameter></term>
2334   <listitem>
2335    <para>
2336     the object size to be mapped, in bytes
2337    </para>
2338   </listitem>
2339  </varlistentry>
2340  <varlistentry>
2341   <term><parameter>vma</parameter></term>
2342   <listitem>
2343    <para>
2344     VMA for the area to be mapped
2345    </para>
2346   </listitem>
2347  </varlistentry>
2348 </variablelist>
2349</refsect1>
2350<refsect1>
2351<title>Description</title>
2352<para>
2353   Set up the VMA to prepare mapping of the GEM object using the gem_vm_ops
2354   provided by the driver. Depending on their requirements, drivers can either
2355   provide a fault handler in their gem_vm_ops (in which case any accesses to
2356   the object will be trapped, to perform migration, GTT binding, surface
2357   register allocation, or performance monitoring), or mmap the buffer memory
2358   synchronously after calling drm_gem_mmap_obj.
2359   </para><para>
2360
2361   This function is mainly intended to implement the DMABUF mmap operation, when
2362   the GEM object is not looked up based on its fake offset. To implement the
2363   DRM mmap operation, drivers should use the <function>drm_gem_mmap</function> function.
2364   </para><para>
2365
2366   <function>drm_gem_mmap_obj</function> assumes the user is granted access to the buffer while
2367   <function>drm_gem_mmap</function> prevents unprivileged users from mapping random objects. So
2368   callers must verify access restrictions before calling this helper.
2369</para>
2370</refsect1>
2371<refsect1>
2372<title>NOTE</title>
2373<para>
2374   This function has to be protected with dev-&gt;struct_mutex
2375   </para><para>
2376
2377   Return 0 or success or -EINVAL if the object size is smaller than the VMA
2378   size, or if no gem_vm_ops are provided.
2379</para>
2380</refsect1>
2381</refentry>
2382
2383<refentry id="API-drm-gem-mmap">
2384<refentryinfo>
2385 <title>LINUX</title>
2386 <productname>Kernel Hackers Manual</productname>
2387 <date>July 2017</date>
2388</refentryinfo>
2389<refmeta>
2390 <refentrytitle><phrase>drm_gem_mmap</phrase></refentrytitle>
2391 <manvolnum>9</manvolnum>
2392 <refmiscinfo class="version">4.1.27</refmiscinfo>
2393</refmeta>
2394<refnamediv>
2395 <refname>drm_gem_mmap</refname>
2396 <refpurpose>
2397     memory map routine for GEM objects
2398 </refpurpose>
2399</refnamediv>
2400<refsynopsisdiv>
2401 <title>Synopsis</title>
2402  <funcsynopsis><funcprototype>
2403   <funcdef>int <function>drm_gem_mmap </function></funcdef>
2404   <paramdef>struct file * <parameter>filp</parameter></paramdef>
2405   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
2406  </funcprototype></funcsynopsis>
2407</refsynopsisdiv>
2408<refsect1>
2409 <title>Arguments</title>
2410 <variablelist>
2411  <varlistentry>
2412   <term><parameter>filp</parameter></term>
2413   <listitem>
2414    <para>
2415     DRM file pointer
2416    </para>
2417   </listitem>
2418  </varlistentry>
2419  <varlistentry>
2420   <term><parameter>vma</parameter></term>
2421   <listitem>
2422    <para>
2423     VMA for the area to be mapped
2424    </para>
2425   </listitem>
2426  </varlistentry>
2427 </variablelist>
2428</refsect1>
2429<refsect1>
2430<title>Description</title>
2431<para>
2432   If a driver supports GEM object mapping, mmap calls on the DRM file
2433   descriptor will end up here.
2434   </para><para>
2435
2436   Look up the GEM object based on the offset passed in (vma-&gt;vm_pgoff will
2437   contain the fake offset we created when the GTT map ioctl was called on
2438   the object) and map it with a call to <function>drm_gem_mmap_obj</function>.
2439   </para><para>
2440
2441   If the caller is not granted access to the buffer object, the mmap will fail
2442   with EACCES. Please see the vma manager for more information.
2443</para>
2444</refsect1>
2445</refentry>
2446
2447      </sect3>
2448    </sect2>
2449    <sect2>
2450      <title>VMA Offset Manager</title>
2451<para>
2452   </para><para>
2453   The vma-manager is responsible to map arbitrary driver-dependent memory
2454   regions into the linear user address-space. It provides offsets to the
2455   caller which can then be used on the address_space of the drm-device. It
2456   takes care to not overlap regions, size them appropriately and to not
2457   confuse mm-core by inconsistent fake vm_pgoff fields.
2458   Drivers shouldn't use this for object placement in VMEM. This manager should
2459   only be used to manage mappings into linear user-space VMs.
2460   </para><para>
2461   We use drm_mm as backend to manage object allocations. But it is highly
2462   optimized for alloc/free calls, not lookups. Hence, we use an rb-tree to
2463   speed up offset lookups.
2464   </para><para>
2465   You must not use multiple offset managers on a single address_space.
2466   Otherwise, mm-core will be unable to tear down memory mappings as the VM will
2467   no longer be linear.
2468   </para><para>
2469   This offset manager works on page-based addresses. That is, every argument
2470   and return code (with the exception of <function>drm_vma_node_offset_addr</function>) is given
2471   in number of pages, not number of bytes. That means, object sizes and offsets
2472   must always be page-aligned (as usual).
2473   If you want to get a valid byte-based user-space address for a given offset,
2474   please see <function>drm_vma_node_offset_addr</function>.
2475   </para><para>
2476   Additionally to offset management, the vma offset manager also handles access
2477   management. For every open-file context that is allowed to access a given
2478   node, you must call <function>drm_vma_node_allow</function>. Otherwise, an <function>mmap</function> call on this
2479   open-file with the offset of the node will fail with -EACCES. To revoke
2480   access again, use <function>drm_vma_node_revoke</function>. However, the caller is responsible
2481   for destroying already existing mappings, if required.
2482</para>
2483
2484<!-- drivers/gpu/drm/drm_vma_manager.c -->
2485<refentry id="API-drm-vma-offset-manager-init">
2486<refentryinfo>
2487 <title>LINUX</title>
2488 <productname>Kernel Hackers Manual</productname>
2489 <date>July 2017</date>
2490</refentryinfo>
2491<refmeta>
2492 <refentrytitle><phrase>drm_vma_offset_manager_init</phrase></refentrytitle>
2493 <manvolnum>9</manvolnum>
2494 <refmiscinfo class="version">4.1.27</refmiscinfo>
2495</refmeta>
2496<refnamediv>
2497 <refname>drm_vma_offset_manager_init</refname>
2498 <refpurpose>
2499  Initialize new offset-manager
2500 </refpurpose>
2501</refnamediv>
2502<refsynopsisdiv>
2503 <title>Synopsis</title>
2504  <funcsynopsis><funcprototype>
2505   <funcdef>void <function>drm_vma_offset_manager_init </function></funcdef>
2506   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
2507   <paramdef>unsigned long <parameter>page_offset</parameter></paramdef>
2508   <paramdef>unsigned long <parameter>size</parameter></paramdef>
2509  </funcprototype></funcsynopsis>
2510</refsynopsisdiv>
2511<refsect1>
2512 <title>Arguments</title>
2513 <variablelist>
2514  <varlistentry>
2515   <term><parameter>mgr</parameter></term>
2516   <listitem>
2517    <para>
2518     Manager object
2519    </para>
2520   </listitem>
2521  </varlistentry>
2522  <varlistentry>
2523   <term><parameter>page_offset</parameter></term>
2524   <listitem>
2525    <para>
2526     Offset of available memory area (page-based)
2527    </para>
2528   </listitem>
2529  </varlistentry>
2530  <varlistentry>
2531   <term><parameter>size</parameter></term>
2532   <listitem>
2533    <para>
2534     Size of available address space range (page-based)
2535    </para>
2536   </listitem>
2537  </varlistentry>
2538 </variablelist>
2539</refsect1>
2540<refsect1>
2541<title>Description</title>
2542<para>
2543   Initialize a new offset-manager. The offset and area size available for the
2544   manager are given as <parameter>page_offset</parameter> and <parameter>size</parameter>. Both are interpreted as
2545   page-numbers, not bytes.
2546   </para><para>
2547
2548   Adding/removing nodes from the manager is locked internally and protected
2549   against concurrent access. However, node allocation and destruction is left
2550   for the caller. While calling into the vma-manager, a given node must
2551   always be guaranteed to be referenced.
2552</para>
2553</refsect1>
2554</refentry>
2555
2556<refentry id="API-drm-vma-offset-manager-destroy">
2557<refentryinfo>
2558 <title>LINUX</title>
2559 <productname>Kernel Hackers Manual</productname>
2560 <date>July 2017</date>
2561</refentryinfo>
2562<refmeta>
2563 <refentrytitle><phrase>drm_vma_offset_manager_destroy</phrase></refentrytitle>
2564 <manvolnum>9</manvolnum>
2565 <refmiscinfo class="version">4.1.27</refmiscinfo>
2566</refmeta>
2567<refnamediv>
2568 <refname>drm_vma_offset_manager_destroy</refname>
2569 <refpurpose>
2570     Destroy offset manager
2571 </refpurpose>
2572</refnamediv>
2573<refsynopsisdiv>
2574 <title>Synopsis</title>
2575  <funcsynopsis><funcprototype>
2576   <funcdef>void <function>drm_vma_offset_manager_destroy </function></funcdef>
2577   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
2578  </funcprototype></funcsynopsis>
2579</refsynopsisdiv>
2580<refsect1>
2581 <title>Arguments</title>
2582 <variablelist>
2583  <varlistentry>
2584   <term><parameter>mgr</parameter></term>
2585   <listitem>
2586    <para>
2587     Manager object
2588    </para>
2589   </listitem>
2590  </varlistentry>
2591 </variablelist>
2592</refsect1>
2593<refsect1>
2594<title>Description</title>
2595<para>
2596   Destroy an object manager which was previously created via
2597   <function>drm_vma_offset_manager_init</function>. The caller must remove all allocated nodes
2598   before destroying the manager. Otherwise, drm_mm will refuse to free the
2599   requested resources.
2600   </para><para>
2601
2602   The manager must not be accessed after this function is called.
2603</para>
2604</refsect1>
2605</refentry>
2606
2607<refentry id="API-drm-vma-offset-lookup">
2608<refentryinfo>
2609 <title>LINUX</title>
2610 <productname>Kernel Hackers Manual</productname>
2611 <date>July 2017</date>
2612</refentryinfo>
2613<refmeta>
2614 <refentrytitle><phrase>drm_vma_offset_lookup</phrase></refentrytitle>
2615 <manvolnum>9</manvolnum>
2616 <refmiscinfo class="version">4.1.27</refmiscinfo>
2617</refmeta>
2618<refnamediv>
2619 <refname>drm_vma_offset_lookup</refname>
2620 <refpurpose>
2621     Find node in offset space
2622 </refpurpose>
2623</refnamediv>
2624<refsynopsisdiv>
2625 <title>Synopsis</title>
2626  <funcsynopsis><funcprototype>
2627   <funcdef>struct drm_vma_offset_node * <function>drm_vma_offset_lookup </function></funcdef>
2628   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
2629   <paramdef>unsigned long <parameter>start</parameter></paramdef>
2630   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
2631  </funcprototype></funcsynopsis>
2632</refsynopsisdiv>
2633<refsect1>
2634 <title>Arguments</title>
2635 <variablelist>
2636  <varlistentry>
2637   <term><parameter>mgr</parameter></term>
2638   <listitem>
2639    <para>
2640     Manager object
2641    </para>
2642   </listitem>
2643  </varlistentry>
2644  <varlistentry>
2645   <term><parameter>start</parameter></term>
2646   <listitem>
2647    <para>
2648     Start address for object (page-based)
2649    </para>
2650   </listitem>
2651  </varlistentry>
2652  <varlistentry>
2653   <term><parameter>pages</parameter></term>
2654   <listitem>
2655    <para>
2656     Size of object (page-based)
2657    </para>
2658   </listitem>
2659  </varlistentry>
2660 </variablelist>
2661</refsect1>
2662<refsect1>
2663<title>Description</title>
2664<para>
2665   Find a node given a start address and object size. This returns the _best_
2666   match for the given node. That is, <parameter>start</parameter> may point somewhere into a valid
2667   region and the given node will be returned, as long as the node spans the
2668   whole requested area (given the size in number of pages as <parameter>pages</parameter>).
2669</para>
2670</refsect1>
2671<refsect1>
2672<title>RETURNS</title>
2673<para>
2674   Returns NULL if no suitable node can be found. Otherwise, the best match
2675   is returned. It's the caller's responsibility to make sure the node doesn't
2676   get destroyed before the caller can access it.
2677</para>
2678</refsect1>
2679</refentry>
2680
2681<refentry id="API-drm-vma-offset-lookup-locked">
2682<refentryinfo>
2683 <title>LINUX</title>
2684 <productname>Kernel Hackers Manual</productname>
2685 <date>July 2017</date>
2686</refentryinfo>
2687<refmeta>
2688 <refentrytitle><phrase>drm_vma_offset_lookup_locked</phrase></refentrytitle>
2689 <manvolnum>9</manvolnum>
2690 <refmiscinfo class="version">4.1.27</refmiscinfo>
2691</refmeta>
2692<refnamediv>
2693 <refname>drm_vma_offset_lookup_locked</refname>
2694 <refpurpose>
2695     Find node in offset space
2696 </refpurpose>
2697</refnamediv>
2698<refsynopsisdiv>
2699 <title>Synopsis</title>
2700  <funcsynopsis><funcprototype>
2701   <funcdef>struct drm_vma_offset_node * <function>drm_vma_offset_lookup_locked </function></funcdef>
2702   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
2703   <paramdef>unsigned long <parameter>start</parameter></paramdef>
2704   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
2705  </funcprototype></funcsynopsis>
2706</refsynopsisdiv>
2707<refsect1>
2708 <title>Arguments</title>
2709 <variablelist>
2710  <varlistentry>
2711   <term><parameter>mgr</parameter></term>
2712   <listitem>
2713    <para>
2714     Manager object
2715    </para>
2716   </listitem>
2717  </varlistentry>
2718  <varlistentry>
2719   <term><parameter>start</parameter></term>
2720   <listitem>
2721    <para>
2722     Start address for object (page-based)
2723    </para>
2724   </listitem>
2725  </varlistentry>
2726  <varlistentry>
2727   <term><parameter>pages</parameter></term>
2728   <listitem>
2729    <para>
2730     Size of object (page-based)
2731    </para>
2732   </listitem>
2733  </varlistentry>
2734 </variablelist>
2735</refsect1>
2736<refsect1>
2737<title>Description</title>
2738<para>
2739   Same as <function>drm_vma_offset_lookup</function> but requires the caller to lock offset lookup
2740   manually. See <function>drm_vma_offset_lock_lookup</function> for an example.
2741</para>
2742</refsect1>
2743<refsect1>
2744<title>RETURNS</title>
2745<para>
2746   Returns NULL if no suitable node can be found. Otherwise, the best match
2747   is returned.
2748</para>
2749</refsect1>
2750</refentry>
2751
2752<refentry id="API-drm-vma-offset-add">
2753<refentryinfo>
2754 <title>LINUX</title>
2755 <productname>Kernel Hackers Manual</productname>
2756 <date>July 2017</date>
2757</refentryinfo>
2758<refmeta>
2759 <refentrytitle><phrase>drm_vma_offset_add</phrase></refentrytitle>
2760 <manvolnum>9</manvolnum>
2761 <refmiscinfo class="version">4.1.27</refmiscinfo>
2762</refmeta>
2763<refnamediv>
2764 <refname>drm_vma_offset_add</refname>
2765 <refpurpose>
2766     Add offset node to manager
2767 </refpurpose>
2768</refnamediv>
2769<refsynopsisdiv>
2770 <title>Synopsis</title>
2771  <funcsynopsis><funcprototype>
2772   <funcdef>int <function>drm_vma_offset_add </function></funcdef>
2773   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
2774   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
2775   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
2776  </funcprototype></funcsynopsis>
2777</refsynopsisdiv>
2778<refsect1>
2779 <title>Arguments</title>
2780 <variablelist>
2781  <varlistentry>
2782   <term><parameter>mgr</parameter></term>
2783   <listitem>
2784    <para>
2785     Manager object
2786    </para>
2787   </listitem>
2788  </varlistentry>
2789  <varlistentry>
2790   <term><parameter>node</parameter></term>
2791   <listitem>
2792    <para>
2793     Node to be added
2794    </para>
2795   </listitem>
2796  </varlistentry>
2797  <varlistentry>
2798   <term><parameter>pages</parameter></term>
2799   <listitem>
2800    <para>
2801     Allocation size visible to user-space (in number of pages)
2802    </para>
2803   </listitem>
2804  </varlistentry>
2805 </variablelist>
2806</refsect1>
2807<refsect1>
2808<title>Description</title>
2809<para>
2810   Add a node to the offset-manager. If the node was already added, this does
2811   nothing and return 0. <parameter>pages</parameter> is the size of the object given in number of
2812   pages.
2813   After this call succeeds, you can access the offset of the node until it
2814   is removed again.
2815   </para><para>
2816
2817   If this call fails, it is safe to retry the operation or call
2818   <function>drm_vma_offset_remove</function>, anyway. However, no cleanup is required in that
2819   case.
2820   </para><para>
2821
2822   <parameter>pages</parameter> is not required to be the same size as the underlying memory object
2823   that you want to map. It only limits the size that user-space can map into
2824   their address space.
2825</para>
2826</refsect1>
2827<refsect1>
2828<title>RETURNS</title>
2829<para>
2830   0 on success, negative error code on failure.
2831</para>
2832</refsect1>
2833</refentry>
2834
2835<refentry id="API-drm-vma-offset-remove">
2836<refentryinfo>
2837 <title>LINUX</title>
2838 <productname>Kernel Hackers Manual</productname>
2839 <date>July 2017</date>
2840</refentryinfo>
2841<refmeta>
2842 <refentrytitle><phrase>drm_vma_offset_remove</phrase></refentrytitle>
2843 <manvolnum>9</manvolnum>
2844 <refmiscinfo class="version">4.1.27</refmiscinfo>
2845</refmeta>
2846<refnamediv>
2847 <refname>drm_vma_offset_remove</refname>
2848 <refpurpose>
2849     Remove offset node from manager
2850 </refpurpose>
2851</refnamediv>
2852<refsynopsisdiv>
2853 <title>Synopsis</title>
2854  <funcsynopsis><funcprototype>
2855   <funcdef>void <function>drm_vma_offset_remove </function></funcdef>
2856   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
2857   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
2858  </funcprototype></funcsynopsis>
2859</refsynopsisdiv>
2860<refsect1>
2861 <title>Arguments</title>
2862 <variablelist>
2863  <varlistentry>
2864   <term><parameter>mgr</parameter></term>
2865   <listitem>
2866    <para>
2867     Manager object
2868    </para>
2869   </listitem>
2870  </varlistentry>
2871  <varlistentry>
2872   <term><parameter>node</parameter></term>
2873   <listitem>
2874    <para>
2875     Node to be removed
2876    </para>
2877   </listitem>
2878  </varlistentry>
2879 </variablelist>
2880</refsect1>
2881<refsect1>
2882<title>Description</title>
2883<para>
2884   Remove a node from the offset manager. If the node wasn't added before, this
2885   does nothing. After this call returns, the offset and size will be 0 until a
2886   new offset is allocated via <function>drm_vma_offset_add</function> again. Helper functions like
2887   <function>drm_vma_node_start</function> and <function>drm_vma_node_offset_addr</function> will return 0 if no
2888   offset is allocated.
2889</para>
2890</refsect1>
2891</refentry>
2892
2893<refentry id="API-drm-vma-node-allow">
2894<refentryinfo>
2895 <title>LINUX</title>
2896 <productname>Kernel Hackers Manual</productname>
2897 <date>July 2017</date>
2898</refentryinfo>
2899<refmeta>
2900 <refentrytitle><phrase>drm_vma_node_allow</phrase></refentrytitle>
2901 <manvolnum>9</manvolnum>
2902 <refmiscinfo class="version">4.1.27</refmiscinfo>
2903</refmeta>
2904<refnamediv>
2905 <refname>drm_vma_node_allow</refname>
2906 <refpurpose>
2907     Add open-file to list of allowed users
2908 </refpurpose>
2909</refnamediv>
2910<refsynopsisdiv>
2911 <title>Synopsis</title>
2912  <funcsynopsis><funcprototype>
2913   <funcdef>int <function>drm_vma_node_allow </function></funcdef>
2914   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
2915   <paramdef>struct file * <parameter>filp</parameter></paramdef>
2916  </funcprototype></funcsynopsis>
2917</refsynopsisdiv>
2918<refsect1>
2919 <title>Arguments</title>
2920 <variablelist>
2921  <varlistentry>
2922   <term><parameter>node</parameter></term>
2923   <listitem>
2924    <para>
2925     Node to modify
2926    </para>
2927   </listitem>
2928  </varlistentry>
2929  <varlistentry>
2930   <term><parameter>filp</parameter></term>
2931   <listitem>
2932    <para>
2933     Open file to add
2934    </para>
2935   </listitem>
2936  </varlistentry>
2937 </variablelist>
2938</refsect1>
2939<refsect1>
2940<title>Description</title>
2941<para>
2942   Add <parameter>filp</parameter> to the list of allowed open-files for this node. If <parameter>filp</parameter> is
2943   already on this list, the ref-count is incremented.
2944   </para><para>
2945
2946   The list of allowed-users is preserved across <function>drm_vma_offset_add</function> and
2947   <function>drm_vma_offset_remove</function> calls. You may even call it if the node is currently
2948   not added to any offset-manager.
2949   </para><para>
2950
2951   You must remove all open-files the same number of times as you added them
2952   before destroying the node. Otherwise, you will leak memory.
2953   </para><para>
2954
2955   This is locked against concurrent access internally.
2956</para>
2957</refsect1>
2958<refsect1>
2959<title>RETURNS</title>
2960<para>
2961   0 on success, negative error code on internal failure (out-of-mem)
2962</para>
2963</refsect1>
2964</refentry>
2965
2966<refentry id="API-drm-vma-node-revoke">
2967<refentryinfo>
2968 <title>LINUX</title>
2969 <productname>Kernel Hackers Manual</productname>
2970 <date>July 2017</date>
2971</refentryinfo>
2972<refmeta>
2973 <refentrytitle><phrase>drm_vma_node_revoke</phrase></refentrytitle>
2974 <manvolnum>9</manvolnum>
2975 <refmiscinfo class="version">4.1.27</refmiscinfo>
2976</refmeta>
2977<refnamediv>
2978 <refname>drm_vma_node_revoke</refname>
2979 <refpurpose>
2980     Remove open-file from list of allowed users
2981 </refpurpose>
2982</refnamediv>
2983<refsynopsisdiv>
2984 <title>Synopsis</title>
2985  <funcsynopsis><funcprototype>
2986   <funcdef>void <function>drm_vma_node_revoke </function></funcdef>
2987   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
2988   <paramdef>struct file * <parameter>filp</parameter></paramdef>
2989  </funcprototype></funcsynopsis>
2990</refsynopsisdiv>
2991<refsect1>
2992 <title>Arguments</title>
2993 <variablelist>
2994  <varlistentry>
2995   <term><parameter>node</parameter></term>
2996   <listitem>
2997    <para>
2998     Node to modify
2999    </para>
3000   </listitem>
3001  </varlistentry>
3002  <varlistentry>
3003   <term><parameter>filp</parameter></term>
3004   <listitem>
3005    <para>
3006     Open file to remove
3007    </para>
3008   </listitem>
3009  </varlistentry>
3010 </variablelist>
3011</refsect1>
3012<refsect1>
3013<title>Description</title>
3014<para>
3015   Decrement the ref-count of <parameter>filp</parameter> in the list of allowed open-files on <parameter>node</parameter>.
3016   If the ref-count drops to zero, remove <parameter>filp</parameter> from the list. You must call
3017   this once for every <function>drm_vma_node_allow</function> on <parameter>filp</parameter>.
3018   </para><para>
3019
3020   This is locked against concurrent access internally.
3021   </para><para>
3022
3023   If <parameter>filp</parameter> is not on the list, nothing is done.
3024</para>
3025</refsect1>
3026</refentry>
3027
3028<refentry id="API-drm-vma-node-is-allowed">
3029<refentryinfo>
3030 <title>LINUX</title>
3031 <productname>Kernel Hackers Manual</productname>
3032 <date>July 2017</date>
3033</refentryinfo>
3034<refmeta>
3035 <refentrytitle><phrase>drm_vma_node_is_allowed</phrase></refentrytitle>
3036 <manvolnum>9</manvolnum>
3037 <refmiscinfo class="version">4.1.27</refmiscinfo>
3038</refmeta>
3039<refnamediv>
3040 <refname>drm_vma_node_is_allowed</refname>
3041 <refpurpose>
3042     Check whether an open-file is granted access
3043 </refpurpose>
3044</refnamediv>
3045<refsynopsisdiv>
3046 <title>Synopsis</title>
3047  <funcsynopsis><funcprototype>
3048   <funcdef>bool <function>drm_vma_node_is_allowed </function></funcdef>
3049   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3050   <paramdef>struct file * <parameter>filp</parameter></paramdef>
3051  </funcprototype></funcsynopsis>
3052</refsynopsisdiv>
3053<refsect1>
3054 <title>Arguments</title>
3055 <variablelist>
3056  <varlistentry>
3057   <term><parameter>node</parameter></term>
3058   <listitem>
3059    <para>
3060     Node to check
3061    </para>
3062   </listitem>
3063  </varlistentry>
3064  <varlistentry>
3065   <term><parameter>filp</parameter></term>
3066   <listitem>
3067    <para>
3068     Open-file to check for
3069    </para>
3070   </listitem>
3071  </varlistentry>
3072 </variablelist>
3073</refsect1>
3074<refsect1>
3075<title>Description</title>
3076<para>
3077   Search the list in <parameter>node</parameter> whether <parameter>filp</parameter> is currently on the list of allowed
3078   open-files (see <function>drm_vma_node_allow</function>).
3079   </para><para>
3080
3081   This is locked against concurrent access internally.
3082</para>
3083</refsect1>
3084<refsect1>
3085<title>RETURNS</title>
3086<para>
3087   true iff <parameter>filp</parameter> is on the list
3088</para>
3089</refsect1>
3090</refentry>
3091
3092<!-- include/drm/drm_vma_manager.h -->
3093<refentry id="API-drm-vma-offset-exact-lookup">
3094<refentryinfo>
3095 <title>LINUX</title>
3096 <productname>Kernel Hackers Manual</productname>
3097 <date>July 2017</date>
3098</refentryinfo>
3099<refmeta>
3100 <refentrytitle><phrase>drm_vma_offset_exact_lookup</phrase></refentrytitle>
3101 <manvolnum>9</manvolnum>
3102 <refmiscinfo class="version">4.1.27</refmiscinfo>
3103</refmeta>
3104<refnamediv>
3105 <refname>drm_vma_offset_exact_lookup</refname>
3106 <refpurpose>
3107  Look up node by exact address
3108 </refpurpose>
3109</refnamediv>
3110<refsynopsisdiv>
3111 <title>Synopsis</title>
3112  <funcsynopsis><funcprototype>
3113   <funcdef>struct drm_vma_offset_node * <function>drm_vma_offset_exact_lookup </function></funcdef>
3114   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
3115   <paramdef>unsigned long <parameter>start</parameter></paramdef>
3116   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
3117  </funcprototype></funcsynopsis>
3118</refsynopsisdiv>
3119<refsect1>
3120 <title>Arguments</title>
3121 <variablelist>
3122  <varlistentry>
3123   <term><parameter>mgr</parameter></term>
3124   <listitem>
3125    <para>
3126     Manager object
3127    </para>
3128   </listitem>
3129  </varlistentry>
3130  <varlistentry>
3131   <term><parameter>start</parameter></term>
3132   <listitem>
3133    <para>
3134     Start address (page-based, not byte-based)
3135    </para>
3136   </listitem>
3137  </varlistentry>
3138  <varlistentry>
3139   <term><parameter>pages</parameter></term>
3140   <listitem>
3141    <para>
3142     Size of object (page-based)
3143    </para>
3144   </listitem>
3145  </varlistentry>
3146 </variablelist>
3147</refsect1>
3148<refsect1>
3149<title>Description</title>
3150<para>
3151   Same as <function>drm_vma_offset_lookup</function> but does not allow any offset into the node.
3152   It only returns the exact object with the given start address.
3153</para>
3154</refsect1>
3155<refsect1>
3156<title>RETURNS</title>
3157<para>
3158   Node at exact start address <parameter>start</parameter>.
3159</para>
3160</refsect1>
3161</refentry>
3162
3163<refentry id="API-drm-vma-offset-lock-lookup">
3164<refentryinfo>
3165 <title>LINUX</title>
3166 <productname>Kernel Hackers Manual</productname>
3167 <date>July 2017</date>
3168</refentryinfo>
3169<refmeta>
3170 <refentrytitle><phrase>drm_vma_offset_lock_lookup</phrase></refentrytitle>
3171 <manvolnum>9</manvolnum>
3172 <refmiscinfo class="version">4.1.27</refmiscinfo>
3173</refmeta>
3174<refnamediv>
3175 <refname>drm_vma_offset_lock_lookup</refname>
3176 <refpurpose>
3177     Lock lookup for extended private use
3178 </refpurpose>
3179</refnamediv>
3180<refsynopsisdiv>
3181 <title>Synopsis</title>
3182  <funcsynopsis><funcprototype>
3183   <funcdef>void <function>drm_vma_offset_lock_lookup </function></funcdef>
3184   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
3185  </funcprototype></funcsynopsis>
3186</refsynopsisdiv>
3187<refsect1>
3188 <title>Arguments</title>
3189 <variablelist>
3190  <varlistentry>
3191   <term><parameter>mgr</parameter></term>
3192   <listitem>
3193    <para>
3194     Manager object
3195    </para>
3196   </listitem>
3197  </varlistentry>
3198 </variablelist>
3199</refsect1>
3200<refsect1>
3201<title>Description</title>
3202<para>
3203   Lock VMA manager for extended lookups. Only *<function>_locked</function> VMA function calls
3204   are allowed while holding this lock. All other contexts are blocked from VMA
3205   until the lock is released via <function>drm_vma_offset_unlock_lookup</function>.
3206   </para><para>
3207
3208   Use this if you need to take a reference to the objects returned by
3209   <function>drm_vma_offset_lookup_locked</function> before releasing this lock again.
3210   </para><para>
3211
3212   This lock must not be used for anything else than extended lookups. You must
3213   not call any other VMA helpers while holding this lock.
3214</para>
3215</refsect1>
3216<refsect1>
3217<title>Note</title>
3218<para>
3219   You're in atomic-context while holding this lock!
3220</para>
3221</refsect1>
3222<refsect1>
3223<title>Example</title>
3224<informalexample><programlisting>
3225     drm_vma_offset_lock_lookup(mgr);
3226     node = drm_vma_offset_lookup_locked(mgr);
3227     if (node)
3228         kref_get_unless_zero(container_of(node, sth, entr));
3229     drm_vma_offset_unlock_lookup(mgr);
3230</programlisting></informalexample>
3231</refsect1>
3232</refentry>
3233
3234<refentry id="API-drm-vma-offset-unlock-lookup">
3235<refentryinfo>
3236 <title>LINUX</title>
3237 <productname>Kernel Hackers Manual</productname>
3238 <date>July 2017</date>
3239</refentryinfo>
3240<refmeta>
3241 <refentrytitle><phrase>drm_vma_offset_unlock_lookup</phrase></refentrytitle>
3242 <manvolnum>9</manvolnum>
3243 <refmiscinfo class="version">4.1.27</refmiscinfo>
3244</refmeta>
3245<refnamediv>
3246 <refname>drm_vma_offset_unlock_lookup</refname>
3247 <refpurpose>
3248     Unlock lookup for extended private use
3249 </refpurpose>
3250</refnamediv>
3251<refsynopsisdiv>
3252 <title>Synopsis</title>
3253  <funcsynopsis><funcprototype>
3254   <funcdef>void <function>drm_vma_offset_unlock_lookup </function></funcdef>
3255   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
3256  </funcprototype></funcsynopsis>
3257</refsynopsisdiv>
3258<refsect1>
3259 <title>Arguments</title>
3260 <variablelist>
3261  <varlistentry>
3262   <term><parameter>mgr</parameter></term>
3263   <listitem>
3264    <para>
3265     Manager object
3266    </para>
3267   </listitem>
3268  </varlistentry>
3269 </variablelist>
3270</refsect1>
3271<refsect1>
3272<title>Description</title>
3273<para>
3274   Release lookup-lock. See <function>drm_vma_offset_lock_lookup</function> for more information.
3275</para>
3276</refsect1>
3277</refentry>
3278
3279<refentry id="API-drm-vma-node-reset">
3280<refentryinfo>
3281 <title>LINUX</title>
3282 <productname>Kernel Hackers Manual</productname>
3283 <date>July 2017</date>
3284</refentryinfo>
3285<refmeta>
3286 <refentrytitle><phrase>drm_vma_node_reset</phrase></refentrytitle>
3287 <manvolnum>9</manvolnum>
3288 <refmiscinfo class="version">4.1.27</refmiscinfo>
3289</refmeta>
3290<refnamediv>
3291 <refname>drm_vma_node_reset</refname>
3292 <refpurpose>
3293     Initialize or reset node object
3294 </refpurpose>
3295</refnamediv>
3296<refsynopsisdiv>
3297 <title>Synopsis</title>
3298  <funcsynopsis><funcprototype>
3299   <funcdef>void <function>drm_vma_node_reset </function></funcdef>
3300   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3301  </funcprototype></funcsynopsis>
3302</refsynopsisdiv>
3303<refsect1>
3304 <title>Arguments</title>
3305 <variablelist>
3306  <varlistentry>
3307   <term><parameter>node</parameter></term>
3308   <listitem>
3309    <para>
3310     Node to initialize or reset
3311    </para>
3312   </listitem>
3313  </varlistentry>
3314 </variablelist>
3315</refsect1>
3316<refsect1>
3317<title>Description</title>
3318<para>
3319   Reset a node to its initial state. This must be called before using it with
3320   any VMA offset manager.
3321   </para><para>
3322
3323   This must not be called on an already allocated node, or you will leak
3324   memory.
3325</para>
3326</refsect1>
3327</refentry>
3328
3329<refentry id="API-drm-vma-node-start">
3330<refentryinfo>
3331 <title>LINUX</title>
3332 <productname>Kernel Hackers Manual</productname>
3333 <date>July 2017</date>
3334</refentryinfo>
3335<refmeta>
3336 <refentrytitle><phrase>drm_vma_node_start</phrase></refentrytitle>
3337 <manvolnum>9</manvolnum>
3338 <refmiscinfo class="version">4.1.27</refmiscinfo>
3339</refmeta>
3340<refnamediv>
3341 <refname>drm_vma_node_start</refname>
3342 <refpurpose>
3343     Return start address for page-based addressing
3344 </refpurpose>
3345</refnamediv>
3346<refsynopsisdiv>
3347 <title>Synopsis</title>
3348  <funcsynopsis><funcprototype>
3349   <funcdef>unsigned long <function>drm_vma_node_start </function></funcdef>
3350   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3351  </funcprototype></funcsynopsis>
3352</refsynopsisdiv>
3353<refsect1>
3354 <title>Arguments</title>
3355 <variablelist>
3356  <varlistentry>
3357   <term><parameter>node</parameter></term>
3358   <listitem>
3359    <para>
3360     Node to inspect
3361    </para>
3362   </listitem>
3363  </varlistentry>
3364 </variablelist>
3365</refsect1>
3366<refsect1>
3367<title>Description</title>
3368<para>
3369   Return the start address of the given node. This can be used as offset into
3370   the linear VM space that is provided by the VMA offset manager. Note that
3371   this can only be used for page-based addressing. If you need a proper offset
3372   for user-space mappings, you must apply <quote>&lt;&lt; PAGE_SHIFT</quote> or use the
3373   <function>drm_vma_node_offset_addr</function> helper instead.
3374</para>
3375</refsect1>
3376<refsect1>
3377<title>RETURNS</title>
3378<para>
3379   Start address of <parameter>node</parameter> for page-based addressing. 0 if the node does not
3380   have an offset allocated.
3381</para>
3382</refsect1>
3383</refentry>
3384
3385<refentry id="API-drm-vma-node-size">
3386<refentryinfo>
3387 <title>LINUX</title>
3388 <productname>Kernel Hackers Manual</productname>
3389 <date>July 2017</date>
3390</refentryinfo>
3391<refmeta>
3392 <refentrytitle><phrase>drm_vma_node_size</phrase></refentrytitle>
3393 <manvolnum>9</manvolnum>
3394 <refmiscinfo class="version">4.1.27</refmiscinfo>
3395</refmeta>
3396<refnamediv>
3397 <refname>drm_vma_node_size</refname>
3398 <refpurpose>
3399     Return size (page-based)
3400 </refpurpose>
3401</refnamediv>
3402<refsynopsisdiv>
3403 <title>Synopsis</title>
3404  <funcsynopsis><funcprototype>
3405   <funcdef>unsigned long <function>drm_vma_node_size </function></funcdef>
3406   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3407  </funcprototype></funcsynopsis>
3408</refsynopsisdiv>
3409<refsect1>
3410 <title>Arguments</title>
3411 <variablelist>
3412  <varlistentry>
3413   <term><parameter>node</parameter></term>
3414   <listitem>
3415    <para>
3416     Node to inspect
3417    </para>
3418   </listitem>
3419  </varlistentry>
3420 </variablelist>
3421</refsect1>
3422<refsect1>
3423<title>Description</title>
3424<para>
3425   Return the size as number of pages for the given node. This is the same size
3426   that was passed to <function>drm_vma_offset_add</function>. If no offset is allocated for the
3427   node, this is 0.
3428</para>
3429</refsect1>
3430<refsect1>
3431<title>RETURNS</title>
3432<para>
3433   Size of <parameter>node</parameter> as number of pages. 0 if the node does not have an offset
3434   allocated.
3435</para>
3436</refsect1>
3437</refentry>
3438
3439<refentry id="API-drm-vma-node-has-offset">
3440<refentryinfo>
3441 <title>LINUX</title>
3442 <productname>Kernel Hackers Manual</productname>
3443 <date>July 2017</date>
3444</refentryinfo>
3445<refmeta>
3446 <refentrytitle><phrase>drm_vma_node_has_offset</phrase></refentrytitle>
3447 <manvolnum>9</manvolnum>
3448 <refmiscinfo class="version">4.1.27</refmiscinfo>
3449</refmeta>
3450<refnamediv>
3451 <refname>drm_vma_node_has_offset</refname>
3452 <refpurpose>
3453     Check whether node is added to offset manager
3454 </refpurpose>
3455</refnamediv>
3456<refsynopsisdiv>
3457 <title>Synopsis</title>
3458  <funcsynopsis><funcprototype>
3459   <funcdef>bool <function>drm_vma_node_has_offset </function></funcdef>
3460   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3461  </funcprototype></funcsynopsis>
3462</refsynopsisdiv>
3463<refsect1>
3464 <title>Arguments</title>
3465 <variablelist>
3466  <varlistentry>
3467   <term><parameter>node</parameter></term>
3468   <listitem>
3469    <para>
3470     Node to be checked
3471    </para>
3472   </listitem>
3473  </varlistentry>
3474 </variablelist>
3475</refsect1>
3476<refsect1>
3477<title>RETURNS</title>
3478<para>
3479   true iff the node was previously allocated an offset and added to
3480   an vma offset manager.
3481</para>
3482</refsect1>
3483</refentry>
3484
3485<refentry id="API-drm-vma-node-offset-addr">
3486<refentryinfo>
3487 <title>LINUX</title>
3488 <productname>Kernel Hackers Manual</productname>
3489 <date>July 2017</date>
3490</refentryinfo>
3491<refmeta>
3492 <refentrytitle><phrase>drm_vma_node_offset_addr</phrase></refentrytitle>
3493 <manvolnum>9</manvolnum>
3494 <refmiscinfo class="version">4.1.27</refmiscinfo>
3495</refmeta>
3496<refnamediv>
3497 <refname>drm_vma_node_offset_addr</refname>
3498 <refpurpose>
3499     Return sanitized offset for user-space mmaps
3500 </refpurpose>
3501</refnamediv>
3502<refsynopsisdiv>
3503 <title>Synopsis</title>
3504  <funcsynopsis><funcprototype>
3505   <funcdef>__u64 <function>drm_vma_node_offset_addr </function></funcdef>
3506   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3507  </funcprototype></funcsynopsis>
3508</refsynopsisdiv>
3509<refsect1>
3510 <title>Arguments</title>
3511 <variablelist>
3512  <varlistentry>
3513   <term><parameter>node</parameter></term>
3514   <listitem>
3515    <para>
3516     Linked offset node
3517    </para>
3518   </listitem>
3519  </varlistentry>
3520 </variablelist>
3521</refsect1>
3522<refsect1>
3523<title>Description</title>
3524<para>
3525   Same as <function>drm_vma_node_start</function> but returns the address as a valid offset that
3526   can be used for user-space mappings during <function>mmap</function>.
3527   This must not be called on unlinked nodes.
3528</para>
3529</refsect1>
3530<refsect1>
3531<title>RETURNS</title>
3532<para>
3533   Offset of <parameter>node</parameter> for byte-based addressing. 0 if the node does not have an
3534   object allocated.
3535</para>
3536</refsect1>
3537</refentry>
3538
3539<refentry id="API-drm-vma-node-unmap">
3540<refentryinfo>
3541 <title>LINUX</title>
3542 <productname>Kernel Hackers Manual</productname>
3543 <date>July 2017</date>
3544</refentryinfo>
3545<refmeta>
3546 <refentrytitle><phrase>drm_vma_node_unmap</phrase></refentrytitle>
3547 <manvolnum>9</manvolnum>
3548 <refmiscinfo class="version">4.1.27</refmiscinfo>
3549</refmeta>
3550<refnamediv>
3551 <refname>drm_vma_node_unmap</refname>
3552 <refpurpose>
3553     Unmap offset node
3554 </refpurpose>
3555</refnamediv>
3556<refsynopsisdiv>
3557 <title>Synopsis</title>
3558  <funcsynopsis><funcprototype>
3559   <funcdef>void <function>drm_vma_node_unmap </function></funcdef>
3560   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3561   <paramdef>struct address_space * <parameter>file_mapping</parameter></paramdef>
3562  </funcprototype></funcsynopsis>
3563</refsynopsisdiv>
3564<refsect1>
3565 <title>Arguments</title>
3566 <variablelist>
3567  <varlistentry>
3568   <term><parameter>node</parameter></term>
3569   <listitem>
3570    <para>
3571     Offset node
3572    </para>
3573   </listitem>
3574  </varlistentry>
3575  <varlistentry>
3576   <term><parameter>file_mapping</parameter></term>
3577   <listitem>
3578    <para>
3579     Address space to unmap <parameter>node</parameter> from
3580    </para>
3581   </listitem>
3582  </varlistentry>
3583 </variablelist>
3584</refsect1>
3585<refsect1>
3586<title>Description</title>
3587<para>
3588   Unmap all userspace mappings for a given offset node. The mappings must be
3589   associated with the <parameter>file_mapping</parameter> address-space. If no offset exists
3590   nothing is done.
3591   </para><para>
3592
3593   This call is unlocked. The caller must guarantee that <function>drm_vma_offset_remove</function>
3594   is not called on this node concurrently.
3595</para>
3596</refsect1>
3597</refentry>
3598
3599<refentry id="API-drm-vma-node-verify-access">
3600<refentryinfo>
3601 <title>LINUX</title>
3602 <productname>Kernel Hackers Manual</productname>
3603 <date>July 2017</date>
3604</refentryinfo>
3605<refmeta>
3606 <refentrytitle><phrase>drm_vma_node_verify_access</phrase></refentrytitle>
3607 <manvolnum>9</manvolnum>
3608 <refmiscinfo class="version">4.1.27</refmiscinfo>
3609</refmeta>
3610<refnamediv>
3611 <refname>drm_vma_node_verify_access</refname>
3612 <refpurpose>
3613     Access verification helper for TTM
3614 </refpurpose>
3615</refnamediv>
3616<refsynopsisdiv>
3617 <title>Synopsis</title>
3618  <funcsynopsis><funcprototype>
3619   <funcdef>int <function>drm_vma_node_verify_access </function></funcdef>
3620   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
3621   <paramdef>struct file * <parameter>filp</parameter></paramdef>
3622  </funcprototype></funcsynopsis>
3623</refsynopsisdiv>
3624<refsect1>
3625 <title>Arguments</title>
3626 <variablelist>
3627  <varlistentry>
3628   <term><parameter>node</parameter></term>
3629   <listitem>
3630    <para>
3631     Offset node
3632    </para>
3633   </listitem>
3634  </varlistentry>
3635  <varlistentry>
3636   <term><parameter>filp</parameter></term>
3637   <listitem>
3638    <para>
3639     Open-file
3640    </para>
3641   </listitem>
3642  </varlistentry>
3643 </variablelist>
3644</refsect1>
3645<refsect1>
3646<title>Description</title>
3647<para>
3648   This checks whether <parameter>filp</parameter> is granted access to <parameter>node</parameter>. It is the same as
3649   <function>drm_vma_node_is_allowed</function> but suitable as drop-in helper for TTM
3650   <function>verify_access</function> callbacks.
3651</para>
3652</refsect1>
3653<refsect1>
3654<title>RETURNS</title>
3655<para>
3656   0 if access is granted, -EACCES otherwise.
3657</para>
3658</refsect1>
3659</refentry>
3660
3661    </sect2>
3662    <sect2 id="drm-prime-support">
3663      <title>PRIME Buffer Sharing</title>
3664      <para>
3665        PRIME is the cross device buffer sharing framework in drm, originally
3666        created for the OPTIMUS range of multi-gpu platforms. To userspace
3667        PRIME buffers are dma-buf based file descriptors.
3668      </para>
3669      <sect3>
3670        <title>Overview and Driver Interface</title>
3671        <para>
3672          Similar to GEM global names, PRIME file descriptors are
3673          also used to share buffer objects across processes. They offer
3674          additional security: as file descriptors must be explicitly sent over
3675          UNIX domain sockets to be shared between applications, they can't be
3676          guessed like the globally unique GEM names.
3677        </para>
3678        <para>
3679          Drivers that support the PRIME
3680          API must set the DRIVER_PRIME bit in the struct
3681          <structname>drm_driver</structname>
3682          <structfield>driver_features</structfield> field, and implement the
3683          <methodname>prime_handle_to_fd</methodname> and
3684          <methodname>prime_fd_to_handle</methodname> operations.
3685        </para>
3686        <para>
3687          <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,
3688                          struct drm_file *file_priv, uint32_t handle,
3689                          uint32_t flags, int *prime_fd);
3690int (*prime_fd_to_handle)(struct drm_device *dev,
3691                          struct drm_file *file_priv, int prime_fd,
3692                          uint32_t *handle);</synopsis>
3693            Those two operations convert a handle to a PRIME file descriptor and
3694            vice versa. Drivers must use the kernel dma-buf buffer sharing framework
3695            to manage the PRIME file descriptors. Similar to the mode setting
3696            API PRIME is agnostic to the underlying buffer object manager, as
3697            long as handles are 32bit unsigned integers.
3698          </para>
3699          <para>
3700            While non-GEM drivers must implement the operations themselves, GEM
3701            drivers must use the <function>drm_gem_prime_handle_to_fd</function>
3702            and <function>drm_gem_prime_fd_to_handle</function> helper functions.
3703            Those helpers rely on the driver
3704            <methodname>gem_prime_export</methodname> and
3705            <methodname>gem_prime_import</methodname> operations to create a dma-buf
3706            instance from a GEM object (dma-buf exporter role) and to create a GEM
3707            object from a dma-buf instance (dma-buf importer role).
3708          </para>
3709          <para>
3710            <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
3711                             struct drm_gem_object *obj,
3712                             int flags);
3713struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
3714                                            struct dma_buf *dma_buf);</synopsis>
3715            These two operations are mandatory for GEM drivers that support
3716            PRIME.
3717          </para>
3718        </sect3>
3719      <sect3>
3720        <title>PRIME Helper Functions</title>
3721<para>
3722   </para><para>
3723   Drivers can implement <parameter>gem_prime_export</parameter> and <parameter>gem_prime_import</parameter> in terms of
3724   simpler APIs by using the helper functions <parameter>drm_gem_prime_export</parameter> and
3725   <parameter>drm_gem_prime_import</parameter>.  These functions implement dma-buf support in terms of
3726   five lower-level driver callbacks:
3727   </para><para>
3728   Export callbacks:
3729   </para><para>
3730   - <parameter>gem_prime_pin</parameter> (optional): prepare a GEM object for exporting
3731   </para><para>
3732   - <parameter>gem_prime_get_sg_table</parameter>: provide a scatter/gather table of pinned pages
3733   </para><para>
3734   - <parameter>gem_prime_vmap</parameter>: vmap a buffer exported by your driver
3735   </para><para>
3736   - <parameter>gem_prime_vunmap</parameter>: vunmap a buffer exported by your driver
3737   </para><para>
3738   Import callback:
3739   </para><para>
3740   - <parameter>gem_prime_import_sg_table</parameter> (import): produce a GEM object from another
3741   driver's scatter/gather table
3742</para>
3743
3744      </sect3>
3745    </sect2>
3746    <sect2>
3747      <title>PRIME Function References</title>
3748<!-- drivers/gpu/drm/drm_prime.c -->
3749<refentry id="API-drm-gem-dmabuf-release">
3750<refentryinfo>
3751 <title>LINUX</title>
3752 <productname>Kernel Hackers Manual</productname>
3753 <date>July 2017</date>
3754</refentryinfo>
3755<refmeta>
3756 <refentrytitle><phrase>drm_gem_dmabuf_release</phrase></refentrytitle>
3757 <manvolnum>9</manvolnum>
3758 <refmiscinfo class="version">4.1.27</refmiscinfo>
3759</refmeta>
3760<refnamediv>
3761 <refname>drm_gem_dmabuf_release</refname>
3762 <refpurpose>
3763  dma_buf release implementation for GEM
3764 </refpurpose>
3765</refnamediv>
3766<refsynopsisdiv>
3767 <title>Synopsis</title>
3768  <funcsynopsis><funcprototype>
3769   <funcdef>void <function>drm_gem_dmabuf_release </function></funcdef>
3770   <paramdef>struct dma_buf * <parameter>dma_buf</parameter></paramdef>
3771  </funcprototype></funcsynopsis>
3772</refsynopsisdiv>
3773<refsect1>
3774 <title>Arguments</title>
3775 <variablelist>
3776  <varlistentry>
3777   <term><parameter>dma_buf</parameter></term>
3778   <listitem>
3779    <para>
3780     buffer to be released
3781    </para>
3782   </listitem>
3783  </varlistentry>
3784 </variablelist>
3785</refsect1>
3786<refsect1>
3787<title>Description</title>
3788<para>
3789   Generic release function for dma_bufs exported as PRIME buffers. GEM drivers
3790   must use this in their dma_buf ops structure as the release callback.
3791</para>
3792</refsect1>
3793</refentry>
3794
3795<refentry id="API-drm-gem-prime-export">
3796<refentryinfo>
3797 <title>LINUX</title>
3798 <productname>Kernel Hackers Manual</productname>
3799 <date>July 2017</date>
3800</refentryinfo>
3801<refmeta>
3802 <refentrytitle><phrase>drm_gem_prime_export</phrase></refentrytitle>
3803 <manvolnum>9</manvolnum>
3804 <refmiscinfo class="version">4.1.27</refmiscinfo>
3805</refmeta>
3806<refnamediv>
3807 <refname>drm_gem_prime_export</refname>
3808 <refpurpose>
3809     helper library implementation of the export callback
3810 </refpurpose>
3811</refnamediv>
3812<refsynopsisdiv>
3813 <title>Synopsis</title>
3814  <funcsynopsis><funcprototype>
3815   <funcdef>struct dma_buf * <function>drm_gem_prime_export </function></funcdef>
3816   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
3817   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
3818   <paramdef>int <parameter>flags</parameter></paramdef>
3819  </funcprototype></funcsynopsis>
3820</refsynopsisdiv>
3821<refsect1>
3822 <title>Arguments</title>
3823 <variablelist>
3824  <varlistentry>
3825   <term><parameter>dev</parameter></term>
3826   <listitem>
3827    <para>
3828     drm_device to export from
3829    </para>
3830   </listitem>
3831  </varlistentry>
3832  <varlistentry>
3833   <term><parameter>obj</parameter></term>
3834   <listitem>
3835    <para>
3836     GEM object to export
3837    </para>
3838   </listitem>
3839  </varlistentry>
3840  <varlistentry>
3841   <term><parameter>flags</parameter></term>
3842   <listitem>
3843    <para>
3844     flags like DRM_CLOEXEC
3845    </para>
3846   </listitem>
3847  </varlistentry>
3848 </variablelist>
3849</refsect1>
3850<refsect1>
3851<title>Description</title>
3852<para>
3853   This is the implementation of the gem_prime_export functions for GEM drivers
3854   using the PRIME helpers.
3855</para>
3856</refsect1>
3857</refentry>
3858
3859<refentry id="API-drm-gem-prime-handle-to-fd">
3860<refentryinfo>
3861 <title>LINUX</title>
3862 <productname>Kernel Hackers Manual</productname>
3863 <date>July 2017</date>
3864</refentryinfo>
3865<refmeta>
3866 <refentrytitle><phrase>drm_gem_prime_handle_to_fd</phrase></refentrytitle>
3867 <manvolnum>9</manvolnum>
3868 <refmiscinfo class="version">4.1.27</refmiscinfo>
3869</refmeta>
3870<refnamediv>
3871 <refname>drm_gem_prime_handle_to_fd</refname>
3872 <refpurpose>
3873     PRIME export function for GEM drivers
3874 </refpurpose>
3875</refnamediv>
3876<refsynopsisdiv>
3877 <title>Synopsis</title>
3878  <funcsynopsis><funcprototype>
3879   <funcdef>int <function>drm_gem_prime_handle_to_fd </function></funcdef>
3880   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
3881   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
3882   <paramdef>uint32_t <parameter>handle</parameter></paramdef>
3883   <paramdef>uint32_t <parameter>flags</parameter></paramdef>
3884   <paramdef>int * <parameter>prime_fd</parameter></paramdef>
3885  </funcprototype></funcsynopsis>
3886</refsynopsisdiv>
3887<refsect1>
3888 <title>Arguments</title>
3889 <variablelist>
3890  <varlistentry>
3891   <term><parameter>dev</parameter></term>
3892   <listitem>
3893    <para>
3894     dev to export the buffer from
3895    </para>
3896   </listitem>
3897  </varlistentry>
3898  <varlistentry>
3899   <term><parameter>file_priv</parameter></term>
3900   <listitem>
3901    <para>
3902     drm file-private structure
3903    </para>
3904   </listitem>
3905  </varlistentry>
3906  <varlistentry>
3907   <term><parameter>handle</parameter></term>
3908   <listitem>
3909    <para>
3910     buffer handle to export
3911    </para>
3912   </listitem>
3913  </varlistentry>
3914  <varlistentry>
3915   <term><parameter>flags</parameter></term>
3916   <listitem>
3917    <para>
3918     flags like DRM_CLOEXEC
3919    </para>
3920   </listitem>
3921  </varlistentry>
3922  <varlistentry>
3923   <term><parameter>prime_fd</parameter></term>
3924   <listitem>
3925    <para>
3926     pointer to storage for the fd id of the create dma-buf
3927    </para>
3928   </listitem>
3929  </varlistentry>
3930 </variablelist>
3931</refsect1>
3932<refsect1>
3933<title>Description</title>
3934<para>
3935   This is the PRIME export function which must be used mandatorily by GEM
3936   drivers to ensure correct lifetime management of the underlying GEM object.
3937   The actual exporting from GEM object to a dma-buf is done through the
3938   gem_prime_export driver callback.
3939</para>
3940</refsect1>
3941</refentry>
3942
3943<refentry id="API-drm-gem-prime-import">
3944<refentryinfo>
3945 <title>LINUX</title>
3946 <productname>Kernel Hackers Manual</productname>
3947 <date>July 2017</date>
3948</refentryinfo>
3949<refmeta>
3950 <refentrytitle><phrase>drm_gem_prime_import</phrase></refentrytitle>
3951 <manvolnum>9</manvolnum>
3952 <refmiscinfo class="version">4.1.27</refmiscinfo>
3953</refmeta>
3954<refnamediv>
3955 <refname>drm_gem_prime_import</refname>
3956 <refpurpose>
3957     helper library implementation of the import callback
3958 </refpurpose>
3959</refnamediv>
3960<refsynopsisdiv>
3961 <title>Synopsis</title>
3962  <funcsynopsis><funcprototype>
3963   <funcdef>struct drm_gem_object * <function>drm_gem_prime_import </function></funcdef>
3964   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
3965   <paramdef>struct dma_buf * <parameter>dma_buf</parameter></paramdef>
3966  </funcprototype></funcsynopsis>
3967</refsynopsisdiv>
3968<refsect1>
3969 <title>Arguments</title>
3970 <variablelist>
3971  <varlistentry>
3972   <term><parameter>dev</parameter></term>
3973   <listitem>
3974    <para>
3975     drm_device to import into
3976    </para>
3977   </listitem>
3978  </varlistentry>
3979  <varlistentry>
3980   <term><parameter>dma_buf</parameter></term>
3981   <listitem>
3982    <para>
3983     dma-buf object to import
3984    </para>
3985   </listitem>
3986  </varlistentry>
3987 </variablelist>
3988</refsect1>
3989<refsect1>
3990<title>Description</title>
3991<para>
3992   This is the implementation of the gem_prime_import functions for GEM drivers
3993   using the PRIME helpers.
3994</para>
3995</refsect1>
3996</refentry>
3997
3998<refentry id="API-drm-gem-prime-fd-to-handle">
3999<refentryinfo>
4000 <title>LINUX</title>
4001 <productname>Kernel Hackers Manual</productname>
4002 <date>July 2017</date>
4003</refentryinfo>
4004<refmeta>
4005 <refentrytitle><phrase>drm_gem_prime_fd_to_handle</phrase></refentrytitle>
4006 <manvolnum>9</manvolnum>
4007 <refmiscinfo class="version">4.1.27</refmiscinfo>
4008</refmeta>
4009<refnamediv>
4010 <refname>drm_gem_prime_fd_to_handle</refname>
4011 <refpurpose>
4012     PRIME import function for GEM drivers
4013 </refpurpose>
4014</refnamediv>
4015<refsynopsisdiv>
4016 <title>Synopsis</title>
4017  <funcsynopsis><funcprototype>
4018   <funcdef>int <function>drm_gem_prime_fd_to_handle </function></funcdef>
4019   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
4020   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
4021   <paramdef>int <parameter>prime_fd</parameter></paramdef>
4022   <paramdef>uint32_t * <parameter>handle</parameter></paramdef>
4023  </funcprototype></funcsynopsis>
4024</refsynopsisdiv>
4025<refsect1>
4026 <title>Arguments</title>
4027 <variablelist>
4028  <varlistentry>
4029   <term><parameter>dev</parameter></term>
4030   <listitem>
4031    <para>
4032     dev to export the buffer from
4033    </para>
4034   </listitem>
4035  </varlistentry>
4036  <varlistentry>
4037   <term><parameter>file_priv</parameter></term>
4038   <listitem>
4039    <para>
4040     drm file-private structure
4041    </para>
4042   </listitem>
4043  </varlistentry>
4044  <varlistentry>
4045   <term><parameter>prime_fd</parameter></term>
4046   <listitem>
4047    <para>
4048     fd id of the dma-buf which should be imported
4049    </para>
4050   </listitem>
4051  </varlistentry>
4052  <varlistentry>
4053   <term><parameter>handle</parameter></term>
4054   <listitem>
4055    <para>
4056     pointer to storage for the handle of the imported buffer object
4057    </para>
4058   </listitem>
4059  </varlistentry>
4060 </variablelist>
4061</refsect1>
4062<refsect1>
4063<title>Description</title>
4064<para>
4065   This is the PRIME import function which must be used mandatorily by GEM
4066   drivers to ensure correct lifetime management of the underlying GEM object.
4067   The actual importing of GEM object from the dma-buf is done through the
4068   gem_import_export driver callback.
4069</para>
4070</refsect1>
4071</refentry>
4072
4073<refentry id="API-drm-prime-pages-to-sg">
4074<refentryinfo>
4075 <title>LINUX</title>
4076 <productname>Kernel Hackers Manual</productname>
4077 <date>July 2017</date>
4078</refentryinfo>
4079<refmeta>
4080 <refentrytitle><phrase>drm_prime_pages_to_sg</phrase></refentrytitle>
4081 <manvolnum>9</manvolnum>
4082 <refmiscinfo class="version">4.1.27</refmiscinfo>
4083</refmeta>
4084<refnamediv>
4085 <refname>drm_prime_pages_to_sg</refname>
4086 <refpurpose>
4087     converts a page array into an sg list
4088 </refpurpose>
4089</refnamediv>
4090<refsynopsisdiv>
4091 <title>Synopsis</title>
4092  <funcsynopsis><funcprototype>
4093   <funcdef>struct sg_table * <function>drm_prime_pages_to_sg </function></funcdef>
4094   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
4095   <paramdef>unsigned int <parameter>nr_pages</parameter></paramdef>
4096  </funcprototype></funcsynopsis>
4097</refsynopsisdiv>
4098<refsect1>
4099 <title>Arguments</title>
4100 <variablelist>
4101  <varlistentry>
4102   <term><parameter>pages</parameter></term>
4103   <listitem>
4104    <para>
4105     pointer to the array of page pointers to convert
4106    </para>
4107   </listitem>
4108  </varlistentry>
4109  <varlistentry>
4110   <term><parameter>nr_pages</parameter></term>
4111   <listitem>
4112    <para>
4113     length of the page vector
4114    </para>
4115   </listitem>
4116  </varlistentry>
4117 </variablelist>
4118</refsect1>
4119<refsect1>
4120<title>Description</title>
4121<para>
4122   This helper creates an sg table object from a set of pages
4123   the driver is responsible for mapping the pages into the
4124   importers address space for use with dma_buf itself.
4125</para>
4126</refsect1>
4127</refentry>
4128
4129<refentry id="API-drm-prime-sg-to-page-addr-arrays">
4130<refentryinfo>
4131 <title>LINUX</title>
4132 <productname>Kernel Hackers Manual</productname>
4133 <date>July 2017</date>
4134</refentryinfo>
4135<refmeta>
4136 <refentrytitle><phrase>drm_prime_sg_to_page_addr_arrays</phrase></refentrytitle>
4137 <manvolnum>9</manvolnum>
4138 <refmiscinfo class="version">4.1.27</refmiscinfo>
4139</refmeta>
4140<refnamediv>
4141 <refname>drm_prime_sg_to_page_addr_arrays</refname>
4142 <refpurpose>
4143     convert an sg table into a page array
4144 </refpurpose>
4145</refnamediv>
4146<refsynopsisdiv>
4147 <title>Synopsis</title>
4148  <funcsynopsis><funcprototype>
4149   <funcdef>int <function>drm_prime_sg_to_page_addr_arrays </function></funcdef>
4150   <paramdef>struct sg_table * <parameter>sgt</parameter></paramdef>
4151   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
4152   <paramdef>dma_addr_t * <parameter>addrs</parameter></paramdef>
4153   <paramdef>int <parameter>max_pages</parameter></paramdef>
4154  </funcprototype></funcsynopsis>
4155</refsynopsisdiv>
4156<refsect1>
4157 <title>Arguments</title>
4158 <variablelist>
4159  <varlistentry>
4160   <term><parameter>sgt</parameter></term>
4161   <listitem>
4162    <para>
4163     scatter-gather table to convert
4164    </para>
4165   </listitem>
4166  </varlistentry>
4167  <varlistentry>
4168   <term><parameter>pages</parameter></term>
4169   <listitem>
4170    <para>
4171     array of page pointers to store the page array in
4172    </para>
4173   </listitem>
4174  </varlistentry>
4175  <varlistentry>
4176   <term><parameter>addrs</parameter></term>
4177   <listitem>
4178    <para>
4179     optional array to store the dma bus address of each page
4180    </para>
4181   </listitem>
4182  </varlistentry>
4183  <varlistentry>
4184   <term><parameter>max_pages</parameter></term>
4185   <listitem>
4186    <para>
4187     size of both the passed-in arrays
4188    </para>
4189   </listitem>
4190  </varlistentry>
4191 </variablelist>
4192</refsect1>
4193<refsect1>
4194<title>Description</title>
4195<para>
4196   Exports an sg table into an array of pages and addresses. This is currently
4197   required by the TTM driver in order to do correct fault handling.
4198</para>
4199</refsect1>
4200</refentry>
4201
4202<refentry id="API-drm-prime-gem-destroy">
4203<refentryinfo>
4204 <title>LINUX</title>
4205 <productname>Kernel Hackers Manual</productname>
4206 <date>July 2017</date>
4207</refentryinfo>
4208<refmeta>
4209 <refentrytitle><phrase>drm_prime_gem_destroy</phrase></refentrytitle>
4210 <manvolnum>9</manvolnum>
4211 <refmiscinfo class="version">4.1.27</refmiscinfo>
4212</refmeta>
4213<refnamediv>
4214 <refname>drm_prime_gem_destroy</refname>
4215 <refpurpose>
4216     helper to clean up a PRIME-imported GEM object
4217 </refpurpose>
4218</refnamediv>
4219<refsynopsisdiv>
4220 <title>Synopsis</title>
4221  <funcsynopsis><funcprototype>
4222   <funcdef>void <function>drm_prime_gem_destroy </function></funcdef>
4223   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
4224   <paramdef>struct sg_table * <parameter>sg</parameter></paramdef>
4225  </funcprototype></funcsynopsis>
4226</refsynopsisdiv>
4227<refsect1>
4228 <title>Arguments</title>
4229 <variablelist>
4230  <varlistentry>
4231   <term><parameter>obj</parameter></term>
4232   <listitem>
4233    <para>
4234     GEM object which was created from a dma-buf
4235    </para>
4236   </listitem>
4237  </varlistentry>
4238  <varlistentry>
4239   <term><parameter>sg</parameter></term>
4240   <listitem>
4241    <para>
4242     the sg-table which was pinned at import time
4243    </para>
4244   </listitem>
4245  </varlistentry>
4246 </variablelist>
4247</refsect1>
4248<refsect1>
4249<title>Description</title>
4250<para>
4251   This is the cleanup functions which GEM drivers need to call when they use
4252   <parameter>drm_gem_prime_import</parameter> to import dma-bufs.
4253</para>
4254</refsect1>
4255</refentry>
4256
4257    </sect2>
4258    <sect2>
4259      <title>DRM MM Range Allocator</title>
4260      <sect3>
4261        <title>Overview</title>
4262<para>
4263   </para><para>
4264   drm_mm provides a simple range allocator. The drivers are free to use the
4265   resource allocator from the linux core if it suits them, the upside of drm_mm
4266   is that it's in the DRM core. Which means that it's easier to extend for
4267   some of the crazier special purpose needs of gpus.
4268   </para><para>
4269   The main data struct is <structname>drm_mm</structname>, allocations are tracked in <structname>drm_mm_node</structname>.
4270   Drivers are free to embed either of them into their own suitable
4271   datastructures. drm_mm itself will not do any allocations of its own, so if
4272   drivers choose not to embed nodes they need to still allocate them
4273   themselves.
4274   </para><para>
4275   The range allocator also supports reservation of preallocated blocks. This is
4276   useful for taking over initial mode setting configurations from the firmware,
4277   where an object needs to be created which exactly matches the firmware's
4278   scanout target. As long as the range is still free it can be inserted anytime
4279   after the allocator is initialized, which helps with avoiding looped
4280   depencies in the driver load sequence.
4281   </para><para>
4282   drm_mm maintains a stack of most recently freed holes, which of all
4283   simplistic datastructures seems to be a fairly decent approach to clustering
4284   allocations and avoiding too much fragmentation. This means free space
4285   searches are O(num_holes). Given that all the fancy features drm_mm supports
4286   something better would be fairly complex and since gfx thrashing is a fairly
4287   steep cliff not a real concern. Removing a node again is O(1).
4288   </para><para>
4289   drm_mm supports a few features: Alignment and range restrictions can be
4290   supplied. Further more every <structname>drm_mm_node</structname> has a color value (which is just an
4291   opaqua unsigned long) which in conjunction with a driver callback can be used
4292   to implement sophisticated placement restrictions. The i915 DRM driver uses
4293   this to implement guard pages between incompatible caching domains in the
4294   graphics TT.
4295   </para><para>
4296   Two behaviors are supported for searching and allocating: bottom-up and top-down.
4297   The default is bottom-up. Top-down allocation can be used if the memory area
4298   has different restrictions, or just to reduce fragmentation.
4299   </para><para>
4300   Finally iteration helpers to walk all nodes and all holes are provided as are
4301   some basic allocator dumpers for debugging.
4302</para>
4303
4304      </sect3>
4305      <sect3>
4306        <title>LRU Scan/Eviction Support</title>
4307<para>
4308   </para><para>
4309   Very often GPUs need to have continuous allocations for a given object. When
4310   evicting objects to make space for a new one it is therefore not most
4311   efficient when we simply start to select all objects from the tail of an LRU
4312   until there's a suitable hole: Especially for big objects or nodes that
4313   otherwise have special allocation constraints there's a good chance we evict
4314   lots of (smaller) objects unecessarily.
4315   </para><para>
4316   The DRM range allocator supports this use-case through the scanning
4317   interfaces. First a scan operation needs to be initialized with
4318   <function>drm_mm_init_scan</function> or <function>drm_mm_init_scan_with_range</function>. The the driver adds
4319   objects to the roaster (probably by walking an LRU list, but this can be
4320   freely implemented) until a suitable hole is found or there's no further
4321   evitable object.
4322   </para><para>
4323   The the driver must walk through all objects again in exactly the reverse
4324   order to restore the allocator state. Note that while the allocator is used
4325   in the scan mode no other operation is allowed.
4326   </para><para>
4327   Finally the driver evicts all objects selected in the scan. Adding and
4328   removing an object is O(1), and since freeing a node is also O(1) the overall
4329   complexity is O(scanned_objects). So like the free stack which needs to be
4330   walked before a scan operation even begins this is linear in the number of
4331   objects. It doesn't seem to hurt badly.
4332</para>
4333
4334      </sect3>
4335      </sect2>
4336    <sect2>
4337      <title>DRM MM Range Allocator Function References</title>
4338<!-- drivers/gpu/drm/drm_mm.c -->
4339<refentry id="API-drm-mm-reserve-node">
4340<refentryinfo>
4341 <title>LINUX</title>
4342 <productname>Kernel Hackers Manual</productname>
4343 <date>July 2017</date>
4344</refentryinfo>
4345<refmeta>
4346 <refentrytitle><phrase>drm_mm_reserve_node</phrase></refentrytitle>
4347 <manvolnum>9</manvolnum>
4348 <refmiscinfo class="version">4.1.27</refmiscinfo>
4349</refmeta>
4350<refnamediv>
4351 <refname>drm_mm_reserve_node</refname>
4352 <refpurpose>
4353  insert an pre-initialized node
4354 </refpurpose>
4355</refnamediv>
4356<refsynopsisdiv>
4357 <title>Synopsis</title>
4358  <funcsynopsis><funcprototype>
4359   <funcdef>int <function>drm_mm_reserve_node </function></funcdef>
4360   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
4361   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
4362  </funcprototype></funcsynopsis>
4363</refsynopsisdiv>
4364<refsect1>
4365 <title>Arguments</title>
4366 <variablelist>
4367  <varlistentry>
4368   <term><parameter>mm</parameter></term>
4369   <listitem>
4370    <para>
4371     drm_mm allocator to insert <parameter>node</parameter> into
4372    </para>
4373   </listitem>
4374  </varlistentry>
4375  <varlistentry>
4376   <term><parameter>node</parameter></term>
4377   <listitem>
4378    <para>
4379     drm_mm_node to insert
4380    </para>
4381   </listitem>
4382  </varlistentry>
4383 </variablelist>
4384</refsect1>
4385<refsect1>
4386<title>Description</title>
4387<para>
4388   This functions inserts an already set-up drm_mm_node into the allocator,
4389   meaning that start, size and color must be set by the caller. This is useful
4390   to initialize the allocator with preallocated objects which must be set-up
4391   before the range allocator can be set-up, e.g. when taking over a firmware
4392   framebuffer.
4393</para>
4394</refsect1>
4395<refsect1>
4396<title>Returns</title>
4397<para>
4398   0 on success, -ENOSPC if there's no hole where <parameter>node</parameter> is.
4399</para>
4400</refsect1>
4401</refentry>
4402
4403<refentry id="API-drm-mm-insert-node-generic">
4404<refentryinfo>
4405 <title>LINUX</title>
4406 <productname>Kernel Hackers Manual</productname>
4407 <date>July 2017</date>
4408</refentryinfo>
4409<refmeta>
4410 <refentrytitle><phrase>drm_mm_insert_node_generic</phrase></refentrytitle>
4411 <manvolnum>9</manvolnum>
4412 <refmiscinfo class="version">4.1.27</refmiscinfo>
4413</refmeta>
4414<refnamediv>
4415 <refname>drm_mm_insert_node_generic</refname>
4416 <refpurpose>
4417     search for space and insert <parameter>node</parameter>
4418 </refpurpose>
4419</refnamediv>
4420<refsynopsisdiv>
4421 <title>Synopsis</title>
4422  <funcsynopsis><funcprototype>
4423   <funcdef>int <function>drm_mm_insert_node_generic </function></funcdef>
4424   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
4425   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
4426   <paramdef>u64 <parameter>size</parameter></paramdef>
4427   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
4428   <paramdef>unsigned long <parameter>color</parameter></paramdef>
4429   <paramdef>enum drm_mm_search_flags <parameter>sflags</parameter></paramdef>
4430   <paramdef>enum drm_mm_allocator_flags <parameter>aflags</parameter></paramdef>
4431  </funcprototype></funcsynopsis>
4432</refsynopsisdiv>
4433<refsect1>
4434 <title>Arguments</title>
4435 <variablelist>
4436  <varlistentry>
4437   <term><parameter>mm</parameter></term>
4438   <listitem>
4439    <para>
4440     drm_mm to allocate from
4441    </para>
4442   </listitem>
4443  </varlistentry>
4444  <varlistentry>
4445   <term><parameter>node</parameter></term>
4446   <listitem>
4447    <para>
4448     preallocate node to insert
4449    </para>
4450   </listitem>
4451  </varlistentry>
4452  <varlistentry>
4453   <term><parameter>size</parameter></term>
4454   <listitem>
4455    <para>
4456     size of the allocation
4457    </para>
4458   </listitem>
4459  </varlistentry>
4460  <varlistentry>
4461   <term><parameter>alignment</parameter></term>
4462   <listitem>
4463    <para>
4464     alignment of the allocation
4465    </para>
4466   </listitem>
4467  </varlistentry>
4468  <varlistentry>
4469   <term><parameter>color</parameter></term>
4470   <listitem>
4471    <para>
4472     opaque tag value to use for this node
4473    </para>
4474   </listitem>
4475  </varlistentry>
4476  <varlistentry>
4477   <term><parameter>sflags</parameter></term>
4478   <listitem>
4479    <para>
4480     flags to fine-tune the allocation search
4481    </para>
4482   </listitem>
4483  </varlistentry>
4484  <varlistentry>
4485   <term><parameter>aflags</parameter></term>
4486   <listitem>
4487    <para>
4488     flags to fine-tune the allocation behavior
4489    </para>
4490   </listitem>
4491  </varlistentry>
4492 </variablelist>
4493</refsect1>
4494<refsect1>
4495<title>Description</title>
4496<para>
4497   The preallocated node must be cleared to 0.
4498</para>
4499</refsect1>
4500<refsect1>
4501<title>Returns</title>
4502<para>
4503   0 on success, -ENOSPC if there's no suitable hole.
4504</para>
4505</refsect1>
4506</refentry>
4507
4508<refentry id="API-drm-mm-insert-node-in-range-generic">
4509<refentryinfo>
4510 <title>LINUX</title>
4511 <productname>Kernel Hackers Manual</productname>
4512 <date>July 2017</date>
4513</refentryinfo>
4514<refmeta>
4515 <refentrytitle><phrase>drm_mm_insert_node_in_range_generic</phrase></refentrytitle>
4516 <manvolnum>9</manvolnum>
4517 <refmiscinfo class="version">4.1.27</refmiscinfo>
4518</refmeta>
4519<refnamediv>
4520 <refname>drm_mm_insert_node_in_range_generic</refname>
4521 <refpurpose>
4522     ranged search for space and insert <parameter>node</parameter>
4523 </refpurpose>
4524</refnamediv>
4525<refsynopsisdiv>
4526 <title>Synopsis</title>
4527  <funcsynopsis><funcprototype>
4528   <funcdef>int <function>drm_mm_insert_node_in_range_generic </function></funcdef>
4529   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
4530   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
4531   <paramdef>u64 <parameter>size</parameter></paramdef>
4532   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
4533   <paramdef>unsigned long <parameter>color</parameter></paramdef>
4534   <paramdef>u64 <parameter>start</parameter></paramdef>
4535   <paramdef>u64 <parameter>end</parameter></paramdef>
4536   <paramdef>enum drm_mm_search_flags <parameter>sflags</parameter></paramdef>
4537   <paramdef>enum drm_mm_allocator_flags <parameter>aflags</parameter></paramdef>
4538  </funcprototype></funcsynopsis>
4539</refsynopsisdiv>
4540<refsect1>
4541 <title>Arguments</title>
4542 <variablelist>
4543  <varlistentry>
4544   <term><parameter>mm</parameter></term>
4545   <listitem>
4546    <para>
4547     drm_mm to allocate from
4548    </para>
4549   </listitem>
4550  </varlistentry>
4551  <varlistentry>
4552   <term><parameter>node</parameter></term>
4553   <listitem>
4554    <para>
4555     preallocate node to insert
4556    </para>
4557   </listitem>
4558  </varlistentry>
4559  <varlistentry>
4560   <term><parameter>size</parameter></term>
4561   <listitem>
4562    <para>
4563     size of the allocation
4564    </para>
4565   </listitem>
4566  </varlistentry>
4567  <varlistentry>
4568   <term><parameter>alignment</parameter></term>
4569   <listitem>
4570    <para>
4571     alignment of the allocation
4572    </para>
4573   </listitem>
4574  </varlistentry>
4575  <varlistentry>
4576   <term><parameter>color</parameter></term>
4577   <listitem>
4578    <para>
4579     opaque tag value to use for this node
4580    </para>
4581   </listitem>
4582  </varlistentry>
4583  <varlistentry>
4584   <term><parameter>start</parameter></term>
4585   <listitem>
4586    <para>
4587     start of the allowed range for this node
4588    </para>
4589   </listitem>
4590  </varlistentry>
4591  <varlistentry>
4592   <term><parameter>end</parameter></term>
4593   <listitem>
4594    <para>
4595     end of the allowed range for this node
4596    </para>
4597   </listitem>
4598  </varlistentry>
4599  <varlistentry>
4600   <term><parameter>sflags</parameter></term>
4601   <listitem>
4602    <para>
4603     flags to fine-tune the allocation search
4604    </para>
4605   </listitem>
4606  </varlistentry>
4607  <varlistentry>
4608   <term><parameter>aflags</parameter></term>
4609   <listitem>
4610    <para>
4611     flags to fine-tune the allocation behavior
4612    </para>
4613   </listitem>
4614  </varlistentry>
4615 </variablelist>
4616</refsect1>
4617<refsect1>
4618<title>Description</title>
4619<para>
4620   The preallocated node must be cleared to 0.
4621</para>
4622</refsect1>
4623<refsect1>
4624<title>Returns</title>
4625<para>
4626   0 on success, -ENOSPC if there's no suitable hole.
4627</para>
4628</refsect1>
4629</refentry>
4630
4631<refentry id="API-drm-mm-remove-node">
4632<refentryinfo>
4633 <title>LINUX</title>
4634 <productname>Kernel Hackers Manual</productname>
4635 <date>July 2017</date>
4636</refentryinfo>
4637<refmeta>
4638 <refentrytitle><phrase>drm_mm_remove_node</phrase></refentrytitle>
4639 <manvolnum>9</manvolnum>
4640 <refmiscinfo class="version">4.1.27</refmiscinfo>
4641</refmeta>
4642<refnamediv>
4643 <refname>drm_mm_remove_node</refname>
4644 <refpurpose>
4645     Remove a memory node from the allocator.
4646 </refpurpose>
4647</refnamediv>
4648<refsynopsisdiv>
4649 <title>Synopsis</title>
4650  <funcsynopsis><funcprototype>
4651   <funcdef>void <function>drm_mm_remove_node </function></funcdef>
4652   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
4653  </funcprototype></funcsynopsis>
4654</refsynopsisdiv>
4655<refsect1>
4656 <title>Arguments</title>
4657 <variablelist>
4658  <varlistentry>
4659   <term><parameter>node</parameter></term>
4660   <listitem>
4661    <para>
4662     drm_mm_node to remove
4663    </para>
4664   </listitem>
4665  </varlistentry>
4666 </variablelist>
4667</refsect1>
4668<refsect1>
4669<title>Description</title>
4670<para>
4671   This just removes a node from its drm_mm allocator. The node does not need to
4672   be cleared again before it can be re-inserted into this or any other drm_mm
4673   allocator. It is a bug to call this function on a un-allocated node.
4674</para>
4675</refsect1>
4676</refentry>
4677
4678<refentry id="API-drm-mm-replace-node">
4679<refentryinfo>
4680 <title>LINUX</title>
4681 <productname>Kernel Hackers Manual</productname>
4682 <date>July 2017</date>
4683</refentryinfo>
4684<refmeta>
4685 <refentrytitle><phrase>drm_mm_replace_node</phrase></refentrytitle>
4686 <manvolnum>9</manvolnum>
4687 <refmiscinfo class="version">4.1.27</refmiscinfo>
4688</refmeta>
4689<refnamediv>
4690 <refname>drm_mm_replace_node</refname>
4691 <refpurpose>
4692     move an allocation from <parameter>old</parameter> to <parameter>new</parameter>
4693 </refpurpose>
4694</refnamediv>
4695<refsynopsisdiv>
4696 <title>Synopsis</title>
4697  <funcsynopsis><funcprototype>
4698   <funcdef>void <function>drm_mm_replace_node </function></funcdef>
4699   <paramdef>struct drm_mm_node * <parameter>old</parameter></paramdef>
4700   <paramdef>struct drm_mm_node * <parameter>new</parameter></paramdef>
4701  </funcprototype></funcsynopsis>
4702</refsynopsisdiv>
4703<refsect1>
4704 <title>Arguments</title>
4705 <variablelist>
4706  <varlistentry>
4707   <term><parameter>old</parameter></term>
4708   <listitem>
4709    <para>
4710     drm_mm_node to remove from the allocator
4711    </para>
4712   </listitem>
4713  </varlistentry>
4714  <varlistentry>
4715   <term><parameter>new</parameter></term>
4716   <listitem>
4717    <para>
4718     drm_mm_node which should inherit <parameter>old</parameter>'s allocation
4719    </para>
4720   </listitem>
4721  </varlistentry>
4722 </variablelist>
4723</refsect1>
4724<refsect1>
4725<title>Description</title>
4726<para>
4727   This is useful for when drivers embed the drm_mm_node structure and hence
4728   can't move allocations by reassigning pointers. It's a combination of remove
4729   and insert with the guarantee that the allocation start will match.
4730</para>
4731</refsect1>
4732</refentry>
4733
4734<refentry id="API-drm-mm-init-scan">
4735<refentryinfo>
4736 <title>LINUX</title>
4737 <productname>Kernel Hackers Manual</productname>
4738 <date>July 2017</date>
4739</refentryinfo>
4740<refmeta>
4741 <refentrytitle><phrase>drm_mm_init_scan</phrase></refentrytitle>
4742 <manvolnum>9</manvolnum>
4743 <refmiscinfo class="version">4.1.27</refmiscinfo>
4744</refmeta>
4745<refnamediv>
4746 <refname>drm_mm_init_scan</refname>
4747 <refpurpose>
4748     initialize lru scanning
4749 </refpurpose>
4750</refnamediv>
4751<refsynopsisdiv>
4752 <title>Synopsis</title>
4753  <funcsynopsis><funcprototype>
4754   <funcdef>void <function>drm_mm_init_scan </function></funcdef>
4755   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
4756   <paramdef>u64 <parameter>size</parameter></paramdef>
4757   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
4758   <paramdef>unsigned long <parameter>color</parameter></paramdef>
4759  </funcprototype></funcsynopsis>
4760</refsynopsisdiv>
4761<refsect1>
4762 <title>Arguments</title>
4763 <variablelist>
4764  <varlistentry>
4765   <term><parameter>mm</parameter></term>
4766   <listitem>
4767    <para>
4768     drm_mm to scan
4769    </para>
4770   </listitem>
4771  </varlistentry>
4772  <varlistentry>
4773   <term><parameter>size</parameter></term>
4774   <listitem>
4775    <para>
4776     size of the allocation
4777    </para>
4778   </listitem>
4779  </varlistentry>
4780  <varlistentry>
4781   <term><parameter>alignment</parameter></term>
4782   <listitem>
4783    <para>
4784     alignment of the allocation
4785    </para>
4786   </listitem>
4787  </varlistentry>
4788  <varlistentry>
4789   <term><parameter>color</parameter></term>
4790   <listitem>
4791    <para>
4792     opaque tag value to use for the allocation
4793    </para>
4794   </listitem>
4795  </varlistentry>
4796 </variablelist>
4797</refsect1>
4798<refsect1>
4799<title>Description</title>
4800<para>
4801   This simply sets up the scanning routines with the parameters for the desired
4802   hole. Note that there's no need to specify allocation flags, since they only
4803   change the place a node is allocated from within a suitable hole.
4804</para>
4805</refsect1>
4806<refsect1>
4807<title>Warning</title>
4808<para>
4809   As long as the scan list is non-empty, no other operations than
4810   adding/removing nodes to/from the scan list are allowed.
4811</para>
4812</refsect1>
4813</refentry>
4814
4815<refentry id="API-drm-mm-init-scan-with-range">
4816<refentryinfo>
4817 <title>LINUX</title>
4818 <productname>Kernel Hackers Manual</productname>
4819 <date>July 2017</date>
4820</refentryinfo>
4821<refmeta>
4822 <refentrytitle><phrase>drm_mm_init_scan_with_range</phrase></refentrytitle>
4823 <manvolnum>9</manvolnum>
4824 <refmiscinfo class="version">4.1.27</refmiscinfo>
4825</refmeta>
4826<refnamediv>
4827 <refname>drm_mm_init_scan_with_range</refname>
4828 <refpurpose>
4829     initialize range-restricted lru scanning
4830 </refpurpose>
4831</refnamediv>
4832<refsynopsisdiv>
4833 <title>Synopsis</title>
4834  <funcsynopsis><funcprototype>
4835   <funcdef>void <function>drm_mm_init_scan_with_range </function></funcdef>
4836   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
4837   <paramdef>u64 <parameter>size</parameter></paramdef>
4838   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
4839   <paramdef>unsigned long <parameter>color</parameter></paramdef>
4840   <paramdef>u64 <parameter>start</parameter></paramdef>
4841   <paramdef>u64 <parameter>end</parameter></paramdef>
4842  </funcprototype></funcsynopsis>
4843</refsynopsisdiv>
4844<refsect1>
4845 <title>Arguments</title>
4846 <variablelist>
4847  <varlistentry>
4848   <term><parameter>mm</parameter></term>
4849   <listitem>
4850    <para>
4851     drm_mm to scan
4852    </para>
4853   </listitem>
4854  </varlistentry>
4855  <varlistentry>
4856   <term><parameter>size</parameter></term>
4857   <listitem>
4858    <para>
4859     size of the allocation
4860    </para>
4861   </listitem>
4862  </varlistentry>
4863  <varlistentry>
4864   <term><parameter>alignment</parameter></term>
4865   <listitem>
4866    <para>
4867     alignment of the allocation
4868    </para>
4869   </listitem>
4870  </varlistentry>
4871  <varlistentry>
4872   <term><parameter>color</parameter></term>
4873   <listitem>
4874    <para>
4875     opaque tag value to use for the allocation
4876    </para>
4877   </listitem>
4878  </varlistentry>
4879  <varlistentry>
4880   <term><parameter>start</parameter></term>
4881   <listitem>
4882    <para>
4883     start of the allowed range for the allocation
4884    </para>
4885   </listitem>
4886  </varlistentry>
4887  <varlistentry>
4888   <term><parameter>end</parameter></term>
4889   <listitem>
4890    <para>
4891     end of the allowed range for the allocation
4892    </para>
4893   </listitem>
4894  </varlistentry>
4895 </variablelist>
4896</refsect1>
4897<refsect1>
4898<title>Description</title>
4899<para>
4900   This simply sets up the scanning routines with the parameters for the desired
4901   hole. Note that there's no need to specify allocation flags, since they only
4902   change the place a node is allocated from within a suitable hole.
4903</para>
4904</refsect1>
4905<refsect1>
4906<title>Warning</title>
4907<para>
4908   As long as the scan list is non-empty, no other operations than
4909   adding/removing nodes to/from the scan list are allowed.
4910</para>
4911</refsect1>
4912</refentry>
4913
4914<refentry id="API-drm-mm-scan-add-block">
4915<refentryinfo>
4916 <title>LINUX</title>
4917 <productname>Kernel Hackers Manual</productname>
4918 <date>July 2017</date>
4919</refentryinfo>
4920<refmeta>
4921 <refentrytitle><phrase>drm_mm_scan_add_block</phrase></refentrytitle>
4922 <manvolnum>9</manvolnum>
4923 <refmiscinfo class="version">4.1.27</refmiscinfo>
4924</refmeta>
4925<refnamediv>
4926 <refname>drm_mm_scan_add_block</refname>
4927 <refpurpose>
4928     add a node to the scan list
4929 </refpurpose>
4930</refnamediv>
4931<refsynopsisdiv>
4932 <title>Synopsis</title>
4933  <funcsynopsis><funcprototype>
4934   <funcdef>bool <function>drm_mm_scan_add_block </function></funcdef>
4935   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
4936  </funcprototype></funcsynopsis>
4937</refsynopsisdiv>
4938<refsect1>
4939 <title>Arguments</title>
4940 <variablelist>
4941  <varlistentry>
4942   <term><parameter>node</parameter></term>
4943   <listitem>
4944    <para>
4945     drm_mm_node to add
4946    </para>
4947   </listitem>
4948  </varlistentry>
4949 </variablelist>
4950</refsect1>
4951<refsect1>
4952<title>Description</title>
4953<para>
4954   Add a node to the scan list that might be freed to make space for the desired
4955   hole.
4956</para>
4957</refsect1>
4958<refsect1>
4959<title>Returns</title>
4960<para>
4961   True if a hole has been found, false otherwise.
4962</para>
4963</refsect1>
4964</refentry>
4965
4966<refentry id="API-drm-mm-scan-remove-block">
4967<refentryinfo>
4968 <title>LINUX</title>
4969 <productname>Kernel Hackers Manual</productname>
4970 <date>July 2017</date>
4971</refentryinfo>
4972<refmeta>
4973 <refentrytitle><phrase>drm_mm_scan_remove_block</phrase></refentrytitle>
4974 <manvolnum>9</manvolnum>
4975 <refmiscinfo class="version">4.1.27</refmiscinfo>
4976</refmeta>
4977<refnamediv>
4978 <refname>drm_mm_scan_remove_block</refname>
4979 <refpurpose>
4980     remove a node from the scan list
4981 </refpurpose>
4982</refnamediv>
4983<refsynopsisdiv>
4984 <title>Synopsis</title>
4985  <funcsynopsis><funcprototype>
4986   <funcdef>bool <function>drm_mm_scan_remove_block </function></funcdef>
4987   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
4988  </funcprototype></funcsynopsis>
4989</refsynopsisdiv>
4990<refsect1>
4991 <title>Arguments</title>
4992 <variablelist>
4993  <varlistentry>
4994   <term><parameter>node</parameter></term>
4995   <listitem>
4996    <para>
4997     drm_mm_node to remove
4998    </para>
4999   </listitem>
5000  </varlistentry>
5001 </variablelist>
5002</refsect1>
5003<refsect1>
5004<title>Description</title>
5005<para>
5006   Nodes _must_ be removed in the exact same order from the scan list as they
5007   have been added, otherwise the internal state of the memory manager will be
5008   corrupted.
5009   </para><para>
5010
5011   When the scan list is empty, the selected memory nodes can be freed. An
5012   immediately following drm_mm_search_free with !DRM_MM_SEARCH_BEST will then
5013   return the just freed block (because its at the top of the free_stack list).
5014</para>
5015</refsect1>
5016<refsect1>
5017<title>Returns</title>
5018<para>
5019   True if this block should be evicted, false otherwise. Will always
5020   return false when no hole has been found.
5021</para>
5022</refsect1>
5023</refentry>
5024
5025<refentry id="API-drm-mm-clean">
5026<refentryinfo>
5027 <title>LINUX</title>
5028 <productname>Kernel Hackers Manual</productname>
5029 <date>July 2017</date>
5030</refentryinfo>
5031<refmeta>
5032 <refentrytitle><phrase>drm_mm_clean</phrase></refentrytitle>
5033 <manvolnum>9</manvolnum>
5034 <refmiscinfo class="version">4.1.27</refmiscinfo>
5035</refmeta>
5036<refnamediv>
5037 <refname>drm_mm_clean</refname>
5038 <refpurpose>
5039     checks whether an allocator is clean
5040 </refpurpose>
5041</refnamediv>
5042<refsynopsisdiv>
5043 <title>Synopsis</title>
5044  <funcsynopsis><funcprototype>
5045   <funcdef>bool <function>drm_mm_clean </function></funcdef>
5046   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5047  </funcprototype></funcsynopsis>
5048</refsynopsisdiv>
5049<refsect1>
5050 <title>Arguments</title>
5051 <variablelist>
5052  <varlistentry>
5053   <term><parameter>mm</parameter></term>
5054   <listitem>
5055    <para>
5056     drm_mm allocator to check
5057    </para>
5058   </listitem>
5059  </varlistentry>
5060 </variablelist>
5061</refsect1>
5062<refsect1>
5063<title>Returns</title>
5064<para>
5065   True if the allocator is completely free, false if there's still a node
5066   allocated in it.
5067</para>
5068</refsect1>
5069</refentry>
5070
5071<refentry id="API-drm-mm-init">
5072<refentryinfo>
5073 <title>LINUX</title>
5074 <productname>Kernel Hackers Manual</productname>
5075 <date>July 2017</date>
5076</refentryinfo>
5077<refmeta>
5078 <refentrytitle><phrase>drm_mm_init</phrase></refentrytitle>
5079 <manvolnum>9</manvolnum>
5080 <refmiscinfo class="version">4.1.27</refmiscinfo>
5081</refmeta>
5082<refnamediv>
5083 <refname>drm_mm_init</refname>
5084 <refpurpose>
5085     initialize a drm-mm allocator
5086 </refpurpose>
5087</refnamediv>
5088<refsynopsisdiv>
5089 <title>Synopsis</title>
5090  <funcsynopsis><funcprototype>
5091   <funcdef>void <function>drm_mm_init </function></funcdef>
5092   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5093   <paramdef>u64 <parameter>start</parameter></paramdef>
5094   <paramdef>u64 <parameter>size</parameter></paramdef>
5095  </funcprototype></funcsynopsis>
5096</refsynopsisdiv>
5097<refsect1>
5098 <title>Arguments</title>
5099 <variablelist>
5100  <varlistentry>
5101   <term><parameter>mm</parameter></term>
5102   <listitem>
5103    <para>
5104     the drm_mm structure to initialize
5105    </para>
5106   </listitem>
5107  </varlistentry>
5108  <varlistentry>
5109   <term><parameter>start</parameter></term>
5110   <listitem>
5111    <para>
5112     start of the range managed by <parameter>mm</parameter>
5113    </para>
5114   </listitem>
5115  </varlistentry>
5116  <varlistentry>
5117   <term><parameter>size</parameter></term>
5118   <listitem>
5119    <para>
5120     end of the range managed by <parameter>mm</parameter>
5121    </para>
5122   </listitem>
5123  </varlistentry>
5124 </variablelist>
5125</refsect1>
5126<refsect1>
5127<title>Description</title>
5128<para>
5129   Note that <parameter>mm</parameter> must be cleared to 0 before calling this function.
5130</para>
5131</refsect1>
5132</refentry>
5133
5134<refentry id="API-drm-mm-takedown">
5135<refentryinfo>
5136 <title>LINUX</title>
5137 <productname>Kernel Hackers Manual</productname>
5138 <date>July 2017</date>
5139</refentryinfo>
5140<refmeta>
5141 <refentrytitle><phrase>drm_mm_takedown</phrase></refentrytitle>
5142 <manvolnum>9</manvolnum>
5143 <refmiscinfo class="version">4.1.27</refmiscinfo>
5144</refmeta>
5145<refnamediv>
5146 <refname>drm_mm_takedown</refname>
5147 <refpurpose>
5148     clean up a drm_mm allocator
5149 </refpurpose>
5150</refnamediv>
5151<refsynopsisdiv>
5152 <title>Synopsis</title>
5153  <funcsynopsis><funcprototype>
5154   <funcdef>void <function>drm_mm_takedown </function></funcdef>
5155   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5156  </funcprototype></funcsynopsis>
5157</refsynopsisdiv>
5158<refsect1>
5159 <title>Arguments</title>
5160 <variablelist>
5161  <varlistentry>
5162   <term><parameter>mm</parameter></term>
5163   <listitem>
5164    <para>
5165     drm_mm allocator to clean up
5166    </para>
5167   </listitem>
5168  </varlistentry>
5169 </variablelist>
5170</refsect1>
5171<refsect1>
5172<title>Description</title>
5173<para>
5174   Note that it is a bug to call this function on an allocator which is not
5175   clean.
5176</para>
5177</refsect1>
5178</refentry>
5179
5180<refentry id="API-drm-mm-debug-table">
5181<refentryinfo>
5182 <title>LINUX</title>
5183 <productname>Kernel Hackers Manual</productname>
5184 <date>July 2017</date>
5185</refentryinfo>
5186<refmeta>
5187 <refentrytitle><phrase>drm_mm_debug_table</phrase></refentrytitle>
5188 <manvolnum>9</manvolnum>
5189 <refmiscinfo class="version">4.1.27</refmiscinfo>
5190</refmeta>
5191<refnamediv>
5192 <refname>drm_mm_debug_table</refname>
5193 <refpurpose>
5194     dump allocator state to dmesg
5195 </refpurpose>
5196</refnamediv>
5197<refsynopsisdiv>
5198 <title>Synopsis</title>
5199  <funcsynopsis><funcprototype>
5200   <funcdef>void <function>drm_mm_debug_table </function></funcdef>
5201   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5202   <paramdef>const char * <parameter>prefix</parameter></paramdef>
5203  </funcprototype></funcsynopsis>
5204</refsynopsisdiv>
5205<refsect1>
5206 <title>Arguments</title>
5207 <variablelist>
5208  <varlistentry>
5209   <term><parameter>mm</parameter></term>
5210   <listitem>
5211    <para>
5212     drm_mm allocator to dump
5213    </para>
5214   </listitem>
5215  </varlistentry>
5216  <varlistentry>
5217   <term><parameter>prefix</parameter></term>
5218   <listitem>
5219    <para>
5220     prefix to use for dumping to dmesg
5221    </para>
5222   </listitem>
5223  </varlistentry>
5224 </variablelist>
5225</refsect1>
5226</refentry>
5227
5228<refentry id="API-drm-mm-dump-table">
5229<refentryinfo>
5230 <title>LINUX</title>
5231 <productname>Kernel Hackers Manual</productname>
5232 <date>July 2017</date>
5233</refentryinfo>
5234<refmeta>
5235 <refentrytitle><phrase>drm_mm_dump_table</phrase></refentrytitle>
5236 <manvolnum>9</manvolnum>
5237 <refmiscinfo class="version">4.1.27</refmiscinfo>
5238</refmeta>
5239<refnamediv>
5240 <refname>drm_mm_dump_table</refname>
5241 <refpurpose>
5242     dump allocator state to a seq_file
5243 </refpurpose>
5244</refnamediv>
5245<refsynopsisdiv>
5246 <title>Synopsis</title>
5247  <funcsynopsis><funcprototype>
5248   <funcdef>int <function>drm_mm_dump_table </function></funcdef>
5249   <paramdef>struct seq_file * <parameter>m</parameter></paramdef>
5250   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5251  </funcprototype></funcsynopsis>
5252</refsynopsisdiv>
5253<refsect1>
5254 <title>Arguments</title>
5255 <variablelist>
5256  <varlistentry>
5257   <term><parameter>m</parameter></term>
5258   <listitem>
5259    <para>
5260     seq_file to dump to
5261    </para>
5262   </listitem>
5263  </varlistentry>
5264  <varlistentry>
5265   <term><parameter>mm</parameter></term>
5266   <listitem>
5267    <para>
5268     drm_mm allocator to dump
5269    </para>
5270   </listitem>
5271  </varlistentry>
5272 </variablelist>
5273</refsect1>
5274</refentry>
5275
5276<!-- include/drm/drm_mm.h -->
5277<refentry id="API-drm-mm-node-allocated">
5278<refentryinfo>
5279 <title>LINUX</title>
5280 <productname>Kernel Hackers Manual</productname>
5281 <date>July 2017</date>
5282</refentryinfo>
5283<refmeta>
5284 <refentrytitle><phrase>drm_mm_node_allocated</phrase></refentrytitle>
5285 <manvolnum>9</manvolnum>
5286 <refmiscinfo class="version">4.1.27</refmiscinfo>
5287</refmeta>
5288<refnamediv>
5289 <refname>drm_mm_node_allocated</refname>
5290 <refpurpose>
5291  checks whether a node is allocated
5292 </refpurpose>
5293</refnamediv>
5294<refsynopsisdiv>
5295 <title>Synopsis</title>
5296  <funcsynopsis><funcprototype>
5297   <funcdef>bool <function>drm_mm_node_allocated </function></funcdef>
5298   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
5299  </funcprototype></funcsynopsis>
5300</refsynopsisdiv>
5301<refsect1>
5302 <title>Arguments</title>
5303 <variablelist>
5304  <varlistentry>
5305   <term><parameter>node</parameter></term>
5306   <listitem>
5307    <para>
5308     drm_mm_node to check
5309    </para>
5310   </listitem>
5311  </varlistentry>
5312 </variablelist>
5313</refsect1>
5314<refsect1>
5315<title>Description</title>
5316<para>
5317   Drivers should use this helpers for proper encapusulation of drm_mm
5318   internals.
5319</para>
5320</refsect1>
5321<refsect1>
5322<title>Returns</title>
5323<para>
5324   True if the <parameter>node</parameter> is allocated.
5325</para>
5326</refsect1>
5327</refentry>
5328
5329<refentry id="API-drm-mm-initialized">
5330<refentryinfo>
5331 <title>LINUX</title>
5332 <productname>Kernel Hackers Manual</productname>
5333 <date>July 2017</date>
5334</refentryinfo>
5335<refmeta>
5336 <refentrytitle><phrase>drm_mm_initialized</phrase></refentrytitle>
5337 <manvolnum>9</manvolnum>
5338 <refmiscinfo class="version">4.1.27</refmiscinfo>
5339</refmeta>
5340<refnamediv>
5341 <refname>drm_mm_initialized</refname>
5342 <refpurpose>
5343     checks whether an allocator is initialized
5344 </refpurpose>
5345</refnamediv>
5346<refsynopsisdiv>
5347 <title>Synopsis</title>
5348  <funcsynopsis><funcprototype>
5349   <funcdef>bool <function>drm_mm_initialized </function></funcdef>
5350   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5351  </funcprototype></funcsynopsis>
5352</refsynopsisdiv>
5353<refsect1>
5354 <title>Arguments</title>
5355 <variablelist>
5356  <varlistentry>
5357   <term><parameter>mm</parameter></term>
5358   <listitem>
5359    <para>
5360     drm_mm to check
5361    </para>
5362   </listitem>
5363  </varlistentry>
5364 </variablelist>
5365</refsect1>
5366<refsect1>
5367<title>Description</title>
5368<para>
5369   Drivers should use this helpers for proper encapusulation of drm_mm
5370   internals.
5371</para>
5372</refsect1>
5373<refsect1>
5374<title>Returns</title>
5375<para>
5376   True if the <parameter>mm</parameter> is initialized.
5377</para>
5378</refsect1>
5379</refentry>
5380
5381<refentry id="API-drm-mm-hole-node-start">
5382<refentryinfo>
5383 <title>LINUX</title>
5384 <productname>Kernel Hackers Manual</productname>
5385 <date>July 2017</date>
5386</refentryinfo>
5387<refmeta>
5388 <refentrytitle><phrase>drm_mm_hole_node_start</phrase></refentrytitle>
5389 <manvolnum>9</manvolnum>
5390 <refmiscinfo class="version">4.1.27</refmiscinfo>
5391</refmeta>
5392<refnamediv>
5393 <refname>drm_mm_hole_node_start</refname>
5394 <refpurpose>
5395     computes the start of the hole following <parameter>node</parameter>
5396 </refpurpose>
5397</refnamediv>
5398<refsynopsisdiv>
5399 <title>Synopsis</title>
5400  <funcsynopsis><funcprototype>
5401   <funcdef>u64 <function>drm_mm_hole_node_start </function></funcdef>
5402   <paramdef>struct drm_mm_node * <parameter>hole_node</parameter></paramdef>
5403  </funcprototype></funcsynopsis>
5404</refsynopsisdiv>
5405<refsect1>
5406 <title>Arguments</title>
5407 <variablelist>
5408  <varlistentry>
5409   <term><parameter>hole_node</parameter></term>
5410   <listitem>
5411    <para>
5412     drm_mm_node which implicitly tracks the following hole
5413    </para>
5414   </listitem>
5415  </varlistentry>
5416 </variablelist>
5417</refsect1>
5418<refsect1>
5419<title>Description</title>
5420<para>
5421   This is useful for driver-sepific debug dumpers. Otherwise drivers should not
5422   inspect holes themselves. Drivers must check first whether a hole indeed
5423   follows by looking at node-&gt;hole_follows.
5424</para>
5425</refsect1>
5426<refsect1>
5427<title>Returns</title>
5428<para>
5429   Start of the subsequent hole.
5430</para>
5431</refsect1>
5432</refentry>
5433
5434<refentry id="API-drm-mm-hole-node-end">
5435<refentryinfo>
5436 <title>LINUX</title>
5437 <productname>Kernel Hackers Manual</productname>
5438 <date>July 2017</date>
5439</refentryinfo>
5440<refmeta>
5441 <refentrytitle><phrase>drm_mm_hole_node_end</phrase></refentrytitle>
5442 <manvolnum>9</manvolnum>
5443 <refmiscinfo class="version">4.1.27</refmiscinfo>
5444</refmeta>
5445<refnamediv>
5446 <refname>drm_mm_hole_node_end</refname>
5447 <refpurpose>
5448     computes the end of the hole following <parameter>node</parameter>
5449 </refpurpose>
5450</refnamediv>
5451<refsynopsisdiv>
5452 <title>Synopsis</title>
5453  <funcsynopsis><funcprototype>
5454   <funcdef>u64 <function>drm_mm_hole_node_end </function></funcdef>
5455   <paramdef>struct drm_mm_node * <parameter>hole_node</parameter></paramdef>
5456  </funcprototype></funcsynopsis>
5457</refsynopsisdiv>
5458<refsect1>
5459 <title>Arguments</title>
5460 <variablelist>
5461  <varlistentry>
5462   <term><parameter>hole_node</parameter></term>
5463   <listitem>
5464    <para>
5465     drm_mm_node which implicitly tracks the following hole
5466    </para>
5467   </listitem>
5468  </varlistentry>
5469 </variablelist>
5470</refsect1>
5471<refsect1>
5472<title>Description</title>
5473<para>
5474   This is useful for driver-sepific debug dumpers. Otherwise drivers should not
5475   inspect holes themselves. Drivers must check first whether a hole indeed
5476   follows by looking at node-&gt;hole_follows.
5477</para>
5478</refsect1>
5479<refsect1>
5480<title>Returns</title>
5481<para>
5482   End of the subsequent hole.
5483</para>
5484</refsect1>
5485</refentry>
5486
5487<refentry id="API-drm-mm-for-each-node">
5488<refentryinfo>
5489 <title>LINUX</title>
5490 <productname>Kernel Hackers Manual</productname>
5491 <date>July 2017</date>
5492</refentryinfo>
5493<refmeta>
5494 <refentrytitle><phrase>drm_mm_for_each_node</phrase></refentrytitle>
5495 <manvolnum>9</manvolnum>
5496 <refmiscinfo class="version">4.1.27</refmiscinfo>
5497</refmeta>
5498<refnamediv>
5499 <refname>drm_mm_for_each_node</refname>
5500 <refpurpose>
5501     iterator to walk over all allocated nodes
5502 </refpurpose>
5503</refnamediv>
5504<refsynopsisdiv>
5505 <title>Synopsis</title>
5506  <funcsynopsis><funcprototype>
5507   <funcdef> <function>drm_mm_for_each_node </function></funcdef>
5508   <paramdef> <parameter>entry</parameter></paramdef>
5509   <paramdef> <parameter>mm</parameter></paramdef>
5510  </funcprototype></funcsynopsis>
5511</refsynopsisdiv>
5512<refsect1>
5513 <title>Arguments</title>
5514 <variablelist>
5515  <varlistentry>
5516   <term><parameter>entry</parameter></term>
5517   <listitem>
5518    <para>
5519     drm_mm_node structure to assign to in each iteration step
5520    </para>
5521   </listitem>
5522  </varlistentry>
5523  <varlistentry>
5524   <term><parameter>mm</parameter></term>
5525   <listitem>
5526    <para>
5527     drm_mm allocator to walk
5528    </para>
5529   </listitem>
5530  </varlistentry>
5531 </variablelist>
5532</refsect1>
5533<refsect1>
5534<title>Description</title>
5535<para>
5536   This iterator walks over all nodes in the range allocator. It is implemented
5537   with list_for_each, so not save against removal of elements.
5538</para>
5539</refsect1>
5540</refentry>
5541
5542<refentry id="API-drm-mm-for-each-hole">
5543<refentryinfo>
5544 <title>LINUX</title>
5545 <productname>Kernel Hackers Manual</productname>
5546 <date>July 2017</date>
5547</refentryinfo>
5548<refmeta>
5549 <refentrytitle><phrase>drm_mm_for_each_hole</phrase></refentrytitle>
5550 <manvolnum>9</manvolnum>
5551 <refmiscinfo class="version">4.1.27</refmiscinfo>
5552</refmeta>
5553<refnamediv>
5554 <refname>drm_mm_for_each_hole</refname>
5555 <refpurpose>
5556     iterator to walk over all holes
5557 </refpurpose>
5558</refnamediv>
5559<refsynopsisdiv>
5560 <title>Synopsis</title>
5561  <funcsynopsis><funcprototype>
5562   <funcdef> <function>drm_mm_for_each_hole </function></funcdef>
5563   <paramdef> <parameter>entry</parameter></paramdef>
5564   <paramdef> <parameter>mm</parameter></paramdef>
5565   <paramdef> <parameter>hole_start</parameter></paramdef>
5566   <paramdef> <parameter>hole_end</parameter></paramdef>
5567  </funcprototype></funcsynopsis>
5568</refsynopsisdiv>
5569<refsect1>
5570 <title>Arguments</title>
5571 <variablelist>
5572  <varlistentry>
5573   <term><parameter>entry</parameter></term>
5574   <listitem>
5575    <para>
5576     drm_mm_node used internally to track progress
5577    </para>
5578   </listitem>
5579  </varlistentry>
5580  <varlistentry>
5581   <term><parameter>mm</parameter></term>
5582   <listitem>
5583    <para>
5584     drm_mm allocator to walk
5585    </para>
5586   </listitem>
5587  </varlistentry>
5588  <varlistentry>
5589   <term><parameter>hole_start</parameter></term>
5590   <listitem>
5591    <para>
5592     ulong variable to assign the hole start to on each iteration
5593    </para>
5594   </listitem>
5595  </varlistentry>
5596  <varlistentry>
5597   <term><parameter>hole_end</parameter></term>
5598   <listitem>
5599    <para>
5600     ulong variable to assign the hole end to on each iteration
5601    </para>
5602   </listitem>
5603  </varlistentry>
5604 </variablelist>
5605</refsect1>
5606<refsect1>
5607<title>Description</title>
5608<para>
5609   This iterator walks over all holes in the range allocator. It is implemented
5610   with list_for_each, so not save against removal of elements. <parameter>entry</parameter> is used
5611   internally and will not reflect a real drm_mm_node for the very first hole.
5612   Hence users of this iterator may not access it.
5613</para>
5614</refsect1>
5615<refsect1>
5616<title>Implementation Note</title>
5617<para>
5618   We need to inline list_for_each_entry in order to be able to set hole_start
5619   and hole_end on each iteration while keeping the macro sane.
5620   </para><para>
5621
5622   The __drm_mm_for_each_hole version is similar, but with added support for
5623   going backwards.
5624</para>
5625</refsect1>
5626</refentry>
5627
5628<refentry id="API-drm-mm-insert-node">
5629<refentryinfo>
5630 <title>LINUX</title>
5631 <productname>Kernel Hackers Manual</productname>
5632 <date>July 2017</date>
5633</refentryinfo>
5634<refmeta>
5635 <refentrytitle><phrase>drm_mm_insert_node</phrase></refentrytitle>
5636 <manvolnum>9</manvolnum>
5637 <refmiscinfo class="version">4.1.27</refmiscinfo>
5638</refmeta>
5639<refnamediv>
5640 <refname>drm_mm_insert_node</refname>
5641 <refpurpose>
5642     search for space and insert <parameter>node</parameter>
5643 </refpurpose>
5644</refnamediv>
5645<refsynopsisdiv>
5646 <title>Synopsis</title>
5647  <funcsynopsis><funcprototype>
5648   <funcdef>int <function>drm_mm_insert_node </function></funcdef>
5649   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5650   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
5651   <paramdef>u64 <parameter>size</parameter></paramdef>
5652   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
5653   <paramdef>enum drm_mm_search_flags <parameter>flags</parameter></paramdef>
5654  </funcprototype></funcsynopsis>
5655</refsynopsisdiv>
5656<refsect1>
5657 <title>Arguments</title>
5658 <variablelist>
5659  <varlistentry>
5660   <term><parameter>mm</parameter></term>
5661   <listitem>
5662    <para>
5663     drm_mm to allocate from
5664    </para>
5665   </listitem>
5666  </varlistentry>
5667  <varlistentry>
5668   <term><parameter>node</parameter></term>
5669   <listitem>
5670    <para>
5671     preallocate node to insert
5672    </para>
5673   </listitem>
5674  </varlistentry>
5675  <varlistentry>
5676   <term><parameter>size</parameter></term>
5677   <listitem>
5678    <para>
5679     size of the allocation
5680    </para>
5681   </listitem>
5682  </varlistentry>
5683  <varlistentry>
5684   <term><parameter>alignment</parameter></term>
5685   <listitem>
5686    <para>
5687     alignment of the allocation
5688    </para>
5689   </listitem>
5690  </varlistentry>
5691  <varlistentry>
5692   <term><parameter>flags</parameter></term>
5693   <listitem>
5694    <para>
5695     flags to fine-tune the allocation
5696    </para>
5697   </listitem>
5698  </varlistentry>
5699 </variablelist>
5700</refsect1>
5701<refsect1>
5702<title>Description</title>
5703<para>
5704   This is a simplified version of <function>drm_mm_insert_node_generic</function> with <parameter>color</parameter> set
5705   to 0.
5706   </para><para>
5707
5708   The preallocated node must be cleared to 0.
5709</para>
5710</refsect1>
5711<refsect1>
5712<title>Returns</title>
5713<para>
5714   0 on success, -ENOSPC if there's no suitable hole.
5715</para>
5716</refsect1>
5717</refentry>
5718
5719<refentry id="API-drm-mm-insert-node-in-range">
5720<refentryinfo>
5721 <title>LINUX</title>
5722 <productname>Kernel Hackers Manual</productname>
5723 <date>July 2017</date>
5724</refentryinfo>
5725<refmeta>
5726 <refentrytitle><phrase>drm_mm_insert_node_in_range</phrase></refentrytitle>
5727 <manvolnum>9</manvolnum>
5728 <refmiscinfo class="version">4.1.27</refmiscinfo>
5729</refmeta>
5730<refnamediv>
5731 <refname>drm_mm_insert_node_in_range</refname>
5732 <refpurpose>
5733     ranged search for space and insert <parameter>node</parameter>
5734 </refpurpose>
5735</refnamediv>
5736<refsynopsisdiv>
5737 <title>Synopsis</title>
5738  <funcsynopsis><funcprototype>
5739   <funcdef>int <function>drm_mm_insert_node_in_range </function></funcdef>
5740   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
5741   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
5742   <paramdef>u64 <parameter>size</parameter></paramdef>
5743   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
5744   <paramdef>u64 <parameter>start</parameter></paramdef>
5745   <paramdef>u64 <parameter>end</parameter></paramdef>
5746   <paramdef>enum drm_mm_search_flags <parameter>flags</parameter></paramdef>
5747  </funcprototype></funcsynopsis>
5748</refsynopsisdiv>
5749<refsect1>
5750 <title>Arguments</title>
5751 <variablelist>
5752  <varlistentry>
5753   <term><parameter>mm</parameter></term>
5754   <listitem>
5755    <para>
5756     drm_mm to allocate from
5757    </para>
5758   </listitem>
5759  </varlistentry>
5760  <varlistentry>
5761   <term><parameter>node</parameter></term>
5762   <listitem>
5763    <para>
5764     preallocate node to insert
5765    </para>
5766   </listitem>
5767  </varlistentry>
5768  <varlistentry>
5769   <term><parameter>size</parameter></term>
5770   <listitem>
5771    <para>
5772     size of the allocation
5773    </para>
5774   </listitem>
5775  </varlistentry>
5776  <varlistentry>
5777   <term><parameter>alignment</parameter></term>
5778   <listitem>
5779    <para>
5780     alignment of the allocation
5781    </para>
5782   </listitem>
5783  </varlistentry>
5784  <varlistentry>
5785   <term><parameter>start</parameter></term>
5786   <listitem>
5787    <para>
5788     start of the allowed range for this node
5789    </para>
5790   </listitem>
5791  </varlistentry>
5792  <varlistentry>
5793   <term><parameter>end</parameter></term>
5794   <listitem>
5795    <para>
5796     end of the allowed range for this node
5797    </para>
5798   </listitem>
5799  </varlistentry>
5800  <varlistentry>
5801   <term><parameter>flags</parameter></term>
5802   <listitem>
5803    <para>
5804     flags to fine-tune the allocation
5805    </para>
5806   </listitem>
5807  </varlistentry>
5808 </variablelist>
5809</refsect1>
5810<refsect1>
5811<title>Description</title>
5812<para>
5813   This is a simplified version of <function>drm_mm_insert_node_in_range_generic</function> with
5814   <parameter>color</parameter> set to 0.
5815   </para><para>
5816
5817   The preallocated node must be cleared to 0.
5818</para>
5819</refsect1>
5820<refsect1>
5821<title>Returns</title>
5822<para>
5823   0 on success, -ENOSPC if there's no suitable hole.
5824</para>
5825</refsect1>
5826</refentry>
5827
5828    </sect2>
5829    <sect2>
5830      <title>CMA Helper Functions Reference</title>
5831<para>
5832   </para><para>
5833   The Contiguous Memory Allocator reserves a pool of memory at early boot
5834   that is used to service requests for large blocks of contiguous memory.
5835   </para><para>
5836   The DRM GEM/CMA helpers use this allocator as a means to provide buffer
5837   objects that are physically contiguous in memory. This is useful for
5838   display drivers that are unable to map scattered buffers via an IOMMU.
5839</para>
5840
5841<!-- drivers/gpu/drm/drm_gem_cma_helper.c -->
5842<refentry id="API-drm-gem-cma-create">
5843<refentryinfo>
5844 <title>LINUX</title>
5845 <productname>Kernel Hackers Manual</productname>
5846 <date>July 2017</date>
5847</refentryinfo>
5848<refmeta>
5849 <refentrytitle><phrase>drm_gem_cma_create</phrase></refentrytitle>
5850 <manvolnum>9</manvolnum>
5851 <refmiscinfo class="version">4.1.27</refmiscinfo>
5852</refmeta>
5853<refnamediv>
5854 <refname>drm_gem_cma_create</refname>
5855 <refpurpose>
5856  allocate an object with the given size
5857 </refpurpose>
5858</refnamediv>
5859<refsynopsisdiv>
5860 <title>Synopsis</title>
5861  <funcsynopsis><funcprototype>
5862   <funcdef>struct drm_gem_cma_object * <function>drm_gem_cma_create </function></funcdef>
5863   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
5864   <paramdef>size_t <parameter>size</parameter></paramdef>
5865  </funcprototype></funcsynopsis>
5866</refsynopsisdiv>
5867<refsect1>
5868 <title>Arguments</title>
5869 <variablelist>
5870  <varlistentry>
5871   <term><parameter>drm</parameter></term>
5872   <listitem>
5873    <para>
5874     DRM device
5875    </para>
5876   </listitem>
5877  </varlistentry>
5878  <varlistentry>
5879   <term><parameter>size</parameter></term>
5880   <listitem>
5881    <para>
5882     size of the object to allocate
5883    </para>
5884   </listitem>
5885  </varlistentry>
5886 </variablelist>
5887</refsect1>
5888<refsect1>
5889<title>Description</title>
5890<para>
5891   This function creates a CMA GEM object and allocates a contiguous chunk of
5892   memory as backing store. The backing memory has the writecombine attribute
5893   set.
5894</para>
5895</refsect1>
5896<refsect1>
5897<title>Returns</title>
5898<para>
5899   A struct drm_gem_cma_object * on success or an <function>ERR_PTR</function>-encoded negative
5900   error code on failure.
5901</para>
5902</refsect1>
5903</refentry>
5904
5905<refentry id="API-drm-gem-cma-free-object">
5906<refentryinfo>
5907 <title>LINUX</title>
5908 <productname>Kernel Hackers Manual</productname>
5909 <date>July 2017</date>
5910</refentryinfo>
5911<refmeta>
5912 <refentrytitle><phrase>drm_gem_cma_free_object</phrase></refentrytitle>
5913 <manvolnum>9</manvolnum>
5914 <refmiscinfo class="version">4.1.27</refmiscinfo>
5915</refmeta>
5916<refnamediv>
5917 <refname>drm_gem_cma_free_object</refname>
5918 <refpurpose>
5919     free resources associated with a CMA GEM object
5920 </refpurpose>
5921</refnamediv>
5922<refsynopsisdiv>
5923 <title>Synopsis</title>
5924  <funcsynopsis><funcprototype>
5925   <funcdef>void <function>drm_gem_cma_free_object </function></funcdef>
5926   <paramdef>struct drm_gem_object * <parameter>gem_obj</parameter></paramdef>
5927  </funcprototype></funcsynopsis>
5928</refsynopsisdiv>
5929<refsect1>
5930 <title>Arguments</title>
5931 <variablelist>
5932  <varlistentry>
5933   <term><parameter>gem_obj</parameter></term>
5934   <listitem>
5935    <para>
5936     GEM object to free
5937    </para>
5938   </listitem>
5939  </varlistentry>
5940 </variablelist>
5941</refsect1>
5942<refsect1>
5943<title>Description</title>
5944<para>
5945   This function frees the backing memory of the CMA GEM object, cleans up the
5946   GEM object state and frees the memory used to store the object itself.
5947   Drivers using the CMA helpers should set this as their DRM driver's
5948   -&gt;<function>gem_free_object</function> callback.
5949</para>
5950</refsect1>
5951</refentry>
5952
5953<refentry id="API-drm-gem-cma-dumb-create-internal">
5954<refentryinfo>
5955 <title>LINUX</title>
5956 <productname>Kernel Hackers Manual</productname>
5957 <date>July 2017</date>
5958</refentryinfo>
5959<refmeta>
5960 <refentrytitle><phrase>drm_gem_cma_dumb_create_internal</phrase></refentrytitle>
5961 <manvolnum>9</manvolnum>
5962 <refmiscinfo class="version">4.1.27</refmiscinfo>
5963</refmeta>
5964<refnamediv>
5965 <refname>drm_gem_cma_dumb_create_internal</refname>
5966 <refpurpose>
5967     create a dumb buffer object
5968 </refpurpose>
5969</refnamediv>
5970<refsynopsisdiv>
5971 <title>Synopsis</title>
5972  <funcsynopsis><funcprototype>
5973   <funcdef>int <function>drm_gem_cma_dumb_create_internal </function></funcdef>
5974   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
5975   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
5976   <paramdef>struct drm_mode_create_dumb * <parameter>args</parameter></paramdef>
5977  </funcprototype></funcsynopsis>
5978</refsynopsisdiv>
5979<refsect1>
5980 <title>Arguments</title>
5981 <variablelist>
5982  <varlistentry>
5983   <term><parameter>file_priv</parameter></term>
5984   <listitem>
5985    <para>
5986     DRM file-private structure to create the dumb buffer for
5987    </para>
5988   </listitem>
5989  </varlistentry>
5990  <varlistentry>
5991   <term><parameter>drm</parameter></term>
5992   <listitem>
5993    <para>
5994     DRM device
5995    </para>
5996   </listitem>
5997  </varlistentry>
5998  <varlistentry>
5999   <term><parameter>args</parameter></term>
6000   <listitem>
6001    <para>
6002     IOCTL data
6003    </para>
6004   </listitem>
6005  </varlistentry>
6006 </variablelist>
6007</refsect1>
6008<refsect1>
6009<title>Description</title>
6010<para>
6011   This aligns the pitch and size arguments to the minimum required. This is
6012   an internal helper that can be wrapped by a driver to account for hardware
6013   with more specific alignment requirements. It should not be used directly
6014   as the -&gt;<function>dumb_create</function> callback in a DRM driver.
6015</para>
6016</refsect1>
6017<refsect1>
6018<title>Returns</title>
6019<para>
6020   0 on success or a negative error code on failure.
6021</para>
6022</refsect1>
6023</refentry>
6024
6025<refentry id="API-drm-gem-cma-dumb-create">
6026<refentryinfo>
6027 <title>LINUX</title>
6028 <productname>Kernel Hackers Manual</productname>
6029 <date>July 2017</date>
6030</refentryinfo>
6031<refmeta>
6032 <refentrytitle><phrase>drm_gem_cma_dumb_create</phrase></refentrytitle>
6033 <manvolnum>9</manvolnum>
6034 <refmiscinfo class="version">4.1.27</refmiscinfo>
6035</refmeta>
6036<refnamediv>
6037 <refname>drm_gem_cma_dumb_create</refname>
6038 <refpurpose>
6039     create a dumb buffer object
6040 </refpurpose>
6041</refnamediv>
6042<refsynopsisdiv>
6043 <title>Synopsis</title>
6044  <funcsynopsis><funcprototype>
6045   <funcdef>int <function>drm_gem_cma_dumb_create </function></funcdef>
6046   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
6047   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
6048   <paramdef>struct drm_mode_create_dumb * <parameter>args</parameter></paramdef>
6049  </funcprototype></funcsynopsis>
6050</refsynopsisdiv>
6051<refsect1>
6052 <title>Arguments</title>
6053 <variablelist>
6054  <varlistentry>
6055   <term><parameter>file_priv</parameter></term>
6056   <listitem>
6057    <para>
6058     DRM file-private structure to create the dumb buffer for
6059    </para>
6060   </listitem>
6061  </varlistentry>
6062  <varlistentry>
6063   <term><parameter>drm</parameter></term>
6064   <listitem>
6065    <para>
6066     DRM device
6067    </para>
6068   </listitem>
6069  </varlistentry>
6070  <varlistentry>
6071   <term><parameter>args</parameter></term>
6072   <listitem>
6073    <para>
6074     IOCTL data
6075    </para>
6076   </listitem>
6077  </varlistentry>
6078 </variablelist>
6079</refsect1>
6080<refsect1>
6081<title>Description</title>
6082<para>
6083   This function computes the pitch of the dumb buffer and rounds it up to an
6084   integer number of bytes per pixel. Drivers for hardware that doesn't have
6085   any additional restrictions on the pitch can directly use this function as
6086   their -&gt;<function>dumb_create</function> callback.
6087   </para><para>
6088
6089   For hardware with additional restrictions, drivers can adjust the fields
6090   set up by userspace and pass the IOCTL data along to the
6091   <function>drm_gem_cma_dumb_create_internal</function> function.
6092</para>
6093</refsect1>
6094<refsect1>
6095<title>Returns</title>
6096<para>
6097   0 on success or a negative error code on failure.
6098</para>
6099</refsect1>
6100</refentry>
6101
6102<refentry id="API-drm-gem-cma-dumb-map-offset">
6103<refentryinfo>
6104 <title>LINUX</title>
6105 <productname>Kernel Hackers Manual</productname>
6106 <date>July 2017</date>
6107</refentryinfo>
6108<refmeta>
6109 <refentrytitle><phrase>drm_gem_cma_dumb_map_offset</phrase></refentrytitle>
6110 <manvolnum>9</manvolnum>
6111 <refmiscinfo class="version">4.1.27</refmiscinfo>
6112</refmeta>
6113<refnamediv>
6114 <refname>drm_gem_cma_dumb_map_offset</refname>
6115 <refpurpose>
6116     return the fake mmap offset for a CMA GEM object
6117 </refpurpose>
6118</refnamediv>
6119<refsynopsisdiv>
6120 <title>Synopsis</title>
6121  <funcsynopsis><funcprototype>
6122   <funcdef>int <function>drm_gem_cma_dumb_map_offset </function></funcdef>
6123   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
6124   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
6125   <paramdef>u32 <parameter>handle</parameter></paramdef>
6126   <paramdef>u64 * <parameter>offset</parameter></paramdef>
6127  </funcprototype></funcsynopsis>
6128</refsynopsisdiv>
6129<refsect1>
6130 <title>Arguments</title>
6131 <variablelist>
6132  <varlistentry>
6133   <term><parameter>file_priv</parameter></term>
6134   <listitem>
6135    <para>
6136     DRM file-private structure containing the GEM object
6137    </para>
6138   </listitem>
6139  </varlistentry>
6140  <varlistentry>
6141   <term><parameter>drm</parameter></term>
6142   <listitem>
6143    <para>
6144     DRM device
6145    </para>
6146   </listitem>
6147  </varlistentry>
6148  <varlistentry>
6149   <term><parameter>handle</parameter></term>
6150   <listitem>
6151    <para>
6152     GEM object handle
6153    </para>
6154   </listitem>
6155  </varlistentry>
6156  <varlistentry>
6157   <term><parameter>offset</parameter></term>
6158   <listitem>
6159    <para>
6160     return location for the fake mmap offset
6161    </para>
6162   </listitem>
6163  </varlistentry>
6164 </variablelist>
6165</refsect1>
6166<refsect1>
6167<title>Description</title>
6168<para>
6169   This function look up an object by its handle and returns the fake mmap
6170   offset associated with it. Drivers using the CMA helpers should set this
6171   as their DRM driver's -&gt;<function>dumb_map_offset</function> callback.
6172</para>
6173</refsect1>
6174<refsect1>
6175<title>Returns</title>
6176<para>
6177   0 on success or a negative error code on failure.
6178</para>
6179</refsect1>
6180</refentry>
6181
6182<refentry id="API-drm-gem-cma-mmap">
6183<refentryinfo>
6184 <title>LINUX</title>
6185 <productname>Kernel Hackers Manual</productname>
6186 <date>July 2017</date>
6187</refentryinfo>
6188<refmeta>
6189 <refentrytitle><phrase>drm_gem_cma_mmap</phrase></refentrytitle>
6190 <manvolnum>9</manvolnum>
6191 <refmiscinfo class="version">4.1.27</refmiscinfo>
6192</refmeta>
6193<refnamediv>
6194 <refname>drm_gem_cma_mmap</refname>
6195 <refpurpose>
6196     memory-map a CMA GEM object
6197 </refpurpose>
6198</refnamediv>
6199<refsynopsisdiv>
6200 <title>Synopsis</title>
6201  <funcsynopsis><funcprototype>
6202   <funcdef>int <function>drm_gem_cma_mmap </function></funcdef>
6203   <paramdef>struct file * <parameter>filp</parameter></paramdef>
6204   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
6205  </funcprototype></funcsynopsis>
6206</refsynopsisdiv>
6207<refsect1>
6208 <title>Arguments</title>
6209 <variablelist>
6210  <varlistentry>
6211   <term><parameter>filp</parameter></term>
6212   <listitem>
6213    <para>
6214     file object
6215    </para>
6216   </listitem>
6217  </varlistentry>
6218  <varlistentry>
6219   <term><parameter>vma</parameter></term>
6220   <listitem>
6221    <para>
6222     VMA for the area to be mapped
6223    </para>
6224   </listitem>
6225  </varlistentry>
6226 </variablelist>
6227</refsect1>
6228<refsect1>
6229<title>Description</title>
6230<para>
6231   This function implements an augmented version of the GEM DRM file mmap
6232</para>
6233</refsect1>
6234<refsect1>
6235<title>operation for CMA objects</title>
6236<para>
6237   In addition to the usual GEM VMA setup it
6238   immediately faults in the entire object instead of using on-demaind
6239   faulting. Drivers which employ the CMA helpers should use this function
6240   as their -&gt;<function>mmap</function> handler in the DRM device file's file_operations
6241   structure.
6242</para>
6243</refsect1>
6244<refsect1>
6245<title>Returns</title>
6246<para>
6247   0 on success or a negative error code on failure.
6248</para>
6249</refsect1>
6250</refentry>
6251
6252<refentry id="API-drm-gem-cma-describe">
6253<refentryinfo>
6254 <title>LINUX</title>
6255 <productname>Kernel Hackers Manual</productname>
6256 <date>July 2017</date>
6257</refentryinfo>
6258<refmeta>
6259 <refentrytitle><phrase>drm_gem_cma_describe</phrase></refentrytitle>
6260 <manvolnum>9</manvolnum>
6261 <refmiscinfo class="version">4.1.27</refmiscinfo>
6262</refmeta>
6263<refnamediv>
6264 <refname>drm_gem_cma_describe</refname>
6265 <refpurpose>
6266     describe a CMA GEM object for debugfs
6267 </refpurpose>
6268</refnamediv>
6269<refsynopsisdiv>
6270 <title>Synopsis</title>
6271  <funcsynopsis><funcprototype>
6272   <funcdef>void <function>drm_gem_cma_describe </function></funcdef>
6273   <paramdef>struct drm_gem_cma_object * <parameter>cma_obj</parameter></paramdef>
6274   <paramdef>struct seq_file * <parameter>m</parameter></paramdef>
6275  </funcprototype></funcsynopsis>
6276</refsynopsisdiv>
6277<refsect1>
6278 <title>Arguments</title>
6279 <variablelist>
6280  <varlistentry>
6281   <term><parameter>cma_obj</parameter></term>
6282   <listitem>
6283    <para>
6284     CMA GEM object
6285    </para>
6286   </listitem>
6287  </varlistentry>
6288  <varlistentry>
6289   <term><parameter>m</parameter></term>
6290   <listitem>
6291    <para>
6292     debugfs file handle
6293    </para>
6294   </listitem>
6295  </varlistentry>
6296 </variablelist>
6297</refsect1>
6298<refsect1>
6299<title>Description</title>
6300<para>
6301   This function can be used to dump a human-readable representation of the
6302   CMA GEM object into a synthetic file.
6303</para>
6304</refsect1>
6305</refentry>
6306
6307<refentry id="API-drm-gem-cma-prime-get-sg-table">
6308<refentryinfo>
6309 <title>LINUX</title>
6310 <productname>Kernel Hackers Manual</productname>
6311 <date>July 2017</date>
6312</refentryinfo>
6313<refmeta>
6314 <refentrytitle><phrase>drm_gem_cma_prime_get_sg_table</phrase></refentrytitle>
6315 <manvolnum>9</manvolnum>
6316 <refmiscinfo class="version">4.1.27</refmiscinfo>
6317</refmeta>
6318<refnamediv>
6319 <refname>drm_gem_cma_prime_get_sg_table</refname>
6320 <refpurpose>
6321     provide a scatter/gather table of pinned pages for a CMA GEM object
6322 </refpurpose>
6323</refnamediv>
6324<refsynopsisdiv>
6325 <title>Synopsis</title>
6326  <funcsynopsis><funcprototype>
6327   <funcdef>struct sg_table * <function>drm_gem_cma_prime_get_sg_table </function></funcdef>
6328   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
6329  </funcprototype></funcsynopsis>
6330</refsynopsisdiv>
6331<refsect1>
6332 <title>Arguments</title>
6333 <variablelist>
6334  <varlistentry>
6335   <term><parameter>obj</parameter></term>
6336   <listitem>
6337    <para>
6338     GEM object
6339    </para>
6340   </listitem>
6341  </varlistentry>
6342 </variablelist>
6343</refsect1>
6344<refsect1>
6345<title>Description</title>
6346<para>
6347   This function exports a scatter/gather table suitable for PRIME usage by
6348   calling the standard DMA mapping API. Drivers using the CMA helpers should
6349   set this as their DRM driver's -&gt;<function>gem_prime_get_sg_table</function> callback.
6350</para>
6351</refsect1>
6352<refsect1>
6353<title>Returns</title>
6354<para>
6355   A pointer to the scatter/gather table of pinned pages or NULL on failure.
6356</para>
6357</refsect1>
6358</refentry>
6359
6360<refentry id="API-drm-gem-cma-prime-import-sg-table">
6361<refentryinfo>
6362 <title>LINUX</title>
6363 <productname>Kernel Hackers Manual</productname>
6364 <date>July 2017</date>
6365</refentryinfo>
6366<refmeta>
6367 <refentrytitle><phrase>drm_gem_cma_prime_import_sg_table</phrase></refentrytitle>
6368 <manvolnum>9</manvolnum>
6369 <refmiscinfo class="version">4.1.27</refmiscinfo>
6370</refmeta>
6371<refnamediv>
6372 <refname>drm_gem_cma_prime_import_sg_table</refname>
6373 <refpurpose>
6374     produce a CMA GEM object from another driver's scatter/gather table of pinned pages
6375 </refpurpose>
6376</refnamediv>
6377<refsynopsisdiv>
6378 <title>Synopsis</title>
6379  <funcsynopsis><funcprototype>
6380   <funcdef>struct drm_gem_object * <function>drm_gem_cma_prime_import_sg_table </function></funcdef>
6381   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
6382   <paramdef>struct dma_buf_attachment * <parameter>attach</parameter></paramdef>
6383   <paramdef>struct sg_table * <parameter>sgt</parameter></paramdef>
6384  </funcprototype></funcsynopsis>
6385</refsynopsisdiv>
6386<refsect1>
6387 <title>Arguments</title>
6388 <variablelist>
6389  <varlistentry>
6390   <term><parameter>dev</parameter></term>
6391   <listitem>
6392    <para>
6393     device to import into
6394    </para>
6395   </listitem>
6396  </varlistentry>
6397  <varlistentry>
6398   <term><parameter>attach</parameter></term>
6399   <listitem>
6400    <para>
6401     DMA-BUF attachment
6402    </para>
6403   </listitem>
6404  </varlistentry>
6405  <varlistentry>
6406   <term><parameter>sgt</parameter></term>
6407   <listitem>
6408    <para>
6409     scatter/gather table of pinned pages
6410    </para>
6411   </listitem>
6412  </varlistentry>
6413 </variablelist>
6414</refsect1>
6415<refsect1>
6416<title>Description</title>
6417<para>
6418   This function imports a scatter/gather table exported via DMA-BUF by
6419   another driver. Imported buffers must be physically contiguous in memory
6420   (i.e. the scatter/gather table must contain a single entry). Drivers that
6421   use the CMA helpers should set this as their DRM driver's
6422   -&gt;<function>gem_prime_import_sg_table</function> callback.
6423</para>
6424</refsect1>
6425<refsect1>
6426<title>Returns</title>
6427<para>
6428   A pointer to a newly created GEM object or an ERR_PTR-encoded negative
6429   error code on failure.
6430</para>
6431</refsect1>
6432</refentry>
6433
6434<refentry id="API-drm-gem-cma-prime-mmap">
6435<refentryinfo>
6436 <title>LINUX</title>
6437 <productname>Kernel Hackers Manual</productname>
6438 <date>July 2017</date>
6439</refentryinfo>
6440<refmeta>
6441 <refentrytitle><phrase>drm_gem_cma_prime_mmap</phrase></refentrytitle>
6442 <manvolnum>9</manvolnum>
6443 <refmiscinfo class="version">4.1.27</refmiscinfo>
6444</refmeta>
6445<refnamediv>
6446 <refname>drm_gem_cma_prime_mmap</refname>
6447 <refpurpose>
6448     memory-map an exported CMA GEM object
6449 </refpurpose>
6450</refnamediv>
6451<refsynopsisdiv>
6452 <title>Synopsis</title>
6453  <funcsynopsis><funcprototype>
6454   <funcdef>int <function>drm_gem_cma_prime_mmap </function></funcdef>
6455   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
6456   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
6457  </funcprototype></funcsynopsis>
6458</refsynopsisdiv>
6459<refsect1>
6460 <title>Arguments</title>
6461 <variablelist>
6462  <varlistentry>
6463   <term><parameter>obj</parameter></term>
6464   <listitem>
6465    <para>
6466     GEM object
6467    </para>
6468   </listitem>
6469  </varlistentry>
6470  <varlistentry>
6471   <term><parameter>vma</parameter></term>
6472   <listitem>
6473    <para>
6474     VMA for the area to be mapped
6475    </para>
6476   </listitem>
6477  </varlistentry>
6478 </variablelist>
6479</refsect1>
6480<refsect1>
6481<title>Description</title>
6482<para>
6483   This function maps a buffer imported via DRM PRIME into a userspace
6484   process's address space. Drivers that use the CMA helpers should set this
6485   as their DRM driver's -&gt;<function>gem_prime_mmap</function> callback.
6486</para>
6487</refsect1>
6488<refsect1>
6489<title>Returns</title>
6490<para>
6491   0 on success or a negative error code on failure.
6492</para>
6493</refsect1>
6494</refentry>
6495
6496<refentry id="API-drm-gem-cma-prime-vmap">
6497<refentryinfo>
6498 <title>LINUX</title>
6499 <productname>Kernel Hackers Manual</productname>
6500 <date>July 2017</date>
6501</refentryinfo>
6502<refmeta>
6503 <refentrytitle><phrase>drm_gem_cma_prime_vmap</phrase></refentrytitle>
6504 <manvolnum>9</manvolnum>
6505 <refmiscinfo class="version">4.1.27</refmiscinfo>
6506</refmeta>
6507<refnamediv>
6508 <refname>drm_gem_cma_prime_vmap</refname>
6509 <refpurpose>
6510     map a CMA GEM object into the kernel's virtual address space
6511 </refpurpose>
6512</refnamediv>
6513<refsynopsisdiv>
6514 <title>Synopsis</title>
6515  <funcsynopsis><funcprototype>
6516   <funcdef>void * <function>drm_gem_cma_prime_vmap </function></funcdef>
6517   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
6518  </funcprototype></funcsynopsis>
6519</refsynopsisdiv>
6520<refsect1>
6521 <title>Arguments</title>
6522 <variablelist>
6523  <varlistentry>
6524   <term><parameter>obj</parameter></term>
6525   <listitem>
6526    <para>
6527     GEM object
6528    </para>
6529   </listitem>
6530  </varlistentry>
6531 </variablelist>
6532</refsect1>
6533<refsect1>
6534<title>Description</title>
6535<para>
6536   This function maps a buffer exported via DRM PRIME into the kernel's
6537   virtual address space. Since the CMA buffers are already mapped into the
6538   kernel virtual address space this simply returns the cached virtual
6539   address. Drivers using the CMA helpers should set this as their DRM
6540   driver's -&gt;<function>gem_prime_vmap</function> callback.
6541</para>
6542</refsect1>
6543<refsect1>
6544<title>Returns</title>
6545<para>
6546   The kernel virtual address of the CMA GEM object's backing store.
6547</para>
6548</refsect1>
6549</refentry>
6550
6551<refentry id="API-drm-gem-cma-prime-vunmap">
6552<refentryinfo>
6553 <title>LINUX</title>
6554 <productname>Kernel Hackers Manual</productname>
6555 <date>July 2017</date>
6556</refentryinfo>
6557<refmeta>
6558 <refentrytitle><phrase>drm_gem_cma_prime_vunmap</phrase></refentrytitle>
6559 <manvolnum>9</manvolnum>
6560 <refmiscinfo class="version">4.1.27</refmiscinfo>
6561</refmeta>
6562<refnamediv>
6563 <refname>drm_gem_cma_prime_vunmap</refname>
6564 <refpurpose>
6565     unmap a CMA GEM object from the kernel's virtual address space
6566 </refpurpose>
6567</refnamediv>
6568<refsynopsisdiv>
6569 <title>Synopsis</title>
6570  <funcsynopsis><funcprototype>
6571   <funcdef>void <function>drm_gem_cma_prime_vunmap </function></funcdef>
6572   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
6573   <paramdef>void * <parameter>vaddr</parameter></paramdef>
6574  </funcprototype></funcsynopsis>
6575</refsynopsisdiv>
6576<refsect1>
6577 <title>Arguments</title>
6578 <variablelist>
6579  <varlistentry>
6580   <term><parameter>obj</parameter></term>
6581   <listitem>
6582    <para>
6583     GEM object
6584    </para>
6585   </listitem>
6586  </varlistentry>
6587  <varlistentry>
6588   <term><parameter>vaddr</parameter></term>
6589   <listitem>
6590    <para>
6591     kernel virtual address where the CMA GEM object was mapped
6592    </para>
6593   </listitem>
6594  </varlistentry>
6595 </variablelist>
6596</refsect1>
6597<refsect1>
6598<title>Description</title>
6599<para>
6600   This function removes a buffer exported via DRM PRIME from the kernel's
6601   virtual address space. This is a no-op because CMA buffers cannot be
6602   unmapped from kernel space. Drivers using the CMA helpers should set this
6603   as their DRM driver's -&gt;<function>gem_prime_vunmap</function> callback.
6604</para>
6605</refsect1>
6606</refentry>
6607
6608<!-- include/drm/drm_gem_cma_helper.h -->
6609<refentry id="API-struct-drm-gem-cma-object">
6610<refentryinfo>
6611 <title>LINUX</title>
6612 <productname>Kernel Hackers Manual</productname>
6613 <date>July 2017</date>
6614</refentryinfo>
6615<refmeta>
6616 <refentrytitle><phrase>struct drm_gem_cma_object</phrase></refentrytitle>
6617 <manvolnum>9</manvolnum>
6618 <refmiscinfo class="version">4.1.27</refmiscinfo>
6619</refmeta>
6620<refnamediv>
6621 <refname>struct drm_gem_cma_object</refname>
6622 <refpurpose>
6623  GEM object backed by CMA memory allocations
6624 </refpurpose>
6625</refnamediv>
6626<refsynopsisdiv>
6627 <title>Synopsis</title>
6628  <programlisting>
6629struct drm_gem_cma_object {
6630  struct drm_gem_object base;
6631  dma_addr_t paddr;
6632  struct sg_table * sgt;
6633  void * vaddr;
6634};  </programlisting>
6635</refsynopsisdiv>
6636 <refsect1>
6637  <title>Members</title>
6638  <variablelist>
6639    <varlistentry>      <term>base</term>
6640      <listitem><para>
6641base GEM object
6642      </para></listitem>
6643    </varlistentry>
6644    <varlistentry>      <term>paddr</term>
6645      <listitem><para>
6646physical address of the backing memory
6647      </para></listitem>
6648    </varlistentry>
6649    <varlistentry>      <term>sgt</term>
6650      <listitem><para>
6651scatter/gather table for imported PRIME buffers
6652      </para></listitem>
6653    </varlistentry>
6654    <varlistentry>      <term>vaddr</term>
6655      <listitem><para>
6656kernel virtual address of the backing memory
6657      </para></listitem>
6658    </varlistentry>
6659  </variablelist>
6660 </refsect1>
6661</refentry>
6662
6663    </sect2>
6664  </sect1>
6665
6666  <!-- Internals: mode setting -->
6667
6668  <sect1 id="drm-mode-setting">
6669    <title>Mode Setting</title>
6670    <para>
6671      Drivers must initialize the mode setting core by calling
6672      <function>drm_mode_config_init</function> on the DRM device. The function
6673      initializes the <structname>drm_device</structname>
6674      <structfield>mode_config</structfield> field and never fails. Once done,
6675      mode configuration must be setup by initializing the following fields.
6676    </para>
6677    <itemizedlist>
6678      <listitem>
6679        <synopsis>int min_width, min_height;
6680int max_width, max_height;</synopsis>
6681        <para>
6682	  Minimum and maximum width and height of the frame buffers in pixel
6683	  units.
6684	</para>
6685      </listitem>
6686      <listitem>
6687        <synopsis>struct drm_mode_config_funcs *funcs;</synopsis>
6688	<para>Mode setting functions.</para>
6689      </listitem>
6690    </itemizedlist>
6691    <sect2>
6692      <title>Display Modes Function Reference</title>
6693<!-- include/drm/drm_modes.h -->
6694<refentry id="API-drm-mode-is-stereo">
6695<refentryinfo>
6696 <title>LINUX</title>
6697 <productname>Kernel Hackers Manual</productname>
6698 <date>July 2017</date>
6699</refentryinfo>
6700<refmeta>
6701 <refentrytitle><phrase>drm_mode_is_stereo</phrase></refentrytitle>
6702 <manvolnum>9</manvolnum>
6703 <refmiscinfo class="version">4.1.27</refmiscinfo>
6704</refmeta>
6705<refnamediv>
6706 <refname>drm_mode_is_stereo</refname>
6707 <refpurpose>
6708  check for stereo mode flags
6709 </refpurpose>
6710</refnamediv>
6711<refsynopsisdiv>
6712 <title>Synopsis</title>
6713  <funcsynopsis><funcprototype>
6714   <funcdef>bool <function>drm_mode_is_stereo </function></funcdef>
6715   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
6716  </funcprototype></funcsynopsis>
6717</refsynopsisdiv>
6718<refsect1>
6719 <title>Arguments</title>
6720 <variablelist>
6721  <varlistentry>
6722   <term><parameter>mode</parameter></term>
6723   <listitem>
6724    <para>
6725     drm_display_mode to check
6726    </para>
6727   </listitem>
6728  </varlistentry>
6729 </variablelist>
6730</refsect1>
6731<refsect1>
6732<title>Returns</title>
6733<para>
6734   True if the mode is one of the stereo modes (like side-by-side), false if
6735   not.
6736</para>
6737</refsect1>
6738</refentry>
6739
6740<!-- drivers/gpu/drm/drm_modes.c -->
6741<refentry id="API-drm-mode-debug-printmodeline">
6742<refentryinfo>
6743 <title>LINUX</title>
6744 <productname>Kernel Hackers Manual</productname>
6745 <date>July 2017</date>
6746</refentryinfo>
6747<refmeta>
6748 <refentrytitle><phrase>drm_mode_debug_printmodeline</phrase></refentrytitle>
6749 <manvolnum>9</manvolnum>
6750 <refmiscinfo class="version">4.1.27</refmiscinfo>
6751</refmeta>
6752<refnamediv>
6753 <refname>drm_mode_debug_printmodeline</refname>
6754 <refpurpose>
6755  print a mode to dmesg
6756 </refpurpose>
6757</refnamediv>
6758<refsynopsisdiv>
6759 <title>Synopsis</title>
6760  <funcsynopsis><funcprototype>
6761   <funcdef>void <function>drm_mode_debug_printmodeline </function></funcdef>
6762   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
6763  </funcprototype></funcsynopsis>
6764</refsynopsisdiv>
6765<refsect1>
6766 <title>Arguments</title>
6767 <variablelist>
6768  <varlistentry>
6769   <term><parameter>mode</parameter></term>
6770   <listitem>
6771    <para>
6772     mode to print
6773    </para>
6774   </listitem>
6775  </varlistentry>
6776 </variablelist>
6777</refsect1>
6778<refsect1>
6779<title>Description</title>
6780<para>
6781   Describe <parameter>mode</parameter> using DRM_DEBUG.
6782</para>
6783</refsect1>
6784</refentry>
6785
6786<refentry id="API-drm-mode-create">
6787<refentryinfo>
6788 <title>LINUX</title>
6789 <productname>Kernel Hackers Manual</productname>
6790 <date>July 2017</date>
6791</refentryinfo>
6792<refmeta>
6793 <refentrytitle><phrase>drm_mode_create</phrase></refentrytitle>
6794 <manvolnum>9</manvolnum>
6795 <refmiscinfo class="version">4.1.27</refmiscinfo>
6796</refmeta>
6797<refnamediv>
6798 <refname>drm_mode_create</refname>
6799 <refpurpose>
6800     create a new display mode
6801 </refpurpose>
6802</refnamediv>
6803<refsynopsisdiv>
6804 <title>Synopsis</title>
6805  <funcsynopsis><funcprototype>
6806   <funcdef>struct drm_display_mode * <function>drm_mode_create </function></funcdef>
6807   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
6808  </funcprototype></funcsynopsis>
6809</refsynopsisdiv>
6810<refsect1>
6811 <title>Arguments</title>
6812 <variablelist>
6813  <varlistentry>
6814   <term><parameter>dev</parameter></term>
6815   <listitem>
6816    <para>
6817     DRM device
6818    </para>
6819   </listitem>
6820  </varlistentry>
6821 </variablelist>
6822</refsect1>
6823<refsect1>
6824<title>Description</title>
6825<para>
6826   Create a new, cleared drm_display_mode with kzalloc, allocate an ID for it
6827   and return it.
6828</para>
6829</refsect1>
6830<refsect1>
6831<title>Returns</title>
6832<para>
6833   Pointer to new mode on success, NULL on error.
6834</para>
6835</refsect1>
6836</refentry>
6837
6838<refentry id="API-drm-mode-destroy">
6839<refentryinfo>
6840 <title>LINUX</title>
6841 <productname>Kernel Hackers Manual</productname>
6842 <date>July 2017</date>
6843</refentryinfo>
6844<refmeta>
6845 <refentrytitle><phrase>drm_mode_destroy</phrase></refentrytitle>
6846 <manvolnum>9</manvolnum>
6847 <refmiscinfo class="version">4.1.27</refmiscinfo>
6848</refmeta>
6849<refnamediv>
6850 <refname>drm_mode_destroy</refname>
6851 <refpurpose>
6852     remove a mode
6853 </refpurpose>
6854</refnamediv>
6855<refsynopsisdiv>
6856 <title>Synopsis</title>
6857  <funcsynopsis><funcprototype>
6858   <funcdef>void <function>drm_mode_destroy </function></funcdef>
6859   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
6860   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
6861  </funcprototype></funcsynopsis>
6862</refsynopsisdiv>
6863<refsect1>
6864 <title>Arguments</title>
6865 <variablelist>
6866  <varlistentry>
6867   <term><parameter>dev</parameter></term>
6868   <listitem>
6869    <para>
6870     DRM device
6871    </para>
6872   </listitem>
6873  </varlistentry>
6874  <varlistentry>
6875   <term><parameter>mode</parameter></term>
6876   <listitem>
6877    <para>
6878     mode to remove
6879    </para>
6880   </listitem>
6881  </varlistentry>
6882 </variablelist>
6883</refsect1>
6884<refsect1>
6885<title>Description</title>
6886<para>
6887   Release <parameter>mode</parameter>'s unique ID, then free it <parameter>mode</parameter> structure itself using kfree.
6888</para>
6889</refsect1>
6890</refentry>
6891
6892<refentry id="API-drm-mode-probed-add">
6893<refentryinfo>
6894 <title>LINUX</title>
6895 <productname>Kernel Hackers Manual</productname>
6896 <date>July 2017</date>
6897</refentryinfo>
6898<refmeta>
6899 <refentrytitle><phrase>drm_mode_probed_add</phrase></refentrytitle>
6900 <manvolnum>9</manvolnum>
6901 <refmiscinfo class="version">4.1.27</refmiscinfo>
6902</refmeta>
6903<refnamediv>
6904 <refname>drm_mode_probed_add</refname>
6905 <refpurpose>
6906     add a mode to a connector's probed_mode list
6907 </refpurpose>
6908</refnamediv>
6909<refsynopsisdiv>
6910 <title>Synopsis</title>
6911  <funcsynopsis><funcprototype>
6912   <funcdef>void <function>drm_mode_probed_add </function></funcdef>
6913   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
6914   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
6915  </funcprototype></funcsynopsis>
6916</refsynopsisdiv>
6917<refsect1>
6918 <title>Arguments</title>
6919 <variablelist>
6920  <varlistentry>
6921   <term><parameter>connector</parameter></term>
6922   <listitem>
6923    <para>
6924     connector the new mode
6925    </para>
6926   </listitem>
6927  </varlistentry>
6928  <varlistentry>
6929   <term><parameter>mode</parameter></term>
6930   <listitem>
6931    <para>
6932     mode data
6933    </para>
6934   </listitem>
6935  </varlistentry>
6936 </variablelist>
6937</refsect1>
6938<refsect1>
6939<title>Description</title>
6940<para>
6941   Add <parameter>mode</parameter> to <parameter>connector</parameter>'s probed_mode list for later use. This list should
6942   then in a second step get filtered and all the modes actually supported by
6943   the hardware moved to the <parameter>connector</parameter>'s modes list.
6944</para>
6945</refsect1>
6946</refentry>
6947
6948<refentry id="API-drm-cvt-mode">
6949<refentryinfo>
6950 <title>LINUX</title>
6951 <productname>Kernel Hackers Manual</productname>
6952 <date>July 2017</date>
6953</refentryinfo>
6954<refmeta>
6955 <refentrytitle><phrase>drm_cvt_mode</phrase></refentrytitle>
6956 <manvolnum>9</manvolnum>
6957 <refmiscinfo class="version">4.1.27</refmiscinfo>
6958</refmeta>
6959<refnamediv>
6960 <refname>drm_cvt_mode</refname>
6961 <refpurpose>
6962     create a modeline based on the CVT algorithm
6963 </refpurpose>
6964</refnamediv>
6965<refsynopsisdiv>
6966 <title>Synopsis</title>
6967  <funcsynopsis><funcprototype>
6968   <funcdef>struct drm_display_mode * <function>drm_cvt_mode </function></funcdef>
6969   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
6970   <paramdef>int <parameter>hdisplay</parameter></paramdef>
6971   <paramdef>int <parameter>vdisplay</parameter></paramdef>
6972   <paramdef>int <parameter>vrefresh</parameter></paramdef>
6973   <paramdef>bool <parameter>reduced</parameter></paramdef>
6974   <paramdef>bool <parameter>interlaced</parameter></paramdef>
6975   <paramdef>bool <parameter>margins</parameter></paramdef>
6976  </funcprototype></funcsynopsis>
6977</refsynopsisdiv>
6978<refsect1>
6979 <title>Arguments</title>
6980 <variablelist>
6981  <varlistentry>
6982   <term><parameter>dev</parameter></term>
6983   <listitem>
6984    <para>
6985     drm device
6986    </para>
6987   </listitem>
6988  </varlistentry>
6989  <varlistentry>
6990   <term><parameter>hdisplay</parameter></term>
6991   <listitem>
6992    <para>
6993     hdisplay size
6994    </para>
6995   </listitem>
6996  </varlistentry>
6997  <varlistentry>
6998   <term><parameter>vdisplay</parameter></term>
6999   <listitem>
7000    <para>
7001     vdisplay size
7002    </para>
7003   </listitem>
7004  </varlistentry>
7005  <varlistentry>
7006   <term><parameter>vrefresh</parameter></term>
7007   <listitem>
7008    <para>
7009     vrefresh rate
7010    </para>
7011   </listitem>
7012  </varlistentry>
7013  <varlistentry>
7014   <term><parameter>reduced</parameter></term>
7015   <listitem>
7016    <para>
7017     whether to use reduced blanking
7018    </para>
7019   </listitem>
7020  </varlistentry>
7021  <varlistentry>
7022   <term><parameter>interlaced</parameter></term>
7023   <listitem>
7024    <para>
7025     whether to compute an interlaced mode
7026    </para>
7027   </listitem>
7028  </varlistentry>
7029  <varlistentry>
7030   <term><parameter>margins</parameter></term>
7031   <listitem>
7032    <para>
7033     whether to add margins (borders)
7034    </para>
7035   </listitem>
7036  </varlistentry>
7037 </variablelist>
7038</refsect1>
7039<refsect1>
7040<title>Description</title>
7041<para>
7042   This function is called to generate the modeline based on CVT algorithm
7043   according to the hdisplay, vdisplay, vrefresh.
7044   It is based from the VESA(TM) Coordinated Video Timing Generator by
7045   Graham Loveridge April 9, 2003 available at
7046</para>
7047</refsect1>
7048<refsect1>
7049<title>http</title>
7050<para>
7051   //www.elo.utfsm.cl/~elo212/docs/CVTd6r1.xls 
7052   </para><para>
7053
7054   And it is copied from xf86CVTmode in xserver/hw/xfree86/modes/xf86cvt.c.
7055   What I have done is to translate it by using integer calculation.
7056</para>
7057</refsect1>
7058<refsect1>
7059<title>Returns</title>
7060<para>
7061   The modeline based on the CVT algorithm stored in a drm_display_mode object.
7062   The display mode object is allocated with <function>drm_mode_create</function>. Returns NULL
7063   when no mode could be allocated.
7064</para>
7065</refsect1>
7066</refentry>
7067
7068<refentry id="API-drm-gtf-mode-complex">
7069<refentryinfo>
7070 <title>LINUX</title>
7071 <productname>Kernel Hackers Manual</productname>
7072 <date>July 2017</date>
7073</refentryinfo>
7074<refmeta>
7075 <refentrytitle><phrase>drm_gtf_mode_complex</phrase></refentrytitle>
7076 <manvolnum>9</manvolnum>
7077 <refmiscinfo class="version">4.1.27</refmiscinfo>
7078</refmeta>
7079<refnamediv>
7080 <refname>drm_gtf_mode_complex</refname>
7081 <refpurpose>
7082     create the modeline based on the full GTF algorithm
7083 </refpurpose>
7084</refnamediv>
7085<refsynopsisdiv>
7086 <title>Synopsis</title>
7087  <funcsynopsis><funcprototype>
7088   <funcdef>struct drm_display_mode * <function>drm_gtf_mode_complex </function></funcdef>
7089   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
7090   <paramdef>int <parameter>hdisplay</parameter></paramdef>
7091   <paramdef>int <parameter>vdisplay</parameter></paramdef>
7092   <paramdef>int <parameter>vrefresh</parameter></paramdef>
7093   <paramdef>bool <parameter>interlaced</parameter></paramdef>
7094   <paramdef>int <parameter>margins</parameter></paramdef>
7095   <paramdef>int <parameter>GTF_M</parameter></paramdef>
7096   <paramdef>int <parameter>GTF_2C</parameter></paramdef>
7097   <paramdef>int <parameter>GTF_K</parameter></paramdef>
7098   <paramdef>int <parameter>GTF_2J</parameter></paramdef>
7099  </funcprototype></funcsynopsis>
7100</refsynopsisdiv>
7101<refsect1>
7102 <title>Arguments</title>
7103 <variablelist>
7104  <varlistentry>
7105   <term><parameter>dev</parameter></term>
7106   <listitem>
7107    <para>
7108     drm device
7109    </para>
7110   </listitem>
7111  </varlistentry>
7112  <varlistentry>
7113   <term><parameter>hdisplay</parameter></term>
7114   <listitem>
7115    <para>
7116     hdisplay size
7117    </para>
7118   </listitem>
7119  </varlistentry>
7120  <varlistentry>
7121   <term><parameter>vdisplay</parameter></term>
7122   <listitem>
7123    <para>
7124     vdisplay size
7125    </para>
7126   </listitem>
7127  </varlistentry>
7128  <varlistentry>
7129   <term><parameter>vrefresh</parameter></term>
7130   <listitem>
7131    <para>
7132     vrefresh rate.
7133    </para>
7134   </listitem>
7135  </varlistentry>
7136  <varlistentry>
7137   <term><parameter>interlaced</parameter></term>
7138   <listitem>
7139    <para>
7140     whether to compute an interlaced mode
7141    </para>
7142   </listitem>
7143  </varlistentry>
7144  <varlistentry>
7145   <term><parameter>margins</parameter></term>
7146   <listitem>
7147    <para>
7148     desired margin (borders) size
7149    </para>
7150   </listitem>
7151  </varlistentry>
7152  <varlistentry>
7153   <term><parameter>GTF_M</parameter></term>
7154   <listitem>
7155    <para>
7156     extended GTF formula parameters
7157    </para>
7158   </listitem>
7159  </varlistentry>
7160  <varlistentry>
7161   <term><parameter>GTF_2C</parameter></term>
7162   <listitem>
7163    <para>
7164     extended GTF formula parameters
7165    </para>
7166   </listitem>
7167  </varlistentry>
7168  <varlistentry>
7169   <term><parameter>GTF_K</parameter></term>
7170   <listitem>
7171    <para>
7172     extended GTF formula parameters
7173    </para>
7174   </listitem>
7175  </varlistentry>
7176  <varlistentry>
7177   <term><parameter>GTF_2J</parameter></term>
7178   <listitem>
7179    <para>
7180     extended GTF formula parameters
7181    </para>
7182   </listitem>
7183  </varlistentry>
7184 </variablelist>
7185</refsect1>
7186<refsect1>
7187<title>Description</title>
7188<para>
7189   GTF feature blocks specify C and J in multiples of 0.5, so we pass them
7190   in here multiplied by two.  For a C of 40, pass in 80.
7191</para>
7192</refsect1>
7193<refsect1>
7194<title>Returns</title>
7195<para>
7196   The modeline based on the full GTF algorithm stored in a drm_display_mode object.
7197   The display mode object is allocated with <function>drm_mode_create</function>. Returns NULL
7198   when no mode could be allocated.
7199</para>
7200</refsect1>
7201</refentry>
7202
7203<refentry id="API-drm-gtf-mode">
7204<refentryinfo>
7205 <title>LINUX</title>
7206 <productname>Kernel Hackers Manual</productname>
7207 <date>July 2017</date>
7208</refentryinfo>
7209<refmeta>
7210 <refentrytitle><phrase>drm_gtf_mode</phrase></refentrytitle>
7211 <manvolnum>9</manvolnum>
7212 <refmiscinfo class="version">4.1.27</refmiscinfo>
7213</refmeta>
7214<refnamediv>
7215 <refname>drm_gtf_mode</refname>
7216 <refpurpose>
7217     create the modeline based on the GTF algorithm
7218 </refpurpose>
7219</refnamediv>
7220<refsynopsisdiv>
7221 <title>Synopsis</title>
7222  <funcsynopsis><funcprototype>
7223   <funcdef>struct drm_display_mode * <function>drm_gtf_mode </function></funcdef>
7224   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
7225   <paramdef>int <parameter>hdisplay</parameter></paramdef>
7226   <paramdef>int <parameter>vdisplay</parameter></paramdef>
7227   <paramdef>int <parameter>vrefresh</parameter></paramdef>
7228   <paramdef>bool <parameter>interlaced</parameter></paramdef>
7229   <paramdef>int <parameter>margins</parameter></paramdef>
7230  </funcprototype></funcsynopsis>
7231</refsynopsisdiv>
7232<refsect1>
7233 <title>Arguments</title>
7234 <variablelist>
7235  <varlistentry>
7236   <term><parameter>dev</parameter></term>
7237   <listitem>
7238    <para>
7239     drm device
7240    </para>
7241   </listitem>
7242  </varlistentry>
7243  <varlistentry>
7244   <term><parameter>hdisplay</parameter></term>
7245   <listitem>
7246    <para>
7247     hdisplay size
7248    </para>
7249   </listitem>
7250  </varlistentry>
7251  <varlistentry>
7252   <term><parameter>vdisplay</parameter></term>
7253   <listitem>
7254    <para>
7255     vdisplay size
7256    </para>
7257   </listitem>
7258  </varlistentry>
7259  <varlistentry>
7260   <term><parameter>vrefresh</parameter></term>
7261   <listitem>
7262    <para>
7263     vrefresh rate.
7264    </para>
7265   </listitem>
7266  </varlistentry>
7267  <varlistentry>
7268   <term><parameter>interlaced</parameter></term>
7269   <listitem>
7270    <para>
7271     whether to compute an interlaced mode
7272    </para>
7273   </listitem>
7274  </varlistentry>
7275  <varlistentry>
7276   <term><parameter>margins</parameter></term>
7277   <listitem>
7278    <para>
7279     desired margin (borders) size
7280    </para>
7281   </listitem>
7282  </varlistentry>
7283 </variablelist>
7284</refsect1>
7285<refsect1>
7286<title>Description</title>
7287<para>
7288   return the modeline based on GTF algorithm
7289   </para><para>
7290
7291   This function is to create the modeline based on the GTF algorithm.
7292</para>
7293</refsect1>
7294<refsect1>
7295<title>Generalized Timing Formula is derived from</title>
7296<para>
7297   GTF Spreadsheet by Andy Morrish (1/5/97)
7298</para>
7299</refsect1>
7300<refsect1>
7301<title>available at http</title>
7302<para>
7303   //www.vesa.org
7304   </para><para>
7305
7306   And it is copied from the file of xserver/hw/xfree86/modes/xf86gtf.c.
7307   What I have done is to translate it by using integer calculation.
7308   I also refer to the function of fb_get_mode in the file of
7309   drivers/video/fbmon.c
7310</para>
7311</refsect1>
7312<refsect1>
7313<title>Standard GTF parameters</title>
7314<para>
7315   M = 600
7316   C = 40
7317   K = 128
7318   J = 20
7319</para>
7320</refsect1>
7321<refsect1>
7322<title>Returns</title>
7323<para>
7324   The modeline based on the GTF algorithm stored in a drm_display_mode object.
7325   The display mode object is allocated with <function>drm_mode_create</function>. Returns NULL
7326   when no mode could be allocated.
7327</para>
7328</refsect1>
7329</refentry>
7330
7331<refentry id="API-drm-display-mode-from-videomode">
7332<refentryinfo>
7333 <title>LINUX</title>
7334 <productname>Kernel Hackers Manual</productname>
7335 <date>July 2017</date>
7336</refentryinfo>
7337<refmeta>
7338 <refentrytitle><phrase>drm_display_mode_from_videomode</phrase></refentrytitle>
7339 <manvolnum>9</manvolnum>
7340 <refmiscinfo class="version">4.1.27</refmiscinfo>
7341</refmeta>
7342<refnamediv>
7343 <refname>drm_display_mode_from_videomode</refname>
7344 <refpurpose>
7345     fill in <parameter>dmode</parameter> using <parameter>vm</parameter>,
7346 </refpurpose>
7347</refnamediv>
7348<refsynopsisdiv>
7349 <title>Synopsis</title>
7350  <funcsynopsis><funcprototype>
7351   <funcdef>void <function>drm_display_mode_from_videomode </function></funcdef>
7352   <paramdef>const struct videomode * <parameter>vm</parameter></paramdef>
7353   <paramdef>struct drm_display_mode * <parameter>dmode</parameter></paramdef>
7354  </funcprototype></funcsynopsis>
7355</refsynopsisdiv>
7356<refsect1>
7357 <title>Arguments</title>
7358 <variablelist>
7359  <varlistentry>
7360   <term><parameter>vm</parameter></term>
7361   <listitem>
7362    <para>
7363     videomode structure to use as source
7364    </para>
7365   </listitem>
7366  </varlistentry>
7367  <varlistentry>
7368   <term><parameter>dmode</parameter></term>
7369   <listitem>
7370    <para>
7371     drm_display_mode structure to use as destination
7372    </para>
7373   </listitem>
7374  </varlistentry>
7375 </variablelist>
7376</refsect1>
7377<refsect1>
7378<title>Description</title>
7379<para>
7380   Fills out <parameter>dmode</parameter> using the display mode specified in <parameter>vm</parameter>.
7381</para>
7382</refsect1>
7383</refentry>
7384
7385<refentry id="API-drm-display-mode-to-videomode">
7386<refentryinfo>
7387 <title>LINUX</title>
7388 <productname>Kernel Hackers Manual</productname>
7389 <date>July 2017</date>
7390</refentryinfo>
7391<refmeta>
7392 <refentrytitle><phrase>drm_display_mode_to_videomode</phrase></refentrytitle>
7393 <manvolnum>9</manvolnum>
7394 <refmiscinfo class="version">4.1.27</refmiscinfo>
7395</refmeta>
7396<refnamediv>
7397 <refname>drm_display_mode_to_videomode</refname>
7398 <refpurpose>
7399     fill in <parameter>vm</parameter> using <parameter>dmode</parameter>,
7400 </refpurpose>
7401</refnamediv>
7402<refsynopsisdiv>
7403 <title>Synopsis</title>
7404  <funcsynopsis><funcprototype>
7405   <funcdef>void <function>drm_display_mode_to_videomode </function></funcdef>
7406   <paramdef>const struct drm_display_mode * <parameter>dmode</parameter></paramdef>
7407   <paramdef>struct videomode * <parameter>vm</parameter></paramdef>
7408  </funcprototype></funcsynopsis>
7409</refsynopsisdiv>
7410<refsect1>
7411 <title>Arguments</title>
7412 <variablelist>
7413  <varlistentry>
7414   <term><parameter>dmode</parameter></term>
7415   <listitem>
7416    <para>
7417     drm_display_mode structure to use as source
7418    </para>
7419   </listitem>
7420  </varlistentry>
7421  <varlistentry>
7422   <term><parameter>vm</parameter></term>
7423   <listitem>
7424    <para>
7425     videomode structure to use as destination
7426    </para>
7427   </listitem>
7428  </varlistentry>
7429 </variablelist>
7430</refsect1>
7431<refsect1>
7432<title>Description</title>
7433<para>
7434   Fills out <parameter>vm</parameter> using the display mode specified in <parameter>dmode</parameter>.
7435</para>
7436</refsect1>
7437</refentry>
7438
7439<refentry id="API-of-get-drm-display-mode">
7440<refentryinfo>
7441 <title>LINUX</title>
7442 <productname>Kernel Hackers Manual</productname>
7443 <date>July 2017</date>
7444</refentryinfo>
7445<refmeta>
7446 <refentrytitle><phrase>of_get_drm_display_mode</phrase></refentrytitle>
7447 <manvolnum>9</manvolnum>
7448 <refmiscinfo class="version">4.1.27</refmiscinfo>
7449</refmeta>
7450<refnamediv>
7451 <refname>of_get_drm_display_mode</refname>
7452 <refpurpose>
7453     get a drm_display_mode from devicetree
7454 </refpurpose>
7455</refnamediv>
7456<refsynopsisdiv>
7457 <title>Synopsis</title>
7458  <funcsynopsis><funcprototype>
7459   <funcdef>int <function>of_get_drm_display_mode </function></funcdef>
7460   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
7461   <paramdef>struct drm_display_mode * <parameter>dmode</parameter></paramdef>
7462   <paramdef>int <parameter>index</parameter></paramdef>
7463  </funcprototype></funcsynopsis>
7464</refsynopsisdiv>
7465<refsect1>
7466 <title>Arguments</title>
7467 <variablelist>
7468  <varlistentry>
7469   <term><parameter>np</parameter></term>
7470   <listitem>
7471    <para>
7472     device_node with the timing specification
7473    </para>
7474   </listitem>
7475  </varlistentry>
7476  <varlistentry>
7477   <term><parameter>dmode</parameter></term>
7478   <listitem>
7479    <para>
7480     will be set to the return value
7481    </para>
7482   </listitem>
7483  </varlistentry>
7484  <varlistentry>
7485   <term><parameter>index</parameter></term>
7486   <listitem>
7487    <para>
7488     index into the list of display timings in devicetree
7489    </para>
7490   </listitem>
7491  </varlistentry>
7492 </variablelist>
7493</refsect1>
7494<refsect1>
7495<title>Description</title>
7496<para>
7497   This function is expensive and should only be used, if only one mode is to be
7498   read from DT. To get multiple modes start with of_get_display_timings and
7499   work with that instead.
7500</para>
7501</refsect1>
7502<refsect1>
7503<title>Returns</title>
7504<para>
7505   0 on success, a negative errno code when no of videomode node was found.
7506</para>
7507</refsect1>
7508</refentry>
7509
7510<refentry id="API-drm-mode-set-name">
7511<refentryinfo>
7512 <title>LINUX</title>
7513 <productname>Kernel Hackers Manual</productname>
7514 <date>July 2017</date>
7515</refentryinfo>
7516<refmeta>
7517 <refentrytitle><phrase>drm_mode_set_name</phrase></refentrytitle>
7518 <manvolnum>9</manvolnum>
7519 <refmiscinfo class="version">4.1.27</refmiscinfo>
7520</refmeta>
7521<refnamediv>
7522 <refname>drm_mode_set_name</refname>
7523 <refpurpose>
7524     set the name on a mode
7525 </refpurpose>
7526</refnamediv>
7527<refsynopsisdiv>
7528 <title>Synopsis</title>
7529  <funcsynopsis><funcprototype>
7530   <funcdef>void <function>drm_mode_set_name </function></funcdef>
7531   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
7532  </funcprototype></funcsynopsis>
7533</refsynopsisdiv>
7534<refsect1>
7535 <title>Arguments</title>
7536 <variablelist>
7537  <varlistentry>
7538   <term><parameter>mode</parameter></term>
7539   <listitem>
7540    <para>
7541     name will be set in this mode
7542    </para>
7543   </listitem>
7544  </varlistentry>
7545 </variablelist>
7546</refsect1>
7547<refsect1>
7548<title>Description</title>
7549<para>
7550   Set the name of <parameter>mode</parameter> to a standard format which is &lt;hdisplay&gt;x&lt;vdisplay&gt;
7551   with an optional 'i' suffix for interlaced modes.
7552</para>
7553</refsect1>
7554</refentry>
7555
7556<refentry id="API-drm-mode-vrefresh">
7557<refentryinfo>
7558 <title>LINUX</title>
7559 <productname>Kernel Hackers Manual</productname>
7560 <date>July 2017</date>
7561</refentryinfo>
7562<refmeta>
7563 <refentrytitle><phrase>drm_mode_vrefresh</phrase></refentrytitle>
7564 <manvolnum>9</manvolnum>
7565 <refmiscinfo class="version">4.1.27</refmiscinfo>
7566</refmeta>
7567<refnamediv>
7568 <refname>drm_mode_vrefresh</refname>
7569 <refpurpose>
7570     get the vrefresh of a mode
7571 </refpurpose>
7572</refnamediv>
7573<refsynopsisdiv>
7574 <title>Synopsis</title>
7575  <funcsynopsis><funcprototype>
7576   <funcdef>int <function>drm_mode_vrefresh </function></funcdef>
7577   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
7578  </funcprototype></funcsynopsis>
7579</refsynopsisdiv>
7580<refsect1>
7581 <title>Arguments</title>
7582 <variablelist>
7583  <varlistentry>
7584   <term><parameter>mode</parameter></term>
7585   <listitem>
7586    <para>
7587     mode
7588    </para>
7589   </listitem>
7590  </varlistentry>
7591 </variablelist>
7592</refsect1>
7593<refsect1>
7594<title>Returns</title>
7595<para>
7596   <parameter>modes</parameter>'s vrefresh rate in Hz, rounded to the nearest integer. Calculates the
7597   value first if it is not yet set.
7598</para>
7599</refsect1>
7600</refentry>
7601
7602<refentry id="API-drm-mode-set-crtcinfo">
7603<refentryinfo>
7604 <title>LINUX</title>
7605 <productname>Kernel Hackers Manual</productname>
7606 <date>July 2017</date>
7607</refentryinfo>
7608<refmeta>
7609 <refentrytitle><phrase>drm_mode_set_crtcinfo</phrase></refentrytitle>
7610 <manvolnum>9</manvolnum>
7611 <refmiscinfo class="version">4.1.27</refmiscinfo>
7612</refmeta>
7613<refnamediv>
7614 <refname>drm_mode_set_crtcinfo</refname>
7615 <refpurpose>
7616     set CRTC modesetting timing parameters
7617 </refpurpose>
7618</refnamediv>
7619<refsynopsisdiv>
7620 <title>Synopsis</title>
7621  <funcsynopsis><funcprototype>
7622   <funcdef>void <function>drm_mode_set_crtcinfo </function></funcdef>
7623   <paramdef>struct drm_display_mode * <parameter>p</parameter></paramdef>
7624   <paramdef>int <parameter>adjust_flags</parameter></paramdef>
7625  </funcprototype></funcsynopsis>
7626</refsynopsisdiv>
7627<refsect1>
7628 <title>Arguments</title>
7629 <variablelist>
7630  <varlistentry>
7631   <term><parameter>p</parameter></term>
7632   <listitem>
7633    <para>
7634     mode
7635    </para>
7636   </listitem>
7637  </varlistentry>
7638  <varlistentry>
7639   <term><parameter>adjust_flags</parameter></term>
7640   <listitem>
7641    <para>
7642     a combination of adjustment flags
7643    </para>
7644   </listitem>
7645  </varlistentry>
7646 </variablelist>
7647</refsect1>
7648<refsect1>
7649<title>Description</title>
7650<para>
7651   Setup the CRTC modesetting timing parameters for <parameter>p</parameter>, adjusting if necessary.
7652   </para><para>
7653
7654   - The CRTC_INTERLACE_HALVE_V flag can be used to halve vertical timings of
7655   interlaced modes.
7656   - The CRTC_STEREO_DOUBLE flag can be used to compute the timings for
7657   buffers containing two eyes (only adjust the timings when needed, eg. for
7658   <quote>frame packing</quote> or <quote>side by side full</quote>).
7659   - The CRTC_NO_DBLSCAN and CRTC_NO_VSCAN flags request that adjustment *not*
7660   be performed for doublescan and vscan &gt; 1 modes respectively.
7661</para>
7662</refsect1>
7663</refentry>
7664
7665<refentry id="API-drm-mode-copy">
7666<refentryinfo>
7667 <title>LINUX</title>
7668 <productname>Kernel Hackers Manual</productname>
7669 <date>July 2017</date>
7670</refentryinfo>
7671<refmeta>
7672 <refentrytitle><phrase>drm_mode_copy</phrase></refentrytitle>
7673 <manvolnum>9</manvolnum>
7674 <refmiscinfo class="version">4.1.27</refmiscinfo>
7675</refmeta>
7676<refnamediv>
7677 <refname>drm_mode_copy</refname>
7678 <refpurpose>
7679     copy the mode
7680 </refpurpose>
7681</refnamediv>
7682<refsynopsisdiv>
7683 <title>Synopsis</title>
7684  <funcsynopsis><funcprototype>
7685   <funcdef>void <function>drm_mode_copy </function></funcdef>
7686   <paramdef>struct drm_display_mode * <parameter>dst</parameter></paramdef>
7687   <paramdef>const struct drm_display_mode * <parameter>src</parameter></paramdef>
7688  </funcprototype></funcsynopsis>
7689</refsynopsisdiv>
7690<refsect1>
7691 <title>Arguments</title>
7692 <variablelist>
7693  <varlistentry>
7694   <term><parameter>dst</parameter></term>
7695   <listitem>
7696    <para>
7697     mode to overwrite
7698    </para>
7699   </listitem>
7700  </varlistentry>
7701  <varlistentry>
7702   <term><parameter>src</parameter></term>
7703   <listitem>
7704    <para>
7705     mode to copy
7706    </para>
7707   </listitem>
7708  </varlistentry>
7709 </variablelist>
7710</refsect1>
7711<refsect1>
7712<title>Description</title>
7713<para>
7714   Copy an existing mode into another mode, preserving the object id and
7715   list head of the destination mode.
7716</para>
7717</refsect1>
7718</refentry>
7719
7720<refentry id="API-drm-mode-duplicate">
7721<refentryinfo>
7722 <title>LINUX</title>
7723 <productname>Kernel Hackers Manual</productname>
7724 <date>July 2017</date>
7725</refentryinfo>
7726<refmeta>
7727 <refentrytitle><phrase>drm_mode_duplicate</phrase></refentrytitle>
7728 <manvolnum>9</manvolnum>
7729 <refmiscinfo class="version">4.1.27</refmiscinfo>
7730</refmeta>
7731<refnamediv>
7732 <refname>drm_mode_duplicate</refname>
7733 <refpurpose>
7734     allocate and duplicate an existing mode
7735 </refpurpose>
7736</refnamediv>
7737<refsynopsisdiv>
7738 <title>Synopsis</title>
7739  <funcsynopsis><funcprototype>
7740   <funcdef>struct drm_display_mode * <function>drm_mode_duplicate </function></funcdef>
7741   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
7742   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
7743  </funcprototype></funcsynopsis>
7744</refsynopsisdiv>
7745<refsect1>
7746 <title>Arguments</title>
7747 <variablelist>
7748  <varlistentry>
7749   <term><parameter>dev</parameter></term>
7750   <listitem>
7751    <para>
7752     drm_device to allocate the duplicated mode for
7753    </para>
7754   </listitem>
7755  </varlistentry>
7756  <varlistentry>
7757   <term><parameter>mode</parameter></term>
7758   <listitem>
7759    <para>
7760     mode to duplicate
7761    </para>
7762   </listitem>
7763  </varlistentry>
7764 </variablelist>
7765</refsect1>
7766<refsect1>
7767<title>Description</title>
7768<para>
7769   Just allocate a new mode, copy the existing mode into it, and return
7770   a pointer to it.  Used to create new instances of established modes.
7771</para>
7772</refsect1>
7773<refsect1>
7774<title>Returns</title>
7775<para>
7776   Pointer to duplicated mode on success, NULL on error.
7777</para>
7778</refsect1>
7779</refentry>
7780
7781<refentry id="API-drm-mode-equal">
7782<refentryinfo>
7783 <title>LINUX</title>
7784 <productname>Kernel Hackers Manual</productname>
7785 <date>July 2017</date>
7786</refentryinfo>
7787<refmeta>
7788 <refentrytitle><phrase>drm_mode_equal</phrase></refentrytitle>
7789 <manvolnum>9</manvolnum>
7790 <refmiscinfo class="version">4.1.27</refmiscinfo>
7791</refmeta>
7792<refnamediv>
7793 <refname>drm_mode_equal</refname>
7794 <refpurpose>
7795     test modes for equality
7796 </refpurpose>
7797</refnamediv>
7798<refsynopsisdiv>
7799 <title>Synopsis</title>
7800  <funcsynopsis><funcprototype>
7801   <funcdef>bool <function>drm_mode_equal </function></funcdef>
7802   <paramdef>const struct drm_display_mode * <parameter>mode1</parameter></paramdef>
7803   <paramdef>const struct drm_display_mode * <parameter>mode2</parameter></paramdef>
7804  </funcprototype></funcsynopsis>
7805</refsynopsisdiv>
7806<refsect1>
7807 <title>Arguments</title>
7808 <variablelist>
7809  <varlistentry>
7810   <term><parameter>mode1</parameter></term>
7811   <listitem>
7812    <para>
7813     first mode
7814    </para>
7815   </listitem>
7816  </varlistentry>
7817  <varlistentry>
7818   <term><parameter>mode2</parameter></term>
7819   <listitem>
7820    <para>
7821     second mode
7822    </para>
7823   </listitem>
7824  </varlistentry>
7825 </variablelist>
7826</refsect1>
7827<refsect1>
7828<title>Description</title>
7829<para>
7830   Check to see if <parameter>mode1</parameter> and <parameter>mode2</parameter> are equivalent.
7831</para>
7832</refsect1>
7833<refsect1>
7834<title>Returns</title>
7835<para>
7836   True if the modes are equal, false otherwise.
7837</para>
7838</refsect1>
7839</refentry>
7840
7841<refentry id="API-drm-mode-equal-no-clocks-no-stereo">
7842<refentryinfo>
7843 <title>LINUX</title>
7844 <productname>Kernel Hackers Manual</productname>
7845 <date>July 2017</date>
7846</refentryinfo>
7847<refmeta>
7848 <refentrytitle><phrase>drm_mode_equal_no_clocks_no_stereo</phrase></refentrytitle>
7849 <manvolnum>9</manvolnum>
7850 <refmiscinfo class="version">4.1.27</refmiscinfo>
7851</refmeta>
7852<refnamediv>
7853 <refname>drm_mode_equal_no_clocks_no_stereo</refname>
7854 <refpurpose>
7855     test modes for equality
7856 </refpurpose>
7857</refnamediv>
7858<refsynopsisdiv>
7859 <title>Synopsis</title>
7860  <funcsynopsis><funcprototype>
7861   <funcdef>bool <function>drm_mode_equal_no_clocks_no_stereo </function></funcdef>
7862   <paramdef>const struct drm_display_mode * <parameter>mode1</parameter></paramdef>
7863   <paramdef>const struct drm_display_mode * <parameter>mode2</parameter></paramdef>
7864  </funcprototype></funcsynopsis>
7865</refsynopsisdiv>
7866<refsect1>
7867 <title>Arguments</title>
7868 <variablelist>
7869  <varlistentry>
7870   <term><parameter>mode1</parameter></term>
7871   <listitem>
7872    <para>
7873     first mode
7874    </para>
7875   </listitem>
7876  </varlistentry>
7877  <varlistentry>
7878   <term><parameter>mode2</parameter></term>
7879   <listitem>
7880    <para>
7881     second mode
7882    </para>
7883   </listitem>
7884  </varlistentry>
7885 </variablelist>
7886</refsect1>
7887<refsect1>
7888<title>Description</title>
7889<para>
7890   Check to see if <parameter>mode1</parameter> and <parameter>mode2</parameter> are equivalent, but
7891   don't check the pixel clocks nor the stereo layout.
7892</para>
7893</refsect1>
7894<refsect1>
7895<title>Returns</title>
7896<para>
7897   True if the modes are equal, false otherwise.
7898</para>
7899</refsect1>
7900</refentry>
7901
7902<refentry id="API-drm-mode-validate-basic">
7903<refentryinfo>
7904 <title>LINUX</title>
7905 <productname>Kernel Hackers Manual</productname>
7906 <date>July 2017</date>
7907</refentryinfo>
7908<refmeta>
7909 <refentrytitle><phrase>drm_mode_validate_basic</phrase></refentrytitle>
7910 <manvolnum>9</manvolnum>
7911 <refmiscinfo class="version">4.1.27</refmiscinfo>
7912</refmeta>
7913<refnamediv>
7914 <refname>drm_mode_validate_basic</refname>
7915 <refpurpose>
7916     make sure the mode is somewhat sane
7917 </refpurpose>
7918</refnamediv>
7919<refsynopsisdiv>
7920 <title>Synopsis</title>
7921  <funcsynopsis><funcprototype>
7922   <funcdef>enum drm_mode_status <function>drm_mode_validate_basic </function></funcdef>
7923   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
7924  </funcprototype></funcsynopsis>
7925</refsynopsisdiv>
7926<refsect1>
7927 <title>Arguments</title>
7928 <variablelist>
7929  <varlistentry>
7930   <term><parameter>mode</parameter></term>
7931   <listitem>
7932    <para>
7933     mode to check
7934    </para>
7935   </listitem>
7936  </varlistentry>
7937 </variablelist>
7938</refsect1>
7939<refsect1>
7940<title>Description</title>
7941<para>
7942   Check that the mode timings are at least somewhat reasonable.
7943   Any hardware specific limits are left up for each driver to check.
7944</para>
7945</refsect1>
7946<refsect1>
7947<title>Returns</title>
7948<para>
7949   The mode status
7950</para>
7951</refsect1>
7952</refentry>
7953
7954<refentry id="API-drm-mode-validate-size">
7955<refentryinfo>
7956 <title>LINUX</title>
7957 <productname>Kernel Hackers Manual</productname>
7958 <date>July 2017</date>
7959</refentryinfo>
7960<refmeta>
7961 <refentrytitle><phrase>drm_mode_validate_size</phrase></refentrytitle>
7962 <manvolnum>9</manvolnum>
7963 <refmiscinfo class="version">4.1.27</refmiscinfo>
7964</refmeta>
7965<refnamediv>
7966 <refname>drm_mode_validate_size</refname>
7967 <refpurpose>
7968     make sure modes adhere to size constraints
7969 </refpurpose>
7970</refnamediv>
7971<refsynopsisdiv>
7972 <title>Synopsis</title>
7973  <funcsynopsis><funcprototype>
7974   <funcdef>enum drm_mode_status <function>drm_mode_validate_size </function></funcdef>
7975   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
7976   <paramdef>int <parameter>maxX</parameter></paramdef>
7977   <paramdef>int <parameter>maxY</parameter></paramdef>
7978  </funcprototype></funcsynopsis>
7979</refsynopsisdiv>
7980<refsect1>
7981 <title>Arguments</title>
7982 <variablelist>
7983  <varlistentry>
7984   <term><parameter>mode</parameter></term>
7985   <listitem>
7986    <para>
7987     mode to check
7988    </para>
7989   </listitem>
7990  </varlistentry>
7991  <varlistentry>
7992   <term><parameter>maxX</parameter></term>
7993   <listitem>
7994    <para>
7995     maximum width
7996    </para>
7997   </listitem>
7998  </varlistentry>
7999  <varlistentry>
8000   <term><parameter>maxY</parameter></term>
8001   <listitem>
8002    <para>
8003     maximum height
8004    </para>
8005   </listitem>
8006  </varlistentry>
8007 </variablelist>
8008</refsect1>
8009<refsect1>
8010<title>Description</title>
8011<para>
8012   This function is a helper which can be used to validate modes against size
8013   limitations of the DRM device/connector. If a mode is too big its status
8014   member is updated with the appropriate validation failure code. The list
8015   itself is not changed.
8016</para>
8017</refsect1>
8018<refsect1>
8019<title>Returns</title>
8020<para>
8021   The mode status
8022</para>
8023</refsect1>
8024</refentry>
8025
8026<refentry id="API-drm-mode-prune-invalid">
8027<refentryinfo>
8028 <title>LINUX</title>
8029 <productname>Kernel Hackers Manual</productname>
8030 <date>July 2017</date>
8031</refentryinfo>
8032<refmeta>
8033 <refentrytitle><phrase>drm_mode_prune_invalid</phrase></refentrytitle>
8034 <manvolnum>9</manvolnum>
8035 <refmiscinfo class="version">4.1.27</refmiscinfo>
8036</refmeta>
8037<refnamediv>
8038 <refname>drm_mode_prune_invalid</refname>
8039 <refpurpose>
8040     remove invalid modes from mode list
8041 </refpurpose>
8042</refnamediv>
8043<refsynopsisdiv>
8044 <title>Synopsis</title>
8045  <funcsynopsis><funcprototype>
8046   <funcdef>void <function>drm_mode_prune_invalid </function></funcdef>
8047   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
8048   <paramdef>struct list_head * <parameter>mode_list</parameter></paramdef>
8049   <paramdef>bool <parameter>verbose</parameter></paramdef>
8050  </funcprototype></funcsynopsis>
8051</refsynopsisdiv>
8052<refsect1>
8053 <title>Arguments</title>
8054 <variablelist>
8055  <varlistentry>
8056   <term><parameter>dev</parameter></term>
8057   <listitem>
8058    <para>
8059     DRM device
8060    </para>
8061   </listitem>
8062  </varlistentry>
8063  <varlistentry>
8064   <term><parameter>mode_list</parameter></term>
8065   <listitem>
8066    <para>
8067     list of modes to check
8068    </para>
8069   </listitem>
8070  </varlistentry>
8071  <varlistentry>
8072   <term><parameter>verbose</parameter></term>
8073   <listitem>
8074    <para>
8075     be verbose about it
8076    </para>
8077   </listitem>
8078  </varlistentry>
8079 </variablelist>
8080</refsect1>
8081<refsect1>
8082<title>Description</title>
8083<para>
8084   This helper function can be used to prune a display mode list after
8085   validation has been completed. All modes who's status is not MODE_OK will be
8086   removed from the list, and if <parameter>verbose</parameter> the status code and mode name is also
8087   printed to dmesg.
8088</para>
8089</refsect1>
8090</refentry>
8091
8092<refentry id="API-drm-mode-sort">
8093<refentryinfo>
8094 <title>LINUX</title>
8095 <productname>Kernel Hackers Manual</productname>
8096 <date>July 2017</date>
8097</refentryinfo>
8098<refmeta>
8099 <refentrytitle><phrase>drm_mode_sort</phrase></refentrytitle>
8100 <manvolnum>9</manvolnum>
8101 <refmiscinfo class="version">4.1.27</refmiscinfo>
8102</refmeta>
8103<refnamediv>
8104 <refname>drm_mode_sort</refname>
8105 <refpurpose>
8106     sort mode list
8107 </refpurpose>
8108</refnamediv>
8109<refsynopsisdiv>
8110 <title>Synopsis</title>
8111  <funcsynopsis><funcprototype>
8112   <funcdef>void <function>drm_mode_sort </function></funcdef>
8113   <paramdef>struct list_head * <parameter>mode_list</parameter></paramdef>
8114  </funcprototype></funcsynopsis>
8115</refsynopsisdiv>
8116<refsect1>
8117 <title>Arguments</title>
8118 <variablelist>
8119  <varlistentry>
8120   <term><parameter>mode_list</parameter></term>
8121   <listitem>
8122    <para>
8123     list of drm_display_mode structures to sort
8124    </para>
8125   </listitem>
8126  </varlistentry>
8127 </variablelist>
8128</refsect1>
8129<refsect1>
8130<title>Description</title>
8131<para>
8132   Sort <parameter>mode_list</parameter> by favorability, moving good modes to the head of the list.
8133</para>
8134</refsect1>
8135</refentry>
8136
8137<refentry id="API-drm-mode-connector-list-update">
8138<refentryinfo>
8139 <title>LINUX</title>
8140 <productname>Kernel Hackers Manual</productname>
8141 <date>July 2017</date>
8142</refentryinfo>
8143<refmeta>
8144 <refentrytitle><phrase>drm_mode_connector_list_update</phrase></refentrytitle>
8145 <manvolnum>9</manvolnum>
8146 <refmiscinfo class="version">4.1.27</refmiscinfo>
8147</refmeta>
8148<refnamediv>
8149 <refname>drm_mode_connector_list_update</refname>
8150 <refpurpose>
8151     update the mode list for the connector
8152 </refpurpose>
8153</refnamediv>
8154<refsynopsisdiv>
8155 <title>Synopsis</title>
8156  <funcsynopsis><funcprototype>
8157   <funcdef>void <function>drm_mode_connector_list_update </function></funcdef>
8158   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
8159   <paramdef>bool <parameter>merge_type_bits</parameter></paramdef>
8160  </funcprototype></funcsynopsis>
8161</refsynopsisdiv>
8162<refsect1>
8163 <title>Arguments</title>
8164 <variablelist>
8165  <varlistentry>
8166   <term><parameter>connector</parameter></term>
8167   <listitem>
8168    <para>
8169     the connector to update
8170    </para>
8171   </listitem>
8172  </varlistentry>
8173  <varlistentry>
8174   <term><parameter>merge_type_bits</parameter></term>
8175   <listitem>
8176    <para>
8177     whether to merge or overwrite type bits
8178    </para>
8179   </listitem>
8180  </varlistentry>
8181 </variablelist>
8182</refsect1>
8183<refsect1>
8184<title>Description</title>
8185<para>
8186   This moves the modes from the <parameter>connector</parameter> probed_modes list
8187   to the actual mode list. It compares the probed mode against the current
8188   list and only adds different/new modes.
8189   </para><para>
8190
8191   This is just a helper functions doesn't validate any modes itself and also
8192   doesn't prune any invalid modes. Callers need to do that themselves.
8193</para>
8194</refsect1>
8195</refentry>
8196
8197<refentry id="API-drm-mode-parse-command-line-for-connector">
8198<refentryinfo>
8199 <title>LINUX</title>
8200 <productname>Kernel Hackers Manual</productname>
8201 <date>July 2017</date>
8202</refentryinfo>
8203<refmeta>
8204 <refentrytitle><phrase>drm_mode_parse_command_line_for_connector</phrase></refentrytitle>
8205 <manvolnum>9</manvolnum>
8206 <refmiscinfo class="version">4.1.27</refmiscinfo>
8207</refmeta>
8208<refnamediv>
8209 <refname>drm_mode_parse_command_line_for_connector</refname>
8210 <refpurpose>
8211     parse command line modeline for connector
8212 </refpurpose>
8213</refnamediv>
8214<refsynopsisdiv>
8215 <title>Synopsis</title>
8216  <funcsynopsis><funcprototype>
8217   <funcdef>bool <function>drm_mode_parse_command_line_for_connector </function></funcdef>
8218   <paramdef>const char * <parameter>mode_option</parameter></paramdef>
8219   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
8220   <paramdef>struct drm_cmdline_mode * <parameter>mode</parameter></paramdef>
8221  </funcprototype></funcsynopsis>
8222</refsynopsisdiv>
8223<refsect1>
8224 <title>Arguments</title>
8225 <variablelist>
8226  <varlistentry>
8227   <term><parameter>mode_option</parameter></term>
8228   <listitem>
8229    <para>
8230     optional per connector mode option
8231    </para>
8232   </listitem>
8233  </varlistentry>
8234  <varlistentry>
8235   <term><parameter>connector</parameter></term>
8236   <listitem>
8237    <para>
8238     connector to parse modeline for
8239    </para>
8240   </listitem>
8241  </varlistentry>
8242  <varlistentry>
8243   <term><parameter>mode</parameter></term>
8244   <listitem>
8245    <para>
8246     preallocated drm_cmdline_mode structure to fill out
8247    </para>
8248   </listitem>
8249  </varlistentry>
8250 </variablelist>
8251</refsect1>
8252<refsect1>
8253<title>Description</title>
8254<para>
8255   This parses <parameter>mode_option</parameter> command line modeline for modes and options to
8256   configure the connector. If <parameter>mode_option</parameter> is NULL the default command line
8257   modeline in fb_mode_option will be parsed instead.
8258   </para><para>
8259
8260   This uses the same parameters as the fb modedb.c, except for an extra
8261   force-enable, force-enable-digital and force-disable bit at the end:
8262   </para><para>
8263
8264   &lt;xres&gt;x&lt;yres&gt;[M][R][-&lt;bpp&gt;][@&lt;refresh&gt;][i][m][eDd]
8265   </para><para>
8266
8267   The intermediate drm_cmdline_mode structure is required to store additional
8268   options from the command line modline like the force-enable/disable flag.
8269</para>
8270</refsect1>
8271<refsect1>
8272<title>Returns</title>
8273<para>
8274   True if a valid modeline has been parsed, false otherwise.
8275</para>
8276</refsect1>
8277</refentry>
8278
8279<refentry id="API-drm-mode-create-from-cmdline-mode">
8280<refentryinfo>
8281 <title>LINUX</title>
8282 <productname>Kernel Hackers Manual</productname>
8283 <date>July 2017</date>
8284</refentryinfo>
8285<refmeta>
8286 <refentrytitle><phrase>drm_mode_create_from_cmdline_mode</phrase></refentrytitle>
8287 <manvolnum>9</manvolnum>
8288 <refmiscinfo class="version">4.1.27</refmiscinfo>
8289</refmeta>
8290<refnamediv>
8291 <refname>drm_mode_create_from_cmdline_mode</refname>
8292 <refpurpose>
8293     convert a command line modeline into a DRM display mode
8294 </refpurpose>
8295</refnamediv>
8296<refsynopsisdiv>
8297 <title>Synopsis</title>
8298  <funcsynopsis><funcprototype>
8299   <funcdef>struct drm_display_mode * <function>drm_mode_create_from_cmdline_mode </function></funcdef>
8300   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
8301   <paramdef>struct drm_cmdline_mode * <parameter>cmd</parameter></paramdef>
8302  </funcprototype></funcsynopsis>
8303</refsynopsisdiv>
8304<refsect1>
8305 <title>Arguments</title>
8306 <variablelist>
8307  <varlistentry>
8308   <term><parameter>dev</parameter></term>
8309   <listitem>
8310    <para>
8311     DRM device to create the new mode for
8312    </para>
8313   </listitem>
8314  </varlistentry>
8315  <varlistentry>
8316   <term><parameter>cmd</parameter></term>
8317   <listitem>
8318    <para>
8319     input command line modeline
8320    </para>
8321   </listitem>
8322  </varlistentry>
8323 </variablelist>
8324</refsect1>
8325<refsect1>
8326<title>Returns</title>
8327<para>
8328   Pointer to converted mode on success, NULL on error.
8329</para>
8330</refsect1>
8331</refentry>
8332
8333    </sect2>
8334    <sect2>
8335      <title>Atomic Mode Setting Function Reference</title>
8336<!-- drivers/gpu/drm/drm_atomic.c -->
8337<refentry id="API-drm-atomic-state-alloc">
8338<refentryinfo>
8339 <title>LINUX</title>
8340 <productname>Kernel Hackers Manual</productname>
8341 <date>July 2017</date>
8342</refentryinfo>
8343<refmeta>
8344 <refentrytitle><phrase>drm_atomic_state_alloc</phrase></refentrytitle>
8345 <manvolnum>9</manvolnum>
8346 <refmiscinfo class="version">4.1.27</refmiscinfo>
8347</refmeta>
8348<refnamediv>
8349 <refname>drm_atomic_state_alloc</refname>
8350 <refpurpose>
8351  allocate atomic state
8352 </refpurpose>
8353</refnamediv>
8354<refsynopsisdiv>
8355 <title>Synopsis</title>
8356  <funcsynopsis><funcprototype>
8357   <funcdef>struct drm_atomic_state * <function>drm_atomic_state_alloc </function></funcdef>
8358   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
8359  </funcprototype></funcsynopsis>
8360</refsynopsisdiv>
8361<refsect1>
8362 <title>Arguments</title>
8363 <variablelist>
8364  <varlistentry>
8365   <term><parameter>dev</parameter></term>
8366   <listitem>
8367    <para>
8368     DRM device
8369    </para>
8370   </listitem>
8371  </varlistentry>
8372 </variablelist>
8373</refsect1>
8374<refsect1>
8375<title>Description</title>
8376<para>
8377   This allocates an empty atomic state to track updates.
8378</para>
8379</refsect1>
8380</refentry>
8381
8382<refentry id="API-drm-atomic-state-clear">
8383<refentryinfo>
8384 <title>LINUX</title>
8385 <productname>Kernel Hackers Manual</productname>
8386 <date>July 2017</date>
8387</refentryinfo>
8388<refmeta>
8389 <refentrytitle><phrase>drm_atomic_state_clear</phrase></refentrytitle>
8390 <manvolnum>9</manvolnum>
8391 <refmiscinfo class="version">4.1.27</refmiscinfo>
8392</refmeta>
8393<refnamediv>
8394 <refname>drm_atomic_state_clear</refname>
8395 <refpurpose>
8396     clear state object
8397 </refpurpose>
8398</refnamediv>
8399<refsynopsisdiv>
8400 <title>Synopsis</title>
8401  <funcsynopsis><funcprototype>
8402   <funcdef>void <function>drm_atomic_state_clear </function></funcdef>
8403   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
8404  </funcprototype></funcsynopsis>
8405</refsynopsisdiv>
8406<refsect1>
8407 <title>Arguments</title>
8408 <variablelist>
8409  <varlistentry>
8410   <term><parameter>state</parameter></term>
8411   <listitem>
8412    <para>
8413     atomic state
8414    </para>
8415   </listitem>
8416  </varlistentry>
8417 </variablelist>
8418</refsect1>
8419<refsect1>
8420<title>Description</title>
8421<para>
8422   When the w/w mutex algorithm detects a deadlock we need to back off and drop
8423   all locks. So someone else could sneak in and change the current modeset
8424   configuration. Which means that all the state assembled in <parameter>state</parameter> is no
8425   longer an atomic update to the current state, but to some arbitrary earlier
8426   state. Which could break assumptions the driver's -&gt;atomic_check likely
8427   relies on.
8428   </para><para>
8429
8430   Hence we must clear all cached state and completely start over, using this
8431   function.
8432</para>
8433</refsect1>
8434</refentry>
8435
8436<refentry id="API-drm-atomic-state-free">
8437<refentryinfo>
8438 <title>LINUX</title>
8439 <productname>Kernel Hackers Manual</productname>
8440 <date>July 2017</date>
8441</refentryinfo>
8442<refmeta>
8443 <refentrytitle><phrase>drm_atomic_state_free</phrase></refentrytitle>
8444 <manvolnum>9</manvolnum>
8445 <refmiscinfo class="version">4.1.27</refmiscinfo>
8446</refmeta>
8447<refnamediv>
8448 <refname>drm_atomic_state_free</refname>
8449 <refpurpose>
8450     free all memory for an atomic state
8451 </refpurpose>
8452</refnamediv>
8453<refsynopsisdiv>
8454 <title>Synopsis</title>
8455  <funcsynopsis><funcprototype>
8456   <funcdef>void <function>drm_atomic_state_free </function></funcdef>
8457   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
8458  </funcprototype></funcsynopsis>
8459</refsynopsisdiv>
8460<refsect1>
8461 <title>Arguments</title>
8462 <variablelist>
8463  <varlistentry>
8464   <term><parameter>state</parameter></term>
8465   <listitem>
8466    <para>
8467     atomic state to deallocate
8468    </para>
8469   </listitem>
8470  </varlistentry>
8471 </variablelist>
8472</refsect1>
8473<refsect1>
8474<title>Description</title>
8475<para>
8476   This frees all memory associated with an atomic state, including all the
8477   per-object state for planes, crtcs and connectors.
8478</para>
8479</refsect1>
8480</refentry>
8481
8482<refentry id="API-drm-atomic-get-crtc-state">
8483<refentryinfo>
8484 <title>LINUX</title>
8485 <productname>Kernel Hackers Manual</productname>
8486 <date>July 2017</date>
8487</refentryinfo>
8488<refmeta>
8489 <refentrytitle><phrase>drm_atomic_get_crtc_state</phrase></refentrytitle>
8490 <manvolnum>9</manvolnum>
8491 <refmiscinfo class="version">4.1.27</refmiscinfo>
8492</refmeta>
8493<refnamediv>
8494 <refname>drm_atomic_get_crtc_state</refname>
8495 <refpurpose>
8496     get crtc state
8497 </refpurpose>
8498</refnamediv>
8499<refsynopsisdiv>
8500 <title>Synopsis</title>
8501  <funcsynopsis><funcprototype>
8502   <funcdef>struct drm_crtc_state * <function>drm_atomic_get_crtc_state </function></funcdef>
8503   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
8504   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
8505  </funcprototype></funcsynopsis>
8506</refsynopsisdiv>
8507<refsect1>
8508 <title>Arguments</title>
8509 <variablelist>
8510  <varlistentry>
8511   <term><parameter>state</parameter></term>
8512   <listitem>
8513    <para>
8514     global atomic state object
8515    </para>
8516   </listitem>
8517  </varlistentry>
8518  <varlistentry>
8519   <term><parameter>crtc</parameter></term>
8520   <listitem>
8521    <para>
8522     crtc to get state object for
8523    </para>
8524   </listitem>
8525  </varlistentry>
8526 </variablelist>
8527</refsect1>
8528<refsect1>
8529<title>Description</title>
8530<para>
8531   This function returns the crtc state for the given crtc, allocating it if
8532   needed. It will also grab the relevant crtc lock to make sure that the state
8533   is consistent.
8534</para>
8535</refsect1>
8536<refsect1>
8537<title>Returns</title>
8538<para>
8539   </para><para>
8540
8541   Either the allocated state or the error code encoded into the pointer. When
8542   the error is EDEADLK then the w/w mutex code has detected a deadlock and the
8543   entire atomic sequence must be restarted. All other errors are fatal.
8544</para>
8545</refsect1>
8546</refentry>
8547
8548<refentry id="API-drm-atomic-crtc-set-property">
8549<refentryinfo>
8550 <title>LINUX</title>
8551 <productname>Kernel Hackers Manual</productname>
8552 <date>July 2017</date>
8553</refentryinfo>
8554<refmeta>
8555 <refentrytitle><phrase>drm_atomic_crtc_set_property</phrase></refentrytitle>
8556 <manvolnum>9</manvolnum>
8557 <refmiscinfo class="version">4.1.27</refmiscinfo>
8558</refmeta>
8559<refnamediv>
8560 <refname>drm_atomic_crtc_set_property</refname>
8561 <refpurpose>
8562     set property on CRTC
8563 </refpurpose>
8564</refnamediv>
8565<refsynopsisdiv>
8566 <title>Synopsis</title>
8567  <funcsynopsis><funcprototype>
8568   <funcdef>int <function>drm_atomic_crtc_set_property </function></funcdef>
8569   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
8570   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
8571   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
8572   <paramdef>uint64_t <parameter>val</parameter></paramdef>
8573  </funcprototype></funcsynopsis>
8574</refsynopsisdiv>
8575<refsect1>
8576 <title>Arguments</title>
8577 <variablelist>
8578  <varlistentry>
8579   <term><parameter>crtc</parameter></term>
8580   <listitem>
8581    <para>
8582     the drm CRTC to set a property on
8583    </para>
8584   </listitem>
8585  </varlistentry>
8586  <varlistentry>
8587   <term><parameter>state</parameter></term>
8588   <listitem>
8589    <para>
8590     the state object to update with the new property value
8591    </para>
8592   </listitem>
8593  </varlistentry>
8594  <varlistentry>
8595   <term><parameter>property</parameter></term>
8596   <listitem>
8597    <para>
8598     the property to set
8599    </para>
8600   </listitem>
8601  </varlistentry>
8602  <varlistentry>
8603   <term><parameter>val</parameter></term>
8604   <listitem>
8605    <para>
8606     the new property value
8607    </para>
8608   </listitem>
8609  </varlistentry>
8610 </variablelist>
8611</refsect1>
8612<refsect1>
8613<title>Description</title>
8614<para>
8615   Use this instead of calling crtc-&gt;atomic_set_property directly.
8616   This function handles generic/core properties and calls out to
8617   driver's -&gt;<function>atomic_set_property</function> for driver properties.  To ensure
8618   consistent behavior you must call this function rather than the
8619   driver hook directly.
8620</para>
8621</refsect1>
8622<refsect1>
8623<title>RETURNS</title>
8624<para>
8625   Zero on success, error code on failure
8626</para>
8627</refsect1>
8628</refentry>
8629
8630<refentry id="API-drm-atomic-get-plane-state">
8631<refentryinfo>
8632 <title>LINUX</title>
8633 <productname>Kernel Hackers Manual</productname>
8634 <date>July 2017</date>
8635</refentryinfo>
8636<refmeta>
8637 <refentrytitle><phrase>drm_atomic_get_plane_state</phrase></refentrytitle>
8638 <manvolnum>9</manvolnum>
8639 <refmiscinfo class="version">4.1.27</refmiscinfo>
8640</refmeta>
8641<refnamediv>
8642 <refname>drm_atomic_get_plane_state</refname>
8643 <refpurpose>
8644     get plane state
8645 </refpurpose>
8646</refnamediv>
8647<refsynopsisdiv>
8648 <title>Synopsis</title>
8649  <funcsynopsis><funcprototype>
8650   <funcdef>struct drm_plane_state * <function>drm_atomic_get_plane_state </function></funcdef>
8651   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
8652   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
8653  </funcprototype></funcsynopsis>
8654</refsynopsisdiv>
8655<refsect1>
8656 <title>Arguments</title>
8657 <variablelist>
8658  <varlistentry>
8659   <term><parameter>state</parameter></term>
8660   <listitem>
8661    <para>
8662     global atomic state object
8663    </para>
8664   </listitem>
8665  </varlistentry>
8666  <varlistentry>
8667   <term><parameter>plane</parameter></term>
8668   <listitem>
8669    <para>
8670     plane to get state object for
8671    </para>
8672   </listitem>
8673  </varlistentry>
8674 </variablelist>
8675</refsect1>
8676<refsect1>
8677<title>Description</title>
8678<para>
8679   This function returns the plane state for the given plane, allocating it if
8680   needed. It will also grab the relevant plane lock to make sure that the state
8681   is consistent.
8682</para>
8683</refsect1>
8684<refsect1>
8685<title>Returns</title>
8686<para>
8687   </para><para>
8688
8689   Either the allocated state or the error code encoded into the pointer. When
8690   the error is EDEADLK then the w/w mutex code has detected a deadlock and the
8691   entire atomic sequence must be restarted. All other errors are fatal.
8692</para>
8693</refsect1>
8694</refentry>
8695
8696<refentry id="API-drm-atomic-plane-set-property">
8697<refentryinfo>
8698 <title>LINUX</title>
8699 <productname>Kernel Hackers Manual</productname>
8700 <date>July 2017</date>
8701</refentryinfo>
8702<refmeta>
8703 <refentrytitle><phrase>drm_atomic_plane_set_property</phrase></refentrytitle>
8704 <manvolnum>9</manvolnum>
8705 <refmiscinfo class="version">4.1.27</refmiscinfo>
8706</refmeta>
8707<refnamediv>
8708 <refname>drm_atomic_plane_set_property</refname>
8709 <refpurpose>
8710     set property on plane
8711 </refpurpose>
8712</refnamediv>
8713<refsynopsisdiv>
8714 <title>Synopsis</title>
8715  <funcsynopsis><funcprototype>
8716   <funcdef>int <function>drm_atomic_plane_set_property </function></funcdef>
8717   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
8718   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
8719   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
8720   <paramdef>uint64_t <parameter>val</parameter></paramdef>
8721  </funcprototype></funcsynopsis>
8722</refsynopsisdiv>
8723<refsect1>
8724 <title>Arguments</title>
8725 <variablelist>
8726  <varlistentry>
8727   <term><parameter>plane</parameter></term>
8728   <listitem>
8729    <para>
8730     the drm plane to set a property on
8731    </para>
8732   </listitem>
8733  </varlistentry>
8734  <varlistentry>
8735   <term><parameter>state</parameter></term>
8736   <listitem>
8737    <para>
8738     the state object to update with the new property value
8739    </para>
8740   </listitem>
8741  </varlistentry>
8742  <varlistentry>
8743   <term><parameter>property</parameter></term>
8744   <listitem>
8745    <para>
8746     the property to set
8747    </para>
8748   </listitem>
8749  </varlistentry>
8750  <varlistentry>
8751   <term><parameter>val</parameter></term>
8752   <listitem>
8753    <para>
8754     the new property value
8755    </para>
8756   </listitem>
8757  </varlistentry>
8758 </variablelist>
8759</refsect1>
8760<refsect1>
8761<title>Description</title>
8762<para>
8763   Use this instead of calling plane-&gt;atomic_set_property directly.
8764   This function handles generic/core properties and calls out to
8765   driver's -&gt;<function>atomic_set_property</function> for driver properties.  To ensure
8766   consistent behavior you must call this function rather than the
8767   driver hook directly.
8768</para>
8769</refsect1>
8770<refsect1>
8771<title>RETURNS</title>
8772<para>
8773   Zero on success, error code on failure
8774</para>
8775</refsect1>
8776</refentry>
8777
8778<refentry id="API-drm-atomic-get-connector-state">
8779<refentryinfo>
8780 <title>LINUX</title>
8781 <productname>Kernel Hackers Manual</productname>
8782 <date>July 2017</date>
8783</refentryinfo>
8784<refmeta>
8785 <refentrytitle><phrase>drm_atomic_get_connector_state</phrase></refentrytitle>
8786 <manvolnum>9</manvolnum>
8787 <refmiscinfo class="version">4.1.27</refmiscinfo>
8788</refmeta>
8789<refnamediv>
8790 <refname>drm_atomic_get_connector_state</refname>
8791 <refpurpose>
8792     get connector state
8793 </refpurpose>
8794</refnamediv>
8795<refsynopsisdiv>
8796 <title>Synopsis</title>
8797  <funcsynopsis><funcprototype>
8798   <funcdef>struct drm_connector_state * <function>drm_atomic_get_connector_state </function></funcdef>
8799   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
8800   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
8801  </funcprototype></funcsynopsis>
8802</refsynopsisdiv>
8803<refsect1>
8804 <title>Arguments</title>
8805 <variablelist>
8806  <varlistentry>
8807   <term><parameter>state</parameter></term>
8808   <listitem>
8809    <para>
8810     global atomic state object
8811    </para>
8812   </listitem>
8813  </varlistentry>
8814  <varlistentry>
8815   <term><parameter>connector</parameter></term>
8816   <listitem>
8817    <para>
8818     connector to get state object for
8819    </para>
8820   </listitem>
8821  </varlistentry>
8822 </variablelist>
8823</refsect1>
8824<refsect1>
8825<title>Description</title>
8826<para>
8827   This function returns the connector state for the given connector,
8828   allocating it if needed. It will also grab the relevant connector lock to
8829   make sure that the state is consistent.
8830</para>
8831</refsect1>
8832<refsect1>
8833<title>Returns</title>
8834<para>
8835   </para><para>
8836
8837   Either the allocated state or the error code encoded into the pointer. When
8838   the error is EDEADLK then the w/w mutex code has detected a deadlock and the
8839   entire atomic sequence must be restarted. All other errors are fatal.
8840</para>
8841</refsect1>
8842</refentry>
8843
8844<refentry id="API-drm-atomic-connector-set-property">
8845<refentryinfo>
8846 <title>LINUX</title>
8847 <productname>Kernel Hackers Manual</productname>
8848 <date>July 2017</date>
8849</refentryinfo>
8850<refmeta>
8851 <refentrytitle><phrase>drm_atomic_connector_set_property</phrase></refentrytitle>
8852 <manvolnum>9</manvolnum>
8853 <refmiscinfo class="version">4.1.27</refmiscinfo>
8854</refmeta>
8855<refnamediv>
8856 <refname>drm_atomic_connector_set_property</refname>
8857 <refpurpose>
8858     set property on connector.
8859 </refpurpose>
8860</refnamediv>
8861<refsynopsisdiv>
8862 <title>Synopsis</title>
8863  <funcsynopsis><funcprototype>
8864   <funcdef>int <function>drm_atomic_connector_set_property </function></funcdef>
8865   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
8866   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
8867   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
8868   <paramdef>uint64_t <parameter>val</parameter></paramdef>
8869  </funcprototype></funcsynopsis>
8870</refsynopsisdiv>
8871<refsect1>
8872 <title>Arguments</title>
8873 <variablelist>
8874  <varlistentry>
8875   <term><parameter>connector</parameter></term>
8876   <listitem>
8877    <para>
8878     the drm connector to set a property on
8879    </para>
8880   </listitem>
8881  </varlistentry>
8882  <varlistentry>
8883   <term><parameter>state</parameter></term>
8884   <listitem>
8885    <para>
8886     the state object to update with the new property value
8887    </para>
8888   </listitem>
8889  </varlistentry>
8890  <varlistentry>
8891   <term><parameter>property</parameter></term>
8892   <listitem>
8893    <para>
8894     the property to set
8895    </para>
8896   </listitem>
8897  </varlistentry>
8898  <varlistentry>
8899   <term><parameter>val</parameter></term>
8900   <listitem>
8901    <para>
8902     the new property value
8903    </para>
8904   </listitem>
8905  </varlistentry>
8906 </variablelist>
8907</refsect1>
8908<refsect1>
8909<title>Description</title>
8910<para>
8911   Use this instead of calling connector-&gt;atomic_set_property directly.
8912   This function handles generic/core properties and calls out to
8913   driver's -&gt;<function>atomic_set_property</function> for driver properties.  To ensure
8914   consistent behavior you must call this function rather than the
8915   driver hook directly.
8916</para>
8917</refsect1>
8918<refsect1>
8919<title>RETURNS</title>
8920<para>
8921   Zero on success, error code on failure
8922</para>
8923</refsect1>
8924</refentry>
8925
8926<refentry id="API-drm-atomic-set-crtc-for-plane">
8927<refentryinfo>
8928 <title>LINUX</title>
8929 <productname>Kernel Hackers Manual</productname>
8930 <date>July 2017</date>
8931</refentryinfo>
8932<refmeta>
8933 <refentrytitle><phrase>drm_atomic_set_crtc_for_plane</phrase></refentrytitle>
8934 <manvolnum>9</manvolnum>
8935 <refmiscinfo class="version">4.1.27</refmiscinfo>
8936</refmeta>
8937<refnamediv>
8938 <refname>drm_atomic_set_crtc_for_plane</refname>
8939 <refpurpose>
8940     set crtc for plane
8941 </refpurpose>
8942</refnamediv>
8943<refsynopsisdiv>
8944 <title>Synopsis</title>
8945  <funcsynopsis><funcprototype>
8946   <funcdef>int <function>drm_atomic_set_crtc_for_plane </function></funcdef>
8947   <paramdef>struct drm_plane_state * <parameter>plane_state</parameter></paramdef>
8948   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
8949  </funcprototype></funcsynopsis>
8950</refsynopsisdiv>
8951<refsect1>
8952 <title>Arguments</title>
8953 <variablelist>
8954  <varlistentry>
8955   <term><parameter>plane_state</parameter></term>
8956   <listitem>
8957    <para>
8958     the plane whose incoming state to update
8959    </para>
8960   </listitem>
8961  </varlistentry>
8962  <varlistentry>
8963   <term><parameter>crtc</parameter></term>
8964   <listitem>
8965    <para>
8966     crtc to use for the plane
8967    </para>
8968   </listitem>
8969  </varlistentry>
8970 </variablelist>
8971</refsect1>
8972<refsect1>
8973<title>Description</title>
8974<para>
8975   Changing the assigned crtc for a plane requires us to grab the lock and state
8976   for the new crtc, as needed. This function takes care of all these details
8977   besides updating the pointer in the state object itself.
8978</para>
8979</refsect1>
8980<refsect1>
8981<title>Returns</title>
8982<para>
8983   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
8984   then the w/w mutex code has detected a deadlock and the entire atomic
8985   sequence must be restarted. All other errors are fatal.
8986</para>
8987</refsect1>
8988</refentry>
8989
8990<refentry id="API-drm-atomic-set-fb-for-plane">
8991<refentryinfo>
8992 <title>LINUX</title>
8993 <productname>Kernel Hackers Manual</productname>
8994 <date>July 2017</date>
8995</refentryinfo>
8996<refmeta>
8997 <refentrytitle><phrase>drm_atomic_set_fb_for_plane</phrase></refentrytitle>
8998 <manvolnum>9</manvolnum>
8999 <refmiscinfo class="version">4.1.27</refmiscinfo>
9000</refmeta>
9001<refnamediv>
9002 <refname>drm_atomic_set_fb_for_plane</refname>
9003 <refpurpose>
9004     set framebuffer for plane
9005 </refpurpose>
9006</refnamediv>
9007<refsynopsisdiv>
9008 <title>Synopsis</title>
9009  <funcsynopsis><funcprototype>
9010   <funcdef>void <function>drm_atomic_set_fb_for_plane </function></funcdef>
9011   <paramdef>struct drm_plane_state * <parameter>plane_state</parameter></paramdef>
9012   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
9013  </funcprototype></funcsynopsis>
9014</refsynopsisdiv>
9015<refsect1>
9016 <title>Arguments</title>
9017 <variablelist>
9018  <varlistentry>
9019   <term><parameter>plane_state</parameter></term>
9020   <listitem>
9021    <para>
9022     atomic state object for the plane
9023    </para>
9024   </listitem>
9025  </varlistentry>
9026  <varlistentry>
9027   <term><parameter>fb</parameter></term>
9028   <listitem>
9029    <para>
9030     fb to use for the plane
9031    </para>
9032   </listitem>
9033  </varlistentry>
9034 </variablelist>
9035</refsect1>
9036<refsect1>
9037<title>Description</title>
9038<para>
9039   Changing the assigned framebuffer for a plane requires us to grab a reference
9040   to the new fb and drop the reference to the old fb, if there is one. This
9041   function takes care of all these details besides updating the pointer in the
9042   state object itself.
9043</para>
9044</refsect1>
9045</refentry>
9046
9047<refentry id="API-drm-atomic-set-crtc-for-connector">
9048<refentryinfo>
9049 <title>LINUX</title>
9050 <productname>Kernel Hackers Manual</productname>
9051 <date>July 2017</date>
9052</refentryinfo>
9053<refmeta>
9054 <refentrytitle><phrase>drm_atomic_set_crtc_for_connector</phrase></refentrytitle>
9055 <manvolnum>9</manvolnum>
9056 <refmiscinfo class="version">4.1.27</refmiscinfo>
9057</refmeta>
9058<refnamediv>
9059 <refname>drm_atomic_set_crtc_for_connector</refname>
9060 <refpurpose>
9061     set crtc for connector
9062 </refpurpose>
9063</refnamediv>
9064<refsynopsisdiv>
9065 <title>Synopsis</title>
9066  <funcsynopsis><funcprototype>
9067   <funcdef>int <function>drm_atomic_set_crtc_for_connector </function></funcdef>
9068   <paramdef>struct drm_connector_state * <parameter>conn_state</parameter></paramdef>
9069   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
9070  </funcprototype></funcsynopsis>
9071</refsynopsisdiv>
9072<refsect1>
9073 <title>Arguments</title>
9074 <variablelist>
9075  <varlistentry>
9076   <term><parameter>conn_state</parameter></term>
9077   <listitem>
9078    <para>
9079     atomic state object for the connector
9080    </para>
9081   </listitem>
9082  </varlistentry>
9083  <varlistentry>
9084   <term><parameter>crtc</parameter></term>
9085   <listitem>
9086    <para>
9087     crtc to use for the connector
9088    </para>
9089   </listitem>
9090  </varlistentry>
9091 </variablelist>
9092</refsect1>
9093<refsect1>
9094<title>Description</title>
9095<para>
9096   Changing the assigned crtc for a connector requires us to grab the lock and
9097   state for the new crtc, as needed. This function takes care of all these
9098   details besides updating the pointer in the state object itself.
9099</para>
9100</refsect1>
9101<refsect1>
9102<title>Returns</title>
9103<para>
9104   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
9105   then the w/w mutex code has detected a deadlock and the entire atomic
9106   sequence must be restarted. All other errors are fatal.
9107</para>
9108</refsect1>
9109</refentry>
9110
9111<refentry id="API-drm-atomic-add-affected-connectors">
9112<refentryinfo>
9113 <title>LINUX</title>
9114 <productname>Kernel Hackers Manual</productname>
9115 <date>July 2017</date>
9116</refentryinfo>
9117<refmeta>
9118 <refentrytitle><phrase>drm_atomic_add_affected_connectors</phrase></refentrytitle>
9119 <manvolnum>9</manvolnum>
9120 <refmiscinfo class="version">4.1.27</refmiscinfo>
9121</refmeta>
9122<refnamediv>
9123 <refname>drm_atomic_add_affected_connectors</refname>
9124 <refpurpose>
9125     add connectors for crtc
9126 </refpurpose>
9127</refnamediv>
9128<refsynopsisdiv>
9129 <title>Synopsis</title>
9130  <funcsynopsis><funcprototype>
9131   <funcdef>int <function>drm_atomic_add_affected_connectors </function></funcdef>
9132   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
9133   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
9134  </funcprototype></funcsynopsis>
9135</refsynopsisdiv>
9136<refsect1>
9137 <title>Arguments</title>
9138 <variablelist>
9139  <varlistentry>
9140   <term><parameter>state</parameter></term>
9141   <listitem>
9142    <para>
9143     atomic state
9144    </para>
9145   </listitem>
9146  </varlistentry>
9147  <varlistentry>
9148   <term><parameter>crtc</parameter></term>
9149   <listitem>
9150    <para>
9151     DRM crtc
9152    </para>
9153   </listitem>
9154  </varlistentry>
9155 </variablelist>
9156</refsect1>
9157<refsect1>
9158<title>Description</title>
9159<para>
9160   This function walks the current configuration and adds all connectors
9161   currently using <parameter>crtc</parameter> to the atomic configuration <parameter>state</parameter>. Note that this
9162   function must acquire the connection mutex. This can potentially cause
9163   unneeded seralization if the update is just for the planes on one crtc. Hence
9164   drivers and helpers should only call this when really needed (e.g. when a
9165   full modeset needs to happen due to some change).
9166</para>
9167</refsect1>
9168<refsect1>
9169<title>Returns</title>
9170<para>
9171   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
9172   then the w/w mutex code has detected a deadlock and the entire atomic
9173   sequence must be restarted. All other errors are fatal.
9174</para>
9175</refsect1>
9176</refentry>
9177
9178<refentry id="API-drm-atomic-connectors-for-crtc">
9179<refentryinfo>
9180 <title>LINUX</title>
9181 <productname>Kernel Hackers Manual</productname>
9182 <date>July 2017</date>
9183</refentryinfo>
9184<refmeta>
9185 <refentrytitle><phrase>drm_atomic_connectors_for_crtc</phrase></refentrytitle>
9186 <manvolnum>9</manvolnum>
9187 <refmiscinfo class="version">4.1.27</refmiscinfo>
9188</refmeta>
9189<refnamediv>
9190 <refname>drm_atomic_connectors_for_crtc</refname>
9191 <refpurpose>
9192     count number of connected outputs
9193 </refpurpose>
9194</refnamediv>
9195<refsynopsisdiv>
9196 <title>Synopsis</title>
9197  <funcsynopsis><funcprototype>
9198   <funcdef>int <function>drm_atomic_connectors_for_crtc </function></funcdef>
9199   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
9200   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
9201  </funcprototype></funcsynopsis>
9202</refsynopsisdiv>
9203<refsect1>
9204 <title>Arguments</title>
9205 <variablelist>
9206  <varlistentry>
9207   <term><parameter>state</parameter></term>
9208   <listitem>
9209    <para>
9210     atomic state
9211    </para>
9212   </listitem>
9213  </varlistentry>
9214  <varlistentry>
9215   <term><parameter>crtc</parameter></term>
9216   <listitem>
9217    <para>
9218     DRM crtc
9219    </para>
9220   </listitem>
9221  </varlistentry>
9222 </variablelist>
9223</refsect1>
9224<refsect1>
9225<title>Description</title>
9226<para>
9227   This function counts all connectors which will be connected to <parameter>crtc</parameter>
9228   according to <parameter>state</parameter>. Useful to recompute the enable state for <parameter>crtc</parameter>.
9229</para>
9230</refsect1>
9231</refentry>
9232
9233<refentry id="API-drm-atomic-legacy-backoff">
9234<refentryinfo>
9235 <title>LINUX</title>
9236 <productname>Kernel Hackers Manual</productname>
9237 <date>July 2017</date>
9238</refentryinfo>
9239<refmeta>
9240 <refentrytitle><phrase>drm_atomic_legacy_backoff</phrase></refentrytitle>
9241 <manvolnum>9</manvolnum>
9242 <refmiscinfo class="version">4.1.27</refmiscinfo>
9243</refmeta>
9244<refnamediv>
9245 <refname>drm_atomic_legacy_backoff</refname>
9246 <refpurpose>
9247     locking backoff for legacy ioctls
9248 </refpurpose>
9249</refnamediv>
9250<refsynopsisdiv>
9251 <title>Synopsis</title>
9252  <funcsynopsis><funcprototype>
9253   <funcdef>void <function>drm_atomic_legacy_backoff </function></funcdef>
9254   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
9255  </funcprototype></funcsynopsis>
9256</refsynopsisdiv>
9257<refsect1>
9258 <title>Arguments</title>
9259 <variablelist>
9260  <varlistentry>
9261   <term><parameter>state</parameter></term>
9262   <listitem>
9263    <para>
9264     atomic state
9265    </para>
9266   </listitem>
9267  </varlistentry>
9268 </variablelist>
9269</refsect1>
9270<refsect1>
9271<title>Description</title>
9272<para>
9273   This function should be used by legacy entry points which don't understand
9274   -EDEADLK semantics. For simplicity this one will grab all modeset locks after
9275   the slowpath completed.
9276</para>
9277</refsect1>
9278</refentry>
9279
9280<refentry id="API-drm-atomic-check-only">
9281<refentryinfo>
9282 <title>LINUX</title>
9283 <productname>Kernel Hackers Manual</productname>
9284 <date>July 2017</date>
9285</refentryinfo>
9286<refmeta>
9287 <refentrytitle><phrase>drm_atomic_check_only</phrase></refentrytitle>
9288 <manvolnum>9</manvolnum>
9289 <refmiscinfo class="version">4.1.27</refmiscinfo>
9290</refmeta>
9291<refnamediv>
9292 <refname>drm_atomic_check_only</refname>
9293 <refpurpose>
9294     check whether a given config would work
9295 </refpurpose>
9296</refnamediv>
9297<refsynopsisdiv>
9298 <title>Synopsis</title>
9299  <funcsynopsis><funcprototype>
9300   <funcdef>int <function>drm_atomic_check_only </function></funcdef>
9301   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
9302  </funcprototype></funcsynopsis>
9303</refsynopsisdiv>
9304<refsect1>
9305 <title>Arguments</title>
9306 <variablelist>
9307  <varlistentry>
9308   <term><parameter>state</parameter></term>
9309   <listitem>
9310    <para>
9311     atomic configuration to check
9312    </para>
9313   </listitem>
9314  </varlistentry>
9315 </variablelist>
9316</refsect1>
9317<refsect1>
9318<title>Description</title>
9319<para>
9320   Note that this function can return -EDEADLK if the driver needed to acquire
9321   more locks but encountered a deadlock. The caller must then do the usual w/w
9322   backoff dance and restart. All other errors are fatal.
9323</para>
9324</refsect1>
9325<refsect1>
9326<title>Returns</title>
9327<para>
9328   0 on success, negative error code on failure.
9329</para>
9330</refsect1>
9331</refentry>
9332
9333<refentry id="API-drm-atomic-commit">
9334<refentryinfo>
9335 <title>LINUX</title>
9336 <productname>Kernel Hackers Manual</productname>
9337 <date>July 2017</date>
9338</refentryinfo>
9339<refmeta>
9340 <refentrytitle><phrase>drm_atomic_commit</phrase></refentrytitle>
9341 <manvolnum>9</manvolnum>
9342 <refmiscinfo class="version">4.1.27</refmiscinfo>
9343</refmeta>
9344<refnamediv>
9345 <refname>drm_atomic_commit</refname>
9346 <refpurpose>
9347     commit configuration atomically
9348 </refpurpose>
9349</refnamediv>
9350<refsynopsisdiv>
9351 <title>Synopsis</title>
9352  <funcsynopsis><funcprototype>
9353   <funcdef>int <function>drm_atomic_commit </function></funcdef>
9354   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
9355  </funcprototype></funcsynopsis>
9356</refsynopsisdiv>
9357<refsect1>
9358 <title>Arguments</title>
9359 <variablelist>
9360  <varlistentry>
9361   <term><parameter>state</parameter></term>
9362   <listitem>
9363    <para>
9364     atomic configuration to check
9365    </para>
9366   </listitem>
9367  </varlistentry>
9368 </variablelist>
9369</refsect1>
9370<refsect1>
9371<title>Description</title>
9372<para>
9373   Note that this function can return -EDEADLK if the driver needed to acquire
9374   more locks but encountered a deadlock. The caller must then do the usual w/w
9375   backoff dance and restart. All other errors are fatal.
9376   </para><para>
9377
9378   Also note that on successful execution ownership of <parameter>state</parameter> is transferred
9379   from the caller of this function to the function itself. The caller must not
9380   free or in any other way access <parameter>state</parameter>. If the function fails then the caller
9381   must clean up <parameter>state</parameter> itself.
9382</para>
9383</refsect1>
9384<refsect1>
9385<title>Returns</title>
9386<para>
9387   0 on success, negative error code on failure.
9388</para>
9389</refsect1>
9390</refentry>
9391
9392<refentry id="API-drm-atomic-async-commit">
9393<refentryinfo>
9394 <title>LINUX</title>
9395 <productname>Kernel Hackers Manual</productname>
9396 <date>July 2017</date>
9397</refentryinfo>
9398<refmeta>
9399 <refentrytitle><phrase>drm_atomic_async_commit</phrase></refentrytitle>
9400 <manvolnum>9</manvolnum>
9401 <refmiscinfo class="version">4.1.27</refmiscinfo>
9402</refmeta>
9403<refnamediv>
9404 <refname>drm_atomic_async_commit</refname>
9405 <refpurpose>
9406     atomic<structname>async</structname> configuration commit
9407 </refpurpose>
9408</refnamediv>
9409<refsynopsisdiv>
9410 <title>Synopsis</title>
9411  <funcsynopsis><funcprototype>
9412   <funcdef>int <function>drm_atomic_async_commit </function></funcdef>
9413   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
9414  </funcprototype></funcsynopsis>
9415</refsynopsisdiv>
9416<refsect1>
9417 <title>Arguments</title>
9418 <variablelist>
9419  <varlistentry>
9420   <term><parameter>state</parameter></term>
9421   <listitem>
9422    <para>
9423     atomic configuration to check
9424    </para>
9425   </listitem>
9426  </varlistentry>
9427 </variablelist>
9428</refsect1>
9429<refsect1>
9430<title>Description</title>
9431<para>
9432   Note that this function can return -EDEADLK if the driver needed to acquire
9433   more locks but encountered a deadlock. The caller must then do the usual w/w
9434   backoff dance and restart. All other errors are fatal.
9435   </para><para>
9436
9437   Also note that on successful execution ownership of <parameter>state</parameter> is transferred
9438   from the caller of this function to the function itself. The caller must not
9439   free or in any other way access <parameter>state</parameter>. If the function fails then the caller
9440   must clean up <parameter>state</parameter> itself.
9441</para>
9442</refsect1>
9443<refsect1>
9444<title>Returns</title>
9445<para>
9446   0 on success, negative error code on failure.
9447</para>
9448</refsect1>
9449</refentry>
9450
9451    </sect2>
9452    <sect2>
9453      <title>Frame Buffer Creation</title>
9454      <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
9455				     struct drm_file *file_priv,
9456				     struct drm_mode_fb_cmd2 *mode_cmd);</synopsis>
9457      <para>
9458        Frame buffers are abstract memory objects that provide a source of
9459        pixels to scanout to a CRTC. Applications explicitly request the
9460        creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and
9461        receive an opaque handle that can be passed to the KMS CRTC control,
9462        plane configuration and page flip functions.
9463      </para>
9464      <para>
9465        Frame buffers rely on the underneath memory manager for low-level memory
9466        operations. When creating a frame buffer applications pass a memory
9467        handle (or a list of memory handles for multi-planar formats) through
9468	the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using
9469	GEM as their userspace buffer management interface this would be a GEM
9470	handle.  Drivers are however free to use their own backing storage object
9471	handles, e.g. vmwgfx directly exposes special TTM handles to userspace
9472	and so expects TTM handles in the create ioctl and not GEM handles.
9473      </para>
9474      <para>
9475        Drivers must first validate the requested frame buffer parameters passed
9476        through the mode_cmd argument. In particular this is where invalid
9477        sizes, pixel formats or pitches can be caught.
9478      </para>
9479      <para>
9480        If the parameters are deemed valid, drivers then create, initialize and
9481        return an instance of struct <structname>drm_framebuffer</structname>.
9482        If desired the instance can be embedded in a larger driver-specific
9483	structure. Drivers must fill its <structfield>width</structfield>,
9484	<structfield>height</structfield>, <structfield>pitches</structfield>,
9485        <structfield>offsets</structfield>, <structfield>depth</structfield>,
9486        <structfield>bits_per_pixel</structfield> and
9487        <structfield>pixel_format</structfield> fields from the values passed
9488        through the <parameter>drm_mode_fb_cmd2</parameter> argument. They
9489        should call the <function>drm_helper_mode_fill_fb_struct</function>
9490        helper function to do so.
9491      </para>
9492
9493      <para>
9494	The initialization of the new framebuffer instance is finalized with a
9495	call to <function>drm_framebuffer_init</function> which takes a pointer
9496	to DRM frame buffer operations (struct
9497	<structname>drm_framebuffer_funcs</structname>). Note that this function
9498	publishes the framebuffer and so from this point on it can be accessed
9499	concurrently from other threads. Hence it must be the last step in the
9500	driver's framebuffer initialization sequence. Frame buffer operations
9501	are
9502        <itemizedlist>
9503          <listitem>
9504            <synopsis>int (*create_handle)(struct drm_framebuffer *fb,
9505		     struct drm_file *file_priv, unsigned int *handle);</synopsis>
9506            <para>
9507              Create a handle to the frame buffer underlying memory object. If
9508              the frame buffer uses a multi-plane format, the handle will
9509              reference the memory object associated with the first plane.
9510            </para>
9511            <para>
9512              Drivers call <function>drm_gem_handle_create</function> to create
9513              the handle.
9514            </para>
9515          </listitem>
9516          <listitem>
9517            <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis>
9518            <para>
9519              Destroy the frame buffer object and frees all associated
9520              resources. Drivers must call
9521              <function>drm_framebuffer_cleanup</function> to free resources
9522              allocated by the DRM core for the frame buffer object, and must
9523              make sure to unreference all memory objects associated with the
9524              frame buffer. Handles created by the
9525              <methodname>create_handle</methodname> operation are released by
9526              the DRM core.
9527            </para>
9528          </listitem>
9529          <listitem>
9530            <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer,
9531	     struct drm_file *file_priv, unsigned flags, unsigned color,
9532	     struct drm_clip_rect *clips, unsigned num_clips);</synopsis>
9533            <para>
9534              This optional operation notifies the driver that a region of the
9535              frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB
9536              ioctl call.
9537            </para>
9538          </listitem>
9539        </itemizedlist>
9540      </para>
9541      <para>
9542	The lifetime of a drm framebuffer is controlled with a reference count,
9543	drivers can grab additional references with
9544	<function>drm_framebuffer_reference</function>and drop them
9545	again with <function>drm_framebuffer_unreference</function>. For
9546	driver-private framebuffers for which the last reference is never
9547	dropped (e.g. for the fbdev framebuffer when the struct
9548	<structname>drm_framebuffer</structname> is embedded into the fbdev
9549	helper struct) drivers can manually clean up a framebuffer at module
9550	unload time with
9551	<function>drm_framebuffer_unregister_private</function>.
9552      </para>
9553    </sect2>
9554    <sect2>
9555      <title>Dumb Buffer Objects</title>
9556      <para>
9557	The KMS API doesn't standardize backing storage object creation and
9558	leaves it to driver-specific ioctls. Furthermore actually creating a
9559	buffer object even for GEM-based drivers is done through a
9560	driver-specific ioctl - GEM only has a common userspace interface for
9561	sharing and destroying objects. While not an issue for full-fledged
9562	graphics stacks that include device-specific userspace components (in
9563	libdrm for instance), this limit makes DRM-based early boot graphics
9564	unnecessarily complex.
9565      </para>
9566      <para>
9567        Dumb objects partly alleviate the problem by providing a standard
9568        API to create dumb buffers suitable for scanout, which can then be used
9569        to create KMS frame buffers.
9570      </para>
9571      <para>
9572        To support dumb objects drivers must implement the
9573        <methodname>dumb_create</methodname>,
9574        <methodname>dumb_destroy</methodname> and
9575        <methodname>dumb_map_offset</methodname> operations.
9576      </para>
9577      <itemizedlist>
9578        <listitem>
9579          <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev,
9580                   struct drm_mode_create_dumb *args);</synopsis>
9581          <para>
9582            The <methodname>dumb_create</methodname> operation creates a driver
9583	    object (GEM or TTM handle) suitable for scanout based on the
9584	    width, height and depth from the struct
9585	    <structname>drm_mode_create_dumb</structname> argument. It fills the
9586	    argument's <structfield>handle</structfield>,
9587	    <structfield>pitch</structfield> and <structfield>size</structfield>
9588	    fields with a handle for the newly created object and its line
9589            pitch and size in bytes.
9590          </para>
9591        </listitem>
9592        <listitem>
9593          <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev,
9594                    uint32_t handle);</synopsis>
9595          <para>
9596            The <methodname>dumb_destroy</methodname> operation destroys a dumb
9597            object created by <methodname>dumb_create</methodname>.
9598          </para>
9599        </listitem>
9600        <listitem>
9601          <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev,
9602                       uint32_t handle, uint64_t *offset);</synopsis>
9603          <para>
9604            The <methodname>dumb_map_offset</methodname> operation associates an
9605            mmap fake offset with the object given by the handle and returns
9606            it. Drivers must use the
9607            <function>drm_gem_create_mmap_offset</function> function to
9608            associate the fake offset as described in
9609            <xref linkend="drm-gem-objects-mapping"/>.
9610          </para>
9611        </listitem>
9612      </itemizedlist>
9613      <para>
9614        Note that dumb objects may not be used for gpu acceleration, as has been
9615	attempted on some ARM embedded platforms. Such drivers really must have
9616	a hardware-specific ioctl to allocate suitable buffer objects.
9617      </para>
9618    </sect2>
9619    <sect2>
9620      <title>Output Polling</title>
9621      <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis>
9622      <para>
9623        This operation notifies the driver that the status of one or more
9624        connectors has changed. Drivers that use the fb helper can just call the
9625        <function>drm_fb_helper_hotplug_event</function> function to handle this
9626        operation.
9627      </para>
9628    </sect2>
9629    <sect2>
9630      <title>Locking</title>
9631      <para>
9632        Beside some lookup structures with their own locking (which is hidden
9633	behind the interface functions) most of the modeset state is protected
9634	by the <code>dev-&lt;mode_config.lock</code> mutex and additionally
9635	per-crtc locks to allow cursor updates, pageflips and similar operations
9636	to occur concurrently with background tasks like output detection.
9637	Operations which cross domains like a full modeset always grab all
9638	locks. Drivers there need to protect resources shared between crtcs with
9639	additional locking. They also need to be careful to always grab the
9640	relevant crtc locks if a modset functions touches crtc state, e.g. for
9641	load detection (which does only grab the <code>mode_config.lock</code>
9642	to allow concurrent screen updates on live crtcs).
9643      </para>
9644    </sect2>
9645  </sect1>
9646
9647  <!-- Internals: kms initialization and cleanup -->
9648
9649  <sect1 id="drm-kms-init">
9650    <title>KMS Initialization and Cleanup</title>
9651    <para>
9652      A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders
9653      and connectors. KMS drivers must thus create and initialize all those
9654      objects at load time after initializing mode setting.
9655    </para>
9656    <sect2>
9657      <title>CRTCs (struct <structname>drm_crtc</structname>)</title>
9658      <para>
9659        A CRTC is an abstraction representing a part of the chip that contains a
9660	pointer to a scanout buffer. Therefore, the number of CRTCs available
9661	determines how many independent scanout buffers can be active at any
9662	given time. The CRTC structure contains several fields to support this:
9663	a pointer to some video memory (abstracted as a frame buffer object), a
9664	display mode, and an (x, y) offset into the video memory to support
9665	panning or configurations where one piece of video memory spans multiple
9666	CRTCs.
9667      </para>
9668      <sect3>
9669        <title>CRTC Initialization</title>
9670        <para>
9671          A KMS device must create and register at least one struct
9672          <structname>drm_crtc</structname> instance. The instance is allocated
9673          and zeroed by the driver, possibly as part of a larger structure, and
9674          registered with a call to <function>drm_crtc_init</function> with a
9675          pointer to CRTC functions.
9676        </para>
9677      </sect3>
9678      <sect3 id="drm-kms-crtcops">
9679        <title>CRTC Operations</title>
9680        <sect4>
9681          <title>Set Configuration</title>
9682          <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis>
9683          <para>
9684            Apply a new CRTC configuration to the device. The configuration
9685            specifies a CRTC, a frame buffer to scan out from, a (x,y) position in
9686            the frame buffer, a display mode and an array of connectors to drive
9687            with the CRTC if possible.
9688          </para>
9689          <para>
9690            If the frame buffer specified in the configuration is NULL, the driver
9691            must detach all encoders connected to the CRTC and all connectors
9692            attached to those encoders and disable them.
9693          </para>
9694          <para>
9695            This operation is called with the mode config lock held.
9696          </para>
9697          <note><para>
9698	    Note that the drm core has no notion of restoring the mode setting
9699	    state after resume, since all resume handling is in the full
9700	    responsibility of the driver. The common mode setting helper library
9701	    though provides a helper which can be used for this:
9702	    <function>drm_helper_resume_force_mode</function>.
9703          </para></note>
9704        </sect4>
9705        <sect4>
9706          <title>Page Flipping</title>
9707          <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb,
9708                   struct drm_pending_vblank_event *event);</synopsis>
9709          <para>
9710            Schedule a page flip to the given frame buffer for the CRTC. This
9711            operation is called with the mode config mutex held.
9712          </para>
9713          <para>
9714            Page flipping is a synchronization mechanism that replaces the frame
9715            buffer being scanned out by the CRTC with a new frame buffer during
9716            vertical blanking, avoiding tearing. When an application requests a page
9717            flip the DRM core verifies that the new frame buffer is large enough to
9718            be scanned out by  the CRTC in the currently configured mode and then
9719            calls the CRTC <methodname>page_flip</methodname> operation with a
9720            pointer to the new frame buffer.
9721          </para>
9722          <para>
9723            The <methodname>page_flip</methodname> operation schedules a page flip.
9724            Once any pending rendering targeting the new frame buffer has
9725            completed, the CRTC will be reprogrammed to display that frame buffer
9726            after the next vertical refresh. The operation must return immediately
9727            without waiting for rendering or page flip to complete and must block
9728            any new rendering to the frame buffer until the page flip completes.
9729          </para>
9730          <para>
9731            If a page flip can be successfully scheduled the driver must set the
9732            <code>drm_crtc-&gt;fb</code> field to the new framebuffer pointed to
9733            by <code>fb</code>. This is important so that the reference counting
9734            on framebuffers stays balanced.
9735          </para>
9736          <para>
9737            If a page flip is already pending, the
9738            <methodname>page_flip</methodname> operation must return
9739            -<errorname>EBUSY</errorname>.
9740          </para>
9741          <para>
9742            To synchronize page flip to vertical blanking the driver will likely
9743            need to enable vertical blanking interrupts. It should call
9744            <function>drm_vblank_get</function> for that purpose, and call
9745            <function>drm_vblank_put</function> after the page flip completes.
9746          </para>
9747          <para>
9748            If the application has requested to be notified when page flip completes
9749            the <methodname>page_flip</methodname> operation will be called with a
9750            non-NULL <parameter>event</parameter> argument pointing to a
9751            <structname>drm_pending_vblank_event</structname> instance. Upon page
9752            flip completion the driver must call <methodname>drm_send_vblank_event</methodname>
9753            to fill in the event and send to wake up any waiting processes.
9754            This can be performed with
9755            <programlisting><![CDATA[
9756            spin_lock_irqsave(&dev->event_lock, flags);
9757            ...
9758            drm_send_vblank_event(dev, pipe, event);
9759            spin_unlock_irqrestore(&dev->event_lock, flags);
9760            ]]></programlisting>
9761          </para>
9762          <note><para>
9763            FIXME: Could drivers that don't need to wait for rendering to complete
9764            just add the event to <literal>dev-&gt;vblank_event_list</literal> and
9765            let the DRM core handle everything, as for "normal" vertical blanking
9766            events?
9767          </para></note>
9768          <para>
9769            While waiting for the page flip to complete, the
9770            <literal>event-&gt;base.link</literal> list head can be used freely by
9771            the driver to store the pending event in a driver-specific list.
9772          </para>
9773          <para>
9774            If the file handle is closed before the event is signaled, drivers must
9775            take care to destroy the event in their
9776            <methodname>preclose</methodname> operation (and, if needed, call
9777            <function>drm_vblank_put</function>).
9778          </para>
9779        </sect4>
9780        <sect4>
9781          <title>Miscellaneous</title>
9782          <itemizedlist>
9783            <listitem>
9784              <synopsis>void (*set_property)(struct drm_crtc *crtc,
9785                     struct drm_property *property, uint64_t value);</synopsis>
9786              <para>
9787                Set the value of the given CRTC property to
9788                <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
9789                for more information about properties.
9790              </para>
9791            </listitem>
9792            <listitem>
9793              <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
9794                        uint32_t start, uint32_t size);</synopsis>
9795              <para>
9796                Apply a gamma table to the device. The operation is optional.
9797              </para>
9798            </listitem>
9799            <listitem>
9800              <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis>
9801              <para>
9802                Destroy the CRTC when not needed anymore. See
9803                <xref linkend="drm-kms-init"/>.
9804              </para>
9805            </listitem>
9806          </itemizedlist>
9807        </sect4>
9808      </sect3>
9809    </sect2>
9810    <sect2>
9811      <title>Planes (struct <structname>drm_plane</structname>)</title>
9812      <para>
9813        A plane represents an image source that can be blended with or overlayed
9814	on top of a CRTC during the scanout process. Planes are associated with
9815	a frame buffer to crop a portion of the image memory (source) and
9816	optionally scale it to a destination size. The result is then blended
9817	with or overlayed on top of a CRTC.
9818      </para>
9819      <para>
9820      The DRM core recognizes three types of planes:
9821      <itemizedlist>
9822        <listitem>
9823        DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC.  Primary
9824        planes are the planes operated upon by CRTC modesetting and flipping
9825        operations described in <xref linkend="drm-kms-crtcops"/>.
9826        </listitem>
9827        <listitem>
9828        DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC.  Cursor
9829        planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and
9830        DRM_IOCTL_MODE_CURSOR2 ioctls.
9831        </listitem>
9832        <listitem>
9833        DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes.
9834        Some drivers refer to these types of planes as "sprites" internally.
9835        </listitem>
9836      </itemizedlist>
9837      For compatibility with legacy userspace, only overlay planes are made
9838      available to userspace by default.  Userspace clients may set the
9839      DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that
9840      they wish to receive a universal plane list containing all plane types.
9841      </para>
9842      <sect3>
9843        <title>Plane Initialization</title>
9844        <para>
9845          To create a plane, a KMS drivers allocates and
9846          zeroes an instances of struct <structname>drm_plane</structname>
9847          (possibly as part of a larger structure) and registers it with a call
9848          to <function>drm_universal_plane_init</function>. The function takes a bitmask
9849          of the CRTCs that can be associated with the plane, a pointer to the
9850          plane functions, a list of format supported formats, and the type of
9851          plane (primary, cursor, or overlay) being initialized.
9852        </para>
9853        <para>
9854          Cursor and overlay planes are optional.  All drivers should provide
9855          one primary plane per CRTC (although this requirement may change in
9856          the future); drivers that do not wish to provide special handling for
9857          primary planes may make use of the helper functions described in
9858          <xref linkend="drm-kms-planehelpers"/> to create and register a
9859          primary plane with standard capabilities.
9860        </para>
9861      </sect3>
9862      <sect3>
9863        <title>Plane Operations</title>
9864        <itemizedlist>
9865          <listitem>
9866            <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc,
9867                        struct drm_framebuffer *fb, int crtc_x, int crtc_y,
9868                        unsigned int crtc_w, unsigned int crtc_h,
9869                        uint32_t src_x, uint32_t src_y,
9870                        uint32_t src_w, uint32_t src_h);</synopsis>
9871            <para>
9872              Enable and configure the plane to use the given CRTC and frame buffer.
9873            </para>
9874            <para>
9875              The source rectangle in frame buffer memory coordinates is given by
9876              the <parameter>src_x</parameter>, <parameter>src_y</parameter>,
9877              <parameter>src_w</parameter> and <parameter>src_h</parameter>
9878              parameters (as 16.16 fixed point values). Devices that don't support
9879              subpixel plane coordinates can ignore the fractional part.
9880            </para>
9881            <para>
9882              The destination rectangle in CRTC coordinates is given by the
9883              <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>,
9884              <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter>
9885              parameters (as integer values). Devices scale the source rectangle to
9886              the destination rectangle. If scaling is not supported, and the source
9887              rectangle size doesn't match the destination rectangle size, the
9888              driver must return a -<errorname>EINVAL</errorname> error.
9889            </para>
9890          </listitem>
9891          <listitem>
9892            <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis>
9893            <para>
9894              Disable the plane. The DRM core calls this method in response to a
9895              DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0.
9896              Disabled planes must not be processed by the CRTC.
9897            </para>
9898          </listitem>
9899          <listitem>
9900            <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis>
9901            <para>
9902              Destroy the plane when not needed anymore. See
9903              <xref linkend="drm-kms-init"/>.
9904            </para>
9905          </listitem>
9906        </itemizedlist>
9907      </sect3>
9908    </sect2>
9909    <sect2>
9910      <title>Encoders (struct <structname>drm_encoder</structname>)</title>
9911      <para>
9912        An encoder takes pixel data from a CRTC and converts it to a format
9913	suitable for any attached connectors. On some devices, it may be
9914	possible to have a CRTC send data to more than one encoder. In that
9915	case, both encoders would receive data from the same scanout buffer,
9916	resulting in a "cloned" display configuration across the connectors
9917	attached to each encoder.
9918      </para>
9919      <sect3>
9920        <title>Encoder Initialization</title>
9921        <para>
9922          As for CRTCs, a KMS driver must create, initialize and register at
9923          least one struct <structname>drm_encoder</structname> instance. The
9924          instance is allocated and zeroed by the driver, possibly as part of a
9925          larger structure.
9926        </para>
9927        <para>
9928          Drivers must initialize the struct <structname>drm_encoder</structname>
9929          <structfield>possible_crtcs</structfield> and
9930          <structfield>possible_clones</structfield> fields before registering the
9931          encoder. Both fields are bitmasks of respectively the CRTCs that the
9932          encoder can be connected to, and sibling encoders candidate for cloning.
9933        </para>
9934        <para>
9935          After being initialized, the encoder must be registered with a call to
9936          <function>drm_encoder_init</function>. The function takes a pointer to
9937          the encoder functions and an encoder type. Supported types are
9938          <itemizedlist>
9939            <listitem>
9940              DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A
9941              </listitem>
9942            <listitem>
9943              DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort
9944            </listitem>
9945            <listitem>
9946              DRM_MODE_ENCODER_LVDS for display panels
9947            </listitem>
9948            <listitem>
9949              DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component,
9950              SCART)
9951            </listitem>
9952            <listitem>
9953              DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
9954            </listitem>
9955          </itemizedlist>
9956        </para>
9957        <para>
9958          Encoders must be attached to a CRTC to be used. DRM drivers leave
9959          encoders unattached at initialization time. Applications (or the fbdev
9960          compatibility layer when implemented) are responsible for attaching the
9961          encoders they want to use to a CRTC.
9962        </para>
9963      </sect3>
9964      <sect3>
9965        <title>Encoder Operations</title>
9966        <itemizedlist>
9967          <listitem>
9968            <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis>
9969            <para>
9970              Called to destroy the encoder when not needed anymore. See
9971              <xref linkend="drm-kms-init"/>.
9972            </para>
9973          </listitem>
9974          <listitem>
9975            <synopsis>void (*set_property)(struct drm_plane *plane,
9976                     struct drm_property *property, uint64_t value);</synopsis>
9977            <para>
9978              Set the value of the given plane property to
9979              <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
9980              for more information about properties.
9981            </para>
9982          </listitem>
9983        </itemizedlist>
9984      </sect3>
9985    </sect2>
9986    <sect2>
9987      <title>Connectors (struct <structname>drm_connector</structname>)</title>
9988      <para>
9989        A connector is the final destination for pixel data on a device, and
9990	usually connects directly to an external display device like a monitor
9991	or laptop panel. A connector can only be attached to one encoder at a
9992	time. The connector is also the structure where information about the
9993	attached display is kept, so it contains fields for display data, EDID
9994	data, DPMS &amp; connection status, and information about modes
9995	supported on the attached displays.
9996      </para>
9997      <sect3>
9998        <title>Connector Initialization</title>
9999        <para>
10000          Finally a KMS driver must create, initialize, register and attach at
10001          least one struct <structname>drm_connector</structname> instance. The
10002          instance is created as other KMS objects and initialized by setting the
10003          following fields.
10004        </para>
10005        <variablelist>
10006          <varlistentry>
10007            <term><structfield>interlace_allowed</structfield></term>
10008            <listitem><para>
10009              Whether the connector can handle interlaced modes.
10010            </para></listitem>
10011          </varlistentry>
10012          <varlistentry>
10013            <term><structfield>doublescan_allowed</structfield></term>
10014            <listitem><para>
10015              Whether the connector can handle doublescan.
10016            </para></listitem>
10017          </varlistentry>
10018          <varlistentry>
10019            <term><structfield>display_info
10020            </structfield></term>
10021            <listitem><para>
10022              Display information is filled from EDID information when a display
10023              is detected. For non hot-pluggable displays such as flat panels in
10024              embedded systems, the driver should initialize the
10025              <structfield>display_info</structfield>.<structfield>width_mm</structfield>
10026              and
10027              <structfield>display_info</structfield>.<structfield>height_mm</structfield>
10028              fields with the physical size of the display.
10029            </para></listitem>
10030          </varlistentry>
10031          <varlistentry>
10032            <term id="drm-kms-connector-polled"><structfield>polled</structfield></term>
10033            <listitem><para>
10034              Connector polling mode, a combination of
10035              <variablelist>
10036                <varlistentry>
10037                  <term>DRM_CONNECTOR_POLL_HPD</term>
10038                  <listitem><para>
10039                    The connector generates hotplug events and doesn't need to be
10040                    periodically polled. The CONNECT and DISCONNECT flags must not
10041                    be set together with the HPD flag.
10042                  </para></listitem>
10043                </varlistentry>
10044                <varlistentry>
10045                  <term>DRM_CONNECTOR_POLL_CONNECT</term>
10046                  <listitem><para>
10047                    Periodically poll the connector for connection.
10048                  </para></listitem>
10049                </varlistentry>
10050                <varlistentry>
10051                  <term>DRM_CONNECTOR_POLL_DISCONNECT</term>
10052                  <listitem><para>
10053                    Periodically poll the connector for disconnection.
10054                  </para></listitem>
10055                </varlistentry>
10056              </variablelist>
10057              Set to 0 for connectors that don't support connection status
10058              discovery.
10059            </para></listitem>
10060          </varlistentry>
10061        </variablelist>
10062        <para>
10063          The connector is then registered with a call to
10064          <function>drm_connector_init</function> with a pointer to the connector
10065          functions and a connector type, and exposed through sysfs with a call to
10066          <function>drm_connector_register</function>.
10067        </para>
10068        <para>
10069          Supported connector types are
10070          <itemizedlist>
10071            <listitem>DRM_MODE_CONNECTOR_VGA</listitem>
10072            <listitem>DRM_MODE_CONNECTOR_DVII</listitem>
10073            <listitem>DRM_MODE_CONNECTOR_DVID</listitem>
10074            <listitem>DRM_MODE_CONNECTOR_DVIA</listitem>
10075            <listitem>DRM_MODE_CONNECTOR_Composite</listitem>
10076            <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem>
10077            <listitem>DRM_MODE_CONNECTOR_LVDS</listitem>
10078            <listitem>DRM_MODE_CONNECTOR_Component</listitem>
10079            <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem>
10080            <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem>
10081            <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem>
10082            <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem>
10083            <listitem>DRM_MODE_CONNECTOR_TV</listitem>
10084            <listitem>DRM_MODE_CONNECTOR_eDP</listitem>
10085            <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem>
10086          </itemizedlist>
10087        </para>
10088        <para>
10089          Connectors must be attached to an encoder to be used. For devices that
10090          map connectors to encoders 1:1, the connector should be attached at
10091          initialization time with a call to
10092          <function>drm_mode_connector_attach_encoder</function>. The driver must
10093          also set the <structname>drm_connector</structname>
10094          <structfield>encoder</structfield> field to point to the attached
10095          encoder.
10096        </para>
10097        <para>
10098          Finally, drivers must initialize the connectors state change detection
10099          with a call to <function>drm_kms_helper_poll_init</function>. If at
10100          least one connector is pollable but can't generate hotplug interrupts
10101          (indicated by the DRM_CONNECTOR_POLL_CONNECT and
10102          DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
10103          automatically be queued to periodically poll for changes. Connectors
10104          that can generate hotplug interrupts must be marked with the
10105          DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must
10106          call <function>drm_helper_hpd_irq_event</function>. The function will
10107          queue a delayed work to check the state of all connectors, but no
10108          periodic polling will be done.
10109        </para>
10110      </sect3>
10111      <sect3>
10112        <title>Connector Operations</title>
10113        <note><para>
10114          Unless otherwise state, all operations are mandatory.
10115        </para></note>
10116        <sect4>
10117          <title>DPMS</title>
10118          <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis>
10119          <para>
10120            The DPMS operation sets the power state of a connector. The mode
10121            argument is one of
10122            <itemizedlist>
10123              <listitem><para>DRM_MODE_DPMS_ON</para></listitem>
10124              <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem>
10125              <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem>
10126              <listitem><para>DRM_MODE_DPMS_OFF</para></listitem>
10127            </itemizedlist>
10128          </para>
10129          <para>
10130            In all but DPMS_ON mode the encoder to which the connector is attached
10131            should put the display in low-power mode by driving its signals
10132            appropriately. If more than one connector is attached to the encoder
10133            care should be taken not to change the power state of other displays as
10134            a side effect. Low-power mode should be propagated to the encoders and
10135            CRTCs when all related connectors are put in low-power mode.
10136          </para>
10137        </sect4>
10138        <sect4>
10139          <title>Modes</title>
10140          <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width,
10141                      uint32_t max_height);</synopsis>
10142          <para>
10143            Fill the mode list with all supported modes for the connector. If the
10144            <parameter>max_width</parameter> and <parameter>max_height</parameter>
10145            arguments are non-zero, the implementation must ignore all modes wider
10146            than <parameter>max_width</parameter> or higher than
10147            <parameter>max_height</parameter>.
10148          </para>
10149          <para>
10150            The connector must also fill in this operation its
10151            <structfield>display_info</structfield>
10152            <structfield>width_mm</structfield> and
10153            <structfield>height_mm</structfield> fields with the connected display
10154            physical size in millimeters. The fields should be set to 0 if the value
10155            isn't known or is not applicable (for instance for projector devices).
10156          </para>
10157        </sect4>
10158        <sect4>
10159          <title>Connection Status</title>
10160          <para>
10161            The connection status is updated through polling or hotplug events when
10162            supported (see <xref linkend="drm-kms-connector-polled"/>). The status
10163            value is reported to userspace through ioctls and must not be used
10164            inside the driver, as it only gets initialized by a call to
10165            <function>drm_mode_getconnector</function> from userspace.
10166          </para>
10167          <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector,
10168                                        bool force);</synopsis>
10169          <para>
10170            Check to see if anything is attached to the connector. The
10171            <parameter>force</parameter> parameter is set to false whilst polling or
10172            to true when checking the connector due to user request.
10173            <parameter>force</parameter> can be used by the driver to avoid
10174            expensive, destructive operations during automated probing.
10175          </para>
10176          <para>
10177            Return connector_status_connected if something is connected to the
10178            connector, connector_status_disconnected if nothing is connected and
10179            connector_status_unknown if the connection state isn't known.
10180          </para>
10181          <para>
10182            Drivers should only return connector_status_connected if the connection
10183            status has really been probed as connected. Connectors that can't detect
10184            the connection status, or failed connection status probes, should return
10185            connector_status_unknown.
10186          </para>
10187        </sect4>
10188        <sect4>
10189          <title>Miscellaneous</title>
10190          <itemizedlist>
10191            <listitem>
10192              <synopsis>void (*set_property)(struct drm_connector *connector,
10193                     struct drm_property *property, uint64_t value);</synopsis>
10194              <para>
10195                Set the value of the given connector property to
10196                <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
10197                for more information about properties.
10198              </para>
10199            </listitem>
10200            <listitem>
10201              <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
10202              <para>
10203                Destroy the connector when not needed anymore. See
10204                <xref linkend="drm-kms-init"/>.
10205              </para>
10206            </listitem>
10207          </itemizedlist>
10208        </sect4>
10209      </sect3>
10210    </sect2>
10211    <sect2>
10212      <title>Cleanup</title>
10213      <para>
10214        The DRM core manages its objects' lifetime. When an object is not needed
10215	anymore the core calls its destroy function, which must clean up and
10216	free every resource allocated for the object. Every
10217	<function>drm_*_init</function> call must be matched with a
10218	corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs
10219	(<function>drm_crtc_cleanup</function>), planes
10220	(<function>drm_plane_cleanup</function>), encoders
10221	(<function>drm_encoder_cleanup</function>) and connectors
10222	(<function>drm_connector_cleanup</function>). Furthermore, connectors
10223	that have been added to sysfs must be removed by a call to
10224	<function>drm_connector_unregister</function> before calling
10225	<function>drm_connector_cleanup</function>.
10226      </para>
10227      <para>
10228        Connectors state change detection must be cleanup up with a call to
10229	<function>drm_kms_helper_poll_fini</function>.
10230      </para>
10231    </sect2>
10232    <sect2>
10233      <title>Output discovery and initialization example</title>
10234      <programlisting><![CDATA[
10235void intel_crt_init(struct drm_device *dev)
10236{
10237	struct drm_connector *connector;
10238	struct intel_output *intel_output;
10239
10240	intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
10241	if (!intel_output)
10242		return;
10243
10244	connector = &intel_output->base;
10245	drm_connector_init(dev, &intel_output->base,
10246			   &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);
10247
10248	drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
10249			 DRM_MODE_ENCODER_DAC);
10250
10251	drm_mode_connector_attach_encoder(&intel_output->base,
10252					  &intel_output->enc);
10253
10254	/* Set up the DDC bus. */
10255	intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
10256	if (!intel_output->ddc_bus) {
10257		dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
10258			   "failed.\n");
10259		return;
10260	}
10261
10262	intel_output->type = INTEL_OUTPUT_ANALOG;
10263	connector->interlace_allowed = 0;
10264	connector->doublescan_allowed = 0;
10265
10266	drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
10267	drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);
10268
10269	drm_connector_register(connector);
10270}]]></programlisting>
10271      <para>
10272        In the example above (taken from the i915 driver), a CRTC, connector and
10273        encoder combination is created. A device-specific i2c bus is also
10274        created for fetching EDID data and performing monitor detection. Once
10275        the process is complete, the new connector is registered with sysfs to
10276        make its properties available to applications.
10277      </para>
10278    </sect2>
10279    <sect2>
10280      <title>KMS API Functions</title>
10281<!-- drivers/gpu/drm/drm_crtc.c -->
10282<refentry id="API-drm-get-connector-status-name">
10283<refentryinfo>
10284 <title>LINUX</title>
10285 <productname>Kernel Hackers Manual</productname>
10286 <date>July 2017</date>
10287</refentryinfo>
10288<refmeta>
10289 <refentrytitle><phrase>drm_get_connector_status_name</phrase></refentrytitle>
10290 <manvolnum>9</manvolnum>
10291 <refmiscinfo class="version">4.1.27</refmiscinfo>
10292</refmeta>
10293<refnamediv>
10294 <refname>drm_get_connector_status_name</refname>
10295 <refpurpose>
10296  return a string for connector status
10297 </refpurpose>
10298</refnamediv>
10299<refsynopsisdiv>
10300 <title>Synopsis</title>
10301  <funcsynopsis><funcprototype>
10302   <funcdef>const char * <function>drm_get_connector_status_name </function></funcdef>
10303   <paramdef>enum drm_connector_status <parameter>status</parameter></paramdef>
10304  </funcprototype></funcsynopsis>
10305</refsynopsisdiv>
10306<refsect1>
10307 <title>Arguments</title>
10308 <variablelist>
10309  <varlistentry>
10310   <term><parameter>status</parameter></term>
10311   <listitem>
10312    <para>
10313     connector status to compute name of
10314    </para>
10315   </listitem>
10316  </varlistentry>
10317 </variablelist>
10318</refsect1>
10319<refsect1>
10320<title>Description</title>
10321<para>
10322   In contrast to the other drm_get_*_name functions this one here returns a
10323   const pointer and hence is threadsafe.
10324</para>
10325</refsect1>
10326</refentry>
10327
10328<refentry id="API-drm-get-subpixel-order-name">
10329<refentryinfo>
10330 <title>LINUX</title>
10331 <productname>Kernel Hackers Manual</productname>
10332 <date>July 2017</date>
10333</refentryinfo>
10334<refmeta>
10335 <refentrytitle><phrase>drm_get_subpixel_order_name</phrase></refentrytitle>
10336 <manvolnum>9</manvolnum>
10337 <refmiscinfo class="version">4.1.27</refmiscinfo>
10338</refmeta>
10339<refnamediv>
10340 <refname>drm_get_subpixel_order_name</refname>
10341 <refpurpose>
10342     return a string for a given subpixel enum
10343 </refpurpose>
10344</refnamediv>
10345<refsynopsisdiv>
10346 <title>Synopsis</title>
10347  <funcsynopsis><funcprototype>
10348   <funcdef>const char * <function>drm_get_subpixel_order_name </function></funcdef>
10349   <paramdef>enum subpixel_order <parameter>order</parameter></paramdef>
10350  </funcprototype></funcsynopsis>
10351</refsynopsisdiv>
10352<refsect1>
10353 <title>Arguments</title>
10354 <variablelist>
10355  <varlistentry>
10356   <term><parameter>order</parameter></term>
10357   <listitem>
10358    <para>
10359     enum of subpixel_order
10360    </para>
10361   </listitem>
10362  </varlistentry>
10363 </variablelist>
10364</refsect1>
10365<refsect1>
10366<title>Description</title>
10367<para>
10368   Note you could abuse this and return something out of bounds, but that
10369   would be a caller error.  No unscrubbed user data should make it here.
10370</para>
10371</refsect1>
10372</refentry>
10373
10374<refentry id="API-drm-get-format-name">
10375<refentryinfo>
10376 <title>LINUX</title>
10377 <productname>Kernel Hackers Manual</productname>
10378 <date>July 2017</date>
10379</refentryinfo>
10380<refmeta>
10381 <refentrytitle><phrase>drm_get_format_name</phrase></refentrytitle>
10382 <manvolnum>9</manvolnum>
10383 <refmiscinfo class="version">4.1.27</refmiscinfo>
10384</refmeta>
10385<refnamediv>
10386 <refname>drm_get_format_name</refname>
10387 <refpurpose>
10388     return a string for drm fourcc format
10389 </refpurpose>
10390</refnamediv>
10391<refsynopsisdiv>
10392 <title>Synopsis</title>
10393  <funcsynopsis><funcprototype>
10394   <funcdef>const char * <function>drm_get_format_name </function></funcdef>
10395   <paramdef>uint32_t <parameter>format</parameter></paramdef>
10396  </funcprototype></funcsynopsis>
10397</refsynopsisdiv>
10398<refsect1>
10399 <title>Arguments</title>
10400 <variablelist>
10401  <varlistentry>
10402   <term><parameter>format</parameter></term>
10403   <listitem>
10404    <para>
10405     format to compute name of
10406    </para>
10407   </listitem>
10408  </varlistentry>
10409 </variablelist>
10410</refsect1>
10411<refsect1>
10412<title>Description</title>
10413<para>
10414   Note that the buffer used by this function is globally shared and owned by
10415   the function itself.
10416</para>
10417</refsect1>
10418<refsect1>
10419<title>FIXME</title>
10420<para>
10421   This isn't really multithreading safe.
10422</para>
10423</refsect1>
10424</refentry>
10425
10426<refentry id="API-drm-mode-object-find">
10427<refentryinfo>
10428 <title>LINUX</title>
10429 <productname>Kernel Hackers Manual</productname>
10430 <date>July 2017</date>
10431</refentryinfo>
10432<refmeta>
10433 <refentrytitle><phrase>drm_mode_object_find</phrase></refentrytitle>
10434 <manvolnum>9</manvolnum>
10435 <refmiscinfo class="version">4.1.27</refmiscinfo>
10436</refmeta>
10437<refnamediv>
10438 <refname>drm_mode_object_find</refname>
10439 <refpurpose>
10440     look up a drm object with static lifetime
10441 </refpurpose>
10442</refnamediv>
10443<refsynopsisdiv>
10444 <title>Synopsis</title>
10445  <funcsynopsis><funcprototype>
10446   <funcdef>struct drm_mode_object * <function>drm_mode_object_find </function></funcdef>
10447   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
10448   <paramdef>uint32_t <parameter>id</parameter></paramdef>
10449   <paramdef>uint32_t <parameter>type</parameter></paramdef>
10450  </funcprototype></funcsynopsis>
10451</refsynopsisdiv>
10452<refsect1>
10453 <title>Arguments</title>
10454 <variablelist>
10455  <varlistentry>
10456   <term><parameter>dev</parameter></term>
10457   <listitem>
10458    <para>
10459     drm device
10460    </para>
10461   </listitem>
10462  </varlistentry>
10463  <varlistentry>
10464   <term><parameter>id</parameter></term>
10465   <listitem>
10466    <para>
10467     id of the mode object
10468    </para>
10469   </listitem>
10470  </varlistentry>
10471  <varlistentry>
10472   <term><parameter>type</parameter></term>
10473   <listitem>
10474    <para>
10475     type of the mode object
10476    </para>
10477   </listitem>
10478  </varlistentry>
10479 </variablelist>
10480</refsect1>
10481<refsect1>
10482<title>Description</title>
10483<para>
10484   Note that framebuffers cannot be looked up with this functions - since those
10485   are reference counted, they need special treatment.  Even with
10486   DRM_MODE_OBJECT_ANY (although that will simply return NULL
10487   rather than <function>WARN_ON</function>).
10488</para>
10489</refsect1>
10490</refentry>
10491
10492<refentry id="API-drm-framebuffer-init">
10493<refentryinfo>
10494 <title>LINUX</title>
10495 <productname>Kernel Hackers Manual</productname>
10496 <date>July 2017</date>
10497</refentryinfo>
10498<refmeta>
10499 <refentrytitle><phrase>drm_framebuffer_init</phrase></refentrytitle>
10500 <manvolnum>9</manvolnum>
10501 <refmiscinfo class="version">4.1.27</refmiscinfo>
10502</refmeta>
10503<refnamediv>
10504 <refname>drm_framebuffer_init</refname>
10505 <refpurpose>
10506     initialize a framebuffer
10507 </refpurpose>
10508</refnamediv>
10509<refsynopsisdiv>
10510 <title>Synopsis</title>
10511  <funcsynopsis><funcprototype>
10512   <funcdef>int <function>drm_framebuffer_init </function></funcdef>
10513   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
10514   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
10515   <paramdef>const struct drm_framebuffer_funcs * <parameter>funcs</parameter></paramdef>
10516  </funcprototype></funcsynopsis>
10517</refsynopsisdiv>
10518<refsect1>
10519 <title>Arguments</title>
10520 <variablelist>
10521  <varlistentry>
10522   <term><parameter>dev</parameter></term>
10523   <listitem>
10524    <para>
10525     DRM device
10526    </para>
10527   </listitem>
10528  </varlistentry>
10529  <varlistentry>
10530   <term><parameter>fb</parameter></term>
10531   <listitem>
10532    <para>
10533     framebuffer to be initialized
10534    </para>
10535   </listitem>
10536  </varlistentry>
10537  <varlistentry>
10538   <term><parameter>funcs</parameter></term>
10539   <listitem>
10540    <para>
10541     ... with these functions
10542    </para>
10543   </listitem>
10544  </varlistentry>
10545 </variablelist>
10546</refsect1>
10547<refsect1>
10548<title>Description</title>
10549<para>
10550   Allocates an ID for the framebuffer's parent mode object, sets its mode
10551   functions &amp; device file and adds it to the master fd list.
10552</para>
10553</refsect1>
10554<refsect1>
10555<title>IMPORTANT</title>
10556<para>
10557   This functions publishes the fb and makes it available for concurrent access
10558   by other users. Which means by this point the fb _must_ be fully set up -
10559   since all the fb attributes are invariant over its lifetime, no further
10560   locking but only correct reference counting is required.
10561</para>
10562</refsect1>
10563<refsect1>
10564<title>Returns</title>
10565<para>
10566   Zero on success, error code on failure.
10567</para>
10568</refsect1>
10569</refentry>
10570
10571<refentry id="API-drm-framebuffer-lookup">
10572<refentryinfo>
10573 <title>LINUX</title>
10574 <productname>Kernel Hackers Manual</productname>
10575 <date>July 2017</date>
10576</refentryinfo>
10577<refmeta>
10578 <refentrytitle><phrase>drm_framebuffer_lookup</phrase></refentrytitle>
10579 <manvolnum>9</manvolnum>
10580 <refmiscinfo class="version">4.1.27</refmiscinfo>
10581</refmeta>
10582<refnamediv>
10583 <refname>drm_framebuffer_lookup</refname>
10584 <refpurpose>
10585     look up a drm framebuffer and grab a reference
10586 </refpurpose>
10587</refnamediv>
10588<refsynopsisdiv>
10589 <title>Synopsis</title>
10590  <funcsynopsis><funcprototype>
10591   <funcdef>struct drm_framebuffer * <function>drm_framebuffer_lookup </function></funcdef>
10592   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
10593   <paramdef>uint32_t <parameter>id</parameter></paramdef>
10594  </funcprototype></funcsynopsis>
10595</refsynopsisdiv>
10596<refsect1>
10597 <title>Arguments</title>
10598 <variablelist>
10599  <varlistentry>
10600   <term><parameter>dev</parameter></term>
10601   <listitem>
10602    <para>
10603     drm device
10604    </para>
10605   </listitem>
10606  </varlistentry>
10607  <varlistentry>
10608   <term><parameter>id</parameter></term>
10609   <listitem>
10610    <para>
10611     id of the fb object
10612    </para>
10613   </listitem>
10614  </varlistentry>
10615 </variablelist>
10616</refsect1>
10617<refsect1>
10618<title>Description</title>
10619<para>
10620   If successful, this grabs an additional reference to the framebuffer -
10621   callers need to make sure to eventually unreference the returned framebuffer
10622   again, using <parameter>drm_framebuffer_unreference</parameter>.
10623</para>
10624</refsect1>
10625</refentry>
10626
10627<refentry id="API-drm-framebuffer-unreference">
10628<refentryinfo>
10629 <title>LINUX</title>
10630 <productname>Kernel Hackers Manual</productname>
10631 <date>July 2017</date>
10632</refentryinfo>
10633<refmeta>
10634 <refentrytitle><phrase>drm_framebuffer_unreference</phrase></refentrytitle>
10635 <manvolnum>9</manvolnum>
10636 <refmiscinfo class="version">4.1.27</refmiscinfo>
10637</refmeta>
10638<refnamediv>
10639 <refname>drm_framebuffer_unreference</refname>
10640 <refpurpose>
10641     unref a framebuffer
10642 </refpurpose>
10643</refnamediv>
10644<refsynopsisdiv>
10645 <title>Synopsis</title>
10646  <funcsynopsis><funcprototype>
10647   <funcdef>void <function>drm_framebuffer_unreference </function></funcdef>
10648   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
10649  </funcprototype></funcsynopsis>
10650</refsynopsisdiv>
10651<refsect1>
10652 <title>Arguments</title>
10653 <variablelist>
10654  <varlistentry>
10655   <term><parameter>fb</parameter></term>
10656   <listitem>
10657    <para>
10658     framebuffer to unref
10659    </para>
10660   </listitem>
10661  </varlistentry>
10662 </variablelist>
10663</refsect1>
10664<refsect1>
10665<title>Description</title>
10666<para>
10667   This functions decrements the fb's refcount and frees it if it drops to zero.
10668</para>
10669</refsect1>
10670</refentry>
10671
10672<refentry id="API-drm-framebuffer-reference">
10673<refentryinfo>
10674 <title>LINUX</title>
10675 <productname>Kernel Hackers Manual</productname>
10676 <date>July 2017</date>
10677</refentryinfo>
10678<refmeta>
10679 <refentrytitle><phrase>drm_framebuffer_reference</phrase></refentrytitle>
10680 <manvolnum>9</manvolnum>
10681 <refmiscinfo class="version">4.1.27</refmiscinfo>
10682</refmeta>
10683<refnamediv>
10684 <refname>drm_framebuffer_reference</refname>
10685 <refpurpose>
10686     incr the fb refcnt
10687 </refpurpose>
10688</refnamediv>
10689<refsynopsisdiv>
10690 <title>Synopsis</title>
10691  <funcsynopsis><funcprototype>
10692   <funcdef>void <function>drm_framebuffer_reference </function></funcdef>
10693   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
10694  </funcprototype></funcsynopsis>
10695</refsynopsisdiv>
10696<refsect1>
10697 <title>Arguments</title>
10698 <variablelist>
10699  <varlistentry>
10700   <term><parameter>fb</parameter></term>
10701   <listitem>
10702    <para>
10703     framebuffer
10704    </para>
10705   </listitem>
10706  </varlistentry>
10707 </variablelist>
10708</refsect1>
10709<refsect1>
10710<title>Description</title>
10711<para>
10712   This functions increments the fb's refcount.
10713</para>
10714</refsect1>
10715</refentry>
10716
10717<refentry id="API-drm-framebuffer-unregister-private">
10718<refentryinfo>
10719 <title>LINUX</title>
10720 <productname>Kernel Hackers Manual</productname>
10721 <date>July 2017</date>
10722</refentryinfo>
10723<refmeta>
10724 <refentrytitle><phrase>drm_framebuffer_unregister_private</phrase></refentrytitle>
10725 <manvolnum>9</manvolnum>
10726 <refmiscinfo class="version">4.1.27</refmiscinfo>
10727</refmeta>
10728<refnamediv>
10729 <refname>drm_framebuffer_unregister_private</refname>
10730 <refpurpose>
10731     unregister a private fb from the lookup idr
10732 </refpurpose>
10733</refnamediv>
10734<refsynopsisdiv>
10735 <title>Synopsis</title>
10736  <funcsynopsis><funcprototype>
10737   <funcdef>void <function>drm_framebuffer_unregister_private </function></funcdef>
10738   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
10739  </funcprototype></funcsynopsis>
10740</refsynopsisdiv>
10741<refsect1>
10742 <title>Arguments</title>
10743 <variablelist>
10744  <varlistentry>
10745   <term><parameter>fb</parameter></term>
10746   <listitem>
10747    <para>
10748     fb to unregister
10749    </para>
10750   </listitem>
10751  </varlistentry>
10752 </variablelist>
10753</refsect1>
10754<refsect1>
10755<title>Description</title>
10756<para>
10757   Drivers need to call this when cleaning up driver-private framebuffers, e.g.
10758   those used for fbdev. Note that the caller must hold a reference of it's own,
10759   i.e. the object may not be destroyed through this call (since it'll lead to a
10760   locking inversion).
10761</para>
10762</refsect1>
10763</refentry>
10764
10765<refentry id="API-drm-framebuffer-cleanup">
10766<refentryinfo>
10767 <title>LINUX</title>
10768 <productname>Kernel Hackers Manual</productname>
10769 <date>July 2017</date>
10770</refentryinfo>
10771<refmeta>
10772 <refentrytitle><phrase>drm_framebuffer_cleanup</phrase></refentrytitle>
10773 <manvolnum>9</manvolnum>
10774 <refmiscinfo class="version">4.1.27</refmiscinfo>
10775</refmeta>
10776<refnamediv>
10777 <refname>drm_framebuffer_cleanup</refname>
10778 <refpurpose>
10779     remove a framebuffer object
10780 </refpurpose>
10781</refnamediv>
10782<refsynopsisdiv>
10783 <title>Synopsis</title>
10784  <funcsynopsis><funcprototype>
10785   <funcdef>void <function>drm_framebuffer_cleanup </function></funcdef>
10786   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
10787  </funcprototype></funcsynopsis>
10788</refsynopsisdiv>
10789<refsect1>
10790 <title>Arguments</title>
10791 <variablelist>
10792  <varlistentry>
10793   <term><parameter>fb</parameter></term>
10794   <listitem>
10795    <para>
10796     framebuffer to remove
10797    </para>
10798   </listitem>
10799  </varlistentry>
10800 </variablelist>
10801</refsect1>
10802<refsect1>
10803<title>Description</title>
10804<para>
10805   Cleanup framebuffer. This function is intended to be used from the drivers
10806   -&gt;destroy callback. It can also be used to clean up driver private
10807   framebuffers embedded into a larger structure.
10808   </para><para>
10809
10810   Note that this function does not remove the fb from active usuage - if it is
10811   still used anywhere, hilarity can ensue since userspace could call getfb on
10812   the id and get back -EINVAL. Obviously no concern at driver unload time.
10813   </para><para>
10814
10815   Also, the framebuffer will not be removed from the lookup idr - for
10816   user-created framebuffers this will happen in in the rmfb ioctl. For
10817   driver-private objects (e.g. for fbdev) drivers need to explicitly call
10818   drm_framebuffer_unregister_private.
10819</para>
10820</refsect1>
10821</refentry>
10822
10823<refentry id="API-drm-framebuffer-remove">
10824<refentryinfo>
10825 <title>LINUX</title>
10826 <productname>Kernel Hackers Manual</productname>
10827 <date>July 2017</date>
10828</refentryinfo>
10829<refmeta>
10830 <refentrytitle><phrase>drm_framebuffer_remove</phrase></refentrytitle>
10831 <manvolnum>9</manvolnum>
10832 <refmiscinfo class="version">4.1.27</refmiscinfo>
10833</refmeta>
10834<refnamediv>
10835 <refname>drm_framebuffer_remove</refname>
10836 <refpurpose>
10837     remove and unreference a framebuffer object
10838 </refpurpose>
10839</refnamediv>
10840<refsynopsisdiv>
10841 <title>Synopsis</title>
10842  <funcsynopsis><funcprototype>
10843   <funcdef>void <function>drm_framebuffer_remove </function></funcdef>
10844   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
10845  </funcprototype></funcsynopsis>
10846</refsynopsisdiv>
10847<refsect1>
10848 <title>Arguments</title>
10849 <variablelist>
10850  <varlistentry>
10851   <term><parameter>fb</parameter></term>
10852   <listitem>
10853    <para>
10854     framebuffer to remove
10855    </para>
10856   </listitem>
10857  </varlistentry>
10858 </variablelist>
10859</refsect1>
10860<refsect1>
10861<title>Description</title>
10862<para>
10863   Scans all the CRTCs and planes in <parameter>dev</parameter>'s mode_config.  If they're
10864   using <parameter>fb</parameter>, removes it, setting it to NULL. Then drops the reference to the
10865   passed-in framebuffer. Might take the modeset locks.
10866   </para><para>
10867
10868   Note that this function optimizes the cleanup away if the caller holds the
10869   last reference to the framebuffer. It is also guaranteed to not take the
10870   modeset locks in this case.
10871</para>
10872</refsect1>
10873</refentry>
10874
10875<refentry id="API-drm-crtc-init-with-planes">
10876<refentryinfo>
10877 <title>LINUX</title>
10878 <productname>Kernel Hackers Manual</productname>
10879 <date>July 2017</date>
10880</refentryinfo>
10881<refmeta>
10882 <refentrytitle><phrase>drm_crtc_init_with_planes</phrase></refentrytitle>
10883 <manvolnum>9</manvolnum>
10884 <refmiscinfo class="version">4.1.27</refmiscinfo>
10885</refmeta>
10886<refnamediv>
10887 <refname>drm_crtc_init_with_planes</refname>
10888 <refpurpose>
10889     Initialise a new CRTC object with specified primary and cursor planes.
10890 </refpurpose>
10891</refnamediv>
10892<refsynopsisdiv>
10893 <title>Synopsis</title>
10894  <funcsynopsis><funcprototype>
10895   <funcdef>int <function>drm_crtc_init_with_planes </function></funcdef>
10896   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
10897   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
10898   <paramdef>struct drm_plane * <parameter>primary</parameter></paramdef>
10899   <paramdef>struct drm_plane * <parameter>cursor</parameter></paramdef>
10900   <paramdef>const struct drm_crtc_funcs * <parameter>funcs</parameter></paramdef>
10901  </funcprototype></funcsynopsis>
10902</refsynopsisdiv>
10903<refsect1>
10904 <title>Arguments</title>
10905 <variablelist>
10906  <varlistentry>
10907   <term><parameter>dev</parameter></term>
10908   <listitem>
10909    <para>
10910     DRM device
10911    </para>
10912   </listitem>
10913  </varlistentry>
10914  <varlistentry>
10915   <term><parameter>crtc</parameter></term>
10916   <listitem>
10917    <para>
10918     CRTC object to init
10919    </para>
10920   </listitem>
10921  </varlistentry>
10922  <varlistentry>
10923   <term><parameter>primary</parameter></term>
10924   <listitem>
10925    <para>
10926     Primary plane for CRTC
10927    </para>
10928   </listitem>
10929  </varlistentry>
10930  <varlistentry>
10931   <term><parameter>cursor</parameter></term>
10932   <listitem>
10933    <para>
10934     Cursor plane for CRTC
10935    </para>
10936   </listitem>
10937  </varlistentry>
10938  <varlistentry>
10939   <term><parameter>funcs</parameter></term>
10940   <listitem>
10941    <para>
10942     callbacks for the new CRTC
10943    </para>
10944   </listitem>
10945  </varlistentry>
10946 </variablelist>
10947</refsect1>
10948<refsect1>
10949<title>Description</title>
10950<para>
10951   Inits a new object created as base part of a driver crtc object.
10952</para>
10953</refsect1>
10954<refsect1>
10955<title>Returns</title>
10956<para>
10957   Zero on success, error code on failure.
10958</para>
10959</refsect1>
10960</refentry>
10961
10962<refentry id="API-drm-crtc-cleanup">
10963<refentryinfo>
10964 <title>LINUX</title>
10965 <productname>Kernel Hackers Manual</productname>
10966 <date>July 2017</date>
10967</refentryinfo>
10968<refmeta>
10969 <refentrytitle><phrase>drm_crtc_cleanup</phrase></refentrytitle>
10970 <manvolnum>9</manvolnum>
10971 <refmiscinfo class="version">4.1.27</refmiscinfo>
10972</refmeta>
10973<refnamediv>
10974 <refname>drm_crtc_cleanup</refname>
10975 <refpurpose>
10976     Clean up the core crtc usage
10977 </refpurpose>
10978</refnamediv>
10979<refsynopsisdiv>
10980 <title>Synopsis</title>
10981  <funcsynopsis><funcprototype>
10982   <funcdef>void <function>drm_crtc_cleanup </function></funcdef>
10983   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
10984  </funcprototype></funcsynopsis>
10985</refsynopsisdiv>
10986<refsect1>
10987 <title>Arguments</title>
10988 <variablelist>
10989  <varlistentry>
10990   <term><parameter>crtc</parameter></term>
10991   <listitem>
10992    <para>
10993     CRTC to cleanup
10994    </para>
10995   </listitem>
10996  </varlistentry>
10997 </variablelist>
10998</refsect1>
10999<refsect1>
11000<title>Description</title>
11001<para>
11002   This function cleans up <parameter>crtc</parameter> and removes it from the DRM mode setting
11003   core. Note that the function does *not* free the crtc structure itself,
11004   this is the responsibility of the caller.
11005</para>
11006</refsect1>
11007</refentry>
11008
11009<refentry id="API-drm-crtc-index">
11010<refentryinfo>
11011 <title>LINUX</title>
11012 <productname>Kernel Hackers Manual</productname>
11013 <date>July 2017</date>
11014</refentryinfo>
11015<refmeta>
11016 <refentrytitle><phrase>drm_crtc_index</phrase></refentrytitle>
11017 <manvolnum>9</manvolnum>
11018 <refmiscinfo class="version">4.1.27</refmiscinfo>
11019</refmeta>
11020<refnamediv>
11021 <refname>drm_crtc_index</refname>
11022 <refpurpose>
11023     find the index of a registered CRTC
11024 </refpurpose>
11025</refnamediv>
11026<refsynopsisdiv>
11027 <title>Synopsis</title>
11028  <funcsynopsis><funcprototype>
11029   <funcdef>unsigned int <function>drm_crtc_index </function></funcdef>
11030   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
11031  </funcprototype></funcsynopsis>
11032</refsynopsisdiv>
11033<refsect1>
11034 <title>Arguments</title>
11035 <variablelist>
11036  <varlistentry>
11037   <term><parameter>crtc</parameter></term>
11038   <listitem>
11039    <para>
11040     CRTC to find index for
11041    </para>
11042   </listitem>
11043  </varlistentry>
11044 </variablelist>
11045</refsect1>
11046<refsect1>
11047<title>Description</title>
11048<para>
11049   Given a registered CRTC, return the index of that CRTC within a DRM
11050   device's list of CRTCs.
11051</para>
11052</refsect1>
11053</refentry>
11054
11055<refentry id="API-drm-display-info-set-bus-formats">
11056<refentryinfo>
11057 <title>LINUX</title>
11058 <productname>Kernel Hackers Manual</productname>
11059 <date>July 2017</date>
11060</refentryinfo>
11061<refmeta>
11062 <refentrytitle><phrase>drm_display_info_set_bus_formats</phrase></refentrytitle>
11063 <manvolnum>9</manvolnum>
11064 <refmiscinfo class="version">4.1.27</refmiscinfo>
11065</refmeta>
11066<refnamediv>
11067 <refname>drm_display_info_set_bus_formats</refname>
11068 <refpurpose>
11069     set the supported bus formats
11070 </refpurpose>
11071</refnamediv>
11072<refsynopsisdiv>
11073 <title>Synopsis</title>
11074  <funcsynopsis><funcprototype>
11075   <funcdef>int <function>drm_display_info_set_bus_formats </function></funcdef>
11076   <paramdef>struct drm_display_info * <parameter>info</parameter></paramdef>
11077   <paramdef>const u32 * <parameter>formats</parameter></paramdef>
11078   <paramdef>unsigned int <parameter>num_formats</parameter></paramdef>
11079  </funcprototype></funcsynopsis>
11080</refsynopsisdiv>
11081<refsect1>
11082 <title>Arguments</title>
11083 <variablelist>
11084  <varlistentry>
11085   <term><parameter>info</parameter></term>
11086   <listitem>
11087    <para>
11088     display info to store bus formats in
11089    </para>
11090   </listitem>
11091  </varlistentry>
11092  <varlistentry>
11093   <term><parameter>formats</parameter></term>
11094   <listitem>
11095    <para>
11096     array containing the supported bus formats
11097    </para>
11098   </listitem>
11099  </varlistentry>
11100  <varlistentry>
11101   <term><parameter>num_formats</parameter></term>
11102   <listitem>
11103    <para>
11104     the number of entries in the fmts array
11105    </para>
11106   </listitem>
11107  </varlistentry>
11108 </variablelist>
11109</refsect1>
11110<refsect1>
11111<title>Description</title>
11112<para>
11113   Store the supported bus formats in display info structure.
11114   See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for
11115   a full list of available formats.
11116</para>
11117</refsect1>
11118</refentry>
11119
11120<refentry id="API-drm-connector-init">
11121<refentryinfo>
11122 <title>LINUX</title>
11123 <productname>Kernel Hackers Manual</productname>
11124 <date>July 2017</date>
11125</refentryinfo>
11126<refmeta>
11127 <refentrytitle><phrase>drm_connector_init</phrase></refentrytitle>
11128 <manvolnum>9</manvolnum>
11129 <refmiscinfo class="version">4.1.27</refmiscinfo>
11130</refmeta>
11131<refnamediv>
11132 <refname>drm_connector_init</refname>
11133 <refpurpose>
11134     Init a preallocated connector
11135 </refpurpose>
11136</refnamediv>
11137<refsynopsisdiv>
11138 <title>Synopsis</title>
11139  <funcsynopsis><funcprototype>
11140   <funcdef>int <function>drm_connector_init </function></funcdef>
11141   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11142   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
11143   <paramdef>const struct drm_connector_funcs * <parameter>funcs</parameter></paramdef>
11144   <paramdef>int <parameter>connector_type</parameter></paramdef>
11145  </funcprototype></funcsynopsis>
11146</refsynopsisdiv>
11147<refsect1>
11148 <title>Arguments</title>
11149 <variablelist>
11150  <varlistentry>
11151   <term><parameter>dev</parameter></term>
11152   <listitem>
11153    <para>
11154     DRM device
11155    </para>
11156   </listitem>
11157  </varlistentry>
11158  <varlistentry>
11159   <term><parameter>connector</parameter></term>
11160   <listitem>
11161    <para>
11162     the connector to init
11163    </para>
11164   </listitem>
11165  </varlistentry>
11166  <varlistentry>
11167   <term><parameter>funcs</parameter></term>
11168   <listitem>
11169    <para>
11170     callbacks for this connector
11171    </para>
11172   </listitem>
11173  </varlistentry>
11174  <varlistentry>
11175   <term><parameter>connector_type</parameter></term>
11176   <listitem>
11177    <para>
11178     user visible type of the connector
11179    </para>
11180   </listitem>
11181  </varlistentry>
11182 </variablelist>
11183</refsect1>
11184<refsect1>
11185<title>Description</title>
11186<para>
11187   Initialises a preallocated connector. Connectors should be
11188   subclassed as part of driver connector objects.
11189</para>
11190</refsect1>
11191<refsect1>
11192<title>Returns</title>
11193<para>
11194   Zero on success, error code on failure.
11195</para>
11196</refsect1>
11197</refentry>
11198
11199<refentry id="API-drm-connector-cleanup">
11200<refentryinfo>
11201 <title>LINUX</title>
11202 <productname>Kernel Hackers Manual</productname>
11203 <date>July 2017</date>
11204</refentryinfo>
11205<refmeta>
11206 <refentrytitle><phrase>drm_connector_cleanup</phrase></refentrytitle>
11207 <manvolnum>9</manvolnum>
11208 <refmiscinfo class="version">4.1.27</refmiscinfo>
11209</refmeta>
11210<refnamediv>
11211 <refname>drm_connector_cleanup</refname>
11212 <refpurpose>
11213     cleans up an initialised connector
11214 </refpurpose>
11215</refnamediv>
11216<refsynopsisdiv>
11217 <title>Synopsis</title>
11218  <funcsynopsis><funcprototype>
11219   <funcdef>void <function>drm_connector_cleanup </function></funcdef>
11220   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
11221  </funcprototype></funcsynopsis>
11222</refsynopsisdiv>
11223<refsect1>
11224 <title>Arguments</title>
11225 <variablelist>
11226  <varlistentry>
11227   <term><parameter>connector</parameter></term>
11228   <listitem>
11229    <para>
11230     connector to cleanup
11231    </para>
11232   </listitem>
11233  </varlistentry>
11234 </variablelist>
11235</refsect1>
11236<refsect1>
11237<title>Description</title>
11238<para>
11239   Cleans up the connector but doesn't free the object.
11240</para>
11241</refsect1>
11242</refentry>
11243
11244<refentry id="API-drm-connector-index">
11245<refentryinfo>
11246 <title>LINUX</title>
11247 <productname>Kernel Hackers Manual</productname>
11248 <date>July 2017</date>
11249</refentryinfo>
11250<refmeta>
11251 <refentrytitle><phrase>drm_connector_index</phrase></refentrytitle>
11252 <manvolnum>9</manvolnum>
11253 <refmiscinfo class="version">4.1.27</refmiscinfo>
11254</refmeta>
11255<refnamediv>
11256 <refname>drm_connector_index</refname>
11257 <refpurpose>
11258     find the index of a registered connector
11259 </refpurpose>
11260</refnamediv>
11261<refsynopsisdiv>
11262 <title>Synopsis</title>
11263  <funcsynopsis><funcprototype>
11264   <funcdef>unsigned int <function>drm_connector_index </function></funcdef>
11265   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
11266  </funcprototype></funcsynopsis>
11267</refsynopsisdiv>
11268<refsect1>
11269 <title>Arguments</title>
11270 <variablelist>
11271  <varlistentry>
11272   <term><parameter>connector</parameter></term>
11273   <listitem>
11274    <para>
11275     connector to find index for
11276    </para>
11277   </listitem>
11278  </varlistentry>
11279 </variablelist>
11280</refsect1>
11281<refsect1>
11282<title>Description</title>
11283<para>
11284   Given a registered connector, return the index of that connector within a DRM
11285   device's list of connectors.
11286</para>
11287</refsect1>
11288</refentry>
11289
11290<refentry id="API-drm-connector-register">
11291<refentryinfo>
11292 <title>LINUX</title>
11293 <productname>Kernel Hackers Manual</productname>
11294 <date>July 2017</date>
11295</refentryinfo>
11296<refmeta>
11297 <refentrytitle><phrase>drm_connector_register</phrase></refentrytitle>
11298 <manvolnum>9</manvolnum>
11299 <refmiscinfo class="version">4.1.27</refmiscinfo>
11300</refmeta>
11301<refnamediv>
11302 <refname>drm_connector_register</refname>
11303 <refpurpose>
11304     register a connector
11305 </refpurpose>
11306</refnamediv>
11307<refsynopsisdiv>
11308 <title>Synopsis</title>
11309  <funcsynopsis><funcprototype>
11310   <funcdef>int <function>drm_connector_register </function></funcdef>
11311   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
11312  </funcprototype></funcsynopsis>
11313</refsynopsisdiv>
11314<refsect1>
11315 <title>Arguments</title>
11316 <variablelist>
11317  <varlistentry>
11318   <term><parameter>connector</parameter></term>
11319   <listitem>
11320    <para>
11321     the connector to register
11322    </para>
11323   </listitem>
11324  </varlistentry>
11325 </variablelist>
11326</refsect1>
11327<refsect1>
11328<title>Description</title>
11329<para>
11330   Register userspace interfaces for a connector
11331</para>
11332</refsect1>
11333<refsect1>
11334<title>Returns</title>
11335<para>
11336   Zero on success, error code on failure.
11337</para>
11338</refsect1>
11339</refentry>
11340
11341<refentry id="API-drm-connector-unregister">
11342<refentryinfo>
11343 <title>LINUX</title>
11344 <productname>Kernel Hackers Manual</productname>
11345 <date>July 2017</date>
11346</refentryinfo>
11347<refmeta>
11348 <refentrytitle><phrase>drm_connector_unregister</phrase></refentrytitle>
11349 <manvolnum>9</manvolnum>
11350 <refmiscinfo class="version">4.1.27</refmiscinfo>
11351</refmeta>
11352<refnamediv>
11353 <refname>drm_connector_unregister</refname>
11354 <refpurpose>
11355     unregister a connector
11356 </refpurpose>
11357</refnamediv>
11358<refsynopsisdiv>
11359 <title>Synopsis</title>
11360  <funcsynopsis><funcprototype>
11361   <funcdef>void <function>drm_connector_unregister </function></funcdef>
11362   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
11363  </funcprototype></funcsynopsis>
11364</refsynopsisdiv>
11365<refsect1>
11366 <title>Arguments</title>
11367 <variablelist>
11368  <varlistentry>
11369   <term><parameter>connector</parameter></term>
11370   <listitem>
11371    <para>
11372     the connector to unregister
11373    </para>
11374   </listitem>
11375  </varlistentry>
11376 </variablelist>
11377</refsect1>
11378<refsect1>
11379<title>Description</title>
11380<para>
11381   Unregister userspace interfaces for a connector
11382</para>
11383</refsect1>
11384</refentry>
11385
11386<refentry id="API-drm-connector-unplug-all">
11387<refentryinfo>
11388 <title>LINUX</title>
11389 <productname>Kernel Hackers Manual</productname>
11390 <date>July 2017</date>
11391</refentryinfo>
11392<refmeta>
11393 <refentrytitle><phrase>drm_connector_unplug_all</phrase></refentrytitle>
11394 <manvolnum>9</manvolnum>
11395 <refmiscinfo class="version">4.1.27</refmiscinfo>
11396</refmeta>
11397<refnamediv>
11398 <refname>drm_connector_unplug_all</refname>
11399 <refpurpose>
11400     unregister connector userspace interfaces
11401 </refpurpose>
11402</refnamediv>
11403<refsynopsisdiv>
11404 <title>Synopsis</title>
11405  <funcsynopsis><funcprototype>
11406   <funcdef>void <function>drm_connector_unplug_all </function></funcdef>
11407   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11408  </funcprototype></funcsynopsis>
11409</refsynopsisdiv>
11410<refsect1>
11411 <title>Arguments</title>
11412 <variablelist>
11413  <varlistentry>
11414   <term><parameter>dev</parameter></term>
11415   <listitem>
11416    <para>
11417     drm device
11418    </para>
11419   </listitem>
11420  </varlistentry>
11421 </variablelist>
11422</refsect1>
11423<refsect1>
11424<title>Description</title>
11425<para>
11426   This function unregisters all connector userspace interfaces in sysfs. Should
11427   be call when the device is disconnected, e.g. from an usb driver's
11428   -&gt;disconnect callback.
11429</para>
11430</refsect1>
11431</refentry>
11432
11433<refentry id="API-drm-encoder-init">
11434<refentryinfo>
11435 <title>LINUX</title>
11436 <productname>Kernel Hackers Manual</productname>
11437 <date>July 2017</date>
11438</refentryinfo>
11439<refmeta>
11440 <refentrytitle><phrase>drm_encoder_init</phrase></refentrytitle>
11441 <manvolnum>9</manvolnum>
11442 <refmiscinfo class="version">4.1.27</refmiscinfo>
11443</refmeta>
11444<refnamediv>
11445 <refname>drm_encoder_init</refname>
11446 <refpurpose>
11447     Init a preallocated encoder
11448 </refpurpose>
11449</refnamediv>
11450<refsynopsisdiv>
11451 <title>Synopsis</title>
11452  <funcsynopsis><funcprototype>
11453   <funcdef>int <function>drm_encoder_init </function></funcdef>
11454   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11455   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
11456   <paramdef>const struct drm_encoder_funcs * <parameter>funcs</parameter></paramdef>
11457   <paramdef>int <parameter>encoder_type</parameter></paramdef>
11458  </funcprototype></funcsynopsis>
11459</refsynopsisdiv>
11460<refsect1>
11461 <title>Arguments</title>
11462 <variablelist>
11463  <varlistentry>
11464   <term><parameter>dev</parameter></term>
11465   <listitem>
11466    <para>
11467     drm device
11468    </para>
11469   </listitem>
11470  </varlistentry>
11471  <varlistentry>
11472   <term><parameter>encoder</parameter></term>
11473   <listitem>
11474    <para>
11475     the encoder to init
11476    </para>
11477   </listitem>
11478  </varlistentry>
11479  <varlistentry>
11480   <term><parameter>funcs</parameter></term>
11481   <listitem>
11482    <para>
11483     callbacks for this encoder
11484    </para>
11485   </listitem>
11486  </varlistentry>
11487  <varlistentry>
11488   <term><parameter>encoder_type</parameter></term>
11489   <listitem>
11490    <para>
11491     user visible type of the encoder
11492    </para>
11493   </listitem>
11494  </varlistentry>
11495 </variablelist>
11496</refsect1>
11497<refsect1>
11498<title>Description</title>
11499<para>
11500   Initialises a preallocated encoder. Encoder should be
11501   subclassed as part of driver encoder objects.
11502</para>
11503</refsect1>
11504<refsect1>
11505<title>Returns</title>
11506<para>
11507   Zero on success, error code on failure.
11508</para>
11509</refsect1>
11510</refentry>
11511
11512<refentry id="API-drm-encoder-cleanup">
11513<refentryinfo>
11514 <title>LINUX</title>
11515 <productname>Kernel Hackers Manual</productname>
11516 <date>July 2017</date>
11517</refentryinfo>
11518<refmeta>
11519 <refentrytitle><phrase>drm_encoder_cleanup</phrase></refentrytitle>
11520 <manvolnum>9</manvolnum>
11521 <refmiscinfo class="version">4.1.27</refmiscinfo>
11522</refmeta>
11523<refnamediv>
11524 <refname>drm_encoder_cleanup</refname>
11525 <refpurpose>
11526     cleans up an initialised encoder
11527 </refpurpose>
11528</refnamediv>
11529<refsynopsisdiv>
11530 <title>Synopsis</title>
11531  <funcsynopsis><funcprototype>
11532   <funcdef>void <function>drm_encoder_cleanup </function></funcdef>
11533   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
11534  </funcprototype></funcsynopsis>
11535</refsynopsisdiv>
11536<refsect1>
11537 <title>Arguments</title>
11538 <variablelist>
11539  <varlistentry>
11540   <term><parameter>encoder</parameter></term>
11541   <listitem>
11542    <para>
11543     encoder to cleanup
11544    </para>
11545   </listitem>
11546  </varlistentry>
11547 </variablelist>
11548</refsect1>
11549<refsect1>
11550<title>Description</title>
11551<para>
11552   Cleans up the encoder but doesn't free the object.
11553</para>
11554</refsect1>
11555</refentry>
11556
11557<refentry id="API-drm-universal-plane-init">
11558<refentryinfo>
11559 <title>LINUX</title>
11560 <productname>Kernel Hackers Manual</productname>
11561 <date>July 2017</date>
11562</refentryinfo>
11563<refmeta>
11564 <refentrytitle><phrase>drm_universal_plane_init</phrase></refentrytitle>
11565 <manvolnum>9</manvolnum>
11566 <refmiscinfo class="version">4.1.27</refmiscinfo>
11567</refmeta>
11568<refnamediv>
11569 <refname>drm_universal_plane_init</refname>
11570 <refpurpose>
11571     Initialize a new universal plane object
11572 </refpurpose>
11573</refnamediv>
11574<refsynopsisdiv>
11575 <title>Synopsis</title>
11576  <funcsynopsis><funcprototype>
11577   <funcdef>int <function>drm_universal_plane_init </function></funcdef>
11578   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11579   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
11580   <paramdef>unsigned long <parameter>possible_crtcs</parameter></paramdef>
11581   <paramdef>const struct drm_plane_funcs * <parameter>funcs</parameter></paramdef>
11582   <paramdef>const uint32_t * <parameter>formats</parameter></paramdef>
11583   <paramdef>uint32_t <parameter>format_count</parameter></paramdef>
11584   <paramdef>enum drm_plane_type <parameter>type</parameter></paramdef>
11585  </funcprototype></funcsynopsis>
11586</refsynopsisdiv>
11587<refsect1>
11588 <title>Arguments</title>
11589 <variablelist>
11590  <varlistentry>
11591   <term><parameter>dev</parameter></term>
11592   <listitem>
11593    <para>
11594     DRM device
11595    </para>
11596   </listitem>
11597  </varlistentry>
11598  <varlistentry>
11599   <term><parameter>plane</parameter></term>
11600   <listitem>
11601    <para>
11602     plane object to init
11603    </para>
11604   </listitem>
11605  </varlistentry>
11606  <varlistentry>
11607   <term><parameter>possible_crtcs</parameter></term>
11608   <listitem>
11609    <para>
11610     bitmask of possible CRTCs
11611    </para>
11612   </listitem>
11613  </varlistentry>
11614  <varlistentry>
11615   <term><parameter>funcs</parameter></term>
11616   <listitem>
11617    <para>
11618     callbacks for the new plane
11619    </para>
11620   </listitem>
11621  </varlistentry>
11622  <varlistentry>
11623   <term><parameter>formats</parameter></term>
11624   <listitem>
11625    <para>
11626     array of supported formats (<constant>DRM_FORMAT_</constant>*)
11627    </para>
11628   </listitem>
11629  </varlistentry>
11630  <varlistentry>
11631   <term><parameter>format_count</parameter></term>
11632   <listitem>
11633    <para>
11634     number of elements in <parameter>formats</parameter>
11635    </para>
11636   </listitem>
11637  </varlistentry>
11638  <varlistentry>
11639   <term><parameter>type</parameter></term>
11640   <listitem>
11641    <para>
11642     type of plane (overlay, primary, cursor)
11643    </para>
11644   </listitem>
11645  </varlistentry>
11646 </variablelist>
11647</refsect1>
11648<refsect1>
11649<title>Description</title>
11650<para>
11651   Initializes a plane object of type <parameter>type</parameter>.
11652</para>
11653</refsect1>
11654<refsect1>
11655<title>Returns</title>
11656<para>
11657   Zero on success, error code on failure.
11658</para>
11659</refsect1>
11660</refentry>
11661
11662<refentry id="API-drm-plane-init">
11663<refentryinfo>
11664 <title>LINUX</title>
11665 <productname>Kernel Hackers Manual</productname>
11666 <date>July 2017</date>
11667</refentryinfo>
11668<refmeta>
11669 <refentrytitle><phrase>drm_plane_init</phrase></refentrytitle>
11670 <manvolnum>9</manvolnum>
11671 <refmiscinfo class="version">4.1.27</refmiscinfo>
11672</refmeta>
11673<refnamediv>
11674 <refname>drm_plane_init</refname>
11675 <refpurpose>
11676     Initialize a legacy plane
11677 </refpurpose>
11678</refnamediv>
11679<refsynopsisdiv>
11680 <title>Synopsis</title>
11681  <funcsynopsis><funcprototype>
11682   <funcdef>int <function>drm_plane_init </function></funcdef>
11683   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11684   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
11685   <paramdef>unsigned long <parameter>possible_crtcs</parameter></paramdef>
11686   <paramdef>const struct drm_plane_funcs * <parameter>funcs</parameter></paramdef>
11687   <paramdef>const uint32_t * <parameter>formats</parameter></paramdef>
11688   <paramdef>uint32_t <parameter>format_count</parameter></paramdef>
11689   <paramdef>bool <parameter>is_primary</parameter></paramdef>
11690  </funcprototype></funcsynopsis>
11691</refsynopsisdiv>
11692<refsect1>
11693 <title>Arguments</title>
11694 <variablelist>
11695  <varlistentry>
11696   <term><parameter>dev</parameter></term>
11697   <listitem>
11698    <para>
11699     DRM device
11700    </para>
11701   </listitem>
11702  </varlistentry>
11703  <varlistentry>
11704   <term><parameter>plane</parameter></term>
11705   <listitem>
11706    <para>
11707     plane object to init
11708    </para>
11709   </listitem>
11710  </varlistentry>
11711  <varlistentry>
11712   <term><parameter>possible_crtcs</parameter></term>
11713   <listitem>
11714    <para>
11715     bitmask of possible CRTCs
11716    </para>
11717   </listitem>
11718  </varlistentry>
11719  <varlistentry>
11720   <term><parameter>funcs</parameter></term>
11721   <listitem>
11722    <para>
11723     callbacks for the new plane
11724    </para>
11725   </listitem>
11726  </varlistentry>
11727  <varlistentry>
11728   <term><parameter>formats</parameter></term>
11729   <listitem>
11730    <para>
11731     array of supported formats (<constant>DRM_FORMAT_</constant>*)
11732    </para>
11733   </listitem>
11734  </varlistentry>
11735  <varlistentry>
11736   <term><parameter>format_count</parameter></term>
11737   <listitem>
11738    <para>
11739     number of elements in <parameter>formats</parameter>
11740    </para>
11741   </listitem>
11742  </varlistentry>
11743  <varlistentry>
11744   <term><parameter>is_primary</parameter></term>
11745   <listitem>
11746    <para>
11747     plane type (primary vs overlay)
11748    </para>
11749   </listitem>
11750  </varlistentry>
11751 </variablelist>
11752</refsect1>
11753<refsect1>
11754<title>Description</title>
11755<para>
11756   Legacy API to initialize a DRM plane.
11757   </para><para>
11758
11759   New drivers should call <function>drm_universal_plane_init</function> instead.
11760</para>
11761</refsect1>
11762<refsect1>
11763<title>Returns</title>
11764<para>
11765   Zero on success, error code on failure.
11766</para>
11767</refsect1>
11768</refentry>
11769
11770<refentry id="API-drm-plane-cleanup">
11771<refentryinfo>
11772 <title>LINUX</title>
11773 <productname>Kernel Hackers Manual</productname>
11774 <date>July 2017</date>
11775</refentryinfo>
11776<refmeta>
11777 <refentrytitle><phrase>drm_plane_cleanup</phrase></refentrytitle>
11778 <manvolnum>9</manvolnum>
11779 <refmiscinfo class="version">4.1.27</refmiscinfo>
11780</refmeta>
11781<refnamediv>
11782 <refname>drm_plane_cleanup</refname>
11783 <refpurpose>
11784     Clean up the core plane usage
11785 </refpurpose>
11786</refnamediv>
11787<refsynopsisdiv>
11788 <title>Synopsis</title>
11789  <funcsynopsis><funcprototype>
11790   <funcdef>void <function>drm_plane_cleanup </function></funcdef>
11791   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
11792  </funcprototype></funcsynopsis>
11793</refsynopsisdiv>
11794<refsect1>
11795 <title>Arguments</title>
11796 <variablelist>
11797  <varlistentry>
11798   <term><parameter>plane</parameter></term>
11799   <listitem>
11800    <para>
11801     plane to cleanup
11802    </para>
11803   </listitem>
11804  </varlistentry>
11805 </variablelist>
11806</refsect1>
11807<refsect1>
11808<title>Description</title>
11809<para>
11810   This function cleans up <parameter>plane</parameter> and removes it from the DRM mode setting
11811   core. Note that the function does *not* free the plane structure itself,
11812   this is the responsibility of the caller.
11813</para>
11814</refsect1>
11815</refentry>
11816
11817<refentry id="API-drm-plane-index">
11818<refentryinfo>
11819 <title>LINUX</title>
11820 <productname>Kernel Hackers Manual</productname>
11821 <date>July 2017</date>
11822</refentryinfo>
11823<refmeta>
11824 <refentrytitle><phrase>drm_plane_index</phrase></refentrytitle>
11825 <manvolnum>9</manvolnum>
11826 <refmiscinfo class="version">4.1.27</refmiscinfo>
11827</refmeta>
11828<refnamediv>
11829 <refname>drm_plane_index</refname>
11830 <refpurpose>
11831     find the index of a registered plane
11832 </refpurpose>
11833</refnamediv>
11834<refsynopsisdiv>
11835 <title>Synopsis</title>
11836  <funcsynopsis><funcprototype>
11837   <funcdef>unsigned int <function>drm_plane_index </function></funcdef>
11838   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
11839  </funcprototype></funcsynopsis>
11840</refsynopsisdiv>
11841<refsect1>
11842 <title>Arguments</title>
11843 <variablelist>
11844  <varlistentry>
11845   <term><parameter>plane</parameter></term>
11846   <listitem>
11847    <para>
11848     plane to find index for
11849    </para>
11850   </listitem>
11851  </varlistentry>
11852 </variablelist>
11853</refsect1>
11854<refsect1>
11855<title>Description</title>
11856<para>
11857   Given a registered plane, return the index of that CRTC within a DRM
11858   device's list of planes.
11859</para>
11860</refsect1>
11861</refentry>
11862
11863<refentry id="API-drm-plane-force-disable">
11864<refentryinfo>
11865 <title>LINUX</title>
11866 <productname>Kernel Hackers Manual</productname>
11867 <date>July 2017</date>
11868</refentryinfo>
11869<refmeta>
11870 <refentrytitle><phrase>drm_plane_force_disable</phrase></refentrytitle>
11871 <manvolnum>9</manvolnum>
11872 <refmiscinfo class="version">4.1.27</refmiscinfo>
11873</refmeta>
11874<refnamediv>
11875 <refname>drm_plane_force_disable</refname>
11876 <refpurpose>
11877     Forcibly disable a plane
11878 </refpurpose>
11879</refnamediv>
11880<refsynopsisdiv>
11881 <title>Synopsis</title>
11882  <funcsynopsis><funcprototype>
11883   <funcdef>void <function>drm_plane_force_disable </function></funcdef>
11884   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
11885  </funcprototype></funcsynopsis>
11886</refsynopsisdiv>
11887<refsect1>
11888 <title>Arguments</title>
11889 <variablelist>
11890  <varlistentry>
11891   <term><parameter>plane</parameter></term>
11892   <listitem>
11893    <para>
11894     plane to disable
11895    </para>
11896   </listitem>
11897  </varlistentry>
11898 </variablelist>
11899</refsect1>
11900<refsect1>
11901<title>Description</title>
11902<para>
11903   Forces the plane to be disabled.
11904   </para><para>
11905
11906   Used when the plane's current framebuffer is destroyed,
11907   and when restoring fbdev mode.
11908</para>
11909</refsect1>
11910</refentry>
11911
11912<refentry id="API-drm-mode-create-dvi-i-properties">
11913<refentryinfo>
11914 <title>LINUX</title>
11915 <productname>Kernel Hackers Manual</productname>
11916 <date>July 2017</date>
11917</refentryinfo>
11918<refmeta>
11919 <refentrytitle><phrase>drm_mode_create_dvi_i_properties</phrase></refentrytitle>
11920 <manvolnum>9</manvolnum>
11921 <refmiscinfo class="version">4.1.27</refmiscinfo>
11922</refmeta>
11923<refnamediv>
11924 <refname>drm_mode_create_dvi_i_properties</refname>
11925 <refpurpose>
11926     create DVI-I specific connector properties
11927 </refpurpose>
11928</refnamediv>
11929<refsynopsisdiv>
11930 <title>Synopsis</title>
11931  <funcsynopsis><funcprototype>
11932   <funcdef>int <function>drm_mode_create_dvi_i_properties </function></funcdef>
11933   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11934  </funcprototype></funcsynopsis>
11935</refsynopsisdiv>
11936<refsect1>
11937 <title>Arguments</title>
11938 <variablelist>
11939  <varlistentry>
11940   <term><parameter>dev</parameter></term>
11941   <listitem>
11942    <para>
11943     DRM device
11944    </para>
11945   </listitem>
11946  </varlistentry>
11947 </variablelist>
11948</refsect1>
11949<refsect1>
11950<title>Description</title>
11951<para>
11952   Called by a driver the first time a DVI-I connector is made.
11953</para>
11954</refsect1>
11955</refentry>
11956
11957<refentry id="API-drm-mode-create-tv-properties">
11958<refentryinfo>
11959 <title>LINUX</title>
11960 <productname>Kernel Hackers Manual</productname>
11961 <date>July 2017</date>
11962</refentryinfo>
11963<refmeta>
11964 <refentrytitle><phrase>drm_mode_create_tv_properties</phrase></refentrytitle>
11965 <manvolnum>9</manvolnum>
11966 <refmiscinfo class="version">4.1.27</refmiscinfo>
11967</refmeta>
11968<refnamediv>
11969 <refname>drm_mode_create_tv_properties</refname>
11970 <refpurpose>
11971     create TV specific connector properties
11972 </refpurpose>
11973</refnamediv>
11974<refsynopsisdiv>
11975 <title>Synopsis</title>
11976  <funcsynopsis><funcprototype>
11977   <funcdef>int <function>drm_mode_create_tv_properties </function></funcdef>
11978   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
11979   <paramdef>unsigned int <parameter>num_modes</parameter></paramdef>
11980   <paramdef>char * <parameter>modes[]</parameter></paramdef>
11981  </funcprototype></funcsynopsis>
11982</refsynopsisdiv>
11983<refsect1>
11984 <title>Arguments</title>
11985 <variablelist>
11986  <varlistentry>
11987   <term><parameter>dev</parameter></term>
11988   <listitem>
11989    <para>
11990     DRM device
11991    </para>
11992   </listitem>
11993  </varlistentry>
11994  <varlistentry>
11995   <term><parameter>num_modes</parameter></term>
11996   <listitem>
11997    <para>
11998     number of different TV formats (modes) supported
11999    </para>
12000   </listitem>
12001  </varlistentry>
12002  <varlistentry>
12003   <term><parameter>modes[]</parameter></term>
12004   <listitem>
12005    <para>
12006     array of pointers to strings containing name of each format
12007    </para>
12008   </listitem>
12009  </varlistentry>
12010 </variablelist>
12011</refsect1>
12012<refsect1>
12013<title>Description</title>
12014<para>
12015   Called by a driver's TV initialization routine, this function creates
12016   the TV specific connector properties for a given device.  Caller is
12017   responsible for allocating a list of format names and passing them to
12018   this routine.
12019</para>
12020</refsect1>
12021</refentry>
12022
12023<refentry id="API-drm-mode-create-scaling-mode-property">
12024<refentryinfo>
12025 <title>LINUX</title>
12026 <productname>Kernel Hackers Manual</productname>
12027 <date>July 2017</date>
12028</refentryinfo>
12029<refmeta>
12030 <refentrytitle><phrase>drm_mode_create_scaling_mode_property</phrase></refentrytitle>
12031 <manvolnum>9</manvolnum>
12032 <refmiscinfo class="version">4.1.27</refmiscinfo>
12033</refmeta>
12034<refnamediv>
12035 <refname>drm_mode_create_scaling_mode_property</refname>
12036 <refpurpose>
12037     create scaling mode property
12038 </refpurpose>
12039</refnamediv>
12040<refsynopsisdiv>
12041 <title>Synopsis</title>
12042  <funcsynopsis><funcprototype>
12043   <funcdef>int <function>drm_mode_create_scaling_mode_property </function></funcdef>
12044   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12045  </funcprototype></funcsynopsis>
12046</refsynopsisdiv>
12047<refsect1>
12048 <title>Arguments</title>
12049 <variablelist>
12050  <varlistentry>
12051   <term><parameter>dev</parameter></term>
12052   <listitem>
12053    <para>
12054     DRM device
12055    </para>
12056   </listitem>
12057  </varlistentry>
12058 </variablelist>
12059</refsect1>
12060<refsect1>
12061<title>Description</title>
12062<para>
12063   Called by a driver the first time it's needed, must be attached to desired
12064   connectors.
12065</para>
12066</refsect1>
12067</refentry>
12068
12069<refentry id="API-drm-mode-create-aspect-ratio-property">
12070<refentryinfo>
12071 <title>LINUX</title>
12072 <productname>Kernel Hackers Manual</productname>
12073 <date>July 2017</date>
12074</refentryinfo>
12075<refmeta>
12076 <refentrytitle><phrase>drm_mode_create_aspect_ratio_property</phrase></refentrytitle>
12077 <manvolnum>9</manvolnum>
12078 <refmiscinfo class="version">4.1.27</refmiscinfo>
12079</refmeta>
12080<refnamediv>
12081 <refname>drm_mode_create_aspect_ratio_property</refname>
12082 <refpurpose>
12083     create aspect ratio property
12084 </refpurpose>
12085</refnamediv>
12086<refsynopsisdiv>
12087 <title>Synopsis</title>
12088  <funcsynopsis><funcprototype>
12089   <funcdef>int <function>drm_mode_create_aspect_ratio_property </function></funcdef>
12090   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12091  </funcprototype></funcsynopsis>
12092</refsynopsisdiv>
12093<refsect1>
12094 <title>Arguments</title>
12095 <variablelist>
12096  <varlistentry>
12097   <term><parameter>dev</parameter></term>
12098   <listitem>
12099    <para>
12100     DRM device
12101    </para>
12102   </listitem>
12103  </varlistentry>
12104 </variablelist>
12105</refsect1>
12106<refsect1>
12107<title>Description</title>
12108<para>
12109   Called by a driver the first time it's needed, must be attached to desired
12110   connectors.
12111</para>
12112</refsect1>
12113<refsect1>
12114<title>Returns</title>
12115<para>
12116   Zero on success, negative errno on failure.
12117</para>
12118</refsect1>
12119</refentry>
12120
12121<refentry id="API-drm-mode-create-dirty-info-property">
12122<refentryinfo>
12123 <title>LINUX</title>
12124 <productname>Kernel Hackers Manual</productname>
12125 <date>July 2017</date>
12126</refentryinfo>
12127<refmeta>
12128 <refentrytitle><phrase>drm_mode_create_dirty_info_property</phrase></refentrytitle>
12129 <manvolnum>9</manvolnum>
12130 <refmiscinfo class="version">4.1.27</refmiscinfo>
12131</refmeta>
12132<refnamediv>
12133 <refname>drm_mode_create_dirty_info_property</refname>
12134 <refpurpose>
12135     create dirty property
12136 </refpurpose>
12137</refnamediv>
12138<refsynopsisdiv>
12139 <title>Synopsis</title>
12140  <funcsynopsis><funcprototype>
12141   <funcdef>int <function>drm_mode_create_dirty_info_property </function></funcdef>
12142   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12143  </funcprototype></funcsynopsis>
12144</refsynopsisdiv>
12145<refsect1>
12146 <title>Arguments</title>
12147 <variablelist>
12148  <varlistentry>
12149   <term><parameter>dev</parameter></term>
12150   <listitem>
12151    <para>
12152     DRM device
12153    </para>
12154   </listitem>
12155  </varlistentry>
12156 </variablelist>
12157</refsect1>
12158<refsect1>
12159<title>Description</title>
12160<para>
12161   Called by a driver the first time it's needed, must be attached to desired
12162   connectors.
12163</para>
12164</refsect1>
12165</refentry>
12166
12167<refentry id="API-drm-mode-create-suggested-offset-properties">
12168<refentryinfo>
12169 <title>LINUX</title>
12170 <productname>Kernel Hackers Manual</productname>
12171 <date>July 2017</date>
12172</refentryinfo>
12173<refmeta>
12174 <refentrytitle><phrase>drm_mode_create_suggested_offset_properties</phrase></refentrytitle>
12175 <manvolnum>9</manvolnum>
12176 <refmiscinfo class="version">4.1.27</refmiscinfo>
12177</refmeta>
12178<refnamediv>
12179 <refname>drm_mode_create_suggested_offset_properties</refname>
12180 <refpurpose>
12181     create suggests offset properties
12182 </refpurpose>
12183</refnamediv>
12184<refsynopsisdiv>
12185 <title>Synopsis</title>
12186  <funcsynopsis><funcprototype>
12187   <funcdef>int <function>drm_mode_create_suggested_offset_properties </function></funcdef>
12188   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12189  </funcprototype></funcsynopsis>
12190</refsynopsisdiv>
12191<refsect1>
12192 <title>Arguments</title>
12193 <variablelist>
12194  <varlistentry>
12195   <term><parameter>dev</parameter></term>
12196   <listitem>
12197    <para>
12198     DRM device
12199    </para>
12200   </listitem>
12201  </varlistentry>
12202 </variablelist>
12203</refsect1>
12204<refsect1>
12205<title>Description</title>
12206<para>
12207   Create the the suggested x/y offset property for connectors.
12208</para>
12209</refsect1>
12210</refentry>
12211
12212<refentry id="API-drm-mode-set-config-internal">
12213<refentryinfo>
12214 <title>LINUX</title>
12215 <productname>Kernel Hackers Manual</productname>
12216 <date>July 2017</date>
12217</refentryinfo>
12218<refmeta>
12219 <refentrytitle><phrase>drm_mode_set_config_internal</phrase></refentrytitle>
12220 <manvolnum>9</manvolnum>
12221 <refmiscinfo class="version">4.1.27</refmiscinfo>
12222</refmeta>
12223<refnamediv>
12224 <refname>drm_mode_set_config_internal</refname>
12225 <refpurpose>
12226     helper to call -&gt;set_config
12227 </refpurpose>
12228</refnamediv>
12229<refsynopsisdiv>
12230 <title>Synopsis</title>
12231  <funcsynopsis><funcprototype>
12232   <funcdef>int <function>drm_mode_set_config_internal </function></funcdef>
12233   <paramdef>struct drm_mode_set * <parameter>set</parameter></paramdef>
12234  </funcprototype></funcsynopsis>
12235</refsynopsisdiv>
12236<refsect1>
12237 <title>Arguments</title>
12238 <variablelist>
12239  <varlistentry>
12240   <term><parameter>set</parameter></term>
12241   <listitem>
12242    <para>
12243     modeset config to set
12244    </para>
12245   </listitem>
12246  </varlistentry>
12247 </variablelist>
12248</refsect1>
12249<refsect1>
12250<title>Description</title>
12251<para>
12252   This is a little helper to wrap internal calls to the -&gt;set_config driver
12253   interface. The only thing it adds is correct refcounting dance.
12254</para>
12255</refsect1>
12256<refsect1>
12257<title>Returns</title>
12258<para>
12259   Zero on success, negative errno on failure.
12260</para>
12261</refsect1>
12262</refentry>
12263
12264<refentry id="API-drm-crtc-get-hv-timing">
12265<refentryinfo>
12266 <title>LINUX</title>
12267 <productname>Kernel Hackers Manual</productname>
12268 <date>July 2017</date>
12269</refentryinfo>
12270<refmeta>
12271 <refentrytitle><phrase>drm_crtc_get_hv_timing</phrase></refentrytitle>
12272 <manvolnum>9</manvolnum>
12273 <refmiscinfo class="version">4.1.27</refmiscinfo>
12274</refmeta>
12275<refnamediv>
12276 <refname>drm_crtc_get_hv_timing</refname>
12277 <refpurpose>
12278     Fetches hdisplay/vdisplay for given mode
12279 </refpurpose>
12280</refnamediv>
12281<refsynopsisdiv>
12282 <title>Synopsis</title>
12283  <funcsynopsis><funcprototype>
12284   <funcdef>void <function>drm_crtc_get_hv_timing </function></funcdef>
12285   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
12286   <paramdef>int * <parameter>hdisplay</parameter></paramdef>
12287   <paramdef>int * <parameter>vdisplay</parameter></paramdef>
12288  </funcprototype></funcsynopsis>
12289</refsynopsisdiv>
12290<refsect1>
12291 <title>Arguments</title>
12292 <variablelist>
12293  <varlistentry>
12294   <term><parameter>mode</parameter></term>
12295   <listitem>
12296    <para>
12297     mode to query
12298    </para>
12299   </listitem>
12300  </varlistentry>
12301  <varlistentry>
12302   <term><parameter>hdisplay</parameter></term>
12303   <listitem>
12304    <para>
12305     hdisplay value to fill in
12306    </para>
12307   </listitem>
12308  </varlistentry>
12309  <varlistentry>
12310   <term><parameter>vdisplay</parameter></term>
12311   <listitem>
12312    <para>
12313     vdisplay value to fill in
12314    </para>
12315   </listitem>
12316  </varlistentry>
12317 </variablelist>
12318</refsect1>
12319<refsect1>
12320<title>Description</title>
12321<para>
12322   The vdisplay value will be doubled if the specified mode is a stereo mode of
12323   the appropriate layout.
12324</para>
12325</refsect1>
12326</refentry>
12327
12328<refentry id="API-drm-crtc-check-viewport">
12329<refentryinfo>
12330 <title>LINUX</title>
12331 <productname>Kernel Hackers Manual</productname>
12332 <date>July 2017</date>
12333</refentryinfo>
12334<refmeta>
12335 <refentrytitle><phrase>drm_crtc_check_viewport</phrase></refentrytitle>
12336 <manvolnum>9</manvolnum>
12337 <refmiscinfo class="version">4.1.27</refmiscinfo>
12338</refmeta>
12339<refnamediv>
12340 <refname>drm_crtc_check_viewport</refname>
12341 <refpurpose>
12342     Checks that a framebuffer is big enough for the CRTC viewport
12343 </refpurpose>
12344</refnamediv>
12345<refsynopsisdiv>
12346 <title>Synopsis</title>
12347  <funcsynopsis><funcprototype>
12348   <funcdef>int <function>drm_crtc_check_viewport </function></funcdef>
12349   <paramdef>const struct drm_crtc * <parameter>crtc</parameter></paramdef>
12350   <paramdef>int <parameter>x</parameter></paramdef>
12351   <paramdef>int <parameter>y</parameter></paramdef>
12352   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
12353   <paramdef>const struct drm_framebuffer * <parameter>fb</parameter></paramdef>
12354  </funcprototype></funcsynopsis>
12355</refsynopsisdiv>
12356<refsect1>
12357 <title>Arguments</title>
12358 <variablelist>
12359  <varlistentry>
12360   <term><parameter>crtc</parameter></term>
12361   <listitem>
12362    <para>
12363     CRTC that framebuffer will be displayed on
12364    </para>
12365   </listitem>
12366  </varlistentry>
12367  <varlistentry>
12368   <term><parameter>x</parameter></term>
12369   <listitem>
12370    <para>
12371     x panning
12372    </para>
12373   </listitem>
12374  </varlistentry>
12375  <varlistentry>
12376   <term><parameter>y</parameter></term>
12377   <listitem>
12378    <para>
12379     y panning
12380    </para>
12381   </listitem>
12382  </varlistentry>
12383  <varlistentry>
12384   <term><parameter>mode</parameter></term>
12385   <listitem>
12386    <para>
12387     mode that framebuffer will be displayed under
12388    </para>
12389   </listitem>
12390  </varlistentry>
12391  <varlistentry>
12392   <term><parameter>fb</parameter></term>
12393   <listitem>
12394    <para>
12395     framebuffer to check size of
12396    </para>
12397   </listitem>
12398  </varlistentry>
12399 </variablelist>
12400</refsect1>
12401</refentry>
12402
12403<refentry id="API-drm-mode-legacy-fb-format">
12404<refentryinfo>
12405 <title>LINUX</title>
12406 <productname>Kernel Hackers Manual</productname>
12407 <date>July 2017</date>
12408</refentryinfo>
12409<refmeta>
12410 <refentrytitle><phrase>drm_mode_legacy_fb_format</phrase></refentrytitle>
12411 <manvolnum>9</manvolnum>
12412 <refmiscinfo class="version">4.1.27</refmiscinfo>
12413</refmeta>
12414<refnamediv>
12415 <refname>drm_mode_legacy_fb_format</refname>
12416 <refpurpose>
12417     compute drm fourcc code from legacy description
12418 </refpurpose>
12419</refnamediv>
12420<refsynopsisdiv>
12421 <title>Synopsis</title>
12422  <funcsynopsis><funcprototype>
12423   <funcdef>uint32_t <function>drm_mode_legacy_fb_format </function></funcdef>
12424   <paramdef>uint32_t <parameter>bpp</parameter></paramdef>
12425   <paramdef>uint32_t <parameter>depth</parameter></paramdef>
12426  </funcprototype></funcsynopsis>
12427</refsynopsisdiv>
12428<refsect1>
12429 <title>Arguments</title>
12430 <variablelist>
12431  <varlistentry>
12432   <term><parameter>bpp</parameter></term>
12433   <listitem>
12434    <para>
12435     bits per pixels
12436    </para>
12437   </listitem>
12438  </varlistentry>
12439  <varlistentry>
12440   <term><parameter>depth</parameter></term>
12441   <listitem>
12442    <para>
12443     bit depth per pixel
12444    </para>
12445   </listitem>
12446  </varlistentry>
12447 </variablelist>
12448</refsect1>
12449<refsect1>
12450<title>Description</title>
12451<para>
12452   Computes a drm fourcc pixel format code for the given <parameter>bpp</parameter>/<parameter>depth</parameter> values.
12453   Useful in fbdev emulation code, since that deals in those values.
12454</para>
12455</refsect1>
12456</refentry>
12457
12458<refentry id="API-drm-property-create">
12459<refentryinfo>
12460 <title>LINUX</title>
12461 <productname>Kernel Hackers Manual</productname>
12462 <date>July 2017</date>
12463</refentryinfo>
12464<refmeta>
12465 <refentrytitle><phrase>drm_property_create</phrase></refentrytitle>
12466 <manvolnum>9</manvolnum>
12467 <refmiscinfo class="version">4.1.27</refmiscinfo>
12468</refmeta>
12469<refnamediv>
12470 <refname>drm_property_create</refname>
12471 <refpurpose>
12472     create a new property type
12473 </refpurpose>
12474</refnamediv>
12475<refsynopsisdiv>
12476 <title>Synopsis</title>
12477  <funcsynopsis><funcprototype>
12478   <funcdef>struct drm_property * <function>drm_property_create </function></funcdef>
12479   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12480   <paramdef>int <parameter>flags</parameter></paramdef>
12481   <paramdef>const char * <parameter>name</parameter></paramdef>
12482   <paramdef>int <parameter>num_values</parameter></paramdef>
12483  </funcprototype></funcsynopsis>
12484</refsynopsisdiv>
12485<refsect1>
12486 <title>Arguments</title>
12487 <variablelist>
12488  <varlistentry>
12489   <term><parameter>dev</parameter></term>
12490   <listitem>
12491    <para>
12492     drm device
12493    </para>
12494   </listitem>
12495  </varlistentry>
12496  <varlistentry>
12497   <term><parameter>flags</parameter></term>
12498   <listitem>
12499    <para>
12500     flags specifying the property type
12501    </para>
12502   </listitem>
12503  </varlistentry>
12504  <varlistentry>
12505   <term><parameter>name</parameter></term>
12506   <listitem>
12507    <para>
12508     name of the property
12509    </para>
12510   </listitem>
12511  </varlistentry>
12512  <varlistentry>
12513   <term><parameter>num_values</parameter></term>
12514   <listitem>
12515    <para>
12516     number of pre-defined values
12517    </para>
12518   </listitem>
12519  </varlistentry>
12520 </variablelist>
12521</refsect1>
12522<refsect1>
12523<title>Description</title>
12524<para>
12525   This creates a new generic drm property which can then be attached to a drm
12526   object with drm_object_attach_property. The returned property object must be
12527   freed with drm_property_destroy.
12528   </para><para>
12529
12530   Note that the DRM core keeps a per-device list of properties and that, if
12531   <function>drm_mode_config_cleanup</function> is called, it will destroy all properties created
12532   by the driver.
12533</para>
12534</refsect1>
12535<refsect1>
12536<title>Returns</title>
12537<para>
12538   A pointer to the newly created property on success, NULL on failure.
12539</para>
12540</refsect1>
12541</refentry>
12542
12543<refentry id="API-drm-property-create-enum">
12544<refentryinfo>
12545 <title>LINUX</title>
12546 <productname>Kernel Hackers Manual</productname>
12547 <date>July 2017</date>
12548</refentryinfo>
12549<refmeta>
12550 <refentrytitle><phrase>drm_property_create_enum</phrase></refentrytitle>
12551 <manvolnum>9</manvolnum>
12552 <refmiscinfo class="version">4.1.27</refmiscinfo>
12553</refmeta>
12554<refnamediv>
12555 <refname>drm_property_create_enum</refname>
12556 <refpurpose>
12557     create a new enumeration property type
12558 </refpurpose>
12559</refnamediv>
12560<refsynopsisdiv>
12561 <title>Synopsis</title>
12562  <funcsynopsis><funcprototype>
12563   <funcdef>struct drm_property * <function>drm_property_create_enum </function></funcdef>
12564   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12565   <paramdef>int <parameter>flags</parameter></paramdef>
12566   <paramdef>const char * <parameter>name</parameter></paramdef>
12567   <paramdef>const struct drm_prop_enum_list * <parameter>props</parameter></paramdef>
12568   <paramdef>int <parameter>num_values</parameter></paramdef>
12569  </funcprototype></funcsynopsis>
12570</refsynopsisdiv>
12571<refsect1>
12572 <title>Arguments</title>
12573 <variablelist>
12574  <varlistentry>
12575   <term><parameter>dev</parameter></term>
12576   <listitem>
12577    <para>
12578     drm device
12579    </para>
12580   </listitem>
12581  </varlistentry>
12582  <varlistentry>
12583   <term><parameter>flags</parameter></term>
12584   <listitem>
12585    <para>
12586     flags specifying the property type
12587    </para>
12588   </listitem>
12589  </varlistentry>
12590  <varlistentry>
12591   <term><parameter>name</parameter></term>
12592   <listitem>
12593    <para>
12594     name of the property
12595    </para>
12596   </listitem>
12597  </varlistentry>
12598  <varlistentry>
12599   <term><parameter>props</parameter></term>
12600   <listitem>
12601    <para>
12602     enumeration lists with property values
12603    </para>
12604   </listitem>
12605  </varlistentry>
12606  <varlistentry>
12607   <term><parameter>num_values</parameter></term>
12608   <listitem>
12609    <para>
12610     number of pre-defined values
12611    </para>
12612   </listitem>
12613  </varlistentry>
12614 </variablelist>
12615</refsect1>
12616<refsect1>
12617<title>Description</title>
12618<para>
12619   This creates a new generic drm property which can then be attached to a drm
12620   object with drm_object_attach_property. The returned property object must be
12621   freed with drm_property_destroy.
12622   </para><para>
12623
12624   Userspace is only allowed to set one of the predefined values for enumeration
12625   properties.
12626</para>
12627</refsect1>
12628<refsect1>
12629<title>Returns</title>
12630<para>
12631   A pointer to the newly created property on success, NULL on failure.
12632</para>
12633</refsect1>
12634</refentry>
12635
12636<refentry id="API-drm-property-create-bitmask">
12637<refentryinfo>
12638 <title>LINUX</title>
12639 <productname>Kernel Hackers Manual</productname>
12640 <date>July 2017</date>
12641</refentryinfo>
12642<refmeta>
12643 <refentrytitle><phrase>drm_property_create_bitmask</phrase></refentrytitle>
12644 <manvolnum>9</manvolnum>
12645 <refmiscinfo class="version">4.1.27</refmiscinfo>
12646</refmeta>
12647<refnamediv>
12648 <refname>drm_property_create_bitmask</refname>
12649 <refpurpose>
12650     create a new bitmask property type
12651 </refpurpose>
12652</refnamediv>
12653<refsynopsisdiv>
12654 <title>Synopsis</title>
12655  <funcsynopsis><funcprototype>
12656   <funcdef>struct drm_property * <function>drm_property_create_bitmask </function></funcdef>
12657   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12658   <paramdef>int <parameter>flags</parameter></paramdef>
12659   <paramdef>const char * <parameter>name</parameter></paramdef>
12660   <paramdef>const struct drm_prop_enum_list * <parameter>props</parameter></paramdef>
12661   <paramdef>int <parameter>num_props</parameter></paramdef>
12662   <paramdef>uint64_t <parameter>supported_bits</parameter></paramdef>
12663  </funcprototype></funcsynopsis>
12664</refsynopsisdiv>
12665<refsect1>
12666 <title>Arguments</title>
12667 <variablelist>
12668  <varlistentry>
12669   <term><parameter>dev</parameter></term>
12670   <listitem>
12671    <para>
12672     drm device
12673    </para>
12674   </listitem>
12675  </varlistentry>
12676  <varlistentry>
12677   <term><parameter>flags</parameter></term>
12678   <listitem>
12679    <para>
12680     flags specifying the property type
12681    </para>
12682   </listitem>
12683  </varlistentry>
12684  <varlistentry>
12685   <term><parameter>name</parameter></term>
12686   <listitem>
12687    <para>
12688     name of the property
12689    </para>
12690   </listitem>
12691  </varlistentry>
12692  <varlistentry>
12693   <term><parameter>props</parameter></term>
12694   <listitem>
12695    <para>
12696     enumeration lists with property bitflags
12697    </para>
12698   </listitem>
12699  </varlistentry>
12700  <varlistentry>
12701   <term><parameter>num_props</parameter></term>
12702   <listitem>
12703    <para>
12704     size of the <parameter>props</parameter> array
12705    </para>
12706   </listitem>
12707  </varlistentry>
12708  <varlistentry>
12709   <term><parameter>supported_bits</parameter></term>
12710   <listitem>
12711    <para>
12712     bitmask of all supported enumeration values
12713    </para>
12714   </listitem>
12715  </varlistentry>
12716 </variablelist>
12717</refsect1>
12718<refsect1>
12719<title>Description</title>
12720<para>
12721   This creates a new bitmask drm property which can then be attached to a drm
12722   object with drm_object_attach_property. The returned property object must be
12723   freed with drm_property_destroy.
12724   </para><para>
12725
12726   Compared to plain enumeration properties userspace is allowed to set any
12727   or'ed together combination of the predefined property bitflag values
12728</para>
12729</refsect1>
12730<refsect1>
12731<title>Returns</title>
12732<para>
12733   A pointer to the newly created property on success, NULL on failure.
12734</para>
12735</refsect1>
12736</refentry>
12737
12738<refentry id="API-drm-property-create-range">
12739<refentryinfo>
12740 <title>LINUX</title>
12741 <productname>Kernel Hackers Manual</productname>
12742 <date>July 2017</date>
12743</refentryinfo>
12744<refmeta>
12745 <refentrytitle><phrase>drm_property_create_range</phrase></refentrytitle>
12746 <manvolnum>9</manvolnum>
12747 <refmiscinfo class="version">4.1.27</refmiscinfo>
12748</refmeta>
12749<refnamediv>
12750 <refname>drm_property_create_range</refname>
12751 <refpurpose>
12752     create a new unsigned ranged property type
12753 </refpurpose>
12754</refnamediv>
12755<refsynopsisdiv>
12756 <title>Synopsis</title>
12757  <funcsynopsis><funcprototype>
12758   <funcdef>struct drm_property * <function>drm_property_create_range </function></funcdef>
12759   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12760   <paramdef>int <parameter>flags</parameter></paramdef>
12761   <paramdef>const char * <parameter>name</parameter></paramdef>
12762   <paramdef>uint64_t <parameter>min</parameter></paramdef>
12763   <paramdef>uint64_t <parameter>max</parameter></paramdef>
12764  </funcprototype></funcsynopsis>
12765</refsynopsisdiv>
12766<refsect1>
12767 <title>Arguments</title>
12768 <variablelist>
12769  <varlistentry>
12770   <term><parameter>dev</parameter></term>
12771   <listitem>
12772    <para>
12773     drm device
12774    </para>
12775   </listitem>
12776  </varlistentry>
12777  <varlistentry>
12778   <term><parameter>flags</parameter></term>
12779   <listitem>
12780    <para>
12781     flags specifying the property type
12782    </para>
12783   </listitem>
12784  </varlistentry>
12785  <varlistentry>
12786   <term><parameter>name</parameter></term>
12787   <listitem>
12788    <para>
12789     name of the property
12790    </para>
12791   </listitem>
12792  </varlistentry>
12793  <varlistentry>
12794   <term><parameter>min</parameter></term>
12795   <listitem>
12796    <para>
12797     minimum value of the property
12798    </para>
12799   </listitem>
12800  </varlistentry>
12801  <varlistentry>
12802   <term><parameter>max</parameter></term>
12803   <listitem>
12804    <para>
12805     maximum value of the property
12806    </para>
12807   </listitem>
12808  </varlistentry>
12809 </variablelist>
12810</refsect1>
12811<refsect1>
12812<title>Description</title>
12813<para>
12814   This creates a new generic drm property which can then be attached to a drm
12815   object with drm_object_attach_property. The returned property object must be
12816   freed with drm_property_destroy.
12817   </para><para>
12818
12819   Userspace is allowed to set any unsigned integer value in the (min, max)
12820   range inclusive.
12821</para>
12822</refsect1>
12823<refsect1>
12824<title>Returns</title>
12825<para>
12826   A pointer to the newly created property on success, NULL on failure.
12827</para>
12828</refsect1>
12829</refentry>
12830
12831<refentry id="API-drm-property-create-signed-range">
12832<refentryinfo>
12833 <title>LINUX</title>
12834 <productname>Kernel Hackers Manual</productname>
12835 <date>July 2017</date>
12836</refentryinfo>
12837<refmeta>
12838 <refentrytitle><phrase>drm_property_create_signed_range</phrase></refentrytitle>
12839 <manvolnum>9</manvolnum>
12840 <refmiscinfo class="version">4.1.27</refmiscinfo>
12841</refmeta>
12842<refnamediv>
12843 <refname>drm_property_create_signed_range</refname>
12844 <refpurpose>
12845     create a new signed ranged property type
12846 </refpurpose>
12847</refnamediv>
12848<refsynopsisdiv>
12849 <title>Synopsis</title>
12850  <funcsynopsis><funcprototype>
12851   <funcdef>struct drm_property * <function>drm_property_create_signed_range </function></funcdef>
12852   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12853   <paramdef>int <parameter>flags</parameter></paramdef>
12854   <paramdef>const char * <parameter>name</parameter></paramdef>
12855   <paramdef>int64_t <parameter>min</parameter></paramdef>
12856   <paramdef>int64_t <parameter>max</parameter></paramdef>
12857  </funcprototype></funcsynopsis>
12858</refsynopsisdiv>
12859<refsect1>
12860 <title>Arguments</title>
12861 <variablelist>
12862  <varlistentry>
12863   <term><parameter>dev</parameter></term>
12864   <listitem>
12865    <para>
12866     drm device
12867    </para>
12868   </listitem>
12869  </varlistentry>
12870  <varlistentry>
12871   <term><parameter>flags</parameter></term>
12872   <listitem>
12873    <para>
12874     flags specifying the property type
12875    </para>
12876   </listitem>
12877  </varlistentry>
12878  <varlistentry>
12879   <term><parameter>name</parameter></term>
12880   <listitem>
12881    <para>
12882     name of the property
12883    </para>
12884   </listitem>
12885  </varlistentry>
12886  <varlistentry>
12887   <term><parameter>min</parameter></term>
12888   <listitem>
12889    <para>
12890     minimum value of the property
12891    </para>
12892   </listitem>
12893  </varlistentry>
12894  <varlistentry>
12895   <term><parameter>max</parameter></term>
12896   <listitem>
12897    <para>
12898     maximum value of the property
12899    </para>
12900   </listitem>
12901  </varlistentry>
12902 </variablelist>
12903</refsect1>
12904<refsect1>
12905<title>Description</title>
12906<para>
12907   This creates a new generic drm property which can then be attached to a drm
12908   object with drm_object_attach_property. The returned property object must be
12909   freed with drm_property_destroy.
12910   </para><para>
12911
12912   Userspace is allowed to set any signed integer value in the (min, max)
12913   range inclusive.
12914</para>
12915</refsect1>
12916<refsect1>
12917<title>Returns</title>
12918<para>
12919   A pointer to the newly created property on success, NULL on failure.
12920</para>
12921</refsect1>
12922</refentry>
12923
12924<refentry id="API-drm-property-create-object">
12925<refentryinfo>
12926 <title>LINUX</title>
12927 <productname>Kernel Hackers Manual</productname>
12928 <date>July 2017</date>
12929</refentryinfo>
12930<refmeta>
12931 <refentrytitle><phrase>drm_property_create_object</phrase></refentrytitle>
12932 <manvolnum>9</manvolnum>
12933 <refmiscinfo class="version">4.1.27</refmiscinfo>
12934</refmeta>
12935<refnamediv>
12936 <refname>drm_property_create_object</refname>
12937 <refpurpose>
12938     create a new object property type
12939 </refpurpose>
12940</refnamediv>
12941<refsynopsisdiv>
12942 <title>Synopsis</title>
12943  <funcsynopsis><funcprototype>
12944   <funcdef>struct drm_property * <function>drm_property_create_object </function></funcdef>
12945   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
12946   <paramdef>int <parameter>flags</parameter></paramdef>
12947   <paramdef>const char * <parameter>name</parameter></paramdef>
12948   <paramdef>uint32_t <parameter>type</parameter></paramdef>
12949  </funcprototype></funcsynopsis>
12950</refsynopsisdiv>
12951<refsect1>
12952 <title>Arguments</title>
12953 <variablelist>
12954  <varlistentry>
12955   <term><parameter>dev</parameter></term>
12956   <listitem>
12957    <para>
12958     drm device
12959    </para>
12960   </listitem>
12961  </varlistentry>
12962  <varlistentry>
12963   <term><parameter>flags</parameter></term>
12964   <listitem>
12965    <para>
12966     flags specifying the property type
12967    </para>
12968   </listitem>
12969  </varlistentry>
12970  <varlistentry>
12971   <term><parameter>name</parameter></term>
12972   <listitem>
12973    <para>
12974     name of the property
12975    </para>
12976   </listitem>
12977  </varlistentry>
12978  <varlistentry>
12979   <term><parameter>type</parameter></term>
12980   <listitem>
12981    <para>
12982     object type from DRM_MODE_OBJECT_* defines
12983    </para>
12984   </listitem>
12985  </varlistentry>
12986 </variablelist>
12987</refsect1>
12988<refsect1>
12989<title>Description</title>
12990<para>
12991   This creates a new generic drm property which can then be attached to a drm
12992   object with drm_object_attach_property. The returned property object must be
12993   freed with drm_property_destroy.
12994   </para><para>
12995
12996   Userspace is only allowed to set this to any property value of the given
12997   <parameter>type</parameter>. Only useful for atomic properties, which is enforced.
12998</para>
12999</refsect1>
13000<refsect1>
13001<title>Returns</title>
13002<para>
13003   A pointer to the newly created property on success, NULL on failure.
13004</para>
13005</refsect1>
13006</refentry>
13007
13008<refentry id="API-drm-property-create-bool">
13009<refentryinfo>
13010 <title>LINUX</title>
13011 <productname>Kernel Hackers Manual</productname>
13012 <date>July 2017</date>
13013</refentryinfo>
13014<refmeta>
13015 <refentrytitle><phrase>drm_property_create_bool</phrase></refentrytitle>
13016 <manvolnum>9</manvolnum>
13017 <refmiscinfo class="version">4.1.27</refmiscinfo>
13018</refmeta>
13019<refnamediv>
13020 <refname>drm_property_create_bool</refname>
13021 <refpurpose>
13022     create a new boolean property type
13023 </refpurpose>
13024</refnamediv>
13025<refsynopsisdiv>
13026 <title>Synopsis</title>
13027  <funcsynopsis><funcprototype>
13028   <funcdef>struct drm_property * <function>drm_property_create_bool </function></funcdef>
13029   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
13030   <paramdef>int <parameter>flags</parameter></paramdef>
13031   <paramdef>const char * <parameter>name</parameter></paramdef>
13032  </funcprototype></funcsynopsis>
13033</refsynopsisdiv>
13034<refsect1>
13035 <title>Arguments</title>
13036 <variablelist>
13037  <varlistentry>
13038   <term><parameter>dev</parameter></term>
13039   <listitem>
13040    <para>
13041     drm device
13042    </para>
13043   </listitem>
13044  </varlistentry>
13045  <varlistentry>
13046   <term><parameter>flags</parameter></term>
13047   <listitem>
13048    <para>
13049     flags specifying the property type
13050    </para>
13051   </listitem>
13052  </varlistentry>
13053  <varlistentry>
13054   <term><parameter>name</parameter></term>
13055   <listitem>
13056    <para>
13057     name of the property
13058    </para>
13059   </listitem>
13060  </varlistentry>
13061 </variablelist>
13062</refsect1>
13063<refsect1>
13064<title>Description</title>
13065<para>
13066   This creates a new generic drm property which can then be attached to a drm
13067   object with drm_object_attach_property. The returned property object must be
13068   freed with drm_property_destroy.
13069   </para><para>
13070
13071   This is implemented as a ranged property with only {0, 1} as valid values.
13072</para>
13073</refsect1>
13074<refsect1>
13075<title>Returns</title>
13076<para>
13077   A pointer to the newly created property on success, NULL on failure.
13078</para>
13079</refsect1>
13080</refentry>
13081
13082<refentry id="API-drm-property-add-enum">
13083<refentryinfo>
13084 <title>LINUX</title>
13085 <productname>Kernel Hackers Manual</productname>
13086 <date>July 2017</date>
13087</refentryinfo>
13088<refmeta>
13089 <refentrytitle><phrase>drm_property_add_enum</phrase></refentrytitle>
13090 <manvolnum>9</manvolnum>
13091 <refmiscinfo class="version">4.1.27</refmiscinfo>
13092</refmeta>
13093<refnamediv>
13094 <refname>drm_property_add_enum</refname>
13095 <refpurpose>
13096     add a possible value to an enumeration property
13097 </refpurpose>
13098</refnamediv>
13099<refsynopsisdiv>
13100 <title>Synopsis</title>
13101  <funcsynopsis><funcprototype>
13102   <funcdef>int <function>drm_property_add_enum </function></funcdef>
13103   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
13104   <paramdef>int <parameter>index</parameter></paramdef>
13105   <paramdef>uint64_t <parameter>value</parameter></paramdef>
13106   <paramdef>const char * <parameter>name</parameter></paramdef>
13107  </funcprototype></funcsynopsis>
13108</refsynopsisdiv>
13109<refsect1>
13110 <title>Arguments</title>
13111 <variablelist>
13112  <varlistentry>
13113   <term><parameter>property</parameter></term>
13114   <listitem>
13115    <para>
13116     enumeration property to change
13117    </para>
13118   </listitem>
13119  </varlistentry>
13120  <varlistentry>
13121   <term><parameter>index</parameter></term>
13122   <listitem>
13123    <para>
13124     index of the new enumeration
13125    </para>
13126   </listitem>
13127  </varlistentry>
13128  <varlistentry>
13129   <term><parameter>value</parameter></term>
13130   <listitem>
13131    <para>
13132     value of the new enumeration
13133    </para>
13134   </listitem>
13135  </varlistentry>
13136  <varlistentry>
13137   <term><parameter>name</parameter></term>
13138   <listitem>
13139    <para>
13140     symbolic name of the new enumeration
13141    </para>
13142   </listitem>
13143  </varlistentry>
13144 </variablelist>
13145</refsect1>
13146<refsect1>
13147<title>Description</title>
13148<para>
13149   This functions adds enumerations to a property.
13150   </para><para>
13151
13152   It's use is deprecated, drivers should use one of the more specific helpers
13153   to directly create the property with all enumerations already attached.
13154</para>
13155</refsect1>
13156<refsect1>
13157<title>Returns</title>
13158<para>
13159   Zero on success, error code on failure.
13160</para>
13161</refsect1>
13162</refentry>
13163
13164<refentry id="API-drm-property-destroy">
13165<refentryinfo>
13166 <title>LINUX</title>
13167 <productname>Kernel Hackers Manual</productname>
13168 <date>July 2017</date>
13169</refentryinfo>
13170<refmeta>
13171 <refentrytitle><phrase>drm_property_destroy</phrase></refentrytitle>
13172 <manvolnum>9</manvolnum>
13173 <refmiscinfo class="version">4.1.27</refmiscinfo>
13174</refmeta>
13175<refnamediv>
13176 <refname>drm_property_destroy</refname>
13177 <refpurpose>
13178     destroy a drm property
13179 </refpurpose>
13180</refnamediv>
13181<refsynopsisdiv>
13182 <title>Synopsis</title>
13183  <funcsynopsis><funcprototype>
13184   <funcdef>void <function>drm_property_destroy </function></funcdef>
13185   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
13186   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
13187  </funcprototype></funcsynopsis>
13188</refsynopsisdiv>
13189<refsect1>
13190 <title>Arguments</title>
13191 <variablelist>
13192  <varlistentry>
13193   <term><parameter>dev</parameter></term>
13194   <listitem>
13195    <para>
13196     drm device
13197    </para>
13198   </listitem>
13199  </varlistentry>
13200  <varlistentry>
13201   <term><parameter>property</parameter></term>
13202   <listitem>
13203    <para>
13204     property to destry
13205    </para>
13206   </listitem>
13207  </varlistentry>
13208 </variablelist>
13209</refsect1>
13210<refsect1>
13211<title>Description</title>
13212<para>
13213   This function frees a property including any attached resources like
13214   enumeration values.
13215</para>
13216</refsect1>
13217</refentry>
13218
13219<refentry id="API-drm-object-attach-property">
13220<refentryinfo>
13221 <title>LINUX</title>
13222 <productname>Kernel Hackers Manual</productname>
13223 <date>July 2017</date>
13224</refentryinfo>
13225<refmeta>
13226 <refentrytitle><phrase>drm_object_attach_property</phrase></refentrytitle>
13227 <manvolnum>9</manvolnum>
13228 <refmiscinfo class="version">4.1.27</refmiscinfo>
13229</refmeta>
13230<refnamediv>
13231 <refname>drm_object_attach_property</refname>
13232 <refpurpose>
13233     attach a property to a modeset object
13234 </refpurpose>
13235</refnamediv>
13236<refsynopsisdiv>
13237 <title>Synopsis</title>
13238  <funcsynopsis><funcprototype>
13239   <funcdef>void <function>drm_object_attach_property </function></funcdef>
13240   <paramdef>struct drm_mode_object * <parameter>obj</parameter></paramdef>
13241   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
13242   <paramdef>uint64_t <parameter>init_val</parameter></paramdef>
13243  </funcprototype></funcsynopsis>
13244</refsynopsisdiv>
13245<refsect1>
13246 <title>Arguments</title>
13247 <variablelist>
13248  <varlistentry>
13249   <term><parameter>obj</parameter></term>
13250   <listitem>
13251    <para>
13252     drm modeset object
13253    </para>
13254   </listitem>
13255  </varlistentry>
13256  <varlistentry>
13257   <term><parameter>property</parameter></term>
13258   <listitem>
13259    <para>
13260     property to attach
13261    </para>
13262   </listitem>
13263  </varlistentry>
13264  <varlistentry>
13265   <term><parameter>init_val</parameter></term>
13266   <listitem>
13267    <para>
13268     initial value of the property
13269    </para>
13270   </listitem>
13271  </varlistentry>
13272 </variablelist>
13273</refsect1>
13274<refsect1>
13275<title>Description</title>
13276<para>
13277   This attaches the given property to the modeset object with the given initial
13278   value. Currently this function cannot fail since the properties are stored in
13279   a statically sized array.
13280</para>
13281</refsect1>
13282</refentry>
13283
13284<refentry id="API-drm-object-property-set-value">
13285<refentryinfo>
13286 <title>LINUX</title>
13287 <productname>Kernel Hackers Manual</productname>
13288 <date>July 2017</date>
13289</refentryinfo>
13290<refmeta>
13291 <refentrytitle><phrase>drm_object_property_set_value</phrase></refentrytitle>
13292 <manvolnum>9</manvolnum>
13293 <refmiscinfo class="version">4.1.27</refmiscinfo>
13294</refmeta>
13295<refnamediv>
13296 <refname>drm_object_property_set_value</refname>
13297 <refpurpose>
13298     set the value of a property
13299 </refpurpose>
13300</refnamediv>
13301<refsynopsisdiv>
13302 <title>Synopsis</title>
13303  <funcsynopsis><funcprototype>
13304   <funcdef>int <function>drm_object_property_set_value </function></funcdef>
13305   <paramdef>struct drm_mode_object * <parameter>obj</parameter></paramdef>
13306   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
13307   <paramdef>uint64_t <parameter>val</parameter></paramdef>
13308  </funcprototype></funcsynopsis>
13309</refsynopsisdiv>
13310<refsect1>
13311 <title>Arguments</title>
13312 <variablelist>
13313  <varlistentry>
13314   <term><parameter>obj</parameter></term>
13315   <listitem>
13316    <para>
13317     drm mode object to set property value for
13318    </para>
13319   </listitem>
13320  </varlistentry>
13321  <varlistentry>
13322   <term><parameter>property</parameter></term>
13323   <listitem>
13324    <para>
13325     property to set
13326    </para>
13327   </listitem>
13328  </varlistentry>
13329  <varlistentry>
13330   <term><parameter>val</parameter></term>
13331   <listitem>
13332    <para>
13333     value the property should be set to
13334    </para>
13335   </listitem>
13336  </varlistentry>
13337 </variablelist>
13338</refsect1>
13339<refsect1>
13340<title>Description</title>
13341<para>
13342   This functions sets a given property on a given object. This function only
13343   changes the software state of the property, it does not call into the
13344   driver's -&gt;set_property callback.
13345</para>
13346</refsect1>
13347<refsect1>
13348<title>Returns</title>
13349<para>
13350   Zero on success, error code on failure.
13351</para>
13352</refsect1>
13353</refentry>
13354
13355<refentry id="API-drm-object-property-get-value">
13356<refentryinfo>
13357 <title>LINUX</title>
13358 <productname>Kernel Hackers Manual</productname>
13359 <date>July 2017</date>
13360</refentryinfo>
13361<refmeta>
13362 <refentrytitle><phrase>drm_object_property_get_value</phrase></refentrytitle>
13363 <manvolnum>9</manvolnum>
13364 <refmiscinfo class="version">4.1.27</refmiscinfo>
13365</refmeta>
13366<refnamediv>
13367 <refname>drm_object_property_get_value</refname>
13368 <refpurpose>
13369     retrieve the value of a property
13370 </refpurpose>
13371</refnamediv>
13372<refsynopsisdiv>
13373 <title>Synopsis</title>
13374  <funcsynopsis><funcprototype>
13375   <funcdef>int <function>drm_object_property_get_value </function></funcdef>
13376   <paramdef>struct drm_mode_object * <parameter>obj</parameter></paramdef>
13377   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
13378   <paramdef>uint64_t * <parameter>val</parameter></paramdef>
13379  </funcprototype></funcsynopsis>
13380</refsynopsisdiv>
13381<refsect1>
13382 <title>Arguments</title>
13383 <variablelist>
13384  <varlistentry>
13385   <term><parameter>obj</parameter></term>
13386   <listitem>
13387    <para>
13388     drm mode object to get property value from
13389    </para>
13390   </listitem>
13391  </varlistentry>
13392  <varlistentry>
13393   <term><parameter>property</parameter></term>
13394   <listitem>
13395    <para>
13396     property to retrieve
13397    </para>
13398   </listitem>
13399  </varlistentry>
13400  <varlistentry>
13401   <term><parameter>val</parameter></term>
13402   <listitem>
13403    <para>
13404     storage for the property value
13405    </para>
13406   </listitem>
13407  </varlistentry>
13408 </variablelist>
13409</refsect1>
13410<refsect1>
13411<title>Description</title>
13412<para>
13413   This function retrieves the softare state of the given property for the given
13414   property. Since there is no driver callback to retrieve the current property
13415   value this might be out of sync with the hardware, depending upon the driver
13416   and property.
13417</para>
13418</refsect1>
13419<refsect1>
13420<title>Returns</title>
13421<para>
13422   Zero on success, error code on failure.
13423</para>
13424</refsect1>
13425</refentry>
13426
13427<refentry id="API-drm-mode-connector-set-path-property">
13428<refentryinfo>
13429 <title>LINUX</title>
13430 <productname>Kernel Hackers Manual</productname>
13431 <date>July 2017</date>
13432</refentryinfo>
13433<refmeta>
13434 <refentrytitle><phrase>drm_mode_connector_set_path_property</phrase></refentrytitle>
13435 <manvolnum>9</manvolnum>
13436 <refmiscinfo class="version">4.1.27</refmiscinfo>
13437</refmeta>
13438<refnamediv>
13439 <refname>drm_mode_connector_set_path_property</refname>
13440 <refpurpose>
13441     set tile property on connector
13442 </refpurpose>
13443</refnamediv>
13444<refsynopsisdiv>
13445 <title>Synopsis</title>
13446  <funcsynopsis><funcprototype>
13447   <funcdef>int <function>drm_mode_connector_set_path_property </function></funcdef>
13448   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
13449   <paramdef>const char * <parameter>path</parameter></paramdef>
13450  </funcprototype></funcsynopsis>
13451</refsynopsisdiv>
13452<refsect1>
13453 <title>Arguments</title>
13454 <variablelist>
13455  <varlistentry>
13456   <term><parameter>connector</parameter></term>
13457   <listitem>
13458    <para>
13459     connector to set property on.
13460    </para>
13461   </listitem>
13462  </varlistentry>
13463  <varlistentry>
13464   <term><parameter>path</parameter></term>
13465   <listitem>
13466    <para>
13467     path to use for property.
13468    </para>
13469   </listitem>
13470  </varlistentry>
13471 </variablelist>
13472</refsect1>
13473<refsect1>
13474<title>Description</title>
13475<para>
13476   This creates a property to expose to userspace to specify a
13477   connector path. This is mainly used for DisplayPort MST where
13478   connectors have a topology and we want to allow userspace to give
13479   them more meaningful names.
13480</para>
13481</refsect1>
13482<refsect1>
13483<title>Returns</title>
13484<para>
13485   Zero on success, negative errno on failure.
13486</para>
13487</refsect1>
13488</refentry>
13489
13490<refentry id="API-drm-mode-connector-set-tile-property">
13491<refentryinfo>
13492 <title>LINUX</title>
13493 <productname>Kernel Hackers Manual</productname>
13494 <date>July 2017</date>
13495</refentryinfo>
13496<refmeta>
13497 <refentrytitle><phrase>drm_mode_connector_set_tile_property</phrase></refentrytitle>
13498 <manvolnum>9</manvolnum>
13499 <refmiscinfo class="version">4.1.27</refmiscinfo>
13500</refmeta>
13501<refnamediv>
13502 <refname>drm_mode_connector_set_tile_property</refname>
13503 <refpurpose>
13504     set tile property on connector
13505 </refpurpose>
13506</refnamediv>
13507<refsynopsisdiv>
13508 <title>Synopsis</title>
13509  <funcsynopsis><funcprototype>
13510   <funcdef>int <function>drm_mode_connector_set_tile_property </function></funcdef>
13511   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
13512  </funcprototype></funcsynopsis>
13513</refsynopsisdiv>
13514<refsect1>
13515 <title>Arguments</title>
13516 <variablelist>
13517  <varlistentry>
13518   <term><parameter>connector</parameter></term>
13519   <listitem>
13520    <para>
13521     connector to set property on.
13522    </para>
13523   </listitem>
13524  </varlistentry>
13525 </variablelist>
13526</refsect1>
13527<refsect1>
13528<title>Description</title>
13529<para>
13530   This looks up the tile information for a connector, and creates a
13531   property for userspace to parse if it exists. The property is of
13532   the form of 8 integers using ':' as a separator.
13533</para>
13534</refsect1>
13535<refsect1>
13536<title>Returns</title>
13537<para>
13538   Zero on success, errno on failure.
13539</para>
13540</refsect1>
13541</refentry>
13542
13543<refentry id="API-drm-mode-connector-update-edid-property">
13544<refentryinfo>
13545 <title>LINUX</title>
13546 <productname>Kernel Hackers Manual</productname>
13547 <date>July 2017</date>
13548</refentryinfo>
13549<refmeta>
13550 <refentrytitle><phrase>drm_mode_connector_update_edid_property</phrase></refentrytitle>
13551 <manvolnum>9</manvolnum>
13552 <refmiscinfo class="version">4.1.27</refmiscinfo>
13553</refmeta>
13554<refnamediv>
13555 <refname>drm_mode_connector_update_edid_property</refname>
13556 <refpurpose>
13557     update the edid property of a connector
13558 </refpurpose>
13559</refnamediv>
13560<refsynopsisdiv>
13561 <title>Synopsis</title>
13562  <funcsynopsis><funcprototype>
13563   <funcdef>int <function>drm_mode_connector_update_edid_property </function></funcdef>
13564   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
13565   <paramdef>const struct edid * <parameter>edid</parameter></paramdef>
13566  </funcprototype></funcsynopsis>
13567</refsynopsisdiv>
13568<refsect1>
13569 <title>Arguments</title>
13570 <variablelist>
13571  <varlistentry>
13572   <term><parameter>connector</parameter></term>
13573   <listitem>
13574    <para>
13575     drm connector
13576    </para>
13577   </listitem>
13578  </varlistentry>
13579  <varlistentry>
13580   <term><parameter>edid</parameter></term>
13581   <listitem>
13582    <para>
13583     new value of the edid property
13584    </para>
13585   </listitem>
13586  </varlistentry>
13587 </variablelist>
13588</refsect1>
13589<refsect1>
13590<title>Description</title>
13591<para>
13592   This function creates a new blob modeset object and assigns its id to the
13593   connector's edid property.
13594</para>
13595</refsect1>
13596<refsect1>
13597<title>Returns</title>
13598<para>
13599   Zero on success, negative errno on failure.
13600</para>
13601</refsect1>
13602</refentry>
13603
13604<refentry id="API-drm-mode-plane-set-obj-prop">
13605<refentryinfo>
13606 <title>LINUX</title>
13607 <productname>Kernel Hackers Manual</productname>
13608 <date>July 2017</date>
13609</refentryinfo>
13610<refmeta>
13611 <refentrytitle><phrase>drm_mode_plane_set_obj_prop</phrase></refentrytitle>
13612 <manvolnum>9</manvolnum>
13613 <refmiscinfo class="version">4.1.27</refmiscinfo>
13614</refmeta>
13615<refnamediv>
13616 <refname>drm_mode_plane_set_obj_prop</refname>
13617 <refpurpose>
13618     set the value of a property
13619 </refpurpose>
13620</refnamediv>
13621<refsynopsisdiv>
13622 <title>Synopsis</title>
13623  <funcsynopsis><funcprototype>
13624   <funcdef>int <function>drm_mode_plane_set_obj_prop </function></funcdef>
13625   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
13626   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
13627   <paramdef>uint64_t <parameter>value</parameter></paramdef>
13628  </funcprototype></funcsynopsis>
13629</refsynopsisdiv>
13630<refsect1>
13631 <title>Arguments</title>
13632 <variablelist>
13633  <varlistentry>
13634   <term><parameter>plane</parameter></term>
13635   <listitem>
13636    <para>
13637     drm plane object to set property value for
13638    </para>
13639   </listitem>
13640  </varlistentry>
13641  <varlistentry>
13642   <term><parameter>property</parameter></term>
13643   <listitem>
13644    <para>
13645     property to set
13646    </para>
13647   </listitem>
13648  </varlistentry>
13649  <varlistentry>
13650   <term><parameter>value</parameter></term>
13651   <listitem>
13652    <para>
13653     value the property should be set to
13654    </para>
13655   </listitem>
13656  </varlistentry>
13657 </variablelist>
13658</refsect1>
13659<refsect1>
13660<title>Description</title>
13661<para>
13662   This functions sets a given property on a given plane object. This function
13663   calls the driver's -&gt;set_property callback and changes the software state of
13664   the property if the callback succeeds.
13665</para>
13666</refsect1>
13667<refsect1>
13668<title>Returns</title>
13669<para>
13670   Zero on success, error code on failure.
13671</para>
13672</refsect1>
13673</refentry>
13674
13675<refentry id="API-drm-mode-connector-attach-encoder">
13676<refentryinfo>
13677 <title>LINUX</title>
13678 <productname>Kernel Hackers Manual</productname>
13679 <date>July 2017</date>
13680</refentryinfo>
13681<refmeta>
13682 <refentrytitle><phrase>drm_mode_connector_attach_encoder</phrase></refentrytitle>
13683 <manvolnum>9</manvolnum>
13684 <refmiscinfo class="version">4.1.27</refmiscinfo>
13685</refmeta>
13686<refnamediv>
13687 <refname>drm_mode_connector_attach_encoder</refname>
13688 <refpurpose>
13689     attach a connector to an encoder
13690 </refpurpose>
13691</refnamediv>
13692<refsynopsisdiv>
13693 <title>Synopsis</title>
13694  <funcsynopsis><funcprototype>
13695   <funcdef>int <function>drm_mode_connector_attach_encoder </function></funcdef>
13696   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
13697   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
13698  </funcprototype></funcsynopsis>
13699</refsynopsisdiv>
13700<refsect1>
13701 <title>Arguments</title>
13702 <variablelist>
13703  <varlistentry>
13704   <term><parameter>connector</parameter></term>
13705   <listitem>
13706    <para>
13707     connector to attach
13708    </para>
13709   </listitem>
13710  </varlistentry>
13711  <varlistentry>
13712   <term><parameter>encoder</parameter></term>
13713   <listitem>
13714    <para>
13715     encoder to attach <parameter>connector</parameter> to
13716    </para>
13717   </listitem>
13718  </varlistentry>
13719 </variablelist>
13720</refsect1>
13721<refsect1>
13722<title>Description</title>
13723<para>
13724   This function links up a connector to an encoder. Note that the routing
13725   restrictions between encoders and crtcs are exposed to userspace through the
13726   possible_clones and possible_crtcs bitmasks.
13727</para>
13728</refsect1>
13729<refsect1>
13730<title>Returns</title>
13731<para>
13732   Zero on success, negative errno on failure.
13733</para>
13734</refsect1>
13735</refentry>
13736
13737<refentry id="API-drm-mode-crtc-set-gamma-size">
13738<refentryinfo>
13739 <title>LINUX</title>
13740 <productname>Kernel Hackers Manual</productname>
13741 <date>July 2017</date>
13742</refentryinfo>
13743<refmeta>
13744 <refentrytitle><phrase>drm_mode_crtc_set_gamma_size</phrase></refentrytitle>
13745 <manvolnum>9</manvolnum>
13746 <refmiscinfo class="version">4.1.27</refmiscinfo>
13747</refmeta>
13748<refnamediv>
13749 <refname>drm_mode_crtc_set_gamma_size</refname>
13750 <refpurpose>
13751     set the gamma table size
13752 </refpurpose>
13753</refnamediv>
13754<refsynopsisdiv>
13755 <title>Synopsis</title>
13756  <funcsynopsis><funcprototype>
13757   <funcdef>int <function>drm_mode_crtc_set_gamma_size </function></funcdef>
13758   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
13759   <paramdef>int <parameter>gamma_size</parameter></paramdef>
13760  </funcprototype></funcsynopsis>
13761</refsynopsisdiv>
13762<refsect1>
13763 <title>Arguments</title>
13764 <variablelist>
13765  <varlistentry>
13766   <term><parameter>crtc</parameter></term>
13767   <listitem>
13768    <para>
13769     CRTC to set the gamma table size for
13770    </para>
13771   </listitem>
13772  </varlistentry>
13773  <varlistentry>
13774   <term><parameter>gamma_size</parameter></term>
13775   <listitem>
13776    <para>
13777     size of the gamma table
13778    </para>
13779   </listitem>
13780  </varlistentry>
13781 </variablelist>
13782</refsect1>
13783<refsect1>
13784<title>Description</title>
13785<para>
13786   Drivers which support gamma tables should set this to the supported gamma
13787   table size when initializing the CRTC. Currently the drm core only supports a
13788   fixed gamma table size.
13789</para>
13790</refsect1>
13791<refsect1>
13792<title>Returns</title>
13793<para>
13794   Zero on success, negative errno on failure.
13795</para>
13796</refsect1>
13797</refentry>
13798
13799<refentry id="API-drm-mode-config-reset">
13800<refentryinfo>
13801 <title>LINUX</title>
13802 <productname>Kernel Hackers Manual</productname>
13803 <date>July 2017</date>
13804</refentryinfo>
13805<refmeta>
13806 <refentrytitle><phrase>drm_mode_config_reset</phrase></refentrytitle>
13807 <manvolnum>9</manvolnum>
13808 <refmiscinfo class="version">4.1.27</refmiscinfo>
13809</refmeta>
13810<refnamediv>
13811 <refname>drm_mode_config_reset</refname>
13812 <refpurpose>
13813     call -&gt;reset callbacks
13814 </refpurpose>
13815</refnamediv>
13816<refsynopsisdiv>
13817 <title>Synopsis</title>
13818  <funcsynopsis><funcprototype>
13819   <funcdef>void <function>drm_mode_config_reset </function></funcdef>
13820   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
13821  </funcprototype></funcsynopsis>
13822</refsynopsisdiv>
13823<refsect1>
13824 <title>Arguments</title>
13825 <variablelist>
13826  <varlistentry>
13827   <term><parameter>dev</parameter></term>
13828   <listitem>
13829    <para>
13830     drm device
13831    </para>
13832   </listitem>
13833  </varlistentry>
13834 </variablelist>
13835</refsect1>
13836<refsect1>
13837<title>Description</title>
13838<para>
13839   This functions calls all the crtc's, encoder's and connector's -&gt;reset
13840   callback. Drivers can use this in e.g. their driver load or resume code to
13841   reset hardware and software state.
13842</para>
13843</refsect1>
13844</refentry>
13845
13846<refentry id="API-drm-fb-get-bpp-depth">
13847<refentryinfo>
13848 <title>LINUX</title>
13849 <productname>Kernel Hackers Manual</productname>
13850 <date>July 2017</date>
13851</refentryinfo>
13852<refmeta>
13853 <refentrytitle><phrase>drm_fb_get_bpp_depth</phrase></refentrytitle>
13854 <manvolnum>9</manvolnum>
13855 <refmiscinfo class="version">4.1.27</refmiscinfo>
13856</refmeta>
13857<refnamediv>
13858 <refname>drm_fb_get_bpp_depth</refname>
13859 <refpurpose>
13860     get the bpp/depth values for format
13861 </refpurpose>
13862</refnamediv>
13863<refsynopsisdiv>
13864 <title>Synopsis</title>
13865  <funcsynopsis><funcprototype>
13866   <funcdef>void <function>drm_fb_get_bpp_depth </function></funcdef>
13867   <paramdef>uint32_t <parameter>format</parameter></paramdef>
13868   <paramdef>unsigned int * <parameter>depth</parameter></paramdef>
13869   <paramdef>int * <parameter>bpp</parameter></paramdef>
13870  </funcprototype></funcsynopsis>
13871</refsynopsisdiv>
13872<refsect1>
13873 <title>Arguments</title>
13874 <variablelist>
13875  <varlistentry>
13876   <term><parameter>format</parameter></term>
13877   <listitem>
13878    <para>
13879     pixel format (DRM_FORMAT_*)
13880    </para>
13881   </listitem>
13882  </varlistentry>
13883  <varlistentry>
13884   <term><parameter>depth</parameter></term>
13885   <listitem>
13886    <para>
13887     storage for the depth value
13888    </para>
13889   </listitem>
13890  </varlistentry>
13891  <varlistentry>
13892   <term><parameter>bpp</parameter></term>
13893   <listitem>
13894    <para>
13895     storage for the bpp value
13896    </para>
13897   </listitem>
13898  </varlistentry>
13899 </variablelist>
13900</refsect1>
13901<refsect1>
13902<title>Description</title>
13903<para>
13904   This only supports RGB formats here for compat with code that doesn't use
13905   pixel formats directly yet.
13906</para>
13907</refsect1>
13908</refentry>
13909
13910<refentry id="API-drm-format-num-planes">
13911<refentryinfo>
13912 <title>LINUX</title>
13913 <productname>Kernel Hackers Manual</productname>
13914 <date>July 2017</date>
13915</refentryinfo>
13916<refmeta>
13917 <refentrytitle><phrase>drm_format_num_planes</phrase></refentrytitle>
13918 <manvolnum>9</manvolnum>
13919 <refmiscinfo class="version">4.1.27</refmiscinfo>
13920</refmeta>
13921<refnamediv>
13922 <refname>drm_format_num_planes</refname>
13923 <refpurpose>
13924     get the number of planes for format
13925 </refpurpose>
13926</refnamediv>
13927<refsynopsisdiv>
13928 <title>Synopsis</title>
13929  <funcsynopsis><funcprototype>
13930   <funcdef>int <function>drm_format_num_planes </function></funcdef>
13931   <paramdef>uint32_t <parameter>format</parameter></paramdef>
13932  </funcprototype></funcsynopsis>
13933</refsynopsisdiv>
13934<refsect1>
13935 <title>Arguments</title>
13936 <variablelist>
13937  <varlistentry>
13938   <term><parameter>format</parameter></term>
13939   <listitem>
13940    <para>
13941     pixel format (DRM_FORMAT_*)
13942    </para>
13943   </listitem>
13944  </varlistentry>
13945 </variablelist>
13946</refsect1>
13947<refsect1>
13948<title>Returns</title>
13949<para>
13950   The number of planes used by the specified pixel format.
13951</para>
13952</refsect1>
13953</refentry>
13954
13955<refentry id="API-drm-format-plane-cpp">
13956<refentryinfo>
13957 <title>LINUX</title>
13958 <productname>Kernel Hackers Manual</productname>
13959 <date>July 2017</date>
13960</refentryinfo>
13961<refmeta>
13962 <refentrytitle><phrase>drm_format_plane_cpp</phrase></refentrytitle>
13963 <manvolnum>9</manvolnum>
13964 <refmiscinfo class="version">4.1.27</refmiscinfo>
13965</refmeta>
13966<refnamediv>
13967 <refname>drm_format_plane_cpp</refname>
13968 <refpurpose>
13969     determine the bytes per pixel value
13970 </refpurpose>
13971</refnamediv>
13972<refsynopsisdiv>
13973 <title>Synopsis</title>
13974  <funcsynopsis><funcprototype>
13975   <funcdef>int <function>drm_format_plane_cpp </function></funcdef>
13976   <paramdef>uint32_t <parameter>format</parameter></paramdef>
13977   <paramdef>int <parameter>plane</parameter></paramdef>
13978  </funcprototype></funcsynopsis>
13979</refsynopsisdiv>
13980<refsect1>
13981 <title>Arguments</title>
13982 <variablelist>
13983  <varlistentry>
13984   <term><parameter>format</parameter></term>
13985   <listitem>
13986    <para>
13987     pixel format (DRM_FORMAT_*)
13988    </para>
13989   </listitem>
13990  </varlistentry>
13991  <varlistentry>
13992   <term><parameter>plane</parameter></term>
13993   <listitem>
13994    <para>
13995     plane index
13996    </para>
13997   </listitem>
13998  </varlistentry>
13999 </variablelist>
14000</refsect1>
14001<refsect1>
14002<title>Returns</title>
14003<para>
14004   The bytes per pixel value for the specified plane.
14005</para>
14006</refsect1>
14007</refentry>
14008
14009<refentry id="API-drm-format-horz-chroma-subsampling">
14010<refentryinfo>
14011 <title>LINUX</title>
14012 <productname>Kernel Hackers Manual</productname>
14013 <date>July 2017</date>
14014</refentryinfo>
14015<refmeta>
14016 <refentrytitle><phrase>drm_format_horz_chroma_subsampling</phrase></refentrytitle>
14017 <manvolnum>9</manvolnum>
14018 <refmiscinfo class="version">4.1.27</refmiscinfo>
14019</refmeta>
14020<refnamediv>
14021 <refname>drm_format_horz_chroma_subsampling</refname>
14022 <refpurpose>
14023     get the horizontal chroma subsampling factor
14024 </refpurpose>
14025</refnamediv>
14026<refsynopsisdiv>
14027 <title>Synopsis</title>
14028  <funcsynopsis><funcprototype>
14029   <funcdef>int <function>drm_format_horz_chroma_subsampling </function></funcdef>
14030   <paramdef>uint32_t <parameter>format</parameter></paramdef>
14031  </funcprototype></funcsynopsis>
14032</refsynopsisdiv>
14033<refsect1>
14034 <title>Arguments</title>
14035 <variablelist>
14036  <varlistentry>
14037   <term><parameter>format</parameter></term>
14038   <listitem>
14039    <para>
14040     pixel format (DRM_FORMAT_*)
14041    </para>
14042   </listitem>
14043  </varlistentry>
14044 </variablelist>
14045</refsect1>
14046<refsect1>
14047<title>Returns</title>
14048<para>
14049   The horizontal chroma subsampling factor for the
14050   specified pixel format.
14051</para>
14052</refsect1>
14053</refentry>
14054
14055<refentry id="API-drm-format-vert-chroma-subsampling">
14056<refentryinfo>
14057 <title>LINUX</title>
14058 <productname>Kernel Hackers Manual</productname>
14059 <date>July 2017</date>
14060</refentryinfo>
14061<refmeta>
14062 <refentrytitle><phrase>drm_format_vert_chroma_subsampling</phrase></refentrytitle>
14063 <manvolnum>9</manvolnum>
14064 <refmiscinfo class="version">4.1.27</refmiscinfo>
14065</refmeta>
14066<refnamediv>
14067 <refname>drm_format_vert_chroma_subsampling</refname>
14068 <refpurpose>
14069     get the vertical chroma subsampling factor
14070 </refpurpose>
14071</refnamediv>
14072<refsynopsisdiv>
14073 <title>Synopsis</title>
14074  <funcsynopsis><funcprototype>
14075   <funcdef>int <function>drm_format_vert_chroma_subsampling </function></funcdef>
14076   <paramdef>uint32_t <parameter>format</parameter></paramdef>
14077  </funcprototype></funcsynopsis>
14078</refsynopsisdiv>
14079<refsect1>
14080 <title>Arguments</title>
14081 <variablelist>
14082  <varlistentry>
14083   <term><parameter>format</parameter></term>
14084   <listitem>
14085    <para>
14086     pixel format (DRM_FORMAT_*)
14087    </para>
14088   </listitem>
14089  </varlistentry>
14090 </variablelist>
14091</refsect1>
14092<refsect1>
14093<title>Returns</title>
14094<para>
14095   The vertical chroma subsampling factor for the
14096   specified pixel format.
14097</para>
14098</refsect1>
14099</refentry>
14100
14101<refentry id="API-drm-rotation-simplify">
14102<refentryinfo>
14103 <title>LINUX</title>
14104 <productname>Kernel Hackers Manual</productname>
14105 <date>July 2017</date>
14106</refentryinfo>
14107<refmeta>
14108 <refentrytitle><phrase>drm_rotation_simplify</phrase></refentrytitle>
14109 <manvolnum>9</manvolnum>
14110 <refmiscinfo class="version">4.1.27</refmiscinfo>
14111</refmeta>
14112<refnamediv>
14113 <refname>drm_rotation_simplify</refname>
14114 <refpurpose>
14115     Try to simplify the rotation
14116 </refpurpose>
14117</refnamediv>
14118<refsynopsisdiv>
14119 <title>Synopsis</title>
14120  <funcsynopsis><funcprototype>
14121   <funcdef>unsigned int <function>drm_rotation_simplify </function></funcdef>
14122   <paramdef>unsigned int <parameter>rotation</parameter></paramdef>
14123   <paramdef>unsigned int <parameter>supported_rotations</parameter></paramdef>
14124  </funcprototype></funcsynopsis>
14125</refsynopsisdiv>
14126<refsect1>
14127 <title>Arguments</title>
14128 <variablelist>
14129  <varlistentry>
14130   <term><parameter>rotation</parameter></term>
14131   <listitem>
14132    <para>
14133     Rotation to be simplified
14134    </para>
14135   </listitem>
14136  </varlistentry>
14137  <varlistentry>
14138   <term><parameter>supported_rotations</parameter></term>
14139   <listitem>
14140    <para>
14141     Supported rotations
14142    </para>
14143   </listitem>
14144  </varlistentry>
14145 </variablelist>
14146</refsect1>
14147<refsect1>
14148<title>Description</title>
14149<para>
14150   Attempt to simplify the rotation to a form that is supported.
14151   Eg. if the hardware supports everything except DRM_REFLECT_X
14152</para>
14153</refsect1>
14154<refsect1>
14155<title>one could call this function like this</title>
14156<para>
14157   </para><para>
14158
14159   drm_rotation_simplify(rotation, BIT(DRM_ROTATE_0) |
14160   BIT(DRM_ROTATE_90) | BIT(DRM_ROTATE_180) |
14161   BIT(DRM_ROTATE_270) | BIT(DRM_REFLECT_Y));
14162   </para><para>
14163
14164   to eliminate the DRM_ROTATE_X flag. Depending on what kind of
14165   transforms the hardware supports, this function may not
14166   be able to produce a supported transform, so the caller should
14167   check the result afterwards.
14168</para>
14169</refsect1>
14170</refentry>
14171
14172<refentry id="API-drm-mode-config-init">
14173<refentryinfo>
14174 <title>LINUX</title>
14175 <productname>Kernel Hackers Manual</productname>
14176 <date>July 2017</date>
14177</refentryinfo>
14178<refmeta>
14179 <refentrytitle><phrase>drm_mode_config_init</phrase></refentrytitle>
14180 <manvolnum>9</manvolnum>
14181 <refmiscinfo class="version">4.1.27</refmiscinfo>
14182</refmeta>
14183<refnamediv>
14184 <refname>drm_mode_config_init</refname>
14185 <refpurpose>
14186     initialize DRM mode_configuration structure
14187 </refpurpose>
14188</refnamediv>
14189<refsynopsisdiv>
14190 <title>Synopsis</title>
14191  <funcsynopsis><funcprototype>
14192   <funcdef>void <function>drm_mode_config_init </function></funcdef>
14193   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
14194  </funcprototype></funcsynopsis>
14195</refsynopsisdiv>
14196<refsect1>
14197 <title>Arguments</title>
14198 <variablelist>
14199  <varlistentry>
14200   <term><parameter>dev</parameter></term>
14201   <listitem>
14202    <para>
14203     DRM device
14204    </para>
14205   </listitem>
14206  </varlistentry>
14207 </variablelist>
14208</refsect1>
14209<refsect1>
14210<title>Description</title>
14211<para>
14212   Initialize <parameter>dev</parameter>'s mode_config structure, used for tracking the graphics
14213   configuration of <parameter>dev</parameter>.
14214   </para><para>
14215
14216   Since this initializes the modeset locks, no locking is possible. Which is no
14217   problem, since this should happen single threaded at init time. It is the
14218   driver's problem to ensure this guarantee.
14219</para>
14220</refsect1>
14221</refentry>
14222
14223<refentry id="API-drm-mode-config-cleanup">
14224<refentryinfo>
14225 <title>LINUX</title>
14226 <productname>Kernel Hackers Manual</productname>
14227 <date>July 2017</date>
14228</refentryinfo>
14229<refmeta>
14230 <refentrytitle><phrase>drm_mode_config_cleanup</phrase></refentrytitle>
14231 <manvolnum>9</manvolnum>
14232 <refmiscinfo class="version">4.1.27</refmiscinfo>
14233</refmeta>
14234<refnamediv>
14235 <refname>drm_mode_config_cleanup</refname>
14236 <refpurpose>
14237     free up DRM mode_config info
14238 </refpurpose>
14239</refnamediv>
14240<refsynopsisdiv>
14241 <title>Synopsis</title>
14242  <funcsynopsis><funcprototype>
14243   <funcdef>void <function>drm_mode_config_cleanup </function></funcdef>
14244   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
14245  </funcprototype></funcsynopsis>
14246</refsynopsisdiv>
14247<refsect1>
14248 <title>Arguments</title>
14249 <variablelist>
14250  <varlistentry>
14251   <term><parameter>dev</parameter></term>
14252   <listitem>
14253    <para>
14254     DRM device
14255    </para>
14256   </listitem>
14257  </varlistentry>
14258 </variablelist>
14259</refsect1>
14260<refsect1>
14261<title>Description</title>
14262<para>
14263   Free up all the connectors and CRTCs associated with this DRM device, then
14264   free up the framebuffers and associated buffer objects.
14265   </para><para>
14266
14267   Note that since this /should/ happen single-threaded at driver/device
14268   teardown time, no locking is required. It's the driver's job to ensure that
14269   this guarantee actually holds true.
14270</para>
14271</refsect1>
14272<refsect1>
14273<title>FIXME</title>
14274<para>
14275   cleanup any dangling user buffer objects too
14276</para>
14277</refsect1>
14278</refentry>
14279
14280<refentry id="API-drm-mode-get-tile-group">
14281<refentryinfo>
14282 <title>LINUX</title>
14283 <productname>Kernel Hackers Manual</productname>
14284 <date>July 2017</date>
14285</refentryinfo>
14286<refmeta>
14287 <refentrytitle><phrase>drm_mode_get_tile_group</phrase></refentrytitle>
14288 <manvolnum>9</manvolnum>
14289 <refmiscinfo class="version">4.1.27</refmiscinfo>
14290</refmeta>
14291<refnamediv>
14292 <refname>drm_mode_get_tile_group</refname>
14293 <refpurpose>
14294     get a reference to an existing tile group
14295 </refpurpose>
14296</refnamediv>
14297<refsynopsisdiv>
14298 <title>Synopsis</title>
14299  <funcsynopsis><funcprototype>
14300   <funcdef>struct drm_tile_group * <function>drm_mode_get_tile_group </function></funcdef>
14301   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
14302   <paramdef>char <parameter>topology[8]</parameter></paramdef>
14303  </funcprototype></funcsynopsis>
14304</refsynopsisdiv>
14305<refsect1>
14306 <title>Arguments</title>
14307 <variablelist>
14308  <varlistentry>
14309   <term><parameter>dev</parameter></term>
14310   <listitem>
14311    <para>
14312     DRM device
14313    </para>
14314   </listitem>
14315  </varlistentry>
14316  <varlistentry>
14317   <term><parameter>topology[8]</parameter></term>
14318   <listitem>
14319    <para>
14320     8-bytes unique per monitor.
14321    </para>
14322   </listitem>
14323  </varlistentry>
14324 </variablelist>
14325</refsect1>
14326<refsect1>
14327<title>Description</title>
14328<para>
14329   Use the unique bytes to get a reference to an existing tile group.
14330</para>
14331</refsect1>
14332<refsect1>
14333<title>RETURNS</title>
14334<para>
14335   tile group or NULL if not found.
14336</para>
14337</refsect1>
14338</refentry>
14339
14340<refentry id="API-drm-mode-create-tile-group">
14341<refentryinfo>
14342 <title>LINUX</title>
14343 <productname>Kernel Hackers Manual</productname>
14344 <date>July 2017</date>
14345</refentryinfo>
14346<refmeta>
14347 <refentrytitle><phrase>drm_mode_create_tile_group</phrase></refentrytitle>
14348 <manvolnum>9</manvolnum>
14349 <refmiscinfo class="version">4.1.27</refmiscinfo>
14350</refmeta>
14351<refnamediv>
14352 <refname>drm_mode_create_tile_group</refname>
14353 <refpurpose>
14354     create a tile group from a displayid description
14355 </refpurpose>
14356</refnamediv>
14357<refsynopsisdiv>
14358 <title>Synopsis</title>
14359  <funcsynopsis><funcprototype>
14360   <funcdef>struct drm_tile_group * <function>drm_mode_create_tile_group </function></funcdef>
14361   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
14362   <paramdef>char <parameter>topology[8]</parameter></paramdef>
14363  </funcprototype></funcsynopsis>
14364</refsynopsisdiv>
14365<refsect1>
14366 <title>Arguments</title>
14367 <variablelist>
14368  <varlistentry>
14369   <term><parameter>dev</parameter></term>
14370   <listitem>
14371    <para>
14372     DRM device
14373    </para>
14374   </listitem>
14375  </varlistentry>
14376  <varlistentry>
14377   <term><parameter>topology[8]</parameter></term>
14378   <listitem>
14379    <para>
14380     8-bytes unique per monitor.
14381    </para>
14382   </listitem>
14383  </varlistentry>
14384 </variablelist>
14385</refsect1>
14386<refsect1>
14387<title>Description</title>
14388<para>
14389   Create a tile group for the unique monitor, and get a unique
14390   identifier for the tile group.
14391</para>
14392</refsect1>
14393<refsect1>
14394<title>RETURNS</title>
14395<para>
14396   new tile group or error.
14397</para>
14398</refsect1>
14399</refentry>
14400
14401    </sect2>
14402    <sect2>
14403      <title>KMS Data Structures</title>
14404<!-- include/drm/drm_crtc.h -->
14405<refentry id="API-struct-drm-crtc-state">
14406<refentryinfo>
14407 <title>LINUX</title>
14408 <productname>Kernel Hackers Manual</productname>
14409 <date>July 2017</date>
14410</refentryinfo>
14411<refmeta>
14412 <refentrytitle><phrase>struct drm_crtc_state</phrase></refentrytitle>
14413 <manvolnum>9</manvolnum>
14414 <refmiscinfo class="version">4.1.27</refmiscinfo>
14415</refmeta>
14416<refnamediv>
14417 <refname>struct drm_crtc_state</refname>
14418 <refpurpose>
14419  mutable CRTC state
14420 </refpurpose>
14421</refnamediv>
14422<refsynopsisdiv>
14423 <title>Synopsis</title>
14424  <programlisting>
14425struct drm_crtc_state {
14426  struct drm_crtc * crtc;
14427  bool enable;
14428  bool active;
14429  bool planes_changed:1;
14430  bool mode_changed:1;
14431  bool active_changed:1;
14432  u32 plane_mask;
14433  u32 last_vblank_count;
14434  struct drm_display_mode adjusted_mode;
14435  struct drm_display_mode mode;
14436  struct drm_pending_vblank_event * event;
14437  struct drm_atomic_state * state;
14438};  </programlisting>
14439</refsynopsisdiv>
14440 <refsect1>
14441  <title>Members</title>
14442  <variablelist>
14443    <varlistentry>      <term>crtc</term>
14444      <listitem><para>
14445backpointer to the CRTC
14446      </para></listitem>
14447    </varlistentry>
14448    <varlistentry>      <term>enable</term>
14449      <listitem><para>
14450whether the CRTC should be enabled, gates all other state
14451      </para></listitem>
14452    </varlistentry>
14453    <varlistentry>      <term>active</term>
14454      <listitem><para>
14455whether the CRTC is actively displaying (used for DPMS)
14456      </para></listitem>
14457    </varlistentry>
14458    <varlistentry>      <term>planes_changed</term>
14459      <listitem><para>
14460for use by helpers and drivers when computing state updates
14461      </para></listitem>
14462    </varlistentry>
14463    <varlistentry>      <term>mode_changed</term>
14464      <listitem><para>
14465for use by helpers and drivers when computing state updates
14466      </para></listitem>
14467    </varlistentry>
14468    <varlistentry>      <term>active_changed</term>
14469      <listitem><para>
14470for use by helpers and drivers when computing state updates
14471      </para></listitem>
14472    </varlistentry>
14473    <varlistentry>      <term>plane_mask</term>
14474      <listitem><para>
14475bitmask of (1 &lt;&lt; drm_plane_index(plane)) of attached planes
14476      </para></listitem>
14477    </varlistentry>
14478    <varlistentry>      <term>last_vblank_count</term>
14479      <listitem><para>
14480for helpers and drivers to capture the vblank of the
14481update to ensure framebuffer cleanup isn't done too early
14482      </para></listitem>
14483    </varlistentry>
14484    <varlistentry>      <term>adjusted_mode</term>
14485      <listitem><para>
14486for use by helpers and drivers to compute adjusted mode timings
14487      </para></listitem>
14488    </varlistentry>
14489    <varlistentry>      <term>mode</term>
14490      <listitem><para>
14491current mode timings
14492      </para></listitem>
14493    </varlistentry>
14494    <varlistentry>      <term>event</term>
14495      <listitem><para>
14496optional pointer to a DRM event to signal upon completion of the
14497state update
14498      </para></listitem>
14499    </varlistentry>
14500    <varlistentry>      <term>state</term>
14501      <listitem><para>
14502backpointer to global drm_atomic_state
14503      </para></listitem>
14504    </varlistentry>
14505  </variablelist>
14506 </refsect1>
14507<refsect1>
14508<title>Description</title>
14509<para>
14510   Note that the distinction between <parameter>enable</parameter> and <parameter>active</parameter> is rather subtile:
14511   Flipping <parameter>active</parameter> while <parameter>enable</parameter> is set without changing anything else may
14512   never return in a failure from the -&gt;atomic_check callback. Userspace assumes
14513   that a DPMS On will always succeed. In other words: <parameter>enable</parameter> controls resource
14514   assignment, <parameter>active</parameter> controls the actual hardware state.
14515</para>
14516</refsect1>
14517</refentry>
14518
14519<refentry id="API-struct-drm-crtc-funcs">
14520<refentryinfo>
14521 <title>LINUX</title>
14522 <productname>Kernel Hackers Manual</productname>
14523 <date>July 2017</date>
14524</refentryinfo>
14525<refmeta>
14526 <refentrytitle><phrase>struct drm_crtc_funcs</phrase></refentrytitle>
14527 <manvolnum>9</manvolnum>
14528 <refmiscinfo class="version">4.1.27</refmiscinfo>
14529</refmeta>
14530<refnamediv>
14531 <refname>struct drm_crtc_funcs</refname>
14532 <refpurpose>
14533     control CRTCs for a given device
14534 </refpurpose>
14535</refnamediv>
14536<refsynopsisdiv>
14537 <title>Synopsis</title>
14538  <programlisting>
14539struct drm_crtc_funcs {
14540  void (* save) (struct drm_crtc *crtc);
14541  void (* restore) (struct drm_crtc *crtc);
14542  void (* reset) (struct drm_crtc *crtc);
14543  int (* cursor_set) (struct drm_crtc *crtc, struct drm_file *file_priv,uint32_t handle, uint32_t width, uint32_t height);
14544  int (* cursor_set2) (struct drm_crtc *crtc, struct drm_file *file_priv,uint32_t handle, uint32_t width, uint32_t height,int32_t hot_x, int32_t hot_y);
14545  int (* cursor_move) (struct drm_crtc *crtc, int x, int y);
14546  void (* gamma_set) (struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,uint32_t start, uint32_t size);
14547  void (* destroy) (struct drm_crtc *crtc);
14548  int (* set_config) (struct drm_mode_set *set);
14549  int (* page_flip) (struct drm_crtc *crtc,struct drm_framebuffer *fb,struct drm_pending_vblank_event *event,uint32_t flags);
14550  int (* set_property) (struct drm_crtc *crtc,struct drm_property *property, uint64_t val);
14551  struct drm_crtc_state *(* atomic_duplicate_state) (struct drm_crtc *crtc);
14552  void (* atomic_destroy_state) (struct drm_crtc *crtc,struct drm_crtc_state *state);
14553  int (* atomic_set_property) (struct drm_crtc *crtc,struct drm_crtc_state *state,struct drm_property *property,uint64_t val);
14554  int (* atomic_get_property) (struct drm_crtc *crtc,const struct drm_crtc_state *state,struct drm_property *property,uint64_t *val);
14555};  </programlisting>
14556</refsynopsisdiv>
14557 <refsect1>
14558  <title>Members</title>
14559  <variablelist>
14560    <varlistentry>      <term>save</term>
14561      <listitem><para>
14562   save CRTC state
14563      </para></listitem>
14564    </varlistentry>
14565    <varlistentry>      <term>restore</term>
14566      <listitem><para>
14567   restore CRTC state
14568      </para></listitem>
14569    </varlistentry>
14570    <varlistentry>      <term>reset</term>
14571      <listitem><para>
14572   reset CRTC after state has been invalidated (e.g. resume)
14573      </para></listitem>
14574    </varlistentry>
14575    <varlistentry>      <term>cursor_set</term>
14576      <listitem><para>
14577   setup the cursor
14578      </para></listitem>
14579    </varlistentry>
14580    <varlistentry>      <term>cursor_set2</term>
14581      <listitem><para>
14582   setup the cursor with hotspot, superseeds <parameter>cursor_set</parameter> if set
14583      </para></listitem>
14584    </varlistentry>
14585    <varlistentry>      <term>cursor_move</term>
14586      <listitem><para>
14587   move the cursor
14588      </para></listitem>
14589    </varlistentry>
14590    <varlistentry>      <term>gamma_set</term>
14591      <listitem><para>
14592   specify color ramp for CRTC
14593      </para></listitem>
14594    </varlistentry>
14595    <varlistentry>      <term>destroy</term>
14596      <listitem><para>
14597   deinit and free object
14598      </para></listitem>
14599    </varlistentry>
14600    <varlistentry>      <term>set_config</term>
14601      <listitem><para>
14602   apply a new CRTC configuration
14603      </para></listitem>
14604    </varlistentry>
14605    <varlistentry>      <term>page_flip</term>
14606      <listitem><para>
14607   initiate a page flip
14608      </para></listitem>
14609    </varlistentry>
14610    <varlistentry>      <term>set_property</term>
14611      <listitem><para>
14612   called when a property is changed
14613      </para></listitem>
14614    </varlistentry>
14615    <varlistentry>      <term>atomic_duplicate_state</term>
14616      <listitem><para>
14617   duplicate the atomic state for this CRTC
14618      </para></listitem>
14619    </varlistentry>
14620    <varlistentry>      <term>atomic_destroy_state</term>
14621      <listitem><para>
14622   destroy an atomic state for this CRTC
14623      </para></listitem>
14624    </varlistentry>
14625    <varlistentry>      <term>atomic_set_property</term>
14626      <listitem><para>
14627   set a property on an atomic state for this CRTC
14628   (do not call directly, use <function>drm_atomic_crtc_set_property</function>)
14629      </para></listitem>
14630    </varlistentry>
14631    <varlistentry>      <term>atomic_get_property</term>
14632      <listitem><para>
14633   get a property on an atomic state for this CRTC
14634   (do not call directly, use <function>drm_atomic_crtc_get_property</function>)
14635      </para></listitem>
14636    </varlistentry>
14637  </variablelist>
14638 </refsect1>
14639<refsect1>
14640<title>Description</title>
14641<para>
14642   The drm_crtc_funcs structure is the central CRTC management structure
14643   in the DRM.  Each CRTC controls one or more connectors (note that the name
14644   CRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc.
14645   connectors, not just CRTs).
14646   </para><para>
14647
14648   Each driver is responsible for filling out this structure at startup time,
14649   in addition to providing other modesetting features, like i2c and DDC
14650   bus accessors.
14651</para>
14652</refsect1>
14653</refentry>
14654
14655<refentry id="API-struct-drm-crtc">
14656<refentryinfo>
14657 <title>LINUX</title>
14658 <productname>Kernel Hackers Manual</productname>
14659 <date>July 2017</date>
14660</refentryinfo>
14661<refmeta>
14662 <refentrytitle><phrase>struct drm_crtc</phrase></refentrytitle>
14663 <manvolnum>9</manvolnum>
14664 <refmiscinfo class="version">4.1.27</refmiscinfo>
14665</refmeta>
14666<refnamediv>
14667 <refname>struct drm_crtc</refname>
14668 <refpurpose>
14669     central CRTC control structure
14670 </refpurpose>
14671</refnamediv>
14672<refsynopsisdiv>
14673 <title>Synopsis</title>
14674  <programlisting>
14675struct drm_crtc {
14676  struct drm_device * dev;
14677  struct device_node * port;
14678  struct list_head head;
14679  struct drm_modeset_lock mutex;
14680  struct drm_mode_object base;
14681  struct drm_plane * primary;
14682  struct drm_plane * cursor;
14683  int cursor_x;
14684  int cursor_y;
14685  bool enabled;
14686  struct drm_display_mode mode;
14687  struct drm_display_mode hwmode;
14688  bool invert_dimensions;
14689  int x;
14690  int y;
14691  const struct drm_crtc_funcs * funcs;
14692  uint32_t gamma_size;
14693  uint16_t * gamma_store;
14694  int framedur_ns;
14695  int linedur_ns;
14696  int pixeldur_ns;
14697  const void * helper_private;
14698  struct drm_object_properties properties;
14699  struct drm_crtc_state * state;
14700  struct drm_modeset_acquire_ctx * acquire_ctx;
14701};  </programlisting>
14702</refsynopsisdiv>
14703 <refsect1>
14704  <title>Members</title>
14705  <variablelist>
14706    <varlistentry>      <term>dev</term>
14707      <listitem><para>
14708   parent DRM device
14709      </para></listitem>
14710    </varlistentry>
14711    <varlistentry>      <term>port</term>
14712      <listitem><para>
14713   OF node used by <function>drm_of_find_possible_crtcs</function>
14714      </para></listitem>
14715    </varlistentry>
14716    <varlistentry>      <term>head</term>
14717      <listitem><para>
14718   list management
14719      </para></listitem>
14720    </varlistentry>
14721    <varlistentry>      <term>mutex</term>
14722      <listitem><para>
14723   per-CRTC locking
14724      </para></listitem>
14725    </varlistentry>
14726    <varlistentry>      <term>base</term>
14727      <listitem><para>
14728   base KMS object for ID tracking etc.
14729      </para></listitem>
14730    </varlistentry>
14731    <varlistentry>      <term>primary</term>
14732      <listitem><para>
14733   primary plane for this CRTC
14734      </para></listitem>
14735    </varlistentry>
14736    <varlistentry>      <term>cursor</term>
14737      <listitem><para>
14738   cursor plane for this CRTC
14739      </para></listitem>
14740    </varlistentry>
14741    <varlistentry>      <term>cursor_x</term>
14742      <listitem><para>
14743   current x position of the cursor, used for universal cursor planes
14744      </para></listitem>
14745    </varlistentry>
14746    <varlistentry>      <term>cursor_y</term>
14747      <listitem><para>
14748   current y position of the cursor, used for universal cursor planes
14749      </para></listitem>
14750    </varlistentry>
14751    <varlistentry>      <term>enabled</term>
14752      <listitem><para>
14753   is this CRTC enabled?
14754      </para></listitem>
14755    </varlistentry>
14756    <varlistentry>      <term>mode</term>
14757      <listitem><para>
14758   current mode timings
14759      </para></listitem>
14760    </varlistentry>
14761    <varlistentry>      <term>hwmode</term>
14762      <listitem><para>
14763   mode timings as programmed to hw regs
14764      </para></listitem>
14765    </varlistentry>
14766    <varlistentry>      <term>invert_dimensions</term>
14767      <listitem><para>
14768   for purposes of error checking crtc vs fb sizes,
14769   invert the width/height of the crtc.  This is used if the driver
14770   is performing 90 or 270 degree rotated scanout
14771      </para></listitem>
14772    </varlistentry>
14773    <varlistentry>      <term>x</term>
14774      <listitem><para>
14775   x position on screen
14776      </para></listitem>
14777    </varlistentry>
14778    <varlistentry>      <term>y</term>
14779      <listitem><para>
14780   y position on screen
14781      </para></listitem>
14782    </varlistentry>
14783    <varlistentry>      <term>funcs</term>
14784      <listitem><para>
14785   CRTC control functions
14786      </para></listitem>
14787    </varlistentry>
14788    <varlistentry>      <term>gamma_size</term>
14789      <listitem><para>
14790   size of gamma ramp
14791      </para></listitem>
14792    </varlistentry>
14793    <varlistentry>      <term>gamma_store</term>
14794      <listitem><para>
14795   gamma ramp values
14796      </para></listitem>
14797    </varlistentry>
14798    <varlistentry>      <term>framedur_ns</term>
14799      <listitem><para>
14800   precise frame timing
14801      </para></listitem>
14802    </varlistentry>
14803    <varlistentry>      <term>linedur_ns</term>
14804      <listitem><para>
14805   precise line timing
14806      </para></listitem>
14807    </varlistentry>
14808    <varlistentry>      <term>pixeldur_ns</term>
14809      <listitem><para>
14810   precise pixel timing
14811      </para></listitem>
14812    </varlistentry>
14813    <varlistentry>      <term>helper_private</term>
14814      <listitem><para>
14815   mid-layer private data
14816      </para></listitem>
14817    </varlistentry>
14818    <varlistentry>      <term>properties</term>
14819      <listitem><para>
14820   property tracking for this CRTC
14821      </para></listitem>
14822    </varlistentry>
14823    <varlistentry>      <term>state</term>
14824      <listitem><para>
14825   current atomic state for this CRTC
14826      </para></listitem>
14827    </varlistentry>
14828    <varlistentry>      <term>acquire_ctx</term>
14829      <listitem><para>
14830   per-CRTC implicit acquire context used by atomic drivers for
14831   legacy ioctls
14832      </para></listitem>
14833    </varlistentry>
14834  </variablelist>
14835 </refsect1>
14836<refsect1>
14837<title>Description</title>
14838<para>
14839   Each CRTC may have one or more connectors associated with it.  This structure
14840   allows the CRTC to be controlled.
14841</para>
14842</refsect1>
14843</refentry>
14844
14845<refentry id="API-struct-drm-connector-state">
14846<refentryinfo>
14847 <title>LINUX</title>
14848 <productname>Kernel Hackers Manual</productname>
14849 <date>July 2017</date>
14850</refentryinfo>
14851<refmeta>
14852 <refentrytitle><phrase>struct drm_connector_state</phrase></refentrytitle>
14853 <manvolnum>9</manvolnum>
14854 <refmiscinfo class="version">4.1.27</refmiscinfo>
14855</refmeta>
14856<refnamediv>
14857 <refname>struct drm_connector_state</refname>
14858 <refpurpose>
14859     mutable connector state
14860 </refpurpose>
14861</refnamediv>
14862<refsynopsisdiv>
14863 <title>Synopsis</title>
14864  <programlisting>
14865struct drm_connector_state {
14866  struct drm_connector * connector;
14867  struct drm_crtc * crtc;
14868  struct drm_encoder * best_encoder;
14869  struct drm_atomic_state * state;
14870};  </programlisting>
14871</refsynopsisdiv>
14872 <refsect1>
14873  <title>Members</title>
14874  <variablelist>
14875    <varlistentry>      <term>connector</term>
14876      <listitem><para>
14877   backpointer to the connector
14878      </para></listitem>
14879    </varlistentry>
14880    <varlistentry>      <term>crtc</term>
14881      <listitem><para>
14882   CRTC to connect connector to, NULL if disabled
14883      </para></listitem>
14884    </varlistentry>
14885    <varlistentry>      <term>best_encoder</term>
14886      <listitem><para>
14887   can be used by helpers and drivers to select the encoder
14888      </para></listitem>
14889    </varlistentry>
14890    <varlistentry>      <term>state</term>
14891      <listitem><para>
14892   backpointer to global drm_atomic_state
14893      </para></listitem>
14894    </varlistentry>
14895  </variablelist>
14896 </refsect1>
14897</refentry>
14898
14899<refentry id="API-struct-drm-connector-funcs">
14900<refentryinfo>
14901 <title>LINUX</title>
14902 <productname>Kernel Hackers Manual</productname>
14903 <date>July 2017</date>
14904</refentryinfo>
14905<refmeta>
14906 <refentrytitle><phrase>struct drm_connector_funcs</phrase></refentrytitle>
14907 <manvolnum>9</manvolnum>
14908 <refmiscinfo class="version">4.1.27</refmiscinfo>
14909</refmeta>
14910<refnamediv>
14911 <refname>struct drm_connector_funcs</refname>
14912 <refpurpose>
14913     control connectors on a given device
14914 </refpurpose>
14915</refnamediv>
14916<refsynopsisdiv>
14917 <title>Synopsis</title>
14918  <programlisting>
14919struct drm_connector_funcs {
14920  void (* dpms) (struct drm_connector *connector, int mode);
14921  void (* save) (struct drm_connector *connector);
14922  void (* restore) (struct drm_connector *connector);
14923  void (* reset) (struct drm_connector *connector);
14924  enum drm_connector_status (* detect) (struct drm_connector *connector,bool force);
14925  int (* fill_modes) (struct drm_connector *connector, uint32_t max_width, uint32_t max_height);
14926  int (* set_property) (struct drm_connector *connector, struct drm_property *property,uint64_t val);
14927  void (* destroy) (struct drm_connector *connector);
14928  void (* force) (struct drm_connector *connector);
14929  struct drm_connector_state *(* atomic_duplicate_state) (struct drm_connector *connector);
14930  void (* atomic_destroy_state) (struct drm_connector *connector,struct drm_connector_state *state);
14931  int (* atomic_set_property) (struct drm_connector *connector,struct drm_connector_state *state,struct drm_property *property,uint64_t val);
14932  int (* atomic_get_property) (struct drm_connector *connector,const struct drm_connector_state *state,struct drm_property *property,uint64_t *val);
14933};  </programlisting>
14934</refsynopsisdiv>
14935 <refsect1>
14936  <title>Members</title>
14937  <variablelist>
14938    <varlistentry>      <term>dpms</term>
14939      <listitem><para>
14940   set power state
14941      </para></listitem>
14942    </varlistentry>
14943    <varlistentry>      <term>save</term>
14944      <listitem><para>
14945   save connector state
14946      </para></listitem>
14947    </varlistentry>
14948    <varlistentry>      <term>restore</term>
14949      <listitem><para>
14950   restore connector state
14951      </para></listitem>
14952    </varlistentry>
14953    <varlistentry>      <term>reset</term>
14954      <listitem><para>
14955   reset connector after state has been invalidated (e.g. resume)
14956      </para></listitem>
14957    </varlistentry>
14958    <varlistentry>      <term>detect</term>
14959      <listitem><para>
14960   is this connector active?
14961      </para></listitem>
14962    </varlistentry>
14963    <varlistentry>      <term>fill_modes</term>
14964      <listitem><para>
14965   fill mode list for this connector
14966      </para></listitem>
14967    </varlistentry>
14968    <varlistentry>      <term>set_property</term>
14969      <listitem><para>
14970   property for this connector may need an update
14971      </para></listitem>
14972    </varlistentry>
14973    <varlistentry>      <term>destroy</term>
14974      <listitem><para>
14975   make object go away
14976      </para></listitem>
14977    </varlistentry>
14978    <varlistentry>      <term>force</term>
14979      <listitem><para>
14980   notify the driver that the connector is forced on
14981      </para></listitem>
14982    </varlistentry>
14983    <varlistentry>      <term>atomic_duplicate_state</term>
14984      <listitem><para>
14985   duplicate the atomic state for this connector
14986      </para></listitem>
14987    </varlistentry>
14988    <varlistentry>      <term>atomic_destroy_state</term>
14989      <listitem><para>
14990   destroy an atomic state for this connector
14991      </para></listitem>
14992    </varlistentry>
14993    <varlistentry>      <term>atomic_set_property</term>
14994      <listitem><para>
14995   set a property on an atomic state for this connector
14996   (do not call directly, use <function>drm_atomic_connector_set_property</function>)
14997      </para></listitem>
14998    </varlistentry>
14999    <varlistentry>      <term>atomic_get_property</term>
15000      <listitem><para>
15001   get a property on an atomic state for this connector
15002   (do not call directly, use <function>drm_atomic_connector_get_property</function>)
15003      </para></listitem>
15004    </varlistentry>
15005  </variablelist>
15006 </refsect1>
15007<refsect1>
15008<title>Description</title>
15009<para>
15010   Each CRTC may have one or more connectors attached to it.  The functions
15011   below allow the core DRM code to control connectors, enumerate available modes,
15012   etc.
15013</para>
15014</refsect1>
15015</refentry>
15016
15017<refentry id="API-struct-drm-encoder-funcs">
15018<refentryinfo>
15019 <title>LINUX</title>
15020 <productname>Kernel Hackers Manual</productname>
15021 <date>July 2017</date>
15022</refentryinfo>
15023<refmeta>
15024 <refentrytitle><phrase>struct drm_encoder_funcs</phrase></refentrytitle>
15025 <manvolnum>9</manvolnum>
15026 <refmiscinfo class="version">4.1.27</refmiscinfo>
15027</refmeta>
15028<refnamediv>
15029 <refname>struct drm_encoder_funcs</refname>
15030 <refpurpose>
15031     encoder controls
15032 </refpurpose>
15033</refnamediv>
15034<refsynopsisdiv>
15035 <title>Synopsis</title>
15036  <programlisting>
15037struct drm_encoder_funcs {
15038  void (* reset) (struct drm_encoder *encoder);
15039  void (* destroy) (struct drm_encoder *encoder);
15040};  </programlisting>
15041</refsynopsisdiv>
15042 <refsect1>
15043  <title>Members</title>
15044  <variablelist>
15045    <varlistentry>      <term>reset</term>
15046      <listitem><para>
15047   reset state (e.g. at init or resume time)
15048      </para></listitem>
15049    </varlistentry>
15050    <varlistentry>      <term>destroy</term>
15051      <listitem><para>
15052   cleanup and free associated data
15053      </para></listitem>
15054    </varlistentry>
15055  </variablelist>
15056 </refsect1>
15057<refsect1>
15058<title>Description</title>
15059<para>
15060   Encoders sit between CRTCs and connectors.
15061</para>
15062</refsect1>
15063</refentry>
15064
15065<refentry id="API-struct-drm-encoder">
15066<refentryinfo>
15067 <title>LINUX</title>
15068 <productname>Kernel Hackers Manual</productname>
15069 <date>July 2017</date>
15070</refentryinfo>
15071<refmeta>
15072 <refentrytitle><phrase>struct drm_encoder</phrase></refentrytitle>
15073 <manvolnum>9</manvolnum>
15074 <refmiscinfo class="version">4.1.27</refmiscinfo>
15075</refmeta>
15076<refnamediv>
15077 <refname>struct drm_encoder</refname>
15078 <refpurpose>
15079     central DRM encoder structure
15080 </refpurpose>
15081</refnamediv>
15082<refsynopsisdiv>
15083 <title>Synopsis</title>
15084  <programlisting>
15085struct drm_encoder {
15086  struct drm_device * dev;
15087  struct list_head head;
15088  struct drm_mode_object base;
15089  char * name;
15090  int encoder_type;
15091  uint32_t possible_crtcs;
15092  uint32_t possible_clones;
15093  struct drm_crtc * crtc;
15094  struct drm_bridge * bridge;
15095  const struct drm_encoder_funcs * funcs;
15096  const void * helper_private;
15097};  </programlisting>
15098</refsynopsisdiv>
15099 <refsect1>
15100  <title>Members</title>
15101  <variablelist>
15102    <varlistentry>      <term>dev</term>
15103      <listitem><para>
15104   parent DRM device
15105      </para></listitem>
15106    </varlistentry>
15107    <varlistentry>      <term>head</term>
15108      <listitem><para>
15109   list management
15110      </para></listitem>
15111    </varlistentry>
15112    <varlistentry>      <term>base</term>
15113      <listitem><para>
15114   base KMS object
15115      </para></listitem>
15116    </varlistentry>
15117    <varlistentry>      <term>name</term>
15118      <listitem><para>
15119   encoder name
15120      </para></listitem>
15121    </varlistentry>
15122    <varlistentry>      <term>encoder_type</term>
15123      <listitem><para>
15124   one of the <constant>DRM_MODE_ENCODER_</constant>&lt;foo&gt; types in drm_mode.h
15125      </para></listitem>
15126    </varlistentry>
15127    <varlistentry>      <term>possible_crtcs</term>
15128      <listitem><para>
15129   bitmask of potential CRTC bindings
15130      </para></listitem>
15131    </varlistentry>
15132    <varlistentry>      <term>possible_clones</term>
15133      <listitem><para>
15134   bitmask of potential sibling encoders for cloning
15135      </para></listitem>
15136    </varlistentry>
15137    <varlistentry>      <term>crtc</term>
15138      <listitem><para>
15139   currently bound CRTC
15140      </para></listitem>
15141    </varlistentry>
15142    <varlistentry>      <term>bridge</term>
15143      <listitem><para>
15144   bridge associated to the encoder
15145      </para></listitem>
15146    </varlistentry>
15147    <varlistentry>      <term>funcs</term>
15148      <listitem><para>
15149   control functions
15150      </para></listitem>
15151    </varlistentry>
15152    <varlistentry>      <term>helper_private</term>
15153      <listitem><para>
15154   mid-layer private data
15155      </para></listitem>
15156    </varlistentry>
15157  </variablelist>
15158 </refsect1>
15159<refsect1>
15160<title>Description</title>
15161<para>
15162   CRTCs drive pixels to encoders, which convert them into signals
15163   appropriate for a given connector or set of connectors.
15164</para>
15165</refsect1>
15166</refentry>
15167
15168<refentry id="API-struct-drm-connector">
15169<refentryinfo>
15170 <title>LINUX</title>
15171 <productname>Kernel Hackers Manual</productname>
15172 <date>July 2017</date>
15173</refentryinfo>
15174<refmeta>
15175 <refentrytitle><phrase>struct drm_connector</phrase></refentrytitle>
15176 <manvolnum>9</manvolnum>
15177 <refmiscinfo class="version">4.1.27</refmiscinfo>
15178</refmeta>
15179<refnamediv>
15180 <refname>struct drm_connector</refname>
15181 <refpurpose>
15182     central DRM connector control structure
15183 </refpurpose>
15184</refnamediv>
15185<refsynopsisdiv>
15186 <title>Synopsis</title>
15187  <programlisting>
15188struct drm_connector {
15189  struct drm_device * dev;
15190  struct device * kdev;
15191  struct device_attribute * attr;
15192  struct list_head head;
15193  struct drm_mode_object base;
15194  char * name;
15195  int connector_type;
15196  int connector_type_id;
15197  bool interlace_allowed;
15198  bool doublescan_allowed;
15199  bool stereo_allowed;
15200  struct list_head modes;
15201  enum drm_connector_status status;
15202  struct list_head probed_modes;
15203  struct drm_display_info display_info;
15204  const struct drm_connector_funcs * funcs;
15205  struct drm_property_blob * edid_blob_ptr;
15206  struct drm_object_properties properties;
15207  struct drm_property_blob * path_blob_ptr;
15208  uint8_t polled;
15209  int dpms;
15210  const void * helper_private;
15211  struct drm_cmdline_mode cmdline_mode;
15212  enum drm_connector_force force;
15213  bool override_edid;
15214  uint32_t encoder_ids[DRM_CONNECTOR_MAX_ENCODER];
15215  struct drm_encoder * encoder;
15216  uint8_t eld[MAX_ELD_BYTES];
15217  bool dvi_dual;
15218  int max_tmds_clock;
15219  bool latency_present[2];
15220  int video_latency[2];
15221  int audio_latency[2];
15222  int null_edid_counter;
15223  unsigned bad_edid_counter;
15224  struct dentry * debugfs_entry;
15225  struct drm_connector_state * state;
15226  bool has_tile;
15227  struct drm_tile_group * tile_group;
15228  bool tile_is_single_monitor;
15229  uint8_t num_h_tile;
15230  uint8_t num_v_tile;
15231  uint8_t tile_h_loc;
15232  uint8_t tile_v_loc;
15233  uint16_t tile_h_size;
15234  uint16_t tile_v_size;
15235};  </programlisting>
15236</refsynopsisdiv>
15237 <refsect1>
15238  <title>Members</title>
15239  <variablelist>
15240    <varlistentry>      <term>dev</term>
15241      <listitem><para>
15242   parent DRM device
15243      </para></listitem>
15244    </varlistentry>
15245    <varlistentry>      <term>kdev</term>
15246      <listitem><para>
15247   kernel device for sysfs attributes
15248      </para></listitem>
15249    </varlistentry>
15250    <varlistentry>      <term>attr</term>
15251      <listitem><para>
15252   sysfs attributes
15253      </para></listitem>
15254    </varlistentry>
15255    <varlistentry>      <term>head</term>
15256      <listitem><para>
15257   list management
15258      </para></listitem>
15259    </varlistentry>
15260    <varlistentry>      <term>base</term>
15261      <listitem><para>
15262   base KMS object
15263      </para></listitem>
15264    </varlistentry>
15265    <varlistentry>      <term>name</term>
15266      <listitem><para>
15267   connector name
15268      </para></listitem>
15269    </varlistentry>
15270    <varlistentry>      <term>connector_type</term>
15271      <listitem><para>
15272   one of the <constant>DRM_MODE_CONNECTOR_</constant>&lt;foo&gt; types from drm_mode.h
15273      </para></listitem>
15274    </varlistentry>
15275    <varlistentry>      <term>connector_type_id</term>
15276      <listitem><para>
15277   index into connector type enum
15278      </para></listitem>
15279    </varlistentry>
15280    <varlistentry>      <term>interlace_allowed</term>
15281      <listitem><para>
15282   can this connector handle interlaced modes?
15283      </para></listitem>
15284    </varlistentry>
15285    <varlistentry>      <term>doublescan_allowed</term>
15286      <listitem><para>
15287   can this connector handle doublescan?
15288      </para></listitem>
15289    </varlistentry>
15290    <varlistentry>      <term>stereo_allowed</term>
15291      <listitem><para>
15292   can this connector handle stereo modes?
15293      </para></listitem>
15294    </varlistentry>
15295    <varlistentry>      <term>modes</term>
15296      <listitem><para>
15297   modes available on this connector (from <function>fill_modes</function> + user)
15298      </para></listitem>
15299    </varlistentry>
15300    <varlistentry>      <term>status</term>
15301      <listitem><para>
15302   one of the drm_connector_status enums (connected, not, or unknown)
15303      </para></listitem>
15304    </varlistentry>
15305    <varlistentry>      <term>probed_modes</term>
15306      <listitem><para>
15307   list of modes derived directly from the display
15308      </para></listitem>
15309    </varlistentry>
15310    <varlistentry>      <term>display_info</term>
15311      <listitem><para>
15312   information about attached display (e.g. from EDID)
15313      </para></listitem>
15314    </varlistentry>
15315    <varlistentry>      <term>funcs</term>
15316      <listitem><para>
15317   connector control functions
15318      </para></listitem>
15319    </varlistentry>
15320    <varlistentry>      <term>edid_blob_ptr</term>
15321      <listitem><para>
15322   DRM property containing EDID if present
15323      </para></listitem>
15324    </varlistentry>
15325    <varlistentry>      <term>properties</term>
15326      <listitem><para>
15327   property tracking for this connector
15328      </para></listitem>
15329    </varlistentry>
15330    <varlistentry>      <term>path_blob_ptr</term>
15331      <listitem><para>
15332   DRM blob property data for the DP MST path property
15333      </para></listitem>
15334    </varlistentry>
15335    <varlistentry>      <term>polled</term>
15336      <listitem><para>
15337   a <constant>DRM_CONNECTOR_POLL_</constant>&lt;foo&gt; value for core driven polling
15338      </para></listitem>
15339    </varlistentry>
15340    <varlistentry>      <term>dpms</term>
15341      <listitem><para>
15342   current dpms state
15343      </para></listitem>
15344    </varlistentry>
15345    <varlistentry>      <term>helper_private</term>
15346      <listitem><para>
15347   mid-layer private data
15348      </para></listitem>
15349    </varlistentry>
15350    <varlistentry>      <term>cmdline_mode</term>
15351      <listitem><para>
15352   mode line parsed from the kernel cmdline for this connector
15353      </para></listitem>
15354    </varlistentry>
15355    <varlistentry>      <term>force</term>
15356      <listitem><para>
15357   a <constant>DRM_FORCE_</constant>&lt;foo&gt; state for forced mode sets
15358      </para></listitem>
15359    </varlistentry>
15360    <varlistentry>      <term>override_edid</term>
15361      <listitem><para>
15362   has the EDID been overwritten through debugfs for testing?
15363      </para></listitem>
15364    </varlistentry>
15365    <varlistentry>      <term>encoder_ids[DRM_CONNECTOR_MAX_ENCODER]</term>
15366      <listitem><para>
15367   valid encoders for this connector
15368      </para></listitem>
15369    </varlistentry>
15370    <varlistentry>      <term>encoder</term>
15371      <listitem><para>
15372   encoder driving this connector, if any
15373      </para></listitem>
15374    </varlistentry>
15375    <varlistentry>      <term>eld[MAX_ELD_BYTES]</term>
15376      <listitem><para>
15377   EDID-like data, if present
15378      </para></listitem>
15379    </varlistentry>
15380    <varlistentry>      <term>dvi_dual</term>
15381      <listitem><para>
15382   dual link DVI, if found
15383      </para></listitem>
15384    </varlistentry>
15385    <varlistentry>      <term>max_tmds_clock</term>
15386      <listitem><para>
15387   max clock rate, if found
15388      </para></listitem>
15389    </varlistentry>
15390    <varlistentry>      <term>latency_present[2]</term>
15391      <listitem><para>
15392   AV delay info from ELD, if found
15393      </para></listitem>
15394    </varlistentry>
15395    <varlistentry>      <term>video_latency[2]</term>
15396      <listitem><para>
15397   video latency info from ELD, if found
15398      </para></listitem>
15399    </varlistentry>
15400    <varlistentry>      <term>audio_latency[2]</term>
15401      <listitem><para>
15402   audio latency info from ELD, if found
15403      </para></listitem>
15404    </varlistentry>
15405    <varlistentry>      <term>null_edid_counter</term>
15406      <listitem><para>
15407   track sinks that give us all zeros for the EDID
15408      </para></listitem>
15409    </varlistentry>
15410    <varlistentry>      <term>bad_edid_counter</term>
15411      <listitem><para>
15412   track sinks that give us an EDID with invalid checksum
15413      </para></listitem>
15414    </varlistentry>
15415    <varlistentry>      <term>debugfs_entry</term>
15416      <listitem><para>
15417   debugfs directory for this connector
15418      </para></listitem>
15419    </varlistentry>
15420    <varlistentry>      <term>state</term>
15421      <listitem><para>
15422   current atomic state for this connector
15423      </para></listitem>
15424    </varlistentry>
15425    <varlistentry>      <term>has_tile</term>
15426      <listitem><para>
15427   is this connector connected to a tiled monitor
15428      </para></listitem>
15429    </varlistentry>
15430    <varlistentry>      <term>tile_group</term>
15431      <listitem><para>
15432   tile group for the connected monitor
15433      </para></listitem>
15434    </varlistentry>
15435    <varlistentry>      <term>tile_is_single_monitor</term>
15436      <listitem><para>
15437   whether the tile is one monitor housing
15438      </para></listitem>
15439    </varlistentry>
15440    <varlistentry>      <term>num_h_tile</term>
15441      <listitem><para>
15442   number of horizontal tiles in the tile group
15443      </para></listitem>
15444    </varlistentry>
15445    <varlistentry>      <term>num_v_tile</term>
15446      <listitem><para>
15447   number of vertical tiles in the tile group
15448      </para></listitem>
15449    </varlistentry>
15450    <varlistentry>      <term>tile_h_loc</term>
15451      <listitem><para>
15452   horizontal location of this tile
15453      </para></listitem>
15454    </varlistentry>
15455    <varlistentry>      <term>tile_v_loc</term>
15456      <listitem><para>
15457   vertical location of this tile
15458      </para></listitem>
15459    </varlistentry>
15460    <varlistentry>      <term>tile_h_size</term>
15461      <listitem><para>
15462   horizontal size of this tile.
15463      </para></listitem>
15464    </varlistentry>
15465    <varlistentry>      <term>tile_v_size</term>
15466      <listitem><para>
15467   vertical size of this tile.
15468      </para></listitem>
15469    </varlistentry>
15470  </variablelist>
15471 </refsect1>
15472<refsect1>
15473<title>Description</title>
15474<para>
15475   Each connector may be connected to one or more CRTCs, or may be clonable by
15476   another connector if they can share a CRTC.  Each connector also has a specific
15477   position in the broader display (referred to as a 'screen' though it could
15478   span multiple monitors).
15479</para>
15480</refsect1>
15481</refentry>
15482
15483<refentry id="API-struct-drm-plane-state">
15484<refentryinfo>
15485 <title>LINUX</title>
15486 <productname>Kernel Hackers Manual</productname>
15487 <date>July 2017</date>
15488</refentryinfo>
15489<refmeta>
15490 <refentrytitle><phrase>struct drm_plane_state</phrase></refentrytitle>
15491 <manvolnum>9</manvolnum>
15492 <refmiscinfo class="version">4.1.27</refmiscinfo>
15493</refmeta>
15494<refnamediv>
15495 <refname>struct drm_plane_state</refname>
15496 <refpurpose>
15497     mutable plane state
15498 </refpurpose>
15499</refnamediv>
15500<refsynopsisdiv>
15501 <title>Synopsis</title>
15502  <programlisting>
15503struct drm_plane_state {
15504  struct drm_plane * plane;
15505  struct drm_crtc * crtc;
15506  struct drm_framebuffer * fb;
15507  struct fence * fence;
15508  int32_t crtc_x;
15509  int32_t crtc_y;
15510  uint32_t crtc_w;
15511  uint32_t crtc_h;
15512  uint32_t src_x;
15513  uint32_t src_y;
15514  uint32_t src_h;
15515  uint32_t src_w;
15516  struct drm_atomic_state * state;
15517};  </programlisting>
15518</refsynopsisdiv>
15519 <refsect1>
15520  <title>Members</title>
15521  <variablelist>
15522    <varlistentry>      <term>plane</term>
15523      <listitem><para>
15524   backpointer to the plane
15525      </para></listitem>
15526    </varlistentry>
15527    <varlistentry>      <term>crtc</term>
15528      <listitem><para>
15529   currently bound CRTC, NULL if disabled
15530      </para></listitem>
15531    </varlistentry>
15532    <varlistentry>      <term>fb</term>
15533      <listitem><para>
15534   currently bound framebuffer
15535      </para></listitem>
15536    </varlistentry>
15537    <varlistentry>      <term>fence</term>
15538      <listitem><para>
15539   optional fence to wait for before scanning out <parameter>fb</parameter>
15540      </para></listitem>
15541    </varlistentry>
15542    <varlistentry>      <term>crtc_x</term>
15543      <listitem><para>
15544   left position of visible portion of plane on crtc
15545      </para></listitem>
15546    </varlistentry>
15547    <varlistentry>      <term>crtc_y</term>
15548      <listitem><para>
15549   upper position of visible portion of plane on crtc
15550      </para></listitem>
15551    </varlistentry>
15552    <varlistentry>      <term>crtc_w</term>
15553      <listitem><para>
15554   width of visible portion of plane on crtc
15555      </para></listitem>
15556    </varlistentry>
15557    <varlistentry>      <term>crtc_h</term>
15558      <listitem><para>
15559   height of visible portion of plane on crtc
15560      </para></listitem>
15561    </varlistentry>
15562    <varlistentry>      <term>src_x</term>
15563      <listitem><para>
15564   left position of visible portion of plane within
15565   plane (in 16.16)
15566      </para></listitem>
15567    </varlistentry>
15568    <varlistentry>      <term>src_y</term>
15569      <listitem><para>
15570   upper position of visible portion of plane within
15571   plane (in 16.16)
15572      </para></listitem>
15573    </varlistentry>
15574    <varlistentry>      <term>src_h</term>
15575      <listitem><para>
15576   height of visible portion of plane (in 16.16)
15577      </para></listitem>
15578    </varlistentry>
15579    <varlistentry>      <term>src_w</term>
15580      <listitem><para>
15581   width of visible portion of plane (in 16.16)
15582      </para></listitem>
15583    </varlistentry>
15584    <varlistentry>      <term>state</term>
15585      <listitem><para>
15586   backpointer to global drm_atomic_state
15587      </para></listitem>
15588    </varlistentry>
15589  </variablelist>
15590 </refsect1>
15591</refentry>
15592
15593<refentry id="API-struct-drm-plane-funcs">
15594<refentryinfo>
15595 <title>LINUX</title>
15596 <productname>Kernel Hackers Manual</productname>
15597 <date>July 2017</date>
15598</refentryinfo>
15599<refmeta>
15600 <refentrytitle><phrase>struct drm_plane_funcs</phrase></refentrytitle>
15601 <manvolnum>9</manvolnum>
15602 <refmiscinfo class="version">4.1.27</refmiscinfo>
15603</refmeta>
15604<refnamediv>
15605 <refname>struct drm_plane_funcs</refname>
15606 <refpurpose>
15607     driver plane control functions
15608 </refpurpose>
15609</refnamediv>
15610<refsynopsisdiv>
15611 <title>Synopsis</title>
15612  <programlisting>
15613struct drm_plane_funcs {
15614  int (* update_plane) (struct drm_plane *plane,struct drm_crtc *crtc, struct drm_framebuffer *fb,int crtc_x, int crtc_y,unsigned int crtc_w, unsigned int crtc_h,uint32_t src_x, uint32_t src_y,uint32_t src_w, uint32_t src_h);
15615  int (* disable_plane) (struct drm_plane *plane);
15616  void (* destroy) (struct drm_plane *plane);
15617  void (* reset) (struct drm_plane *plane);
15618  int (* set_property) (struct drm_plane *plane,struct drm_property *property, uint64_t val);
15619  struct drm_plane_state *(* atomic_duplicate_state) (struct drm_plane *plane);
15620  void (* atomic_destroy_state) (struct drm_plane *plane,struct drm_plane_state *state);
15621  int (* atomic_set_property) (struct drm_plane *plane,struct drm_plane_state *state,struct drm_property *property,uint64_t val);
15622  int (* atomic_get_property) (struct drm_plane *plane,const struct drm_plane_state *state,struct drm_property *property,uint64_t *val);
15623};  </programlisting>
15624</refsynopsisdiv>
15625 <refsect1>
15626  <title>Members</title>
15627  <variablelist>
15628    <varlistentry>      <term>update_plane</term>
15629      <listitem><para>
15630   update the plane configuration
15631      </para></listitem>
15632    </varlistentry>
15633    <varlistentry>      <term>disable_plane</term>
15634      <listitem><para>
15635   shut down the plane
15636      </para></listitem>
15637    </varlistentry>
15638    <varlistentry>      <term>destroy</term>
15639      <listitem><para>
15640   clean up plane resources
15641      </para></listitem>
15642    </varlistentry>
15643    <varlistentry>      <term>reset</term>
15644      <listitem><para>
15645   reset plane after state has been invalidated (e.g. resume)
15646      </para></listitem>
15647    </varlistentry>
15648    <varlistentry>      <term>set_property</term>
15649      <listitem><para>
15650   called when a property is changed
15651      </para></listitem>
15652    </varlistentry>
15653    <varlistentry>      <term>atomic_duplicate_state</term>
15654      <listitem><para>
15655   duplicate the atomic state for this plane
15656      </para></listitem>
15657    </varlistentry>
15658    <varlistentry>      <term>atomic_destroy_state</term>
15659      <listitem><para>
15660   destroy an atomic state for this plane
15661      </para></listitem>
15662    </varlistentry>
15663    <varlistentry>      <term>atomic_set_property</term>
15664      <listitem><para>
15665   set a property on an atomic state for this plane
15666   (do not call directly, use <function>drm_atomic_plane_set_property</function>)
15667      </para></listitem>
15668    </varlistentry>
15669    <varlistentry>      <term>atomic_get_property</term>
15670      <listitem><para>
15671   get a property on an atomic state for this plane
15672   (do not call directly, use <function>drm_atomic_plane_get_property</function>)
15673      </para></listitem>
15674    </varlistentry>
15675  </variablelist>
15676 </refsect1>
15677</refentry>
15678
15679<refentry id="API-struct-drm-plane">
15680<refentryinfo>
15681 <title>LINUX</title>
15682 <productname>Kernel Hackers Manual</productname>
15683 <date>July 2017</date>
15684</refentryinfo>
15685<refmeta>
15686 <refentrytitle><phrase>struct drm_plane</phrase></refentrytitle>
15687 <manvolnum>9</manvolnum>
15688 <refmiscinfo class="version">4.1.27</refmiscinfo>
15689</refmeta>
15690<refnamediv>
15691 <refname>struct drm_plane</refname>
15692 <refpurpose>
15693     central DRM plane control structure
15694 </refpurpose>
15695</refnamediv>
15696<refsynopsisdiv>
15697 <title>Synopsis</title>
15698  <programlisting>
15699struct drm_plane {
15700  struct drm_device * dev;
15701  struct list_head head;
15702  struct drm_mode_object base;
15703  uint32_t possible_crtcs;
15704  uint32_t * format_types;
15705  uint32_t format_count;
15706  bool format_default;
15707  struct drm_crtc * crtc;
15708  struct drm_framebuffer * fb;
15709  struct drm_framebuffer * old_fb;
15710  const struct drm_plane_funcs * funcs;
15711  struct drm_object_properties properties;
15712  enum drm_plane_type type;
15713  struct drm_plane_state * state;
15714};  </programlisting>
15715</refsynopsisdiv>
15716 <refsect1>
15717  <title>Members</title>
15718  <variablelist>
15719    <varlistentry>      <term>dev</term>
15720      <listitem><para>
15721   DRM device this plane belongs to
15722      </para></listitem>
15723    </varlistentry>
15724    <varlistentry>      <term>head</term>
15725      <listitem><para>
15726   for list management
15727      </para></listitem>
15728    </varlistentry>
15729    <varlistentry>      <term>base</term>
15730      <listitem><para>
15731   base mode object
15732      </para></listitem>
15733    </varlistentry>
15734    <varlistentry>      <term>possible_crtcs</term>
15735      <listitem><para>
15736   pipes this plane can be bound to
15737      </para></listitem>
15738    </varlistentry>
15739    <varlistentry>      <term>format_types</term>
15740      <listitem><para>
15741   array of formats supported by this plane
15742      </para></listitem>
15743    </varlistentry>
15744    <varlistentry>      <term>format_count</term>
15745      <listitem><para>
15746   number of formats supported
15747      </para></listitem>
15748    </varlistentry>
15749    <varlistentry>      <term>format_default</term>
15750      <listitem><para>
15751   driver hasn't supplied supported formats for the plane
15752      </para></listitem>
15753    </varlistentry>
15754    <varlistentry>      <term>crtc</term>
15755      <listitem><para>
15756   currently bound CRTC
15757      </para></listitem>
15758    </varlistentry>
15759    <varlistentry>      <term>fb</term>
15760      <listitem><para>
15761   currently bound fb
15762      </para></listitem>
15763    </varlistentry>
15764    <varlistentry>      <term>old_fb</term>
15765      <listitem><para>
15766   Temporary tracking of the old fb while a modeset is ongoing. Used by
15767   <function>drm_mode_set_config_internal</function> to implement correct refcounting.
15768      </para></listitem>
15769    </varlistentry>
15770    <varlistentry>      <term>funcs</term>
15771      <listitem><para>
15772   helper functions
15773      </para></listitem>
15774    </varlistentry>
15775    <varlistentry>      <term>properties</term>
15776      <listitem><para>
15777   property tracking for this plane
15778      </para></listitem>
15779    </varlistentry>
15780    <varlistentry>      <term>type</term>
15781      <listitem><para>
15782   type of plane (overlay, primary, cursor)
15783      </para></listitem>
15784    </varlistentry>
15785    <varlistentry>      <term>state</term>
15786      <listitem><para>
15787   current atomic state for this plane
15788      </para></listitem>
15789    </varlistentry>
15790  </variablelist>
15791 </refsect1>
15792</refentry>
15793
15794<refentry id="API-struct-drm-bridge-funcs">
15795<refentryinfo>
15796 <title>LINUX</title>
15797 <productname>Kernel Hackers Manual</productname>
15798 <date>July 2017</date>
15799</refentryinfo>
15800<refmeta>
15801 <refentrytitle><phrase>struct drm_bridge_funcs</phrase></refentrytitle>
15802 <manvolnum>9</manvolnum>
15803 <refmiscinfo class="version">4.1.27</refmiscinfo>
15804</refmeta>
15805<refnamediv>
15806 <refname>struct drm_bridge_funcs</refname>
15807 <refpurpose>
15808     drm_bridge control functions
15809 </refpurpose>
15810</refnamediv>
15811<refsynopsisdiv>
15812 <title>Synopsis</title>
15813  <programlisting>
15814struct drm_bridge_funcs {
15815  int (* attach) (struct drm_bridge *bridge);
15816  bool (* mode_fixup) (struct drm_bridge *bridge,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
15817  void (* disable) (struct drm_bridge *bridge);
15818  void (* post_disable) (struct drm_bridge *bridge);
15819  void (* mode_set) (struct drm_bridge *bridge,struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
15820  void (* pre_enable) (struct drm_bridge *bridge);
15821  void (* enable) (struct drm_bridge *bridge);
15822};  </programlisting>
15823</refsynopsisdiv>
15824 <refsect1>
15825  <title>Members</title>
15826  <variablelist>
15827    <varlistentry>      <term>attach</term>
15828      <listitem><para>
15829   Called during drm_bridge_attach
15830      </para></listitem>
15831    </varlistentry>
15832    <varlistentry>      <term>mode_fixup</term>
15833      <listitem><para>
15834   Try to fixup (or reject entirely) proposed mode for this bridge
15835      </para></listitem>
15836    </varlistentry>
15837    <varlistentry>      <term>disable</term>
15838      <listitem><para>
15839   Called right before encoder prepare, disables the bridge
15840      </para></listitem>
15841    </varlistentry>
15842    <varlistentry>      <term>post_disable</term>
15843      <listitem><para>
15844   Called right after encoder prepare, for lockstepped disable
15845      </para></listitem>
15846    </varlistentry>
15847    <varlistentry>      <term>mode_set</term>
15848      <listitem><para>
15849   Set this mode to the bridge
15850      </para></listitem>
15851    </varlistentry>
15852    <varlistentry>      <term>pre_enable</term>
15853      <listitem><para>
15854   Called right before encoder commit, for lockstepped commit
15855      </para></listitem>
15856    </varlistentry>
15857    <varlistentry>      <term>enable</term>
15858      <listitem><para>
15859   Called right after encoder commit, enables the bridge
15860      </para></listitem>
15861    </varlistentry>
15862  </variablelist>
15863 </refsect1>
15864</refentry>
15865
15866<refentry id="API-struct-drm-bridge">
15867<refentryinfo>
15868 <title>LINUX</title>
15869 <productname>Kernel Hackers Manual</productname>
15870 <date>July 2017</date>
15871</refentryinfo>
15872<refmeta>
15873 <refentrytitle><phrase>struct drm_bridge</phrase></refentrytitle>
15874 <manvolnum>9</manvolnum>
15875 <refmiscinfo class="version">4.1.27</refmiscinfo>
15876</refmeta>
15877<refnamediv>
15878 <refname>struct drm_bridge</refname>
15879 <refpurpose>
15880     central DRM bridge control structure
15881 </refpurpose>
15882</refnamediv>
15883<refsynopsisdiv>
15884 <title>Synopsis</title>
15885  <programlisting>
15886struct drm_bridge {
15887  struct drm_device * dev;
15888#ifdef CONFIG_OF
15889  struct device_node * of_node;
15890#endif
15891  struct list_head list;
15892  const struct drm_bridge_funcs * funcs;
15893  void * driver_private;
15894};  </programlisting>
15895</refsynopsisdiv>
15896 <refsect1>
15897  <title>Members</title>
15898  <variablelist>
15899    <varlistentry>      <term>dev</term>
15900      <listitem><para>
15901   DRM device this bridge belongs to
15902      </para></listitem>
15903    </varlistentry>
15904    <varlistentry>      <term>of_node</term>
15905      <listitem><para>
15906   device node pointer to the bridge
15907      </para></listitem>
15908    </varlistentry>
15909    <varlistentry>      <term>list</term>
15910      <listitem><para>
15911   to keep track of all added bridges
15912      </para></listitem>
15913    </varlistentry>
15914    <varlistentry>      <term>funcs</term>
15915      <listitem><para>
15916   control functions
15917      </para></listitem>
15918    </varlistentry>
15919    <varlistentry>      <term>driver_private</term>
15920      <listitem><para>
15921   pointer to the bridge driver's internal context
15922      </para></listitem>
15923    </varlistentry>
15924  </variablelist>
15925 </refsect1>
15926</refentry>
15927
15928<refentry id="API-struct-drm-atomic-state">
15929<refentryinfo>
15930 <title>LINUX</title>
15931 <productname>Kernel Hackers Manual</productname>
15932 <date>July 2017</date>
15933</refentryinfo>
15934<refmeta>
15935 <refentrytitle><phrase>struct drm_atomic_state</phrase></refentrytitle>
15936 <manvolnum>9</manvolnum>
15937 <refmiscinfo class="version">4.1.27</refmiscinfo>
15938</refmeta>
15939<refnamediv>
15940 <refname>struct drm_atomic_state</refname>
15941 <refpurpose>
15942     the global state object for atomic updates
15943 </refpurpose>
15944</refnamediv>
15945<refsynopsisdiv>
15946 <title>Synopsis</title>
15947  <programlisting>
15948struct drm_atomic_state {
15949  struct drm_device * dev;
15950  bool allow_modeset:1;
15951  bool legacy_cursor_update:1;
15952  struct drm_plane ** planes;
15953  struct drm_plane_state ** plane_states;
15954  struct drm_crtc ** crtcs;
15955  struct drm_crtc_state ** crtc_states;
15956  int num_connector;
15957  struct drm_connector ** connectors;
15958  struct drm_connector_state ** connector_states;
15959  struct drm_modeset_acquire_ctx * acquire_ctx;
15960};  </programlisting>
15961</refsynopsisdiv>
15962 <refsect1>
15963  <title>Members</title>
15964  <variablelist>
15965    <varlistentry>      <term>dev</term>
15966      <listitem><para>
15967   parent DRM device
15968      </para></listitem>
15969    </varlistentry>
15970    <varlistentry>      <term>allow_modeset</term>
15971      <listitem><para>
15972   allow full modeset
15973      </para></listitem>
15974    </varlistentry>
15975    <varlistentry>      <term>legacy_cursor_update</term>
15976      <listitem><para>
15977   hint to enforce legacy cursor ioctl semantics
15978      </para></listitem>
15979    </varlistentry>
15980    <varlistentry>      <term>planes</term>
15981      <listitem><para>
15982   pointer to array of plane pointers
15983      </para></listitem>
15984    </varlistentry>
15985    <varlistentry>      <term>plane_states</term>
15986      <listitem><para>
15987   pointer to array of plane states pointers
15988      </para></listitem>
15989    </varlistentry>
15990    <varlistentry>      <term>crtcs</term>
15991      <listitem><para>
15992   pointer to array of CRTC pointers
15993      </para></listitem>
15994    </varlistentry>
15995    <varlistentry>      <term>crtc_states</term>
15996      <listitem><para>
15997   pointer to array of CRTC states pointers
15998      </para></listitem>
15999    </varlistentry>
16000    <varlistentry>      <term>num_connector</term>
16001      <listitem><para>
16002   size of the <parameter>connectors</parameter> and <parameter>connector_states</parameter> arrays
16003      </para></listitem>
16004    </varlistentry>
16005    <varlistentry>      <term>connectors</term>
16006      <listitem><para>
16007   pointer to array of connector pointers
16008      </para></listitem>
16009    </varlistentry>
16010    <varlistentry>      <term>connector_states</term>
16011      <listitem><para>
16012   pointer to array of connector states pointers
16013      </para></listitem>
16014    </varlistentry>
16015    <varlistentry>      <term>acquire_ctx</term>
16016      <listitem><para>
16017   acquire context for this atomic modeset state update
16018      </para></listitem>
16019    </varlistentry>
16020  </variablelist>
16021 </refsect1>
16022</refentry>
16023
16024<refentry id="API-struct-drm-mode-set">
16025<refentryinfo>
16026 <title>LINUX</title>
16027 <productname>Kernel Hackers Manual</productname>
16028 <date>July 2017</date>
16029</refentryinfo>
16030<refmeta>
16031 <refentrytitle><phrase>struct drm_mode_set</phrase></refentrytitle>
16032 <manvolnum>9</manvolnum>
16033 <refmiscinfo class="version">4.1.27</refmiscinfo>
16034</refmeta>
16035<refnamediv>
16036 <refname>struct drm_mode_set</refname>
16037 <refpurpose>
16038     new values for a CRTC config change
16039 </refpurpose>
16040</refnamediv>
16041<refsynopsisdiv>
16042 <title>Synopsis</title>
16043  <programlisting>
16044struct drm_mode_set {
16045  struct drm_framebuffer * fb;
16046  struct drm_crtc * crtc;
16047  struct drm_display_mode * mode;
16048  uint32_t x;
16049  uint32_t y;
16050  struct drm_connector ** connectors;
16051  size_t num_connectors;
16052};  </programlisting>
16053</refsynopsisdiv>
16054 <refsect1>
16055  <title>Members</title>
16056  <variablelist>
16057    <varlistentry>      <term>fb</term>
16058      <listitem><para>
16059   framebuffer to use for new config
16060      </para></listitem>
16061    </varlistentry>
16062    <varlistentry>      <term>crtc</term>
16063      <listitem><para>
16064   CRTC whose configuration we're about to change
16065      </para></listitem>
16066    </varlistentry>
16067    <varlistentry>      <term>mode</term>
16068      <listitem><para>
16069   mode timings to use
16070      </para></listitem>
16071    </varlistentry>
16072    <varlistentry>      <term>x</term>
16073      <listitem><para>
16074   position of this CRTC relative to <parameter>fb</parameter>
16075      </para></listitem>
16076    </varlistentry>
16077    <varlistentry>      <term>y</term>
16078      <listitem><para>
16079   position of this CRTC relative to <parameter>fb</parameter>
16080      </para></listitem>
16081    </varlistentry>
16082    <varlistentry>      <term>connectors</term>
16083      <listitem><para>
16084   array of connectors to drive with this CRTC if possible
16085      </para></listitem>
16086    </varlistentry>
16087    <varlistentry>      <term>num_connectors</term>
16088      <listitem><para>
16089   size of <parameter>connectors</parameter> array
16090      </para></listitem>
16091    </varlistentry>
16092  </variablelist>
16093 </refsect1>
16094<refsect1>
16095<title>Description</title>
16096<para>
16097   Represents a single crtc the connectors that it drives with what mode
16098   and from which framebuffer it scans out from.
16099   </para><para>
16100
16101   This is used to set modes.
16102</para>
16103</refsect1>
16104</refentry>
16105
16106<refentry id="API-struct-drm-mode-config-funcs">
16107<refentryinfo>
16108 <title>LINUX</title>
16109 <productname>Kernel Hackers Manual</productname>
16110 <date>July 2017</date>
16111</refentryinfo>
16112<refmeta>
16113 <refentrytitle><phrase>struct drm_mode_config_funcs</phrase></refentrytitle>
16114 <manvolnum>9</manvolnum>
16115 <refmiscinfo class="version">4.1.27</refmiscinfo>
16116</refmeta>
16117<refnamediv>
16118 <refname>struct drm_mode_config_funcs</refname>
16119 <refpurpose>
16120     basic driver provided mode setting functions
16121 </refpurpose>
16122</refnamediv>
16123<refsynopsisdiv>
16124 <title>Synopsis</title>
16125  <programlisting>
16126struct drm_mode_config_funcs {
16127  struct drm_framebuffer *(* fb_create) (struct drm_device *dev,struct drm_file *file_priv,struct drm_mode_fb_cmd2 *mode_cmd);
16128  void (* output_poll_changed) (struct drm_device *dev);
16129  int (* atomic_check) (struct drm_device *dev,struct drm_atomic_state *a);
16130  int (* atomic_commit) (struct drm_device *dev,struct drm_atomic_state *a,bool async);
16131};  </programlisting>
16132</refsynopsisdiv>
16133 <refsect1>
16134  <title>Members</title>
16135  <variablelist>
16136    <varlistentry>      <term>fb_create</term>
16137      <listitem><para>
16138   create a new framebuffer object
16139      </para></listitem>
16140    </varlistentry>
16141    <varlistentry>      <term>output_poll_changed</term>
16142      <listitem><para>
16143   function to handle output configuration changes
16144      </para></listitem>
16145    </varlistentry>
16146    <varlistentry>      <term>atomic_check</term>
16147      <listitem><para>
16148   check whether a given atomic state update is possible
16149      </para></listitem>
16150    </varlistentry>
16151    <varlistentry>      <term>atomic_commit</term>
16152      <listitem><para>
16153   commit an atomic state update previously verified with
16154   <function>atomic_check</function>
16155      </para></listitem>
16156    </varlistentry>
16157  </variablelist>
16158 </refsect1>
16159<refsect1>
16160<title>Description</title>
16161<para>
16162   Some global (i.e. not per-CRTC, connector, etc) mode setting functions that
16163   involve drivers.
16164</para>
16165</refsect1>
16166</refentry>
16167
16168<refentry id="API-struct-drm-mode-group">
16169<refentryinfo>
16170 <title>LINUX</title>
16171 <productname>Kernel Hackers Manual</productname>
16172 <date>July 2017</date>
16173</refentryinfo>
16174<refmeta>
16175 <refentrytitle><phrase>struct drm_mode_group</phrase></refentrytitle>
16176 <manvolnum>9</manvolnum>
16177 <refmiscinfo class="version">4.1.27</refmiscinfo>
16178</refmeta>
16179<refnamediv>
16180 <refname>struct drm_mode_group</refname>
16181 <refpurpose>
16182     group of mode setting resources for potential sub-grouping
16183 </refpurpose>
16184</refnamediv>
16185<refsynopsisdiv>
16186 <title>Synopsis</title>
16187  <programlisting>
16188struct drm_mode_group {
16189  uint32_t num_crtcs;
16190  uint32_t num_encoders;
16191  uint32_t num_connectors;
16192  uint32_t * id_list;
16193};  </programlisting>
16194</refsynopsisdiv>
16195 <refsect1>
16196  <title>Members</title>
16197  <variablelist>
16198    <varlistentry>      <term>num_crtcs</term>
16199      <listitem><para>
16200   CRTC count
16201      </para></listitem>
16202    </varlistentry>
16203    <varlistentry>      <term>num_encoders</term>
16204      <listitem><para>
16205   encoder count
16206      </para></listitem>
16207    </varlistentry>
16208    <varlistentry>      <term>num_connectors</term>
16209      <listitem><para>
16210   connector count
16211      </para></listitem>
16212    </varlistentry>
16213    <varlistentry>      <term>id_list</term>
16214      <listitem><para>
16215   list of KMS object IDs in this group
16216      </para></listitem>
16217    </varlistentry>
16218  </variablelist>
16219 </refsect1>
16220<refsect1>
16221<title>Description</title>
16222<para>
16223   Currently this simply tracks the global mode setting state.  But in the
16224   future it could allow groups of objects to be set aside into independent
16225   control groups for use by different user level processes (e.g. two X servers
16226   running simultaneously on different heads, each with their own mode
16227   configuration and freedom of mode setting).
16228</para>
16229</refsect1>
16230</refentry>
16231
16232<refentry id="API-struct-drm-mode-config">
16233<refentryinfo>
16234 <title>LINUX</title>
16235 <productname>Kernel Hackers Manual</productname>
16236 <date>July 2017</date>
16237</refentryinfo>
16238<refmeta>
16239 <refentrytitle><phrase>struct drm_mode_config</phrase></refentrytitle>
16240 <manvolnum>9</manvolnum>
16241 <refmiscinfo class="version">4.1.27</refmiscinfo>
16242</refmeta>
16243<refnamediv>
16244 <refname>struct drm_mode_config</refname>
16245 <refpurpose>
16246     Mode configuration control structure
16247 </refpurpose>
16248</refnamediv>
16249<refsynopsisdiv>
16250 <title>Synopsis</title>
16251  <programlisting>
16252struct drm_mode_config {
16253  struct mutex mutex;
16254  struct drm_modeset_lock connection_mutex;
16255  struct drm_modeset_acquire_ctx * acquire_ctx;
16256  struct mutex idr_mutex;
16257  struct idr crtc_idr;
16258  struct mutex fb_lock;
16259  int num_fb;
16260  struct list_head fb_list;
16261  int num_connector;
16262  struct list_head connector_list;
16263  int num_encoder;
16264  struct list_head encoder_list;
16265  int num_overlay_plane;
16266  int num_total_plane;
16267  struct list_head plane_list;
16268  int num_crtc;
16269  struct list_head crtc_list;
16270  struct list_head property_list;
16271  int min_width;
16272  int min_height;
16273  int max_width;
16274  int max_height;
16275  const struct drm_mode_config_funcs * funcs;
16276  resource_size_t fb_base;
16277  bool poll_enabled;
16278  bool poll_running;
16279  struct delayed_work output_poll_work;
16280  struct list_head property_blob_list;
16281  uint32_t preferred_depth;
16282  uint32_t prefer_shadow;
16283  bool async_page_flip;
16284  uint32_t cursor_width;
16285  uint32_t cursor_height;
16286};  </programlisting>
16287</refsynopsisdiv>
16288 <refsect1>
16289  <title>Members</title>
16290  <variablelist>
16291    <varlistentry>      <term>mutex</term>
16292      <listitem><para>
16293   mutex protecting KMS related lists and structures
16294      </para></listitem>
16295    </varlistentry>
16296    <varlistentry>      <term>connection_mutex</term>
16297      <listitem><para>
16298   ww mutex protecting connector state and routing
16299      </para></listitem>
16300    </varlistentry>
16301    <varlistentry>      <term>acquire_ctx</term>
16302      <listitem><para>
16303   global implicit acquire context used by atomic drivers for
16304   legacy ioctls
16305      </para></listitem>
16306    </varlistentry>
16307    <varlistentry>      <term>idr_mutex</term>
16308      <listitem><para>
16309   mutex for KMS ID allocation and management
16310      </para></listitem>
16311    </varlistentry>
16312    <varlistentry>      <term>crtc_idr</term>
16313      <listitem><para>
16314   main KMS ID tracking object
16315      </para></listitem>
16316    </varlistentry>
16317    <varlistentry>      <term>fb_lock</term>
16318      <listitem><para>
16319   mutex to protect fb state and lists
16320      </para></listitem>
16321    </varlistentry>
16322    <varlistentry>      <term>num_fb</term>
16323      <listitem><para>
16324   number of fbs available
16325      </para></listitem>
16326    </varlistentry>
16327    <varlistentry>      <term>fb_list</term>
16328      <listitem><para>
16329   list of framebuffers available
16330      </para></listitem>
16331    </varlistentry>
16332    <varlistentry>      <term>num_connector</term>
16333      <listitem><para>
16334   number of connectors on this device
16335      </para></listitem>
16336    </varlistentry>
16337    <varlistentry>      <term>connector_list</term>
16338      <listitem><para>
16339   list of connector objects
16340      </para></listitem>
16341    </varlistentry>
16342    <varlistentry>      <term>num_encoder</term>
16343      <listitem><para>
16344   number of encoders on this device
16345      </para></listitem>
16346    </varlistentry>
16347    <varlistentry>      <term>encoder_list</term>
16348      <listitem><para>
16349   list of encoder objects
16350      </para></listitem>
16351    </varlistentry>
16352    <varlistentry>      <term>num_overlay_plane</term>
16353      <listitem><para>
16354   number of overlay planes on this device
16355      </para></listitem>
16356    </varlistentry>
16357    <varlistentry>      <term>num_total_plane</term>
16358      <listitem><para>
16359   number of universal (i.e. with primary/curso) planes on this device
16360      </para></listitem>
16361    </varlistentry>
16362    <varlistentry>      <term>plane_list</term>
16363      <listitem><para>
16364   list of plane objects
16365      </para></listitem>
16366    </varlistentry>
16367    <varlistentry>      <term>num_crtc</term>
16368      <listitem><para>
16369   number of CRTCs on this device
16370      </para></listitem>
16371    </varlistentry>
16372    <varlistentry>      <term>crtc_list</term>
16373      <listitem><para>
16374   list of CRTC objects
16375      </para></listitem>
16376    </varlistentry>
16377    <varlistentry>      <term>property_list</term>
16378      <listitem><para>
16379   list of property objects
16380      </para></listitem>
16381    </varlistentry>
16382    <varlistentry>      <term>min_width</term>
16383      <listitem><para>
16384   minimum pixel width on this device
16385      </para></listitem>
16386    </varlistentry>
16387    <varlistentry>      <term>min_height</term>
16388      <listitem><para>
16389   minimum pixel height on this device
16390      </para></listitem>
16391    </varlistentry>
16392    <varlistentry>      <term>max_width</term>
16393      <listitem><para>
16394   maximum pixel width on this device
16395      </para></listitem>
16396    </varlistentry>
16397    <varlistentry>      <term>max_height</term>
16398      <listitem><para>
16399   maximum pixel height on this device
16400      </para></listitem>
16401    </varlistentry>
16402    <varlistentry>      <term>funcs</term>
16403      <listitem><para>
16404   core driver provided mode setting functions
16405      </para></listitem>
16406    </varlistentry>
16407    <varlistentry>      <term>fb_base</term>
16408      <listitem><para>
16409   base address of the framebuffer
16410      </para></listitem>
16411    </varlistentry>
16412    <varlistentry>      <term>poll_enabled</term>
16413      <listitem><para>
16414   track polling support for this device
16415      </para></listitem>
16416    </varlistentry>
16417    <varlistentry>      <term>poll_running</term>
16418      <listitem><para>
16419   track polling status for this device
16420      </para></listitem>
16421    </varlistentry>
16422    <varlistentry>      <term>output_poll_work</term>
16423      <listitem><para>
16424   delayed work for polling in process context
16425      </para></listitem>
16426    </varlistentry>
16427    <varlistentry>      <term>property_blob_list</term>
16428      <listitem><para>
16429   list of all the blob property objects
16430      </para></listitem>
16431    </varlistentry>
16432    <varlistentry>      <term>preferred_depth</term>
16433      <listitem><para>
16434   preferred RBG pixel depth, used by fb helpers
16435      </para></listitem>
16436    </varlistentry>
16437    <varlistentry>      <term>prefer_shadow</term>
16438      <listitem><para>
16439   hint to userspace to prefer shadow-fb rendering
16440      </para></listitem>
16441    </varlistentry>
16442    <varlistentry>      <term>async_page_flip</term>
16443      <listitem><para>
16444   does this device support async flips on the primary plane?
16445      </para></listitem>
16446    </varlistentry>
16447    <varlistentry>      <term>cursor_width</term>
16448      <listitem><para>
16449   hint to userspace for max cursor width
16450      </para></listitem>
16451    </varlistentry>
16452    <varlistentry>      <term>cursor_height</term>
16453      <listitem><para>
16454   hint to userspace for max cursor height
16455      </para></listitem>
16456    </varlistentry>
16457  </variablelist>
16458 </refsect1>
16459<refsect1>
16460<title>_property</title>
16461<para>
16462   core property tracking
16463</para>
16464</refsect1>
16465<refsect1>
16466<title>Description</title>
16467<para>
16468   Core mode resource tracking structure.  All CRTC, encoders, and connectors
16469   enumerated by the driver are added here, as are global properties.  Some
16470   global restrictions are also here, e.g. dimension restrictions.
16471</para>
16472</refsect1>
16473</refentry>
16474
16475<refentry id="API-drm-for-each-plane-mask">
16476<refentryinfo>
16477 <title>LINUX</title>
16478 <productname>Kernel Hackers Manual</productname>
16479 <date>July 2017</date>
16480</refentryinfo>
16481<refmeta>
16482 <refentrytitle><phrase>drm_for_each_plane_mask</phrase></refentrytitle>
16483 <manvolnum>9</manvolnum>
16484 <refmiscinfo class="version">4.1.27</refmiscinfo>
16485</refmeta>
16486<refnamediv>
16487 <refname>drm_for_each_plane_mask</refname>
16488 <refpurpose>
16489     iterate over planes specified by bitmask
16490 </refpurpose>
16491</refnamediv>
16492<refsynopsisdiv>
16493 <title>Synopsis</title>
16494  <funcsynopsis><funcprototype>
16495   <funcdef> <function>drm_for_each_plane_mask </function></funcdef>
16496   <paramdef> <parameter>plane</parameter></paramdef>
16497   <paramdef> <parameter>dev</parameter></paramdef>
16498   <paramdef> <parameter>plane_mask</parameter></paramdef>
16499  </funcprototype></funcsynopsis>
16500</refsynopsisdiv>
16501<refsect1>
16502 <title>Arguments</title>
16503 <variablelist>
16504  <varlistentry>
16505   <term><parameter>plane</parameter></term>
16506   <listitem>
16507    <para>
16508     the loop cursor
16509    </para>
16510   </listitem>
16511  </varlistentry>
16512  <varlistentry>
16513   <term><parameter>dev</parameter></term>
16514   <listitem>
16515    <para>
16516     the DRM device
16517    </para>
16518   </listitem>
16519  </varlistentry>
16520  <varlistentry>
16521   <term><parameter>plane_mask</parameter></term>
16522   <listitem>
16523    <para>
16524     bitmask of plane indices
16525    </para>
16526   </listitem>
16527  </varlistentry>
16528 </variablelist>
16529</refsect1>
16530<refsect1>
16531<title>Description</title>
16532<para>
16533   Iterate over all planes specified by bitmask.
16534</para>
16535</refsect1>
16536</refentry>
16537
16538<refentry id="API-drm-crtc-mask">
16539<refentryinfo>
16540 <title>LINUX</title>
16541 <productname>Kernel Hackers Manual</productname>
16542 <date>July 2017</date>
16543</refentryinfo>
16544<refmeta>
16545 <refentrytitle><phrase>drm_crtc_mask</phrase></refentrytitle>
16546 <manvolnum>9</manvolnum>
16547 <refmiscinfo class="version">4.1.27</refmiscinfo>
16548</refmeta>
16549<refnamediv>
16550 <refname>drm_crtc_mask</refname>
16551 <refpurpose>
16552     find the mask of a registered CRTC
16553 </refpurpose>
16554</refnamediv>
16555<refsynopsisdiv>
16556 <title>Synopsis</title>
16557  <funcsynopsis><funcprototype>
16558   <funcdef>uint32_t <function>drm_crtc_mask </function></funcdef>
16559   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
16560  </funcprototype></funcsynopsis>
16561</refsynopsisdiv>
16562<refsect1>
16563 <title>Arguments</title>
16564 <variablelist>
16565  <varlistentry>
16566   <term><parameter>crtc</parameter></term>
16567   <listitem>
16568    <para>
16569     CRTC to find mask for
16570    </para>
16571   </listitem>
16572  </varlistentry>
16573 </variablelist>
16574</refsect1>
16575<refsect1>
16576<title>Description</title>
16577<para>
16578   Given a registered CRTC, return the mask bit of that CRTC for an
16579   encoder's possible_crtcs field.
16580</para>
16581</refsect1>
16582</refentry>
16583
16584<refentry id="API-drm-encoder-crtc-ok">
16585<refentryinfo>
16586 <title>LINUX</title>
16587 <productname>Kernel Hackers Manual</productname>
16588 <date>July 2017</date>
16589</refentryinfo>
16590<refmeta>
16591 <refentrytitle><phrase>drm_encoder_crtc_ok</phrase></refentrytitle>
16592 <manvolnum>9</manvolnum>
16593 <refmiscinfo class="version">4.1.27</refmiscinfo>
16594</refmeta>
16595<refnamediv>
16596 <refname>drm_encoder_crtc_ok</refname>
16597 <refpurpose>
16598     can a given crtc drive a given encoder?
16599 </refpurpose>
16600</refnamediv>
16601<refsynopsisdiv>
16602 <title>Synopsis</title>
16603  <funcsynopsis><funcprototype>
16604   <funcdef>bool <function>drm_encoder_crtc_ok </function></funcdef>
16605   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
16606   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
16607  </funcprototype></funcsynopsis>
16608</refsynopsisdiv>
16609<refsect1>
16610 <title>Arguments</title>
16611 <variablelist>
16612  <varlistentry>
16613   <term><parameter>encoder</parameter></term>
16614   <listitem>
16615    <para>
16616     encoder to test
16617    </para>
16618   </listitem>
16619  </varlistentry>
16620  <varlistentry>
16621   <term><parameter>crtc</parameter></term>
16622   <listitem>
16623    <para>
16624     crtc to test
16625    </para>
16626   </listitem>
16627  </varlistentry>
16628 </variablelist>
16629</refsect1>
16630<refsect1>
16631<title>Description</title>
16632<para>
16633   Return false if <parameter>encoder</parameter> can't be driven by <parameter>crtc</parameter>, true otherwise.
16634</para>
16635</refsect1>
16636</refentry>
16637
16638    </sect2>
16639    <sect2>
16640      <title>KMS Locking</title>
16641<para>
16642   </para><para>
16643   As KMS moves toward more fine grained locking, and atomic ioctl where
16644   userspace can indirectly control locking order, it becomes necessary
16645   to use ww_mutex and acquire-contexts to avoid deadlocks.  But because
16646   the locking is more distributed around the driver code, we want a bit
16647   of extra utility/tracking out of our acquire-ctx.  This is provided
16648   by drm_modeset_lock / drm_modeset_acquire_ctx.
16649   </para><para>
16650   For basic principles of ww_mutex, see: Documentation/locking/ww-mutex-design.txt
16651   </para><para>
16652   The basic usage pattern is to:
16653   </para><para>
16654   drm_modeset_acquire_init(<structname>ctx</structname>)
16655   retry:
16656   foreach (lock in random_ordered_set_of_locks) {
16657   ret = drm_modeset_lock(lock, <structname>ctx</structname>)
16658   if (ret == -EDEADLK) {
16659   drm_modeset_backoff(<structname>ctx</structname>);
16660   goto retry;
16661   }
16662   }
16663   </para><para>
16664   ... do stuff ...
16665   </para><para>
16666   drm_modeset_drop_locks(<structname>ctx</structname>);
16667   drm_modeset_acquire_fini(<structname>ctx</structname>);
16668</para>
16669
16670<!-- include/drm/drm_modeset_lock.h -->
16671<refentry id="API-struct-drm-modeset-acquire-ctx">
16672<refentryinfo>
16673 <title>LINUX</title>
16674 <productname>Kernel Hackers Manual</productname>
16675 <date>July 2017</date>
16676</refentryinfo>
16677<refmeta>
16678 <refentrytitle><phrase>struct drm_modeset_acquire_ctx</phrase></refentrytitle>
16679 <manvolnum>9</manvolnum>
16680 <refmiscinfo class="version">4.1.27</refmiscinfo>
16681</refmeta>
16682<refnamediv>
16683 <refname>struct drm_modeset_acquire_ctx</refname>
16684 <refpurpose>
16685  locking context (see ww_acquire_ctx)
16686 </refpurpose>
16687</refnamediv>
16688<refsynopsisdiv>
16689 <title>Synopsis</title>
16690  <programlisting>
16691struct drm_modeset_acquire_ctx {
16692  struct ww_acquire_ctx ww_ctx;
16693  struct drm_modeset_lock * contended;
16694  struct list_head locked;
16695  bool trylock_only;
16696};  </programlisting>
16697</refsynopsisdiv>
16698 <refsect1>
16699  <title>Members</title>
16700  <variablelist>
16701    <varlistentry>      <term>ww_ctx</term>
16702      <listitem><para>
16703base acquire ctx
16704      </para></listitem>
16705    </varlistentry>
16706    <varlistentry>      <term>contended</term>
16707      <listitem><para>
16708used internally for -EDEADLK handling
16709      </para></listitem>
16710    </varlistentry>
16711    <varlistentry>      <term>locked</term>
16712      <listitem><para>
16713list of held locks
16714      </para></listitem>
16715    </varlistentry>
16716    <varlistentry>      <term>trylock_only</term>
16717      <listitem><para>
16718trylock mode used in atomic contexts/panic notifiers
16719      </para></listitem>
16720    </varlistentry>
16721  </variablelist>
16722 </refsect1>
16723<refsect1>
16724<title>Description</title>
16725<para>
16726   Each thread competing for a set of locks must use one acquire
16727   ctx.  And if any lock fxn returns -EDEADLK, it must backoff and
16728   retry.
16729</para>
16730</refsect1>
16731</refentry>
16732
16733<refentry id="API-drm-modeset-lock-init">
16734<refentryinfo>
16735 <title>LINUX</title>
16736 <productname>Kernel Hackers Manual</productname>
16737 <date>July 2017</date>
16738</refentryinfo>
16739<refmeta>
16740 <refentrytitle><phrase>drm_modeset_lock_init</phrase></refentrytitle>
16741 <manvolnum>9</manvolnum>
16742 <refmiscinfo class="version">4.1.27</refmiscinfo>
16743</refmeta>
16744<refnamediv>
16745 <refname>drm_modeset_lock_init</refname>
16746 <refpurpose>
16747     initialize lock
16748 </refpurpose>
16749</refnamediv>
16750<refsynopsisdiv>
16751 <title>Synopsis</title>
16752  <funcsynopsis><funcprototype>
16753   <funcdef>void <function>drm_modeset_lock_init </function></funcdef>
16754   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
16755  </funcprototype></funcsynopsis>
16756</refsynopsisdiv>
16757<refsect1>
16758 <title>Arguments</title>
16759 <variablelist>
16760  <varlistentry>
16761   <term><parameter>lock</parameter></term>
16762   <listitem>
16763    <para>
16764     lock to init
16765    </para>
16766   </listitem>
16767  </varlistentry>
16768 </variablelist>
16769</refsect1>
16770</refentry>
16771
16772<refentry id="API-drm-modeset-lock-fini">
16773<refentryinfo>
16774 <title>LINUX</title>
16775 <productname>Kernel Hackers Manual</productname>
16776 <date>July 2017</date>
16777</refentryinfo>
16778<refmeta>
16779 <refentrytitle><phrase>drm_modeset_lock_fini</phrase></refentrytitle>
16780 <manvolnum>9</manvolnum>
16781 <refmiscinfo class="version">4.1.27</refmiscinfo>
16782</refmeta>
16783<refnamediv>
16784 <refname>drm_modeset_lock_fini</refname>
16785 <refpurpose>
16786     cleanup lock
16787 </refpurpose>
16788</refnamediv>
16789<refsynopsisdiv>
16790 <title>Synopsis</title>
16791  <funcsynopsis><funcprototype>
16792   <funcdef>void <function>drm_modeset_lock_fini </function></funcdef>
16793   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
16794  </funcprototype></funcsynopsis>
16795</refsynopsisdiv>
16796<refsect1>
16797 <title>Arguments</title>
16798 <variablelist>
16799  <varlistentry>
16800   <term><parameter>lock</parameter></term>
16801   <listitem>
16802    <para>
16803     lock to cleanup
16804    </para>
16805   </listitem>
16806  </varlistentry>
16807 </variablelist>
16808</refsect1>
16809</refentry>
16810
16811<refentry id="API-drm-modeset-is-locked">
16812<refentryinfo>
16813 <title>LINUX</title>
16814 <productname>Kernel Hackers Manual</productname>
16815 <date>July 2017</date>
16816</refentryinfo>
16817<refmeta>
16818 <refentrytitle><phrase>drm_modeset_is_locked</phrase></refentrytitle>
16819 <manvolnum>9</manvolnum>
16820 <refmiscinfo class="version">4.1.27</refmiscinfo>
16821</refmeta>
16822<refnamediv>
16823 <refname>drm_modeset_is_locked</refname>
16824 <refpurpose>
16825     equivalent to <function>mutex_is_locked</function>
16826 </refpurpose>
16827</refnamediv>
16828<refsynopsisdiv>
16829 <title>Synopsis</title>
16830  <funcsynopsis><funcprototype>
16831   <funcdef>bool <function>drm_modeset_is_locked </function></funcdef>
16832   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
16833  </funcprototype></funcsynopsis>
16834</refsynopsisdiv>
16835<refsect1>
16836 <title>Arguments</title>
16837 <variablelist>
16838  <varlistentry>
16839   <term><parameter>lock</parameter></term>
16840   <listitem>
16841    <para>
16842     lock to check
16843    </para>
16844   </listitem>
16845  </varlistentry>
16846 </variablelist>
16847</refsect1>
16848</refentry>
16849
16850<!-- drivers/gpu/drm/drm_modeset_lock.c -->
16851<refentry id="API---drm-modeset-lock-all">
16852<refentryinfo>
16853 <title>LINUX</title>
16854 <productname>Kernel Hackers Manual</productname>
16855 <date>July 2017</date>
16856</refentryinfo>
16857<refmeta>
16858 <refentrytitle><phrase>__drm_modeset_lock_all</phrase></refentrytitle>
16859 <manvolnum>9</manvolnum>
16860 <refmiscinfo class="version">4.1.27</refmiscinfo>
16861</refmeta>
16862<refnamediv>
16863 <refname>__drm_modeset_lock_all</refname>
16864 <refpurpose>
16865  internal helper to grab all modeset locks
16866 </refpurpose>
16867</refnamediv>
16868<refsynopsisdiv>
16869 <title>Synopsis</title>
16870  <funcsynopsis><funcprototype>
16871   <funcdef>int <function>__drm_modeset_lock_all </function></funcdef>
16872   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
16873   <paramdef>bool <parameter>trylock</parameter></paramdef>
16874  </funcprototype></funcsynopsis>
16875</refsynopsisdiv>
16876<refsect1>
16877 <title>Arguments</title>
16878 <variablelist>
16879  <varlistentry>
16880   <term><parameter>dev</parameter></term>
16881   <listitem>
16882    <para>
16883     DRM device
16884    </para>
16885   </listitem>
16886  </varlistentry>
16887  <varlistentry>
16888   <term><parameter>trylock</parameter></term>
16889   <listitem>
16890    <para>
16891     trylock mode for atomic contexts
16892    </para>
16893   </listitem>
16894  </varlistentry>
16895 </variablelist>
16896</refsect1>
16897<refsect1>
16898<title>Description</title>
16899<para>
16900   This is a special version of <function>drm_modeset_lock_all</function> which can also be used in
16901   atomic contexts. Then <parameter>trylock</parameter> must be set to true.
16902</para>
16903</refsect1>
16904<refsect1>
16905<title>Returns</title>
16906<para>
16907   0 on success or negative error code on failure.
16908</para>
16909</refsect1>
16910</refentry>
16911
16912<refentry id="API-drm-modeset-lock-all">
16913<refentryinfo>
16914 <title>LINUX</title>
16915 <productname>Kernel Hackers Manual</productname>
16916 <date>July 2017</date>
16917</refentryinfo>
16918<refmeta>
16919 <refentrytitle><phrase>drm_modeset_lock_all</phrase></refentrytitle>
16920 <manvolnum>9</manvolnum>
16921 <refmiscinfo class="version">4.1.27</refmiscinfo>
16922</refmeta>
16923<refnamediv>
16924 <refname>drm_modeset_lock_all</refname>
16925 <refpurpose>
16926     take all modeset locks
16927 </refpurpose>
16928</refnamediv>
16929<refsynopsisdiv>
16930 <title>Synopsis</title>
16931  <funcsynopsis><funcprototype>
16932   <funcdef>void <function>drm_modeset_lock_all </function></funcdef>
16933   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
16934  </funcprototype></funcsynopsis>
16935</refsynopsisdiv>
16936<refsect1>
16937 <title>Arguments</title>
16938 <variablelist>
16939  <varlistentry>
16940   <term><parameter>dev</parameter></term>
16941   <listitem>
16942    <para>
16943     drm device
16944    </para>
16945   </listitem>
16946  </varlistentry>
16947 </variablelist>
16948</refsect1>
16949<refsect1>
16950<title>Description</title>
16951<para>
16952   This function takes all modeset locks, suitable where a more fine-grained
16953   scheme isn't (yet) implemented. Locks must be dropped with
16954   drm_modeset_unlock_all.
16955</para>
16956</refsect1>
16957</refentry>
16958
16959<refentry id="API-drm-modeset-unlock-all">
16960<refentryinfo>
16961 <title>LINUX</title>
16962 <productname>Kernel Hackers Manual</productname>
16963 <date>July 2017</date>
16964</refentryinfo>
16965<refmeta>
16966 <refentrytitle><phrase>drm_modeset_unlock_all</phrase></refentrytitle>
16967 <manvolnum>9</manvolnum>
16968 <refmiscinfo class="version">4.1.27</refmiscinfo>
16969</refmeta>
16970<refnamediv>
16971 <refname>drm_modeset_unlock_all</refname>
16972 <refpurpose>
16973     drop all modeset locks
16974 </refpurpose>
16975</refnamediv>
16976<refsynopsisdiv>
16977 <title>Synopsis</title>
16978  <funcsynopsis><funcprototype>
16979   <funcdef>void <function>drm_modeset_unlock_all </function></funcdef>
16980   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
16981  </funcprototype></funcsynopsis>
16982</refsynopsisdiv>
16983<refsect1>
16984 <title>Arguments</title>
16985 <variablelist>
16986  <varlistentry>
16987   <term><parameter>dev</parameter></term>
16988   <listitem>
16989    <para>
16990     device
16991    </para>
16992   </listitem>
16993  </varlistentry>
16994 </variablelist>
16995</refsect1>
16996<refsect1>
16997<title>Description</title>
16998<para>
16999   This function drop all modeset locks taken by drm_modeset_lock_all.
17000</para>
17001</refsect1>
17002</refentry>
17003
17004<refentry id="API-drm-modeset-lock-crtc">
17005<refentryinfo>
17006 <title>LINUX</title>
17007 <productname>Kernel Hackers Manual</productname>
17008 <date>July 2017</date>
17009</refentryinfo>
17010<refmeta>
17011 <refentrytitle><phrase>drm_modeset_lock_crtc</phrase></refentrytitle>
17012 <manvolnum>9</manvolnum>
17013 <refmiscinfo class="version">4.1.27</refmiscinfo>
17014</refmeta>
17015<refnamediv>
17016 <refname>drm_modeset_lock_crtc</refname>
17017 <refpurpose>
17018     lock crtc with hidden acquire ctx for a plane update
17019 </refpurpose>
17020</refnamediv>
17021<refsynopsisdiv>
17022 <title>Synopsis</title>
17023  <funcsynopsis><funcprototype>
17024   <funcdef>void <function>drm_modeset_lock_crtc </function></funcdef>
17025   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
17026   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
17027  </funcprototype></funcsynopsis>
17028</refsynopsisdiv>
17029<refsect1>
17030 <title>Arguments</title>
17031 <variablelist>
17032  <varlistentry>
17033   <term><parameter>crtc</parameter></term>
17034   <listitem>
17035    <para>
17036     DRM CRTC
17037    </para>
17038   </listitem>
17039  </varlistentry>
17040  <varlistentry>
17041   <term><parameter>plane</parameter></term>
17042   <listitem>
17043    <para>
17044     DRM plane to be updated on <parameter>crtc</parameter>
17045    </para>
17046   </listitem>
17047  </varlistentry>
17048 </variablelist>
17049</refsect1>
17050<refsect1>
17051<title>Description</title>
17052<para>
17053   This function locks the given crtc and plane (which should be either the
17054   primary or cursor plane) using a hidden acquire context. This is necessary so
17055   that drivers internally using the atomic interfaces can grab further locks
17056   with the lock acquire context.
17057   </para><para>
17058
17059   Note that <parameter>plane</parameter> can be NULL, e.g. when the cursor support hasn't yet been
17060   converted to universal planes yet.
17061</para>
17062</refsect1>
17063</refentry>
17064
17065<refentry id="API-drm-modeset-legacy-acquire-ctx">
17066<refentryinfo>
17067 <title>LINUX</title>
17068 <productname>Kernel Hackers Manual</productname>
17069 <date>July 2017</date>
17070</refentryinfo>
17071<refmeta>
17072 <refentrytitle><phrase>drm_modeset_legacy_acquire_ctx</phrase></refentrytitle>
17073 <manvolnum>9</manvolnum>
17074 <refmiscinfo class="version">4.1.27</refmiscinfo>
17075</refmeta>
17076<refnamediv>
17077 <refname>drm_modeset_legacy_acquire_ctx</refname>
17078 <refpurpose>
17079     find acquire ctx for legacy ioctls
17080 </refpurpose>
17081</refnamediv>
17082<refsynopsisdiv>
17083 <title>Synopsis</title>
17084  <funcsynopsis><funcprototype>
17085   <funcdef>struct drm_modeset_acquire_ctx * <function>drm_modeset_legacy_acquire_ctx </function></funcdef>
17086   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
17087  </funcprototype></funcsynopsis>
17088</refsynopsisdiv>
17089<refsect1>
17090 <title>Arguments</title>
17091 <variablelist>
17092  <varlistentry>
17093   <term><parameter>crtc</parameter></term>
17094   <listitem>
17095    <para>
17096     drm crtc
17097    </para>
17098   </listitem>
17099  </varlistentry>
17100 </variablelist>
17101</refsect1>
17102<refsect1>
17103<title>Description</title>
17104<para>
17105   Legacy ioctl operations like cursor updates or page flips only have per-crtc
17106   locking, and store the acquire ctx in the corresponding crtc. All other
17107   legacy operations take all locks and use a global acquire context. This
17108   function grabs the right one.
17109</para>
17110</refsect1>
17111</refentry>
17112
17113<refentry id="API-drm-modeset-unlock-crtc">
17114<refentryinfo>
17115 <title>LINUX</title>
17116 <productname>Kernel Hackers Manual</productname>
17117 <date>July 2017</date>
17118</refentryinfo>
17119<refmeta>
17120 <refentrytitle><phrase>drm_modeset_unlock_crtc</phrase></refentrytitle>
17121 <manvolnum>9</manvolnum>
17122 <refmiscinfo class="version">4.1.27</refmiscinfo>
17123</refmeta>
17124<refnamediv>
17125 <refname>drm_modeset_unlock_crtc</refname>
17126 <refpurpose>
17127     drop crtc lock
17128 </refpurpose>
17129</refnamediv>
17130<refsynopsisdiv>
17131 <title>Synopsis</title>
17132  <funcsynopsis><funcprototype>
17133   <funcdef>void <function>drm_modeset_unlock_crtc </function></funcdef>
17134   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
17135  </funcprototype></funcsynopsis>
17136</refsynopsisdiv>
17137<refsect1>
17138 <title>Arguments</title>
17139 <variablelist>
17140  <varlistentry>
17141   <term><parameter>crtc</parameter></term>
17142   <listitem>
17143    <para>
17144     drm crtc
17145    </para>
17146   </listitem>
17147  </varlistentry>
17148 </variablelist>
17149</refsect1>
17150<refsect1>
17151<title>Description</title>
17152<para>
17153   This drops the crtc lock acquire with <function>drm_modeset_lock_crtc</function> and all other
17154   locks acquired through the hidden context.
17155</para>
17156</refsect1>
17157</refentry>
17158
17159<refentry id="API-drm-warn-on-modeset-not-all-locked">
17160<refentryinfo>
17161 <title>LINUX</title>
17162 <productname>Kernel Hackers Manual</productname>
17163 <date>July 2017</date>
17164</refentryinfo>
17165<refmeta>
17166 <refentrytitle><phrase>drm_warn_on_modeset_not_all_locked</phrase></refentrytitle>
17167 <manvolnum>9</manvolnum>
17168 <refmiscinfo class="version">4.1.27</refmiscinfo>
17169</refmeta>
17170<refnamediv>
17171 <refname>drm_warn_on_modeset_not_all_locked</refname>
17172 <refpurpose>
17173     check that all modeset locks are locked
17174 </refpurpose>
17175</refnamediv>
17176<refsynopsisdiv>
17177 <title>Synopsis</title>
17178  <funcsynopsis><funcprototype>
17179   <funcdef>void <function>drm_warn_on_modeset_not_all_locked </function></funcdef>
17180   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
17181  </funcprototype></funcsynopsis>
17182</refsynopsisdiv>
17183<refsect1>
17184 <title>Arguments</title>
17185 <variablelist>
17186  <varlistentry>
17187   <term><parameter>dev</parameter></term>
17188   <listitem>
17189    <para>
17190     device
17191    </para>
17192   </listitem>
17193  </varlistentry>
17194 </variablelist>
17195</refsect1>
17196<refsect1>
17197<title>Description</title>
17198<para>
17199   Useful as a debug assert.
17200</para>
17201</refsect1>
17202</refentry>
17203
17204<refentry id="API-drm-modeset-acquire-init">
17205<refentryinfo>
17206 <title>LINUX</title>
17207 <productname>Kernel Hackers Manual</productname>
17208 <date>July 2017</date>
17209</refentryinfo>
17210<refmeta>
17211 <refentrytitle><phrase>drm_modeset_acquire_init</phrase></refentrytitle>
17212 <manvolnum>9</manvolnum>
17213 <refmiscinfo class="version">4.1.27</refmiscinfo>
17214</refmeta>
17215<refnamediv>
17216 <refname>drm_modeset_acquire_init</refname>
17217 <refpurpose>
17218     initialize acquire context
17219 </refpurpose>
17220</refnamediv>
17221<refsynopsisdiv>
17222 <title>Synopsis</title>
17223  <funcsynopsis><funcprototype>
17224   <funcdef>void <function>drm_modeset_acquire_init </function></funcdef>
17225   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17226   <paramdef>uint32_t <parameter>flags</parameter></paramdef>
17227  </funcprototype></funcsynopsis>
17228</refsynopsisdiv>
17229<refsect1>
17230 <title>Arguments</title>
17231 <variablelist>
17232  <varlistentry>
17233   <term><parameter>ctx</parameter></term>
17234   <listitem>
17235    <para>
17236     the acquire context
17237    </para>
17238   </listitem>
17239  </varlistentry>
17240  <varlistentry>
17241   <term><parameter>flags</parameter></term>
17242   <listitem>
17243    <para>
17244     for future
17245    </para>
17246   </listitem>
17247  </varlistentry>
17248 </variablelist>
17249</refsect1>
17250</refentry>
17251
17252<refentry id="API-drm-modeset-acquire-fini">
17253<refentryinfo>
17254 <title>LINUX</title>
17255 <productname>Kernel Hackers Manual</productname>
17256 <date>July 2017</date>
17257</refentryinfo>
17258<refmeta>
17259 <refentrytitle><phrase>drm_modeset_acquire_fini</phrase></refentrytitle>
17260 <manvolnum>9</manvolnum>
17261 <refmiscinfo class="version">4.1.27</refmiscinfo>
17262</refmeta>
17263<refnamediv>
17264 <refname>drm_modeset_acquire_fini</refname>
17265 <refpurpose>
17266     cleanup acquire context
17267 </refpurpose>
17268</refnamediv>
17269<refsynopsisdiv>
17270 <title>Synopsis</title>
17271  <funcsynopsis><funcprototype>
17272   <funcdef>void <function>drm_modeset_acquire_fini </function></funcdef>
17273   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17274  </funcprototype></funcsynopsis>
17275</refsynopsisdiv>
17276<refsect1>
17277 <title>Arguments</title>
17278 <variablelist>
17279  <varlistentry>
17280   <term><parameter>ctx</parameter></term>
17281   <listitem>
17282    <para>
17283     the acquire context
17284    </para>
17285   </listitem>
17286  </varlistentry>
17287 </variablelist>
17288</refsect1>
17289</refentry>
17290
17291<refentry id="API-drm-modeset-drop-locks">
17292<refentryinfo>
17293 <title>LINUX</title>
17294 <productname>Kernel Hackers Manual</productname>
17295 <date>July 2017</date>
17296</refentryinfo>
17297<refmeta>
17298 <refentrytitle><phrase>drm_modeset_drop_locks</phrase></refentrytitle>
17299 <manvolnum>9</manvolnum>
17300 <refmiscinfo class="version">4.1.27</refmiscinfo>
17301</refmeta>
17302<refnamediv>
17303 <refname>drm_modeset_drop_locks</refname>
17304 <refpurpose>
17305     drop all locks
17306 </refpurpose>
17307</refnamediv>
17308<refsynopsisdiv>
17309 <title>Synopsis</title>
17310  <funcsynopsis><funcprototype>
17311   <funcdef>void <function>drm_modeset_drop_locks </function></funcdef>
17312   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17313  </funcprototype></funcsynopsis>
17314</refsynopsisdiv>
17315<refsect1>
17316 <title>Arguments</title>
17317 <variablelist>
17318  <varlistentry>
17319   <term><parameter>ctx</parameter></term>
17320   <listitem>
17321    <para>
17322     the acquire context
17323    </para>
17324   </listitem>
17325  </varlistentry>
17326 </variablelist>
17327</refsect1>
17328<refsect1>
17329<title>Description</title>
17330<para>
17331   Drop all locks currently held against this acquire context.
17332</para>
17333</refsect1>
17334</refentry>
17335
17336<refentry id="API-drm-modeset-backoff">
17337<refentryinfo>
17338 <title>LINUX</title>
17339 <productname>Kernel Hackers Manual</productname>
17340 <date>July 2017</date>
17341</refentryinfo>
17342<refmeta>
17343 <refentrytitle><phrase>drm_modeset_backoff</phrase></refentrytitle>
17344 <manvolnum>9</manvolnum>
17345 <refmiscinfo class="version">4.1.27</refmiscinfo>
17346</refmeta>
17347<refnamediv>
17348 <refname>drm_modeset_backoff</refname>
17349 <refpurpose>
17350     deadlock avoidance backoff
17351 </refpurpose>
17352</refnamediv>
17353<refsynopsisdiv>
17354 <title>Synopsis</title>
17355  <funcsynopsis><funcprototype>
17356   <funcdef>void <function>drm_modeset_backoff </function></funcdef>
17357   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17358  </funcprototype></funcsynopsis>
17359</refsynopsisdiv>
17360<refsect1>
17361 <title>Arguments</title>
17362 <variablelist>
17363  <varlistentry>
17364   <term><parameter>ctx</parameter></term>
17365   <listitem>
17366    <para>
17367     the acquire context
17368    </para>
17369   </listitem>
17370  </varlistentry>
17371 </variablelist>
17372</refsect1>
17373<refsect1>
17374<title>Description</title>
17375<para>
17376   If deadlock is detected (ie. <function>drm_modeset_lock</function> returns -EDEADLK),
17377   you must call this function to drop all currently held locks and
17378   block until the contended lock becomes available.
17379</para>
17380</refsect1>
17381</refentry>
17382
17383<refentry id="API-drm-modeset-backoff-interruptible">
17384<refentryinfo>
17385 <title>LINUX</title>
17386 <productname>Kernel Hackers Manual</productname>
17387 <date>July 2017</date>
17388</refentryinfo>
17389<refmeta>
17390 <refentrytitle><phrase>drm_modeset_backoff_interruptible</phrase></refentrytitle>
17391 <manvolnum>9</manvolnum>
17392 <refmiscinfo class="version">4.1.27</refmiscinfo>
17393</refmeta>
17394<refnamediv>
17395 <refname>drm_modeset_backoff_interruptible</refname>
17396 <refpurpose>
17397     deadlock avoidance backoff
17398 </refpurpose>
17399</refnamediv>
17400<refsynopsisdiv>
17401 <title>Synopsis</title>
17402  <funcsynopsis><funcprototype>
17403   <funcdef>int <function>drm_modeset_backoff_interruptible </function></funcdef>
17404   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17405  </funcprototype></funcsynopsis>
17406</refsynopsisdiv>
17407<refsect1>
17408 <title>Arguments</title>
17409 <variablelist>
17410  <varlistentry>
17411   <term><parameter>ctx</parameter></term>
17412   <listitem>
17413    <para>
17414     the acquire context
17415    </para>
17416   </listitem>
17417  </varlistentry>
17418 </variablelist>
17419</refsect1>
17420<refsect1>
17421<title>Description</title>
17422<para>
17423   Interruptible version of <function>drm_modeset_backoff</function>
17424</para>
17425</refsect1>
17426</refentry>
17427
17428<refentry id="API-drm-modeset-lock">
17429<refentryinfo>
17430 <title>LINUX</title>
17431 <productname>Kernel Hackers Manual</productname>
17432 <date>July 2017</date>
17433</refentryinfo>
17434<refmeta>
17435 <refentrytitle><phrase>drm_modeset_lock</phrase></refentrytitle>
17436 <manvolnum>9</manvolnum>
17437 <refmiscinfo class="version">4.1.27</refmiscinfo>
17438</refmeta>
17439<refnamediv>
17440 <refname>drm_modeset_lock</refname>
17441 <refpurpose>
17442     take modeset lock
17443 </refpurpose>
17444</refnamediv>
17445<refsynopsisdiv>
17446 <title>Synopsis</title>
17447  <funcsynopsis><funcprototype>
17448   <funcdef>int <function>drm_modeset_lock </function></funcdef>
17449   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
17450   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17451  </funcprototype></funcsynopsis>
17452</refsynopsisdiv>
17453<refsect1>
17454 <title>Arguments</title>
17455 <variablelist>
17456  <varlistentry>
17457   <term><parameter>lock</parameter></term>
17458   <listitem>
17459    <para>
17460     lock to take
17461    </para>
17462   </listitem>
17463  </varlistentry>
17464  <varlistentry>
17465   <term><parameter>ctx</parameter></term>
17466   <listitem>
17467    <para>
17468     acquire ctx
17469    </para>
17470   </listitem>
17471  </varlistentry>
17472 </variablelist>
17473</refsect1>
17474<refsect1>
17475<title>Description</title>
17476<para>
17477   If ctx is not NULL, then its ww acquire context is used and the
17478   lock will be tracked by the context and can be released by calling
17479   <function>drm_modeset_drop_locks</function>.  If -EDEADLK is returned, this means a
17480   deadlock scenario has been detected and it is an error to attempt
17481   to take any more locks without first calling <function>drm_modeset_backoff</function>.
17482</para>
17483</refsect1>
17484</refentry>
17485
17486<refentry id="API-drm-modeset-lock-interruptible">
17487<refentryinfo>
17488 <title>LINUX</title>
17489 <productname>Kernel Hackers Manual</productname>
17490 <date>July 2017</date>
17491</refentryinfo>
17492<refmeta>
17493 <refentrytitle><phrase>drm_modeset_lock_interruptible</phrase></refentrytitle>
17494 <manvolnum>9</manvolnum>
17495 <refmiscinfo class="version">4.1.27</refmiscinfo>
17496</refmeta>
17497<refnamediv>
17498 <refname>drm_modeset_lock_interruptible</refname>
17499 <refpurpose>
17500     take modeset lock
17501 </refpurpose>
17502</refnamediv>
17503<refsynopsisdiv>
17504 <title>Synopsis</title>
17505  <funcsynopsis><funcprototype>
17506   <funcdef>int <function>drm_modeset_lock_interruptible </function></funcdef>
17507   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
17508   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
17509  </funcprototype></funcsynopsis>
17510</refsynopsisdiv>
17511<refsect1>
17512 <title>Arguments</title>
17513 <variablelist>
17514  <varlistentry>
17515   <term><parameter>lock</parameter></term>
17516   <listitem>
17517    <para>
17518     lock to take
17519    </para>
17520   </listitem>
17521  </varlistentry>
17522  <varlistentry>
17523   <term><parameter>ctx</parameter></term>
17524   <listitem>
17525    <para>
17526     acquire ctx
17527    </para>
17528   </listitem>
17529  </varlistentry>
17530 </variablelist>
17531</refsect1>
17532<refsect1>
17533<title>Description</title>
17534<para>
17535   Interruptible version of <function>drm_modeset_lock</function>
17536</para>
17537</refsect1>
17538</refentry>
17539
17540<refentry id="API-drm-modeset-unlock">
17541<refentryinfo>
17542 <title>LINUX</title>
17543 <productname>Kernel Hackers Manual</productname>
17544 <date>July 2017</date>
17545</refentryinfo>
17546<refmeta>
17547 <refentrytitle><phrase>drm_modeset_unlock</phrase></refentrytitle>
17548 <manvolnum>9</manvolnum>
17549 <refmiscinfo class="version">4.1.27</refmiscinfo>
17550</refmeta>
17551<refnamediv>
17552 <refname>drm_modeset_unlock</refname>
17553 <refpurpose>
17554     drop modeset lock
17555 </refpurpose>
17556</refnamediv>
17557<refsynopsisdiv>
17558 <title>Synopsis</title>
17559  <funcsynopsis><funcprototype>
17560   <funcdef>void <function>drm_modeset_unlock </function></funcdef>
17561   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
17562  </funcprototype></funcsynopsis>
17563</refsynopsisdiv>
17564<refsect1>
17565 <title>Arguments</title>
17566 <variablelist>
17567  <varlistentry>
17568   <term><parameter>lock</parameter></term>
17569   <listitem>
17570    <para>
17571     lock to release
17572    </para>
17573   </listitem>
17574  </varlistentry>
17575 </variablelist>
17576</refsect1>
17577</refentry>
17578
17579    </sect2>
17580  </sect1>
17581
17582  <!-- Internals: kms helper functions -->
17583
17584  <sect1>
17585    <title>Mode Setting Helper Functions</title>
17586    <para>
17587      The plane, CRTC, encoder and connector functions provided by the drivers
17588      implement the DRM API. They're called by the DRM core and ioctl handlers
17589      to handle device state changes and configuration request. As implementing
17590      those functions often requires logic not specific to drivers, mid-layer
17591      helper functions are available to avoid duplicating boilerplate code.
17592    </para>
17593    <para>
17594      The DRM core contains one mid-layer implementation. The mid-layer provides
17595      implementations of several plane, CRTC, encoder and connector functions
17596      (called from the top of the mid-layer) that pre-process requests and call
17597      lower-level functions provided by the driver (at the bottom of the
17598      mid-layer). For instance, the
17599      <function>drm_crtc_helper_set_config</function> function can be used to
17600      fill the struct <structname>drm_crtc_funcs</structname>
17601      <structfield>set_config</structfield> field. When called, it will split
17602      the <methodname>set_config</methodname> operation in smaller, simpler
17603      operations and call the driver to handle them.
17604    </para>
17605    <para>
17606      To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>,
17607      <function>drm_encoder_helper_add</function> and
17608      <function>drm_connector_helper_add</function> functions to install their
17609      mid-layer bottom operations handlers, and fill the
17610      <structname>drm_crtc_funcs</structname>,
17611      <structname>drm_encoder_funcs</structname> and
17612      <structname>drm_connector_funcs</structname> structures with pointers to
17613      the mid-layer top API functions. Installing the mid-layer bottom operation
17614      handlers is best done right after registering the corresponding KMS object.
17615    </para>
17616    <para>
17617      The mid-layer is not split between CRTC, encoder and connector operations.
17618      To use it, a driver must provide bottom functions for all of the three KMS
17619      entities.
17620    </para>
17621    <sect2>
17622      <title>Helper Functions</title>
17623      <itemizedlist>
17624        <listitem>
17625          <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis>
17626          <para>
17627            The <function>drm_crtc_helper_set_config</function> helper function
17628            is a CRTC <methodname>set_config</methodname> implementation. It
17629            first tries to locate the best encoder for each connector by calling
17630            the connector <methodname>best_encoder</methodname> helper
17631            operation.
17632          </para>
17633          <para>
17634            After locating the appropriate encoders, the helper function will
17635            call the <methodname>mode_fixup</methodname> encoder and CRTC helper
17636            operations to adjust the requested mode, or reject it completely in
17637            which case an error will be returned to the application. If the new
17638            configuration after mode adjustment is identical to the current
17639            configuration the helper function will return without performing any
17640            other operation.
17641          </para>
17642          <para>
17643            If the adjusted mode is identical to the current mode but changes to
17644            the frame buffer need to be applied, the
17645            <function>drm_crtc_helper_set_config</function> function will call
17646            the CRTC <methodname>mode_set_base</methodname> helper operation. If
17647            the adjusted mode differs from the current mode, or if the
17648            <methodname>mode_set_base</methodname> helper operation is not
17649            provided, the helper function performs a full mode set sequence by
17650            calling the <methodname>prepare</methodname>,
17651            <methodname>mode_set</methodname> and
17652            <methodname>commit</methodname> CRTC and encoder helper operations,
17653            in that order.
17654          </para>
17655        </listitem>
17656        <listitem>
17657          <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis>
17658          <para>
17659            The <function>drm_helper_connector_dpms</function> helper function
17660            is a connector <methodname>dpms</methodname> implementation that
17661            tracks power state of connectors. To use the function, drivers must
17662            provide <methodname>dpms</methodname> helper operations for CRTCs
17663            and encoders to apply the DPMS state to the device.
17664          </para>
17665          <para>
17666            The mid-layer doesn't track the power state of CRTCs and encoders.
17667            The <methodname>dpms</methodname> helper operations can thus be
17668            called with a mode identical to the currently active mode.
17669          </para>
17670        </listitem>
17671        <listitem>
17672          <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector,
17673                                            uint32_t maxX, uint32_t maxY);</synopsis>
17674          <para>
17675            The <function>drm_helper_probe_single_connector_modes</function> helper
17676            function is a connector <methodname>fill_modes</methodname>
17677            implementation that updates the connection status for the connector
17678            and then retrieves a list of modes by calling the connector
17679            <methodname>get_modes</methodname> helper operation.
17680          </para>
17681         <para>
17682            If the helper operation returns no mode, and if the connector status
17683            is connector_status_connected, standard VESA DMT modes up to
17684            1024x768 are automatically added to the modes list by a call to
17685            <function>drm_add_modes_noedid</function>.
17686          </para>
17687          <para>
17688            The function then filters out modes larger than
17689            <parameter>max_width</parameter> and <parameter>max_height</parameter>
17690            if specified. It finally calls the optional connector
17691            <methodname>mode_valid</methodname> helper operation for each mode in
17692            the probed list to check whether the mode is valid for the connector.
17693          </para>
17694        </listitem>
17695      </itemizedlist>
17696    </sect2>
17697    <sect2>
17698      <title>CRTC Helper Operations</title>
17699      <itemizedlist>
17700        <listitem id="drm-helper-crtc-mode-fixup">
17701          <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc,
17702                       const struct drm_display_mode *mode,
17703                       struct drm_display_mode *adjusted_mode);</synopsis>
17704          <para>
17705            Let CRTCs adjust the requested mode or reject it completely. This
17706            operation returns true if the mode is accepted (possibly after being
17707            adjusted) or false if it is rejected.
17708          </para>
17709          <para>
17710            The <methodname>mode_fixup</methodname> operation should reject the
17711            mode if it can't reasonably use it. The definition of "reasonable"
17712            is currently fuzzy in this context. One possible behaviour would be
17713            to set the adjusted mode to the panel timings when a fixed-mode
17714            panel is used with hardware capable of scaling. Another behaviour
17715            would be to accept any input mode and adjust it to the closest mode
17716            supported by the hardware (FIXME: This needs to be clarified).
17717          </para>
17718        </listitem>
17719        <listitem>
17720          <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
17721                     struct drm_framebuffer *old_fb)</synopsis>
17722          <para>
17723            Move the CRTC on the current frame buffer (stored in
17724            <literal>crtc-&gt;fb</literal>) to position (x,y). Any of the frame
17725            buffer, x position or y position may have been modified.
17726          </para>
17727          <para>
17728            This helper operation is optional. If not provided, the
17729            <function>drm_crtc_helper_set_config</function> function will fall
17730            back to the <methodname>mode_set</methodname> helper operation.
17731          </para>
17732          <note><para>
17733            FIXME: Why are x and y passed as arguments, as they can be accessed
17734            through <literal>crtc-&gt;x</literal> and
17735            <literal>crtc-&gt;y</literal>?
17736          </para></note>
17737        </listitem>
17738        <listitem>
17739          <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis>
17740          <para>
17741            Prepare the CRTC for mode setting. This operation is called after
17742            validating the requested mode. Drivers use it to perform
17743            device-specific operations required before setting the new mode.
17744          </para>
17745        </listitem>
17746        <listitem>
17747          <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode,
17748                struct drm_display_mode *adjusted_mode, int x, int y,
17749                struct drm_framebuffer *old_fb);</synopsis>
17750          <para>
17751            Set a new mode, position and frame buffer. Depending on the device
17752            requirements, the mode can be stored internally by the driver and
17753            applied in the <methodname>commit</methodname> operation, or
17754            programmed to the hardware immediately.
17755          </para>
17756          <para>
17757            The <methodname>mode_set</methodname> operation returns 0 on success
17758	    or a negative error code if an error occurs.
17759          </para>
17760        </listitem>
17761        <listitem>
17762          <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis>
17763          <para>
17764            Commit a mode. This operation is called after setting the new mode.
17765            Upon return the device must use the new mode and be fully
17766            operational.
17767          </para>
17768        </listitem>
17769      </itemizedlist>
17770    </sect2>
17771    <sect2>
17772      <title>Encoder Helper Operations</title>
17773      <itemizedlist>
17774        <listitem>
17775          <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder,
17776                       const struct drm_display_mode *mode,
17777                       struct drm_display_mode *adjusted_mode);</synopsis>
17778          <para>
17779            Let encoders adjust the requested mode or reject it completely. This
17780            operation returns true if the mode is accepted (possibly after being
17781            adjusted) or false if it is rejected. See the
17782            <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper
17783            operation</link> for an explanation of the allowed adjustments.
17784          </para>
17785        </listitem>
17786        <listitem>
17787          <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis>
17788          <para>
17789            Prepare the encoder for mode setting. This operation is called after
17790            validating the requested mode. Drivers use it to perform
17791            device-specific operations required before setting the new mode.
17792          </para>
17793        </listitem>
17794        <listitem>
17795          <synopsis>void (*mode_set)(struct drm_encoder *encoder,
17796                 struct drm_display_mode *mode,
17797                 struct drm_display_mode *adjusted_mode);</synopsis>
17798          <para>
17799            Set a new mode. Depending on the device requirements, the mode can
17800            be stored internally by the driver and applied in the
17801            <methodname>commit</methodname> operation, or programmed to the
17802            hardware immediately.
17803          </para>
17804        </listitem>
17805        <listitem>
17806          <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis>
17807          <para>
17808            Commit a mode. This operation is called after setting the new mode.
17809            Upon return the device must use the new mode and be fully
17810            operational.
17811          </para>
17812        </listitem>
17813      </itemizedlist>
17814    </sect2>
17815    <sect2>
17816      <title>Connector Helper Operations</title>
17817      <itemizedlist>
17818        <listitem>
17819          <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis>
17820          <para>
17821            Return a pointer to the best encoder for the connecter. Device that
17822            map connectors to encoders 1:1 simply return the pointer to the
17823            associated encoder. This operation is mandatory.
17824          </para>
17825        </listitem>
17826        <listitem>
17827          <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis>
17828          <para>
17829            Fill the connector's <structfield>probed_modes</structfield> list
17830            by parsing EDID data with <function>drm_add_edid_modes</function>,
17831            adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>,
17832            or calling <function>drm_mode_probed_add</function> directly for every
17833            supported mode and return the number of modes it has detected. This
17834            operation is mandatory.
17835          </para>
17836          <para>
17837            Note that the caller function will automatically add standard VESA
17838            DMT modes up to 1024x768 if the <methodname>get_modes</methodname>
17839            helper operation returns no mode and if the connector status is
17840            connector_status_connected. There is no need to call
17841            <function>drm_add_edid_modes</function> manually in that case.
17842          </para>
17843          <para>
17844            When adding modes manually the driver creates each mode with a call to
17845            <function>drm_mode_create</function> and must fill the following fields.
17846            <itemizedlist>
17847              <listitem>
17848                <synopsis>__u32 type;</synopsis>
17849                <para>
17850                  Mode type bitmask, a combination of
17851                  <variablelist>
17852                    <varlistentry>
17853                      <term>DRM_MODE_TYPE_BUILTIN</term>
17854                      <listitem><para>not used?</para></listitem>
17855                    </varlistentry>
17856                    <varlistentry>
17857                      <term>DRM_MODE_TYPE_CLOCK_C</term>
17858                      <listitem><para>not used?</para></listitem>
17859                    </varlistentry>
17860                    <varlistentry>
17861                      <term>DRM_MODE_TYPE_CRTC_C</term>
17862                      <listitem><para>not used?</para></listitem>
17863                    </varlistentry>
17864                    <varlistentry>
17865                      <term>
17866        DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector
17867                      </term>
17868                      <listitem>
17869                        <para>not used?</para>
17870                      </listitem>
17871                    </varlistentry>
17872                    <varlistentry>
17873                      <term>DRM_MODE_TYPE_DEFAULT</term>
17874                      <listitem><para>not used?</para></listitem>
17875                    </varlistentry>
17876                    <varlistentry>
17877                      <term>DRM_MODE_TYPE_USERDEF</term>
17878                      <listitem><para>not used?</para></listitem>
17879                    </varlistentry>
17880                    <varlistentry>
17881                      <term>DRM_MODE_TYPE_DRIVER</term>
17882                      <listitem>
17883                        <para>
17884                          The mode has been created by the driver (as opposed to
17885                          to user-created modes).
17886                        </para>
17887                      </listitem>
17888                    </varlistentry>
17889                  </variablelist>
17890                  Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they
17891                  create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred
17892                  mode.
17893                </para>
17894              </listitem>
17895              <listitem>
17896                <synopsis>__u32 clock;</synopsis>
17897                <para>Pixel clock frequency in kHz unit</para>
17898              </listitem>
17899              <listitem>
17900                <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal;
17901    __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis>
17902                <para>Horizontal and vertical timing information</para>
17903                <screen><![CDATA[
17904             Active                 Front           Sync           Back
17905             Region                 Porch                          Porch
17906    <-----------------------><----------------><-------------><-------------->
17907
17908      //////////////////////|
17909     ////////////////////// |
17910    //////////////////////  |..................               ................
17911                                               _______________
17912
17913    <----- [hv]display ----->
17914    <------------- [hv]sync_start ------------>
17915    <--------------------- [hv]sync_end --------------------->
17916    <-------------------------------- [hv]total ----------------------------->
17917]]></screen>
17918              </listitem>
17919              <listitem>
17920                <synopsis>__u16 hskew;
17921    __u16 vscan;</synopsis>
17922                <para>Unknown</para>
17923              </listitem>
17924              <listitem>
17925                <synopsis>__u32 flags;</synopsis>
17926                <para>
17927                  Mode flags, a combination of
17928                  <variablelist>
17929                    <varlistentry>
17930                      <term>DRM_MODE_FLAG_PHSYNC</term>
17931                      <listitem><para>
17932                        Horizontal sync is active high
17933                      </para></listitem>
17934                    </varlistentry>
17935                    <varlistentry>
17936                      <term>DRM_MODE_FLAG_NHSYNC</term>
17937                      <listitem><para>
17938                        Horizontal sync is active low
17939                      </para></listitem>
17940                    </varlistentry>
17941                    <varlistentry>
17942                      <term>DRM_MODE_FLAG_PVSYNC</term>
17943                      <listitem><para>
17944                        Vertical sync is active high
17945                      </para></listitem>
17946                    </varlistentry>
17947                    <varlistentry>
17948                      <term>DRM_MODE_FLAG_NVSYNC</term>
17949                      <listitem><para>
17950                        Vertical sync is active low
17951                      </para></listitem>
17952                    </varlistentry>
17953                    <varlistentry>
17954                      <term>DRM_MODE_FLAG_INTERLACE</term>
17955                      <listitem><para>
17956                        Mode is interlaced
17957                      </para></listitem>
17958                    </varlistentry>
17959                    <varlistentry>
17960                      <term>DRM_MODE_FLAG_DBLSCAN</term>
17961                      <listitem><para>
17962                        Mode uses doublescan
17963                      </para></listitem>
17964                    </varlistentry>
17965                    <varlistentry>
17966                      <term>DRM_MODE_FLAG_CSYNC</term>
17967                      <listitem><para>
17968                        Mode uses composite sync
17969                      </para></listitem>
17970                    </varlistentry>
17971                    <varlistentry>
17972                      <term>DRM_MODE_FLAG_PCSYNC</term>
17973                      <listitem><para>
17974                        Composite sync is active high
17975                      </para></listitem>
17976                    </varlistentry>
17977                    <varlistentry>
17978                      <term>DRM_MODE_FLAG_NCSYNC</term>
17979                      <listitem><para>
17980                        Composite sync is active low
17981                      </para></listitem>
17982                    </varlistentry>
17983                    <varlistentry>
17984                      <term>DRM_MODE_FLAG_HSKEW</term>
17985                      <listitem><para>
17986                        hskew provided (not used?)
17987                      </para></listitem>
17988                    </varlistentry>
17989                    <varlistentry>
17990                      <term>DRM_MODE_FLAG_BCAST</term>
17991                      <listitem><para>
17992                        not used?
17993                      </para></listitem>
17994                    </varlistentry>
17995                    <varlistentry>
17996                      <term>DRM_MODE_FLAG_PIXMUX</term>
17997                      <listitem><para>
17998                        not used?
17999                      </para></listitem>
18000                    </varlistentry>
18001                    <varlistentry>
18002                      <term>DRM_MODE_FLAG_DBLCLK</term>
18003                      <listitem><para>
18004                        not used?
18005                      </para></listitem>
18006                    </varlistentry>
18007                    <varlistentry>
18008                      <term>DRM_MODE_FLAG_CLKDIV2</term>
18009                      <listitem><para>
18010                        ?
18011                      </para></listitem>
18012                    </varlistentry>
18013                  </variablelist>
18014                </para>
18015                <para>
18016                  Note that modes marked with the INTERLACE or DBLSCAN flags will be
18017                  filtered out by
18018                  <function>drm_helper_probe_single_connector_modes</function> if
18019                  the connector's <structfield>interlace_allowed</structfield> or
18020                  <structfield>doublescan_allowed</structfield> field is set to 0.
18021                </para>
18022              </listitem>
18023              <listitem>
18024                <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis>
18025                <para>
18026                  Mode name. The driver must call
18027                  <function>drm_mode_set_name</function> to fill the mode name from
18028                  <structfield>hdisplay</structfield>,
18029                  <structfield>vdisplay</structfield> and interlace flag after
18030                  filling the corresponding fields.
18031                </para>
18032              </listitem>
18033            </itemizedlist>
18034          </para>
18035          <para>
18036            The <structfield>vrefresh</structfield> value is computed by
18037            <function>drm_helper_probe_single_connector_modes</function>.
18038          </para>
18039          <para>
18040            When parsing EDID data, <function>drm_add_edid_modes</function> fills the
18041            connector <structfield>display_info</structfield>
18042            <structfield>width_mm</structfield> and
18043            <structfield>height_mm</structfield> fields. When creating modes
18044            manually the <methodname>get_modes</methodname> helper operation must
18045            set the <structfield>display_info</structfield>
18046            <structfield>width_mm</structfield> and
18047            <structfield>height_mm</structfield> fields if they haven't been set
18048            already (for instance at initialization time when a fixed-size panel is
18049            attached to the connector). The mode <structfield>width_mm</structfield>
18050            and <structfield>height_mm</structfield> fields are only used internally
18051            during EDID parsing and should not be set when creating modes manually.
18052          </para>
18053        </listitem>
18054        <listitem>
18055          <synopsis>int (*mode_valid)(struct drm_connector *connector,
18056		  struct drm_display_mode *mode);</synopsis>
18057          <para>
18058            Verify whether a mode is valid for the connector. Return MODE_OK for
18059            supported modes and one of the enum drm_mode_status values (MODE_*)
18060            for unsupported modes. This operation is optional.
18061          </para>
18062          <para>
18063            As the mode rejection reason is currently not used beside for
18064            immediately removing the unsupported mode, an implementation can
18065            return MODE_BAD regardless of the exact reason why the mode is not
18066            valid.
18067          </para>
18068          <note><para>
18069            Note that the <methodname>mode_valid</methodname> helper operation is
18070            only called for modes detected by the device, and
18071            <emphasis>not</emphasis> for modes set by the user through the CRTC
18072            <methodname>set_config</methodname> operation.
18073          </para></note>
18074        </listitem>
18075      </itemizedlist>
18076    </sect2>
18077    <sect2>
18078      <title>Atomic Modeset Helper Functions Reference</title>
18079      <sect3>
18080	<title>Overview</title>
18081<para>
18082   </para><para>
18083   This helper library provides implementations of check and commit functions on
18084   top of the CRTC modeset helper callbacks and the plane helper callbacks. It
18085   also provides convenience implementations for the atomic state handling
18086   callbacks for drivers which don't need to subclass the drm core structures to
18087   add their own additional internal state.
18088   </para><para>
18089   This library also provides default implementations for the check callback in
18090   drm_atomic_helper_check and for the commit callback with
18091   drm_atomic_helper_commit. But the individual stages and callbacks are expose
18092   to allow drivers to mix and match and e.g. use the plane helpers only
18093   together with a driver private modeset implementation.
18094   </para><para>
18095   This library also provides implementations for all the legacy driver
18096   interfaces on top of the atomic interface. See drm_atomic_helper_set_config,
18097   drm_atomic_helper_disable_plane, drm_atomic_helper_disable_plane and the
18098   various functions to implement set_property callbacks. New drivers must not
18099   implement these functions themselves but must use the provided helpers.
18100</para>
18101
18102      </sect3>
18103      <sect3>
18104	<title>Implementing Asynchronous Atomic Commit</title>
18105<para>
18106   </para><para>
18107   For now the atomic helpers don't support async commit directly. If there is
18108   real need it could be added though, using the dma-buf fence infrastructure
18109   for generic synchronization with outstanding rendering.
18110   </para><para>
18111   For now drivers have to implement async commit themselves, with the following
18112   sequence being the recommended one:
18113   </para><para>
18114   1. Run <function>drm_atomic_helper_prepare_planes</function> first. This is the only function
18115   which commit needs to call which can fail, so we want to run it first and
18116   synchronously.
18117   </para><para>
18118   2. Synchronize with any outstanding asynchronous commit worker threads which
18119   might be affected the new state update. This can be done by either cancelling
18120   or flushing the work items, depending upon whether the driver can deal with
18121   cancelled updates. Note that it is important to ensure that the framebuffer
18122   cleanup is still done when cancelling.
18123   </para><para>
18124   For sufficient parallelism it is recommended to have a work item per crtc
18125   (for updates which don't touch global state) and a global one. Then we only
18126   need to synchronize with the crtc work items for changed crtcs and the global
18127   work item, which allows nice concurrent updates on disjoint sets of crtcs.
18128   </para><para>
18129   3. The software state is updated synchronously with
18130   drm_atomic_helper_swap_state. Doing this under the protection of all modeset
18131   locks means concurrent callers never see inconsistent state. And doing this
18132   while it's guaranteed that no relevant async worker runs means that async
18133   workers do not need grab any locks. Actually they must not grab locks, for
18134   otherwise the work flushing will deadlock.
18135   </para><para>
18136   4. Schedule a work item to do all subsequent steps, using the split-out
18137   commit helpers: a) pre-plane commit b) plane commit c) post-plane commit and
18138   then cleaning up the framebuffers after the old framebuffer is no longer
18139   being displayed.
18140</para>
18141
18142      </sect3>
18143      <sect3>
18144	<title>Atomic State Reset and Initialization</title>
18145<para>
18146   </para><para>
18147   Both the drm core and the atomic helpers assume that there is always the full
18148   and correct atomic software state for all connectors, CRTCs and planes
18149   available. Which is a bit a problem on driver load and also after system
18150   suspend. One way to solve this is to have a hardware state read-out
18151   infrastructure which reconstructs the full software state (e.g. the i915
18152   driver).
18153   </para><para>
18154   The simpler solution is to just reset the software state to everything off,
18155   which is easiest to do by calling <function>drm_mode_config_reset</function>. To facilitate this
18156   the atomic helpers provide default reset implementations for all hooks.
18157</para>
18158
18159      </sect3>
18160<!-- include/drm/drm_atomic_helper.h -->
18161<refentry id="API-drm-atomic-crtc-for-each-plane">
18162<refentryinfo>
18163 <title>LINUX</title>
18164 <productname>Kernel Hackers Manual</productname>
18165 <date>July 2017</date>
18166</refentryinfo>
18167<refmeta>
18168 <refentrytitle><phrase>drm_atomic_crtc_for_each_plane</phrase></refentrytitle>
18169 <manvolnum>9</manvolnum>
18170 <refmiscinfo class="version">4.1.27</refmiscinfo>
18171</refmeta>
18172<refnamediv>
18173 <refname>drm_atomic_crtc_for_each_plane</refname>
18174 <refpurpose>
18175  iterate over planes currently attached to CRTC
18176 </refpurpose>
18177</refnamediv>
18178<refsynopsisdiv>
18179 <title>Synopsis</title>
18180  <funcsynopsis><funcprototype>
18181   <funcdef> <function>drm_atomic_crtc_for_each_plane </function></funcdef>
18182   <paramdef> <parameter>plane</parameter></paramdef>
18183   <paramdef> <parameter>crtc</parameter></paramdef>
18184  </funcprototype></funcsynopsis>
18185</refsynopsisdiv>
18186<refsect1>
18187 <title>Arguments</title>
18188 <variablelist>
18189  <varlistentry>
18190   <term><parameter>plane</parameter></term>
18191   <listitem>
18192    <para>
18193     the loop cursor
18194    </para>
18195   </listitem>
18196  </varlistentry>
18197  <varlistentry>
18198   <term><parameter>crtc</parameter></term>
18199   <listitem>
18200    <para>
18201     the crtc whose planes are iterated
18202    </para>
18203   </listitem>
18204  </varlistentry>
18205 </variablelist>
18206</refsect1>
18207<refsect1>
18208<title>Description</title>
18209<para>
18210   This iterates over the current state, useful (for example) when applying
18211   atomic state after it has been checked and swapped.  To iterate over the
18212   planes which *will* be attached (for -&gt;<function>atomic_check</function>) see
18213   <function>drm_crtc_for_each_pending_plane</function>
18214</para>
18215</refsect1>
18216</refentry>
18217
18218<refentry id="API-drm-atomic-crtc-state-for-each-plane">
18219<refentryinfo>
18220 <title>LINUX</title>
18221 <productname>Kernel Hackers Manual</productname>
18222 <date>July 2017</date>
18223</refentryinfo>
18224<refmeta>
18225 <refentrytitle><phrase>drm_atomic_crtc_state_for_each_plane</phrase></refentrytitle>
18226 <manvolnum>9</manvolnum>
18227 <refmiscinfo class="version">4.1.27</refmiscinfo>
18228</refmeta>
18229<refnamediv>
18230 <refname>drm_atomic_crtc_state_for_each_plane</refname>
18231 <refpurpose>
18232     iterate over attached planes in new state
18233 </refpurpose>
18234</refnamediv>
18235<refsynopsisdiv>
18236 <title>Synopsis</title>
18237  <funcsynopsis><funcprototype>
18238   <funcdef> <function>drm_atomic_crtc_state_for_each_plane </function></funcdef>
18239   <paramdef> <parameter>plane</parameter></paramdef>
18240   <paramdef> <parameter>crtc_state</parameter></paramdef>
18241  </funcprototype></funcsynopsis>
18242</refsynopsisdiv>
18243<refsect1>
18244 <title>Arguments</title>
18245 <variablelist>
18246  <varlistentry>
18247   <term><parameter>plane</parameter></term>
18248   <listitem>
18249    <para>
18250     the loop cursor
18251    </para>
18252   </listitem>
18253  </varlistentry>
18254  <varlistentry>
18255   <term><parameter>crtc_state</parameter></term>
18256   <listitem>
18257    <para>
18258     the incoming crtc-state
18259    </para>
18260   </listitem>
18261  </varlistentry>
18262 </variablelist>
18263</refsect1>
18264<refsect1>
18265<title>Description</title>
18266<para>
18267   Similar to <function>drm_crtc_for_each_plane</function>, but iterates the planes that will be
18268   attached if the specified state is applied.  Useful during (for example)
18269   -&gt;<function>atomic_check</function> operations, to validate the incoming state
18270</para>
18271</refsect1>
18272</refentry>
18273
18274<!-- drivers/gpu/drm/drm_atomic_helper.c -->
18275<refentry id="API-drm-atomic-helper-check-modeset">
18276<refentryinfo>
18277 <title>LINUX</title>
18278 <productname>Kernel Hackers Manual</productname>
18279 <date>July 2017</date>
18280</refentryinfo>
18281<refmeta>
18282 <refentrytitle><phrase>drm_atomic_helper_check_modeset</phrase></refentrytitle>
18283 <manvolnum>9</manvolnum>
18284 <refmiscinfo class="version">4.1.27</refmiscinfo>
18285</refmeta>
18286<refnamediv>
18287 <refname>drm_atomic_helper_check_modeset</refname>
18288 <refpurpose>
18289  validate state object for modeset changes
18290 </refpurpose>
18291</refnamediv>
18292<refsynopsisdiv>
18293 <title>Synopsis</title>
18294  <funcsynopsis><funcprototype>
18295   <funcdef>int <function>drm_atomic_helper_check_modeset </function></funcdef>
18296   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18297   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
18298  </funcprototype></funcsynopsis>
18299</refsynopsisdiv>
18300<refsect1>
18301 <title>Arguments</title>
18302 <variablelist>
18303  <varlistentry>
18304   <term><parameter>dev</parameter></term>
18305   <listitem>
18306    <para>
18307     DRM device
18308    </para>
18309   </listitem>
18310  </varlistentry>
18311  <varlistentry>
18312   <term><parameter>state</parameter></term>
18313   <listitem>
18314    <para>
18315     the driver state object
18316    </para>
18317   </listitem>
18318  </varlistentry>
18319 </variablelist>
18320</refsect1>
18321<refsect1>
18322<title>Description</title>
18323<para>
18324   Check the state object to see if the requested state is physically possible.
18325   This does all the crtc and connector related computations for an atomic
18326   update. It computes and updates crtc_state-&gt;mode_changed, adds any additional
18327   connectors needed for full modesets and calls down into -&gt;mode_fixup
18328   functions of the driver backend.
18329</para>
18330</refsect1>
18331<refsect1>
18332<title>IMPORTANT</title>
18333<para>
18334   </para><para>
18335
18336   Drivers which update -&gt;mode_changed (e.g. in their -&gt;atomic_check hooks if a
18337   plane update can't be done without a full modeset) _must_ call this function
18338   afterwards after that change. It is permitted to call this function multiple
18339   times for the same update, e.g. when the -&gt;atomic_check functions depend upon
18340   the adjusted dotclock for fifo space allocation and watermark computation.
18341   </para><para>
18342
18343   RETURNS
18344   Zero for success or -errno
18345</para>
18346</refsect1>
18347</refentry>
18348
18349<refentry id="API-drm-atomic-helper-check-planes">
18350<refentryinfo>
18351 <title>LINUX</title>
18352 <productname>Kernel Hackers Manual</productname>
18353 <date>July 2017</date>
18354</refentryinfo>
18355<refmeta>
18356 <refentrytitle><phrase>drm_atomic_helper_check_planes</phrase></refentrytitle>
18357 <manvolnum>9</manvolnum>
18358 <refmiscinfo class="version">4.1.27</refmiscinfo>
18359</refmeta>
18360<refnamediv>
18361 <refname>drm_atomic_helper_check_planes</refname>
18362 <refpurpose>
18363     validate state object for planes changes
18364 </refpurpose>
18365</refnamediv>
18366<refsynopsisdiv>
18367 <title>Synopsis</title>
18368  <funcsynopsis><funcprototype>
18369   <funcdef>int <function>drm_atomic_helper_check_planes </function></funcdef>
18370   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18371   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
18372  </funcprototype></funcsynopsis>
18373</refsynopsisdiv>
18374<refsect1>
18375 <title>Arguments</title>
18376 <variablelist>
18377  <varlistentry>
18378   <term><parameter>dev</parameter></term>
18379   <listitem>
18380    <para>
18381     DRM device
18382    </para>
18383   </listitem>
18384  </varlistentry>
18385  <varlistentry>
18386   <term><parameter>state</parameter></term>
18387   <listitem>
18388    <para>
18389     the driver state object
18390    </para>
18391   </listitem>
18392  </varlistentry>
18393 </variablelist>
18394</refsect1>
18395<refsect1>
18396<title>Description</title>
18397<para>
18398   Check the state object to see if the requested state is physically possible.
18399   This does all the plane update related checks using by calling into the
18400   -&gt;atomic_check hooks provided by the driver.
18401   </para><para>
18402
18403   RETURNS
18404   Zero for success or -errno
18405</para>
18406</refsect1>
18407</refentry>
18408
18409<refentry id="API-drm-atomic-helper-check">
18410<refentryinfo>
18411 <title>LINUX</title>
18412 <productname>Kernel Hackers Manual</productname>
18413 <date>July 2017</date>
18414</refentryinfo>
18415<refmeta>
18416 <refentrytitle><phrase>drm_atomic_helper_check</phrase></refentrytitle>
18417 <manvolnum>9</manvolnum>
18418 <refmiscinfo class="version">4.1.27</refmiscinfo>
18419</refmeta>
18420<refnamediv>
18421 <refname>drm_atomic_helper_check</refname>
18422 <refpurpose>
18423     validate state object
18424 </refpurpose>
18425</refnamediv>
18426<refsynopsisdiv>
18427 <title>Synopsis</title>
18428  <funcsynopsis><funcprototype>
18429   <funcdef>int <function>drm_atomic_helper_check </function></funcdef>
18430   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18431   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
18432  </funcprototype></funcsynopsis>
18433</refsynopsisdiv>
18434<refsect1>
18435 <title>Arguments</title>
18436 <variablelist>
18437  <varlistentry>
18438   <term><parameter>dev</parameter></term>
18439   <listitem>
18440    <para>
18441     DRM device
18442    </para>
18443   </listitem>
18444  </varlistentry>
18445  <varlistentry>
18446   <term><parameter>state</parameter></term>
18447   <listitem>
18448    <para>
18449     the driver state object
18450    </para>
18451   </listitem>
18452  </varlistentry>
18453 </variablelist>
18454</refsect1>
18455<refsect1>
18456<title>Description</title>
18457<para>
18458   Check the state object to see if the requested state is physically possible.
18459   Only crtcs and planes have check callbacks, so for any additional (global)
18460   checking that a driver needs it can simply wrap that around this function.
18461   Drivers without such needs can directly use this as their -&gt;<function>atomic_check</function>
18462   callback.
18463   </para><para>
18464
18465   This just wraps the two parts of the state checking for planes and modeset
18466</para>
18467</refsect1>
18468<refsect1>
18469<title>state in the default order</title>
18470<para>
18471   First it calls <function>drm_atomic_helper_check_modeset</function>
18472   and then <function>drm_atomic_helper_check_planes</function>. The assumption is that the
18473   -&gt;atomic_check functions depend upon an updated adjusted_mode.clock to
18474   e.g. properly compute watermarks.
18475   </para><para>
18476
18477   RETURNS
18478   Zero for success or -errno
18479</para>
18480</refsect1>
18481</refentry>
18482
18483<refentry id="API-drm-atomic-helper-commit-modeset-disables">
18484<refentryinfo>
18485 <title>LINUX</title>
18486 <productname>Kernel Hackers Manual</productname>
18487 <date>July 2017</date>
18488</refentryinfo>
18489<refmeta>
18490 <refentrytitle><phrase>drm_atomic_helper_commit_modeset_disables</phrase></refentrytitle>
18491 <manvolnum>9</manvolnum>
18492 <refmiscinfo class="version">4.1.27</refmiscinfo>
18493</refmeta>
18494<refnamediv>
18495 <refname>drm_atomic_helper_commit_modeset_disables</refname>
18496 <refpurpose>
18497     modeset commit to disable outputs
18498 </refpurpose>
18499</refnamediv>
18500<refsynopsisdiv>
18501 <title>Synopsis</title>
18502  <funcsynopsis><funcprototype>
18503   <funcdef>void <function>drm_atomic_helper_commit_modeset_disables </function></funcdef>
18504   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18505   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
18506  </funcprototype></funcsynopsis>
18507</refsynopsisdiv>
18508<refsect1>
18509 <title>Arguments</title>
18510 <variablelist>
18511  <varlistentry>
18512   <term><parameter>dev</parameter></term>
18513   <listitem>
18514    <para>
18515     DRM device
18516    </para>
18517   </listitem>
18518  </varlistentry>
18519  <varlistentry>
18520   <term><parameter>old_state</parameter></term>
18521   <listitem>
18522    <para>
18523     atomic state object with old state structures
18524    </para>
18525   </listitem>
18526  </varlistentry>
18527 </variablelist>
18528</refsect1>
18529<refsect1>
18530<title>Description</title>
18531<para>
18532   This function shuts down all the outputs that need to be shut down and
18533   prepares them (if required) with the new mode.
18534   </para><para>
18535
18536   For compatability with legacy crtc helpers this should be called before
18537   <function>drm_atomic_helper_commit_planes</function>, which is what the default commit function
18538   does. But drivers with different needs can group the modeset commits together
18539   and do the plane commits at the end. This is useful for drivers doing runtime
18540   PM since planes updates then only happen when the CRTC is actually enabled.
18541</para>
18542</refsect1>
18543</refentry>
18544
18545<refentry id="API-drm-atomic-helper-commit-modeset-enables">
18546<refentryinfo>
18547 <title>LINUX</title>
18548 <productname>Kernel Hackers Manual</productname>
18549 <date>July 2017</date>
18550</refentryinfo>
18551<refmeta>
18552 <refentrytitle><phrase>drm_atomic_helper_commit_modeset_enables</phrase></refentrytitle>
18553 <manvolnum>9</manvolnum>
18554 <refmiscinfo class="version">4.1.27</refmiscinfo>
18555</refmeta>
18556<refnamediv>
18557 <refname>drm_atomic_helper_commit_modeset_enables</refname>
18558 <refpurpose>
18559     modeset commit to enable outputs
18560 </refpurpose>
18561</refnamediv>
18562<refsynopsisdiv>
18563 <title>Synopsis</title>
18564  <funcsynopsis><funcprototype>
18565   <funcdef>void <function>drm_atomic_helper_commit_modeset_enables </function></funcdef>
18566   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18567   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
18568  </funcprototype></funcsynopsis>
18569</refsynopsisdiv>
18570<refsect1>
18571 <title>Arguments</title>
18572 <variablelist>
18573  <varlistentry>
18574   <term><parameter>dev</parameter></term>
18575   <listitem>
18576    <para>
18577     DRM device
18578    </para>
18579   </listitem>
18580  </varlistentry>
18581  <varlistentry>
18582   <term><parameter>old_state</parameter></term>
18583   <listitem>
18584    <para>
18585     atomic state object with old state structures
18586    </para>
18587   </listitem>
18588  </varlistentry>
18589 </variablelist>
18590</refsect1>
18591<refsect1>
18592<title>Description</title>
18593<para>
18594   This function enables all the outputs with the new configuration which had to
18595   be turned off for the update.
18596   </para><para>
18597
18598   For compatability with legacy crtc helpers this should be called after
18599   <function>drm_atomic_helper_commit_planes</function>, which is what the default commit function
18600   does. But drivers with different needs can group the modeset commits together
18601   and do the plane commits at the end. This is useful for drivers doing runtime
18602   PM since planes updates then only happen when the CRTC is actually enabled.
18603</para>
18604</refsect1>
18605</refentry>
18606
18607<refentry id="API-drm-atomic-helper-wait-for-vblanks">
18608<refentryinfo>
18609 <title>LINUX</title>
18610 <productname>Kernel Hackers Manual</productname>
18611 <date>July 2017</date>
18612</refentryinfo>
18613<refmeta>
18614 <refentrytitle><phrase>drm_atomic_helper_wait_for_vblanks</phrase></refentrytitle>
18615 <manvolnum>9</manvolnum>
18616 <refmiscinfo class="version">4.1.27</refmiscinfo>
18617</refmeta>
18618<refnamediv>
18619 <refname>drm_atomic_helper_wait_for_vblanks</refname>
18620 <refpurpose>
18621     wait for vblank on crtcs
18622 </refpurpose>
18623</refnamediv>
18624<refsynopsisdiv>
18625 <title>Synopsis</title>
18626  <funcsynopsis><funcprototype>
18627   <funcdef>void <function>drm_atomic_helper_wait_for_vblanks </function></funcdef>
18628   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18629   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
18630  </funcprototype></funcsynopsis>
18631</refsynopsisdiv>
18632<refsect1>
18633 <title>Arguments</title>
18634 <variablelist>
18635  <varlistentry>
18636   <term><parameter>dev</parameter></term>
18637   <listitem>
18638    <para>
18639     DRM device
18640    </para>
18641   </listitem>
18642  </varlistentry>
18643  <varlistentry>
18644   <term><parameter>old_state</parameter></term>
18645   <listitem>
18646    <para>
18647     atomic state object with old state structures
18648    </para>
18649   </listitem>
18650  </varlistentry>
18651 </variablelist>
18652</refsect1>
18653<refsect1>
18654<title>Description</title>
18655<para>
18656   Helper to, after atomic commit, wait for vblanks on all effected
18657   crtcs (ie. before cleaning up old framebuffers using
18658   <function>drm_atomic_helper_cleanup_planes</function>). It will only wait on crtcs where the
18659   framebuffers have actually changed to optimize for the legacy cursor and
18660   plane update use-case.
18661</para>
18662</refsect1>
18663</refentry>
18664
18665<refentry id="API-drm-atomic-helper-commit">
18666<refentryinfo>
18667 <title>LINUX</title>
18668 <productname>Kernel Hackers Manual</productname>
18669 <date>July 2017</date>
18670</refentryinfo>
18671<refmeta>
18672 <refentrytitle><phrase>drm_atomic_helper_commit</phrase></refentrytitle>
18673 <manvolnum>9</manvolnum>
18674 <refmiscinfo class="version">4.1.27</refmiscinfo>
18675</refmeta>
18676<refnamediv>
18677 <refname>drm_atomic_helper_commit</refname>
18678 <refpurpose>
18679     commit validated state object
18680 </refpurpose>
18681</refnamediv>
18682<refsynopsisdiv>
18683 <title>Synopsis</title>
18684  <funcsynopsis><funcprototype>
18685   <funcdef>int <function>drm_atomic_helper_commit </function></funcdef>
18686   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18687   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
18688   <paramdef>bool <parameter>async</parameter></paramdef>
18689  </funcprototype></funcsynopsis>
18690</refsynopsisdiv>
18691<refsect1>
18692 <title>Arguments</title>
18693 <variablelist>
18694  <varlistentry>
18695   <term><parameter>dev</parameter></term>
18696   <listitem>
18697    <para>
18698     DRM device
18699    </para>
18700   </listitem>
18701  </varlistentry>
18702  <varlistentry>
18703   <term><parameter>state</parameter></term>
18704   <listitem>
18705    <para>
18706     the driver state object
18707    </para>
18708   </listitem>
18709  </varlistentry>
18710  <varlistentry>
18711   <term><parameter>async</parameter></term>
18712   <listitem>
18713    <para>
18714     asynchronous commit
18715    </para>
18716   </listitem>
18717  </varlistentry>
18718 </variablelist>
18719</refsect1>
18720<refsect1>
18721<title>Description</title>
18722<para>
18723   This function commits a with <function>drm_atomic_helper_check</function> pre-validated state
18724   object. This can still fail when e.g. the framebuffer reservation fails. For
18725   now this doesn't implement asynchronous commits.
18726   </para><para>
18727
18728   RETURNS
18729   Zero for success or -errno.
18730</para>
18731</refsect1>
18732</refentry>
18733
18734<refentry id="API-drm-atomic-helper-prepare-planes">
18735<refentryinfo>
18736 <title>LINUX</title>
18737 <productname>Kernel Hackers Manual</productname>
18738 <date>July 2017</date>
18739</refentryinfo>
18740<refmeta>
18741 <refentrytitle><phrase>drm_atomic_helper_prepare_planes</phrase></refentrytitle>
18742 <manvolnum>9</manvolnum>
18743 <refmiscinfo class="version">4.1.27</refmiscinfo>
18744</refmeta>
18745<refnamediv>
18746 <refname>drm_atomic_helper_prepare_planes</refname>
18747 <refpurpose>
18748     prepare plane resources before commit
18749 </refpurpose>
18750</refnamediv>
18751<refsynopsisdiv>
18752 <title>Synopsis</title>
18753  <funcsynopsis><funcprototype>
18754   <funcdef>int <function>drm_atomic_helper_prepare_planes </function></funcdef>
18755   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18756   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
18757  </funcprototype></funcsynopsis>
18758</refsynopsisdiv>
18759<refsect1>
18760 <title>Arguments</title>
18761 <variablelist>
18762  <varlistentry>
18763   <term><parameter>dev</parameter></term>
18764   <listitem>
18765    <para>
18766     DRM device
18767    </para>
18768   </listitem>
18769  </varlistentry>
18770  <varlistentry>
18771   <term><parameter>state</parameter></term>
18772   <listitem>
18773    <para>
18774     atomic state object with new state structures
18775    </para>
18776   </listitem>
18777  </varlistentry>
18778 </variablelist>
18779</refsect1>
18780<refsect1>
18781<title>Description</title>
18782<para>
18783   This function prepares plane state, specifically framebuffers, for the new
18784   configuration. If any failure is encountered this function will call
18785   -&gt;cleanup_fb on any already successfully prepared framebuffer.
18786</para>
18787</refsect1>
18788<refsect1>
18789<title>Returns</title>
18790<para>
18791   0 on success, negative error code on failure.
18792</para>
18793</refsect1>
18794</refentry>
18795
18796<refentry id="API-drm-atomic-helper-commit-planes">
18797<refentryinfo>
18798 <title>LINUX</title>
18799 <productname>Kernel Hackers Manual</productname>
18800 <date>July 2017</date>
18801</refentryinfo>
18802<refmeta>
18803 <refentrytitle><phrase>drm_atomic_helper_commit_planes</phrase></refentrytitle>
18804 <manvolnum>9</manvolnum>
18805 <refmiscinfo class="version">4.1.27</refmiscinfo>
18806</refmeta>
18807<refnamediv>
18808 <refname>drm_atomic_helper_commit_planes</refname>
18809 <refpurpose>
18810     commit plane state
18811 </refpurpose>
18812</refnamediv>
18813<refsynopsisdiv>
18814 <title>Synopsis</title>
18815  <funcsynopsis><funcprototype>
18816   <funcdef>void <function>drm_atomic_helper_commit_planes </function></funcdef>
18817   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18818   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
18819  </funcprototype></funcsynopsis>
18820</refsynopsisdiv>
18821<refsect1>
18822 <title>Arguments</title>
18823 <variablelist>
18824  <varlistentry>
18825   <term><parameter>dev</parameter></term>
18826   <listitem>
18827    <para>
18828     DRM device
18829    </para>
18830   </listitem>
18831  </varlistentry>
18832  <varlistentry>
18833   <term><parameter>old_state</parameter></term>
18834   <listitem>
18835    <para>
18836     atomic state object with old state structures
18837    </para>
18838   </listitem>
18839  </varlistentry>
18840 </variablelist>
18841</refsect1>
18842<refsect1>
18843<title>Description</title>
18844<para>
18845   This function commits the new plane state using the plane and atomic helper
18846   functions for planes and crtcs. It assumes that the atomic state has already
18847   been pushed into the relevant object state pointers, since this step can no
18848   longer fail.
18849   </para><para>
18850
18851   It still requires the global state object <parameter>old_state</parameter> to know which planes and
18852   crtcs need to be updated though.
18853</para>
18854</refsect1>
18855</refentry>
18856
18857<refentry id="API-drm-atomic-helper-cleanup-planes">
18858<refentryinfo>
18859 <title>LINUX</title>
18860 <productname>Kernel Hackers Manual</productname>
18861 <date>July 2017</date>
18862</refentryinfo>
18863<refmeta>
18864 <refentrytitle><phrase>drm_atomic_helper_cleanup_planes</phrase></refentrytitle>
18865 <manvolnum>9</manvolnum>
18866 <refmiscinfo class="version">4.1.27</refmiscinfo>
18867</refmeta>
18868<refnamediv>
18869 <refname>drm_atomic_helper_cleanup_planes</refname>
18870 <refpurpose>
18871     cleanup plane resources after commit
18872 </refpurpose>
18873</refnamediv>
18874<refsynopsisdiv>
18875 <title>Synopsis</title>
18876  <funcsynopsis><funcprototype>
18877   <funcdef>void <function>drm_atomic_helper_cleanup_planes </function></funcdef>
18878   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18879   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
18880  </funcprototype></funcsynopsis>
18881</refsynopsisdiv>
18882<refsect1>
18883 <title>Arguments</title>
18884 <variablelist>
18885  <varlistentry>
18886   <term><parameter>dev</parameter></term>
18887   <listitem>
18888    <para>
18889     DRM device
18890    </para>
18891   </listitem>
18892  </varlistentry>
18893  <varlistentry>
18894   <term><parameter>old_state</parameter></term>
18895   <listitem>
18896    <para>
18897     atomic state object with old state structures
18898    </para>
18899   </listitem>
18900  </varlistentry>
18901 </variablelist>
18902</refsect1>
18903<refsect1>
18904<title>Description</title>
18905<para>
18906   This function cleans up plane state, specifically framebuffers, from the old
18907   configuration. Hence the old configuration must be perserved in <parameter>old_state</parameter> to
18908   be able to call this function.
18909   </para><para>
18910
18911   This function must also be called on the new state when the atomic update
18912   fails at any point after calling <function>drm_atomic_helper_prepare_planes</function>.
18913</para>
18914</refsect1>
18915</refentry>
18916
18917<refentry id="API-drm-atomic-helper-swap-state">
18918<refentryinfo>
18919 <title>LINUX</title>
18920 <productname>Kernel Hackers Manual</productname>
18921 <date>July 2017</date>
18922</refentryinfo>
18923<refmeta>
18924 <refentrytitle><phrase>drm_atomic_helper_swap_state</phrase></refentrytitle>
18925 <manvolnum>9</manvolnum>
18926 <refmiscinfo class="version">4.1.27</refmiscinfo>
18927</refmeta>
18928<refnamediv>
18929 <refname>drm_atomic_helper_swap_state</refname>
18930 <refpurpose>
18931     store atomic state into current sw state
18932 </refpurpose>
18933</refnamediv>
18934<refsynopsisdiv>
18935 <title>Synopsis</title>
18936  <funcsynopsis><funcprototype>
18937   <funcdef>void <function>drm_atomic_helper_swap_state </function></funcdef>
18938   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
18939   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
18940  </funcprototype></funcsynopsis>
18941</refsynopsisdiv>
18942<refsect1>
18943 <title>Arguments</title>
18944 <variablelist>
18945  <varlistentry>
18946   <term><parameter>dev</parameter></term>
18947   <listitem>
18948    <para>
18949     DRM device
18950    </para>
18951   </listitem>
18952  </varlistentry>
18953  <varlistentry>
18954   <term><parameter>state</parameter></term>
18955   <listitem>
18956    <para>
18957     atomic state
18958    </para>
18959   </listitem>
18960  </varlistentry>
18961 </variablelist>
18962</refsect1>
18963<refsect1>
18964<title>Description</title>
18965<para>
18966   This function stores the atomic state into the current state pointers in all
18967   driver objects. It should be called after all failing steps have been done
18968   and succeeded, but before the actual hardware state is committed.
18969   </para><para>
18970
18971   For cleanup and error recovery the current state for all changed objects will
18972   be swaped into <parameter>state</parameter>.
18973   </para><para>
18974
18975   With that sequence it fits perfectly into the plane prepare/cleanup sequence:
18976   </para><para>
18977
18978   1. Call <function>drm_atomic_helper_prepare_planes</function> with the staged atomic state.
18979   </para><para>
18980
18981   2. Do any other steps that might fail.
18982   </para><para>
18983
18984   3. Put the staged state into the current state pointers with this function.
18985   </para><para>
18986
18987   4. Actually commit the hardware state.
18988   </para><para>
18989
18990   5. Call drm_atomic_helper_cleanup_planes with <parameter>state</parameter>, which since step 3
18991   contains the old state. Also do any other cleanup required with that state.
18992</para>
18993</refsect1>
18994</refentry>
18995
18996<refentry id="API-drm-atomic-helper-update-plane">
18997<refentryinfo>
18998 <title>LINUX</title>
18999 <productname>Kernel Hackers Manual</productname>
19000 <date>July 2017</date>
19001</refentryinfo>
19002<refmeta>
19003 <refentrytitle><phrase>drm_atomic_helper_update_plane</phrase></refentrytitle>
19004 <manvolnum>9</manvolnum>
19005 <refmiscinfo class="version">4.1.27</refmiscinfo>
19006</refmeta>
19007<refnamediv>
19008 <refname>drm_atomic_helper_update_plane</refname>
19009 <refpurpose>
19010     Helper for primary plane update using atomic
19011 </refpurpose>
19012</refnamediv>
19013<refsynopsisdiv>
19014 <title>Synopsis</title>
19015  <funcsynopsis><funcprototype>
19016   <funcdef>int <function>drm_atomic_helper_update_plane </function></funcdef>
19017   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
19018   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19019   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
19020   <paramdef>int <parameter>crtc_x</parameter></paramdef>
19021   <paramdef>int <parameter>crtc_y</parameter></paramdef>
19022   <paramdef>unsigned int <parameter>crtc_w</parameter></paramdef>
19023   <paramdef>unsigned int <parameter>crtc_h</parameter></paramdef>
19024   <paramdef>uint32_t <parameter>src_x</parameter></paramdef>
19025   <paramdef>uint32_t <parameter>src_y</parameter></paramdef>
19026   <paramdef>uint32_t <parameter>src_w</parameter></paramdef>
19027   <paramdef>uint32_t <parameter>src_h</parameter></paramdef>
19028  </funcprototype></funcsynopsis>
19029</refsynopsisdiv>
19030<refsect1>
19031 <title>Arguments</title>
19032 <variablelist>
19033  <varlistentry>
19034   <term><parameter>plane</parameter></term>
19035   <listitem>
19036    <para>
19037     plane object to update
19038    </para>
19039   </listitem>
19040  </varlistentry>
19041  <varlistentry>
19042   <term><parameter>crtc</parameter></term>
19043   <listitem>
19044    <para>
19045     owning CRTC of owning plane
19046    </para>
19047   </listitem>
19048  </varlistentry>
19049  <varlistentry>
19050   <term><parameter>fb</parameter></term>
19051   <listitem>
19052    <para>
19053     framebuffer to flip onto plane
19054    </para>
19055   </listitem>
19056  </varlistentry>
19057  <varlistentry>
19058   <term><parameter>crtc_x</parameter></term>
19059   <listitem>
19060    <para>
19061     x offset of primary plane on crtc
19062    </para>
19063   </listitem>
19064  </varlistentry>
19065  <varlistentry>
19066   <term><parameter>crtc_y</parameter></term>
19067   <listitem>
19068    <para>
19069     y offset of primary plane on crtc
19070    </para>
19071   </listitem>
19072  </varlistentry>
19073  <varlistentry>
19074   <term><parameter>crtc_w</parameter></term>
19075   <listitem>
19076    <para>
19077     width of primary plane rectangle on crtc
19078    </para>
19079   </listitem>
19080  </varlistentry>
19081  <varlistentry>
19082   <term><parameter>crtc_h</parameter></term>
19083   <listitem>
19084    <para>
19085     height of primary plane rectangle on crtc
19086    </para>
19087   </listitem>
19088  </varlistentry>
19089  <varlistentry>
19090   <term><parameter>src_x</parameter></term>
19091   <listitem>
19092    <para>
19093     x offset of <parameter>fb</parameter> for panning
19094    </para>
19095   </listitem>
19096  </varlistentry>
19097  <varlistentry>
19098   <term><parameter>src_y</parameter></term>
19099   <listitem>
19100    <para>
19101     y offset of <parameter>fb</parameter> for panning
19102    </para>
19103   </listitem>
19104  </varlistentry>
19105  <varlistentry>
19106   <term><parameter>src_w</parameter></term>
19107   <listitem>
19108    <para>
19109     width of source rectangle in <parameter>fb</parameter>
19110    </para>
19111   </listitem>
19112  </varlistentry>
19113  <varlistentry>
19114   <term><parameter>src_h</parameter></term>
19115   <listitem>
19116    <para>
19117     height of source rectangle in <parameter>fb</parameter>
19118    </para>
19119   </listitem>
19120  </varlistentry>
19121 </variablelist>
19122</refsect1>
19123<refsect1>
19124<title>Description</title>
19125<para>
19126   Provides a default plane update handler using the atomic driver interface.
19127</para>
19128</refsect1>
19129<refsect1>
19130<title>RETURNS</title>
19131<para>
19132   Zero on success, error code on failure
19133</para>
19134</refsect1>
19135</refentry>
19136
19137<refentry id="API-drm-atomic-helper-disable-plane">
19138<refentryinfo>
19139 <title>LINUX</title>
19140 <productname>Kernel Hackers Manual</productname>
19141 <date>July 2017</date>
19142</refentryinfo>
19143<refmeta>
19144 <refentrytitle><phrase>drm_atomic_helper_disable_plane</phrase></refentrytitle>
19145 <manvolnum>9</manvolnum>
19146 <refmiscinfo class="version">4.1.27</refmiscinfo>
19147</refmeta>
19148<refnamediv>
19149 <refname>drm_atomic_helper_disable_plane</refname>
19150 <refpurpose>
19151     Helper for primary plane disable using * atomic
19152 </refpurpose>
19153</refnamediv>
19154<refsynopsisdiv>
19155 <title>Synopsis</title>
19156  <funcsynopsis><funcprototype>
19157   <funcdef>int <function>drm_atomic_helper_disable_plane </function></funcdef>
19158   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
19159  </funcprototype></funcsynopsis>
19160</refsynopsisdiv>
19161<refsect1>
19162 <title>Arguments</title>
19163 <variablelist>
19164  <varlistentry>
19165   <term><parameter>plane</parameter></term>
19166   <listitem>
19167    <para>
19168     plane to disable
19169    </para>
19170   </listitem>
19171  </varlistentry>
19172 </variablelist>
19173</refsect1>
19174<refsect1>
19175<title>Description</title>
19176<para>
19177   Provides a default plane disable handler using the atomic driver interface.
19178</para>
19179</refsect1>
19180<refsect1>
19181<title>RETURNS</title>
19182<para>
19183   Zero on success, error code on failure
19184</para>
19185</refsect1>
19186</refentry>
19187
19188<refentry id="API-drm-atomic-helper-set-config">
19189<refentryinfo>
19190 <title>LINUX</title>
19191 <productname>Kernel Hackers Manual</productname>
19192 <date>July 2017</date>
19193</refentryinfo>
19194<refmeta>
19195 <refentrytitle><phrase>drm_atomic_helper_set_config</phrase></refentrytitle>
19196 <manvolnum>9</manvolnum>
19197 <refmiscinfo class="version">4.1.27</refmiscinfo>
19198</refmeta>
19199<refnamediv>
19200 <refname>drm_atomic_helper_set_config</refname>
19201 <refpurpose>
19202     set a new config from userspace
19203 </refpurpose>
19204</refnamediv>
19205<refsynopsisdiv>
19206 <title>Synopsis</title>
19207  <funcsynopsis><funcprototype>
19208   <funcdef>int <function>drm_atomic_helper_set_config </function></funcdef>
19209   <paramdef>struct drm_mode_set * <parameter>set</parameter></paramdef>
19210  </funcprototype></funcsynopsis>
19211</refsynopsisdiv>
19212<refsect1>
19213 <title>Arguments</title>
19214 <variablelist>
19215  <varlistentry>
19216   <term><parameter>set</parameter></term>
19217   <listitem>
19218    <para>
19219     mode set configuration
19220    </para>
19221   </listitem>
19222  </varlistentry>
19223 </variablelist>
19224</refsect1>
19225<refsect1>
19226<title>Description</title>
19227<para>
19228   Provides a default crtc set_config handler using the atomic driver interface.
19229</para>
19230</refsect1>
19231<refsect1>
19232<title>Returns</title>
19233<para>
19234   Returns 0 on success, negative errno numbers on failure.
19235</para>
19236</refsect1>
19237</refentry>
19238
19239<refentry id="API-drm-atomic-helper-crtc-set-property">
19240<refentryinfo>
19241 <title>LINUX</title>
19242 <productname>Kernel Hackers Manual</productname>
19243 <date>July 2017</date>
19244</refentryinfo>
19245<refmeta>
19246 <refentrytitle><phrase>drm_atomic_helper_crtc_set_property</phrase></refentrytitle>
19247 <manvolnum>9</manvolnum>
19248 <refmiscinfo class="version">4.1.27</refmiscinfo>
19249</refmeta>
19250<refnamediv>
19251 <refname>drm_atomic_helper_crtc_set_property</refname>
19252 <refpurpose>
19253     helper for crtc properties
19254 </refpurpose>
19255</refnamediv>
19256<refsynopsisdiv>
19257 <title>Synopsis</title>
19258  <funcsynopsis><funcprototype>
19259   <funcdef>int <function>drm_atomic_helper_crtc_set_property </function></funcdef>
19260   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19261   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
19262   <paramdef>uint64_t <parameter>val</parameter></paramdef>
19263  </funcprototype></funcsynopsis>
19264</refsynopsisdiv>
19265<refsect1>
19266 <title>Arguments</title>
19267 <variablelist>
19268  <varlistentry>
19269   <term><parameter>crtc</parameter></term>
19270   <listitem>
19271    <para>
19272     DRM crtc
19273    </para>
19274   </listitem>
19275  </varlistentry>
19276  <varlistentry>
19277   <term><parameter>property</parameter></term>
19278   <listitem>
19279    <para>
19280     DRM property
19281    </para>
19282   </listitem>
19283  </varlistentry>
19284  <varlistentry>
19285   <term><parameter>val</parameter></term>
19286   <listitem>
19287    <para>
19288     value of property
19289    </para>
19290   </listitem>
19291  </varlistentry>
19292 </variablelist>
19293</refsect1>
19294<refsect1>
19295<title>Description</title>
19296<para>
19297   Provides a default crtc set_property handler using the atomic driver
19298   interface.
19299</para>
19300</refsect1>
19301<refsect1>
19302<title>RETURNS</title>
19303<para>
19304   Zero on success, error code on failure
19305</para>
19306</refsect1>
19307</refentry>
19308
19309<refentry id="API-drm-atomic-helper-plane-set-property">
19310<refentryinfo>
19311 <title>LINUX</title>
19312 <productname>Kernel Hackers Manual</productname>
19313 <date>July 2017</date>
19314</refentryinfo>
19315<refmeta>
19316 <refentrytitle><phrase>drm_atomic_helper_plane_set_property</phrase></refentrytitle>
19317 <manvolnum>9</manvolnum>
19318 <refmiscinfo class="version">4.1.27</refmiscinfo>
19319</refmeta>
19320<refnamediv>
19321 <refname>drm_atomic_helper_plane_set_property</refname>
19322 <refpurpose>
19323     helper for plane properties
19324 </refpurpose>
19325</refnamediv>
19326<refsynopsisdiv>
19327 <title>Synopsis</title>
19328  <funcsynopsis><funcprototype>
19329   <funcdef>int <function>drm_atomic_helper_plane_set_property </function></funcdef>
19330   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
19331   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
19332   <paramdef>uint64_t <parameter>val</parameter></paramdef>
19333  </funcprototype></funcsynopsis>
19334</refsynopsisdiv>
19335<refsect1>
19336 <title>Arguments</title>
19337 <variablelist>
19338  <varlistentry>
19339   <term><parameter>plane</parameter></term>
19340   <listitem>
19341    <para>
19342     DRM plane
19343    </para>
19344   </listitem>
19345  </varlistentry>
19346  <varlistentry>
19347   <term><parameter>property</parameter></term>
19348   <listitem>
19349    <para>
19350     DRM property
19351    </para>
19352   </listitem>
19353  </varlistentry>
19354  <varlistentry>
19355   <term><parameter>val</parameter></term>
19356   <listitem>
19357    <para>
19358     value of property
19359    </para>
19360   </listitem>
19361  </varlistentry>
19362 </variablelist>
19363</refsect1>
19364<refsect1>
19365<title>Description</title>
19366<para>
19367   Provides a default plane set_property handler using the atomic driver
19368   interface.
19369</para>
19370</refsect1>
19371<refsect1>
19372<title>RETURNS</title>
19373<para>
19374   Zero on success, error code on failure
19375</para>
19376</refsect1>
19377</refentry>
19378
19379<refentry id="API-drm-atomic-helper-connector-set-property">
19380<refentryinfo>
19381 <title>LINUX</title>
19382 <productname>Kernel Hackers Manual</productname>
19383 <date>July 2017</date>
19384</refentryinfo>
19385<refmeta>
19386 <refentrytitle><phrase>drm_atomic_helper_connector_set_property</phrase></refentrytitle>
19387 <manvolnum>9</manvolnum>
19388 <refmiscinfo class="version">4.1.27</refmiscinfo>
19389</refmeta>
19390<refnamediv>
19391 <refname>drm_atomic_helper_connector_set_property</refname>
19392 <refpurpose>
19393     helper for connector properties
19394 </refpurpose>
19395</refnamediv>
19396<refsynopsisdiv>
19397 <title>Synopsis</title>
19398  <funcsynopsis><funcprototype>
19399   <funcdef>int <function>drm_atomic_helper_connector_set_property </function></funcdef>
19400   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
19401   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
19402   <paramdef>uint64_t <parameter>val</parameter></paramdef>
19403  </funcprototype></funcsynopsis>
19404</refsynopsisdiv>
19405<refsect1>
19406 <title>Arguments</title>
19407 <variablelist>
19408  <varlistentry>
19409   <term><parameter>connector</parameter></term>
19410   <listitem>
19411    <para>
19412     DRM connector
19413    </para>
19414   </listitem>
19415  </varlistentry>
19416  <varlistentry>
19417   <term><parameter>property</parameter></term>
19418   <listitem>
19419    <para>
19420     DRM property
19421    </para>
19422   </listitem>
19423  </varlistentry>
19424  <varlistentry>
19425   <term><parameter>val</parameter></term>
19426   <listitem>
19427    <para>
19428     value of property
19429    </para>
19430   </listitem>
19431  </varlistentry>
19432 </variablelist>
19433</refsect1>
19434<refsect1>
19435<title>Description</title>
19436<para>
19437   Provides a default connector set_property handler using the atomic driver
19438   interface.
19439</para>
19440</refsect1>
19441<refsect1>
19442<title>RETURNS</title>
19443<para>
19444   Zero on success, error code on failure
19445</para>
19446</refsect1>
19447</refentry>
19448
19449<refentry id="API-drm-atomic-helper-page-flip">
19450<refentryinfo>
19451 <title>LINUX</title>
19452 <productname>Kernel Hackers Manual</productname>
19453 <date>July 2017</date>
19454</refentryinfo>
19455<refmeta>
19456 <refentrytitle><phrase>drm_atomic_helper_page_flip</phrase></refentrytitle>
19457 <manvolnum>9</manvolnum>
19458 <refmiscinfo class="version">4.1.27</refmiscinfo>
19459</refmeta>
19460<refnamediv>
19461 <refname>drm_atomic_helper_page_flip</refname>
19462 <refpurpose>
19463     execute a legacy page flip
19464 </refpurpose>
19465</refnamediv>
19466<refsynopsisdiv>
19467 <title>Synopsis</title>
19468  <funcsynopsis><funcprototype>
19469   <funcdef>int <function>drm_atomic_helper_page_flip </function></funcdef>
19470   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19471   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
19472   <paramdef>struct drm_pending_vblank_event * <parameter>event</parameter></paramdef>
19473   <paramdef>uint32_t <parameter>flags</parameter></paramdef>
19474  </funcprototype></funcsynopsis>
19475</refsynopsisdiv>
19476<refsect1>
19477 <title>Arguments</title>
19478 <variablelist>
19479  <varlistentry>
19480   <term><parameter>crtc</parameter></term>
19481   <listitem>
19482    <para>
19483     DRM crtc
19484    </para>
19485   </listitem>
19486  </varlistentry>
19487  <varlistentry>
19488   <term><parameter>fb</parameter></term>
19489   <listitem>
19490    <para>
19491     DRM framebuffer
19492    </para>
19493   </listitem>
19494  </varlistentry>
19495  <varlistentry>
19496   <term><parameter>event</parameter></term>
19497   <listitem>
19498    <para>
19499     optional DRM event to signal upon completion
19500    </para>
19501   </listitem>
19502  </varlistentry>
19503  <varlistentry>
19504   <term><parameter>flags</parameter></term>
19505   <listitem>
19506    <para>
19507     flip flags for non-vblank sync'ed updates
19508    </para>
19509   </listitem>
19510  </varlistentry>
19511 </variablelist>
19512</refsect1>
19513<refsect1>
19514<title>Description</title>
19515<para>
19516   Provides a default page flip implementation using the atomic driver interface.
19517   </para><para>
19518
19519   Note that for now so called async page flips (i.e. updates which are not
19520   synchronized to vblank) are not supported, since the atomic interfaces have
19521   no provisions for this yet.
19522</para>
19523</refsect1>
19524<refsect1>
19525<title>Returns</title>
19526<para>
19527   Returns 0 on success, negative errno numbers on failure.
19528</para>
19529</refsect1>
19530</refentry>
19531
19532<refentry id="API-drm-atomic-helper-connector-dpms">
19533<refentryinfo>
19534 <title>LINUX</title>
19535 <productname>Kernel Hackers Manual</productname>
19536 <date>July 2017</date>
19537</refentryinfo>
19538<refmeta>
19539 <refentrytitle><phrase>drm_atomic_helper_connector_dpms</phrase></refentrytitle>
19540 <manvolnum>9</manvolnum>
19541 <refmiscinfo class="version">4.1.27</refmiscinfo>
19542</refmeta>
19543<refnamediv>
19544 <refname>drm_atomic_helper_connector_dpms</refname>
19545 <refpurpose>
19546     connector dpms helper implementation
19547 </refpurpose>
19548</refnamediv>
19549<refsynopsisdiv>
19550 <title>Synopsis</title>
19551  <funcsynopsis><funcprototype>
19552   <funcdef>void <function>drm_atomic_helper_connector_dpms </function></funcdef>
19553   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
19554   <paramdef>int <parameter>mode</parameter></paramdef>
19555  </funcprototype></funcsynopsis>
19556</refsynopsisdiv>
19557<refsect1>
19558 <title>Arguments</title>
19559 <variablelist>
19560  <varlistentry>
19561   <term><parameter>connector</parameter></term>
19562   <listitem>
19563    <para>
19564     affected connector
19565    </para>
19566   </listitem>
19567  </varlistentry>
19568  <varlistentry>
19569   <term><parameter>mode</parameter></term>
19570   <listitem>
19571    <para>
19572     DPMS mode
19573    </para>
19574   </listitem>
19575  </varlistentry>
19576 </variablelist>
19577</refsect1>
19578<refsect1>
19579<title>Description</title>
19580<para>
19581   This is the main helper function provided by the atomic helper framework for
19582   implementing the legacy DPMS connector interface. It computes the new desired
19583   -&gt;active state for the corresponding CRTC (if the connector is enabled) and
19584   updates it.
19585</para>
19586</refsect1>
19587</refentry>
19588
19589<refentry id="API-drm-atomic-helper-crtc-reset">
19590<refentryinfo>
19591 <title>LINUX</title>
19592 <productname>Kernel Hackers Manual</productname>
19593 <date>July 2017</date>
19594</refentryinfo>
19595<refmeta>
19596 <refentrytitle><phrase>drm_atomic_helper_crtc_reset</phrase></refentrytitle>
19597 <manvolnum>9</manvolnum>
19598 <refmiscinfo class="version">4.1.27</refmiscinfo>
19599</refmeta>
19600<refnamediv>
19601 <refname>drm_atomic_helper_crtc_reset</refname>
19602 <refpurpose>
19603     default -&gt;reset hook for CRTCs
19604 </refpurpose>
19605</refnamediv>
19606<refsynopsisdiv>
19607 <title>Synopsis</title>
19608  <funcsynopsis><funcprototype>
19609   <funcdef>void <function>drm_atomic_helper_crtc_reset </function></funcdef>
19610   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19611  </funcprototype></funcsynopsis>
19612</refsynopsisdiv>
19613<refsect1>
19614 <title>Arguments</title>
19615 <variablelist>
19616  <varlistentry>
19617   <term><parameter>crtc</parameter></term>
19618   <listitem>
19619    <para>
19620     drm CRTC
19621    </para>
19622   </listitem>
19623  </varlistentry>
19624 </variablelist>
19625</refsect1>
19626<refsect1>
19627<title>Description</title>
19628<para>
19629   Resets the atomic state for <parameter>crtc</parameter> by freeing the state pointer (which might
19630   be NULL, e.g. at driver load time) and allocating a new empty state object.
19631</para>
19632</refsect1>
19633</refentry>
19634
19635<refentry id="API---drm-atomic-helper-crtc-duplicate-state">
19636<refentryinfo>
19637 <title>LINUX</title>
19638 <productname>Kernel Hackers Manual</productname>
19639 <date>July 2017</date>
19640</refentryinfo>
19641<refmeta>
19642 <refentrytitle><phrase>__drm_atomic_helper_crtc_duplicate_state</phrase></refentrytitle>
19643 <manvolnum>9</manvolnum>
19644 <refmiscinfo class="version">4.1.27</refmiscinfo>
19645</refmeta>
19646<refnamediv>
19647 <refname>__drm_atomic_helper_crtc_duplicate_state</refname>
19648 <refpurpose>
19649     copy atomic CRTC state
19650 </refpurpose>
19651</refnamediv>
19652<refsynopsisdiv>
19653 <title>Synopsis</title>
19654  <funcsynopsis><funcprototype>
19655   <funcdef>void <function>__drm_atomic_helper_crtc_duplicate_state </function></funcdef>
19656   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19657   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
19658  </funcprototype></funcsynopsis>
19659</refsynopsisdiv>
19660<refsect1>
19661 <title>Arguments</title>
19662 <variablelist>
19663  <varlistentry>
19664   <term><parameter>crtc</parameter></term>
19665   <listitem>
19666    <para>
19667     CRTC object
19668    </para>
19669   </listitem>
19670  </varlistentry>
19671  <varlistentry>
19672   <term><parameter>state</parameter></term>
19673   <listitem>
19674    <para>
19675     atomic CRTC state
19676    </para>
19677   </listitem>
19678  </varlistentry>
19679 </variablelist>
19680</refsect1>
19681<refsect1>
19682<title>Description</title>
19683<para>
19684   Copies atomic state from a CRTC's current state and resets inferred values.
19685   This is useful for drivers that subclass the CRTC state.
19686</para>
19687</refsect1>
19688</refentry>
19689
19690<refentry id="API-drm-atomic-helper-crtc-duplicate-state">
19691<refentryinfo>
19692 <title>LINUX</title>
19693 <productname>Kernel Hackers Manual</productname>
19694 <date>July 2017</date>
19695</refentryinfo>
19696<refmeta>
19697 <refentrytitle><phrase>drm_atomic_helper_crtc_duplicate_state</phrase></refentrytitle>
19698 <manvolnum>9</manvolnum>
19699 <refmiscinfo class="version">4.1.27</refmiscinfo>
19700</refmeta>
19701<refnamediv>
19702 <refname>drm_atomic_helper_crtc_duplicate_state</refname>
19703 <refpurpose>
19704     default state duplicate hook
19705 </refpurpose>
19706</refnamediv>
19707<refsynopsisdiv>
19708 <title>Synopsis</title>
19709  <funcsynopsis><funcprototype>
19710   <funcdef>struct drm_crtc_state * <function>drm_atomic_helper_crtc_duplicate_state </function></funcdef>
19711   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19712  </funcprototype></funcsynopsis>
19713</refsynopsisdiv>
19714<refsect1>
19715 <title>Arguments</title>
19716 <variablelist>
19717  <varlistentry>
19718   <term><parameter>crtc</parameter></term>
19719   <listitem>
19720    <para>
19721     drm CRTC
19722    </para>
19723   </listitem>
19724  </varlistentry>
19725 </variablelist>
19726</refsect1>
19727<refsect1>
19728<title>Description</title>
19729<para>
19730   Default CRTC state duplicate hook for drivers which don't have their own
19731   subclassed CRTC state structure.
19732</para>
19733</refsect1>
19734</refentry>
19735
19736<refentry id="API---drm-atomic-helper-crtc-destroy-state">
19737<refentryinfo>
19738 <title>LINUX</title>
19739 <productname>Kernel Hackers Manual</productname>
19740 <date>July 2017</date>
19741</refentryinfo>
19742<refmeta>
19743 <refentrytitle><phrase>__drm_atomic_helper_crtc_destroy_state</phrase></refentrytitle>
19744 <manvolnum>9</manvolnum>
19745 <refmiscinfo class="version">4.1.27</refmiscinfo>
19746</refmeta>
19747<refnamediv>
19748 <refname>__drm_atomic_helper_crtc_destroy_state</refname>
19749 <refpurpose>
19750     release CRTC state
19751 </refpurpose>
19752</refnamediv>
19753<refsynopsisdiv>
19754 <title>Synopsis</title>
19755  <funcsynopsis><funcprototype>
19756   <funcdef>void <function>__drm_atomic_helper_crtc_destroy_state </function></funcdef>
19757   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19758   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
19759  </funcprototype></funcsynopsis>
19760</refsynopsisdiv>
19761<refsect1>
19762 <title>Arguments</title>
19763 <variablelist>
19764  <varlistentry>
19765   <term><parameter>crtc</parameter></term>
19766   <listitem>
19767    <para>
19768     CRTC object
19769    </para>
19770   </listitem>
19771  </varlistentry>
19772  <varlistentry>
19773   <term><parameter>state</parameter></term>
19774   <listitem>
19775    <para>
19776     CRTC state object to release
19777    </para>
19778   </listitem>
19779  </varlistentry>
19780 </variablelist>
19781</refsect1>
19782<refsect1>
19783<title>Description</title>
19784<para>
19785   Releases all resources stored in the CRTC state without actually freeing
19786   the memory of the CRTC state. This is useful for drivers that subclass the
19787   CRTC state.
19788</para>
19789</refsect1>
19790</refentry>
19791
19792<refentry id="API-drm-atomic-helper-crtc-destroy-state">
19793<refentryinfo>
19794 <title>LINUX</title>
19795 <productname>Kernel Hackers Manual</productname>
19796 <date>July 2017</date>
19797</refentryinfo>
19798<refmeta>
19799 <refentrytitle><phrase>drm_atomic_helper_crtc_destroy_state</phrase></refentrytitle>
19800 <manvolnum>9</manvolnum>
19801 <refmiscinfo class="version">4.1.27</refmiscinfo>
19802</refmeta>
19803<refnamediv>
19804 <refname>drm_atomic_helper_crtc_destroy_state</refname>
19805 <refpurpose>
19806     default state destroy hook
19807 </refpurpose>
19808</refnamediv>
19809<refsynopsisdiv>
19810 <title>Synopsis</title>
19811  <funcsynopsis><funcprototype>
19812   <funcdef>void <function>drm_atomic_helper_crtc_destroy_state </function></funcdef>
19813   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
19814   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
19815  </funcprototype></funcsynopsis>
19816</refsynopsisdiv>
19817<refsect1>
19818 <title>Arguments</title>
19819 <variablelist>
19820  <varlistentry>
19821   <term><parameter>crtc</parameter></term>
19822   <listitem>
19823    <para>
19824     drm CRTC
19825    </para>
19826   </listitem>
19827  </varlistentry>
19828  <varlistentry>
19829   <term><parameter>state</parameter></term>
19830   <listitem>
19831    <para>
19832     CRTC state object to release
19833    </para>
19834   </listitem>
19835  </varlistentry>
19836 </variablelist>
19837</refsect1>
19838<refsect1>
19839<title>Description</title>
19840<para>
19841   Default CRTC state destroy hook for drivers which don't have their own
19842   subclassed CRTC state structure.
19843</para>
19844</refsect1>
19845</refentry>
19846
19847<refentry id="API-drm-atomic-helper-plane-reset">
19848<refentryinfo>
19849 <title>LINUX</title>
19850 <productname>Kernel Hackers Manual</productname>
19851 <date>July 2017</date>
19852</refentryinfo>
19853<refmeta>
19854 <refentrytitle><phrase>drm_atomic_helper_plane_reset</phrase></refentrytitle>
19855 <manvolnum>9</manvolnum>
19856 <refmiscinfo class="version">4.1.27</refmiscinfo>
19857</refmeta>
19858<refnamediv>
19859 <refname>drm_atomic_helper_plane_reset</refname>
19860 <refpurpose>
19861     default -&gt;reset hook for planes
19862 </refpurpose>
19863</refnamediv>
19864<refsynopsisdiv>
19865 <title>Synopsis</title>
19866  <funcsynopsis><funcprototype>
19867   <funcdef>void <function>drm_atomic_helper_plane_reset </function></funcdef>
19868   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
19869  </funcprototype></funcsynopsis>
19870</refsynopsisdiv>
19871<refsect1>
19872 <title>Arguments</title>
19873 <variablelist>
19874  <varlistentry>
19875   <term><parameter>plane</parameter></term>
19876   <listitem>
19877    <para>
19878     drm plane
19879    </para>
19880   </listitem>
19881  </varlistentry>
19882 </variablelist>
19883</refsect1>
19884<refsect1>
19885<title>Description</title>
19886<para>
19887   Resets the atomic state for <parameter>plane</parameter> by freeing the state pointer (which might
19888   be NULL, e.g. at driver load time) and allocating a new empty state object.
19889</para>
19890</refsect1>
19891</refentry>
19892
19893<refentry id="API---drm-atomic-helper-plane-duplicate-state">
19894<refentryinfo>
19895 <title>LINUX</title>
19896 <productname>Kernel Hackers Manual</productname>
19897 <date>July 2017</date>
19898</refentryinfo>
19899<refmeta>
19900 <refentrytitle><phrase>__drm_atomic_helper_plane_duplicate_state</phrase></refentrytitle>
19901 <manvolnum>9</manvolnum>
19902 <refmiscinfo class="version">4.1.27</refmiscinfo>
19903</refmeta>
19904<refnamediv>
19905 <refname>__drm_atomic_helper_plane_duplicate_state</refname>
19906 <refpurpose>
19907     copy atomic plane state
19908 </refpurpose>
19909</refnamediv>
19910<refsynopsisdiv>
19911 <title>Synopsis</title>
19912  <funcsynopsis><funcprototype>
19913   <funcdef>void <function>__drm_atomic_helper_plane_duplicate_state </function></funcdef>
19914   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
19915   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
19916  </funcprototype></funcsynopsis>
19917</refsynopsisdiv>
19918<refsect1>
19919 <title>Arguments</title>
19920 <variablelist>
19921  <varlistentry>
19922   <term><parameter>plane</parameter></term>
19923   <listitem>
19924    <para>
19925     plane object
19926    </para>
19927   </listitem>
19928  </varlistentry>
19929  <varlistentry>
19930   <term><parameter>state</parameter></term>
19931   <listitem>
19932    <para>
19933     atomic plane state
19934    </para>
19935   </listitem>
19936  </varlistentry>
19937 </variablelist>
19938</refsect1>
19939<refsect1>
19940<title>Description</title>
19941<para>
19942   Copies atomic state from a plane's current state. This is useful for
19943   drivers that subclass the plane state.
19944</para>
19945</refsect1>
19946</refentry>
19947
19948<refentry id="API-drm-atomic-helper-plane-duplicate-state">
19949<refentryinfo>
19950 <title>LINUX</title>
19951 <productname>Kernel Hackers Manual</productname>
19952 <date>July 2017</date>
19953</refentryinfo>
19954<refmeta>
19955 <refentrytitle><phrase>drm_atomic_helper_plane_duplicate_state</phrase></refentrytitle>
19956 <manvolnum>9</manvolnum>
19957 <refmiscinfo class="version">4.1.27</refmiscinfo>
19958</refmeta>
19959<refnamediv>
19960 <refname>drm_atomic_helper_plane_duplicate_state</refname>
19961 <refpurpose>
19962     default state duplicate hook
19963 </refpurpose>
19964</refnamediv>
19965<refsynopsisdiv>
19966 <title>Synopsis</title>
19967  <funcsynopsis><funcprototype>
19968   <funcdef>struct drm_plane_state * <function>drm_atomic_helper_plane_duplicate_state </function></funcdef>
19969   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
19970  </funcprototype></funcsynopsis>
19971</refsynopsisdiv>
19972<refsect1>
19973 <title>Arguments</title>
19974 <variablelist>
19975  <varlistentry>
19976   <term><parameter>plane</parameter></term>
19977   <listitem>
19978    <para>
19979     drm plane
19980    </para>
19981   </listitem>
19982  </varlistentry>
19983 </variablelist>
19984</refsect1>
19985<refsect1>
19986<title>Description</title>
19987<para>
19988   Default plane state duplicate hook for drivers which don't have their own
19989   subclassed plane state structure.
19990</para>
19991</refsect1>
19992</refentry>
19993
19994<refentry id="API---drm-atomic-helper-plane-destroy-state">
19995<refentryinfo>
19996 <title>LINUX</title>
19997 <productname>Kernel Hackers Manual</productname>
19998 <date>July 2017</date>
19999</refentryinfo>
20000<refmeta>
20001 <refentrytitle><phrase>__drm_atomic_helper_plane_destroy_state</phrase></refentrytitle>
20002 <manvolnum>9</manvolnum>
20003 <refmiscinfo class="version">4.1.27</refmiscinfo>
20004</refmeta>
20005<refnamediv>
20006 <refname>__drm_atomic_helper_plane_destroy_state</refname>
20007 <refpurpose>
20008     release plane state
20009 </refpurpose>
20010</refnamediv>
20011<refsynopsisdiv>
20012 <title>Synopsis</title>
20013  <funcsynopsis><funcprototype>
20014   <funcdef>void <function>__drm_atomic_helper_plane_destroy_state </function></funcdef>
20015   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
20016   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
20017  </funcprototype></funcsynopsis>
20018</refsynopsisdiv>
20019<refsect1>
20020 <title>Arguments</title>
20021 <variablelist>
20022  <varlistentry>
20023   <term><parameter>plane</parameter></term>
20024   <listitem>
20025    <para>
20026     plane object
20027    </para>
20028   </listitem>
20029  </varlistentry>
20030  <varlistentry>
20031   <term><parameter>state</parameter></term>
20032   <listitem>
20033    <para>
20034     plane state object to release
20035    </para>
20036   </listitem>
20037  </varlistentry>
20038 </variablelist>
20039</refsect1>
20040<refsect1>
20041<title>Description</title>
20042<para>
20043   Releases all resources stored in the plane state without actually freeing
20044   the memory of the plane state. This is useful for drivers that subclass the
20045   plane state.
20046</para>
20047</refsect1>
20048</refentry>
20049
20050<refentry id="API-drm-atomic-helper-plane-destroy-state">
20051<refentryinfo>
20052 <title>LINUX</title>
20053 <productname>Kernel Hackers Manual</productname>
20054 <date>July 2017</date>
20055</refentryinfo>
20056<refmeta>
20057 <refentrytitle><phrase>drm_atomic_helper_plane_destroy_state</phrase></refentrytitle>
20058 <manvolnum>9</manvolnum>
20059 <refmiscinfo class="version">4.1.27</refmiscinfo>
20060</refmeta>
20061<refnamediv>
20062 <refname>drm_atomic_helper_plane_destroy_state</refname>
20063 <refpurpose>
20064     default state destroy hook
20065 </refpurpose>
20066</refnamediv>
20067<refsynopsisdiv>
20068 <title>Synopsis</title>
20069  <funcsynopsis><funcprototype>
20070   <funcdef>void <function>drm_atomic_helper_plane_destroy_state </function></funcdef>
20071   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
20072   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
20073  </funcprototype></funcsynopsis>
20074</refsynopsisdiv>
20075<refsect1>
20076 <title>Arguments</title>
20077 <variablelist>
20078  <varlistentry>
20079   <term><parameter>plane</parameter></term>
20080   <listitem>
20081    <para>
20082     drm plane
20083    </para>
20084   </listitem>
20085  </varlistentry>
20086  <varlistentry>
20087   <term><parameter>state</parameter></term>
20088   <listitem>
20089    <para>
20090     plane state object to release
20091    </para>
20092   </listitem>
20093  </varlistentry>
20094 </variablelist>
20095</refsect1>
20096<refsect1>
20097<title>Description</title>
20098<para>
20099   Default plane state destroy hook for drivers which don't have their own
20100   subclassed plane state structure.
20101</para>
20102</refsect1>
20103</refentry>
20104
20105<refentry id="API-drm-atomic-helper-connector-reset">
20106<refentryinfo>
20107 <title>LINUX</title>
20108 <productname>Kernel Hackers Manual</productname>
20109 <date>July 2017</date>
20110</refentryinfo>
20111<refmeta>
20112 <refentrytitle><phrase>drm_atomic_helper_connector_reset</phrase></refentrytitle>
20113 <manvolnum>9</manvolnum>
20114 <refmiscinfo class="version">4.1.27</refmiscinfo>
20115</refmeta>
20116<refnamediv>
20117 <refname>drm_atomic_helper_connector_reset</refname>
20118 <refpurpose>
20119     default -&gt;reset hook for connectors
20120 </refpurpose>
20121</refnamediv>
20122<refsynopsisdiv>
20123 <title>Synopsis</title>
20124  <funcsynopsis><funcprototype>
20125   <funcdef>void <function>drm_atomic_helper_connector_reset </function></funcdef>
20126   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
20127  </funcprototype></funcsynopsis>
20128</refsynopsisdiv>
20129<refsect1>
20130 <title>Arguments</title>
20131 <variablelist>
20132  <varlistentry>
20133   <term><parameter>connector</parameter></term>
20134   <listitem>
20135    <para>
20136     drm connector
20137    </para>
20138   </listitem>
20139  </varlistentry>
20140 </variablelist>
20141</refsect1>
20142<refsect1>
20143<title>Description</title>
20144<para>
20145   Resets the atomic state for <parameter>connector</parameter> by freeing the state pointer (which
20146   might be NULL, e.g. at driver load time) and allocating a new empty state
20147   object.
20148</para>
20149</refsect1>
20150</refentry>
20151
20152<refentry id="API---drm-atomic-helper-connector-duplicate-state">
20153<refentryinfo>
20154 <title>LINUX</title>
20155 <productname>Kernel Hackers Manual</productname>
20156 <date>July 2017</date>
20157</refentryinfo>
20158<refmeta>
20159 <refentrytitle><phrase>__drm_atomic_helper_connector_duplicate_state</phrase></refentrytitle>
20160 <manvolnum>9</manvolnum>
20161 <refmiscinfo class="version">4.1.27</refmiscinfo>
20162</refmeta>
20163<refnamediv>
20164 <refname>__drm_atomic_helper_connector_duplicate_state</refname>
20165 <refpurpose>
20166     copy atomic connector state
20167 </refpurpose>
20168</refnamediv>
20169<refsynopsisdiv>
20170 <title>Synopsis</title>
20171  <funcsynopsis><funcprototype>
20172   <funcdef>void <function>__drm_atomic_helper_connector_duplicate_state </function></funcdef>
20173   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
20174   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
20175  </funcprototype></funcsynopsis>
20176</refsynopsisdiv>
20177<refsect1>
20178 <title>Arguments</title>
20179 <variablelist>
20180  <varlistentry>
20181   <term><parameter>connector</parameter></term>
20182   <listitem>
20183    <para>
20184     connector object
20185    </para>
20186   </listitem>
20187  </varlistentry>
20188  <varlistentry>
20189   <term><parameter>state</parameter></term>
20190   <listitem>
20191    <para>
20192     atomic connector state
20193    </para>
20194   </listitem>
20195  </varlistentry>
20196 </variablelist>
20197</refsect1>
20198<refsect1>
20199<title>Description</title>
20200<para>
20201   Copies atomic state from a connector's current state. This is useful for
20202   drivers that subclass the connector state.
20203</para>
20204</refsect1>
20205</refentry>
20206
20207<refentry id="API-drm-atomic-helper-connector-duplicate-state">
20208<refentryinfo>
20209 <title>LINUX</title>
20210 <productname>Kernel Hackers Manual</productname>
20211 <date>July 2017</date>
20212</refentryinfo>
20213<refmeta>
20214 <refentrytitle><phrase>drm_atomic_helper_connector_duplicate_state</phrase></refentrytitle>
20215 <manvolnum>9</manvolnum>
20216 <refmiscinfo class="version">4.1.27</refmiscinfo>
20217</refmeta>
20218<refnamediv>
20219 <refname>drm_atomic_helper_connector_duplicate_state</refname>
20220 <refpurpose>
20221     default state duplicate hook
20222 </refpurpose>
20223</refnamediv>
20224<refsynopsisdiv>
20225 <title>Synopsis</title>
20226  <funcsynopsis><funcprototype>
20227   <funcdef>struct drm_connector_state * <function>drm_atomic_helper_connector_duplicate_state </function></funcdef>
20228   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
20229  </funcprototype></funcsynopsis>
20230</refsynopsisdiv>
20231<refsect1>
20232 <title>Arguments</title>
20233 <variablelist>
20234  <varlistentry>
20235   <term><parameter>connector</parameter></term>
20236   <listitem>
20237    <para>
20238     drm connector
20239    </para>
20240   </listitem>
20241  </varlistentry>
20242 </variablelist>
20243</refsect1>
20244<refsect1>
20245<title>Description</title>
20246<para>
20247   Default connector state duplicate hook for drivers which don't have their own
20248   subclassed connector state structure.
20249</para>
20250</refsect1>
20251</refentry>
20252
20253<refentry id="API---drm-atomic-helper-connector-destroy-state">
20254<refentryinfo>
20255 <title>LINUX</title>
20256 <productname>Kernel Hackers Manual</productname>
20257 <date>July 2017</date>
20258</refentryinfo>
20259<refmeta>
20260 <refentrytitle><phrase>__drm_atomic_helper_connector_destroy_state</phrase></refentrytitle>
20261 <manvolnum>9</manvolnum>
20262 <refmiscinfo class="version">4.1.27</refmiscinfo>
20263</refmeta>
20264<refnamediv>
20265 <refname>__drm_atomic_helper_connector_destroy_state</refname>
20266 <refpurpose>
20267     release connector state
20268 </refpurpose>
20269</refnamediv>
20270<refsynopsisdiv>
20271 <title>Synopsis</title>
20272  <funcsynopsis><funcprototype>
20273   <funcdef>void <function>__drm_atomic_helper_connector_destroy_state </function></funcdef>
20274   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
20275   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
20276  </funcprototype></funcsynopsis>
20277</refsynopsisdiv>
20278<refsect1>
20279 <title>Arguments</title>
20280 <variablelist>
20281  <varlistentry>
20282   <term><parameter>connector</parameter></term>
20283   <listitem>
20284    <para>
20285     connector object
20286    </para>
20287   </listitem>
20288  </varlistentry>
20289  <varlistentry>
20290   <term><parameter>state</parameter></term>
20291   <listitem>
20292    <para>
20293     connector state object to release
20294    </para>
20295   </listitem>
20296  </varlistentry>
20297 </variablelist>
20298</refsect1>
20299<refsect1>
20300<title>Description</title>
20301<para>
20302   Releases all resources stored in the connector state without actually
20303   freeing the memory of the connector state. This is useful for drivers that
20304   subclass the connector state.
20305</para>
20306</refsect1>
20307</refentry>
20308
20309<refentry id="API-drm-atomic-helper-connector-destroy-state">
20310<refentryinfo>
20311 <title>LINUX</title>
20312 <productname>Kernel Hackers Manual</productname>
20313 <date>July 2017</date>
20314</refentryinfo>
20315<refmeta>
20316 <refentrytitle><phrase>drm_atomic_helper_connector_destroy_state</phrase></refentrytitle>
20317 <manvolnum>9</manvolnum>
20318 <refmiscinfo class="version">4.1.27</refmiscinfo>
20319</refmeta>
20320<refnamediv>
20321 <refname>drm_atomic_helper_connector_destroy_state</refname>
20322 <refpurpose>
20323     default state destroy hook
20324 </refpurpose>
20325</refnamediv>
20326<refsynopsisdiv>
20327 <title>Synopsis</title>
20328  <funcsynopsis><funcprototype>
20329   <funcdef>void <function>drm_atomic_helper_connector_destroy_state </function></funcdef>
20330   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
20331   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
20332  </funcprototype></funcsynopsis>
20333</refsynopsisdiv>
20334<refsect1>
20335 <title>Arguments</title>
20336 <variablelist>
20337  <varlistentry>
20338   <term><parameter>connector</parameter></term>
20339   <listitem>
20340    <para>
20341     drm connector
20342    </para>
20343   </listitem>
20344  </varlistentry>
20345  <varlistentry>
20346   <term><parameter>state</parameter></term>
20347   <listitem>
20348    <para>
20349     connector state object to release
20350    </para>
20351   </listitem>
20352  </varlistentry>
20353 </variablelist>
20354</refsect1>
20355<refsect1>
20356<title>Description</title>
20357<para>
20358   Default connector state destroy hook for drivers which don't have their own
20359   subclassed connector state structure.
20360</para>
20361</refsect1>
20362</refentry>
20363
20364    </sect2>
20365    <sect2>
20366      <title>Modeset Helper Functions Reference</title>
20367<!-- include/drm/drm_crtc_helper.h -->
20368<refentry id="API-struct-drm-crtc-helper-funcs">
20369<refentryinfo>
20370 <title>LINUX</title>
20371 <productname>Kernel Hackers Manual</productname>
20372 <date>July 2017</date>
20373</refentryinfo>
20374<refmeta>
20375 <refentrytitle><phrase>struct drm_crtc_helper_funcs</phrase></refentrytitle>
20376 <manvolnum>9</manvolnum>
20377 <refmiscinfo class="version">4.1.27</refmiscinfo>
20378</refmeta>
20379<refnamediv>
20380 <refname>struct drm_crtc_helper_funcs</refname>
20381 <refpurpose>
20382  helper operations for CRTCs
20383 </refpurpose>
20384</refnamediv>
20385<refsynopsisdiv>
20386 <title>Synopsis</title>
20387  <programlisting>
20388struct drm_crtc_helper_funcs {
20389  void (* dpms) (struct drm_crtc *crtc, int mode);
20390  void (* prepare) (struct drm_crtc *crtc);
20391  void (* commit) (struct drm_crtc *crtc);
20392  bool (* mode_fixup) (struct drm_crtc *crtc,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
20393  int (* mode_set) (struct drm_crtc *crtc, struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode, int x, int y,struct drm_framebuffer *old_fb);
20394  void (* mode_set_nofb) (struct drm_crtc *crtc);
20395  int (* mode_set_base) (struct drm_crtc *crtc, int x, int y,struct drm_framebuffer *old_fb);
20396  int (* mode_set_base_atomic) (struct drm_crtc *crtc,struct drm_framebuffer *fb, int x, int y,enum mode_set_atomic);
20397  void (* load_lut) (struct drm_crtc *crtc);
20398  void (* disable) (struct drm_crtc *crtc);
20399  void (* enable) (struct drm_crtc *crtc);
20400  int (* atomic_check) (struct drm_crtc *crtc,struct drm_crtc_state *state);
20401  void (* atomic_begin) (struct drm_crtc *crtc);
20402  void (* atomic_flush) (struct drm_crtc *crtc);
20403};  </programlisting>
20404</refsynopsisdiv>
20405 <refsect1>
20406  <title>Members</title>
20407  <variablelist>
20408    <varlistentry>      <term>dpms</term>
20409      <listitem><para>
20410set power state
20411      </para></listitem>
20412    </varlistentry>
20413    <varlistentry>      <term>prepare</term>
20414      <listitem><para>
20415prepare the CRTC, called before <parameter>mode_set</parameter>
20416      </para></listitem>
20417    </varlistentry>
20418    <varlistentry>      <term>commit</term>
20419      <listitem><para>
20420commit changes to CRTC, called after <parameter>mode_set</parameter>
20421      </para></listitem>
20422    </varlistentry>
20423    <varlistentry>      <term>mode_fixup</term>
20424      <listitem><para>
20425try to fixup proposed mode for this CRTC
20426      </para></listitem>
20427    </varlistentry>
20428    <varlistentry>      <term>mode_set</term>
20429      <listitem><para>
20430set this mode
20431      </para></listitem>
20432    </varlistentry>
20433    <varlistentry>      <term>mode_set_nofb</term>
20434      <listitem><para>
20435set mode only (no scanout buffer attached)
20436      </para></listitem>
20437    </varlistentry>
20438    <varlistentry>      <term>mode_set_base</term>
20439      <listitem><para>
20440update the scanout buffer
20441      </para></listitem>
20442    </varlistentry>
20443    <varlistentry>      <term>mode_set_base_atomic</term>
20444      <listitem><para>
20445non-blocking mode set (used for kgdb support)
20446      </para></listitem>
20447    </varlistentry>
20448    <varlistentry>      <term>load_lut</term>
20449      <listitem><para>
20450load color palette
20451      </para></listitem>
20452    </varlistentry>
20453    <varlistentry>      <term>disable</term>
20454      <listitem><para>
20455disable CRTC when no longer in use
20456      </para></listitem>
20457    </varlistentry>
20458    <varlistentry>      <term>enable</term>
20459      <listitem><para>
20460enable CRTC
20461      </para></listitem>
20462    </varlistentry>
20463    <varlistentry>      <term>atomic_check</term>
20464      <listitem><para>
20465check for validity of an atomic state
20466      </para></listitem>
20467    </varlistentry>
20468    <varlistentry>      <term>atomic_begin</term>
20469      <listitem><para>
20470begin atomic update
20471      </para></listitem>
20472    </varlistentry>
20473    <varlistentry>      <term>atomic_flush</term>
20474      <listitem><para>
20475flush atomic update
20476      </para></listitem>
20477    </varlistentry>
20478  </variablelist>
20479 </refsect1>
20480<refsect1>
20481<title>Description</title>
20482<para>
20483   The helper operations are called by the mid-layer CRTC helper.
20484   </para><para>
20485
20486   Note that with atomic helpers <parameter>dpms</parameter>, <parameter>prepare</parameter> and <parameter>commit</parameter> hooks are
20487   deprecated. Used <parameter>enable</parameter> and <parameter>disable</parameter> instead exclusively.
20488   </para><para>
20489
20490   With legacy crtc helpers there's a big semantic difference between <parameter>disable</parameter>
20491</para>
20492</refsect1>
20493<refsect1>
20494<title>and the other hooks</title>
20495<para>
20496   <parameter>disable</parameter> also needs to release any resources acquired in
20497   <parameter>mode_set</parameter> (like shared PLLs).
20498</para>
20499</refsect1>
20500</refentry>
20501
20502<refentry id="API-struct-drm-encoder-helper-funcs">
20503<refentryinfo>
20504 <title>LINUX</title>
20505 <productname>Kernel Hackers Manual</productname>
20506 <date>July 2017</date>
20507</refentryinfo>
20508<refmeta>
20509 <refentrytitle><phrase>struct drm_encoder_helper_funcs</phrase></refentrytitle>
20510 <manvolnum>9</manvolnum>
20511 <refmiscinfo class="version">4.1.27</refmiscinfo>
20512</refmeta>
20513<refnamediv>
20514 <refname>struct drm_encoder_helper_funcs</refname>
20515 <refpurpose>
20516     helper operations for encoders
20517 </refpurpose>
20518</refnamediv>
20519<refsynopsisdiv>
20520 <title>Synopsis</title>
20521  <programlisting>
20522struct drm_encoder_helper_funcs {
20523  void (* dpms) (struct drm_encoder *encoder, int mode);
20524  void (* save) (struct drm_encoder *encoder);
20525  void (* restore) (struct drm_encoder *encoder);
20526  bool (* mode_fixup) (struct drm_encoder *encoder,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
20527  void (* prepare) (struct drm_encoder *encoder);
20528  void (* commit) (struct drm_encoder *encoder);
20529  void (* mode_set) (struct drm_encoder *encoder,struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
20530  struct drm_crtc *(* get_crtc) (struct drm_encoder *encoder);
20531  enum drm_connector_status (* detect) (struct drm_encoder *encoder,struct drm_connector *connector);
20532  void (* disable) (struct drm_encoder *encoder);
20533  void (* enable) (struct drm_encoder *encoder);
20534  int (* atomic_check) (struct drm_encoder *encoder,struct drm_crtc_state *crtc_state,struct drm_connector_state *conn_state);
20535};  </programlisting>
20536</refsynopsisdiv>
20537 <refsect1>
20538  <title>Members</title>
20539  <variablelist>
20540    <varlistentry>      <term>dpms</term>
20541      <listitem><para>
20542   set power state
20543      </para></listitem>
20544    </varlistentry>
20545    <varlistentry>      <term>save</term>
20546      <listitem><para>
20547   save connector state
20548      </para></listitem>
20549    </varlistentry>
20550    <varlistentry>      <term>restore</term>
20551      <listitem><para>
20552   restore connector state
20553      </para></listitem>
20554    </varlistentry>
20555    <varlistentry>      <term>mode_fixup</term>
20556      <listitem><para>
20557   try to fixup proposed mode for this connector
20558      </para></listitem>
20559    </varlistentry>
20560    <varlistentry>      <term>prepare</term>
20561      <listitem><para>
20562   part of the disable sequence, called before the CRTC modeset
20563      </para></listitem>
20564    </varlistentry>
20565    <varlistentry>      <term>commit</term>
20566      <listitem><para>
20567   called after the CRTC modeset
20568      </para></listitem>
20569    </varlistentry>
20570    <varlistentry>      <term>mode_set</term>
20571      <listitem><para>
20572   set this mode, optional for atomic helpers
20573      </para></listitem>
20574    </varlistentry>
20575    <varlistentry>      <term>get_crtc</term>
20576      <listitem><para>
20577   return CRTC that the encoder is currently attached to
20578      </para></listitem>
20579    </varlistentry>
20580    <varlistentry>      <term>detect</term>
20581      <listitem><para>
20582   connection status detection
20583      </para></listitem>
20584    </varlistentry>
20585    <varlistentry>      <term>disable</term>
20586      <listitem><para>
20587   disable encoder when not in use (overrides DPMS off)
20588      </para></listitem>
20589    </varlistentry>
20590    <varlistentry>      <term>enable</term>
20591      <listitem><para>
20592   enable encoder
20593      </para></listitem>
20594    </varlistentry>
20595    <varlistentry>      <term>atomic_check</term>
20596      <listitem><para>
20597   check for validity of an atomic update
20598      </para></listitem>
20599    </varlistentry>
20600  </variablelist>
20601 </refsect1>
20602<refsect1>
20603<title>Description</title>
20604<para>
20605   The helper operations are called by the mid-layer CRTC helper.
20606   </para><para>
20607
20608   Note that with atomic helpers <parameter>dpms</parameter>, <parameter>prepare</parameter> and <parameter>commit</parameter> hooks are
20609   deprecated. Used <parameter>enable</parameter> and <parameter>disable</parameter> instead exclusively.
20610   </para><para>
20611
20612   With legacy crtc helpers there's a big semantic difference between <parameter>disable</parameter>
20613</para>
20614</refsect1>
20615<refsect1>
20616<title>and the other hooks</title>
20617<para>
20618   <parameter>disable</parameter> also needs to release any resources acquired in
20619   <parameter>mode_set</parameter> (like shared PLLs).
20620</para>
20621</refsect1>
20622</refentry>
20623
20624<refentry id="API-struct-drm-connector-helper-funcs">
20625<refentryinfo>
20626 <title>LINUX</title>
20627 <productname>Kernel Hackers Manual</productname>
20628 <date>July 2017</date>
20629</refentryinfo>
20630<refmeta>
20631 <refentrytitle><phrase>struct drm_connector_helper_funcs</phrase></refentrytitle>
20632 <manvolnum>9</manvolnum>
20633 <refmiscinfo class="version">4.1.27</refmiscinfo>
20634</refmeta>
20635<refnamediv>
20636 <refname>struct drm_connector_helper_funcs</refname>
20637 <refpurpose>
20638     helper operations for connectors
20639 </refpurpose>
20640</refnamediv>
20641<refsynopsisdiv>
20642 <title>Synopsis</title>
20643  <programlisting>
20644struct drm_connector_helper_funcs {
20645  int (* get_modes) (struct drm_connector *connector);
20646  enum drm_mode_status (* mode_valid) (struct drm_connector *connector,struct drm_display_mode *mode);
20647  struct drm_encoder *(* best_encoder) (struct drm_connector *connector);
20648};  </programlisting>
20649</refsynopsisdiv>
20650 <refsect1>
20651  <title>Members</title>
20652  <variablelist>
20653    <varlistentry>      <term>get_modes</term>
20654      <listitem><para>
20655   get mode list for this connector
20656      </para></listitem>
20657    </varlistentry>
20658    <varlistentry>      <term>mode_valid</term>
20659      <listitem><para>
20660   is this mode valid on the given connector? (optional)
20661      </para></listitem>
20662    </varlistentry>
20663    <varlistentry>      <term>best_encoder</term>
20664      <listitem><para>
20665   return the preferred encoder for this connector
20666      </para></listitem>
20667    </varlistentry>
20668  </variablelist>
20669 </refsect1>
20670<refsect1>
20671<title>Description</title>
20672<para>
20673   The helper operations are called by the mid-layer CRTC helper.
20674</para>
20675</refsect1>
20676</refentry>
20677
20678<!-- drivers/gpu/drm/drm_crtc_helper.c -->
20679<refentry id="API-drm-helper-move-panel-connectors-to-head">
20680<refentryinfo>
20681 <title>LINUX</title>
20682 <productname>Kernel Hackers Manual</productname>
20683 <date>July 2017</date>
20684</refentryinfo>
20685<refmeta>
20686 <refentrytitle><phrase>drm_helper_move_panel_connectors_to_head</phrase></refentrytitle>
20687 <manvolnum>9</manvolnum>
20688 <refmiscinfo class="version">4.1.27</refmiscinfo>
20689</refmeta>
20690<refnamediv>
20691 <refname>drm_helper_move_panel_connectors_to_head</refname>
20692 <refpurpose>
20693  move panels to the front in the connector list
20694 </refpurpose>
20695</refnamediv>
20696<refsynopsisdiv>
20697 <title>Synopsis</title>
20698  <funcsynopsis><funcprototype>
20699   <funcdef>void <function>drm_helper_move_panel_connectors_to_head </function></funcdef>
20700   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
20701  </funcprototype></funcsynopsis>
20702</refsynopsisdiv>
20703<refsect1>
20704 <title>Arguments</title>
20705 <variablelist>
20706  <varlistentry>
20707   <term><parameter>dev</parameter></term>
20708   <listitem>
20709    <para>
20710     drm device to operate on
20711    </para>
20712   </listitem>
20713  </varlistentry>
20714 </variablelist>
20715</refsect1>
20716<refsect1>
20717<title>Description</title>
20718<para>
20719   Some userspace presumes that the first connected connector is the main
20720   display, where it's supposed to display e.g. the login screen. For
20721   laptops, this should be the main panel. Use this function to sort all
20722   (eDP/LVDS) panels to the front of the connector list, instead of
20723   painstakingly trying to initialize them in the right order.
20724</para>
20725</refsect1>
20726</refentry>
20727
20728<refentry id="API-drm-helper-encoder-in-use">
20729<refentryinfo>
20730 <title>LINUX</title>
20731 <productname>Kernel Hackers Manual</productname>
20732 <date>July 2017</date>
20733</refentryinfo>
20734<refmeta>
20735 <refentrytitle><phrase>drm_helper_encoder_in_use</phrase></refentrytitle>
20736 <manvolnum>9</manvolnum>
20737 <refmiscinfo class="version">4.1.27</refmiscinfo>
20738</refmeta>
20739<refnamediv>
20740 <refname>drm_helper_encoder_in_use</refname>
20741 <refpurpose>
20742     check if a given encoder is in use
20743 </refpurpose>
20744</refnamediv>
20745<refsynopsisdiv>
20746 <title>Synopsis</title>
20747  <funcsynopsis><funcprototype>
20748   <funcdef>bool <function>drm_helper_encoder_in_use </function></funcdef>
20749   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
20750  </funcprototype></funcsynopsis>
20751</refsynopsisdiv>
20752<refsect1>
20753 <title>Arguments</title>
20754 <variablelist>
20755  <varlistentry>
20756   <term><parameter>encoder</parameter></term>
20757   <listitem>
20758    <para>
20759     encoder to check
20760    </para>
20761   </listitem>
20762  </varlistentry>
20763 </variablelist>
20764</refsect1>
20765<refsect1>
20766<title>Description</title>
20767<para>
20768   Checks whether <parameter>encoder</parameter> is with the current mode setting output configuration
20769   in use by any connector. This doesn't mean that it is actually enabled since
20770   the DPMS state is tracked separately.
20771</para>
20772</refsect1>
20773<refsect1>
20774<title>Returns</title>
20775<para>
20776   True if <parameter>encoder</parameter> is used, false otherwise.
20777</para>
20778</refsect1>
20779</refentry>
20780
20781<refentry id="API-drm-helper-crtc-in-use">
20782<refentryinfo>
20783 <title>LINUX</title>
20784 <productname>Kernel Hackers Manual</productname>
20785 <date>July 2017</date>
20786</refentryinfo>
20787<refmeta>
20788 <refentrytitle><phrase>drm_helper_crtc_in_use</phrase></refentrytitle>
20789 <manvolnum>9</manvolnum>
20790 <refmiscinfo class="version">4.1.27</refmiscinfo>
20791</refmeta>
20792<refnamediv>
20793 <refname>drm_helper_crtc_in_use</refname>
20794 <refpurpose>
20795     check if a given CRTC is in a mode_config
20796 </refpurpose>
20797</refnamediv>
20798<refsynopsisdiv>
20799 <title>Synopsis</title>
20800  <funcsynopsis><funcprototype>
20801   <funcdef>bool <function>drm_helper_crtc_in_use </function></funcdef>
20802   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
20803  </funcprototype></funcsynopsis>
20804</refsynopsisdiv>
20805<refsect1>
20806 <title>Arguments</title>
20807 <variablelist>
20808  <varlistentry>
20809   <term><parameter>crtc</parameter></term>
20810   <listitem>
20811    <para>
20812     CRTC to check
20813    </para>
20814   </listitem>
20815  </varlistentry>
20816 </variablelist>
20817</refsect1>
20818<refsect1>
20819<title>Description</title>
20820<para>
20821   Checks whether <parameter>crtc</parameter> is with the current mode setting output configuration
20822   in use by any connector. This doesn't mean that it is actually enabled since
20823   the DPMS state is tracked separately.
20824</para>
20825</refsect1>
20826<refsect1>
20827<title>Returns</title>
20828<para>
20829   True if <parameter>crtc</parameter> is used, false otherwise.
20830</para>
20831</refsect1>
20832</refentry>
20833
20834<refentry id="API-drm-helper-disable-unused-functions">
20835<refentryinfo>
20836 <title>LINUX</title>
20837 <productname>Kernel Hackers Manual</productname>
20838 <date>July 2017</date>
20839</refentryinfo>
20840<refmeta>
20841 <refentrytitle><phrase>drm_helper_disable_unused_functions</phrase></refentrytitle>
20842 <manvolnum>9</manvolnum>
20843 <refmiscinfo class="version">4.1.27</refmiscinfo>
20844</refmeta>
20845<refnamediv>
20846 <refname>drm_helper_disable_unused_functions</refname>
20847 <refpurpose>
20848     disable unused objects
20849 </refpurpose>
20850</refnamediv>
20851<refsynopsisdiv>
20852 <title>Synopsis</title>
20853  <funcsynopsis><funcprototype>
20854   <funcdef>void <function>drm_helper_disable_unused_functions </function></funcdef>
20855   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
20856  </funcprototype></funcsynopsis>
20857</refsynopsisdiv>
20858<refsect1>
20859 <title>Arguments</title>
20860 <variablelist>
20861  <varlistentry>
20862   <term><parameter>dev</parameter></term>
20863   <listitem>
20864    <para>
20865     DRM device
20866    </para>
20867   </listitem>
20868  </varlistentry>
20869 </variablelist>
20870</refsect1>
20871<refsect1>
20872<title>Description</title>
20873<para>
20874   This function walks through the entire mode setting configuration of <parameter>dev</parameter>. It
20875   will remove any crtc links of unused encoders and encoder links of
20876   disconnected connectors. Then it will disable all unused encoders and crtcs
20877   either by calling their disable callback if available or by calling their
20878   dpms callback with DRM_MODE_DPMS_OFF.
20879</para>
20880</refsect1>
20881</refentry>
20882
20883<refentry id="API-drm-crtc-helper-set-mode">
20884<refentryinfo>
20885 <title>LINUX</title>
20886 <productname>Kernel Hackers Manual</productname>
20887 <date>July 2017</date>
20888</refentryinfo>
20889<refmeta>
20890 <refentrytitle><phrase>drm_crtc_helper_set_mode</phrase></refentrytitle>
20891 <manvolnum>9</manvolnum>
20892 <refmiscinfo class="version">4.1.27</refmiscinfo>
20893</refmeta>
20894<refnamediv>
20895 <refname>drm_crtc_helper_set_mode</refname>
20896 <refpurpose>
20897     internal helper to set a mode
20898 </refpurpose>
20899</refnamediv>
20900<refsynopsisdiv>
20901 <title>Synopsis</title>
20902  <funcsynopsis><funcprototype>
20903   <funcdef>bool <function>drm_crtc_helper_set_mode </function></funcdef>
20904   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
20905   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
20906   <paramdef>int <parameter>x</parameter></paramdef>
20907   <paramdef>int <parameter>y</parameter></paramdef>
20908   <paramdef>struct drm_framebuffer * <parameter>old_fb</parameter></paramdef>
20909  </funcprototype></funcsynopsis>
20910</refsynopsisdiv>
20911<refsect1>
20912 <title>Arguments</title>
20913 <variablelist>
20914  <varlistentry>
20915   <term><parameter>crtc</parameter></term>
20916   <listitem>
20917    <para>
20918     CRTC to program
20919    </para>
20920   </listitem>
20921  </varlistentry>
20922  <varlistentry>
20923   <term><parameter>mode</parameter></term>
20924   <listitem>
20925    <para>
20926     mode to use
20927    </para>
20928   </listitem>
20929  </varlistentry>
20930  <varlistentry>
20931   <term><parameter>x</parameter></term>
20932   <listitem>
20933    <para>
20934     horizontal offset into the surface
20935    </para>
20936   </listitem>
20937  </varlistentry>
20938  <varlistentry>
20939   <term><parameter>y</parameter></term>
20940   <listitem>
20941    <para>
20942     vertical offset into the surface
20943    </para>
20944   </listitem>
20945  </varlistentry>
20946  <varlistentry>
20947   <term><parameter>old_fb</parameter></term>
20948   <listitem>
20949    <para>
20950     old framebuffer, for cleanup
20951    </para>
20952   </listitem>
20953  </varlistentry>
20954 </variablelist>
20955</refsect1>
20956<refsect1>
20957<title>Description</title>
20958<para>
20959   Try to set <parameter>mode</parameter> on <parameter>crtc</parameter>.  Give <parameter>crtc</parameter> and its associated connectors a chance
20960   to fixup or reject the mode prior to trying to set it. This is an internal
20961   helper that drivers could e.g. use to update properties that require the
20962   entire output pipe to be disabled and re-enabled in a new configuration. For
20963   example for changing whether audio is enabled on a hdmi link or for changing
20964   panel fitter or dither attributes. It is also called by the
20965   <function>drm_crtc_helper_set_config</function> helper function to drive the mode setting
20966   sequence.
20967</para>
20968</refsect1>
20969<refsect1>
20970<title>Returns</title>
20971<para>
20972   True if the mode was set successfully, false otherwise.
20973</para>
20974</refsect1>
20975</refentry>
20976
20977<refentry id="API-drm-crtc-helper-set-config">
20978<refentryinfo>
20979 <title>LINUX</title>
20980 <productname>Kernel Hackers Manual</productname>
20981 <date>July 2017</date>
20982</refentryinfo>
20983<refmeta>
20984 <refentrytitle><phrase>drm_crtc_helper_set_config</phrase></refentrytitle>
20985 <manvolnum>9</manvolnum>
20986 <refmiscinfo class="version">4.1.27</refmiscinfo>
20987</refmeta>
20988<refnamediv>
20989 <refname>drm_crtc_helper_set_config</refname>
20990 <refpurpose>
20991     set a new config from userspace
20992 </refpurpose>
20993</refnamediv>
20994<refsynopsisdiv>
20995 <title>Synopsis</title>
20996  <funcsynopsis><funcprototype>
20997   <funcdef>int <function>drm_crtc_helper_set_config </function></funcdef>
20998   <paramdef>struct drm_mode_set * <parameter>set</parameter></paramdef>
20999  </funcprototype></funcsynopsis>
21000</refsynopsisdiv>
21001<refsect1>
21002 <title>Arguments</title>
21003 <variablelist>
21004  <varlistentry>
21005   <term><parameter>set</parameter></term>
21006   <listitem>
21007    <para>
21008     mode set configuration
21009    </para>
21010   </listitem>
21011  </varlistentry>
21012 </variablelist>
21013</refsect1>
21014<refsect1>
21015<title>Description</title>
21016<para>
21017   Setup a new configuration, provided by the upper layers (either an ioctl call
21018   from userspace or internally e.g. from the fbdev support code) in <parameter>set</parameter>, and
21019   enable it. This is the main helper functions for drivers that implement
21020   kernel mode setting with the crtc helper functions and the assorted
21021   -&gt;<function>prepare</function>, -&gt;<function>modeset</function> and -&gt;<function>commit</function> helper callbacks.
21022</para>
21023</refsect1>
21024<refsect1>
21025<title>Returns</title>
21026<para>
21027   Returns 0 on success, negative errno numbers on failure.
21028</para>
21029</refsect1>
21030</refentry>
21031
21032<refentry id="API-drm-helper-connector-dpms">
21033<refentryinfo>
21034 <title>LINUX</title>
21035 <productname>Kernel Hackers Manual</productname>
21036 <date>July 2017</date>
21037</refentryinfo>
21038<refmeta>
21039 <refentrytitle><phrase>drm_helper_connector_dpms</phrase></refentrytitle>
21040 <manvolnum>9</manvolnum>
21041 <refmiscinfo class="version">4.1.27</refmiscinfo>
21042</refmeta>
21043<refnamediv>
21044 <refname>drm_helper_connector_dpms</refname>
21045 <refpurpose>
21046     connector dpms helper implementation
21047 </refpurpose>
21048</refnamediv>
21049<refsynopsisdiv>
21050 <title>Synopsis</title>
21051  <funcsynopsis><funcprototype>
21052   <funcdef>void <function>drm_helper_connector_dpms </function></funcdef>
21053   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
21054   <paramdef>int <parameter>mode</parameter></paramdef>
21055  </funcprototype></funcsynopsis>
21056</refsynopsisdiv>
21057<refsect1>
21058 <title>Arguments</title>
21059 <variablelist>
21060  <varlistentry>
21061   <term><parameter>connector</parameter></term>
21062   <listitem>
21063    <para>
21064     affected connector
21065    </para>
21066   </listitem>
21067  </varlistentry>
21068  <varlistentry>
21069   <term><parameter>mode</parameter></term>
21070   <listitem>
21071    <para>
21072     DPMS mode
21073    </para>
21074   </listitem>
21075  </varlistentry>
21076 </variablelist>
21077</refsect1>
21078<refsect1>
21079<title>Description</title>
21080<para>
21081   This is the main helper function provided by the crtc helper framework for
21082   implementing the DPMS connector attribute. It computes the new desired DPMS
21083   state for all encoders and crtcs in the output mesh and calls the -&gt;<function>dpms</function>
21084   callback provided by the driver appropriately.
21085</para>
21086</refsect1>
21087</refentry>
21088
21089<refentry id="API-drm-helper-mode-fill-fb-struct">
21090<refentryinfo>
21091 <title>LINUX</title>
21092 <productname>Kernel Hackers Manual</productname>
21093 <date>July 2017</date>
21094</refentryinfo>
21095<refmeta>
21096 <refentrytitle><phrase>drm_helper_mode_fill_fb_struct</phrase></refentrytitle>
21097 <manvolnum>9</manvolnum>
21098 <refmiscinfo class="version">4.1.27</refmiscinfo>
21099</refmeta>
21100<refnamediv>
21101 <refname>drm_helper_mode_fill_fb_struct</refname>
21102 <refpurpose>
21103     fill out framebuffer metadata
21104 </refpurpose>
21105</refnamediv>
21106<refsynopsisdiv>
21107 <title>Synopsis</title>
21108  <funcsynopsis><funcprototype>
21109   <funcdef>void <function>drm_helper_mode_fill_fb_struct </function></funcdef>
21110   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
21111   <paramdef>struct drm_mode_fb_cmd2 * <parameter>mode_cmd</parameter></paramdef>
21112  </funcprototype></funcsynopsis>
21113</refsynopsisdiv>
21114<refsect1>
21115 <title>Arguments</title>
21116 <variablelist>
21117  <varlistentry>
21118   <term><parameter>fb</parameter></term>
21119   <listitem>
21120    <para>
21121     drm_framebuffer object to fill out
21122    </para>
21123   </listitem>
21124  </varlistentry>
21125  <varlistentry>
21126   <term><parameter>mode_cmd</parameter></term>
21127   <listitem>
21128    <para>
21129     metadata from the userspace fb creation request
21130    </para>
21131   </listitem>
21132  </varlistentry>
21133 </variablelist>
21134</refsect1>
21135<refsect1>
21136<title>Description</title>
21137<para>
21138   This helper can be used in a drivers fb_create callback to pre-fill the fb's
21139   metadata fields.
21140</para>
21141</refsect1>
21142</refentry>
21143
21144<refentry id="API-drm-helper-resume-force-mode">
21145<refentryinfo>
21146 <title>LINUX</title>
21147 <productname>Kernel Hackers Manual</productname>
21148 <date>July 2017</date>
21149</refentryinfo>
21150<refmeta>
21151 <refentrytitle><phrase>drm_helper_resume_force_mode</phrase></refentrytitle>
21152 <manvolnum>9</manvolnum>
21153 <refmiscinfo class="version">4.1.27</refmiscinfo>
21154</refmeta>
21155<refnamediv>
21156 <refname>drm_helper_resume_force_mode</refname>
21157 <refpurpose>
21158     force-restore mode setting configuration
21159 </refpurpose>
21160</refnamediv>
21161<refsynopsisdiv>
21162 <title>Synopsis</title>
21163  <funcsynopsis><funcprototype>
21164   <funcdef>void <function>drm_helper_resume_force_mode </function></funcdef>
21165   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21166  </funcprototype></funcsynopsis>
21167</refsynopsisdiv>
21168<refsect1>
21169 <title>Arguments</title>
21170 <variablelist>
21171  <varlistentry>
21172   <term><parameter>dev</parameter></term>
21173   <listitem>
21174    <para>
21175     drm_device which should be restored
21176    </para>
21177   </listitem>
21178  </varlistentry>
21179 </variablelist>
21180</refsect1>
21181<refsect1>
21182<title>Description</title>
21183<para>
21184   Drivers which use the mode setting helpers can use this function to
21185   force-restore the mode setting configuration e.g. on resume or when something
21186   else might have trampled over the hw state (like some overzealous old BIOSen
21187   tended to do).
21188   </para><para>
21189
21190   This helper doesn't provide a error return value since restoring the old
21191   config should never fail due to resource allocation issues since the driver
21192   has successfully set the restored configuration already. Hence this should
21193   boil down to the equivalent of a few dpms on calls, which also don't provide
21194   an error code.
21195   </para><para>
21196
21197   Drivers where simply restoring an old configuration again might fail (e.g.
21198   due to slight differences in allocating shared resources when the
21199   configuration is restored in a different order than when userspace set it up)
21200   need to use their own restore logic.
21201</para>
21202</refsect1>
21203</refentry>
21204
21205<refentry id="API-drm-helper-crtc-mode-set">
21206<refentryinfo>
21207 <title>LINUX</title>
21208 <productname>Kernel Hackers Manual</productname>
21209 <date>July 2017</date>
21210</refentryinfo>
21211<refmeta>
21212 <refentrytitle><phrase>drm_helper_crtc_mode_set</phrase></refentrytitle>
21213 <manvolnum>9</manvolnum>
21214 <refmiscinfo class="version">4.1.27</refmiscinfo>
21215</refmeta>
21216<refnamediv>
21217 <refname>drm_helper_crtc_mode_set</refname>
21218 <refpurpose>
21219     mode_set implementation for atomic plane helpers
21220 </refpurpose>
21221</refnamediv>
21222<refsynopsisdiv>
21223 <title>Synopsis</title>
21224  <funcsynopsis><funcprototype>
21225   <funcdef>int <function>drm_helper_crtc_mode_set </function></funcdef>
21226   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
21227   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
21228   <paramdef>struct drm_display_mode * <parameter>adjusted_mode</parameter></paramdef>
21229   <paramdef>int <parameter>x</parameter></paramdef>
21230   <paramdef>int <parameter>y</parameter></paramdef>
21231   <paramdef>struct drm_framebuffer * <parameter>old_fb</parameter></paramdef>
21232  </funcprototype></funcsynopsis>
21233</refsynopsisdiv>
21234<refsect1>
21235 <title>Arguments</title>
21236 <variablelist>
21237  <varlistentry>
21238   <term><parameter>crtc</parameter></term>
21239   <listitem>
21240    <para>
21241     DRM CRTC
21242    </para>
21243   </listitem>
21244  </varlistentry>
21245  <varlistentry>
21246   <term><parameter>mode</parameter></term>
21247   <listitem>
21248    <para>
21249     DRM display mode which userspace requested
21250    </para>
21251   </listitem>
21252  </varlistentry>
21253  <varlistentry>
21254   <term><parameter>adjusted_mode</parameter></term>
21255   <listitem>
21256    <para>
21257     DRM display mode adjusted by -&gt;mode_fixup callbacks
21258    </para>
21259   </listitem>
21260  </varlistentry>
21261  <varlistentry>
21262   <term><parameter>x</parameter></term>
21263   <listitem>
21264    <para>
21265     x offset of the CRTC scanout area on the underlying framebuffer
21266    </para>
21267   </listitem>
21268  </varlistentry>
21269  <varlistentry>
21270   <term><parameter>y</parameter></term>
21271   <listitem>
21272    <para>
21273     y offset of the CRTC scanout area on the underlying framebuffer
21274    </para>
21275   </listitem>
21276  </varlistentry>
21277  <varlistentry>
21278   <term><parameter>old_fb</parameter></term>
21279   <listitem>
21280    <para>
21281     previous framebuffer
21282    </para>
21283   </listitem>
21284  </varlistentry>
21285 </variablelist>
21286</refsect1>
21287<refsect1>
21288<title>Description</title>
21289<para>
21290   This function implements a callback useable as the -&gt;mode_set callback
21291   required by the crtc helpers. Besides the atomic plane helper functions for
21292   the primary plane the driver must also provide the -&gt;mode_set_nofb callback
21293   to set up the crtc.
21294   </para><para>
21295
21296   This is a transitional helper useful for converting drivers to the atomic
21297   interfaces.
21298</para>
21299</refsect1>
21300</refentry>
21301
21302<refentry id="API-drm-helper-crtc-mode-set-base">
21303<refentryinfo>
21304 <title>LINUX</title>
21305 <productname>Kernel Hackers Manual</productname>
21306 <date>July 2017</date>
21307</refentryinfo>
21308<refmeta>
21309 <refentrytitle><phrase>drm_helper_crtc_mode_set_base</phrase></refentrytitle>
21310 <manvolnum>9</manvolnum>
21311 <refmiscinfo class="version">4.1.27</refmiscinfo>
21312</refmeta>
21313<refnamediv>
21314 <refname>drm_helper_crtc_mode_set_base</refname>
21315 <refpurpose>
21316     mode_set_base implementation for atomic plane helpers
21317 </refpurpose>
21318</refnamediv>
21319<refsynopsisdiv>
21320 <title>Synopsis</title>
21321  <funcsynopsis><funcprototype>
21322   <funcdef>int <function>drm_helper_crtc_mode_set_base </function></funcdef>
21323   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
21324   <paramdef>int <parameter>x</parameter></paramdef>
21325   <paramdef>int <parameter>y</parameter></paramdef>
21326   <paramdef>struct drm_framebuffer * <parameter>old_fb</parameter></paramdef>
21327  </funcprototype></funcsynopsis>
21328</refsynopsisdiv>
21329<refsect1>
21330 <title>Arguments</title>
21331 <variablelist>
21332  <varlistentry>
21333   <term><parameter>crtc</parameter></term>
21334   <listitem>
21335    <para>
21336     DRM CRTC
21337    </para>
21338   </listitem>
21339  </varlistentry>
21340  <varlistentry>
21341   <term><parameter>x</parameter></term>
21342   <listitem>
21343    <para>
21344     x offset of the CRTC scanout area on the underlying framebuffer
21345    </para>
21346   </listitem>
21347  </varlistentry>
21348  <varlistentry>
21349   <term><parameter>y</parameter></term>
21350   <listitem>
21351    <para>
21352     y offset of the CRTC scanout area on the underlying framebuffer
21353    </para>
21354   </listitem>
21355  </varlistentry>
21356  <varlistentry>
21357   <term><parameter>old_fb</parameter></term>
21358   <listitem>
21359    <para>
21360     previous framebuffer
21361    </para>
21362   </listitem>
21363  </varlistentry>
21364 </variablelist>
21365</refsect1>
21366<refsect1>
21367<title>Description</title>
21368<para>
21369   This function implements a callback useable as the -&gt;mode_set_base used
21370   required by the crtc helpers. The driver must provide the atomic plane helper
21371   functions for the primary plane.
21372   </para><para>
21373
21374   This is a transitional helper useful for converting drivers to the atomic
21375   interfaces.
21376</para>
21377</refsect1>
21378</refentry>
21379
21380<para>
21381   </para><para>
21382   The CRTC modeset helper library provides a default set_config implementation
21383   in <function>drm_crtc_helper_set_config</function>. Plus a few other convenience functions using
21384   the same callbacks which drivers can use to e.g. restore the modeset
21385   configuration on resume with <function>drm_helper_resume_force_mode</function>.
21386   </para><para>
21387   The driver callbacks are mostly compatible with the atomic modeset helpers,
21388   except for the handling of the primary plane: Atomic helpers require that the
21389   primary plane is implemented as a real standalone plane and not directly tied
21390   to the CRTC state. For easier transition this library provides functions to
21391   implement the old semantics required by the CRTC helpers using the new plane
21392   and atomic helper callbacks.
21393   </para><para>
21394   Drivers are strongly urged to convert to the atomic helpers (by way of first
21395   converting to the plane helpers). New drivers must not use these functions
21396   but need to implement the atomic interface instead, potentially using the
21397   atomic helpers for that.
21398</para>
21399
21400    </sect2>
21401    <sect2>
21402      <title>Output Probing Helper Functions Reference</title>
21403<para>
21404   </para><para>
21405   This library provides some helper code for output probing. It provides an
21406   implementation of the core connector-&gt;fill_modes interface with
21407   drm_helper_probe_single_connector_modes.
21408   </para><para>
21409   It also provides support for polling connectors with a work item and for
21410   generic hotplug interrupt handling where the driver doesn't or cannot keep
21411   track of a per-connector hpd interrupt.
21412   </para><para>
21413   This helper library can be used independently of the modeset helper library.
21414   Drivers can also overwrite different parts e.g. use their own hotplug
21415   handling code to avoid probing unrelated outputs.
21416</para>
21417
21418<!-- drivers/gpu/drm/drm_probe_helper.c -->
21419<refentry id="API-drm-helper-probe-single-connector-modes">
21420<refentryinfo>
21421 <title>LINUX</title>
21422 <productname>Kernel Hackers Manual</productname>
21423 <date>July 2017</date>
21424</refentryinfo>
21425<refmeta>
21426 <refentrytitle><phrase>drm_helper_probe_single_connector_modes</phrase></refentrytitle>
21427 <manvolnum>9</manvolnum>
21428 <refmiscinfo class="version">4.1.27</refmiscinfo>
21429</refmeta>
21430<refnamediv>
21431 <refname>drm_helper_probe_single_connector_modes</refname>
21432 <refpurpose>
21433  get complete set of display modes
21434 </refpurpose>
21435</refnamediv>
21436<refsynopsisdiv>
21437 <title>Synopsis</title>
21438  <funcsynopsis><funcprototype>
21439   <funcdef>int <function>drm_helper_probe_single_connector_modes </function></funcdef>
21440   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
21441   <paramdef>uint32_t <parameter>maxX</parameter></paramdef>
21442   <paramdef>uint32_t <parameter>maxY</parameter></paramdef>
21443  </funcprototype></funcsynopsis>
21444</refsynopsisdiv>
21445<refsect1>
21446 <title>Arguments</title>
21447 <variablelist>
21448  <varlistentry>
21449   <term><parameter>connector</parameter></term>
21450   <listitem>
21451    <para>
21452     connector to probe
21453    </para>
21454   </listitem>
21455  </varlistentry>
21456  <varlistentry>
21457   <term><parameter>maxX</parameter></term>
21458   <listitem>
21459    <para>
21460     max width for modes
21461    </para>
21462   </listitem>
21463  </varlistentry>
21464  <varlistentry>
21465   <term><parameter>maxY</parameter></term>
21466   <listitem>
21467    <para>
21468     max height for modes
21469    </para>
21470   </listitem>
21471  </varlistentry>
21472 </variablelist>
21473</refsect1>
21474<refsect1>
21475<title>Description</title>
21476<para>
21477   Based on the helper callbacks implemented by <parameter>connector</parameter> try to detect all
21478   valid modes.  Modes will first be added to the connector's probed_modes list,
21479   then culled (based on validity and the <parameter>maxX</parameter>, <parameter>maxY</parameter> parameters) and put into
21480   the normal modes list.
21481   </para><para>
21482
21483   Intended to be use as a generic implementation of the -&gt;<function>fill_modes</function>
21484   <parameter>connector</parameter> vfunc for drivers that use the crtc helpers for output mode
21485   filtering and detection.
21486</para>
21487</refsect1>
21488<refsect1>
21489<title>Returns</title>
21490<para>
21491   The number of modes found on <parameter>connector</parameter>.
21492</para>
21493</refsect1>
21494</refentry>
21495
21496<refentry id="API-drm-helper-probe-single-connector-modes-nomerge">
21497<refentryinfo>
21498 <title>LINUX</title>
21499 <productname>Kernel Hackers Manual</productname>
21500 <date>July 2017</date>
21501</refentryinfo>
21502<refmeta>
21503 <refentrytitle><phrase>drm_helper_probe_single_connector_modes_nomerge</phrase></refentrytitle>
21504 <manvolnum>9</manvolnum>
21505 <refmiscinfo class="version">4.1.27</refmiscinfo>
21506</refmeta>
21507<refnamediv>
21508 <refname>drm_helper_probe_single_connector_modes_nomerge</refname>
21509 <refpurpose>
21510     get complete set of display modes
21511 </refpurpose>
21512</refnamediv>
21513<refsynopsisdiv>
21514 <title>Synopsis</title>
21515  <funcsynopsis><funcprototype>
21516   <funcdef>int <function>drm_helper_probe_single_connector_modes_nomerge </function></funcdef>
21517   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
21518   <paramdef>uint32_t <parameter>maxX</parameter></paramdef>
21519   <paramdef>uint32_t <parameter>maxY</parameter></paramdef>
21520  </funcprototype></funcsynopsis>
21521</refsynopsisdiv>
21522<refsect1>
21523 <title>Arguments</title>
21524 <variablelist>
21525  <varlistentry>
21526   <term><parameter>connector</parameter></term>
21527   <listitem>
21528    <para>
21529     connector to probe
21530    </para>
21531   </listitem>
21532  </varlistentry>
21533  <varlistentry>
21534   <term><parameter>maxX</parameter></term>
21535   <listitem>
21536    <para>
21537     max width for modes
21538    </para>
21539   </listitem>
21540  </varlistentry>
21541  <varlistentry>
21542   <term><parameter>maxY</parameter></term>
21543   <listitem>
21544    <para>
21545     max height for modes
21546    </para>
21547   </listitem>
21548  </varlistentry>
21549 </variablelist>
21550</refsect1>
21551<refsect1>
21552<title>Description</title>
21553<para>
21554   This operates like drm_hehlper_probe_single_connector_modes except it
21555   replaces the mode bits instead of merging them for preferred modes.
21556</para>
21557</refsect1>
21558</refentry>
21559
21560<refentry id="API-drm-kms-helper-hotplug-event">
21561<refentryinfo>
21562 <title>LINUX</title>
21563 <productname>Kernel Hackers Manual</productname>
21564 <date>July 2017</date>
21565</refentryinfo>
21566<refmeta>
21567 <refentrytitle><phrase>drm_kms_helper_hotplug_event</phrase></refentrytitle>
21568 <manvolnum>9</manvolnum>
21569 <refmiscinfo class="version">4.1.27</refmiscinfo>
21570</refmeta>
21571<refnamediv>
21572 <refname>drm_kms_helper_hotplug_event</refname>
21573 <refpurpose>
21574     fire off KMS hotplug events
21575 </refpurpose>
21576</refnamediv>
21577<refsynopsisdiv>
21578 <title>Synopsis</title>
21579  <funcsynopsis><funcprototype>
21580   <funcdef>void <function>drm_kms_helper_hotplug_event </function></funcdef>
21581   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21582  </funcprototype></funcsynopsis>
21583</refsynopsisdiv>
21584<refsect1>
21585 <title>Arguments</title>
21586 <variablelist>
21587  <varlistentry>
21588   <term><parameter>dev</parameter></term>
21589   <listitem>
21590    <para>
21591     drm_device whose connector state changed
21592    </para>
21593   </listitem>
21594  </varlistentry>
21595 </variablelist>
21596</refsect1>
21597<refsect1>
21598<title>Description</title>
21599<para>
21600   This function fires off the uevent for userspace and also calls the
21601   output_poll_changed function, which is most commonly used to inform the fbdev
21602   emulation code and allow it to update the fbcon output configuration.
21603   </para><para>
21604
21605   Drivers should call this from their hotplug handling code when a change is
21606   detected. Note that this function does not do any output detection of its
21607   own, like <function>drm_helper_hpd_irq_event</function> does - this is assumed to be done by the
21608   driver already.
21609   </para><para>
21610
21611   This function must be called from process context with no mode
21612   setting locks held.
21613</para>
21614</refsect1>
21615</refentry>
21616
21617<refentry id="API-drm-kms-helper-poll-disable">
21618<refentryinfo>
21619 <title>LINUX</title>
21620 <productname>Kernel Hackers Manual</productname>
21621 <date>July 2017</date>
21622</refentryinfo>
21623<refmeta>
21624 <refentrytitle><phrase>drm_kms_helper_poll_disable</phrase></refentrytitle>
21625 <manvolnum>9</manvolnum>
21626 <refmiscinfo class="version">4.1.27</refmiscinfo>
21627</refmeta>
21628<refnamediv>
21629 <refname>drm_kms_helper_poll_disable</refname>
21630 <refpurpose>
21631     disable output polling
21632 </refpurpose>
21633</refnamediv>
21634<refsynopsisdiv>
21635 <title>Synopsis</title>
21636  <funcsynopsis><funcprototype>
21637   <funcdef>void <function>drm_kms_helper_poll_disable </function></funcdef>
21638   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21639  </funcprototype></funcsynopsis>
21640</refsynopsisdiv>
21641<refsect1>
21642 <title>Arguments</title>
21643 <variablelist>
21644  <varlistentry>
21645   <term><parameter>dev</parameter></term>
21646   <listitem>
21647    <para>
21648     drm_device
21649    </para>
21650   </listitem>
21651  </varlistentry>
21652 </variablelist>
21653</refsect1>
21654<refsect1>
21655<title>Description</title>
21656<para>
21657   This function disables the output polling work.
21658   </para><para>
21659
21660   Drivers can call this helper from their device suspend implementation. It is
21661   not an error to call this even when output polling isn't enabled or arlready
21662   disabled.
21663</para>
21664</refsect1>
21665</refentry>
21666
21667<refentry id="API-drm-kms-helper-poll-enable">
21668<refentryinfo>
21669 <title>LINUX</title>
21670 <productname>Kernel Hackers Manual</productname>
21671 <date>July 2017</date>
21672</refentryinfo>
21673<refmeta>
21674 <refentrytitle><phrase>drm_kms_helper_poll_enable</phrase></refentrytitle>
21675 <manvolnum>9</manvolnum>
21676 <refmiscinfo class="version">4.1.27</refmiscinfo>
21677</refmeta>
21678<refnamediv>
21679 <refname>drm_kms_helper_poll_enable</refname>
21680 <refpurpose>
21681     re-enable output polling.
21682 </refpurpose>
21683</refnamediv>
21684<refsynopsisdiv>
21685 <title>Synopsis</title>
21686  <funcsynopsis><funcprototype>
21687   <funcdef>void <function>drm_kms_helper_poll_enable </function></funcdef>
21688   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21689  </funcprototype></funcsynopsis>
21690</refsynopsisdiv>
21691<refsect1>
21692 <title>Arguments</title>
21693 <variablelist>
21694  <varlistentry>
21695   <term><parameter>dev</parameter></term>
21696   <listitem>
21697    <para>
21698     drm_device
21699    </para>
21700   </listitem>
21701  </varlistentry>
21702 </variablelist>
21703</refsect1>
21704<refsect1>
21705<title>Description</title>
21706<para>
21707   This function re-enables the output polling work.
21708   </para><para>
21709
21710   Drivers can call this helper from their device resume implementation. It is
21711   an error to call this when the output polling support has not yet been set
21712   up.
21713</para>
21714</refsect1>
21715</refentry>
21716
21717<refentry id="API-drm-kms-helper-poll-init">
21718<refentryinfo>
21719 <title>LINUX</title>
21720 <productname>Kernel Hackers Manual</productname>
21721 <date>July 2017</date>
21722</refentryinfo>
21723<refmeta>
21724 <refentrytitle><phrase>drm_kms_helper_poll_init</phrase></refentrytitle>
21725 <manvolnum>9</manvolnum>
21726 <refmiscinfo class="version">4.1.27</refmiscinfo>
21727</refmeta>
21728<refnamediv>
21729 <refname>drm_kms_helper_poll_init</refname>
21730 <refpurpose>
21731     initialize and enable output polling
21732 </refpurpose>
21733</refnamediv>
21734<refsynopsisdiv>
21735 <title>Synopsis</title>
21736  <funcsynopsis><funcprototype>
21737   <funcdef>void <function>drm_kms_helper_poll_init </function></funcdef>
21738   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21739  </funcprototype></funcsynopsis>
21740</refsynopsisdiv>
21741<refsect1>
21742 <title>Arguments</title>
21743 <variablelist>
21744  <varlistentry>
21745   <term><parameter>dev</parameter></term>
21746   <listitem>
21747    <para>
21748     drm_device
21749    </para>
21750   </listitem>
21751  </varlistentry>
21752 </variablelist>
21753</refsect1>
21754<refsect1>
21755<title>Description</title>
21756<para>
21757   This function intializes and then also enables output polling support for
21758   <parameter>dev</parameter>. Drivers which do not have reliable hotplug support in hardware can use
21759   this helper infrastructure to regularly poll such connectors for changes in
21760   their connection state.
21761   </para><para>
21762
21763   Drivers can control which connectors are polled by setting the
21764   DRM_CONNECTOR_POLL_CONNECT and DRM_CONNECTOR_POLL_DISCONNECT flags. On
21765   connectors where probing live outputs can result in visual distortion drivers
21766   should not set the DRM_CONNECTOR_POLL_DISCONNECT flag to avoid this.
21767   Connectors which have no flag or only DRM_CONNECTOR_POLL_HPD set are
21768   completely ignored by the polling logic.
21769   </para><para>
21770
21771   Note that a connector can be both polled and probed from the hotplug handler,
21772   in case the hotplug interrupt is known to be unreliable.
21773</para>
21774</refsect1>
21775</refentry>
21776
21777<refentry id="API-drm-kms-helper-poll-fini">
21778<refentryinfo>
21779 <title>LINUX</title>
21780 <productname>Kernel Hackers Manual</productname>
21781 <date>July 2017</date>
21782</refentryinfo>
21783<refmeta>
21784 <refentrytitle><phrase>drm_kms_helper_poll_fini</phrase></refentrytitle>
21785 <manvolnum>9</manvolnum>
21786 <refmiscinfo class="version">4.1.27</refmiscinfo>
21787</refmeta>
21788<refnamediv>
21789 <refname>drm_kms_helper_poll_fini</refname>
21790 <refpurpose>
21791     disable output polling and clean it up
21792 </refpurpose>
21793</refnamediv>
21794<refsynopsisdiv>
21795 <title>Synopsis</title>
21796  <funcsynopsis><funcprototype>
21797   <funcdef>void <function>drm_kms_helper_poll_fini </function></funcdef>
21798   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21799  </funcprototype></funcsynopsis>
21800</refsynopsisdiv>
21801<refsect1>
21802 <title>Arguments</title>
21803 <variablelist>
21804  <varlistentry>
21805   <term><parameter>dev</parameter></term>
21806   <listitem>
21807    <para>
21808     drm_device
21809    </para>
21810   </listitem>
21811  </varlistentry>
21812 </variablelist>
21813</refsect1>
21814</refentry>
21815
21816<refentry id="API-drm-helper-hpd-irq-event">
21817<refentryinfo>
21818 <title>LINUX</title>
21819 <productname>Kernel Hackers Manual</productname>
21820 <date>July 2017</date>
21821</refentryinfo>
21822<refmeta>
21823 <refentrytitle><phrase>drm_helper_hpd_irq_event</phrase></refentrytitle>
21824 <manvolnum>9</manvolnum>
21825 <refmiscinfo class="version">4.1.27</refmiscinfo>
21826</refmeta>
21827<refnamediv>
21828 <refname>drm_helper_hpd_irq_event</refname>
21829 <refpurpose>
21830     hotplug processing
21831 </refpurpose>
21832</refnamediv>
21833<refsynopsisdiv>
21834 <title>Synopsis</title>
21835  <funcsynopsis><funcprototype>
21836   <funcdef>bool <function>drm_helper_hpd_irq_event </function></funcdef>
21837   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
21838  </funcprototype></funcsynopsis>
21839</refsynopsisdiv>
21840<refsect1>
21841 <title>Arguments</title>
21842 <variablelist>
21843  <varlistentry>
21844   <term><parameter>dev</parameter></term>
21845   <listitem>
21846    <para>
21847     drm_device
21848    </para>
21849   </listitem>
21850  </varlistentry>
21851 </variablelist>
21852</refsect1>
21853<refsect1>
21854<title>Description</title>
21855<para>
21856   Drivers can use this helper function to run a detect cycle on all connectors
21857   which have the DRM_CONNECTOR_POLL_HPD flag set in their <structname>polled</structname> member. All
21858   other connectors are ignored, which is useful to avoid reprobing fixed
21859   panels.
21860   </para><para>
21861
21862   This helper function is useful for drivers which can't or don't track hotplug
21863   interrupts for each connector.
21864   </para><para>
21865
21866   Drivers which support hotplug interrupts for each connector individually and
21867   which have a more fine-grained detect logic should bypass this code and
21868   directly call <function>drm_kms_helper_hotplug_event</function> in case the connector state
21869   changed.
21870   </para><para>
21871
21872   This function must be called from process context with no mode
21873   setting locks held.
21874   </para><para>
21875
21876   Note that a connector can be both polled and probed from the hotplug handler,
21877   in case the hotplug interrupt is known to be unreliable.
21878</para>
21879</refsect1>
21880</refentry>
21881
21882    </sect2>
21883    <sect2>
21884      <title>fbdev Helper Functions Reference</title>
21885<para>
21886   </para><para>
21887   The fb helper functions are useful to provide an fbdev on top of a drm kernel
21888   mode setting driver. They can be used mostly independently from the crtc
21889   helper functions used by many drivers to implement the kernel mode setting
21890   interfaces.
21891   </para><para>
21892   Initialization is done as a four-step process with <function>drm_fb_helper_prepare</function>,
21893   <function>drm_fb_helper_init</function>, <function>drm_fb_helper_single_add_all_connectors</function> and
21894   <function>drm_fb_helper_initial_config</function>. Drivers with fancier requirements than the
21895   default behaviour can override the third step with their own code.
21896   Teardown is done with <function>drm_fb_helper_fini</function>.
21897   </para><para>
21898   At runtime drivers should restore the fbdev console by calling
21899   <function>drm_fb_helper_restore_fbdev_mode</function> from their -&gt;lastclose callback. They
21900   should also notify the fb helper code from updates to the output
21901   configuration by calling <function>drm_fb_helper_hotplug_event</function>. For easier
21902   integration with the output polling code in drm_crtc_helper.c the modeset
21903   code provides a -&gt;output_poll_changed callback.
21904   </para><para>
21905   All other functions exported by the fb helper library can be used to
21906   implement the fbdev driver interface by the driver.
21907   </para><para>
21908   It is possible, though perhaps somewhat tricky, to implement race-free
21909   hotplug detection using the fbdev helpers. The <function>drm_fb_helper_prepare</function>
21910   helper must be called first to initialize the minimum required to make
21911   hotplug detection work. Drivers also need to make sure to properly set up
21912   the dev-&gt;mode_config.funcs member. After calling <function>drm_kms_helper_poll_init</function>
21913   it is safe to enable interrupts and start processing hotplug events. At the
21914   same time, drivers should initialize all modeset objects such as CRTCs,
21915   encoders and connectors. To finish up the fbdev helper initialization, the
21916   <function>drm_fb_helper_init</function> function is called. To probe for all attached displays
21917   and set up an initial configuration using the detected hardware, drivers
21918   should call <function>drm_fb_helper_single_add_all_connectors</function> followed by
21919   <function>drm_fb_helper_initial_config</function>.
21920</para>
21921
21922<!-- drivers/gpu/drm/drm_fb_helper.c -->
21923<refentry id="API-drm-fb-helper-single-add-all-connectors">
21924<refentryinfo>
21925 <title>LINUX</title>
21926 <productname>Kernel Hackers Manual</productname>
21927 <date>July 2017</date>
21928</refentryinfo>
21929<refmeta>
21930 <refentrytitle><phrase>drm_fb_helper_single_add_all_connectors</phrase></refentrytitle>
21931 <manvolnum>9</manvolnum>
21932 <refmiscinfo class="version">4.1.27</refmiscinfo>
21933</refmeta>
21934<refnamediv>
21935 <refname>drm_fb_helper_single_add_all_connectors</refname>
21936 <refpurpose>
21937  add all connectors to fbdev emulation helper
21938 </refpurpose>
21939</refnamediv>
21940<refsynopsisdiv>
21941 <title>Synopsis</title>
21942  <funcsynopsis><funcprototype>
21943   <funcdef>int <function>drm_fb_helper_single_add_all_connectors </function></funcdef>
21944   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
21945  </funcprototype></funcsynopsis>
21946</refsynopsisdiv>
21947<refsect1>
21948 <title>Arguments</title>
21949 <variablelist>
21950  <varlistentry>
21951   <term><parameter>fb_helper</parameter></term>
21952   <listitem>
21953    <para>
21954     fbdev initialized with drm_fb_helper_init
21955    </para>
21956   </listitem>
21957  </varlistentry>
21958 </variablelist>
21959</refsect1>
21960<refsect1>
21961<title>Description</title>
21962<para>
21963   This functions adds all the available connectors for use with the given
21964   fb_helper. This is a separate step to allow drivers to freely assign
21965   connectors to the fbdev, e.g. if some are reserved for special purposes or
21966   not adequate to be used for the fbcon.
21967   </para><para>
21968
21969   Since this is part of the initial setup before the fbdev is published, no
21970   locking is required.
21971</para>
21972</refsect1>
21973</refentry>
21974
21975<refentry id="API-drm-fb-helper-debug-enter">
21976<refentryinfo>
21977 <title>LINUX</title>
21978 <productname>Kernel Hackers Manual</productname>
21979 <date>July 2017</date>
21980</refentryinfo>
21981<refmeta>
21982 <refentrytitle><phrase>drm_fb_helper_debug_enter</phrase></refentrytitle>
21983 <manvolnum>9</manvolnum>
21984 <refmiscinfo class="version">4.1.27</refmiscinfo>
21985</refmeta>
21986<refnamediv>
21987 <refname>drm_fb_helper_debug_enter</refname>
21988 <refpurpose>
21989     implementation for -&gt;fb_debug_enter
21990 </refpurpose>
21991</refnamediv>
21992<refsynopsisdiv>
21993 <title>Synopsis</title>
21994  <funcsynopsis><funcprototype>
21995   <funcdef>int <function>drm_fb_helper_debug_enter </function></funcdef>
21996   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
21997  </funcprototype></funcsynopsis>
21998</refsynopsisdiv>
21999<refsect1>
22000 <title>Arguments</title>
22001 <variablelist>
22002  <varlistentry>
22003   <term><parameter>info</parameter></term>
22004   <listitem>
22005    <para>
22006     fbdev registered by the helper
22007    </para>
22008   </listitem>
22009  </varlistentry>
22010 </variablelist>
22011</refsect1>
22012</refentry>
22013
22014<refentry id="API-drm-fb-helper-debug-leave">
22015<refentryinfo>
22016 <title>LINUX</title>
22017 <productname>Kernel Hackers Manual</productname>
22018 <date>July 2017</date>
22019</refentryinfo>
22020<refmeta>
22021 <refentrytitle><phrase>drm_fb_helper_debug_leave</phrase></refentrytitle>
22022 <manvolnum>9</manvolnum>
22023 <refmiscinfo class="version">4.1.27</refmiscinfo>
22024</refmeta>
22025<refnamediv>
22026 <refname>drm_fb_helper_debug_leave</refname>
22027 <refpurpose>
22028     implementation for -&gt;fb_debug_leave
22029 </refpurpose>
22030</refnamediv>
22031<refsynopsisdiv>
22032 <title>Synopsis</title>
22033  <funcsynopsis><funcprototype>
22034   <funcdef>int <function>drm_fb_helper_debug_leave </function></funcdef>
22035   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22036  </funcprototype></funcsynopsis>
22037</refsynopsisdiv>
22038<refsect1>
22039 <title>Arguments</title>
22040 <variablelist>
22041  <varlistentry>
22042   <term><parameter>info</parameter></term>
22043   <listitem>
22044    <para>
22045     fbdev registered by the helper
22046    </para>
22047   </listitem>
22048  </varlistentry>
22049 </variablelist>
22050</refsect1>
22051</refentry>
22052
22053<refentry id="API-drm-fb-helper-restore-fbdev-mode-unlocked">
22054<refentryinfo>
22055 <title>LINUX</title>
22056 <productname>Kernel Hackers Manual</productname>
22057 <date>July 2017</date>
22058</refentryinfo>
22059<refmeta>
22060 <refentrytitle><phrase>drm_fb_helper_restore_fbdev_mode_unlocked</phrase></refentrytitle>
22061 <manvolnum>9</manvolnum>
22062 <refmiscinfo class="version">4.1.27</refmiscinfo>
22063</refmeta>
22064<refnamediv>
22065 <refname>drm_fb_helper_restore_fbdev_mode_unlocked</refname>
22066 <refpurpose>
22067     restore fbdev configuration
22068 </refpurpose>
22069</refnamediv>
22070<refsynopsisdiv>
22071 <title>Synopsis</title>
22072  <funcsynopsis><funcprototype>
22073   <funcdef>bool <function>drm_fb_helper_restore_fbdev_mode_unlocked </function></funcdef>
22074   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
22075  </funcprototype></funcsynopsis>
22076</refsynopsisdiv>
22077<refsect1>
22078 <title>Arguments</title>
22079 <variablelist>
22080  <varlistentry>
22081   <term><parameter>fb_helper</parameter></term>
22082   <listitem>
22083    <para>
22084     fbcon to restore
22085    </para>
22086   </listitem>
22087  </varlistentry>
22088 </variablelist>
22089</refsect1>
22090<refsect1>
22091<title>Description</title>
22092<para>
22093   This should be called from driver's drm -&gt;lastclose callback
22094   when implementing an fbcon on top of kms using this helper. This ensures that
22095   the user isn't greeted with a black screen when e.g. X dies.
22096</para>
22097</refsect1>
22098</refentry>
22099
22100<refentry id="API-drm-fb-helper-blank">
22101<refentryinfo>
22102 <title>LINUX</title>
22103 <productname>Kernel Hackers Manual</productname>
22104 <date>July 2017</date>
22105</refentryinfo>
22106<refmeta>
22107 <refentrytitle><phrase>drm_fb_helper_blank</phrase></refentrytitle>
22108 <manvolnum>9</manvolnum>
22109 <refmiscinfo class="version">4.1.27</refmiscinfo>
22110</refmeta>
22111<refnamediv>
22112 <refname>drm_fb_helper_blank</refname>
22113 <refpurpose>
22114     implementation for -&gt;fb_blank
22115 </refpurpose>
22116</refnamediv>
22117<refsynopsisdiv>
22118 <title>Synopsis</title>
22119  <funcsynopsis><funcprototype>
22120   <funcdef>int <function>drm_fb_helper_blank </function></funcdef>
22121   <paramdef>int <parameter>blank</parameter></paramdef>
22122   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22123  </funcprototype></funcsynopsis>
22124</refsynopsisdiv>
22125<refsect1>
22126 <title>Arguments</title>
22127 <variablelist>
22128  <varlistentry>
22129   <term><parameter>blank</parameter></term>
22130   <listitem>
22131    <para>
22132     desired blanking state
22133    </para>
22134   </listitem>
22135  </varlistentry>
22136  <varlistentry>
22137   <term><parameter>info</parameter></term>
22138   <listitem>
22139    <para>
22140     fbdev registered by the helper
22141    </para>
22142   </listitem>
22143  </varlistentry>
22144 </variablelist>
22145</refsect1>
22146</refentry>
22147
22148<refentry id="API-drm-fb-helper-prepare">
22149<refentryinfo>
22150 <title>LINUX</title>
22151 <productname>Kernel Hackers Manual</productname>
22152 <date>July 2017</date>
22153</refentryinfo>
22154<refmeta>
22155 <refentrytitle><phrase>drm_fb_helper_prepare</phrase></refentrytitle>
22156 <manvolnum>9</manvolnum>
22157 <refmiscinfo class="version">4.1.27</refmiscinfo>
22158</refmeta>
22159<refnamediv>
22160 <refname>drm_fb_helper_prepare</refname>
22161 <refpurpose>
22162     setup a drm_fb_helper structure
22163 </refpurpose>
22164</refnamediv>
22165<refsynopsisdiv>
22166 <title>Synopsis</title>
22167  <funcsynopsis><funcprototype>
22168   <funcdef>void <function>drm_fb_helper_prepare </function></funcdef>
22169   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
22170   <paramdef>struct drm_fb_helper * <parameter>helper</parameter></paramdef>
22171   <paramdef>const struct drm_fb_helper_funcs * <parameter>funcs</parameter></paramdef>
22172  </funcprototype></funcsynopsis>
22173</refsynopsisdiv>
22174<refsect1>
22175 <title>Arguments</title>
22176 <variablelist>
22177  <varlistentry>
22178   <term><parameter>dev</parameter></term>
22179   <listitem>
22180    <para>
22181     DRM device
22182    </para>
22183   </listitem>
22184  </varlistentry>
22185  <varlistentry>
22186   <term><parameter>helper</parameter></term>
22187   <listitem>
22188    <para>
22189     driver-allocated fbdev helper structure to set up
22190    </para>
22191   </listitem>
22192  </varlistentry>
22193  <varlistentry>
22194   <term><parameter>funcs</parameter></term>
22195   <listitem>
22196    <para>
22197     pointer to structure of functions associate with this helper
22198    </para>
22199   </listitem>
22200  </varlistentry>
22201 </variablelist>
22202</refsect1>
22203<refsect1>
22204<title>Description</title>
22205<para>
22206   Sets up the bare minimum to make the framebuffer helper usable. This is
22207   useful to implement race-free initialization of the polling helpers.
22208</para>
22209</refsect1>
22210</refentry>
22211
22212<refentry id="API-drm-fb-helper-init">
22213<refentryinfo>
22214 <title>LINUX</title>
22215 <productname>Kernel Hackers Manual</productname>
22216 <date>July 2017</date>
22217</refentryinfo>
22218<refmeta>
22219 <refentrytitle><phrase>drm_fb_helper_init</phrase></refentrytitle>
22220 <manvolnum>9</manvolnum>
22221 <refmiscinfo class="version">4.1.27</refmiscinfo>
22222</refmeta>
22223<refnamediv>
22224 <refname>drm_fb_helper_init</refname>
22225 <refpurpose>
22226     initialize a drm_fb_helper structure
22227 </refpurpose>
22228</refnamediv>
22229<refsynopsisdiv>
22230 <title>Synopsis</title>
22231  <funcsynopsis><funcprototype>
22232   <funcdef>int <function>drm_fb_helper_init </function></funcdef>
22233   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
22234   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
22235   <paramdef>int <parameter>crtc_count</parameter></paramdef>
22236   <paramdef>int <parameter>max_conn_count</parameter></paramdef>
22237  </funcprototype></funcsynopsis>
22238</refsynopsisdiv>
22239<refsect1>
22240 <title>Arguments</title>
22241 <variablelist>
22242  <varlistentry>
22243   <term><parameter>dev</parameter></term>
22244   <listitem>
22245    <para>
22246     drm device
22247    </para>
22248   </listitem>
22249  </varlistentry>
22250  <varlistentry>
22251   <term><parameter>fb_helper</parameter></term>
22252   <listitem>
22253    <para>
22254     driver-allocated fbdev helper structure to initialize
22255    </para>
22256   </listitem>
22257  </varlistentry>
22258  <varlistentry>
22259   <term><parameter>crtc_count</parameter></term>
22260   <listitem>
22261    <para>
22262     maximum number of crtcs to support in this fbdev emulation
22263    </para>
22264   </listitem>
22265  </varlistentry>
22266  <varlistentry>
22267   <term><parameter>max_conn_count</parameter></term>
22268   <listitem>
22269    <para>
22270     max connector count
22271    </para>
22272   </listitem>
22273  </varlistentry>
22274 </variablelist>
22275</refsect1>
22276<refsect1>
22277<title>Description</title>
22278<para>
22279   This allocates the structures for the fbdev helper with the given limits.
22280   Note that this won't yet touch the hardware (through the driver interfaces)
22281   nor register the fbdev. This is only done in <function>drm_fb_helper_initial_config</function>
22282   to allow driver writes more control over the exact init sequence.
22283   </para><para>
22284
22285   Drivers must call <function>drm_fb_helper_prepare</function> before calling this function.
22286</para>
22287</refsect1>
22288<refsect1>
22289<title>RETURNS</title>
22290<para>
22291   Zero if everything went ok, nonzero otherwise.
22292</para>
22293</refsect1>
22294</refentry>
22295
22296<refentry id="API-drm-fb-helper-setcmap">
22297<refentryinfo>
22298 <title>LINUX</title>
22299 <productname>Kernel Hackers Manual</productname>
22300 <date>July 2017</date>
22301</refentryinfo>
22302<refmeta>
22303 <refentrytitle><phrase>drm_fb_helper_setcmap</phrase></refentrytitle>
22304 <manvolnum>9</manvolnum>
22305 <refmiscinfo class="version">4.1.27</refmiscinfo>
22306</refmeta>
22307<refnamediv>
22308 <refname>drm_fb_helper_setcmap</refname>
22309 <refpurpose>
22310     implementation for -&gt;fb_setcmap
22311 </refpurpose>
22312</refnamediv>
22313<refsynopsisdiv>
22314 <title>Synopsis</title>
22315  <funcsynopsis><funcprototype>
22316   <funcdef>int <function>drm_fb_helper_setcmap </function></funcdef>
22317   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
22318   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22319  </funcprototype></funcsynopsis>
22320</refsynopsisdiv>
22321<refsect1>
22322 <title>Arguments</title>
22323 <variablelist>
22324  <varlistentry>
22325   <term><parameter>cmap</parameter></term>
22326   <listitem>
22327    <para>
22328     cmap to set
22329    </para>
22330   </listitem>
22331  </varlistentry>
22332  <varlistentry>
22333   <term><parameter>info</parameter></term>
22334   <listitem>
22335    <para>
22336     fbdev registered by the helper
22337    </para>
22338   </listitem>
22339  </varlistentry>
22340 </variablelist>
22341</refsect1>
22342</refentry>
22343
22344<refentry id="API-drm-fb-helper-check-var">
22345<refentryinfo>
22346 <title>LINUX</title>
22347 <productname>Kernel Hackers Manual</productname>
22348 <date>July 2017</date>
22349</refentryinfo>
22350<refmeta>
22351 <refentrytitle><phrase>drm_fb_helper_check_var</phrase></refentrytitle>
22352 <manvolnum>9</manvolnum>
22353 <refmiscinfo class="version">4.1.27</refmiscinfo>
22354</refmeta>
22355<refnamediv>
22356 <refname>drm_fb_helper_check_var</refname>
22357 <refpurpose>
22358     implementation for -&gt;fb_check_var
22359 </refpurpose>
22360</refnamediv>
22361<refsynopsisdiv>
22362 <title>Synopsis</title>
22363  <funcsynopsis><funcprototype>
22364   <funcdef>int <function>drm_fb_helper_check_var </function></funcdef>
22365   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
22366   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22367  </funcprototype></funcsynopsis>
22368</refsynopsisdiv>
22369<refsect1>
22370 <title>Arguments</title>
22371 <variablelist>
22372  <varlistentry>
22373   <term><parameter>var</parameter></term>
22374   <listitem>
22375    <para>
22376     screeninfo to check
22377    </para>
22378   </listitem>
22379  </varlistentry>
22380  <varlistentry>
22381   <term><parameter>info</parameter></term>
22382   <listitem>
22383    <para>
22384     fbdev registered by the helper
22385    </para>
22386   </listitem>
22387  </varlistentry>
22388 </variablelist>
22389</refsect1>
22390</refentry>
22391
22392<refentry id="API-drm-fb-helper-set-par">
22393<refentryinfo>
22394 <title>LINUX</title>
22395 <productname>Kernel Hackers Manual</productname>
22396 <date>July 2017</date>
22397</refentryinfo>
22398<refmeta>
22399 <refentrytitle><phrase>drm_fb_helper_set_par</phrase></refentrytitle>
22400 <manvolnum>9</manvolnum>
22401 <refmiscinfo class="version">4.1.27</refmiscinfo>
22402</refmeta>
22403<refnamediv>
22404 <refname>drm_fb_helper_set_par</refname>
22405 <refpurpose>
22406     implementation for -&gt;fb_set_par
22407 </refpurpose>
22408</refnamediv>
22409<refsynopsisdiv>
22410 <title>Synopsis</title>
22411  <funcsynopsis><funcprototype>
22412   <funcdef>int <function>drm_fb_helper_set_par </function></funcdef>
22413   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22414  </funcprototype></funcsynopsis>
22415</refsynopsisdiv>
22416<refsect1>
22417 <title>Arguments</title>
22418 <variablelist>
22419  <varlistentry>
22420   <term><parameter>info</parameter></term>
22421   <listitem>
22422    <para>
22423     fbdev registered by the helper
22424    </para>
22425   </listitem>
22426  </varlistentry>
22427 </variablelist>
22428</refsect1>
22429<refsect1>
22430<title>Description</title>
22431<para>
22432   This will let fbcon do the mode init and is called at initialization time by
22433   the fbdev core when registering the driver, and later on through the hotplug
22434   callback.
22435</para>
22436</refsect1>
22437</refentry>
22438
22439<refentry id="API-drm-fb-helper-pan-display">
22440<refentryinfo>
22441 <title>LINUX</title>
22442 <productname>Kernel Hackers Manual</productname>
22443 <date>July 2017</date>
22444</refentryinfo>
22445<refmeta>
22446 <refentrytitle><phrase>drm_fb_helper_pan_display</phrase></refentrytitle>
22447 <manvolnum>9</manvolnum>
22448 <refmiscinfo class="version">4.1.27</refmiscinfo>
22449</refmeta>
22450<refnamediv>
22451 <refname>drm_fb_helper_pan_display</refname>
22452 <refpurpose>
22453     implementation for -&gt;fb_pan_display
22454 </refpurpose>
22455</refnamediv>
22456<refsynopsisdiv>
22457 <title>Synopsis</title>
22458  <funcsynopsis><funcprototype>
22459   <funcdef>int <function>drm_fb_helper_pan_display </function></funcdef>
22460   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
22461   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22462  </funcprototype></funcsynopsis>
22463</refsynopsisdiv>
22464<refsect1>
22465 <title>Arguments</title>
22466 <variablelist>
22467  <varlistentry>
22468   <term><parameter>var</parameter></term>
22469   <listitem>
22470    <para>
22471     updated screen information
22472    </para>
22473   </listitem>
22474  </varlistentry>
22475  <varlistentry>
22476   <term><parameter>info</parameter></term>
22477   <listitem>
22478    <para>
22479     fbdev registered by the helper
22480    </para>
22481   </listitem>
22482  </varlistentry>
22483 </variablelist>
22484</refsect1>
22485</refentry>
22486
22487<refentry id="API-drm-fb-helper-fill-fix">
22488<refentryinfo>
22489 <title>LINUX</title>
22490 <productname>Kernel Hackers Manual</productname>
22491 <date>July 2017</date>
22492</refentryinfo>
22493<refmeta>
22494 <refentrytitle><phrase>drm_fb_helper_fill_fix</phrase></refentrytitle>
22495 <manvolnum>9</manvolnum>
22496 <refmiscinfo class="version">4.1.27</refmiscinfo>
22497</refmeta>
22498<refnamediv>
22499 <refname>drm_fb_helper_fill_fix</refname>
22500 <refpurpose>
22501     initializes fixed fbdev information
22502 </refpurpose>
22503</refnamediv>
22504<refsynopsisdiv>
22505 <title>Synopsis</title>
22506  <funcsynopsis><funcprototype>
22507   <funcdef>void <function>drm_fb_helper_fill_fix </function></funcdef>
22508   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22509   <paramdef>uint32_t <parameter>pitch</parameter></paramdef>
22510   <paramdef>uint32_t <parameter>depth</parameter></paramdef>
22511  </funcprototype></funcsynopsis>
22512</refsynopsisdiv>
22513<refsect1>
22514 <title>Arguments</title>
22515 <variablelist>
22516  <varlistentry>
22517   <term><parameter>info</parameter></term>
22518   <listitem>
22519    <para>
22520     fbdev registered by the helper
22521    </para>
22522   </listitem>
22523  </varlistentry>
22524  <varlistentry>
22525   <term><parameter>pitch</parameter></term>
22526   <listitem>
22527    <para>
22528     desired pitch
22529    </para>
22530   </listitem>
22531  </varlistentry>
22532  <varlistentry>
22533   <term><parameter>depth</parameter></term>
22534   <listitem>
22535    <para>
22536     desired depth
22537    </para>
22538   </listitem>
22539  </varlistentry>
22540 </variablelist>
22541</refsect1>
22542<refsect1>
22543<title>Description</title>
22544<para>
22545   Helper to fill in the fixed fbdev information useful for a non-accelerated
22546   fbdev emulations. Drivers which support acceleration methods which impose
22547   additional constraints need to set up their own limits.
22548   </para><para>
22549
22550   Drivers should call this (or their equivalent setup code) from their
22551   -&gt;fb_probe callback.
22552</para>
22553</refsect1>
22554</refentry>
22555
22556<refentry id="API-drm-fb-helper-fill-var">
22557<refentryinfo>
22558 <title>LINUX</title>
22559 <productname>Kernel Hackers Manual</productname>
22560 <date>July 2017</date>
22561</refentryinfo>
22562<refmeta>
22563 <refentrytitle><phrase>drm_fb_helper_fill_var</phrase></refentrytitle>
22564 <manvolnum>9</manvolnum>
22565 <refmiscinfo class="version">4.1.27</refmiscinfo>
22566</refmeta>
22567<refnamediv>
22568 <refname>drm_fb_helper_fill_var</refname>
22569 <refpurpose>
22570     initalizes variable fbdev information
22571 </refpurpose>
22572</refnamediv>
22573<refsynopsisdiv>
22574 <title>Synopsis</title>
22575  <funcsynopsis><funcprototype>
22576   <funcdef>void <function>drm_fb_helper_fill_var </function></funcdef>
22577   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
22578   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
22579   <paramdef>uint32_t <parameter>fb_width</parameter></paramdef>
22580   <paramdef>uint32_t <parameter>fb_height</parameter></paramdef>
22581  </funcprototype></funcsynopsis>
22582</refsynopsisdiv>
22583<refsect1>
22584 <title>Arguments</title>
22585 <variablelist>
22586  <varlistentry>
22587   <term><parameter>info</parameter></term>
22588   <listitem>
22589    <para>
22590     fbdev instance to set up
22591    </para>
22592   </listitem>
22593  </varlistentry>
22594  <varlistentry>
22595   <term><parameter>fb_helper</parameter></term>
22596   <listitem>
22597    <para>
22598     fb helper instance to use as template
22599    </para>
22600   </listitem>
22601  </varlistentry>
22602  <varlistentry>
22603   <term><parameter>fb_width</parameter></term>
22604   <listitem>
22605    <para>
22606     desired fb width
22607    </para>
22608   </listitem>
22609  </varlistentry>
22610  <varlistentry>
22611   <term><parameter>fb_height</parameter></term>
22612   <listitem>
22613    <para>
22614     desired fb height
22615    </para>
22616   </listitem>
22617  </varlistentry>
22618 </variablelist>
22619</refsect1>
22620<refsect1>
22621<title>Description</title>
22622<para>
22623   Sets up the variable fbdev metainformation from the given fb helper instance
22624   and the drm framebuffer allocated in fb_helper-&gt;fb.
22625   </para><para>
22626
22627   Drivers should call this (or their equivalent setup code) from their
22628   -&gt;fb_probe callback after having allocated the fbdev backing
22629   storage framebuffer.
22630</para>
22631</refsect1>
22632</refentry>
22633
22634<refentry id="API-drm-fb-helper-initial-config">
22635<refentryinfo>
22636 <title>LINUX</title>
22637 <productname>Kernel Hackers Manual</productname>
22638 <date>July 2017</date>
22639</refentryinfo>
22640<refmeta>
22641 <refentrytitle><phrase>drm_fb_helper_initial_config</phrase></refentrytitle>
22642 <manvolnum>9</manvolnum>
22643 <refmiscinfo class="version">4.1.27</refmiscinfo>
22644</refmeta>
22645<refnamediv>
22646 <refname>drm_fb_helper_initial_config</refname>
22647 <refpurpose>
22648     setup a sane initial connector configuration
22649 </refpurpose>
22650</refnamediv>
22651<refsynopsisdiv>
22652 <title>Synopsis</title>
22653  <funcsynopsis><funcprototype>
22654   <funcdef>int <function>drm_fb_helper_initial_config </function></funcdef>
22655   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
22656   <paramdef>int <parameter>bpp_sel</parameter></paramdef>
22657  </funcprototype></funcsynopsis>
22658</refsynopsisdiv>
22659<refsect1>
22660 <title>Arguments</title>
22661 <variablelist>
22662  <varlistentry>
22663   <term><parameter>fb_helper</parameter></term>
22664   <listitem>
22665    <para>
22666     fb_helper device struct
22667    </para>
22668   </listitem>
22669  </varlistentry>
22670  <varlistentry>
22671   <term><parameter>bpp_sel</parameter></term>
22672   <listitem>
22673    <para>
22674     bpp value to use for the framebuffer configuration
22675    </para>
22676   </listitem>
22677  </varlistentry>
22678 </variablelist>
22679</refsect1>
22680<refsect1>
22681<title>Description</title>
22682<para>
22683   Scans the CRTCs and connectors and tries to put together an initial setup.
22684   At the moment, this is a cloned configuration across all heads with
22685   a new framebuffer object as the backing store.
22686   </para><para>
22687
22688   Note that this also registers the fbdev and so allows userspace to call into
22689   the driver through the fbdev interfaces.
22690   </para><para>
22691
22692   This function will call down into the -&gt;fb_probe callback to let
22693   the driver allocate and initialize the fbdev info structure and the drm
22694   framebuffer used to back the fbdev. <function>drm_fb_helper_fill_var</function> and
22695   <function>drm_fb_helper_fill_fix</function> are provided as helpers to setup simple default
22696   values for the fbdev info structure.
22697</para>
22698</refsect1>
22699<refsect1>
22700<title>RETURNS</title>
22701<para>
22702   Zero if everything went ok, nonzero otherwise.
22703</para>
22704</refsect1>
22705</refentry>
22706
22707<refentry id="API-drm-fb-helper-hotplug-event">
22708<refentryinfo>
22709 <title>LINUX</title>
22710 <productname>Kernel Hackers Manual</productname>
22711 <date>July 2017</date>
22712</refentryinfo>
22713<refmeta>
22714 <refentrytitle><phrase>drm_fb_helper_hotplug_event</phrase></refentrytitle>
22715 <manvolnum>9</manvolnum>
22716 <refmiscinfo class="version">4.1.27</refmiscinfo>
22717</refmeta>
22718<refnamediv>
22719 <refname>drm_fb_helper_hotplug_event</refname>
22720 <refpurpose>
22721     respond to a hotplug notification by probing all the outputs attached to the fb
22722 </refpurpose>
22723</refnamediv>
22724<refsynopsisdiv>
22725 <title>Synopsis</title>
22726  <funcsynopsis><funcprototype>
22727   <funcdef>int <function>drm_fb_helper_hotplug_event </function></funcdef>
22728   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
22729  </funcprototype></funcsynopsis>
22730</refsynopsisdiv>
22731<refsect1>
22732 <title>Arguments</title>
22733 <variablelist>
22734  <varlistentry>
22735   <term><parameter>fb_helper</parameter></term>
22736   <listitem>
22737    <para>
22738     the drm_fb_helper
22739    </para>
22740   </listitem>
22741  </varlistentry>
22742 </variablelist>
22743</refsect1>
22744<refsect1>
22745<title>Description</title>
22746<para>
22747   Scan the connectors attached to the fb_helper and try to put together a
22748   setup after *notification of a change in output configuration.
22749   </para><para>
22750
22751   Called at runtime, takes the mode config locks to be able to check/change the
22752   modeset configuration. Must be run from process context (which usually means
22753   either the output polling work or a work item launched from the driver's
22754   hotplug interrupt).
22755   </para><para>
22756
22757   Note that drivers may call this even before calling
22758   drm_fb_helper_initial_config but only aftert drm_fb_helper_init. This allows
22759   for a race-free fbcon setup and will make sure that the fbdev emulation will
22760   not miss any hotplug events.
22761</para>
22762</refsect1>
22763<refsect1>
22764<title>RETURNS</title>
22765<para>
22766   0 on success and a non-zero error code otherwise.
22767</para>
22768</refsect1>
22769</refentry>
22770
22771<!-- include/drm/drm_fb_helper.h -->
22772<refentry id="API-struct-drm-fb-helper-surface-size">
22773<refentryinfo>
22774 <title>LINUX</title>
22775 <productname>Kernel Hackers Manual</productname>
22776 <date>July 2017</date>
22777</refentryinfo>
22778<refmeta>
22779 <refentrytitle><phrase>struct drm_fb_helper_surface_size</phrase></refentrytitle>
22780 <manvolnum>9</manvolnum>
22781 <refmiscinfo class="version">4.1.27</refmiscinfo>
22782</refmeta>
22783<refnamediv>
22784 <refname>struct drm_fb_helper_surface_size</refname>
22785 <refpurpose>
22786  describes fbdev size and scanout surface size
22787 </refpurpose>
22788</refnamediv>
22789<refsynopsisdiv>
22790 <title>Synopsis</title>
22791  <programlisting>
22792struct drm_fb_helper_surface_size {
22793  u32 fb_width;
22794  u32 fb_height;
22795  u32 surface_width;
22796  u32 surface_height;
22797  u32 surface_bpp;
22798  u32 surface_depth;
22799};  </programlisting>
22800</refsynopsisdiv>
22801 <refsect1>
22802  <title>Members</title>
22803  <variablelist>
22804    <varlistentry>      <term>fb_width</term>
22805      <listitem><para>
22806fbdev width
22807      </para></listitem>
22808    </varlistentry>
22809    <varlistentry>      <term>fb_height</term>
22810      <listitem><para>
22811fbdev height
22812      </para></listitem>
22813    </varlistentry>
22814    <varlistentry>      <term>surface_width</term>
22815      <listitem><para>
22816scanout buffer width
22817      </para></listitem>
22818    </varlistentry>
22819    <varlistentry>      <term>surface_height</term>
22820      <listitem><para>
22821scanout buffer height
22822      </para></listitem>
22823    </varlistentry>
22824    <varlistentry>      <term>surface_bpp</term>
22825      <listitem><para>
22826scanout buffer bpp
22827      </para></listitem>
22828    </varlistentry>
22829    <varlistentry>      <term>surface_depth</term>
22830      <listitem><para>
22831scanout buffer depth
22832      </para></listitem>
22833    </varlistentry>
22834  </variablelist>
22835 </refsect1>
22836<refsect1>
22837<title>Description</title>
22838<para>
22839   Note that the scanout surface width/height may be larger than the fbdev
22840   width/height.  In case of multiple displays, the scanout surface is sized
22841   according to the largest width/height (so it is large enough for all CRTCs
22842   to scanout).  But the fbdev width/height is sized to the minimum width/
22843   height of all the displays.  This ensures that fbcon fits on the smallest
22844   of the attached displays.
22845   </para><para>
22846
22847   So what is passed to <function>drm_fb_helper_fill_var</function> should be fb_width/fb_height,
22848   rather than the surface size.
22849</para>
22850</refsect1>
22851</refentry>
22852
22853<refentry id="API-struct-drm-fb-helper-funcs">
22854<refentryinfo>
22855 <title>LINUX</title>
22856 <productname>Kernel Hackers Manual</productname>
22857 <date>July 2017</date>
22858</refentryinfo>
22859<refmeta>
22860 <refentrytitle><phrase>struct drm_fb_helper_funcs</phrase></refentrytitle>
22861 <manvolnum>9</manvolnum>
22862 <refmiscinfo class="version">4.1.27</refmiscinfo>
22863</refmeta>
22864<refnamediv>
22865 <refname>struct drm_fb_helper_funcs</refname>
22866 <refpurpose>
22867     driver callbacks for the fbdev emulation library
22868 </refpurpose>
22869</refnamediv>
22870<refsynopsisdiv>
22871 <title>Synopsis</title>
22872  <programlisting>
22873struct drm_fb_helper_funcs {
22874  void (* gamma_set) (struct drm_crtc *crtc, u16 red, u16 green,u16 blue, int regno);
22875  void (* gamma_get) (struct drm_crtc *crtc, u16 *red, u16 *green,u16 *blue, int regno);
22876  int (* fb_probe) (struct drm_fb_helper *helper,struct drm_fb_helper_surface_size *sizes);
22877  bool (* initial_config) (struct drm_fb_helper *fb_helper,struct drm_fb_helper_crtc **crtcs,struct drm_display_mode **modes,struct drm_fb_offset *offsets,bool *enabled, int width, int height);
22878};  </programlisting>
22879</refsynopsisdiv>
22880 <refsect1>
22881  <title>Members</title>
22882  <variablelist>
22883    <varlistentry>      <term>gamma_set</term>
22884      <listitem><para>
22885   Set the given gamma lut register on the given crtc.
22886      </para></listitem>
22887    </varlistentry>
22888    <varlistentry>      <term>gamma_get</term>
22889      <listitem><para>
22890   Read the given gamma lut register on the given crtc, used to
22891   save the current lut when force-restoring the fbdev for e.g.
22892   kdbg.
22893      </para></listitem>
22894    </varlistentry>
22895    <varlistentry>      <term>fb_probe</term>
22896      <listitem><para>
22897   Driver callback to allocate and initialize the fbdev info
22898   structure. Furthermore it also needs to allocate the drm
22899   framebuffer used to back the fbdev.
22900      </para></listitem>
22901    </varlistentry>
22902    <varlistentry>      <term>initial_config</term>
22903      <listitem><para>
22904   Setup an initial fbdev display configuration
22905      </para></listitem>
22906    </varlistentry>
22907  </variablelist>
22908 </refsect1>
22909<refsect1>
22910<title>Description</title>
22911<para>
22912   Driver callbacks used by the fbdev emulation helper library.
22913</para>
22914</refsect1>
22915</refentry>
22916
22917    </sect2>
22918    <sect2>
22919      <title>Display Port Helper Functions Reference</title>
22920<para>
22921   </para><para>
22922   These functions contain some common logic and helpers at various abstraction
22923   levels to deal with Display Port sink devices and related things like DP aux
22924   channel transfers, EDID reading over DP aux channels, decoding certain DPCD
22925   blocks, ...
22926</para>
22927
22928<para>
22929   </para><para>
22930   The DisplayPort AUX channel is an abstraction to allow generic, driver-
22931   independent access to AUX functionality. Drivers can take advantage of
22932   this by filling in the fields of the drm_dp_aux structure.
22933   </para><para>
22934   Transactions are described using a hardware-independent drm_dp_aux_msg
22935   structure, which is passed into a driver's .<function>transfer</function> implementation.
22936   Both native and I2C-over-AUX transactions are supported.
22937</para>
22938
22939<!-- include/drm/drm_dp_helper.h -->
22940<refentry id="API-struct-drm-dp-aux-msg">
22941<refentryinfo>
22942 <title>LINUX</title>
22943 <productname>Kernel Hackers Manual</productname>
22944 <date>July 2017</date>
22945</refentryinfo>
22946<refmeta>
22947 <refentrytitle><phrase>struct drm_dp_aux_msg</phrase></refentrytitle>
22948 <manvolnum>9</manvolnum>
22949 <refmiscinfo class="version">4.1.27</refmiscinfo>
22950</refmeta>
22951<refnamediv>
22952 <refname>struct drm_dp_aux_msg</refname>
22953 <refpurpose>
22954  DisplayPort AUX channel transaction
22955 </refpurpose>
22956</refnamediv>
22957<refsynopsisdiv>
22958 <title>Synopsis</title>
22959  <programlisting>
22960struct drm_dp_aux_msg {
22961  unsigned int address;
22962  u8 request;
22963  u8 reply;
22964  void * buffer;
22965  size_t size;
22966};  </programlisting>
22967</refsynopsisdiv>
22968 <refsect1>
22969  <title>Members</title>
22970  <variablelist>
22971    <varlistentry>      <term>address</term>
22972      <listitem><para>
22973address of the (first) register to access
22974      </para></listitem>
22975    </varlistentry>
22976    <varlistentry>      <term>request</term>
22977      <listitem><para>
22978contains the type of transaction (see DP_AUX_* macros)
22979      </para></listitem>
22980    </varlistentry>
22981    <varlistentry>      <term>reply</term>
22982      <listitem><para>
22983upon completion, contains the reply type of the transaction
22984      </para></listitem>
22985    </varlistentry>
22986    <varlistentry>      <term>buffer</term>
22987      <listitem><para>
22988pointer to a transmission or reception buffer
22989      </para></listitem>
22990    </varlistentry>
22991    <varlistentry>      <term>size</term>
22992      <listitem><para>
22993size of <parameter>buffer</parameter>
22994      </para></listitem>
22995    </varlistentry>
22996  </variablelist>
22997 </refsect1>
22998</refentry>
22999
23000<refentry id="API-struct-drm-dp-aux">
23001<refentryinfo>
23002 <title>LINUX</title>
23003 <productname>Kernel Hackers Manual</productname>
23004 <date>July 2017</date>
23005</refentryinfo>
23006<refmeta>
23007 <refentrytitle><phrase>struct drm_dp_aux</phrase></refentrytitle>
23008 <manvolnum>9</manvolnum>
23009 <refmiscinfo class="version">4.1.27</refmiscinfo>
23010</refmeta>
23011<refnamediv>
23012 <refname>struct drm_dp_aux</refname>
23013 <refpurpose>
23014     DisplayPort AUX channel
23015 </refpurpose>
23016</refnamediv>
23017<refsynopsisdiv>
23018 <title>Synopsis</title>
23019  <programlisting>
23020struct drm_dp_aux {
23021  const char * name;
23022  struct i2c_adapter ddc;
23023  struct device * dev;
23024  struct mutex hw_mutex;
23025  ssize_t (* transfer) (struct drm_dp_aux *aux,struct drm_dp_aux_msg *msg);
23026};  </programlisting>
23027</refsynopsisdiv>
23028 <refsect1>
23029  <title>Members</title>
23030  <variablelist>
23031    <varlistentry>      <term>name</term>
23032      <listitem><para>
23033   user-visible name of this AUX channel and the I2C-over-AUX adapter
23034      </para></listitem>
23035    </varlistentry>
23036    <varlistentry>      <term>ddc</term>
23037      <listitem><para>
23038   I2C adapter that can be used for I2C-over-AUX communication
23039      </para></listitem>
23040    </varlistentry>
23041    <varlistentry>      <term>dev</term>
23042      <listitem><para>
23043   pointer to struct device that is the parent for this AUX channel
23044      </para></listitem>
23045    </varlistentry>
23046    <varlistentry>      <term>hw_mutex</term>
23047      <listitem><para>
23048   internal mutex used for locking transfers
23049      </para></listitem>
23050    </varlistentry>
23051    <varlistentry>      <term>transfer</term>
23052      <listitem><para>
23053   transfers a message representing a single AUX transaction
23054      </para></listitem>
23055    </varlistentry>
23056  </variablelist>
23057 </refsect1>
23058<refsect1>
23059<title>Description</title>
23060<para>
23061   The .dev field should be set to a pointer to the device that implements
23062   the AUX channel.
23063   </para><para>
23064
23065   The .name field may be used to specify the name of the I2C adapter. If set to
23066   NULL, <function>dev_name</function> of .dev will be used.
23067   </para><para>
23068
23069   Drivers provide a hardware-specific implementation of how transactions
23070   are executed via the .<function>transfer</function> function. A pointer to a drm_dp_aux_msg
23071   structure describing the transaction is passed into this function. Upon
23072   success, the implementation should return the number of payload bytes
23073   that were transferred, or a negative error-code on failure. Helpers
23074   propagate errors from the .<function>transfer</function> function, with the exception of
23075   the -EBUSY error, which causes a transaction to be retried. On a short,
23076   helpers will return -EPROTO to make it simpler to check for failure.
23077   </para><para>
23078
23079   An AUX channel can also be used to transport I2C messages to a sink. A
23080   typical application of that is to access an EDID that's present in the
23081   sink device. The .<function>transfer</function> function can also be used to execute such
23082   transactions. The <function>drm_dp_aux_register_i2c_bus</function> function registers an
23083   I2C adapter that can be passed to <function>drm_probe_ddc</function>. Upon removal, drivers
23084   should call <function>drm_dp_aux_unregister_i2c_bus</function> to remove the I2C adapter.
23085   The I2C adapter uses long transfers by default; if a partial response is
23086   received, the adapter will drop down to the size given by the partial
23087   response for this transaction only.
23088   </para><para>
23089
23090   Note that the aux helper code assumes that the .<function>transfer</function> function
23091   only modifies the reply field of the drm_dp_aux_msg structure.  The
23092   retry logic and i2c helpers assume this is the case.
23093</para>
23094</refsect1>
23095</refentry>
23096
23097<refentry id="API-drm-dp-dpcd-readb">
23098<refentryinfo>
23099 <title>LINUX</title>
23100 <productname>Kernel Hackers Manual</productname>
23101 <date>July 2017</date>
23102</refentryinfo>
23103<refmeta>
23104 <refentrytitle><phrase>drm_dp_dpcd_readb</phrase></refentrytitle>
23105 <manvolnum>9</manvolnum>
23106 <refmiscinfo class="version">4.1.27</refmiscinfo>
23107</refmeta>
23108<refnamediv>
23109 <refname>drm_dp_dpcd_readb</refname>
23110 <refpurpose>
23111     read a single byte from the DPCD
23112 </refpurpose>
23113</refnamediv>
23114<refsynopsisdiv>
23115 <title>Synopsis</title>
23116  <funcsynopsis><funcprototype>
23117   <funcdef>ssize_t <function>drm_dp_dpcd_readb </function></funcdef>
23118   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23119   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
23120   <paramdef>u8 * <parameter>valuep</parameter></paramdef>
23121  </funcprototype></funcsynopsis>
23122</refsynopsisdiv>
23123<refsect1>
23124 <title>Arguments</title>
23125 <variablelist>
23126  <varlistentry>
23127   <term><parameter>aux</parameter></term>
23128   <listitem>
23129    <para>
23130     DisplayPort AUX channel
23131    </para>
23132   </listitem>
23133  </varlistentry>
23134  <varlistentry>
23135   <term><parameter>offset</parameter></term>
23136   <listitem>
23137    <para>
23138     address of the register to read
23139    </para>
23140   </listitem>
23141  </varlistentry>
23142  <varlistentry>
23143   <term><parameter>valuep</parameter></term>
23144   <listitem>
23145    <para>
23146     location where the value of the register will be stored
23147    </para>
23148   </listitem>
23149  </varlistentry>
23150 </variablelist>
23151</refsect1>
23152<refsect1>
23153<title>Description</title>
23154<para>
23155   Returns the number of bytes transferred (1) on success, or a negative
23156   error code on failure.
23157</para>
23158</refsect1>
23159</refentry>
23160
23161<refentry id="API-drm-dp-dpcd-writeb">
23162<refentryinfo>
23163 <title>LINUX</title>
23164 <productname>Kernel Hackers Manual</productname>
23165 <date>July 2017</date>
23166</refentryinfo>
23167<refmeta>
23168 <refentrytitle><phrase>drm_dp_dpcd_writeb</phrase></refentrytitle>
23169 <manvolnum>9</manvolnum>
23170 <refmiscinfo class="version">4.1.27</refmiscinfo>
23171</refmeta>
23172<refnamediv>
23173 <refname>drm_dp_dpcd_writeb</refname>
23174 <refpurpose>
23175     write a single byte to the DPCD
23176 </refpurpose>
23177</refnamediv>
23178<refsynopsisdiv>
23179 <title>Synopsis</title>
23180  <funcsynopsis><funcprototype>
23181   <funcdef>ssize_t <function>drm_dp_dpcd_writeb </function></funcdef>
23182   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23183   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
23184   <paramdef>u8 <parameter>value</parameter></paramdef>
23185  </funcprototype></funcsynopsis>
23186</refsynopsisdiv>
23187<refsect1>
23188 <title>Arguments</title>
23189 <variablelist>
23190  <varlistentry>
23191   <term><parameter>aux</parameter></term>
23192   <listitem>
23193    <para>
23194     DisplayPort AUX channel
23195    </para>
23196   </listitem>
23197  </varlistentry>
23198  <varlistentry>
23199   <term><parameter>offset</parameter></term>
23200   <listitem>
23201    <para>
23202     address of the register to write
23203    </para>
23204   </listitem>
23205  </varlistentry>
23206  <varlistentry>
23207   <term><parameter>value</parameter></term>
23208   <listitem>
23209    <para>
23210     value to write to the register
23211    </para>
23212   </listitem>
23213  </varlistentry>
23214 </variablelist>
23215</refsect1>
23216<refsect1>
23217<title>Description</title>
23218<para>
23219   Returns the number of bytes transferred (1) on success, or a negative
23220   error code on failure.
23221</para>
23222</refsect1>
23223</refentry>
23224
23225<!-- drivers/gpu/drm/drm_dp_helper.c -->
23226<refentry id="API-drm-dp-dpcd-read">
23227<refentryinfo>
23228 <title>LINUX</title>
23229 <productname>Kernel Hackers Manual</productname>
23230 <date>July 2017</date>
23231</refentryinfo>
23232<refmeta>
23233 <refentrytitle><phrase>drm_dp_dpcd_read</phrase></refentrytitle>
23234 <manvolnum>9</manvolnum>
23235 <refmiscinfo class="version">4.1.27</refmiscinfo>
23236</refmeta>
23237<refnamediv>
23238 <refname>drm_dp_dpcd_read</refname>
23239 <refpurpose>
23240  read a series of bytes from the DPCD
23241 </refpurpose>
23242</refnamediv>
23243<refsynopsisdiv>
23244 <title>Synopsis</title>
23245  <funcsynopsis><funcprototype>
23246   <funcdef>ssize_t <function>drm_dp_dpcd_read </function></funcdef>
23247   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23248   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
23249   <paramdef>void * <parameter>buffer</parameter></paramdef>
23250   <paramdef>size_t <parameter>size</parameter></paramdef>
23251  </funcprototype></funcsynopsis>
23252</refsynopsisdiv>
23253<refsect1>
23254 <title>Arguments</title>
23255 <variablelist>
23256  <varlistentry>
23257   <term><parameter>aux</parameter></term>
23258   <listitem>
23259    <para>
23260     DisplayPort AUX channel
23261    </para>
23262   </listitem>
23263  </varlistentry>
23264  <varlistentry>
23265   <term><parameter>offset</parameter></term>
23266   <listitem>
23267    <para>
23268     address of the (first) register to read
23269    </para>
23270   </listitem>
23271  </varlistentry>
23272  <varlistentry>
23273   <term><parameter>buffer</parameter></term>
23274   <listitem>
23275    <para>
23276     buffer to store the register values
23277    </para>
23278   </listitem>
23279  </varlistentry>
23280  <varlistentry>
23281   <term><parameter>size</parameter></term>
23282   <listitem>
23283    <para>
23284     number of bytes in <parameter>buffer</parameter>
23285    </para>
23286   </listitem>
23287  </varlistentry>
23288 </variablelist>
23289</refsect1>
23290<refsect1>
23291<title>Description</title>
23292<para>
23293   Returns the number of bytes transferred on success, or a negative error
23294   code on failure. -EIO is returned if the request was NAKed by the sink or
23295   if the retry count was exceeded. If not all bytes were transferred, this
23296   function returns -EPROTO. Errors from the underlying AUX channel transfer
23297   function, with the exception of -EBUSY (which causes the transaction to
23298   be retried), are propagated to the caller.
23299</para>
23300</refsect1>
23301</refentry>
23302
23303<refentry id="API-drm-dp-dpcd-write">
23304<refentryinfo>
23305 <title>LINUX</title>
23306 <productname>Kernel Hackers Manual</productname>
23307 <date>July 2017</date>
23308</refentryinfo>
23309<refmeta>
23310 <refentrytitle><phrase>drm_dp_dpcd_write</phrase></refentrytitle>
23311 <manvolnum>9</manvolnum>
23312 <refmiscinfo class="version">4.1.27</refmiscinfo>
23313</refmeta>
23314<refnamediv>
23315 <refname>drm_dp_dpcd_write</refname>
23316 <refpurpose>
23317     write a series of bytes to the DPCD
23318 </refpurpose>
23319</refnamediv>
23320<refsynopsisdiv>
23321 <title>Synopsis</title>
23322  <funcsynopsis><funcprototype>
23323   <funcdef>ssize_t <function>drm_dp_dpcd_write </function></funcdef>
23324   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23325   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
23326   <paramdef>void * <parameter>buffer</parameter></paramdef>
23327   <paramdef>size_t <parameter>size</parameter></paramdef>
23328  </funcprototype></funcsynopsis>
23329</refsynopsisdiv>
23330<refsect1>
23331 <title>Arguments</title>
23332 <variablelist>
23333  <varlistentry>
23334   <term><parameter>aux</parameter></term>
23335   <listitem>
23336    <para>
23337     DisplayPort AUX channel
23338    </para>
23339   </listitem>
23340  </varlistentry>
23341  <varlistentry>
23342   <term><parameter>offset</parameter></term>
23343   <listitem>
23344    <para>
23345     address of the (first) register to write
23346    </para>
23347   </listitem>
23348  </varlistentry>
23349  <varlistentry>
23350   <term><parameter>buffer</parameter></term>
23351   <listitem>
23352    <para>
23353     buffer containing the values to write
23354    </para>
23355   </listitem>
23356  </varlistentry>
23357  <varlistentry>
23358   <term><parameter>size</parameter></term>
23359   <listitem>
23360    <para>
23361     number of bytes in <parameter>buffer</parameter>
23362    </para>
23363   </listitem>
23364  </varlistentry>
23365 </variablelist>
23366</refsect1>
23367<refsect1>
23368<title>Description</title>
23369<para>
23370   Returns the number of bytes transferred on success, or a negative error
23371   code on failure. -EIO is returned if the request was NAKed by the sink or
23372   if the retry count was exceeded. If not all bytes were transferred, this
23373   function returns -EPROTO. Errors from the underlying AUX channel transfer
23374   function, with the exception of -EBUSY (which causes the transaction to
23375   be retried), are propagated to the caller.
23376</para>
23377</refsect1>
23378</refentry>
23379
23380<refentry id="API-drm-dp-dpcd-read-link-status">
23381<refentryinfo>
23382 <title>LINUX</title>
23383 <productname>Kernel Hackers Manual</productname>
23384 <date>July 2017</date>
23385</refentryinfo>
23386<refmeta>
23387 <refentrytitle><phrase>drm_dp_dpcd_read_link_status</phrase></refentrytitle>
23388 <manvolnum>9</manvolnum>
23389 <refmiscinfo class="version">4.1.27</refmiscinfo>
23390</refmeta>
23391<refnamediv>
23392 <refname>drm_dp_dpcd_read_link_status</refname>
23393 <refpurpose>
23394     read DPCD link status (bytes 0x202-0x207)
23395 </refpurpose>
23396</refnamediv>
23397<refsynopsisdiv>
23398 <title>Synopsis</title>
23399  <funcsynopsis><funcprototype>
23400   <funcdef>int <function>drm_dp_dpcd_read_link_status </function></funcdef>
23401   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23402   <paramdef>u8 <parameter>status[DP_LINK_STATUS_SIZE]</parameter></paramdef>
23403  </funcprototype></funcsynopsis>
23404</refsynopsisdiv>
23405<refsect1>
23406 <title>Arguments</title>
23407 <variablelist>
23408  <varlistentry>
23409   <term><parameter>aux</parameter></term>
23410   <listitem>
23411    <para>
23412     DisplayPort AUX channel
23413    </para>
23414   </listitem>
23415  </varlistentry>
23416  <varlistentry>
23417   <term><parameter>status[DP_LINK_STATUS_SIZE]</parameter></term>
23418   <listitem>
23419    <para>
23420     buffer to store the link status in (must be at least 6 bytes)
23421    </para>
23422   </listitem>
23423  </varlistentry>
23424 </variablelist>
23425</refsect1>
23426<refsect1>
23427<title>Description</title>
23428<para>
23429   Returns the number of bytes transferred on success or a negative error
23430   code on failure.
23431</para>
23432</refsect1>
23433</refentry>
23434
23435<refentry id="API-drm-dp-link-probe">
23436<refentryinfo>
23437 <title>LINUX</title>
23438 <productname>Kernel Hackers Manual</productname>
23439 <date>July 2017</date>
23440</refentryinfo>
23441<refmeta>
23442 <refentrytitle><phrase>drm_dp_link_probe</phrase></refentrytitle>
23443 <manvolnum>9</manvolnum>
23444 <refmiscinfo class="version">4.1.27</refmiscinfo>
23445</refmeta>
23446<refnamediv>
23447 <refname>drm_dp_link_probe</refname>
23448 <refpurpose>
23449     probe a DisplayPort link for capabilities
23450 </refpurpose>
23451</refnamediv>
23452<refsynopsisdiv>
23453 <title>Synopsis</title>
23454  <funcsynopsis><funcprototype>
23455   <funcdef>int <function>drm_dp_link_probe </function></funcdef>
23456   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23457   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
23458  </funcprototype></funcsynopsis>
23459</refsynopsisdiv>
23460<refsect1>
23461 <title>Arguments</title>
23462 <variablelist>
23463  <varlistentry>
23464   <term><parameter>aux</parameter></term>
23465   <listitem>
23466    <para>
23467     DisplayPort AUX channel
23468    </para>
23469   </listitem>
23470  </varlistentry>
23471  <varlistentry>
23472   <term><parameter>link</parameter></term>
23473   <listitem>
23474    <para>
23475     pointer to structure in which to return link capabilities
23476    </para>
23477   </listitem>
23478  </varlistentry>
23479 </variablelist>
23480</refsect1>
23481<refsect1>
23482<title>Description</title>
23483<para>
23484   The structure filled in by this function can usually be passed directly
23485   into <function>drm_dp_link_power_up</function> and <function>drm_dp_link_configure</function> to power up and
23486   configure the link based on the link's capabilities.
23487   </para><para>
23488
23489   Returns 0 on success or a negative error code on failure.
23490</para>
23491</refsect1>
23492</refentry>
23493
23494<refentry id="API-drm-dp-link-power-up">
23495<refentryinfo>
23496 <title>LINUX</title>
23497 <productname>Kernel Hackers Manual</productname>
23498 <date>July 2017</date>
23499</refentryinfo>
23500<refmeta>
23501 <refentrytitle><phrase>drm_dp_link_power_up</phrase></refentrytitle>
23502 <manvolnum>9</manvolnum>
23503 <refmiscinfo class="version">4.1.27</refmiscinfo>
23504</refmeta>
23505<refnamediv>
23506 <refname>drm_dp_link_power_up</refname>
23507 <refpurpose>
23508     power up a DisplayPort link
23509 </refpurpose>
23510</refnamediv>
23511<refsynopsisdiv>
23512 <title>Synopsis</title>
23513  <funcsynopsis><funcprototype>
23514   <funcdef>int <function>drm_dp_link_power_up </function></funcdef>
23515   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23516   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
23517  </funcprototype></funcsynopsis>
23518</refsynopsisdiv>
23519<refsect1>
23520 <title>Arguments</title>
23521 <variablelist>
23522  <varlistentry>
23523   <term><parameter>aux</parameter></term>
23524   <listitem>
23525    <para>
23526     DisplayPort AUX channel
23527    </para>
23528   </listitem>
23529  </varlistentry>
23530  <varlistentry>
23531   <term><parameter>link</parameter></term>
23532   <listitem>
23533    <para>
23534     pointer to a structure containing the link configuration
23535    </para>
23536   </listitem>
23537  </varlistentry>
23538 </variablelist>
23539</refsect1>
23540<refsect1>
23541<title>Description</title>
23542<para>
23543   Returns 0 on success or a negative error code on failure.
23544</para>
23545</refsect1>
23546</refentry>
23547
23548<refentry id="API-drm-dp-link-power-down">
23549<refentryinfo>
23550 <title>LINUX</title>
23551 <productname>Kernel Hackers Manual</productname>
23552 <date>July 2017</date>
23553</refentryinfo>
23554<refmeta>
23555 <refentrytitle><phrase>drm_dp_link_power_down</phrase></refentrytitle>
23556 <manvolnum>9</manvolnum>
23557 <refmiscinfo class="version">4.1.27</refmiscinfo>
23558</refmeta>
23559<refnamediv>
23560 <refname>drm_dp_link_power_down</refname>
23561 <refpurpose>
23562     power down a DisplayPort link
23563 </refpurpose>
23564</refnamediv>
23565<refsynopsisdiv>
23566 <title>Synopsis</title>
23567  <funcsynopsis><funcprototype>
23568   <funcdef>int <function>drm_dp_link_power_down </function></funcdef>
23569   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23570   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
23571  </funcprototype></funcsynopsis>
23572</refsynopsisdiv>
23573<refsect1>
23574 <title>Arguments</title>
23575 <variablelist>
23576  <varlistentry>
23577   <term><parameter>aux</parameter></term>
23578   <listitem>
23579    <para>
23580     DisplayPort AUX channel
23581    </para>
23582   </listitem>
23583  </varlistentry>
23584  <varlistentry>
23585   <term><parameter>link</parameter></term>
23586   <listitem>
23587    <para>
23588     pointer to a structure containing the link configuration
23589    </para>
23590   </listitem>
23591  </varlistentry>
23592 </variablelist>
23593</refsect1>
23594<refsect1>
23595<title>Description</title>
23596<para>
23597   Returns 0 on success or a negative error code on failure.
23598</para>
23599</refsect1>
23600</refentry>
23601
23602<refentry id="API-drm-dp-link-configure">
23603<refentryinfo>
23604 <title>LINUX</title>
23605 <productname>Kernel Hackers Manual</productname>
23606 <date>July 2017</date>
23607</refentryinfo>
23608<refmeta>
23609 <refentrytitle><phrase>drm_dp_link_configure</phrase></refentrytitle>
23610 <manvolnum>9</manvolnum>
23611 <refmiscinfo class="version">4.1.27</refmiscinfo>
23612</refmeta>
23613<refnamediv>
23614 <refname>drm_dp_link_configure</refname>
23615 <refpurpose>
23616     configure a DisplayPort link
23617 </refpurpose>
23618</refnamediv>
23619<refsynopsisdiv>
23620 <title>Synopsis</title>
23621  <funcsynopsis><funcprototype>
23622   <funcdef>int <function>drm_dp_link_configure </function></funcdef>
23623   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23624   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
23625  </funcprototype></funcsynopsis>
23626</refsynopsisdiv>
23627<refsect1>
23628 <title>Arguments</title>
23629 <variablelist>
23630  <varlistentry>
23631   <term><parameter>aux</parameter></term>
23632   <listitem>
23633    <para>
23634     DisplayPort AUX channel
23635    </para>
23636   </listitem>
23637  </varlistentry>
23638  <varlistentry>
23639   <term><parameter>link</parameter></term>
23640   <listitem>
23641    <para>
23642     pointer to a structure containing the link configuration
23643    </para>
23644   </listitem>
23645  </varlistentry>
23646 </variablelist>
23647</refsect1>
23648<refsect1>
23649<title>Description</title>
23650<para>
23651   Returns 0 on success or a negative error code on failure.
23652</para>
23653</refsect1>
23654</refentry>
23655
23656<refentry id="API-drm-dp-aux-register">
23657<refentryinfo>
23658 <title>LINUX</title>
23659 <productname>Kernel Hackers Manual</productname>
23660 <date>July 2017</date>
23661</refentryinfo>
23662<refmeta>
23663 <refentrytitle><phrase>drm_dp_aux_register</phrase></refentrytitle>
23664 <manvolnum>9</manvolnum>
23665 <refmiscinfo class="version">4.1.27</refmiscinfo>
23666</refmeta>
23667<refnamediv>
23668 <refname>drm_dp_aux_register</refname>
23669 <refpurpose>
23670     initialise and register aux channel
23671 </refpurpose>
23672</refnamediv>
23673<refsynopsisdiv>
23674 <title>Synopsis</title>
23675  <funcsynopsis><funcprototype>
23676   <funcdef>int <function>drm_dp_aux_register </function></funcdef>
23677   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23678  </funcprototype></funcsynopsis>
23679</refsynopsisdiv>
23680<refsect1>
23681 <title>Arguments</title>
23682 <variablelist>
23683  <varlistentry>
23684   <term><parameter>aux</parameter></term>
23685   <listitem>
23686    <para>
23687     DisplayPort AUX channel
23688    </para>
23689   </listitem>
23690  </varlistentry>
23691 </variablelist>
23692</refsect1>
23693<refsect1>
23694<title>Description</title>
23695<para>
23696   Returns 0 on success or a negative error code on failure.
23697</para>
23698</refsect1>
23699</refentry>
23700
23701<refentry id="API-drm-dp-aux-unregister">
23702<refentryinfo>
23703 <title>LINUX</title>
23704 <productname>Kernel Hackers Manual</productname>
23705 <date>July 2017</date>
23706</refentryinfo>
23707<refmeta>
23708 <refentrytitle><phrase>drm_dp_aux_unregister</phrase></refentrytitle>
23709 <manvolnum>9</manvolnum>
23710 <refmiscinfo class="version">4.1.27</refmiscinfo>
23711</refmeta>
23712<refnamediv>
23713 <refname>drm_dp_aux_unregister</refname>
23714 <refpurpose>
23715     unregister an AUX adapter
23716 </refpurpose>
23717</refnamediv>
23718<refsynopsisdiv>
23719 <title>Synopsis</title>
23720  <funcsynopsis><funcprototype>
23721   <funcdef>void <function>drm_dp_aux_unregister </function></funcdef>
23722   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
23723  </funcprototype></funcsynopsis>
23724</refsynopsisdiv>
23725<refsect1>
23726 <title>Arguments</title>
23727 <variablelist>
23728  <varlistentry>
23729   <term><parameter>aux</parameter></term>
23730   <listitem>
23731    <para>
23732     DisplayPort AUX channel
23733    </para>
23734   </listitem>
23735  </varlistentry>
23736 </variablelist>
23737</refsect1>
23738</refentry>
23739
23740    </sect2>
23741    <sect2>
23742      <title>Display Port MST Helper Functions Reference</title>
23743<para>
23744   </para><para>
23745   These functions contain parts of the DisplayPort 1.2a MultiStream Transport
23746   protocol. The helpers contain a topology manager and bandwidth manager.
23747   The helpers encapsulate the sending and received of sideband msgs.
23748</para>
23749
23750<!-- include/drm/drm_dp_mst_helper.h -->
23751<refentry id="API-struct-drm-dp-vcpi">
23752<refentryinfo>
23753 <title>LINUX</title>
23754 <productname>Kernel Hackers Manual</productname>
23755 <date>July 2017</date>
23756</refentryinfo>
23757<refmeta>
23758 <refentrytitle><phrase>struct drm_dp_vcpi</phrase></refentrytitle>
23759 <manvolnum>9</manvolnum>
23760 <refmiscinfo class="version">4.1.27</refmiscinfo>
23761</refmeta>
23762<refnamediv>
23763 <refname>struct drm_dp_vcpi</refname>
23764 <refpurpose>
23765  Virtual Channel Payload Identifier
23766 </refpurpose>
23767</refnamediv>
23768<refsynopsisdiv>
23769 <title>Synopsis</title>
23770  <programlisting>
23771struct drm_dp_vcpi {
23772  int vcpi;
23773  int pbn;
23774  int aligned_pbn;
23775  int num_slots;
23776};  </programlisting>
23777</refsynopsisdiv>
23778 <refsect1>
23779  <title>Members</title>
23780  <variablelist>
23781    <varlistentry>      <term>vcpi</term>
23782      <listitem><para>
23783Virtual channel ID.
23784      </para></listitem>
23785    </varlistentry>
23786    <varlistentry>      <term>pbn</term>
23787      <listitem><para>
23788Payload Bandwidth Number for this channel
23789      </para></listitem>
23790    </varlistentry>
23791    <varlistentry>      <term>aligned_pbn</term>
23792      <listitem><para>
23793PBN aligned with slot size
23794      </para></listitem>
23795    </varlistentry>
23796    <varlistentry>      <term>num_slots</term>
23797      <listitem><para>
23798number of slots for this PBN
23799      </para></listitem>
23800    </varlistentry>
23801  </variablelist>
23802 </refsect1>
23803</refentry>
23804
23805<refentry id="API-struct-drm-dp-mst-port">
23806<refentryinfo>
23807 <title>LINUX</title>
23808 <productname>Kernel Hackers Manual</productname>
23809 <date>July 2017</date>
23810</refentryinfo>
23811<refmeta>
23812 <refentrytitle><phrase>struct drm_dp_mst_port</phrase></refentrytitle>
23813 <manvolnum>9</manvolnum>
23814 <refmiscinfo class="version">4.1.27</refmiscinfo>
23815</refmeta>
23816<refnamediv>
23817 <refname>struct drm_dp_mst_port</refname>
23818 <refpurpose>
23819     MST port
23820 </refpurpose>
23821</refnamediv>
23822<refsynopsisdiv>
23823 <title>Synopsis</title>
23824  <programlisting>
23825struct drm_dp_mst_port {
23826  struct kref kref;
23827  u8 port_num;
23828  bool input;
23829  bool mcs;
23830  bool ddps;
23831  u8 pdt;
23832  bool ldps;
23833  u8 dpcd_rev;
23834  u8 num_sdp_streams;
23835  u8 num_sdp_stream_sinks;
23836  uint16_t available_pbn;
23837  struct list_head next;
23838  struct drm_dp_mst_branch * mstb;
23839  struct drm_dp_aux aux;
23840  struct drm_dp_mst_branch * parent;
23841  struct drm_dp_vcpi vcpi;
23842  struct drm_connector * connector;
23843  struct drm_dp_mst_topology_mgr * mgr;
23844};  </programlisting>
23845</refsynopsisdiv>
23846 <refsect1>
23847  <title>Members</title>
23848  <variablelist>
23849    <varlistentry>      <term>kref</term>
23850      <listitem><para>
23851   reference count for this port.
23852      </para></listitem>
23853    </varlistentry>
23854    <varlistentry>      <term>port_num</term>
23855      <listitem><para>
23856   port number
23857      </para></listitem>
23858    </varlistentry>
23859    <varlistentry>      <term>input</term>
23860      <listitem><para>
23861   if this port is an input port.
23862      </para></listitem>
23863    </varlistentry>
23864    <varlistentry>      <term>mcs</term>
23865      <listitem><para>
23866   message capability status - DP 1.2 spec.
23867      </para></listitem>
23868    </varlistentry>
23869    <varlistentry>      <term>ddps</term>
23870      <listitem><para>
23871   DisplayPort Device Plug Status - DP 1.2
23872      </para></listitem>
23873    </varlistentry>
23874    <varlistentry>      <term>pdt</term>
23875      <listitem><para>
23876   Peer Device Type
23877      </para></listitem>
23878    </varlistentry>
23879    <varlistentry>      <term>ldps</term>
23880      <listitem><para>
23881   Legacy Device Plug Status
23882      </para></listitem>
23883    </varlistentry>
23884    <varlistentry>      <term>dpcd_rev</term>
23885      <listitem><para>
23886   DPCD revision of device on this port
23887      </para></listitem>
23888    </varlistentry>
23889    <varlistentry>      <term>num_sdp_streams</term>
23890      <listitem><para>
23891   Number of simultaneous streams
23892      </para></listitem>
23893    </varlistentry>
23894    <varlistentry>      <term>num_sdp_stream_sinks</term>
23895      <listitem><para>
23896   Number of stream sinks
23897      </para></listitem>
23898    </varlistentry>
23899    <varlistentry>      <term>available_pbn</term>
23900      <listitem><para>
23901   Available bandwidth for this port.
23902      </para></listitem>
23903    </varlistentry>
23904    <varlistentry>      <term>next</term>
23905      <listitem><para>
23906   link to next port on this branch device
23907      </para></listitem>
23908    </varlistentry>
23909    <varlistentry>      <term>mstb</term>
23910      <listitem><para>
23911   branch device attach below this port
23912      </para></listitem>
23913    </varlistentry>
23914    <varlistentry>      <term>aux</term>
23915      <listitem><para>
23916   i2c aux transport to talk to device connected to this port.
23917      </para></listitem>
23918    </varlistentry>
23919    <varlistentry>      <term>parent</term>
23920      <listitem><para>
23921   branch device parent of this port
23922      </para></listitem>
23923    </varlistentry>
23924    <varlistentry>      <term>vcpi</term>
23925      <listitem><para>
23926   Virtual Channel Payload info for this port.
23927      </para></listitem>
23928    </varlistentry>
23929    <varlistentry>      <term>connector</term>
23930      <listitem><para>
23931   DRM connector this port is connected to.
23932      </para></listitem>
23933    </varlistentry>
23934    <varlistentry>      <term>mgr</term>
23935      <listitem><para>
23936   topology manager this port lives under.
23937      </para></listitem>
23938    </varlistentry>
23939  </variablelist>
23940 </refsect1>
23941<refsect1>
23942<title>Description</title>
23943<para>
23944   This structure represents an MST port endpoint on a device somewhere
23945   in the MST topology.
23946</para>
23947</refsect1>
23948</refentry>
23949
23950<refentry id="API-struct-drm-dp-mst-branch">
23951<refentryinfo>
23952 <title>LINUX</title>
23953 <productname>Kernel Hackers Manual</productname>
23954 <date>July 2017</date>
23955</refentryinfo>
23956<refmeta>
23957 <refentrytitle><phrase>struct drm_dp_mst_branch</phrase></refentrytitle>
23958 <manvolnum>9</manvolnum>
23959 <refmiscinfo class="version">4.1.27</refmiscinfo>
23960</refmeta>
23961<refnamediv>
23962 <refname>struct drm_dp_mst_branch</refname>
23963 <refpurpose>
23964     MST branch device.
23965 </refpurpose>
23966</refnamediv>
23967<refsynopsisdiv>
23968 <title>Synopsis</title>
23969  <programlisting>
23970struct drm_dp_mst_branch {
23971  struct kref kref;
23972  u8 rad[8];
23973  u8 lct;
23974  int num_ports;
23975  int msg_slots;
23976  struct list_head ports;
23977  struct drm_dp_mst_port * port_parent;
23978  struct drm_dp_mst_topology_mgr * mgr;
23979  struct drm_dp_sideband_msg_tx * tx_slots[2];
23980  int last_seqno;
23981  bool link_address_sent;
23982  u8 guid[16];
23983};  </programlisting>
23984</refsynopsisdiv>
23985 <refsect1>
23986  <title>Members</title>
23987  <variablelist>
23988    <varlistentry>      <term>kref</term>
23989      <listitem><para>
23990   reference count for this port.
23991      </para></listitem>
23992    </varlistentry>
23993    <varlistentry>      <term>rad[8]</term>
23994      <listitem><para>
23995   Relative Address to talk to this branch device.
23996      </para></listitem>
23997    </varlistentry>
23998    <varlistentry>      <term>lct</term>
23999      <listitem><para>
24000   Link count total to talk to this branch device.
24001      </para></listitem>
24002    </varlistentry>
24003    <varlistentry>      <term>num_ports</term>
24004      <listitem><para>
24005   number of ports on the branch.
24006      </para></listitem>
24007    </varlistentry>
24008    <varlistentry>      <term>msg_slots</term>
24009      <listitem><para>
24010   one bit per transmitted msg slot.
24011      </para></listitem>
24012    </varlistentry>
24013    <varlistentry>      <term>ports</term>
24014      <listitem><para>
24015   linked list of ports on this branch.
24016      </para></listitem>
24017    </varlistentry>
24018    <varlistentry>      <term>port_parent</term>
24019      <listitem><para>
24020   pointer to the port parent, NULL if toplevel.
24021      </para></listitem>
24022    </varlistentry>
24023    <varlistentry>      <term>mgr</term>
24024      <listitem><para>
24025   topology manager for this branch device.
24026      </para></listitem>
24027    </varlistentry>
24028    <varlistentry>      <term>tx_slots[2]</term>
24029      <listitem><para>
24030   transmission slots for this device.
24031      </para></listitem>
24032    </varlistentry>
24033    <varlistentry>      <term>last_seqno</term>
24034      <listitem><para>
24035   last sequence number used to talk to this.
24036      </para></listitem>
24037    </varlistentry>
24038    <varlistentry>      <term>link_address_sent</term>
24039      <listitem><para>
24040   if a link address message has been sent to this device yet.
24041      </para></listitem>
24042    </varlistentry>
24043    <varlistentry>      <term>guid[16]</term>
24044      <listitem><para>
24045   guid for DP 1.2 branch device. port under this branch can be
24046   identified by port #.
24047      </para></listitem>
24048    </varlistentry>
24049  </variablelist>
24050 </refsect1>
24051<refsect1>
24052<title>Description</title>
24053<para>
24054   This structure represents an MST branch device, there is one
24055   primary branch device at the root, along with any other branches connected
24056   to downstream port of parent branches.
24057</para>
24058</refsect1>
24059</refentry>
24060
24061<refentry id="API-struct-drm-dp-mst-topology-mgr">
24062<refentryinfo>
24063 <title>LINUX</title>
24064 <productname>Kernel Hackers Manual</productname>
24065 <date>July 2017</date>
24066</refentryinfo>
24067<refmeta>
24068 <refentrytitle><phrase>struct drm_dp_mst_topology_mgr</phrase></refentrytitle>
24069 <manvolnum>9</manvolnum>
24070 <refmiscinfo class="version">4.1.27</refmiscinfo>
24071</refmeta>
24072<refnamediv>
24073 <refname>struct drm_dp_mst_topology_mgr</refname>
24074 <refpurpose>
24075     DisplayPort MST manager
24076 </refpurpose>
24077</refnamediv>
24078<refsynopsisdiv>
24079 <title>Synopsis</title>
24080  <programlisting>
24081struct drm_dp_mst_topology_mgr {
24082  struct device * dev;
24083  struct drm_dp_mst_topology_cbs * cbs;
24084  struct drm_dp_aux * aux;
24085  int max_payloads;
24086  int conn_base_id;
24087  struct drm_dp_sideband_msg_rx down_rep_recv;
24088  struct drm_dp_sideband_msg_rx up_req_recv;
24089  struct mutex lock;
24090  bool mst_state;
24091  struct drm_dp_mst_branch * mst_primary;
24092  u8 dpcd[DP_RECEIVER_CAP_SIZE];
24093  int pbn_div;
24094};  </programlisting>
24095</refsynopsisdiv>
24096 <refsect1>
24097  <title>Members</title>
24098  <variablelist>
24099    <varlistentry>      <term>dev</term>
24100      <listitem><para>
24101   device pointer for adding i2c devices etc.
24102      </para></listitem>
24103    </varlistentry>
24104    <varlistentry>      <term>cbs</term>
24105      <listitem><para>
24106   callbacks for connector addition and destruction.
24107   <parameter>max_dpcd_transaction_bytes</parameter> - maximum number of bytes to read/write in one go.
24108      </para></listitem>
24109    </varlistentry>
24110    <varlistentry>      <term>aux</term>
24111      <listitem><para>
24112   aux channel for the DP connector.
24113      </para></listitem>
24114    </varlistentry>
24115    <varlistentry>      <term>max_payloads</term>
24116      <listitem><para>
24117   maximum number of payloads the GPU can generate.
24118      </para></listitem>
24119    </varlistentry>
24120    <varlistentry>      <term>conn_base_id</term>
24121      <listitem><para>
24122   DRM connector ID this mgr is connected to.
24123      </para></listitem>
24124    </varlistentry>
24125    <varlistentry>      <term>down_rep_recv</term>
24126      <listitem><para>
24127   msg receiver state for down replies.
24128      </para></listitem>
24129    </varlistentry>
24130    <varlistentry>      <term>up_req_recv</term>
24131      <listitem><para>
24132   msg receiver state for up requests.
24133      </para></listitem>
24134    </varlistentry>
24135    <varlistentry>      <term>lock</term>
24136      <listitem><para>
24137   protects mst state, primary, dpcd.
24138      </para></listitem>
24139    </varlistentry>
24140    <varlistentry>      <term>mst_state</term>
24141      <listitem><para>
24142   if this manager is enabled for an MST capable port.
24143      </para></listitem>
24144    </varlistentry>
24145    <varlistentry>      <term>mst_primary</term>
24146      <listitem><para>
24147   pointer to the primary branch device.
24148      </para></listitem>
24149    </varlistentry>
24150    <varlistentry>      <term>dpcd[DP_RECEIVER_CAP_SIZE]</term>
24151      <listitem><para>
24152   cache of DPCD for primary port.
24153      </para></listitem>
24154    </varlistentry>
24155    <varlistentry>      <term>pbn_div</term>
24156      <listitem><para>
24157   PBN to slots divisor.
24158      </para></listitem>
24159    </varlistentry>
24160  </variablelist>
24161 </refsect1>
24162<refsect1>
24163<title>Description</title>
24164<para>
24165   This struct represents the toplevel displayport MST topology manager.
24166   There should be one instance of this for every MST capable DP connector
24167   on the GPU.
24168</para>
24169</refsect1>
24170</refentry>
24171
24172<!-- drivers/gpu/drm/drm_dp_mst_topology.c -->
24173<refentry id="API-drm-dp-update-payload-part1">
24174<refentryinfo>
24175 <title>LINUX</title>
24176 <productname>Kernel Hackers Manual</productname>
24177 <date>July 2017</date>
24178</refentryinfo>
24179<refmeta>
24180 <refentrytitle><phrase>drm_dp_update_payload_part1</phrase></refentrytitle>
24181 <manvolnum>9</manvolnum>
24182 <refmiscinfo class="version">4.1.27</refmiscinfo>
24183</refmeta>
24184<refnamediv>
24185 <refname>drm_dp_update_payload_part1</refname>
24186 <refpurpose>
24187  Execute payload update part 1
24188 </refpurpose>
24189</refnamediv>
24190<refsynopsisdiv>
24191 <title>Synopsis</title>
24192  <funcsynopsis><funcprototype>
24193   <funcdef>int <function>drm_dp_update_payload_part1 </function></funcdef>
24194   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24195  </funcprototype></funcsynopsis>
24196</refsynopsisdiv>
24197<refsect1>
24198 <title>Arguments</title>
24199 <variablelist>
24200  <varlistentry>
24201   <term><parameter>mgr</parameter></term>
24202   <listitem>
24203    <para>
24204     manager to use.
24205    </para>
24206   </listitem>
24207  </varlistentry>
24208 </variablelist>
24209</refsect1>
24210<refsect1>
24211<title>Description</title>
24212<para>
24213   This iterates over all proposed virtual channels, and tries to
24214   allocate space in the link for them. For 0-&gt;slots transitions,
24215   this step just writes the VCPI to the MST device. For slots-&gt;0
24216   transitions, this writes the updated VCPIs and removes the
24217   remote VC payloads.
24218   </para><para>
24219
24220   after calling this the driver should generate ACT and payload
24221   packets.
24222</para>
24223</refsect1>
24224</refentry>
24225
24226<refentry id="API-drm-dp-update-payload-part2">
24227<refentryinfo>
24228 <title>LINUX</title>
24229 <productname>Kernel Hackers Manual</productname>
24230 <date>July 2017</date>
24231</refentryinfo>
24232<refmeta>
24233 <refentrytitle><phrase>drm_dp_update_payload_part2</phrase></refentrytitle>
24234 <manvolnum>9</manvolnum>
24235 <refmiscinfo class="version">4.1.27</refmiscinfo>
24236</refmeta>
24237<refnamediv>
24238 <refname>drm_dp_update_payload_part2</refname>
24239 <refpurpose>
24240     Execute payload update part 2
24241 </refpurpose>
24242</refnamediv>
24243<refsynopsisdiv>
24244 <title>Synopsis</title>
24245  <funcsynopsis><funcprototype>
24246   <funcdef>int <function>drm_dp_update_payload_part2 </function></funcdef>
24247   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24248  </funcprototype></funcsynopsis>
24249</refsynopsisdiv>
24250<refsect1>
24251 <title>Arguments</title>
24252 <variablelist>
24253  <varlistentry>
24254   <term><parameter>mgr</parameter></term>
24255   <listitem>
24256    <para>
24257     manager to use.
24258    </para>
24259   </listitem>
24260  </varlistentry>
24261 </variablelist>
24262</refsect1>
24263<refsect1>
24264<title>Description</title>
24265<para>
24266   This iterates over all proposed virtual channels, and tries to
24267   allocate space in the link for them. For 0-&gt;slots transitions,
24268   this step writes the remote VC payload commands. For slots-&gt;0
24269   this just resets some internal state.
24270</para>
24271</refsect1>
24272</refentry>
24273
24274<refentry id="API-drm-dp-mst-topology-mgr-set-mst">
24275<refentryinfo>
24276 <title>LINUX</title>
24277 <productname>Kernel Hackers Manual</productname>
24278 <date>July 2017</date>
24279</refentryinfo>
24280<refmeta>
24281 <refentrytitle><phrase>drm_dp_mst_topology_mgr_set_mst</phrase></refentrytitle>
24282 <manvolnum>9</manvolnum>
24283 <refmiscinfo class="version">4.1.27</refmiscinfo>
24284</refmeta>
24285<refnamediv>
24286 <refname>drm_dp_mst_topology_mgr_set_mst</refname>
24287 <refpurpose>
24288     Set the MST state for a topology manager
24289 </refpurpose>
24290</refnamediv>
24291<refsynopsisdiv>
24292 <title>Synopsis</title>
24293  <funcsynopsis><funcprototype>
24294   <funcdef>int <function>drm_dp_mst_topology_mgr_set_mst </function></funcdef>
24295   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24296   <paramdef>bool <parameter>mst_state</parameter></paramdef>
24297  </funcprototype></funcsynopsis>
24298</refsynopsisdiv>
24299<refsect1>
24300 <title>Arguments</title>
24301 <variablelist>
24302  <varlistentry>
24303   <term><parameter>mgr</parameter></term>
24304   <listitem>
24305    <para>
24306     manager to set state for
24307    </para>
24308   </listitem>
24309  </varlistentry>
24310  <varlistentry>
24311   <term><parameter>mst_state</parameter></term>
24312   <listitem>
24313    <para>
24314     true to enable MST on this connector - false to disable.
24315    </para>
24316   </listitem>
24317  </varlistentry>
24318 </variablelist>
24319</refsect1>
24320<refsect1>
24321<title>Description</title>
24322<para>
24323   This is called by the driver when it detects an MST capable device plugged
24324   into a DP MST capable port, or when a DP MST capable device is unplugged.
24325</para>
24326</refsect1>
24327</refentry>
24328
24329<refentry id="API-drm-dp-mst-topology-mgr-suspend">
24330<refentryinfo>
24331 <title>LINUX</title>
24332 <productname>Kernel Hackers Manual</productname>
24333 <date>July 2017</date>
24334</refentryinfo>
24335<refmeta>
24336 <refentrytitle><phrase>drm_dp_mst_topology_mgr_suspend</phrase></refentrytitle>
24337 <manvolnum>9</manvolnum>
24338 <refmiscinfo class="version">4.1.27</refmiscinfo>
24339</refmeta>
24340<refnamediv>
24341 <refname>drm_dp_mst_topology_mgr_suspend</refname>
24342 <refpurpose>
24343     suspend the MST manager
24344 </refpurpose>
24345</refnamediv>
24346<refsynopsisdiv>
24347 <title>Synopsis</title>
24348  <funcsynopsis><funcprototype>
24349   <funcdef>void <function>drm_dp_mst_topology_mgr_suspend </function></funcdef>
24350   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24351  </funcprototype></funcsynopsis>
24352</refsynopsisdiv>
24353<refsect1>
24354 <title>Arguments</title>
24355 <variablelist>
24356  <varlistentry>
24357   <term><parameter>mgr</parameter></term>
24358   <listitem>
24359    <para>
24360     manager to suspend
24361    </para>
24362   </listitem>
24363  </varlistentry>
24364 </variablelist>
24365</refsect1>
24366<refsect1>
24367<title>Description</title>
24368<para>
24369   This function tells the MST device that we can't handle UP messages
24370   anymore. This should stop it from sending any since we are suspended.
24371</para>
24372</refsect1>
24373</refentry>
24374
24375<refentry id="API-drm-dp-mst-topology-mgr-resume">
24376<refentryinfo>
24377 <title>LINUX</title>
24378 <productname>Kernel Hackers Manual</productname>
24379 <date>July 2017</date>
24380</refentryinfo>
24381<refmeta>
24382 <refentrytitle><phrase>drm_dp_mst_topology_mgr_resume</phrase></refentrytitle>
24383 <manvolnum>9</manvolnum>
24384 <refmiscinfo class="version">4.1.27</refmiscinfo>
24385</refmeta>
24386<refnamediv>
24387 <refname>drm_dp_mst_topology_mgr_resume</refname>
24388 <refpurpose>
24389     resume the MST manager
24390 </refpurpose>
24391</refnamediv>
24392<refsynopsisdiv>
24393 <title>Synopsis</title>
24394  <funcsynopsis><funcprototype>
24395   <funcdef>int <function>drm_dp_mst_topology_mgr_resume </function></funcdef>
24396   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24397  </funcprototype></funcsynopsis>
24398</refsynopsisdiv>
24399<refsect1>
24400 <title>Arguments</title>
24401 <variablelist>
24402  <varlistentry>
24403   <term><parameter>mgr</parameter></term>
24404   <listitem>
24405    <para>
24406     manager to resume
24407    </para>
24408   </listitem>
24409  </varlistentry>
24410 </variablelist>
24411</refsect1>
24412<refsect1>
24413<title>Description</title>
24414<para>
24415   This will fetch DPCD and see if the device is still there,
24416   if it is, it will rewrite the MSTM control bits, and return.
24417   </para><para>
24418
24419   if the device fails this returns -1, and the driver should do
24420   a full MST reprobe, in case we were undocked.
24421</para>
24422</refsect1>
24423</refentry>
24424
24425<refentry id="API-drm-dp-mst-hpd-irq">
24426<refentryinfo>
24427 <title>LINUX</title>
24428 <productname>Kernel Hackers Manual</productname>
24429 <date>July 2017</date>
24430</refentryinfo>
24431<refmeta>
24432 <refentrytitle><phrase>drm_dp_mst_hpd_irq</phrase></refentrytitle>
24433 <manvolnum>9</manvolnum>
24434 <refmiscinfo class="version">4.1.27</refmiscinfo>
24435</refmeta>
24436<refnamediv>
24437 <refname>drm_dp_mst_hpd_irq</refname>
24438 <refpurpose>
24439     MST hotplug IRQ notify
24440 </refpurpose>
24441</refnamediv>
24442<refsynopsisdiv>
24443 <title>Synopsis</title>
24444  <funcsynopsis><funcprototype>
24445   <funcdef>int <function>drm_dp_mst_hpd_irq </function></funcdef>
24446   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24447   <paramdef>u8 * <parameter>esi</parameter></paramdef>
24448   <paramdef>bool * <parameter>handled</parameter></paramdef>
24449  </funcprototype></funcsynopsis>
24450</refsynopsisdiv>
24451<refsect1>
24452 <title>Arguments</title>
24453 <variablelist>
24454  <varlistentry>
24455   <term><parameter>mgr</parameter></term>
24456   <listitem>
24457    <para>
24458     manager to notify irq for.
24459    </para>
24460   </listitem>
24461  </varlistentry>
24462  <varlistentry>
24463   <term><parameter>esi</parameter></term>
24464   <listitem>
24465    <para>
24466     4 bytes from SINK_COUNT_ESI
24467    </para>
24468   </listitem>
24469  </varlistentry>
24470  <varlistentry>
24471   <term><parameter>handled</parameter></term>
24472   <listitem>
24473    <para>
24474     whether the hpd interrupt was consumed or not
24475    </para>
24476   </listitem>
24477  </varlistentry>
24478 </variablelist>
24479</refsect1>
24480<refsect1>
24481<title>Description</title>
24482<para>
24483   This should be called from the driver when it detects a short IRQ,
24484   along with the value of the DEVICE_SERVICE_IRQ_VECTOR_ESI0. The
24485   topology manager will process the sideband messages received as a result
24486   of this.
24487</para>
24488</refsect1>
24489</refentry>
24490
24491<refentry id="API-drm-dp-mst-detect-port">
24492<refentryinfo>
24493 <title>LINUX</title>
24494 <productname>Kernel Hackers Manual</productname>
24495 <date>July 2017</date>
24496</refentryinfo>
24497<refmeta>
24498 <refentrytitle><phrase>drm_dp_mst_detect_port</phrase></refentrytitle>
24499 <manvolnum>9</manvolnum>
24500 <refmiscinfo class="version">4.1.27</refmiscinfo>
24501</refmeta>
24502<refnamediv>
24503 <refname>drm_dp_mst_detect_port</refname>
24504 <refpurpose>
24505     get connection status for an MST port
24506 </refpurpose>
24507</refnamediv>
24508<refsynopsisdiv>
24509 <title>Synopsis</title>
24510  <funcsynopsis><funcprototype>
24511   <funcdef>enum drm_connector_status <function>drm_dp_mst_detect_port </function></funcdef>
24512   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
24513   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24514   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
24515  </funcprototype></funcsynopsis>
24516</refsynopsisdiv>
24517<refsect1>
24518 <title>Arguments</title>
24519 <variablelist>
24520  <varlistentry>
24521   <term><parameter>connector</parameter></term>
24522   <listitem>
24523    <para>
24524     -- undescribed --
24525    </para>
24526   </listitem>
24527  </varlistentry>
24528  <varlistentry>
24529   <term><parameter>mgr</parameter></term>
24530   <listitem>
24531    <para>
24532     manager for this port
24533    </para>
24534   </listitem>
24535  </varlistentry>
24536  <varlistentry>
24537   <term><parameter>port</parameter></term>
24538   <listitem>
24539    <para>
24540     unverified pointer to a port
24541    </para>
24542   </listitem>
24543  </varlistentry>
24544 </variablelist>
24545</refsect1>
24546<refsect1>
24547<title>Description</title>
24548<para>
24549   This returns the current connection state for a port. It validates the
24550   port pointer still exists so the caller doesn't require a reference
24551</para>
24552</refsect1>
24553</refentry>
24554
24555<refentry id="API-drm-dp-mst-get-edid">
24556<refentryinfo>
24557 <title>LINUX</title>
24558 <productname>Kernel Hackers Manual</productname>
24559 <date>July 2017</date>
24560</refentryinfo>
24561<refmeta>
24562 <refentrytitle><phrase>drm_dp_mst_get_edid</phrase></refentrytitle>
24563 <manvolnum>9</manvolnum>
24564 <refmiscinfo class="version">4.1.27</refmiscinfo>
24565</refmeta>
24566<refnamediv>
24567 <refname>drm_dp_mst_get_edid</refname>
24568 <refpurpose>
24569     get EDID for an MST port
24570 </refpurpose>
24571</refnamediv>
24572<refsynopsisdiv>
24573 <title>Synopsis</title>
24574  <funcsynopsis><funcprototype>
24575   <funcdef>struct edid * <function>drm_dp_mst_get_edid </function></funcdef>
24576   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
24577   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24578   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
24579  </funcprototype></funcsynopsis>
24580</refsynopsisdiv>
24581<refsect1>
24582 <title>Arguments</title>
24583 <variablelist>
24584  <varlistentry>
24585   <term><parameter>connector</parameter></term>
24586   <listitem>
24587    <para>
24588     toplevel connector to get EDID for
24589    </para>
24590   </listitem>
24591  </varlistentry>
24592  <varlistentry>
24593   <term><parameter>mgr</parameter></term>
24594   <listitem>
24595    <para>
24596     manager for this port
24597    </para>
24598   </listitem>
24599  </varlistentry>
24600  <varlistentry>
24601   <term><parameter>port</parameter></term>
24602   <listitem>
24603    <para>
24604     unverified pointer to a port.
24605    </para>
24606   </listitem>
24607  </varlistentry>
24608 </variablelist>
24609</refsect1>
24610<refsect1>
24611<title>Description</title>
24612<para>
24613   This returns an EDID for the port connected to a connector,
24614   It validates the pointer still exists so the caller doesn't require a
24615   reference.
24616</para>
24617</refsect1>
24618</refentry>
24619
24620<refentry id="API-drm-dp-find-vcpi-slots">
24621<refentryinfo>
24622 <title>LINUX</title>
24623 <productname>Kernel Hackers Manual</productname>
24624 <date>July 2017</date>
24625</refentryinfo>
24626<refmeta>
24627 <refentrytitle><phrase>drm_dp_find_vcpi_slots</phrase></refentrytitle>
24628 <manvolnum>9</manvolnum>
24629 <refmiscinfo class="version">4.1.27</refmiscinfo>
24630</refmeta>
24631<refnamediv>
24632 <refname>drm_dp_find_vcpi_slots</refname>
24633 <refpurpose>
24634     find slots for this PBN value
24635 </refpurpose>
24636</refnamediv>
24637<refsynopsisdiv>
24638 <title>Synopsis</title>
24639  <funcsynopsis><funcprototype>
24640   <funcdef>int <function>drm_dp_find_vcpi_slots </function></funcdef>
24641   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24642   <paramdef>int <parameter>pbn</parameter></paramdef>
24643  </funcprototype></funcsynopsis>
24644</refsynopsisdiv>
24645<refsect1>
24646 <title>Arguments</title>
24647 <variablelist>
24648  <varlistentry>
24649   <term><parameter>mgr</parameter></term>
24650   <listitem>
24651    <para>
24652     manager to use
24653    </para>
24654   </listitem>
24655  </varlistentry>
24656  <varlistentry>
24657   <term><parameter>pbn</parameter></term>
24658   <listitem>
24659    <para>
24660     payload bandwidth to convert into slots.
24661    </para>
24662   </listitem>
24663  </varlistentry>
24664 </variablelist>
24665</refsect1>
24666</refentry>
24667
24668<refentry id="API-drm-dp-mst-allocate-vcpi">
24669<refentryinfo>
24670 <title>LINUX</title>
24671 <productname>Kernel Hackers Manual</productname>
24672 <date>July 2017</date>
24673</refentryinfo>
24674<refmeta>
24675 <refentrytitle><phrase>drm_dp_mst_allocate_vcpi</phrase></refentrytitle>
24676 <manvolnum>9</manvolnum>
24677 <refmiscinfo class="version">4.1.27</refmiscinfo>
24678</refmeta>
24679<refnamediv>
24680 <refname>drm_dp_mst_allocate_vcpi</refname>
24681 <refpurpose>
24682     Allocate a virtual channel
24683 </refpurpose>
24684</refnamediv>
24685<refsynopsisdiv>
24686 <title>Synopsis</title>
24687  <funcsynopsis><funcprototype>
24688   <funcdef>bool <function>drm_dp_mst_allocate_vcpi </function></funcdef>
24689   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24690   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
24691   <paramdef>int <parameter>pbn</parameter></paramdef>
24692   <paramdef>int * <parameter>slots</parameter></paramdef>
24693  </funcprototype></funcsynopsis>
24694</refsynopsisdiv>
24695<refsect1>
24696 <title>Arguments</title>
24697 <variablelist>
24698  <varlistentry>
24699   <term><parameter>mgr</parameter></term>
24700   <listitem>
24701    <para>
24702     manager for this port
24703    </para>
24704   </listitem>
24705  </varlistentry>
24706  <varlistentry>
24707   <term><parameter>port</parameter></term>
24708   <listitem>
24709    <para>
24710     port to allocate a virtual channel for.
24711    </para>
24712   </listitem>
24713  </varlistentry>
24714  <varlistentry>
24715   <term><parameter>pbn</parameter></term>
24716   <listitem>
24717    <para>
24718     payload bandwidth number to request
24719    </para>
24720   </listitem>
24721  </varlistentry>
24722  <varlistentry>
24723   <term><parameter>slots</parameter></term>
24724   <listitem>
24725    <para>
24726     returned number of slots for this PBN.
24727    </para>
24728   </listitem>
24729  </varlistentry>
24730 </variablelist>
24731</refsect1>
24732</refentry>
24733
24734<refentry id="API-drm-dp-mst-reset-vcpi-slots">
24735<refentryinfo>
24736 <title>LINUX</title>
24737 <productname>Kernel Hackers Manual</productname>
24738 <date>July 2017</date>
24739</refentryinfo>
24740<refmeta>
24741 <refentrytitle><phrase>drm_dp_mst_reset_vcpi_slots</phrase></refentrytitle>
24742 <manvolnum>9</manvolnum>
24743 <refmiscinfo class="version">4.1.27</refmiscinfo>
24744</refmeta>
24745<refnamediv>
24746 <refname>drm_dp_mst_reset_vcpi_slots</refname>
24747 <refpurpose>
24748     Reset number of slots to 0 for VCPI
24749 </refpurpose>
24750</refnamediv>
24751<refsynopsisdiv>
24752 <title>Synopsis</title>
24753  <funcsynopsis><funcprototype>
24754   <funcdef>void <function>drm_dp_mst_reset_vcpi_slots </function></funcdef>
24755   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24756   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
24757  </funcprototype></funcsynopsis>
24758</refsynopsisdiv>
24759<refsect1>
24760 <title>Arguments</title>
24761 <variablelist>
24762  <varlistentry>
24763   <term><parameter>mgr</parameter></term>
24764   <listitem>
24765    <para>
24766     manager for this port
24767    </para>
24768   </listitem>
24769  </varlistentry>
24770  <varlistentry>
24771   <term><parameter>port</parameter></term>
24772   <listitem>
24773    <para>
24774     unverified pointer to a port.
24775    </para>
24776   </listitem>
24777  </varlistentry>
24778 </variablelist>
24779</refsect1>
24780<refsect1>
24781<title>Description</title>
24782<para>
24783   This just resets the number of slots for the ports VCPI for later programming.
24784</para>
24785</refsect1>
24786</refentry>
24787
24788<refentry id="API-drm-dp-mst-deallocate-vcpi">
24789<refentryinfo>
24790 <title>LINUX</title>
24791 <productname>Kernel Hackers Manual</productname>
24792 <date>July 2017</date>
24793</refentryinfo>
24794<refmeta>
24795 <refentrytitle><phrase>drm_dp_mst_deallocate_vcpi</phrase></refentrytitle>
24796 <manvolnum>9</manvolnum>
24797 <refmiscinfo class="version">4.1.27</refmiscinfo>
24798</refmeta>
24799<refnamediv>
24800 <refname>drm_dp_mst_deallocate_vcpi</refname>
24801 <refpurpose>
24802     deallocate a VCPI
24803 </refpurpose>
24804</refnamediv>
24805<refsynopsisdiv>
24806 <title>Synopsis</title>
24807  <funcsynopsis><funcprototype>
24808   <funcdef>void <function>drm_dp_mst_deallocate_vcpi </function></funcdef>
24809   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24810   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
24811  </funcprototype></funcsynopsis>
24812</refsynopsisdiv>
24813<refsect1>
24814 <title>Arguments</title>
24815 <variablelist>
24816  <varlistentry>
24817   <term><parameter>mgr</parameter></term>
24818   <listitem>
24819    <para>
24820     manager for this port
24821    </para>
24822   </listitem>
24823  </varlistentry>
24824  <varlistentry>
24825   <term><parameter>port</parameter></term>
24826   <listitem>
24827    <para>
24828     unverified port to deallocate vcpi for
24829    </para>
24830   </listitem>
24831  </varlistentry>
24832 </variablelist>
24833</refsect1>
24834</refentry>
24835
24836<refentry id="API-drm-dp-check-act-status">
24837<refentryinfo>
24838 <title>LINUX</title>
24839 <productname>Kernel Hackers Manual</productname>
24840 <date>July 2017</date>
24841</refentryinfo>
24842<refmeta>
24843 <refentrytitle><phrase>drm_dp_check_act_status</phrase></refentrytitle>
24844 <manvolnum>9</manvolnum>
24845 <refmiscinfo class="version">4.1.27</refmiscinfo>
24846</refmeta>
24847<refnamediv>
24848 <refname>drm_dp_check_act_status</refname>
24849 <refpurpose>
24850     Check ACT handled status.
24851 </refpurpose>
24852</refnamediv>
24853<refsynopsisdiv>
24854 <title>Synopsis</title>
24855  <funcsynopsis><funcprototype>
24856   <funcdef>int <function>drm_dp_check_act_status </function></funcdef>
24857   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24858  </funcprototype></funcsynopsis>
24859</refsynopsisdiv>
24860<refsect1>
24861 <title>Arguments</title>
24862 <variablelist>
24863  <varlistentry>
24864   <term><parameter>mgr</parameter></term>
24865   <listitem>
24866    <para>
24867     manager to use
24868    </para>
24869   </listitem>
24870  </varlistentry>
24871 </variablelist>
24872</refsect1>
24873<refsect1>
24874<title>Description</title>
24875<para>
24876   Check the payload status bits in the DPCD for ACT handled completion.
24877</para>
24878</refsect1>
24879</refentry>
24880
24881<refentry id="API-drm-dp-calc-pbn-mode">
24882<refentryinfo>
24883 <title>LINUX</title>
24884 <productname>Kernel Hackers Manual</productname>
24885 <date>July 2017</date>
24886</refentryinfo>
24887<refmeta>
24888 <refentrytitle><phrase>drm_dp_calc_pbn_mode</phrase></refentrytitle>
24889 <manvolnum>9</manvolnum>
24890 <refmiscinfo class="version">4.1.27</refmiscinfo>
24891</refmeta>
24892<refnamediv>
24893 <refname>drm_dp_calc_pbn_mode</refname>
24894 <refpurpose>
24895     Calculate the PBN for a mode.
24896 </refpurpose>
24897</refnamediv>
24898<refsynopsisdiv>
24899 <title>Synopsis</title>
24900  <funcsynopsis><funcprototype>
24901   <funcdef>int <function>drm_dp_calc_pbn_mode </function></funcdef>
24902   <paramdef>int <parameter>clock</parameter></paramdef>
24903   <paramdef>int <parameter>bpp</parameter></paramdef>
24904  </funcprototype></funcsynopsis>
24905</refsynopsisdiv>
24906<refsect1>
24907 <title>Arguments</title>
24908 <variablelist>
24909  <varlistentry>
24910   <term><parameter>clock</parameter></term>
24911   <listitem>
24912    <para>
24913     dot clock for the mode
24914    </para>
24915   </listitem>
24916  </varlistentry>
24917  <varlistentry>
24918   <term><parameter>bpp</parameter></term>
24919   <listitem>
24920    <para>
24921     bpp for the mode.
24922    </para>
24923   </listitem>
24924  </varlistentry>
24925 </variablelist>
24926</refsect1>
24927<refsect1>
24928<title>Description</title>
24929<para>
24930   This uses the formula in the spec to calculate the PBN value for a mode.
24931</para>
24932</refsect1>
24933</refentry>
24934
24935<refentry id="API-drm-dp-mst-dump-topology">
24936<refentryinfo>
24937 <title>LINUX</title>
24938 <productname>Kernel Hackers Manual</productname>
24939 <date>July 2017</date>
24940</refentryinfo>
24941<refmeta>
24942 <refentrytitle><phrase>drm_dp_mst_dump_topology</phrase></refentrytitle>
24943 <manvolnum>9</manvolnum>
24944 <refmiscinfo class="version">4.1.27</refmiscinfo>
24945</refmeta>
24946<refnamediv>
24947 <refname>drm_dp_mst_dump_topology</refname>
24948 <refpurpose>
24949   </refpurpose>
24950</refnamediv>
24951<refsynopsisdiv>
24952 <title>Synopsis</title>
24953  <funcsynopsis><funcprototype>
24954   <funcdef>void <function>drm_dp_mst_dump_topology </function></funcdef>
24955   <paramdef>struct seq_file * <parameter>m</parameter></paramdef>
24956   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
24957  </funcprototype></funcsynopsis>
24958</refsynopsisdiv>
24959<refsect1>
24960 <title>Arguments</title>
24961 <variablelist>
24962  <varlistentry>
24963   <term><parameter>m</parameter></term>
24964   <listitem>
24965    <para>
24966     seq_file to dump output to
24967    </para>
24968   </listitem>
24969  </varlistentry>
24970  <varlistentry>
24971   <term><parameter>mgr</parameter></term>
24972   <listitem>
24973    <para>
24974     manager to dump current topology for.
24975    </para>
24976   </listitem>
24977  </varlistentry>
24978 </variablelist>
24979</refsect1>
24980<refsect1>
24981<title>Description</title>
24982<para>
24983   helper to dump MST topology to a seq file for debugfs.
24984</para>
24985</refsect1>
24986</refentry>
24987
24988<refentry id="API-drm-dp-mst-topology-mgr-init">
24989<refentryinfo>
24990 <title>LINUX</title>
24991 <productname>Kernel Hackers Manual</productname>
24992 <date>July 2017</date>
24993</refentryinfo>
24994<refmeta>
24995 <refentrytitle><phrase>drm_dp_mst_topology_mgr_init</phrase></refentrytitle>
24996 <manvolnum>9</manvolnum>
24997 <refmiscinfo class="version">4.1.27</refmiscinfo>
24998</refmeta>
24999<refnamediv>
25000 <refname>drm_dp_mst_topology_mgr_init</refname>
25001 <refpurpose>
25002     initialise a topology manager
25003 </refpurpose>
25004</refnamediv>
25005<refsynopsisdiv>
25006 <title>Synopsis</title>
25007  <funcsynopsis><funcprototype>
25008   <funcdef>int <function>drm_dp_mst_topology_mgr_init </function></funcdef>
25009   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
25010   <paramdef>struct device * <parameter>dev</parameter></paramdef>
25011   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
25012   <paramdef>int <parameter>max_dpcd_transaction_bytes</parameter></paramdef>
25013   <paramdef>int <parameter>max_payloads</parameter></paramdef>
25014   <paramdef>int <parameter>conn_base_id</parameter></paramdef>
25015  </funcprototype></funcsynopsis>
25016</refsynopsisdiv>
25017<refsect1>
25018 <title>Arguments</title>
25019 <variablelist>
25020  <varlistentry>
25021   <term><parameter>mgr</parameter></term>
25022   <listitem>
25023    <para>
25024     manager struct to initialise
25025    </para>
25026   </listitem>
25027  </varlistentry>
25028  <varlistentry>
25029   <term><parameter>dev</parameter></term>
25030   <listitem>
25031    <para>
25032     device providing this structure - for i2c addition.
25033    </para>
25034   </listitem>
25035  </varlistentry>
25036  <varlistentry>
25037   <term><parameter>aux</parameter></term>
25038   <listitem>
25039    <para>
25040     DP helper aux channel to talk to this device
25041    </para>
25042   </listitem>
25043  </varlistentry>
25044  <varlistentry>
25045   <term><parameter>max_dpcd_transaction_bytes</parameter></term>
25046   <listitem>
25047    <para>
25048     hw specific DPCD transaction limit
25049    </para>
25050   </listitem>
25051  </varlistentry>
25052  <varlistentry>
25053   <term><parameter>max_payloads</parameter></term>
25054   <listitem>
25055    <para>
25056     maximum number of payloads this GPU can source
25057    </para>
25058   </listitem>
25059  </varlistentry>
25060  <varlistentry>
25061   <term><parameter>conn_base_id</parameter></term>
25062   <listitem>
25063    <para>
25064     the connector object ID the MST device is connected to.
25065    </para>
25066   </listitem>
25067  </varlistentry>
25068 </variablelist>
25069</refsect1>
25070<refsect1>
25071<title>Description</title>
25072<para>
25073   Return 0 for success, or negative error code on failure
25074</para>
25075</refsect1>
25076</refentry>
25077
25078<refentry id="API-drm-dp-mst-topology-mgr-destroy">
25079<refentryinfo>
25080 <title>LINUX</title>
25081 <productname>Kernel Hackers Manual</productname>
25082 <date>July 2017</date>
25083</refentryinfo>
25084<refmeta>
25085 <refentrytitle><phrase>drm_dp_mst_topology_mgr_destroy</phrase></refentrytitle>
25086 <manvolnum>9</manvolnum>
25087 <refmiscinfo class="version">4.1.27</refmiscinfo>
25088</refmeta>
25089<refnamediv>
25090 <refname>drm_dp_mst_topology_mgr_destroy</refname>
25091 <refpurpose>
25092     destroy topology manager.
25093 </refpurpose>
25094</refnamediv>
25095<refsynopsisdiv>
25096 <title>Synopsis</title>
25097  <funcsynopsis><funcprototype>
25098   <funcdef>void <function>drm_dp_mst_topology_mgr_destroy </function></funcdef>
25099   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
25100  </funcprototype></funcsynopsis>
25101</refsynopsisdiv>
25102<refsect1>
25103 <title>Arguments</title>
25104 <variablelist>
25105  <varlistentry>
25106   <term><parameter>mgr</parameter></term>
25107   <listitem>
25108    <para>
25109     manager to destroy
25110    </para>
25111   </listitem>
25112  </varlistentry>
25113 </variablelist>
25114</refsect1>
25115</refentry>
25116
25117    </sect2>
25118    <sect2>
25119      <title>MIPI DSI Helper Functions Reference</title>
25120<para>
25121   </para><para>
25122   These functions contain some common logic and helpers to deal with MIPI DSI
25123   peripherals.
25124   </para><para>
25125   Helpers are provided for a number of standard MIPI DSI command as well as a
25126   subset of the MIPI DCS command set.
25127</para>
25128
25129<!-- include/drm/drm_mipi_dsi.h -->
25130<refentry id="API-struct-mipi-dsi-msg">
25131<refentryinfo>
25132 <title>LINUX</title>
25133 <productname>Kernel Hackers Manual</productname>
25134 <date>July 2017</date>
25135</refentryinfo>
25136<refmeta>
25137 <refentrytitle><phrase>struct mipi_dsi_msg</phrase></refentrytitle>
25138 <manvolnum>9</manvolnum>
25139 <refmiscinfo class="version">4.1.27</refmiscinfo>
25140</refmeta>
25141<refnamediv>
25142 <refname>struct mipi_dsi_msg</refname>
25143 <refpurpose>
25144  read/write DSI buffer
25145 </refpurpose>
25146</refnamediv>
25147<refsynopsisdiv>
25148 <title>Synopsis</title>
25149  <programlisting>
25150struct mipi_dsi_msg {
25151  u8 channel;
25152  u8 type;
25153  u16 flags;
25154  size_t tx_len;
25155  const void * tx_buf;
25156  size_t rx_len;
25157  void * rx_buf;
25158};  </programlisting>
25159</refsynopsisdiv>
25160 <refsect1>
25161  <title>Members</title>
25162  <variablelist>
25163    <varlistentry>      <term>channel</term>
25164      <listitem><para>
25165virtual channel id
25166      </para></listitem>
25167    </varlistentry>
25168    <varlistentry>      <term>type</term>
25169      <listitem><para>
25170payload data type
25171      </para></listitem>
25172    </varlistentry>
25173    <varlistentry>      <term>flags</term>
25174      <listitem><para>
25175flags controlling this message transmission
25176      </para></listitem>
25177    </varlistentry>
25178    <varlistentry>      <term>tx_len</term>
25179      <listitem><para>
25180length of <parameter>tx_buf</parameter>
25181      </para></listitem>
25182    </varlistentry>
25183    <varlistentry>      <term>tx_buf</term>
25184      <listitem><para>
25185data to be written
25186      </para></listitem>
25187    </varlistentry>
25188    <varlistentry>      <term>rx_len</term>
25189      <listitem><para>
25190length of <parameter>rx_buf</parameter>
25191      </para></listitem>
25192    </varlistentry>
25193    <varlistentry>      <term>rx_buf</term>
25194      <listitem><para>
25195data to be read, or NULL
25196      </para></listitem>
25197    </varlistentry>
25198  </variablelist>
25199 </refsect1>
25200</refentry>
25201
25202<refentry id="API-struct-mipi-dsi-packet">
25203<refentryinfo>
25204 <title>LINUX</title>
25205 <productname>Kernel Hackers Manual</productname>
25206 <date>July 2017</date>
25207</refentryinfo>
25208<refmeta>
25209 <refentrytitle><phrase>struct mipi_dsi_packet</phrase></refentrytitle>
25210 <manvolnum>9</manvolnum>
25211 <refmiscinfo class="version">4.1.27</refmiscinfo>
25212</refmeta>
25213<refnamediv>
25214 <refname>struct mipi_dsi_packet</refname>
25215 <refpurpose>
25216     represents a MIPI DSI packet in protocol format
25217 </refpurpose>
25218</refnamediv>
25219<refsynopsisdiv>
25220 <title>Synopsis</title>
25221  <programlisting>
25222struct mipi_dsi_packet {
25223  size_t size;
25224  u8 header[4];
25225  size_t payload_length;
25226  const u8 * payload;
25227};  </programlisting>
25228</refsynopsisdiv>
25229 <refsect1>
25230  <title>Members</title>
25231  <variablelist>
25232    <varlistentry>      <term>size</term>
25233      <listitem><para>
25234   size (in bytes) of the packet
25235      </para></listitem>
25236    </varlistentry>
25237    <varlistentry>      <term>header[4]</term>
25238      <listitem><para>
25239   the four bytes that make up the header (Data ID, Word Count or
25240   Packet Data, and ECC)
25241      </para></listitem>
25242    </varlistentry>
25243    <varlistentry>      <term>payload_length</term>
25244      <listitem><para>
25245   number of bytes in the payload
25246      </para></listitem>
25247    </varlistentry>
25248    <varlistentry>      <term>payload</term>
25249      <listitem><para>
25250   a pointer to a buffer containing the payload, if any
25251      </para></listitem>
25252    </varlistentry>
25253  </variablelist>
25254 </refsect1>
25255</refentry>
25256
25257<refentry id="API-struct-mipi-dsi-host-ops">
25258<refentryinfo>
25259 <title>LINUX</title>
25260 <productname>Kernel Hackers Manual</productname>
25261 <date>July 2017</date>
25262</refentryinfo>
25263<refmeta>
25264 <refentrytitle><phrase>struct mipi_dsi_host_ops</phrase></refentrytitle>
25265 <manvolnum>9</manvolnum>
25266 <refmiscinfo class="version">4.1.27</refmiscinfo>
25267</refmeta>
25268<refnamediv>
25269 <refname>struct mipi_dsi_host_ops</refname>
25270 <refpurpose>
25271     DSI bus operations
25272 </refpurpose>
25273</refnamediv>
25274<refsynopsisdiv>
25275 <title>Synopsis</title>
25276  <programlisting>
25277struct mipi_dsi_host_ops {
25278  int (* attach) (struct mipi_dsi_host *host,struct mipi_dsi_device *dsi);
25279  int (* detach) (struct mipi_dsi_host *host,struct mipi_dsi_device *dsi);
25280  ssize_t (* transfer) (struct mipi_dsi_host *host,const struct mipi_dsi_msg *msg);
25281};  </programlisting>
25282</refsynopsisdiv>
25283 <refsect1>
25284  <title>Members</title>
25285  <variablelist>
25286    <varlistentry>      <term>attach</term>
25287      <listitem><para>
25288   attach DSI device to DSI host
25289      </para></listitem>
25290    </varlistentry>
25291    <varlistentry>      <term>detach</term>
25292      <listitem><para>
25293   detach DSI device from DSI host
25294      </para></listitem>
25295    </varlistentry>
25296    <varlistentry>      <term>transfer</term>
25297      <listitem><para>
25298   transmit a DSI packet
25299      </para></listitem>
25300    </varlistentry>
25301  </variablelist>
25302 </refsect1>
25303<refsect1>
25304<title>Description</title>
25305<para>
25306   DSI packets transmitted by .<function>transfer</function> are passed in as mipi_dsi_msg
25307   structures. This structure contains information about the type of packet
25308   being transmitted as well as the transmit and receive buffers. When an
25309   error is encountered during transmission, this function will return a
25310   negative error code. On success it shall return the number of bytes
25311   transmitted for write packets or the number of bytes received for read
25312   packets.
25313   </para><para>
25314
25315   Note that typically DSI packet transmission is atomic, so the .<function>transfer</function>
25316   function will seldomly return anything other than the number of bytes
25317   contained in the transmit buffer on success.
25318</para>
25319</refsect1>
25320</refentry>
25321
25322<refentry id="API-struct-mipi-dsi-host">
25323<refentryinfo>
25324 <title>LINUX</title>
25325 <productname>Kernel Hackers Manual</productname>
25326 <date>July 2017</date>
25327</refentryinfo>
25328<refmeta>
25329 <refentrytitle><phrase>struct mipi_dsi_host</phrase></refentrytitle>
25330 <manvolnum>9</manvolnum>
25331 <refmiscinfo class="version">4.1.27</refmiscinfo>
25332</refmeta>
25333<refnamediv>
25334 <refname>struct mipi_dsi_host</refname>
25335 <refpurpose>
25336     DSI host device
25337 </refpurpose>
25338</refnamediv>
25339<refsynopsisdiv>
25340 <title>Synopsis</title>
25341  <programlisting>
25342struct mipi_dsi_host {
25343  struct device * dev;
25344  const struct mipi_dsi_host_ops * ops;
25345};  </programlisting>
25346</refsynopsisdiv>
25347 <refsect1>
25348  <title>Members</title>
25349  <variablelist>
25350    <varlistentry>      <term>dev</term>
25351      <listitem><para>
25352   driver model device node for this DSI host
25353      </para></listitem>
25354    </varlistentry>
25355    <varlistentry>      <term>ops</term>
25356      <listitem><para>
25357   DSI host operations
25358      </para></listitem>
25359    </varlistentry>
25360  </variablelist>
25361 </refsect1>
25362</refentry>
25363
25364<refentry id="API-struct-mipi-dsi-device">
25365<refentryinfo>
25366 <title>LINUX</title>
25367 <productname>Kernel Hackers Manual</productname>
25368 <date>July 2017</date>
25369</refentryinfo>
25370<refmeta>
25371 <refentrytitle><phrase>struct mipi_dsi_device</phrase></refentrytitle>
25372 <manvolnum>9</manvolnum>
25373 <refmiscinfo class="version">4.1.27</refmiscinfo>
25374</refmeta>
25375<refnamediv>
25376 <refname>struct mipi_dsi_device</refname>
25377 <refpurpose>
25378     DSI peripheral device
25379 </refpurpose>
25380</refnamediv>
25381<refsynopsisdiv>
25382 <title>Synopsis</title>
25383  <programlisting>
25384struct mipi_dsi_device {
25385  struct mipi_dsi_host * host;
25386  struct device dev;
25387  unsigned int channel;
25388  unsigned int lanes;
25389  enum mipi_dsi_pixel_format format;
25390  unsigned long mode_flags;
25391};  </programlisting>
25392</refsynopsisdiv>
25393 <refsect1>
25394  <title>Members</title>
25395  <variablelist>
25396    <varlistentry>      <term>host</term>
25397      <listitem><para>
25398   DSI host for this peripheral
25399      </para></listitem>
25400    </varlistentry>
25401    <varlistentry>      <term>dev</term>
25402      <listitem><para>
25403   driver model device node for this peripheral
25404      </para></listitem>
25405    </varlistentry>
25406    <varlistentry>      <term>channel</term>
25407      <listitem><para>
25408   virtual channel assigned to the peripheral
25409      </para></listitem>
25410    </varlistentry>
25411    <varlistentry>      <term>lanes</term>
25412      <listitem><para>
25413   number of active data lanes
25414      </para></listitem>
25415    </varlistentry>
25416    <varlistentry>      <term>format</term>
25417      <listitem><para>
25418   pixel format for video mode
25419      </para></listitem>
25420    </varlistentry>
25421    <varlistentry>      <term>mode_flags</term>
25422      <listitem><para>
25423   DSI operation mode related flags
25424      </para></listitem>
25425    </varlistentry>
25426  </variablelist>
25427 </refsect1>
25428</refentry>
25429
25430<refentry id="API-enum-mipi-dsi-dcs-tear-mode">
25431<refentryinfo>
25432 <title>LINUX</title>
25433 <productname>Kernel Hackers Manual</productname>
25434 <date>July 2017</date>
25435</refentryinfo>
25436<refmeta>
25437 <refentrytitle><phrase>enum mipi_dsi_dcs_tear_mode</phrase></refentrytitle>
25438 <manvolnum>9</manvolnum>
25439 <refmiscinfo class="version">4.1.27</refmiscinfo>
25440</refmeta>
25441<refnamediv>
25442 <refname>enum mipi_dsi_dcs_tear_mode</refname>
25443 <refpurpose>
25444     Tearing Effect Output Line mode
25445 </refpurpose>
25446</refnamediv>
25447<refsynopsisdiv>
25448 <title>Synopsis</title>
25449  <programlisting>
25450enum mipi_dsi_dcs_tear_mode {
25451  MIPI_DSI_DCS_TEAR_MODE_VBLANK,
25452  MIPI_DSI_DCS_TEAR_MODE_VHBLANK
25453};  </programlisting>
25454</refsynopsisdiv>
25455<refsect1>
25456 <title>Constants</title>
25457  <variablelist>
25458    <varlistentry>      <term>MIPI_DSI_DCS_TEAR_MODE_VBLANK</term>
25459      <listitem><para>
25460   the TE output line consists of V-Blanking
25461   information only
25462      </para></listitem>
25463    </varlistentry>
25464    <varlistentry>      <term>MIPI_DSI_DCS_TEAR_MODE_VHBLANK</term>
25465      <listitem><para>
25466   the TE output line consists of both
25467   V-Blanking and H-Blanking information
25468      </para></listitem>
25469    </varlistentry>
25470  </variablelist>
25471</refsect1>
25472</refentry>
25473
25474<refentry id="API-struct-mipi-dsi-driver">
25475<refentryinfo>
25476 <title>LINUX</title>
25477 <productname>Kernel Hackers Manual</productname>
25478 <date>July 2017</date>
25479</refentryinfo>
25480<refmeta>
25481 <refentrytitle><phrase>struct mipi_dsi_driver</phrase></refentrytitle>
25482 <manvolnum>9</manvolnum>
25483 <refmiscinfo class="version">4.1.27</refmiscinfo>
25484</refmeta>
25485<refnamediv>
25486 <refname>struct mipi_dsi_driver</refname>
25487 <refpurpose>
25488     DSI driver
25489 </refpurpose>
25490</refnamediv>
25491<refsynopsisdiv>
25492 <title>Synopsis</title>
25493  <programlisting>
25494struct mipi_dsi_driver {
25495  struct device_driver driver;
25496  int(* probe) (struct mipi_dsi_device *dsi);
25497  int(* remove) (struct mipi_dsi_device *dsi);
25498  void (* shutdown) (struct mipi_dsi_device *dsi);
25499};  </programlisting>
25500</refsynopsisdiv>
25501 <refsect1>
25502  <title>Members</title>
25503  <variablelist>
25504    <varlistentry>      <term>driver</term>
25505      <listitem><para>
25506   device driver model driver
25507      </para></listitem>
25508    </varlistentry>
25509    <varlistentry>      <term>probe</term>
25510      <listitem><para>
25511   callback for device binding
25512      </para></listitem>
25513    </varlistentry>
25514    <varlistentry>      <term>remove</term>
25515      <listitem><para>
25516   callback for device unbinding
25517      </para></listitem>
25518    </varlistentry>
25519    <varlistentry>      <term>shutdown</term>
25520      <listitem><para>
25521   called at shutdown time to quiesce the device
25522      </para></listitem>
25523    </varlistentry>
25524  </variablelist>
25525 </refsect1>
25526</refentry>
25527
25528<!-- drivers/gpu/drm/drm_mipi_dsi.c -->
25529<refentry id="API-of-find-mipi-dsi-device-by-node">
25530<refentryinfo>
25531 <title>LINUX</title>
25532 <productname>Kernel Hackers Manual</productname>
25533 <date>July 2017</date>
25534</refentryinfo>
25535<refmeta>
25536 <refentrytitle><phrase>of_find_mipi_dsi_device_by_node</phrase></refentrytitle>
25537 <manvolnum>9</manvolnum>
25538 <refmiscinfo class="version">4.1.27</refmiscinfo>
25539</refmeta>
25540<refnamediv>
25541 <refname>of_find_mipi_dsi_device_by_node</refname>
25542 <refpurpose>
25543  find the MIPI DSI device matching a device tree node
25544 </refpurpose>
25545</refnamediv>
25546<refsynopsisdiv>
25547 <title>Synopsis</title>
25548  <funcsynopsis><funcprototype>
25549   <funcdef>struct mipi_dsi_device * <function>of_find_mipi_dsi_device_by_node </function></funcdef>
25550   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
25551  </funcprototype></funcsynopsis>
25552</refsynopsisdiv>
25553<refsect1>
25554 <title>Arguments</title>
25555 <variablelist>
25556  <varlistentry>
25557   <term><parameter>np</parameter></term>
25558   <listitem>
25559    <para>
25560     device tree node
25561    </para>
25562   </listitem>
25563  </varlistentry>
25564 </variablelist>
25565</refsect1>
25566<refsect1>
25567<title>Return</title>
25568<para>
25569   A pointer to the MIPI DSI device corresponding to <parameter>np</parameter> or NULL if no
25570   such device exists (or has not been registered yet).
25571</para>
25572</refsect1>
25573</refentry>
25574
25575<refentry id="API-mipi-dsi-attach">
25576<refentryinfo>
25577 <title>LINUX</title>
25578 <productname>Kernel Hackers Manual</productname>
25579 <date>July 2017</date>
25580</refentryinfo>
25581<refmeta>
25582 <refentrytitle><phrase>mipi_dsi_attach</phrase></refentrytitle>
25583 <manvolnum>9</manvolnum>
25584 <refmiscinfo class="version">4.1.27</refmiscinfo>
25585</refmeta>
25586<refnamediv>
25587 <refname>mipi_dsi_attach</refname>
25588 <refpurpose>
25589     attach a DSI device to its DSI host
25590 </refpurpose>
25591</refnamediv>
25592<refsynopsisdiv>
25593 <title>Synopsis</title>
25594  <funcsynopsis><funcprototype>
25595   <funcdef>int <function>mipi_dsi_attach </function></funcdef>
25596   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
25597  </funcprototype></funcsynopsis>
25598</refsynopsisdiv>
25599<refsect1>
25600 <title>Arguments</title>
25601 <variablelist>
25602  <varlistentry>
25603   <term><parameter>dsi</parameter></term>
25604   <listitem>
25605    <para>
25606     DSI peripheral
25607    </para>
25608   </listitem>
25609  </varlistentry>
25610 </variablelist>
25611</refsect1>
25612</refentry>
25613
25614<refentry id="API-mipi-dsi-detach">
25615<refentryinfo>
25616 <title>LINUX</title>
25617 <productname>Kernel Hackers Manual</productname>
25618 <date>July 2017</date>
25619</refentryinfo>
25620<refmeta>
25621 <refentrytitle><phrase>mipi_dsi_detach</phrase></refentrytitle>
25622 <manvolnum>9</manvolnum>
25623 <refmiscinfo class="version">4.1.27</refmiscinfo>
25624</refmeta>
25625<refnamediv>
25626 <refname>mipi_dsi_detach</refname>
25627 <refpurpose>
25628     detach a DSI device from its DSI host
25629 </refpurpose>
25630</refnamediv>
25631<refsynopsisdiv>
25632 <title>Synopsis</title>
25633  <funcsynopsis><funcprototype>
25634   <funcdef>int <function>mipi_dsi_detach </function></funcdef>
25635   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
25636  </funcprototype></funcsynopsis>
25637</refsynopsisdiv>
25638<refsect1>
25639 <title>Arguments</title>
25640 <variablelist>
25641  <varlistentry>
25642   <term><parameter>dsi</parameter></term>
25643   <listitem>
25644    <para>
25645     DSI peripheral
25646    </para>
25647   </listitem>
25648  </varlistentry>
25649 </variablelist>
25650</refsect1>
25651</refentry>
25652
25653<refentry id="API-mipi-dsi-packet-format-is-short">
25654<refentryinfo>
25655 <title>LINUX</title>
25656 <productname>Kernel Hackers Manual</productname>
25657 <date>July 2017</date>
25658</refentryinfo>
25659<refmeta>
25660 <refentrytitle><phrase>mipi_dsi_packet_format_is_short</phrase></refentrytitle>
25661 <manvolnum>9</manvolnum>
25662 <refmiscinfo class="version">4.1.27</refmiscinfo>
25663</refmeta>
25664<refnamediv>
25665 <refname>mipi_dsi_packet_format_is_short</refname>
25666 <refpurpose>
25667     check if a packet is of the short format
25668 </refpurpose>
25669</refnamediv>
25670<refsynopsisdiv>
25671 <title>Synopsis</title>
25672  <funcsynopsis><funcprototype>
25673   <funcdef>bool <function>mipi_dsi_packet_format_is_short </function></funcdef>
25674   <paramdef>u8 <parameter>type</parameter></paramdef>
25675  </funcprototype></funcsynopsis>
25676</refsynopsisdiv>
25677<refsect1>
25678 <title>Arguments</title>
25679 <variablelist>
25680  <varlistentry>
25681   <term><parameter>type</parameter></term>
25682   <listitem>
25683    <para>
25684     MIPI DSI data type of the packet
25685    </para>
25686   </listitem>
25687  </varlistentry>
25688 </variablelist>
25689</refsect1>
25690<refsect1>
25691<title>Return</title>
25692<para>
25693   true if the packet for the given data type is a short packet, false
25694   otherwise.
25695</para>
25696</refsect1>
25697</refentry>
25698
25699<refentry id="API-mipi-dsi-packet-format-is-long">
25700<refentryinfo>
25701 <title>LINUX</title>
25702 <productname>Kernel Hackers Manual</productname>
25703 <date>July 2017</date>
25704</refentryinfo>
25705<refmeta>
25706 <refentrytitle><phrase>mipi_dsi_packet_format_is_long</phrase></refentrytitle>
25707 <manvolnum>9</manvolnum>
25708 <refmiscinfo class="version">4.1.27</refmiscinfo>
25709</refmeta>
25710<refnamediv>
25711 <refname>mipi_dsi_packet_format_is_long</refname>
25712 <refpurpose>
25713     check if a packet is of the long format
25714 </refpurpose>
25715</refnamediv>
25716<refsynopsisdiv>
25717 <title>Synopsis</title>
25718  <funcsynopsis><funcprototype>
25719   <funcdef>bool <function>mipi_dsi_packet_format_is_long </function></funcdef>
25720   <paramdef>u8 <parameter>type</parameter></paramdef>
25721  </funcprototype></funcsynopsis>
25722</refsynopsisdiv>
25723<refsect1>
25724 <title>Arguments</title>
25725 <variablelist>
25726  <varlistentry>
25727   <term><parameter>type</parameter></term>
25728   <listitem>
25729    <para>
25730     MIPI DSI data type of the packet
25731    </para>
25732   </listitem>
25733  </varlistentry>
25734 </variablelist>
25735</refsect1>
25736<refsect1>
25737<title>Return</title>
25738<para>
25739   true if the packet for the given data type is a long packet, false
25740   otherwise.
25741</para>
25742</refsect1>
25743</refentry>
25744
25745<refentry id="API-mipi-dsi-create-packet">
25746<refentryinfo>
25747 <title>LINUX</title>
25748 <productname>Kernel Hackers Manual</productname>
25749 <date>July 2017</date>
25750</refentryinfo>
25751<refmeta>
25752 <refentrytitle><phrase>mipi_dsi_create_packet</phrase></refentrytitle>
25753 <manvolnum>9</manvolnum>
25754 <refmiscinfo class="version">4.1.27</refmiscinfo>
25755</refmeta>
25756<refnamediv>
25757 <refname>mipi_dsi_create_packet</refname>
25758 <refpurpose>
25759     create a packet from a message according to the DSI protocol
25760 </refpurpose>
25761</refnamediv>
25762<refsynopsisdiv>
25763 <title>Synopsis</title>
25764  <funcsynopsis><funcprototype>
25765   <funcdef>int <function>mipi_dsi_create_packet </function></funcdef>
25766   <paramdef>struct mipi_dsi_packet * <parameter>packet</parameter></paramdef>
25767   <paramdef>const struct mipi_dsi_msg * <parameter>msg</parameter></paramdef>
25768  </funcprototype></funcsynopsis>
25769</refsynopsisdiv>
25770<refsect1>
25771 <title>Arguments</title>
25772 <variablelist>
25773  <varlistentry>
25774   <term><parameter>packet</parameter></term>
25775   <listitem>
25776    <para>
25777     pointer to a DSI packet structure
25778    </para>
25779   </listitem>
25780  </varlistentry>
25781  <varlistentry>
25782   <term><parameter>msg</parameter></term>
25783   <listitem>
25784    <para>
25785     message to translate into a packet
25786    </para>
25787   </listitem>
25788  </varlistentry>
25789 </variablelist>
25790</refsect1>
25791<refsect1>
25792<title>Return</title>
25793<para>
25794   0 on success or a negative error code on failure.
25795</para>
25796</refsect1>
25797</refentry>
25798
25799<refentry id="API-mipi-dsi-generic-write">
25800<refentryinfo>
25801 <title>LINUX</title>
25802 <productname>Kernel Hackers Manual</productname>
25803 <date>July 2017</date>
25804</refentryinfo>
25805<refmeta>
25806 <refentrytitle><phrase>mipi_dsi_generic_write</phrase></refentrytitle>
25807 <manvolnum>9</manvolnum>
25808 <refmiscinfo class="version">4.1.27</refmiscinfo>
25809</refmeta>
25810<refnamediv>
25811 <refname>mipi_dsi_generic_write</refname>
25812 <refpurpose>
25813     transmit data using a generic write packet
25814 </refpurpose>
25815</refnamediv>
25816<refsynopsisdiv>
25817 <title>Synopsis</title>
25818  <funcsynopsis><funcprototype>
25819   <funcdef>ssize_t <function>mipi_dsi_generic_write </function></funcdef>
25820   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
25821   <paramdef>const void * <parameter>payload</parameter></paramdef>
25822   <paramdef>size_t <parameter>size</parameter></paramdef>
25823  </funcprototype></funcsynopsis>
25824</refsynopsisdiv>
25825<refsect1>
25826 <title>Arguments</title>
25827 <variablelist>
25828  <varlistentry>
25829   <term><parameter>dsi</parameter></term>
25830   <listitem>
25831    <para>
25832     DSI peripheral device
25833    </para>
25834   </listitem>
25835  </varlistentry>
25836  <varlistentry>
25837   <term><parameter>payload</parameter></term>
25838   <listitem>
25839    <para>
25840     buffer containing the payload
25841    </para>
25842   </listitem>
25843  </varlistentry>
25844  <varlistentry>
25845   <term><parameter>size</parameter></term>
25846   <listitem>
25847    <para>
25848     size of payload buffer
25849    </para>
25850   </listitem>
25851  </varlistentry>
25852 </variablelist>
25853</refsect1>
25854<refsect1>
25855<title>Description</title>
25856<para>
25857   This function will automatically choose the right data type depending on
25858   the payload length.
25859</para>
25860</refsect1>
25861<refsect1>
25862<title>Return</title>
25863<para>
25864   The number of bytes transmitted on success or a negative error code
25865   on failure.
25866</para>
25867</refsect1>
25868</refentry>
25869
25870<refentry id="API-mipi-dsi-generic-read">
25871<refentryinfo>
25872 <title>LINUX</title>
25873 <productname>Kernel Hackers Manual</productname>
25874 <date>July 2017</date>
25875</refentryinfo>
25876<refmeta>
25877 <refentrytitle><phrase>mipi_dsi_generic_read</phrase></refentrytitle>
25878 <manvolnum>9</manvolnum>
25879 <refmiscinfo class="version">4.1.27</refmiscinfo>
25880</refmeta>
25881<refnamediv>
25882 <refname>mipi_dsi_generic_read</refname>
25883 <refpurpose>
25884     receive data using a generic read packet
25885 </refpurpose>
25886</refnamediv>
25887<refsynopsisdiv>
25888 <title>Synopsis</title>
25889  <funcsynopsis><funcprototype>
25890   <funcdef>ssize_t <function>mipi_dsi_generic_read </function></funcdef>
25891   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
25892   <paramdef>const void * <parameter>params</parameter></paramdef>
25893   <paramdef>size_t <parameter>num_params</parameter></paramdef>
25894   <paramdef>void * <parameter>data</parameter></paramdef>
25895   <paramdef>size_t <parameter>size</parameter></paramdef>
25896  </funcprototype></funcsynopsis>
25897</refsynopsisdiv>
25898<refsect1>
25899 <title>Arguments</title>
25900 <variablelist>
25901  <varlistentry>
25902   <term><parameter>dsi</parameter></term>
25903   <listitem>
25904    <para>
25905     DSI peripheral device
25906    </para>
25907   </listitem>
25908  </varlistentry>
25909  <varlistentry>
25910   <term><parameter>params</parameter></term>
25911   <listitem>
25912    <para>
25913     buffer containing the request parameters
25914    </para>
25915   </listitem>
25916  </varlistentry>
25917  <varlistentry>
25918   <term><parameter>num_params</parameter></term>
25919   <listitem>
25920    <para>
25921     number of request parameters
25922    </para>
25923   </listitem>
25924  </varlistentry>
25925  <varlistentry>
25926   <term><parameter>data</parameter></term>
25927   <listitem>
25928    <para>
25929     buffer in which to return the received data
25930    </para>
25931   </listitem>
25932  </varlistentry>
25933  <varlistentry>
25934   <term><parameter>size</parameter></term>
25935   <listitem>
25936    <para>
25937     size of receive buffer
25938    </para>
25939   </listitem>
25940  </varlistentry>
25941 </variablelist>
25942</refsect1>
25943<refsect1>
25944<title>Description</title>
25945<para>
25946   This function will automatically choose the right data type depending on
25947   the number of parameters passed in.
25948</para>
25949</refsect1>
25950<refsect1>
25951<title>Return</title>
25952<para>
25953   The number of bytes successfully read or a negative error code on
25954   failure.
25955</para>
25956</refsect1>
25957</refentry>
25958
25959<refentry id="API-mipi-dsi-dcs-write-buffer">
25960<refentryinfo>
25961 <title>LINUX</title>
25962 <productname>Kernel Hackers Manual</productname>
25963 <date>July 2017</date>
25964</refentryinfo>
25965<refmeta>
25966 <refentrytitle><phrase>mipi_dsi_dcs_write_buffer</phrase></refentrytitle>
25967 <manvolnum>9</manvolnum>
25968 <refmiscinfo class="version">4.1.27</refmiscinfo>
25969</refmeta>
25970<refnamediv>
25971 <refname>mipi_dsi_dcs_write_buffer</refname>
25972 <refpurpose>
25973     transmit a DCS command with payload
25974 </refpurpose>
25975</refnamediv>
25976<refsynopsisdiv>
25977 <title>Synopsis</title>
25978  <funcsynopsis><funcprototype>
25979   <funcdef>ssize_t <function>mipi_dsi_dcs_write_buffer </function></funcdef>
25980   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
25981   <paramdef>const void * <parameter>data</parameter></paramdef>
25982   <paramdef>size_t <parameter>len</parameter></paramdef>
25983  </funcprototype></funcsynopsis>
25984</refsynopsisdiv>
25985<refsect1>
25986 <title>Arguments</title>
25987 <variablelist>
25988  <varlistentry>
25989   <term><parameter>dsi</parameter></term>
25990   <listitem>
25991    <para>
25992     DSI peripheral device
25993    </para>
25994   </listitem>
25995  </varlistentry>
25996  <varlistentry>
25997   <term><parameter>data</parameter></term>
25998   <listitem>
25999    <para>
26000     buffer containing data to be transmitted
26001    </para>
26002   </listitem>
26003  </varlistentry>
26004  <varlistentry>
26005   <term><parameter>len</parameter></term>
26006   <listitem>
26007    <para>
26008     size of transmission buffer
26009    </para>
26010   </listitem>
26011  </varlistentry>
26012 </variablelist>
26013</refsect1>
26014<refsect1>
26015<title>Description</title>
26016<para>
26017   This function will automatically choose the right data type depending on
26018   the command payload length.
26019</para>
26020</refsect1>
26021<refsect1>
26022<title>Return</title>
26023<para>
26024   The number of bytes successfully transmitted or a negative error
26025   code on failure.
26026</para>
26027</refsect1>
26028</refentry>
26029
26030<refentry id="API-mipi-dsi-dcs-write">
26031<refentryinfo>
26032 <title>LINUX</title>
26033 <productname>Kernel Hackers Manual</productname>
26034 <date>July 2017</date>
26035</refentryinfo>
26036<refmeta>
26037 <refentrytitle><phrase>mipi_dsi_dcs_write</phrase></refentrytitle>
26038 <manvolnum>9</manvolnum>
26039 <refmiscinfo class="version">4.1.27</refmiscinfo>
26040</refmeta>
26041<refnamediv>
26042 <refname>mipi_dsi_dcs_write</refname>
26043 <refpurpose>
26044     send DCS write command
26045 </refpurpose>
26046</refnamediv>
26047<refsynopsisdiv>
26048 <title>Synopsis</title>
26049  <funcsynopsis><funcprototype>
26050   <funcdef>ssize_t <function>mipi_dsi_dcs_write </function></funcdef>
26051   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26052   <paramdef>u8 <parameter>cmd</parameter></paramdef>
26053   <paramdef>const void * <parameter>data</parameter></paramdef>
26054   <paramdef>size_t <parameter>len</parameter></paramdef>
26055  </funcprototype></funcsynopsis>
26056</refsynopsisdiv>
26057<refsect1>
26058 <title>Arguments</title>
26059 <variablelist>
26060  <varlistentry>
26061   <term><parameter>dsi</parameter></term>
26062   <listitem>
26063    <para>
26064     DSI peripheral device
26065    </para>
26066   </listitem>
26067  </varlistentry>
26068  <varlistentry>
26069   <term><parameter>cmd</parameter></term>
26070   <listitem>
26071    <para>
26072     DCS command
26073    </para>
26074   </listitem>
26075  </varlistentry>
26076  <varlistentry>
26077   <term><parameter>data</parameter></term>
26078   <listitem>
26079    <para>
26080     buffer containing the command payload
26081    </para>
26082   </listitem>
26083  </varlistentry>
26084  <varlistentry>
26085   <term><parameter>len</parameter></term>
26086   <listitem>
26087    <para>
26088     command payload length
26089    </para>
26090   </listitem>
26091  </varlistentry>
26092 </variablelist>
26093</refsect1>
26094<refsect1>
26095<title>Description</title>
26096<para>
26097   This function will automatically choose the right data type depending on
26098   the command payload length.
26099</para>
26100</refsect1>
26101<refsect1>
26102<title>Return</title>
26103<para>
26104   The number of bytes successfully transmitted or a negative error
26105   code on failure.
26106</para>
26107</refsect1>
26108</refentry>
26109
26110<refentry id="API-mipi-dsi-dcs-read">
26111<refentryinfo>
26112 <title>LINUX</title>
26113 <productname>Kernel Hackers Manual</productname>
26114 <date>July 2017</date>
26115</refentryinfo>
26116<refmeta>
26117 <refentrytitle><phrase>mipi_dsi_dcs_read</phrase></refentrytitle>
26118 <manvolnum>9</manvolnum>
26119 <refmiscinfo class="version">4.1.27</refmiscinfo>
26120</refmeta>
26121<refnamediv>
26122 <refname>mipi_dsi_dcs_read</refname>
26123 <refpurpose>
26124     send DCS read request command
26125 </refpurpose>
26126</refnamediv>
26127<refsynopsisdiv>
26128 <title>Synopsis</title>
26129  <funcsynopsis><funcprototype>
26130   <funcdef>ssize_t <function>mipi_dsi_dcs_read </function></funcdef>
26131   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26132   <paramdef>u8 <parameter>cmd</parameter></paramdef>
26133   <paramdef>void * <parameter>data</parameter></paramdef>
26134   <paramdef>size_t <parameter>len</parameter></paramdef>
26135  </funcprototype></funcsynopsis>
26136</refsynopsisdiv>
26137<refsect1>
26138 <title>Arguments</title>
26139 <variablelist>
26140  <varlistentry>
26141   <term><parameter>dsi</parameter></term>
26142   <listitem>
26143    <para>
26144     DSI peripheral device
26145    </para>
26146   </listitem>
26147  </varlistentry>
26148  <varlistentry>
26149   <term><parameter>cmd</parameter></term>
26150   <listitem>
26151    <para>
26152     DCS command
26153    </para>
26154   </listitem>
26155  </varlistentry>
26156  <varlistentry>
26157   <term><parameter>data</parameter></term>
26158   <listitem>
26159    <para>
26160     buffer in which to receive data
26161    </para>
26162   </listitem>
26163  </varlistentry>
26164  <varlistentry>
26165   <term><parameter>len</parameter></term>
26166   <listitem>
26167    <para>
26168     size of receive buffer
26169    </para>
26170   </listitem>
26171  </varlistentry>
26172 </variablelist>
26173</refsect1>
26174<refsect1>
26175<title>Return</title>
26176<para>
26177   The number of bytes read or a negative error code on failure.
26178</para>
26179</refsect1>
26180</refentry>
26181
26182<refentry id="API-mipi-dsi-dcs-nop">
26183<refentryinfo>
26184 <title>LINUX</title>
26185 <productname>Kernel Hackers Manual</productname>
26186 <date>July 2017</date>
26187</refentryinfo>
26188<refmeta>
26189 <refentrytitle><phrase>mipi_dsi_dcs_nop</phrase></refentrytitle>
26190 <manvolnum>9</manvolnum>
26191 <refmiscinfo class="version">4.1.27</refmiscinfo>
26192</refmeta>
26193<refnamediv>
26194 <refname>mipi_dsi_dcs_nop</refname>
26195 <refpurpose>
26196     send DCS nop packet
26197 </refpurpose>
26198</refnamediv>
26199<refsynopsisdiv>
26200 <title>Synopsis</title>
26201  <funcsynopsis><funcprototype>
26202   <funcdef>int <function>mipi_dsi_dcs_nop </function></funcdef>
26203   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26204  </funcprototype></funcsynopsis>
26205</refsynopsisdiv>
26206<refsect1>
26207 <title>Arguments</title>
26208 <variablelist>
26209  <varlistentry>
26210   <term><parameter>dsi</parameter></term>
26211   <listitem>
26212    <para>
26213     DSI peripheral device
26214    </para>
26215   </listitem>
26216  </varlistentry>
26217 </variablelist>
26218</refsect1>
26219<refsect1>
26220<title>Return</title>
26221<para>
26222   0 on success or a negative error code on failure.
26223</para>
26224</refsect1>
26225</refentry>
26226
26227<refentry id="API-mipi-dsi-dcs-soft-reset">
26228<refentryinfo>
26229 <title>LINUX</title>
26230 <productname>Kernel Hackers Manual</productname>
26231 <date>July 2017</date>
26232</refentryinfo>
26233<refmeta>
26234 <refentrytitle><phrase>mipi_dsi_dcs_soft_reset</phrase></refentrytitle>
26235 <manvolnum>9</manvolnum>
26236 <refmiscinfo class="version">4.1.27</refmiscinfo>
26237</refmeta>
26238<refnamediv>
26239 <refname>mipi_dsi_dcs_soft_reset</refname>
26240 <refpurpose>
26241     perform a software reset of the display module
26242 </refpurpose>
26243</refnamediv>
26244<refsynopsisdiv>
26245 <title>Synopsis</title>
26246  <funcsynopsis><funcprototype>
26247   <funcdef>int <function>mipi_dsi_dcs_soft_reset </function></funcdef>
26248   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26249  </funcprototype></funcsynopsis>
26250</refsynopsisdiv>
26251<refsect1>
26252 <title>Arguments</title>
26253 <variablelist>
26254  <varlistentry>
26255   <term><parameter>dsi</parameter></term>
26256   <listitem>
26257    <para>
26258     DSI peripheral device
26259    </para>
26260   </listitem>
26261  </varlistentry>
26262 </variablelist>
26263</refsect1>
26264<refsect1>
26265<title>Return</title>
26266<para>
26267   0 on success or a negative error code on failure.
26268</para>
26269</refsect1>
26270</refentry>
26271
26272<refentry id="API-mipi-dsi-dcs-get-power-mode">
26273<refentryinfo>
26274 <title>LINUX</title>
26275 <productname>Kernel Hackers Manual</productname>
26276 <date>July 2017</date>
26277</refentryinfo>
26278<refmeta>
26279 <refentrytitle><phrase>mipi_dsi_dcs_get_power_mode</phrase></refentrytitle>
26280 <manvolnum>9</manvolnum>
26281 <refmiscinfo class="version">4.1.27</refmiscinfo>
26282</refmeta>
26283<refnamediv>
26284 <refname>mipi_dsi_dcs_get_power_mode</refname>
26285 <refpurpose>
26286     query the display module's current power mode
26287 </refpurpose>
26288</refnamediv>
26289<refsynopsisdiv>
26290 <title>Synopsis</title>
26291  <funcsynopsis><funcprototype>
26292   <funcdef>int <function>mipi_dsi_dcs_get_power_mode </function></funcdef>
26293   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26294   <paramdef>u8 * <parameter>mode</parameter></paramdef>
26295  </funcprototype></funcsynopsis>
26296</refsynopsisdiv>
26297<refsect1>
26298 <title>Arguments</title>
26299 <variablelist>
26300  <varlistentry>
26301   <term><parameter>dsi</parameter></term>
26302   <listitem>
26303    <para>
26304     DSI peripheral device
26305    </para>
26306   </listitem>
26307  </varlistentry>
26308  <varlistentry>
26309   <term><parameter>mode</parameter></term>
26310   <listitem>
26311    <para>
26312     return location for the current power mode
26313    </para>
26314   </listitem>
26315  </varlistentry>
26316 </variablelist>
26317</refsect1>
26318<refsect1>
26319<title>Return</title>
26320<para>
26321   0 on success or a negative error code on failure.
26322</para>
26323</refsect1>
26324</refentry>
26325
26326<refentry id="API-mipi-dsi-dcs-get-pixel-format">
26327<refentryinfo>
26328 <title>LINUX</title>
26329 <productname>Kernel Hackers Manual</productname>
26330 <date>July 2017</date>
26331</refentryinfo>
26332<refmeta>
26333 <refentrytitle><phrase>mipi_dsi_dcs_get_pixel_format</phrase></refentrytitle>
26334 <manvolnum>9</manvolnum>
26335 <refmiscinfo class="version">4.1.27</refmiscinfo>
26336</refmeta>
26337<refnamediv>
26338 <refname>mipi_dsi_dcs_get_pixel_format</refname>
26339 <refpurpose>
26340     gets the pixel format for the RGB image data used by the interface
26341 </refpurpose>
26342</refnamediv>
26343<refsynopsisdiv>
26344 <title>Synopsis</title>
26345  <funcsynopsis><funcprototype>
26346   <funcdef>int <function>mipi_dsi_dcs_get_pixel_format </function></funcdef>
26347   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26348   <paramdef>u8 * <parameter>format</parameter></paramdef>
26349  </funcprototype></funcsynopsis>
26350</refsynopsisdiv>
26351<refsect1>
26352 <title>Arguments</title>
26353 <variablelist>
26354  <varlistentry>
26355   <term><parameter>dsi</parameter></term>
26356   <listitem>
26357    <para>
26358     DSI peripheral device
26359    </para>
26360   </listitem>
26361  </varlistentry>
26362  <varlistentry>
26363   <term><parameter>format</parameter></term>
26364   <listitem>
26365    <para>
26366     return location for the pixel format
26367    </para>
26368   </listitem>
26369  </varlistentry>
26370 </variablelist>
26371</refsect1>
26372<refsect1>
26373<title>Return</title>
26374<para>
26375   0 on success or a negative error code on failure.
26376</para>
26377</refsect1>
26378</refentry>
26379
26380<refentry id="API-mipi-dsi-dcs-enter-sleep-mode">
26381<refentryinfo>
26382 <title>LINUX</title>
26383 <productname>Kernel Hackers Manual</productname>
26384 <date>July 2017</date>
26385</refentryinfo>
26386<refmeta>
26387 <refentrytitle><phrase>mipi_dsi_dcs_enter_sleep_mode</phrase></refentrytitle>
26388 <manvolnum>9</manvolnum>
26389 <refmiscinfo class="version">4.1.27</refmiscinfo>
26390</refmeta>
26391<refnamediv>
26392 <refname>mipi_dsi_dcs_enter_sleep_mode</refname>
26393 <refpurpose>
26394     disable all unnecessary blocks inside the display module except interface communication
26395 </refpurpose>
26396</refnamediv>
26397<refsynopsisdiv>
26398 <title>Synopsis</title>
26399  <funcsynopsis><funcprototype>
26400   <funcdef>int <function>mipi_dsi_dcs_enter_sleep_mode </function></funcdef>
26401   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26402  </funcprototype></funcsynopsis>
26403</refsynopsisdiv>
26404<refsect1>
26405 <title>Arguments</title>
26406 <variablelist>
26407  <varlistentry>
26408   <term><parameter>dsi</parameter></term>
26409   <listitem>
26410    <para>
26411     DSI peripheral device
26412    </para>
26413   </listitem>
26414  </varlistentry>
26415 </variablelist>
26416</refsect1>
26417<refsect1>
26418<title>Return</title>
26419<para>
26420   0 on success or a negative error code on failure.
26421</para>
26422</refsect1>
26423</refentry>
26424
26425<refentry id="API-mipi-dsi-dcs-exit-sleep-mode">
26426<refentryinfo>
26427 <title>LINUX</title>
26428 <productname>Kernel Hackers Manual</productname>
26429 <date>July 2017</date>
26430</refentryinfo>
26431<refmeta>
26432 <refentrytitle><phrase>mipi_dsi_dcs_exit_sleep_mode</phrase></refentrytitle>
26433 <manvolnum>9</manvolnum>
26434 <refmiscinfo class="version">4.1.27</refmiscinfo>
26435</refmeta>
26436<refnamediv>
26437 <refname>mipi_dsi_dcs_exit_sleep_mode</refname>
26438 <refpurpose>
26439     enable all blocks inside the display module
26440 </refpurpose>
26441</refnamediv>
26442<refsynopsisdiv>
26443 <title>Synopsis</title>
26444  <funcsynopsis><funcprototype>
26445   <funcdef>int <function>mipi_dsi_dcs_exit_sleep_mode </function></funcdef>
26446   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26447  </funcprototype></funcsynopsis>
26448</refsynopsisdiv>
26449<refsect1>
26450 <title>Arguments</title>
26451 <variablelist>
26452  <varlistentry>
26453   <term><parameter>dsi</parameter></term>
26454   <listitem>
26455    <para>
26456     DSI peripheral device
26457    </para>
26458   </listitem>
26459  </varlistentry>
26460 </variablelist>
26461</refsect1>
26462<refsect1>
26463<title>Return</title>
26464<para>
26465   0 on success or a negative error code on failure.
26466</para>
26467</refsect1>
26468</refentry>
26469
26470<refentry id="API-mipi-dsi-dcs-set-display-off">
26471<refentryinfo>
26472 <title>LINUX</title>
26473 <productname>Kernel Hackers Manual</productname>
26474 <date>July 2017</date>
26475</refentryinfo>
26476<refmeta>
26477 <refentrytitle><phrase>mipi_dsi_dcs_set_display_off</phrase></refentrytitle>
26478 <manvolnum>9</manvolnum>
26479 <refmiscinfo class="version">4.1.27</refmiscinfo>
26480</refmeta>
26481<refnamediv>
26482 <refname>mipi_dsi_dcs_set_display_off</refname>
26483 <refpurpose>
26484     stop displaying the image data on the display device
26485 </refpurpose>
26486</refnamediv>
26487<refsynopsisdiv>
26488 <title>Synopsis</title>
26489  <funcsynopsis><funcprototype>
26490   <funcdef>int <function>mipi_dsi_dcs_set_display_off </function></funcdef>
26491   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26492  </funcprototype></funcsynopsis>
26493</refsynopsisdiv>
26494<refsect1>
26495 <title>Arguments</title>
26496 <variablelist>
26497  <varlistentry>
26498   <term><parameter>dsi</parameter></term>
26499   <listitem>
26500    <para>
26501     DSI peripheral device
26502    </para>
26503   </listitem>
26504  </varlistentry>
26505 </variablelist>
26506</refsect1>
26507<refsect1>
26508<title>Return</title>
26509<para>
26510   0 on success or a negative error code on failure.
26511</para>
26512</refsect1>
26513</refentry>
26514
26515<refentry id="API-mipi-dsi-dcs-set-display-on">
26516<refentryinfo>
26517 <title>LINUX</title>
26518 <productname>Kernel Hackers Manual</productname>
26519 <date>July 2017</date>
26520</refentryinfo>
26521<refmeta>
26522 <refentrytitle><phrase>mipi_dsi_dcs_set_display_on</phrase></refentrytitle>
26523 <manvolnum>9</manvolnum>
26524 <refmiscinfo class="version">4.1.27</refmiscinfo>
26525</refmeta>
26526<refnamediv>
26527 <refname>mipi_dsi_dcs_set_display_on</refname>
26528 <refpurpose>
26529     start displaying the image data on the display device
26530 </refpurpose>
26531</refnamediv>
26532<refsynopsisdiv>
26533 <title>Synopsis</title>
26534  <funcsynopsis><funcprototype>
26535   <funcdef>int <function>mipi_dsi_dcs_set_display_on </function></funcdef>
26536   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26537  </funcprototype></funcsynopsis>
26538</refsynopsisdiv>
26539<refsect1>
26540 <title>Arguments</title>
26541 <variablelist>
26542  <varlistentry>
26543   <term><parameter>dsi</parameter></term>
26544   <listitem>
26545    <para>
26546     DSI peripheral device
26547    </para>
26548   </listitem>
26549  </varlistentry>
26550 </variablelist>
26551</refsect1>
26552<refsect1>
26553<title>Return</title>
26554<para>
26555   0 on success or a negative error code on failure
26556</para>
26557</refsect1>
26558</refentry>
26559
26560<refentry id="API-mipi-dsi-dcs-set-column-address">
26561<refentryinfo>
26562 <title>LINUX</title>
26563 <productname>Kernel Hackers Manual</productname>
26564 <date>July 2017</date>
26565</refentryinfo>
26566<refmeta>
26567 <refentrytitle><phrase>mipi_dsi_dcs_set_column_address</phrase></refentrytitle>
26568 <manvolnum>9</manvolnum>
26569 <refmiscinfo class="version">4.1.27</refmiscinfo>
26570</refmeta>
26571<refnamediv>
26572 <refname>mipi_dsi_dcs_set_column_address</refname>
26573 <refpurpose>
26574     define the column extent of the frame memory accessed by the host processor
26575 </refpurpose>
26576</refnamediv>
26577<refsynopsisdiv>
26578 <title>Synopsis</title>
26579  <funcsynopsis><funcprototype>
26580   <funcdef>int <function>mipi_dsi_dcs_set_column_address </function></funcdef>
26581   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26582   <paramdef>u16 <parameter>start</parameter></paramdef>
26583   <paramdef>u16 <parameter>end</parameter></paramdef>
26584  </funcprototype></funcsynopsis>
26585</refsynopsisdiv>
26586<refsect1>
26587 <title>Arguments</title>
26588 <variablelist>
26589  <varlistentry>
26590   <term><parameter>dsi</parameter></term>
26591   <listitem>
26592    <para>
26593     DSI peripheral device
26594    </para>
26595   </listitem>
26596  </varlistentry>
26597  <varlistentry>
26598   <term><parameter>start</parameter></term>
26599   <listitem>
26600    <para>
26601     first column of frame memory
26602    </para>
26603   </listitem>
26604  </varlistentry>
26605  <varlistentry>
26606   <term><parameter>end</parameter></term>
26607   <listitem>
26608    <para>
26609     last column of frame memory
26610    </para>
26611   </listitem>
26612  </varlistentry>
26613 </variablelist>
26614</refsect1>
26615<refsect1>
26616<title>Return</title>
26617<para>
26618   0 on success or a negative error code on failure.
26619</para>
26620</refsect1>
26621</refentry>
26622
26623<refentry id="API-mipi-dsi-dcs-set-page-address">
26624<refentryinfo>
26625 <title>LINUX</title>
26626 <productname>Kernel Hackers Manual</productname>
26627 <date>July 2017</date>
26628</refentryinfo>
26629<refmeta>
26630 <refentrytitle><phrase>mipi_dsi_dcs_set_page_address</phrase></refentrytitle>
26631 <manvolnum>9</manvolnum>
26632 <refmiscinfo class="version">4.1.27</refmiscinfo>
26633</refmeta>
26634<refnamediv>
26635 <refname>mipi_dsi_dcs_set_page_address</refname>
26636 <refpurpose>
26637     define the page extent of the frame memory accessed by the host processor
26638 </refpurpose>
26639</refnamediv>
26640<refsynopsisdiv>
26641 <title>Synopsis</title>
26642  <funcsynopsis><funcprototype>
26643   <funcdef>int <function>mipi_dsi_dcs_set_page_address </function></funcdef>
26644   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26645   <paramdef>u16 <parameter>start</parameter></paramdef>
26646   <paramdef>u16 <parameter>end</parameter></paramdef>
26647  </funcprototype></funcsynopsis>
26648</refsynopsisdiv>
26649<refsect1>
26650 <title>Arguments</title>
26651 <variablelist>
26652  <varlistentry>
26653   <term><parameter>dsi</parameter></term>
26654   <listitem>
26655    <para>
26656     DSI peripheral device
26657    </para>
26658   </listitem>
26659  </varlistentry>
26660  <varlistentry>
26661   <term><parameter>start</parameter></term>
26662   <listitem>
26663    <para>
26664     first page of frame memory
26665    </para>
26666   </listitem>
26667  </varlistentry>
26668  <varlistentry>
26669   <term><parameter>end</parameter></term>
26670   <listitem>
26671    <para>
26672     last page of frame memory
26673    </para>
26674   </listitem>
26675  </varlistentry>
26676 </variablelist>
26677</refsect1>
26678<refsect1>
26679<title>Return</title>
26680<para>
26681   0 on success or a negative error code on failure.
26682</para>
26683</refsect1>
26684</refentry>
26685
26686<refentry id="API-mipi-dsi-dcs-set-tear-off">
26687<refentryinfo>
26688 <title>LINUX</title>
26689 <productname>Kernel Hackers Manual</productname>
26690 <date>July 2017</date>
26691</refentryinfo>
26692<refmeta>
26693 <refentrytitle><phrase>mipi_dsi_dcs_set_tear_off</phrase></refentrytitle>
26694 <manvolnum>9</manvolnum>
26695 <refmiscinfo class="version">4.1.27</refmiscinfo>
26696</refmeta>
26697<refnamediv>
26698 <refname>mipi_dsi_dcs_set_tear_off</refname>
26699 <refpurpose>
26700     turn off the display module's Tearing Effect output signal on the TE signal line
26701 </refpurpose>
26702</refnamediv>
26703<refsynopsisdiv>
26704 <title>Synopsis</title>
26705  <funcsynopsis><funcprototype>
26706   <funcdef>int <function>mipi_dsi_dcs_set_tear_off </function></funcdef>
26707   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26708  </funcprototype></funcsynopsis>
26709</refsynopsisdiv>
26710<refsect1>
26711 <title>Arguments</title>
26712 <variablelist>
26713  <varlistentry>
26714   <term><parameter>dsi</parameter></term>
26715   <listitem>
26716    <para>
26717     DSI peripheral device
26718    </para>
26719   </listitem>
26720  </varlistentry>
26721 </variablelist>
26722</refsect1>
26723<refsect1>
26724<title>Return</title>
26725<para>
26726   0 on success or a negative error code on failure
26727</para>
26728</refsect1>
26729</refentry>
26730
26731<refentry id="API-mipi-dsi-dcs-set-tear-on">
26732<refentryinfo>
26733 <title>LINUX</title>
26734 <productname>Kernel Hackers Manual</productname>
26735 <date>July 2017</date>
26736</refentryinfo>
26737<refmeta>
26738 <refentrytitle><phrase>mipi_dsi_dcs_set_tear_on</phrase></refentrytitle>
26739 <manvolnum>9</manvolnum>
26740 <refmiscinfo class="version">4.1.27</refmiscinfo>
26741</refmeta>
26742<refnamediv>
26743 <refname>mipi_dsi_dcs_set_tear_on</refname>
26744 <refpurpose>
26745     turn on the display module's Tearing Effect output signal on the TE signal line.
26746 </refpurpose>
26747</refnamediv>
26748<refsynopsisdiv>
26749 <title>Synopsis</title>
26750  <funcsynopsis><funcprototype>
26751   <funcdef>int <function>mipi_dsi_dcs_set_tear_on </function></funcdef>
26752   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26753   <paramdef>enum mipi_dsi_dcs_tear_mode <parameter>mode</parameter></paramdef>
26754  </funcprototype></funcsynopsis>
26755</refsynopsisdiv>
26756<refsect1>
26757 <title>Arguments</title>
26758 <variablelist>
26759  <varlistentry>
26760   <term><parameter>dsi</parameter></term>
26761   <listitem>
26762    <para>
26763     DSI peripheral device
26764    </para>
26765   </listitem>
26766  </varlistentry>
26767  <varlistentry>
26768   <term><parameter>mode</parameter></term>
26769   <listitem>
26770    <para>
26771     the Tearing Effect Output Line mode
26772    </para>
26773   </listitem>
26774  </varlistentry>
26775 </variablelist>
26776</refsect1>
26777<refsect1>
26778<title>Return</title>
26779<para>
26780   0 on success or a negative error code on failure
26781</para>
26782</refsect1>
26783</refentry>
26784
26785<refentry id="API-mipi-dsi-dcs-set-pixel-format">
26786<refentryinfo>
26787 <title>LINUX</title>
26788 <productname>Kernel Hackers Manual</productname>
26789 <date>July 2017</date>
26790</refentryinfo>
26791<refmeta>
26792 <refentrytitle><phrase>mipi_dsi_dcs_set_pixel_format</phrase></refentrytitle>
26793 <manvolnum>9</manvolnum>
26794 <refmiscinfo class="version">4.1.27</refmiscinfo>
26795</refmeta>
26796<refnamediv>
26797 <refname>mipi_dsi_dcs_set_pixel_format</refname>
26798 <refpurpose>
26799     sets the pixel format for the RGB image data used by the interface
26800 </refpurpose>
26801</refnamediv>
26802<refsynopsisdiv>
26803 <title>Synopsis</title>
26804  <funcsynopsis><funcprototype>
26805   <funcdef>int <function>mipi_dsi_dcs_set_pixel_format </function></funcdef>
26806   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
26807   <paramdef>u8 <parameter>format</parameter></paramdef>
26808  </funcprototype></funcsynopsis>
26809</refsynopsisdiv>
26810<refsect1>
26811 <title>Arguments</title>
26812 <variablelist>
26813  <varlistentry>
26814   <term><parameter>dsi</parameter></term>
26815   <listitem>
26816    <para>
26817     DSI peripheral device
26818    </para>
26819   </listitem>
26820  </varlistentry>
26821  <varlistentry>
26822   <term><parameter>format</parameter></term>
26823   <listitem>
26824    <para>
26825     pixel format
26826    </para>
26827   </listitem>
26828  </varlistentry>
26829 </variablelist>
26830</refsect1>
26831<refsect1>
26832<title>Return</title>
26833<para>
26834   0 on success or a negative error code on failure.
26835</para>
26836</refsect1>
26837</refentry>
26838
26839<refentry id="API-mipi-dsi-driver-register-full">
26840<refentryinfo>
26841 <title>LINUX</title>
26842 <productname>Kernel Hackers Manual</productname>
26843 <date>July 2017</date>
26844</refentryinfo>
26845<refmeta>
26846 <refentrytitle><phrase>mipi_dsi_driver_register_full</phrase></refentrytitle>
26847 <manvolnum>9</manvolnum>
26848 <refmiscinfo class="version">4.1.27</refmiscinfo>
26849</refmeta>
26850<refnamediv>
26851 <refname>mipi_dsi_driver_register_full</refname>
26852 <refpurpose>
26853     register a driver for DSI devices
26854 </refpurpose>
26855</refnamediv>
26856<refsynopsisdiv>
26857 <title>Synopsis</title>
26858  <funcsynopsis><funcprototype>
26859   <funcdef>int <function>mipi_dsi_driver_register_full </function></funcdef>
26860   <paramdef>struct mipi_dsi_driver * <parameter>drv</parameter></paramdef>
26861   <paramdef>struct module * <parameter>owner</parameter></paramdef>
26862  </funcprototype></funcsynopsis>
26863</refsynopsisdiv>
26864<refsect1>
26865 <title>Arguments</title>
26866 <variablelist>
26867  <varlistentry>
26868   <term><parameter>drv</parameter></term>
26869   <listitem>
26870    <para>
26871     DSI driver structure
26872    </para>
26873   </listitem>
26874  </varlistentry>
26875  <varlistentry>
26876   <term><parameter>owner</parameter></term>
26877   <listitem>
26878    <para>
26879     owner module
26880    </para>
26881   </listitem>
26882  </varlistentry>
26883 </variablelist>
26884</refsect1>
26885<refsect1>
26886<title>Return</title>
26887<para>
26888   0 on success or a negative error code on failure.
26889</para>
26890</refsect1>
26891</refentry>
26892
26893<refentry id="API-mipi-dsi-driver-unregister">
26894<refentryinfo>
26895 <title>LINUX</title>
26896 <productname>Kernel Hackers Manual</productname>
26897 <date>July 2017</date>
26898</refentryinfo>
26899<refmeta>
26900 <refentrytitle><phrase>mipi_dsi_driver_unregister</phrase></refentrytitle>
26901 <manvolnum>9</manvolnum>
26902 <refmiscinfo class="version">4.1.27</refmiscinfo>
26903</refmeta>
26904<refnamediv>
26905 <refname>mipi_dsi_driver_unregister</refname>
26906 <refpurpose>
26907     unregister a driver for DSI devices
26908 </refpurpose>
26909</refnamediv>
26910<refsynopsisdiv>
26911 <title>Synopsis</title>
26912  <funcsynopsis><funcprototype>
26913   <funcdef>void <function>mipi_dsi_driver_unregister </function></funcdef>
26914   <paramdef>struct mipi_dsi_driver * <parameter>drv</parameter></paramdef>
26915  </funcprototype></funcsynopsis>
26916</refsynopsisdiv>
26917<refsect1>
26918 <title>Arguments</title>
26919 <variablelist>
26920  <varlistentry>
26921   <term><parameter>drv</parameter></term>
26922   <listitem>
26923    <para>
26924     DSI driver structure
26925    </para>
26926   </listitem>
26927  </varlistentry>
26928 </variablelist>
26929</refsect1>
26930<refsect1>
26931<title>Return</title>
26932<para>
26933   0 on success or a negative error code on failure.
26934</para>
26935</refsect1>
26936</refentry>
26937
26938    </sect2>
26939    <sect2>
26940      <title>EDID Helper Functions Reference</title>
26941<!-- drivers/gpu/drm/drm_edid.c -->
26942<refentry id="API-drm-edid-header-is-valid">
26943<refentryinfo>
26944 <title>LINUX</title>
26945 <productname>Kernel Hackers Manual</productname>
26946 <date>July 2017</date>
26947</refentryinfo>
26948<refmeta>
26949 <refentrytitle><phrase>drm_edid_header_is_valid</phrase></refentrytitle>
26950 <manvolnum>9</manvolnum>
26951 <refmiscinfo class="version">4.1.27</refmiscinfo>
26952</refmeta>
26953<refnamediv>
26954 <refname>drm_edid_header_is_valid</refname>
26955 <refpurpose>
26956  sanity check the header of the base EDID block
26957 </refpurpose>
26958</refnamediv>
26959<refsynopsisdiv>
26960 <title>Synopsis</title>
26961  <funcsynopsis><funcprototype>
26962   <funcdef>int <function>drm_edid_header_is_valid </function></funcdef>
26963   <paramdef>const u8 * <parameter>raw_edid</parameter></paramdef>
26964  </funcprototype></funcsynopsis>
26965</refsynopsisdiv>
26966<refsect1>
26967 <title>Arguments</title>
26968 <variablelist>
26969  <varlistentry>
26970   <term><parameter>raw_edid</parameter></term>
26971   <listitem>
26972    <para>
26973     pointer to raw base EDID block
26974    </para>
26975   </listitem>
26976  </varlistentry>
26977 </variablelist>
26978</refsect1>
26979<refsect1>
26980<title>Description</title>
26981<para>
26982   Sanity check the header of the base EDID block.
26983</para>
26984</refsect1>
26985<refsect1>
26986<title>Return</title>
26987<para>
26988   8 if the header is perfect, down to 0 if it's totally wrong.
26989</para>
26990</refsect1>
26991</refentry>
26992
26993<refentry id="API-drm-edid-block-valid">
26994<refentryinfo>
26995 <title>LINUX</title>
26996 <productname>Kernel Hackers Manual</productname>
26997 <date>July 2017</date>
26998</refentryinfo>
26999<refmeta>
27000 <refentrytitle><phrase>drm_edid_block_valid</phrase></refentrytitle>
27001 <manvolnum>9</manvolnum>
27002 <refmiscinfo class="version">4.1.27</refmiscinfo>
27003</refmeta>
27004<refnamediv>
27005 <refname>drm_edid_block_valid</refname>
27006 <refpurpose>
27007     Sanity check the EDID block (base or extension)
27008 </refpurpose>
27009</refnamediv>
27010<refsynopsisdiv>
27011 <title>Synopsis</title>
27012  <funcsynopsis><funcprototype>
27013   <funcdef>bool <function>drm_edid_block_valid </function></funcdef>
27014   <paramdef>u8 * <parameter>raw_edid</parameter></paramdef>
27015   <paramdef>int <parameter>block</parameter></paramdef>
27016   <paramdef>bool <parameter>print_bad_edid</parameter></paramdef>
27017  </funcprototype></funcsynopsis>
27018</refsynopsisdiv>
27019<refsect1>
27020 <title>Arguments</title>
27021 <variablelist>
27022  <varlistentry>
27023   <term><parameter>raw_edid</parameter></term>
27024   <listitem>
27025    <para>
27026     pointer to raw EDID block
27027    </para>
27028   </listitem>
27029  </varlistentry>
27030  <varlistentry>
27031   <term><parameter>block</parameter></term>
27032   <listitem>
27033    <para>
27034     type of block to validate (0 for base, extension otherwise)
27035    </para>
27036   </listitem>
27037  </varlistentry>
27038  <varlistentry>
27039   <term><parameter>print_bad_edid</parameter></term>
27040   <listitem>
27041    <para>
27042     if true, dump bad EDID blocks to the console
27043    </para>
27044   </listitem>
27045  </varlistentry>
27046 </variablelist>
27047</refsect1>
27048<refsect1>
27049<title>Description</title>
27050<para>
27051   Validate a base or extension EDID block and optionally dump bad blocks to
27052   the console.
27053</para>
27054</refsect1>
27055<refsect1>
27056<title>Return</title>
27057<para>
27058   True if the block is valid, false otherwise.
27059</para>
27060</refsect1>
27061</refentry>
27062
27063<refentry id="API-drm-edid-is-valid">
27064<refentryinfo>
27065 <title>LINUX</title>
27066 <productname>Kernel Hackers Manual</productname>
27067 <date>July 2017</date>
27068</refentryinfo>
27069<refmeta>
27070 <refentrytitle><phrase>drm_edid_is_valid</phrase></refentrytitle>
27071 <manvolnum>9</manvolnum>
27072 <refmiscinfo class="version">4.1.27</refmiscinfo>
27073</refmeta>
27074<refnamediv>
27075 <refname>drm_edid_is_valid</refname>
27076 <refpurpose>
27077     sanity check EDID data
27078 </refpurpose>
27079</refnamediv>
27080<refsynopsisdiv>
27081 <title>Synopsis</title>
27082  <funcsynopsis><funcprototype>
27083   <funcdef>bool <function>drm_edid_is_valid </function></funcdef>
27084   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27085  </funcprototype></funcsynopsis>
27086</refsynopsisdiv>
27087<refsect1>
27088 <title>Arguments</title>
27089 <variablelist>
27090  <varlistentry>
27091   <term><parameter>edid</parameter></term>
27092   <listitem>
27093    <para>
27094     EDID data
27095    </para>
27096   </listitem>
27097  </varlistentry>
27098 </variablelist>
27099</refsect1>
27100<refsect1>
27101<title>Description</title>
27102<para>
27103   Sanity-check an entire EDID record (including extensions)
27104</para>
27105</refsect1>
27106<refsect1>
27107<title>Return</title>
27108<para>
27109   True if the EDID data is valid, false otherwise.
27110</para>
27111</refsect1>
27112</refentry>
27113
27114<refentry id="API-drm-do-get-edid">
27115<refentryinfo>
27116 <title>LINUX</title>
27117 <productname>Kernel Hackers Manual</productname>
27118 <date>July 2017</date>
27119</refentryinfo>
27120<refmeta>
27121 <refentrytitle><phrase>drm_do_get_edid</phrase></refentrytitle>
27122 <manvolnum>9</manvolnum>
27123 <refmiscinfo class="version">4.1.27</refmiscinfo>
27124</refmeta>
27125<refnamediv>
27126 <refname>drm_do_get_edid</refname>
27127 <refpurpose>
27128     get EDID data using a custom EDID block read function
27129 </refpurpose>
27130</refnamediv>
27131<refsynopsisdiv>
27132 <title>Synopsis</title>
27133  <funcsynopsis><funcprototype>
27134   <funcdef>struct edid * <function>drm_do_get_edid </function></funcdef>
27135   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
27136   <paramdef>int (*<parameter>get_edid_block</parameter>)
27137     <funcparams>void *data, u8 *buf, unsigned int block, 			      size_t len</funcparams></paramdef>
27138   <paramdef>void * <parameter>data</parameter></paramdef>
27139  </funcprototype></funcsynopsis>
27140</refsynopsisdiv>
27141<refsect1>
27142 <title>Arguments</title>
27143 <variablelist>
27144  <varlistentry>
27145   <term><parameter>connector</parameter></term>
27146   <listitem>
27147    <para>
27148     connector we're probing
27149    </para>
27150   </listitem>
27151  </varlistentry>
27152  <varlistentry>
27153   <term><parameter>get_edid_block</parameter></term>
27154   <listitem>
27155    <para>
27156     EDID block read function
27157    </para>
27158   </listitem>
27159  </varlistentry>
27160  <varlistentry>
27161   <term><parameter>data</parameter></term>
27162   <listitem>
27163    <para>
27164     private data passed to the block read function
27165    </para>
27166   </listitem>
27167  </varlistentry>
27168 </variablelist>
27169</refsect1>
27170<refsect1>
27171<title>Description</title>
27172<para>
27173   When the I2C adapter connected to the DDC bus is hidden behind a device that
27174   exposes a different interface to read EDID blocks this function can be used
27175   to get EDID data using a custom block read function.
27176   </para><para>
27177
27178   As in the general case the DDC bus is accessible by the kernel at the I2C
27179   level, drivers must make all reasonable efforts to expose it as an I2C
27180   adapter and use <function>drm_get_edid</function> instead of abusing this function.
27181</para>
27182</refsect1>
27183<refsect1>
27184<title>Return</title>
27185<para>
27186   Pointer to valid EDID or NULL if we couldn't find any.
27187</para>
27188</refsect1>
27189</refentry>
27190
27191<refentry id="API-drm-probe-ddc">
27192<refentryinfo>
27193 <title>LINUX</title>
27194 <productname>Kernel Hackers Manual</productname>
27195 <date>July 2017</date>
27196</refentryinfo>
27197<refmeta>
27198 <refentrytitle><phrase>drm_probe_ddc</phrase></refentrytitle>
27199 <manvolnum>9</manvolnum>
27200 <refmiscinfo class="version">4.1.27</refmiscinfo>
27201</refmeta>
27202<refnamediv>
27203 <refname>drm_probe_ddc</refname>
27204 <refpurpose>
27205     probe DDC presence
27206 </refpurpose>
27207</refnamediv>
27208<refsynopsisdiv>
27209 <title>Synopsis</title>
27210  <funcsynopsis><funcprototype>
27211   <funcdef>bool <function>drm_probe_ddc </function></funcdef>
27212   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
27213  </funcprototype></funcsynopsis>
27214</refsynopsisdiv>
27215<refsect1>
27216 <title>Arguments</title>
27217 <variablelist>
27218  <varlistentry>
27219   <term><parameter>adapter</parameter></term>
27220   <listitem>
27221    <para>
27222     I2C adapter to probe
27223    </para>
27224   </listitem>
27225  </varlistentry>
27226 </variablelist>
27227</refsect1>
27228<refsect1>
27229<title>Return</title>
27230<para>
27231   True on success, false on failure.
27232</para>
27233</refsect1>
27234</refentry>
27235
27236<refentry id="API-drm-get-edid">
27237<refentryinfo>
27238 <title>LINUX</title>
27239 <productname>Kernel Hackers Manual</productname>
27240 <date>July 2017</date>
27241</refentryinfo>
27242<refmeta>
27243 <refentrytitle><phrase>drm_get_edid</phrase></refentrytitle>
27244 <manvolnum>9</manvolnum>
27245 <refmiscinfo class="version">4.1.27</refmiscinfo>
27246</refmeta>
27247<refnamediv>
27248 <refname>drm_get_edid</refname>
27249 <refpurpose>
27250     get EDID data, if available
27251 </refpurpose>
27252</refnamediv>
27253<refsynopsisdiv>
27254 <title>Synopsis</title>
27255  <funcsynopsis><funcprototype>
27256   <funcdef>struct edid * <function>drm_get_edid </function></funcdef>
27257   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
27258   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
27259  </funcprototype></funcsynopsis>
27260</refsynopsisdiv>
27261<refsect1>
27262 <title>Arguments</title>
27263 <variablelist>
27264  <varlistentry>
27265   <term><parameter>connector</parameter></term>
27266   <listitem>
27267    <para>
27268     connector we're probing
27269    </para>
27270   </listitem>
27271  </varlistentry>
27272  <varlistentry>
27273   <term><parameter>adapter</parameter></term>
27274   <listitem>
27275    <para>
27276     I2C adapter to use for DDC
27277    </para>
27278   </listitem>
27279  </varlistentry>
27280 </variablelist>
27281</refsect1>
27282<refsect1>
27283<title>Description</title>
27284<para>
27285   Poke the given I2C channel to grab EDID data if possible.  If found,
27286   attach it to the connector.
27287</para>
27288</refsect1>
27289<refsect1>
27290<title>Return</title>
27291<para>
27292   Pointer to valid EDID or NULL if we couldn't find any.
27293</para>
27294</refsect1>
27295</refentry>
27296
27297<refentry id="API-drm-edid-duplicate">
27298<refentryinfo>
27299 <title>LINUX</title>
27300 <productname>Kernel Hackers Manual</productname>
27301 <date>July 2017</date>
27302</refentryinfo>
27303<refmeta>
27304 <refentrytitle><phrase>drm_edid_duplicate</phrase></refentrytitle>
27305 <manvolnum>9</manvolnum>
27306 <refmiscinfo class="version">4.1.27</refmiscinfo>
27307</refmeta>
27308<refnamediv>
27309 <refname>drm_edid_duplicate</refname>
27310 <refpurpose>
27311     duplicate an EDID and the extensions
27312 </refpurpose>
27313</refnamediv>
27314<refsynopsisdiv>
27315 <title>Synopsis</title>
27316  <funcsynopsis><funcprototype>
27317   <funcdef>struct edid * <function>drm_edid_duplicate </function></funcdef>
27318   <paramdef>const struct edid * <parameter>edid</parameter></paramdef>
27319  </funcprototype></funcsynopsis>
27320</refsynopsisdiv>
27321<refsect1>
27322 <title>Arguments</title>
27323 <variablelist>
27324  <varlistentry>
27325   <term><parameter>edid</parameter></term>
27326   <listitem>
27327    <para>
27328     EDID to duplicate
27329    </para>
27330   </listitem>
27331  </varlistentry>
27332 </variablelist>
27333</refsect1>
27334<refsect1>
27335<title>Return</title>
27336<para>
27337   Pointer to duplicated EDID or NULL on allocation failure.
27338</para>
27339</refsect1>
27340</refentry>
27341
27342<refentry id="API-drm-match-cea-mode">
27343<refentryinfo>
27344 <title>LINUX</title>
27345 <productname>Kernel Hackers Manual</productname>
27346 <date>July 2017</date>
27347</refentryinfo>
27348<refmeta>
27349 <refentrytitle><phrase>drm_match_cea_mode</phrase></refentrytitle>
27350 <manvolnum>9</manvolnum>
27351 <refmiscinfo class="version">4.1.27</refmiscinfo>
27352</refmeta>
27353<refnamediv>
27354 <refname>drm_match_cea_mode</refname>
27355 <refpurpose>
27356     look for a CEA mode matching given mode
27357 </refpurpose>
27358</refnamediv>
27359<refsynopsisdiv>
27360 <title>Synopsis</title>
27361  <funcsynopsis><funcprototype>
27362   <funcdef>u8 <function>drm_match_cea_mode </function></funcdef>
27363   <paramdef>const struct drm_display_mode * <parameter>to_match</parameter></paramdef>
27364  </funcprototype></funcsynopsis>
27365</refsynopsisdiv>
27366<refsect1>
27367 <title>Arguments</title>
27368 <variablelist>
27369  <varlistentry>
27370   <term><parameter>to_match</parameter></term>
27371   <listitem>
27372    <para>
27373     display mode
27374    </para>
27375   </listitem>
27376  </varlistentry>
27377 </variablelist>
27378</refsect1>
27379<refsect1>
27380<title>Return</title>
27381<para>
27382   The CEA Video ID (VIC) of the mode or 0 if it isn't a CEA-861
27383   mode.
27384</para>
27385</refsect1>
27386</refentry>
27387
27388<refentry id="API-drm-get-cea-aspect-ratio">
27389<refentryinfo>
27390 <title>LINUX</title>
27391 <productname>Kernel Hackers Manual</productname>
27392 <date>July 2017</date>
27393</refentryinfo>
27394<refmeta>
27395 <refentrytitle><phrase>drm_get_cea_aspect_ratio</phrase></refentrytitle>
27396 <manvolnum>9</manvolnum>
27397 <refmiscinfo class="version">4.1.27</refmiscinfo>
27398</refmeta>
27399<refnamediv>
27400 <refname>drm_get_cea_aspect_ratio</refname>
27401 <refpurpose>
27402     get the picture aspect ratio corresponding to the input VIC from the CEA mode list
27403 </refpurpose>
27404</refnamediv>
27405<refsynopsisdiv>
27406 <title>Synopsis</title>
27407  <funcsynopsis><funcprototype>
27408   <funcdef>enum hdmi_picture_aspect <function>drm_get_cea_aspect_ratio </function></funcdef>
27409   <paramdef>const u8 <parameter>video_code</parameter></paramdef>
27410  </funcprototype></funcsynopsis>
27411</refsynopsisdiv>
27412<refsect1>
27413 <title>Arguments</title>
27414 <variablelist>
27415  <varlistentry>
27416   <term><parameter>video_code</parameter></term>
27417   <listitem>
27418    <para>
27419     ID given to each of the CEA modes
27420    </para>
27421   </listitem>
27422  </varlistentry>
27423 </variablelist>
27424</refsect1>
27425<refsect1>
27426<title>Description</title>
27427<para>
27428   Returns picture aspect ratio
27429</para>
27430</refsect1>
27431</refentry>
27432
27433<refentry id="API-drm-edid-to-eld">
27434<refentryinfo>
27435 <title>LINUX</title>
27436 <productname>Kernel Hackers Manual</productname>
27437 <date>July 2017</date>
27438</refentryinfo>
27439<refmeta>
27440 <refentrytitle><phrase>drm_edid_to_eld</phrase></refentrytitle>
27441 <manvolnum>9</manvolnum>
27442 <refmiscinfo class="version">4.1.27</refmiscinfo>
27443</refmeta>
27444<refnamediv>
27445 <refname>drm_edid_to_eld</refname>
27446 <refpurpose>
27447     build ELD from EDID
27448 </refpurpose>
27449</refnamediv>
27450<refsynopsisdiv>
27451 <title>Synopsis</title>
27452  <funcsynopsis><funcprototype>
27453   <funcdef>void <function>drm_edid_to_eld </function></funcdef>
27454   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
27455   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27456  </funcprototype></funcsynopsis>
27457</refsynopsisdiv>
27458<refsect1>
27459 <title>Arguments</title>
27460 <variablelist>
27461  <varlistentry>
27462   <term><parameter>connector</parameter></term>
27463   <listitem>
27464    <para>
27465     connector corresponding to the HDMI/DP sink
27466    </para>
27467   </listitem>
27468  </varlistentry>
27469  <varlistentry>
27470   <term><parameter>edid</parameter></term>
27471   <listitem>
27472    <para>
27473     EDID to parse
27474    </para>
27475   </listitem>
27476  </varlistentry>
27477 </variablelist>
27478</refsect1>
27479<refsect1>
27480<title>Description</title>
27481<para>
27482   Fill the ELD (EDID-Like Data) buffer for passing to the audio driver. The
27483   Conn_Type, HDCP and Port_ID ELD fields are left for the graphics driver to
27484   fill in.
27485</para>
27486</refsect1>
27487</refentry>
27488
27489<refentry id="API-drm-edid-to-sad">
27490<refentryinfo>
27491 <title>LINUX</title>
27492 <productname>Kernel Hackers Manual</productname>
27493 <date>July 2017</date>
27494</refentryinfo>
27495<refmeta>
27496 <refentrytitle><phrase>drm_edid_to_sad</phrase></refentrytitle>
27497 <manvolnum>9</manvolnum>
27498 <refmiscinfo class="version">4.1.27</refmiscinfo>
27499</refmeta>
27500<refnamediv>
27501 <refname>drm_edid_to_sad</refname>
27502 <refpurpose>
27503     extracts SADs from EDID
27504 </refpurpose>
27505</refnamediv>
27506<refsynopsisdiv>
27507 <title>Synopsis</title>
27508  <funcsynopsis><funcprototype>
27509   <funcdef>int <function>drm_edid_to_sad </function></funcdef>
27510   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27511   <paramdef>struct cea_sad ** <parameter>sads</parameter></paramdef>
27512  </funcprototype></funcsynopsis>
27513</refsynopsisdiv>
27514<refsect1>
27515 <title>Arguments</title>
27516 <variablelist>
27517  <varlistentry>
27518   <term><parameter>edid</parameter></term>
27519   <listitem>
27520    <para>
27521     EDID to parse
27522    </para>
27523   </listitem>
27524  </varlistentry>
27525  <varlistentry>
27526   <term><parameter>sads</parameter></term>
27527   <listitem>
27528    <para>
27529     pointer that will be set to the extracted SADs
27530    </para>
27531   </listitem>
27532  </varlistentry>
27533 </variablelist>
27534</refsect1>
27535<refsect1>
27536<title>Description</title>
27537<para>
27538   Looks for CEA EDID block and extracts SADs (Short Audio Descriptors) from it.
27539</para>
27540</refsect1>
27541<refsect1>
27542<title>Note</title>
27543<para>
27544   The returned pointer needs to be freed using <function>kfree</function>.
27545</para>
27546</refsect1>
27547<refsect1>
27548<title>Return</title>
27549<para>
27550   The number of found SADs or negative number on error.
27551</para>
27552</refsect1>
27553</refentry>
27554
27555<refentry id="API-drm-edid-to-speaker-allocation">
27556<refentryinfo>
27557 <title>LINUX</title>
27558 <productname>Kernel Hackers Manual</productname>
27559 <date>July 2017</date>
27560</refentryinfo>
27561<refmeta>
27562 <refentrytitle><phrase>drm_edid_to_speaker_allocation</phrase></refentrytitle>
27563 <manvolnum>9</manvolnum>
27564 <refmiscinfo class="version">4.1.27</refmiscinfo>
27565</refmeta>
27566<refnamediv>
27567 <refname>drm_edid_to_speaker_allocation</refname>
27568 <refpurpose>
27569     extracts Speaker Allocation Data Blocks from EDID
27570 </refpurpose>
27571</refnamediv>
27572<refsynopsisdiv>
27573 <title>Synopsis</title>
27574  <funcsynopsis><funcprototype>
27575   <funcdef>int <function>drm_edid_to_speaker_allocation </function></funcdef>
27576   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27577   <paramdef>u8 ** <parameter>sadb</parameter></paramdef>
27578  </funcprototype></funcsynopsis>
27579</refsynopsisdiv>
27580<refsect1>
27581 <title>Arguments</title>
27582 <variablelist>
27583  <varlistentry>
27584   <term><parameter>edid</parameter></term>
27585   <listitem>
27586    <para>
27587     EDID to parse
27588    </para>
27589   </listitem>
27590  </varlistentry>
27591  <varlistentry>
27592   <term><parameter>sadb</parameter></term>
27593   <listitem>
27594    <para>
27595     pointer to the speaker block
27596    </para>
27597   </listitem>
27598  </varlistentry>
27599 </variablelist>
27600</refsect1>
27601<refsect1>
27602<title>Description</title>
27603<para>
27604   Looks for CEA EDID block and extracts the Speaker Allocation Data Block from it.
27605</para>
27606</refsect1>
27607<refsect1>
27608<title>Note</title>
27609<para>
27610   The returned pointer needs to be freed using <function>kfree</function>.
27611</para>
27612</refsect1>
27613<refsect1>
27614<title>Return</title>
27615<para>
27616   The number of found Speaker Allocation Blocks or negative number on
27617   error.
27618</para>
27619</refsect1>
27620</refentry>
27621
27622<refentry id="API-drm-av-sync-delay">
27623<refentryinfo>
27624 <title>LINUX</title>
27625 <productname>Kernel Hackers Manual</productname>
27626 <date>July 2017</date>
27627</refentryinfo>
27628<refmeta>
27629 <refentrytitle><phrase>drm_av_sync_delay</phrase></refentrytitle>
27630 <manvolnum>9</manvolnum>
27631 <refmiscinfo class="version">4.1.27</refmiscinfo>
27632</refmeta>
27633<refnamediv>
27634 <refname>drm_av_sync_delay</refname>
27635 <refpurpose>
27636     compute the HDMI/DP sink audio-video sync delay
27637 </refpurpose>
27638</refnamediv>
27639<refsynopsisdiv>
27640 <title>Synopsis</title>
27641  <funcsynopsis><funcprototype>
27642   <funcdef>int <function>drm_av_sync_delay </function></funcdef>
27643   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
27644   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
27645  </funcprototype></funcsynopsis>
27646</refsynopsisdiv>
27647<refsect1>
27648 <title>Arguments</title>
27649 <variablelist>
27650  <varlistentry>
27651   <term><parameter>connector</parameter></term>
27652   <listitem>
27653    <para>
27654     connector associated with the HDMI/DP sink
27655    </para>
27656   </listitem>
27657  </varlistentry>
27658  <varlistentry>
27659   <term><parameter>mode</parameter></term>
27660   <listitem>
27661    <para>
27662     the display mode
27663    </para>
27664   </listitem>
27665  </varlistentry>
27666 </variablelist>
27667</refsect1>
27668<refsect1>
27669<title>Return</title>
27670<para>
27671   The HDMI/DP sink's audio-video sync delay in milliseconds or 0 if
27672   the sink doesn't support audio or video.
27673</para>
27674</refsect1>
27675</refentry>
27676
27677<refentry id="API-drm-select-eld">
27678<refentryinfo>
27679 <title>LINUX</title>
27680 <productname>Kernel Hackers Manual</productname>
27681 <date>July 2017</date>
27682</refentryinfo>
27683<refmeta>
27684 <refentrytitle><phrase>drm_select_eld</phrase></refentrytitle>
27685 <manvolnum>9</manvolnum>
27686 <refmiscinfo class="version">4.1.27</refmiscinfo>
27687</refmeta>
27688<refnamediv>
27689 <refname>drm_select_eld</refname>
27690 <refpurpose>
27691     select one ELD from multiple HDMI/DP sinks
27692 </refpurpose>
27693</refnamediv>
27694<refsynopsisdiv>
27695 <title>Synopsis</title>
27696  <funcsynopsis><funcprototype>
27697   <funcdef>struct drm_connector * <function>drm_select_eld </function></funcdef>
27698   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
27699   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
27700  </funcprototype></funcsynopsis>
27701</refsynopsisdiv>
27702<refsect1>
27703 <title>Arguments</title>
27704 <variablelist>
27705  <varlistentry>
27706   <term><parameter>encoder</parameter></term>
27707   <listitem>
27708    <para>
27709     the encoder just changed display mode
27710    </para>
27711   </listitem>
27712  </varlistentry>
27713  <varlistentry>
27714   <term><parameter>mode</parameter></term>
27715   <listitem>
27716    <para>
27717     the adjusted display mode
27718    </para>
27719   </listitem>
27720  </varlistentry>
27721 </variablelist>
27722</refsect1>
27723<refsect1>
27724<title>Description</title>
27725<para>
27726   It's possible for one encoder to be associated with multiple HDMI/DP sinks.
27727   The policy is now hard coded to simply use the first HDMI/DP sink's ELD.
27728</para>
27729</refsect1>
27730<refsect1>
27731<title>Return</title>
27732<para>
27733   The connector associated with the first HDMI/DP sink that has ELD
27734   attached to it.
27735</para>
27736</refsect1>
27737</refentry>
27738
27739<refentry id="API-drm-detect-hdmi-monitor">
27740<refentryinfo>
27741 <title>LINUX</title>
27742 <productname>Kernel Hackers Manual</productname>
27743 <date>July 2017</date>
27744</refentryinfo>
27745<refmeta>
27746 <refentrytitle><phrase>drm_detect_hdmi_monitor</phrase></refentrytitle>
27747 <manvolnum>9</manvolnum>
27748 <refmiscinfo class="version">4.1.27</refmiscinfo>
27749</refmeta>
27750<refnamediv>
27751 <refname>drm_detect_hdmi_monitor</refname>
27752 <refpurpose>
27753     detect whether monitor is HDMI
27754 </refpurpose>
27755</refnamediv>
27756<refsynopsisdiv>
27757 <title>Synopsis</title>
27758  <funcsynopsis><funcprototype>
27759   <funcdef>bool <function>drm_detect_hdmi_monitor </function></funcdef>
27760   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27761  </funcprototype></funcsynopsis>
27762</refsynopsisdiv>
27763<refsect1>
27764 <title>Arguments</title>
27765 <variablelist>
27766  <varlistentry>
27767   <term><parameter>edid</parameter></term>
27768   <listitem>
27769    <para>
27770     monitor EDID information
27771    </para>
27772   </listitem>
27773  </varlistentry>
27774 </variablelist>
27775</refsect1>
27776<refsect1>
27777<title>Description</title>
27778<para>
27779   Parse the CEA extension according to CEA-861-B.
27780</para>
27781</refsect1>
27782<refsect1>
27783<title>Return</title>
27784<para>
27785   True if the monitor is HDMI, false if not or unknown.
27786</para>
27787</refsect1>
27788</refentry>
27789
27790<refentry id="API-drm-detect-monitor-audio">
27791<refentryinfo>
27792 <title>LINUX</title>
27793 <productname>Kernel Hackers Manual</productname>
27794 <date>July 2017</date>
27795</refentryinfo>
27796<refmeta>
27797 <refentrytitle><phrase>drm_detect_monitor_audio</phrase></refentrytitle>
27798 <manvolnum>9</manvolnum>
27799 <refmiscinfo class="version">4.1.27</refmiscinfo>
27800</refmeta>
27801<refnamediv>
27802 <refname>drm_detect_monitor_audio</refname>
27803 <refpurpose>
27804     check monitor audio capability
27805 </refpurpose>
27806</refnamediv>
27807<refsynopsisdiv>
27808 <title>Synopsis</title>
27809  <funcsynopsis><funcprototype>
27810   <funcdef>bool <function>drm_detect_monitor_audio </function></funcdef>
27811   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27812  </funcprototype></funcsynopsis>
27813</refsynopsisdiv>
27814<refsect1>
27815 <title>Arguments</title>
27816 <variablelist>
27817  <varlistentry>
27818   <term><parameter>edid</parameter></term>
27819   <listitem>
27820    <para>
27821     EDID block to scan
27822    </para>
27823   </listitem>
27824  </varlistentry>
27825 </variablelist>
27826</refsect1>
27827<refsect1>
27828<title>Description</title>
27829<para>
27830   Monitor should have CEA extension block.
27831   If monitor has 'basic audio', but no CEA audio blocks, it's 'basic
27832   audio' only. If there is any audio extension block and supported
27833   audio format, assume at least 'basic audio' support, even if 'basic
27834   audio' is not defined in EDID.
27835</para>
27836</refsect1>
27837<refsect1>
27838<title>Return</title>
27839<para>
27840   True if the monitor supports audio, false otherwise.
27841</para>
27842</refsect1>
27843</refentry>
27844
27845<refentry id="API-drm-rgb-quant-range-selectable">
27846<refentryinfo>
27847 <title>LINUX</title>
27848 <productname>Kernel Hackers Manual</productname>
27849 <date>July 2017</date>
27850</refentryinfo>
27851<refmeta>
27852 <refentrytitle><phrase>drm_rgb_quant_range_selectable</phrase></refentrytitle>
27853 <manvolnum>9</manvolnum>
27854 <refmiscinfo class="version">4.1.27</refmiscinfo>
27855</refmeta>
27856<refnamediv>
27857 <refname>drm_rgb_quant_range_selectable</refname>
27858 <refpurpose>
27859     is RGB quantization range selectable?
27860 </refpurpose>
27861</refnamediv>
27862<refsynopsisdiv>
27863 <title>Synopsis</title>
27864  <funcsynopsis><funcprototype>
27865   <funcdef>bool <function>drm_rgb_quant_range_selectable </function></funcdef>
27866   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27867  </funcprototype></funcsynopsis>
27868</refsynopsisdiv>
27869<refsect1>
27870 <title>Arguments</title>
27871 <variablelist>
27872  <varlistentry>
27873   <term><parameter>edid</parameter></term>
27874   <listitem>
27875    <para>
27876     EDID block to scan
27877    </para>
27878   </listitem>
27879  </varlistentry>
27880 </variablelist>
27881</refsect1>
27882<refsect1>
27883<title>Description</title>
27884<para>
27885   Check whether the monitor reports the RGB quantization range selection
27886   as supported. The AVI infoframe can then be used to inform the monitor
27887   which quantization range (full or limited) is used.
27888</para>
27889</refsect1>
27890<refsect1>
27891<title>Return</title>
27892<para>
27893   True if the RGB quantization range is selectable, false otherwise.
27894</para>
27895</refsect1>
27896</refentry>
27897
27898<refentry id="API-drm-add-edid-modes">
27899<refentryinfo>
27900 <title>LINUX</title>
27901 <productname>Kernel Hackers Manual</productname>
27902 <date>July 2017</date>
27903</refentryinfo>
27904<refmeta>
27905 <refentrytitle><phrase>drm_add_edid_modes</phrase></refentrytitle>
27906 <manvolnum>9</manvolnum>
27907 <refmiscinfo class="version">4.1.27</refmiscinfo>
27908</refmeta>
27909<refnamediv>
27910 <refname>drm_add_edid_modes</refname>
27911 <refpurpose>
27912     add modes from EDID data, if available
27913 </refpurpose>
27914</refnamediv>
27915<refsynopsisdiv>
27916 <title>Synopsis</title>
27917  <funcsynopsis><funcprototype>
27918   <funcdef>int <function>drm_add_edid_modes </function></funcdef>
27919   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
27920   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
27921  </funcprototype></funcsynopsis>
27922</refsynopsisdiv>
27923<refsect1>
27924 <title>Arguments</title>
27925 <variablelist>
27926  <varlistentry>
27927   <term><parameter>connector</parameter></term>
27928   <listitem>
27929    <para>
27930     connector we're probing
27931    </para>
27932   </listitem>
27933  </varlistentry>
27934  <varlistentry>
27935   <term><parameter>edid</parameter></term>
27936   <listitem>
27937    <para>
27938     EDID data
27939    </para>
27940   </listitem>
27941  </varlistentry>
27942 </variablelist>
27943</refsect1>
27944<refsect1>
27945<title>Description</title>
27946<para>
27947   Add the specified modes to the connector's mode list.
27948</para>
27949</refsect1>
27950<refsect1>
27951<title>Return</title>
27952<para>
27953   The number of modes added or 0 if we couldn't find any.
27954</para>
27955</refsect1>
27956</refentry>
27957
27958<refentry id="API-drm-add-modes-noedid">
27959<refentryinfo>
27960 <title>LINUX</title>
27961 <productname>Kernel Hackers Manual</productname>
27962 <date>July 2017</date>
27963</refentryinfo>
27964<refmeta>
27965 <refentrytitle><phrase>drm_add_modes_noedid</phrase></refentrytitle>
27966 <manvolnum>9</manvolnum>
27967 <refmiscinfo class="version">4.1.27</refmiscinfo>
27968</refmeta>
27969<refnamediv>
27970 <refname>drm_add_modes_noedid</refname>
27971 <refpurpose>
27972     add modes for the connectors without EDID
27973 </refpurpose>
27974</refnamediv>
27975<refsynopsisdiv>
27976 <title>Synopsis</title>
27977  <funcsynopsis><funcprototype>
27978   <funcdef>int <function>drm_add_modes_noedid </function></funcdef>
27979   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
27980   <paramdef>int <parameter>hdisplay</parameter></paramdef>
27981   <paramdef>int <parameter>vdisplay</parameter></paramdef>
27982  </funcprototype></funcsynopsis>
27983</refsynopsisdiv>
27984<refsect1>
27985 <title>Arguments</title>
27986 <variablelist>
27987  <varlistentry>
27988   <term><parameter>connector</parameter></term>
27989   <listitem>
27990    <para>
27991     connector we're probing
27992    </para>
27993   </listitem>
27994  </varlistentry>
27995  <varlistentry>
27996   <term><parameter>hdisplay</parameter></term>
27997   <listitem>
27998    <para>
27999     the horizontal display limit
28000    </para>
28001   </listitem>
28002  </varlistentry>
28003  <varlistentry>
28004   <term><parameter>vdisplay</parameter></term>
28005   <listitem>
28006    <para>
28007     the vertical display limit
28008    </para>
28009   </listitem>
28010  </varlistentry>
28011 </variablelist>
28012</refsect1>
28013<refsect1>
28014<title>Description</title>
28015<para>
28016   Add the specified modes to the connector's mode list. Only when the
28017   hdisplay/vdisplay is not beyond the given limit, it will be added.
28018</para>
28019</refsect1>
28020<refsect1>
28021<title>Return</title>
28022<para>
28023   The number of modes added or 0 if we couldn't find any.
28024</para>
28025</refsect1>
28026</refentry>
28027
28028<refentry id="API-drm-set-preferred-mode">
28029<refentryinfo>
28030 <title>LINUX</title>
28031 <productname>Kernel Hackers Manual</productname>
28032 <date>July 2017</date>
28033</refentryinfo>
28034<refmeta>
28035 <refentrytitle><phrase>drm_set_preferred_mode</phrase></refentrytitle>
28036 <manvolnum>9</manvolnum>
28037 <refmiscinfo class="version">4.1.27</refmiscinfo>
28038</refmeta>
28039<refnamediv>
28040 <refname>drm_set_preferred_mode</refname>
28041 <refpurpose>
28042     Sets the preferred mode of a connector
28043 </refpurpose>
28044</refnamediv>
28045<refsynopsisdiv>
28046 <title>Synopsis</title>
28047  <funcsynopsis><funcprototype>
28048   <funcdef>void <function>drm_set_preferred_mode </function></funcdef>
28049   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
28050   <paramdef>int <parameter>hpref</parameter></paramdef>
28051   <paramdef>int <parameter>vpref</parameter></paramdef>
28052  </funcprototype></funcsynopsis>
28053</refsynopsisdiv>
28054<refsect1>
28055 <title>Arguments</title>
28056 <variablelist>
28057  <varlistentry>
28058   <term><parameter>connector</parameter></term>
28059   <listitem>
28060    <para>
28061     connector whose mode list should be processed
28062    </para>
28063   </listitem>
28064  </varlistentry>
28065  <varlistentry>
28066   <term><parameter>hpref</parameter></term>
28067   <listitem>
28068    <para>
28069     horizontal resolution of preferred mode
28070    </para>
28071   </listitem>
28072  </varlistentry>
28073  <varlistentry>
28074   <term><parameter>vpref</parameter></term>
28075   <listitem>
28076    <para>
28077     vertical resolution of preferred mode
28078    </para>
28079   </listitem>
28080  </varlistentry>
28081 </variablelist>
28082</refsect1>
28083<refsect1>
28084<title>Description</title>
28085<para>
28086   Marks a mode as preferred if it matches the resolution specified by <parameter>hpref</parameter>
28087   and <parameter>vpref</parameter>.
28088</para>
28089</refsect1>
28090</refentry>
28091
28092<refentry id="API-drm-hdmi-avi-infoframe-from-display-mode">
28093<refentryinfo>
28094 <title>LINUX</title>
28095 <productname>Kernel Hackers Manual</productname>
28096 <date>July 2017</date>
28097</refentryinfo>
28098<refmeta>
28099 <refentrytitle><phrase>drm_hdmi_avi_infoframe_from_display_mode</phrase></refentrytitle>
28100 <manvolnum>9</manvolnum>
28101 <refmiscinfo class="version">4.1.27</refmiscinfo>
28102</refmeta>
28103<refnamediv>
28104 <refname>drm_hdmi_avi_infoframe_from_display_mode</refname>
28105 <refpurpose>
28106     fill an HDMI AVI infoframe with data from a DRM display mode
28107 </refpurpose>
28108</refnamediv>
28109<refsynopsisdiv>
28110 <title>Synopsis</title>
28111  <funcsynopsis><funcprototype>
28112   <funcdef>int <function>drm_hdmi_avi_infoframe_from_display_mode </function></funcdef>
28113   <paramdef>struct hdmi_avi_infoframe * <parameter>frame</parameter></paramdef>
28114   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
28115  </funcprototype></funcsynopsis>
28116</refsynopsisdiv>
28117<refsect1>
28118 <title>Arguments</title>
28119 <variablelist>
28120  <varlistentry>
28121   <term><parameter>frame</parameter></term>
28122   <listitem>
28123    <para>
28124     HDMI AVI infoframe
28125    </para>
28126   </listitem>
28127  </varlistentry>
28128  <varlistentry>
28129   <term><parameter>mode</parameter></term>
28130   <listitem>
28131    <para>
28132     DRM display mode
28133    </para>
28134   </listitem>
28135  </varlistentry>
28136 </variablelist>
28137</refsect1>
28138<refsect1>
28139<title>Return</title>
28140<para>
28141   0 on success or a negative error code on failure.
28142</para>
28143</refsect1>
28144</refentry>
28145
28146<refentry id="API-drm-hdmi-vendor-infoframe-from-display-mode">
28147<refentryinfo>
28148 <title>LINUX</title>
28149 <productname>Kernel Hackers Manual</productname>
28150 <date>July 2017</date>
28151</refentryinfo>
28152<refmeta>
28153 <refentrytitle><phrase>drm_hdmi_vendor_infoframe_from_display_mode</phrase></refentrytitle>
28154 <manvolnum>9</manvolnum>
28155 <refmiscinfo class="version">4.1.27</refmiscinfo>
28156</refmeta>
28157<refnamediv>
28158 <refname>drm_hdmi_vendor_infoframe_from_display_mode</refname>
28159 <refpurpose>
28160     fill an HDMI infoframe with data from a DRM display mode
28161 </refpurpose>
28162</refnamediv>
28163<refsynopsisdiv>
28164 <title>Synopsis</title>
28165  <funcsynopsis><funcprototype>
28166   <funcdef>int <function>drm_hdmi_vendor_infoframe_from_display_mode </function></funcdef>
28167   <paramdef>struct hdmi_vendor_infoframe * <parameter>frame</parameter></paramdef>
28168   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
28169  </funcprototype></funcsynopsis>
28170</refsynopsisdiv>
28171<refsect1>
28172 <title>Arguments</title>
28173 <variablelist>
28174  <varlistentry>
28175   <term><parameter>frame</parameter></term>
28176   <listitem>
28177    <para>
28178     HDMI vendor infoframe
28179    </para>
28180   </listitem>
28181  </varlistentry>
28182  <varlistentry>
28183   <term><parameter>mode</parameter></term>
28184   <listitem>
28185    <para>
28186     DRM display mode
28187    </para>
28188   </listitem>
28189  </varlistentry>
28190 </variablelist>
28191</refsect1>
28192<refsect1>
28193<title>Description</title>
28194<para>
28195   Note that there's is a need to send HDMI vendor infoframes only when using a
28196   4k or stereoscopic 3D mode. So when giving any other mode as input this
28197   function will return -EINVAL, error that can be safely ignored.
28198</para>
28199</refsect1>
28200<refsect1>
28201<title>Return</title>
28202<para>
28203   0 on success or a negative error code on failure.
28204</para>
28205</refsect1>
28206</refentry>
28207
28208    </sect2>
28209    <sect2>
28210      <title>Rectangle Utilities Reference</title>
28211<para>
28212   </para><para>
28213   Utility functions to help manage rectangular areas for
28214   clipping, scaling, etc. calculations.
28215</para>
28216
28217<!-- include/drm/drm_rect.h -->
28218<refentry id="API-struct-drm-rect">
28219<refentryinfo>
28220 <title>LINUX</title>
28221 <productname>Kernel Hackers Manual</productname>
28222 <date>July 2017</date>
28223</refentryinfo>
28224<refmeta>
28225 <refentrytitle><phrase>struct drm_rect</phrase></refentrytitle>
28226 <manvolnum>9</manvolnum>
28227 <refmiscinfo class="version">4.1.27</refmiscinfo>
28228</refmeta>
28229<refnamediv>
28230 <refname>struct drm_rect</refname>
28231 <refpurpose>
28232  two dimensional rectangle
28233 </refpurpose>
28234</refnamediv>
28235<refsynopsisdiv>
28236 <title>Synopsis</title>
28237  <programlisting>
28238struct drm_rect {
28239  int x1;
28240  int y1;
28241  int x2;
28242  int y2;
28243};  </programlisting>
28244</refsynopsisdiv>
28245 <refsect1>
28246  <title>Members</title>
28247  <variablelist>
28248    <varlistentry>      <term>x1</term>
28249      <listitem><para>
28250horizontal starting coordinate (inclusive)
28251      </para></listitem>
28252    </varlistentry>
28253    <varlistentry>      <term>y1</term>
28254      <listitem><para>
28255vertical starting coordinate (inclusive)
28256      </para></listitem>
28257    </varlistentry>
28258    <varlistentry>      <term>x2</term>
28259      <listitem><para>
28260horizontal ending coordinate (exclusive)
28261      </para></listitem>
28262    </varlistentry>
28263    <varlistentry>      <term>y2</term>
28264      <listitem><para>
28265vertical ending coordinate (exclusive)
28266      </para></listitem>
28267    </varlistentry>
28268  </variablelist>
28269 </refsect1>
28270</refentry>
28271
28272<refentry id="API-drm-rect-adjust-size">
28273<refentryinfo>
28274 <title>LINUX</title>
28275 <productname>Kernel Hackers Manual</productname>
28276 <date>July 2017</date>
28277</refentryinfo>
28278<refmeta>
28279 <refentrytitle><phrase>drm_rect_adjust_size</phrase></refentrytitle>
28280 <manvolnum>9</manvolnum>
28281 <refmiscinfo class="version">4.1.27</refmiscinfo>
28282</refmeta>
28283<refnamediv>
28284 <refname>drm_rect_adjust_size</refname>
28285 <refpurpose>
28286     adjust the size of the rectangle
28287 </refpurpose>
28288</refnamediv>
28289<refsynopsisdiv>
28290 <title>Synopsis</title>
28291  <funcsynopsis><funcprototype>
28292   <funcdef>void <function>drm_rect_adjust_size </function></funcdef>
28293   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
28294   <paramdef>int <parameter>dw</parameter></paramdef>
28295   <paramdef>int <parameter>dh</parameter></paramdef>
28296  </funcprototype></funcsynopsis>
28297</refsynopsisdiv>
28298<refsect1>
28299 <title>Arguments</title>
28300 <variablelist>
28301  <varlistentry>
28302   <term><parameter>r</parameter></term>
28303   <listitem>
28304    <para>
28305     rectangle to be adjusted
28306    </para>
28307   </listitem>
28308  </varlistentry>
28309  <varlistentry>
28310   <term><parameter>dw</parameter></term>
28311   <listitem>
28312    <para>
28313     horizontal adjustment
28314    </para>
28315   </listitem>
28316  </varlistentry>
28317  <varlistentry>
28318   <term><parameter>dh</parameter></term>
28319   <listitem>
28320    <para>
28321     vertical adjustment
28322    </para>
28323   </listitem>
28324  </varlistentry>
28325 </variablelist>
28326</refsect1>
28327<refsect1>
28328<title>Description</title>
28329<para>
28330   Change the size of rectangle <parameter>r</parameter> by <parameter>dw</parameter> in the horizontal direction,
28331   and by <parameter>dh</parameter> in the vertical direction, while keeping the center
28332   of <parameter>r</parameter> stationary.
28333   </para><para>
28334
28335   Positive <parameter>dw</parameter> and <parameter>dh</parameter> increase the size, negative values decrease it.
28336</para>
28337</refsect1>
28338</refentry>
28339
28340<refentry id="API-drm-rect-translate">
28341<refentryinfo>
28342 <title>LINUX</title>
28343 <productname>Kernel Hackers Manual</productname>
28344 <date>July 2017</date>
28345</refentryinfo>
28346<refmeta>
28347 <refentrytitle><phrase>drm_rect_translate</phrase></refentrytitle>
28348 <manvolnum>9</manvolnum>
28349 <refmiscinfo class="version">4.1.27</refmiscinfo>
28350</refmeta>
28351<refnamediv>
28352 <refname>drm_rect_translate</refname>
28353 <refpurpose>
28354     translate the rectangle
28355 </refpurpose>
28356</refnamediv>
28357<refsynopsisdiv>
28358 <title>Synopsis</title>
28359  <funcsynopsis><funcprototype>
28360   <funcdef>void <function>drm_rect_translate </function></funcdef>
28361   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
28362   <paramdef>int <parameter>dx</parameter></paramdef>
28363   <paramdef>int <parameter>dy</parameter></paramdef>
28364  </funcprototype></funcsynopsis>
28365</refsynopsisdiv>
28366<refsect1>
28367 <title>Arguments</title>
28368 <variablelist>
28369  <varlistentry>
28370   <term><parameter>r</parameter></term>
28371   <listitem>
28372    <para>
28373     rectangle to be tranlated
28374    </para>
28375   </listitem>
28376  </varlistentry>
28377  <varlistentry>
28378   <term><parameter>dx</parameter></term>
28379   <listitem>
28380    <para>
28381     horizontal translation
28382    </para>
28383   </listitem>
28384  </varlistentry>
28385  <varlistentry>
28386   <term><parameter>dy</parameter></term>
28387   <listitem>
28388    <para>
28389     vertical translation
28390    </para>
28391   </listitem>
28392  </varlistentry>
28393 </variablelist>
28394</refsect1>
28395<refsect1>
28396<title>Description</title>
28397<para>
28398   Move rectangle <parameter>r</parameter> by <parameter>dx</parameter> in the horizontal direction,
28399   and by <parameter>dy</parameter> in the vertical direction.
28400</para>
28401</refsect1>
28402</refentry>
28403
28404<refentry id="API-drm-rect-downscale">
28405<refentryinfo>
28406 <title>LINUX</title>
28407 <productname>Kernel Hackers Manual</productname>
28408 <date>July 2017</date>
28409</refentryinfo>
28410<refmeta>
28411 <refentrytitle><phrase>drm_rect_downscale</phrase></refentrytitle>
28412 <manvolnum>9</manvolnum>
28413 <refmiscinfo class="version">4.1.27</refmiscinfo>
28414</refmeta>
28415<refnamediv>
28416 <refname>drm_rect_downscale</refname>
28417 <refpurpose>
28418     downscale a rectangle
28419 </refpurpose>
28420</refnamediv>
28421<refsynopsisdiv>
28422 <title>Synopsis</title>
28423  <funcsynopsis><funcprototype>
28424   <funcdef>void <function>drm_rect_downscale </function></funcdef>
28425   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
28426   <paramdef>int <parameter>horz</parameter></paramdef>
28427   <paramdef>int <parameter>vert</parameter></paramdef>
28428  </funcprototype></funcsynopsis>
28429</refsynopsisdiv>
28430<refsect1>
28431 <title>Arguments</title>
28432 <variablelist>
28433  <varlistentry>
28434   <term><parameter>r</parameter></term>
28435   <listitem>
28436    <para>
28437     rectangle to be downscaled
28438    </para>
28439   </listitem>
28440  </varlistentry>
28441  <varlistentry>
28442   <term><parameter>horz</parameter></term>
28443   <listitem>
28444    <para>
28445     horizontal downscale factor
28446    </para>
28447   </listitem>
28448  </varlistentry>
28449  <varlistentry>
28450   <term><parameter>vert</parameter></term>
28451   <listitem>
28452    <para>
28453     vertical downscale factor
28454    </para>
28455   </listitem>
28456  </varlistentry>
28457 </variablelist>
28458</refsect1>
28459<refsect1>
28460<title>Description</title>
28461<para>
28462   Divide the coordinates of rectangle <parameter>r</parameter> by <parameter>horz</parameter> and <parameter>vert</parameter>.
28463</para>
28464</refsect1>
28465</refentry>
28466
28467<refentry id="API-drm-rect-width">
28468<refentryinfo>
28469 <title>LINUX</title>
28470 <productname>Kernel Hackers Manual</productname>
28471 <date>July 2017</date>
28472</refentryinfo>
28473<refmeta>
28474 <refentrytitle><phrase>drm_rect_width</phrase></refentrytitle>
28475 <manvolnum>9</manvolnum>
28476 <refmiscinfo class="version">4.1.27</refmiscinfo>
28477</refmeta>
28478<refnamediv>
28479 <refname>drm_rect_width</refname>
28480 <refpurpose>
28481     determine the rectangle width
28482 </refpurpose>
28483</refnamediv>
28484<refsynopsisdiv>
28485 <title>Synopsis</title>
28486  <funcsynopsis><funcprototype>
28487   <funcdef>int <function>drm_rect_width </function></funcdef>
28488   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
28489  </funcprototype></funcsynopsis>
28490</refsynopsisdiv>
28491<refsect1>
28492 <title>Arguments</title>
28493 <variablelist>
28494  <varlistentry>
28495   <term><parameter>r</parameter></term>
28496   <listitem>
28497    <para>
28498     rectangle whose width is returned
28499    </para>
28500   </listitem>
28501  </varlistentry>
28502 </variablelist>
28503</refsect1>
28504<refsect1>
28505<title>RETURNS</title>
28506<para>
28507   The width of the rectangle.
28508</para>
28509</refsect1>
28510</refentry>
28511
28512<refentry id="API-drm-rect-height">
28513<refentryinfo>
28514 <title>LINUX</title>
28515 <productname>Kernel Hackers Manual</productname>
28516 <date>July 2017</date>
28517</refentryinfo>
28518<refmeta>
28519 <refentrytitle><phrase>drm_rect_height</phrase></refentrytitle>
28520 <manvolnum>9</manvolnum>
28521 <refmiscinfo class="version">4.1.27</refmiscinfo>
28522</refmeta>
28523<refnamediv>
28524 <refname>drm_rect_height</refname>
28525 <refpurpose>
28526     determine the rectangle height
28527 </refpurpose>
28528</refnamediv>
28529<refsynopsisdiv>
28530 <title>Synopsis</title>
28531  <funcsynopsis><funcprototype>
28532   <funcdef>int <function>drm_rect_height </function></funcdef>
28533   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
28534  </funcprototype></funcsynopsis>
28535</refsynopsisdiv>
28536<refsect1>
28537 <title>Arguments</title>
28538 <variablelist>
28539  <varlistentry>
28540   <term><parameter>r</parameter></term>
28541   <listitem>
28542    <para>
28543     rectangle whose height is returned
28544    </para>
28545   </listitem>
28546  </varlistentry>
28547 </variablelist>
28548</refsect1>
28549<refsect1>
28550<title>RETURNS</title>
28551<para>
28552   The height of the rectangle.
28553</para>
28554</refsect1>
28555</refentry>
28556
28557<refentry id="API-drm-rect-visible">
28558<refentryinfo>
28559 <title>LINUX</title>
28560 <productname>Kernel Hackers Manual</productname>
28561 <date>July 2017</date>
28562</refentryinfo>
28563<refmeta>
28564 <refentrytitle><phrase>drm_rect_visible</phrase></refentrytitle>
28565 <manvolnum>9</manvolnum>
28566 <refmiscinfo class="version">4.1.27</refmiscinfo>
28567</refmeta>
28568<refnamediv>
28569 <refname>drm_rect_visible</refname>
28570 <refpurpose>
28571     determine if the the rectangle is visible
28572 </refpurpose>
28573</refnamediv>
28574<refsynopsisdiv>
28575 <title>Synopsis</title>
28576  <funcsynopsis><funcprototype>
28577   <funcdef>bool <function>drm_rect_visible </function></funcdef>
28578   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
28579  </funcprototype></funcsynopsis>
28580</refsynopsisdiv>
28581<refsect1>
28582 <title>Arguments</title>
28583 <variablelist>
28584  <varlistentry>
28585   <term><parameter>r</parameter></term>
28586   <listitem>
28587    <para>
28588     rectangle whose visibility is returned
28589    </para>
28590   </listitem>
28591  </varlistentry>
28592 </variablelist>
28593</refsect1>
28594<refsect1>
28595<title>RETURNS</title>
28596<para>
28597   <constant>true</constant> if the rectangle is visible, <constant>false</constant> otherwise.
28598</para>
28599</refsect1>
28600</refentry>
28601
28602<refentry id="API-drm-rect-equals">
28603<refentryinfo>
28604 <title>LINUX</title>
28605 <productname>Kernel Hackers Manual</productname>
28606 <date>July 2017</date>
28607</refentryinfo>
28608<refmeta>
28609 <refentrytitle><phrase>drm_rect_equals</phrase></refentrytitle>
28610 <manvolnum>9</manvolnum>
28611 <refmiscinfo class="version">4.1.27</refmiscinfo>
28612</refmeta>
28613<refnamediv>
28614 <refname>drm_rect_equals</refname>
28615 <refpurpose>
28616     determine if two rectangles are equal
28617 </refpurpose>
28618</refnamediv>
28619<refsynopsisdiv>
28620 <title>Synopsis</title>
28621  <funcsynopsis><funcprototype>
28622   <funcdef>bool <function>drm_rect_equals </function></funcdef>
28623   <paramdef>const struct drm_rect * <parameter>r1</parameter></paramdef>
28624   <paramdef>const struct drm_rect * <parameter>r2</parameter></paramdef>
28625  </funcprototype></funcsynopsis>
28626</refsynopsisdiv>
28627<refsect1>
28628 <title>Arguments</title>
28629 <variablelist>
28630  <varlistentry>
28631   <term><parameter>r1</parameter></term>
28632   <listitem>
28633    <para>
28634     first rectangle
28635    </para>
28636   </listitem>
28637  </varlistentry>
28638  <varlistentry>
28639   <term><parameter>r2</parameter></term>
28640   <listitem>
28641    <para>
28642     second rectangle
28643    </para>
28644   </listitem>
28645  </varlistentry>
28646 </variablelist>
28647</refsect1>
28648<refsect1>
28649<title>RETURNS</title>
28650<para>
28651   <constant>true</constant> if the rectangles are equal, <constant>false</constant> otherwise.
28652</para>
28653</refsect1>
28654</refentry>
28655
28656<!-- drivers/gpu/drm/drm_rect.c -->
28657<refentry id="API-drm-rect-intersect">
28658<refentryinfo>
28659 <title>LINUX</title>
28660 <productname>Kernel Hackers Manual</productname>
28661 <date>July 2017</date>
28662</refentryinfo>
28663<refmeta>
28664 <refentrytitle><phrase>drm_rect_intersect</phrase></refentrytitle>
28665 <manvolnum>9</manvolnum>
28666 <refmiscinfo class="version">4.1.27</refmiscinfo>
28667</refmeta>
28668<refnamediv>
28669 <refname>drm_rect_intersect</refname>
28670 <refpurpose>
28671  intersect two rectangles
28672 </refpurpose>
28673</refnamediv>
28674<refsynopsisdiv>
28675 <title>Synopsis</title>
28676  <funcsynopsis><funcprototype>
28677   <funcdef>bool <function>drm_rect_intersect </function></funcdef>
28678   <paramdef>struct drm_rect * <parameter>r1</parameter></paramdef>
28679   <paramdef>const struct drm_rect * <parameter>r2</parameter></paramdef>
28680  </funcprototype></funcsynopsis>
28681</refsynopsisdiv>
28682<refsect1>
28683 <title>Arguments</title>
28684 <variablelist>
28685  <varlistentry>
28686   <term><parameter>r1</parameter></term>
28687   <listitem>
28688    <para>
28689     first rectangle
28690    </para>
28691   </listitem>
28692  </varlistentry>
28693  <varlistentry>
28694   <term><parameter>r2</parameter></term>
28695   <listitem>
28696    <para>
28697     second rectangle
28698    </para>
28699   </listitem>
28700  </varlistentry>
28701 </variablelist>
28702</refsect1>
28703<refsect1>
28704<title>Description</title>
28705<para>
28706   Calculate the intersection of rectangles <parameter>r1</parameter> and <parameter>r2</parameter>.
28707   <parameter>r1</parameter> will be overwritten with the intersection.
28708</para>
28709</refsect1>
28710<refsect1>
28711<title>RETURNS</title>
28712<para>
28713   <constant>true</constant> if rectangle <parameter>r1</parameter> is still visible after the operation,
28714   <constant>false</constant> otherwise.
28715</para>
28716</refsect1>
28717</refentry>
28718
28719<refentry id="API-drm-rect-clip-scaled">
28720<refentryinfo>
28721 <title>LINUX</title>
28722 <productname>Kernel Hackers Manual</productname>
28723 <date>July 2017</date>
28724</refentryinfo>
28725<refmeta>
28726 <refentrytitle><phrase>drm_rect_clip_scaled</phrase></refentrytitle>
28727 <manvolnum>9</manvolnum>
28728 <refmiscinfo class="version">4.1.27</refmiscinfo>
28729</refmeta>
28730<refnamediv>
28731 <refname>drm_rect_clip_scaled</refname>
28732 <refpurpose>
28733     perform a scaled clip operation
28734 </refpurpose>
28735</refnamediv>
28736<refsynopsisdiv>
28737 <title>Synopsis</title>
28738  <funcsynopsis><funcprototype>
28739   <funcdef>bool <function>drm_rect_clip_scaled </function></funcdef>
28740   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
28741   <paramdef>struct drm_rect * <parameter>dst</parameter></paramdef>
28742   <paramdef>const struct drm_rect * <parameter>clip</parameter></paramdef>
28743   <paramdef>int <parameter>hscale</parameter></paramdef>
28744   <paramdef>int <parameter>vscale</parameter></paramdef>
28745  </funcprototype></funcsynopsis>
28746</refsynopsisdiv>
28747<refsect1>
28748 <title>Arguments</title>
28749 <variablelist>
28750  <varlistentry>
28751   <term><parameter>src</parameter></term>
28752   <listitem>
28753    <para>
28754     source window rectangle
28755    </para>
28756   </listitem>
28757  </varlistentry>
28758  <varlistentry>
28759   <term><parameter>dst</parameter></term>
28760   <listitem>
28761    <para>
28762     destination window rectangle
28763    </para>
28764   </listitem>
28765  </varlistentry>
28766  <varlistentry>
28767   <term><parameter>clip</parameter></term>
28768   <listitem>
28769    <para>
28770     clip rectangle
28771    </para>
28772   </listitem>
28773  </varlistentry>
28774  <varlistentry>
28775   <term><parameter>hscale</parameter></term>
28776   <listitem>
28777    <para>
28778     horizontal scaling factor
28779    </para>
28780   </listitem>
28781  </varlistentry>
28782  <varlistentry>
28783   <term><parameter>vscale</parameter></term>
28784   <listitem>
28785    <para>
28786     vertical scaling factor
28787    </para>
28788   </listitem>
28789  </varlistentry>
28790 </variablelist>
28791</refsect1>
28792<refsect1>
28793<title>Description</title>
28794<para>
28795   Clip rectangle <parameter>dst</parameter> by rectangle <parameter>clip</parameter>. Clip rectangle <parameter>src</parameter> by the
28796   same amounts multiplied by <parameter>hscale</parameter> and <parameter>vscale</parameter>.
28797</para>
28798</refsect1>
28799<refsect1>
28800<title>RETURNS</title>
28801<para>
28802   <constant>true</constant> if rectangle <parameter>dst</parameter> is still visible after being clipped,
28803   <constant>false</constant> otherwise
28804</para>
28805</refsect1>
28806</refentry>
28807
28808<refentry id="API-drm-rect-calc-hscale">
28809<refentryinfo>
28810 <title>LINUX</title>
28811 <productname>Kernel Hackers Manual</productname>
28812 <date>July 2017</date>
28813</refentryinfo>
28814<refmeta>
28815 <refentrytitle><phrase>drm_rect_calc_hscale</phrase></refentrytitle>
28816 <manvolnum>9</manvolnum>
28817 <refmiscinfo class="version">4.1.27</refmiscinfo>
28818</refmeta>
28819<refnamediv>
28820 <refname>drm_rect_calc_hscale</refname>
28821 <refpurpose>
28822     calculate the horizontal scaling factor
28823 </refpurpose>
28824</refnamediv>
28825<refsynopsisdiv>
28826 <title>Synopsis</title>
28827  <funcsynopsis><funcprototype>
28828   <funcdef>int <function>drm_rect_calc_hscale </function></funcdef>
28829   <paramdef>const struct drm_rect * <parameter>src</parameter></paramdef>
28830   <paramdef>const struct drm_rect * <parameter>dst</parameter></paramdef>
28831   <paramdef>int <parameter>min_hscale</parameter></paramdef>
28832   <paramdef>int <parameter>max_hscale</parameter></paramdef>
28833  </funcprototype></funcsynopsis>
28834</refsynopsisdiv>
28835<refsect1>
28836 <title>Arguments</title>
28837 <variablelist>
28838  <varlistentry>
28839   <term><parameter>src</parameter></term>
28840   <listitem>
28841    <para>
28842     source window rectangle
28843    </para>
28844   </listitem>
28845  </varlistentry>
28846  <varlistentry>
28847   <term><parameter>dst</parameter></term>
28848   <listitem>
28849    <para>
28850     destination window rectangle
28851    </para>
28852   </listitem>
28853  </varlistentry>
28854  <varlistentry>
28855   <term><parameter>min_hscale</parameter></term>
28856   <listitem>
28857    <para>
28858     minimum allowed horizontal scaling factor
28859    </para>
28860   </listitem>
28861  </varlistentry>
28862  <varlistentry>
28863   <term><parameter>max_hscale</parameter></term>
28864   <listitem>
28865    <para>
28866     maximum allowed horizontal scaling factor
28867    </para>
28868   </listitem>
28869  </varlistentry>
28870 </variablelist>
28871</refsect1>
28872<refsect1>
28873<title>Description</title>
28874<para>
28875   Calculate the horizontal scaling factor as
28876   (<parameter>src</parameter> width) / (<parameter>dst</parameter> width).
28877</para>
28878</refsect1>
28879<refsect1>
28880<title>RETURNS</title>
28881<para>
28882   The horizontal scaling factor, or errno of out of limits.
28883</para>
28884</refsect1>
28885</refentry>
28886
28887<refentry id="API-drm-rect-calc-vscale">
28888<refentryinfo>
28889 <title>LINUX</title>
28890 <productname>Kernel Hackers Manual</productname>
28891 <date>July 2017</date>
28892</refentryinfo>
28893<refmeta>
28894 <refentrytitle><phrase>drm_rect_calc_vscale</phrase></refentrytitle>
28895 <manvolnum>9</manvolnum>
28896 <refmiscinfo class="version">4.1.27</refmiscinfo>
28897</refmeta>
28898<refnamediv>
28899 <refname>drm_rect_calc_vscale</refname>
28900 <refpurpose>
28901     calculate the vertical scaling factor
28902 </refpurpose>
28903</refnamediv>
28904<refsynopsisdiv>
28905 <title>Synopsis</title>
28906  <funcsynopsis><funcprototype>
28907   <funcdef>int <function>drm_rect_calc_vscale </function></funcdef>
28908   <paramdef>const struct drm_rect * <parameter>src</parameter></paramdef>
28909   <paramdef>const struct drm_rect * <parameter>dst</parameter></paramdef>
28910   <paramdef>int <parameter>min_vscale</parameter></paramdef>
28911   <paramdef>int <parameter>max_vscale</parameter></paramdef>
28912  </funcprototype></funcsynopsis>
28913</refsynopsisdiv>
28914<refsect1>
28915 <title>Arguments</title>
28916 <variablelist>
28917  <varlistentry>
28918   <term><parameter>src</parameter></term>
28919   <listitem>
28920    <para>
28921     source window rectangle
28922    </para>
28923   </listitem>
28924  </varlistentry>
28925  <varlistentry>
28926   <term><parameter>dst</parameter></term>
28927   <listitem>
28928    <para>
28929     destination window rectangle
28930    </para>
28931   </listitem>
28932  </varlistentry>
28933  <varlistentry>
28934   <term><parameter>min_vscale</parameter></term>
28935   <listitem>
28936    <para>
28937     minimum allowed vertical scaling factor
28938    </para>
28939   </listitem>
28940  </varlistentry>
28941  <varlistentry>
28942   <term><parameter>max_vscale</parameter></term>
28943   <listitem>
28944    <para>
28945     maximum allowed vertical scaling factor
28946    </para>
28947   </listitem>
28948  </varlistentry>
28949 </variablelist>
28950</refsect1>
28951<refsect1>
28952<title>Description</title>
28953<para>
28954   Calculate the vertical scaling factor as
28955   (<parameter>src</parameter> height) / (<parameter>dst</parameter> height).
28956</para>
28957</refsect1>
28958<refsect1>
28959<title>RETURNS</title>
28960<para>
28961   The vertical scaling factor, or errno of out of limits.
28962</para>
28963</refsect1>
28964</refentry>
28965
28966<refentry id="API-drm-rect-calc-hscale-relaxed">
28967<refentryinfo>
28968 <title>LINUX</title>
28969 <productname>Kernel Hackers Manual</productname>
28970 <date>July 2017</date>
28971</refentryinfo>
28972<refmeta>
28973 <refentrytitle><phrase>drm_rect_calc_hscale_relaxed</phrase></refentrytitle>
28974 <manvolnum>9</manvolnum>
28975 <refmiscinfo class="version">4.1.27</refmiscinfo>
28976</refmeta>
28977<refnamediv>
28978 <refname>drm_rect_calc_hscale_relaxed</refname>
28979 <refpurpose>
28980     calculate the horizontal scaling factor
28981 </refpurpose>
28982</refnamediv>
28983<refsynopsisdiv>
28984 <title>Synopsis</title>
28985  <funcsynopsis><funcprototype>
28986   <funcdef>int <function>drm_rect_calc_hscale_relaxed </function></funcdef>
28987   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
28988   <paramdef>struct drm_rect * <parameter>dst</parameter></paramdef>
28989   <paramdef>int <parameter>min_hscale</parameter></paramdef>
28990   <paramdef>int <parameter>max_hscale</parameter></paramdef>
28991  </funcprototype></funcsynopsis>
28992</refsynopsisdiv>
28993<refsect1>
28994 <title>Arguments</title>
28995 <variablelist>
28996  <varlistentry>
28997   <term><parameter>src</parameter></term>
28998   <listitem>
28999    <para>
29000     source window rectangle
29001    </para>
29002   </listitem>
29003  </varlistentry>
29004  <varlistentry>
29005   <term><parameter>dst</parameter></term>
29006   <listitem>
29007    <para>
29008     destination window rectangle
29009    </para>
29010   </listitem>
29011  </varlistentry>
29012  <varlistentry>
29013   <term><parameter>min_hscale</parameter></term>
29014   <listitem>
29015    <para>
29016     minimum allowed horizontal scaling factor
29017    </para>
29018   </listitem>
29019  </varlistentry>
29020  <varlistentry>
29021   <term><parameter>max_hscale</parameter></term>
29022   <listitem>
29023    <para>
29024     maximum allowed horizontal scaling factor
29025    </para>
29026   </listitem>
29027  </varlistentry>
29028 </variablelist>
29029</refsect1>
29030<refsect1>
29031<title>Description</title>
29032<para>
29033   Calculate the horizontal scaling factor as
29034   (<parameter>src</parameter> width) / (<parameter>dst</parameter> width).
29035   </para><para>
29036
29037   If the calculated scaling factor is below <parameter>min_vscale</parameter>,
29038   decrease the height of rectangle <parameter>dst</parameter> to compensate.
29039   </para><para>
29040
29041   If the calculated scaling factor is above <parameter>max_vscale</parameter>,
29042   decrease the height of rectangle <parameter>src</parameter> to compensate.
29043</para>
29044</refsect1>
29045<refsect1>
29046<title>RETURNS</title>
29047<para>
29048   The horizontal scaling factor.
29049</para>
29050</refsect1>
29051</refentry>
29052
29053<refentry id="API-drm-rect-calc-vscale-relaxed">
29054<refentryinfo>
29055 <title>LINUX</title>
29056 <productname>Kernel Hackers Manual</productname>
29057 <date>July 2017</date>
29058</refentryinfo>
29059<refmeta>
29060 <refentrytitle><phrase>drm_rect_calc_vscale_relaxed</phrase></refentrytitle>
29061 <manvolnum>9</manvolnum>
29062 <refmiscinfo class="version">4.1.27</refmiscinfo>
29063</refmeta>
29064<refnamediv>
29065 <refname>drm_rect_calc_vscale_relaxed</refname>
29066 <refpurpose>
29067     calculate the vertical scaling factor
29068 </refpurpose>
29069</refnamediv>
29070<refsynopsisdiv>
29071 <title>Synopsis</title>
29072  <funcsynopsis><funcprototype>
29073   <funcdef>int <function>drm_rect_calc_vscale_relaxed </function></funcdef>
29074   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
29075   <paramdef>struct drm_rect * <parameter>dst</parameter></paramdef>
29076   <paramdef>int <parameter>min_vscale</parameter></paramdef>
29077   <paramdef>int <parameter>max_vscale</parameter></paramdef>
29078  </funcprototype></funcsynopsis>
29079</refsynopsisdiv>
29080<refsect1>
29081 <title>Arguments</title>
29082 <variablelist>
29083  <varlistentry>
29084   <term><parameter>src</parameter></term>
29085   <listitem>
29086    <para>
29087     source window rectangle
29088    </para>
29089   </listitem>
29090  </varlistentry>
29091  <varlistentry>
29092   <term><parameter>dst</parameter></term>
29093   <listitem>
29094    <para>
29095     destination window rectangle
29096    </para>
29097   </listitem>
29098  </varlistentry>
29099  <varlistentry>
29100   <term><parameter>min_vscale</parameter></term>
29101   <listitem>
29102    <para>
29103     minimum allowed vertical scaling factor
29104    </para>
29105   </listitem>
29106  </varlistentry>
29107  <varlistentry>
29108   <term><parameter>max_vscale</parameter></term>
29109   <listitem>
29110    <para>
29111     maximum allowed vertical scaling factor
29112    </para>
29113   </listitem>
29114  </varlistentry>
29115 </variablelist>
29116</refsect1>
29117<refsect1>
29118<title>Description</title>
29119<para>
29120   Calculate the vertical scaling factor as
29121   (<parameter>src</parameter> height) / (<parameter>dst</parameter> height).
29122   </para><para>
29123
29124   If the calculated scaling factor is below <parameter>min_vscale</parameter>,
29125   decrease the height of rectangle <parameter>dst</parameter> to compensate.
29126   </para><para>
29127
29128   If the calculated scaling factor is above <parameter>max_vscale</parameter>,
29129   decrease the height of rectangle <parameter>src</parameter> to compensate.
29130</para>
29131</refsect1>
29132<refsect1>
29133<title>RETURNS</title>
29134<para>
29135   The vertical scaling factor.
29136</para>
29137</refsect1>
29138</refentry>
29139
29140<refentry id="API-drm-rect-debug-print">
29141<refentryinfo>
29142 <title>LINUX</title>
29143 <productname>Kernel Hackers Manual</productname>
29144 <date>July 2017</date>
29145</refentryinfo>
29146<refmeta>
29147 <refentrytitle><phrase>drm_rect_debug_print</phrase></refentrytitle>
29148 <manvolnum>9</manvolnum>
29149 <refmiscinfo class="version">4.1.27</refmiscinfo>
29150</refmeta>
29151<refnamediv>
29152 <refname>drm_rect_debug_print</refname>
29153 <refpurpose>
29154     print the rectangle information
29155 </refpurpose>
29156</refnamediv>
29157<refsynopsisdiv>
29158 <title>Synopsis</title>
29159  <funcsynopsis><funcprototype>
29160   <funcdef>void <function>drm_rect_debug_print </function></funcdef>
29161   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
29162   <paramdef>bool <parameter>fixed_point</parameter></paramdef>
29163  </funcprototype></funcsynopsis>
29164</refsynopsisdiv>
29165<refsect1>
29166 <title>Arguments</title>
29167 <variablelist>
29168  <varlistentry>
29169   <term><parameter>r</parameter></term>
29170   <listitem>
29171    <para>
29172     rectangle to print
29173    </para>
29174   </listitem>
29175  </varlistentry>
29176  <varlistentry>
29177   <term><parameter>fixed_point</parameter></term>
29178   <listitem>
29179    <para>
29180     rectangle is in 16.16 fixed point format
29181    </para>
29182   </listitem>
29183  </varlistentry>
29184 </variablelist>
29185</refsect1>
29186</refentry>
29187
29188<refentry id="API-drm-rect-rotate">
29189<refentryinfo>
29190 <title>LINUX</title>
29191 <productname>Kernel Hackers Manual</productname>
29192 <date>July 2017</date>
29193</refentryinfo>
29194<refmeta>
29195 <refentrytitle><phrase>drm_rect_rotate</phrase></refentrytitle>
29196 <manvolnum>9</manvolnum>
29197 <refmiscinfo class="version">4.1.27</refmiscinfo>
29198</refmeta>
29199<refnamediv>
29200 <refname>drm_rect_rotate</refname>
29201 <refpurpose>
29202     Rotate the rectangle
29203 </refpurpose>
29204</refnamediv>
29205<refsynopsisdiv>
29206 <title>Synopsis</title>
29207  <funcsynopsis><funcprototype>
29208   <funcdef>void <function>drm_rect_rotate </function></funcdef>
29209   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
29210   <paramdef>int <parameter>width</parameter></paramdef>
29211   <paramdef>int <parameter>height</parameter></paramdef>
29212   <paramdef>unsigned int <parameter>rotation</parameter></paramdef>
29213  </funcprototype></funcsynopsis>
29214</refsynopsisdiv>
29215<refsect1>
29216 <title>Arguments</title>
29217 <variablelist>
29218  <varlistentry>
29219   <term><parameter>r</parameter></term>
29220   <listitem>
29221    <para>
29222     rectangle to be rotated
29223    </para>
29224   </listitem>
29225  </varlistentry>
29226  <varlistentry>
29227   <term><parameter>width</parameter></term>
29228   <listitem>
29229    <para>
29230     Width of the coordinate space
29231    </para>
29232   </listitem>
29233  </varlistentry>
29234  <varlistentry>
29235   <term><parameter>height</parameter></term>
29236   <listitem>
29237    <para>
29238     Height of the coordinate space
29239    </para>
29240   </listitem>
29241  </varlistentry>
29242  <varlistentry>
29243   <term><parameter>rotation</parameter></term>
29244   <listitem>
29245    <para>
29246     Transformation to be applied
29247    </para>
29248   </listitem>
29249  </varlistentry>
29250 </variablelist>
29251</refsect1>
29252<refsect1>
29253<title>Description</title>
29254<para>
29255   Apply <parameter>rotation</parameter> to the coordinates of rectangle <parameter>r</parameter>.
29256   </para><para>
29257
29258   <parameter>width</parameter> and <parameter>height</parameter> combined with <parameter>rotation</parameter> define
29259   the location of the new origin.
29260   </para><para>
29261
29262   <parameter>width</parameter> correcsponds to the horizontal and <parameter>height</parameter>
29263   to the vertical axis of the untransformed coordinate
29264   space.
29265</para>
29266</refsect1>
29267</refentry>
29268
29269<refentry id="API-drm-rect-rotate-inv">
29270<refentryinfo>
29271 <title>LINUX</title>
29272 <productname>Kernel Hackers Manual</productname>
29273 <date>July 2017</date>
29274</refentryinfo>
29275<refmeta>
29276 <refentrytitle><phrase>drm_rect_rotate_inv</phrase></refentrytitle>
29277 <manvolnum>9</manvolnum>
29278 <refmiscinfo class="version">4.1.27</refmiscinfo>
29279</refmeta>
29280<refnamediv>
29281 <refname>drm_rect_rotate_inv</refname>
29282 <refpurpose>
29283     Inverse rotate the rectangle
29284 </refpurpose>
29285</refnamediv>
29286<refsynopsisdiv>
29287 <title>Synopsis</title>
29288  <funcsynopsis><funcprototype>
29289   <funcdef>void <function>drm_rect_rotate_inv </function></funcdef>
29290   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
29291   <paramdef>int <parameter>width</parameter></paramdef>
29292   <paramdef>int <parameter>height</parameter></paramdef>
29293   <paramdef>unsigned int <parameter>rotation</parameter></paramdef>
29294  </funcprototype></funcsynopsis>
29295</refsynopsisdiv>
29296<refsect1>
29297 <title>Arguments</title>
29298 <variablelist>
29299  <varlistentry>
29300   <term><parameter>r</parameter></term>
29301   <listitem>
29302    <para>
29303     rectangle to be rotated
29304    </para>
29305   </listitem>
29306  </varlistentry>
29307  <varlistentry>
29308   <term><parameter>width</parameter></term>
29309   <listitem>
29310    <para>
29311     Width of the coordinate space
29312    </para>
29313   </listitem>
29314  </varlistentry>
29315  <varlistentry>
29316   <term><parameter>height</parameter></term>
29317   <listitem>
29318    <para>
29319     Height of the coordinate space
29320    </para>
29321   </listitem>
29322  </varlistentry>
29323  <varlistentry>
29324   <term><parameter>rotation</parameter></term>
29325   <listitem>
29326    <para>
29327     Transformation whose inverse is to be applied
29328    </para>
29329   </listitem>
29330  </varlistentry>
29331 </variablelist>
29332</refsect1>
29333<refsect1>
29334<title>Description</title>
29335<para>
29336   Apply the inverse of <parameter>rotation</parameter> to the coordinates
29337   of rectangle <parameter>r</parameter>.
29338   </para><para>
29339
29340   <parameter>width</parameter> and <parameter>height</parameter> combined with <parameter>rotation</parameter> define
29341   the location of the new origin.
29342   </para><para>
29343
29344   <parameter>width</parameter> correcsponds to the horizontal and <parameter>height</parameter>
29345   to the vertical axis of the original untransformed
29346   coordinate space, so that you never have to flip
29347   them when doing a rotatation and its inverse.
29348   That is, if you do:
29349   </para><para>
29350
29351   drm_rotate(<structname>r</structname>, width, height, rotation);
29352   drm_rotate_inv(<structname>r</structname>, width, height, rotation);
29353   </para><para>
29354
29355   you will always get back the original rectangle.
29356</para>
29357</refsect1>
29358</refentry>
29359
29360    </sect2>
29361    <sect2>
29362      <title>Flip-work Helper Reference</title>
29363<para>
29364   </para><para>
29365   Util to queue up work to run from work-queue context after flip/vblank.
29366   Typically this can be used to defer unref of framebuffer's, cursor
29367   bo's, etc until after vblank.  The APIs are all thread-safe.
29368   Moreover, drm_flip_work_queue_task and drm_flip_work_queue can be called
29369   in atomic context.
29370</para>
29371
29372<!-- include/drm/drm_flip_work.h -->
29373<refentry id="API-struct-drm-flip-task">
29374<refentryinfo>
29375 <title>LINUX</title>
29376 <productname>Kernel Hackers Manual</productname>
29377 <date>July 2017</date>
29378</refentryinfo>
29379<refmeta>
29380 <refentrytitle><phrase>struct drm_flip_task</phrase></refentrytitle>
29381 <manvolnum>9</manvolnum>
29382 <refmiscinfo class="version">4.1.27</refmiscinfo>
29383</refmeta>
29384<refnamediv>
29385 <refname>struct drm_flip_task</refname>
29386 <refpurpose>
29387  flip work task
29388 </refpurpose>
29389</refnamediv>
29390<refsynopsisdiv>
29391 <title>Synopsis</title>
29392  <programlisting>
29393struct drm_flip_task {
29394  struct list_head node;
29395  void * data;
29396};  </programlisting>
29397</refsynopsisdiv>
29398 <refsect1>
29399  <title>Members</title>
29400  <variablelist>
29401    <varlistentry>      <term>node</term>
29402      <listitem><para>
29403list entry element
29404      </para></listitem>
29405    </varlistentry>
29406    <varlistentry>      <term>data</term>
29407      <listitem><para>
29408data to pass to work-&gt;func
29409      </para></listitem>
29410    </varlistentry>
29411  </variablelist>
29412 </refsect1>
29413</refentry>
29414
29415<refentry id="API-struct-drm-flip-work">
29416<refentryinfo>
29417 <title>LINUX</title>
29418 <productname>Kernel Hackers Manual</productname>
29419 <date>July 2017</date>
29420</refentryinfo>
29421<refmeta>
29422 <refentrytitle><phrase>struct drm_flip_work</phrase></refentrytitle>
29423 <manvolnum>9</manvolnum>
29424 <refmiscinfo class="version">4.1.27</refmiscinfo>
29425</refmeta>
29426<refnamediv>
29427 <refname>struct drm_flip_work</refname>
29428 <refpurpose>
29429     flip work queue
29430 </refpurpose>
29431</refnamediv>
29432<refsynopsisdiv>
29433 <title>Synopsis</title>
29434  <programlisting>
29435struct drm_flip_work {
29436  const char * name;
29437  drm_flip_func_t func;
29438  struct work_struct worker;
29439  struct list_head queued;
29440  struct list_head commited;
29441  spinlock_t lock;
29442};  </programlisting>
29443</refsynopsisdiv>
29444 <refsect1>
29445  <title>Members</title>
29446  <variablelist>
29447    <varlistentry>      <term>name</term>
29448      <listitem><para>
29449   debug name
29450      </para></listitem>
29451    </varlistentry>
29452    <varlistentry>      <term>func</term>
29453      <listitem><para>
29454   callback fxn called for each committed item
29455      </para></listitem>
29456    </varlistentry>
29457    <varlistentry>      <term>worker</term>
29458      <listitem><para>
29459   worker which calls <parameter>func</parameter>
29460      </para></listitem>
29461    </varlistentry>
29462    <varlistentry>      <term>queued</term>
29463      <listitem><para>
29464   queued tasks
29465      </para></listitem>
29466    </varlistentry>
29467    <varlistentry>      <term>commited</term>
29468      <listitem><para>
29469   commited tasks
29470      </para></listitem>
29471    </varlistentry>
29472    <varlistentry>      <term>lock</term>
29473      <listitem><para>
29474   lock to access queued and commited lists
29475      </para></listitem>
29476    </varlistentry>
29477  </variablelist>
29478 </refsect1>
29479</refentry>
29480
29481<!-- drivers/gpu/drm/drm_flip_work.c -->
29482<refentry id="API-drm-flip-work-allocate-task">
29483<refentryinfo>
29484 <title>LINUX</title>
29485 <productname>Kernel Hackers Manual</productname>
29486 <date>July 2017</date>
29487</refentryinfo>
29488<refmeta>
29489 <refentrytitle><phrase>drm_flip_work_allocate_task</phrase></refentrytitle>
29490 <manvolnum>9</manvolnum>
29491 <refmiscinfo class="version">4.1.27</refmiscinfo>
29492</refmeta>
29493<refnamediv>
29494 <refname>drm_flip_work_allocate_task</refname>
29495 <refpurpose>
29496  allocate a flip-work task
29497 </refpurpose>
29498</refnamediv>
29499<refsynopsisdiv>
29500 <title>Synopsis</title>
29501  <funcsynopsis><funcprototype>
29502   <funcdef>struct drm_flip_task * <function>drm_flip_work_allocate_task </function></funcdef>
29503   <paramdef>void * <parameter>data</parameter></paramdef>
29504   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
29505  </funcprototype></funcsynopsis>
29506</refsynopsisdiv>
29507<refsect1>
29508 <title>Arguments</title>
29509 <variablelist>
29510  <varlistentry>
29511   <term><parameter>data</parameter></term>
29512   <listitem>
29513    <para>
29514     data associated to the task
29515    </para>
29516   </listitem>
29517  </varlistentry>
29518  <varlistentry>
29519   <term><parameter>flags</parameter></term>
29520   <listitem>
29521    <para>
29522     allocator flags
29523    </para>
29524   </listitem>
29525  </varlistentry>
29526 </variablelist>
29527</refsect1>
29528<refsect1>
29529<title>Description</title>
29530<para>
29531   Allocate a drm_flip_task object and attach private data to it.
29532</para>
29533</refsect1>
29534</refentry>
29535
29536<refentry id="API-drm-flip-work-queue-task">
29537<refentryinfo>
29538 <title>LINUX</title>
29539 <productname>Kernel Hackers Manual</productname>
29540 <date>July 2017</date>
29541</refentryinfo>
29542<refmeta>
29543 <refentrytitle><phrase>drm_flip_work_queue_task</phrase></refentrytitle>
29544 <manvolnum>9</manvolnum>
29545 <refmiscinfo class="version">4.1.27</refmiscinfo>
29546</refmeta>
29547<refnamediv>
29548 <refname>drm_flip_work_queue_task</refname>
29549 <refpurpose>
29550     queue a specific task
29551 </refpurpose>
29552</refnamediv>
29553<refsynopsisdiv>
29554 <title>Synopsis</title>
29555  <funcsynopsis><funcprototype>
29556   <funcdef>void <function>drm_flip_work_queue_task </function></funcdef>
29557   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
29558   <paramdef>struct drm_flip_task * <parameter>task</parameter></paramdef>
29559  </funcprototype></funcsynopsis>
29560</refsynopsisdiv>
29561<refsect1>
29562 <title>Arguments</title>
29563 <variablelist>
29564  <varlistentry>
29565   <term><parameter>work</parameter></term>
29566   <listitem>
29567    <para>
29568     the flip-work
29569    </para>
29570   </listitem>
29571  </varlistentry>
29572  <varlistentry>
29573   <term><parameter>task</parameter></term>
29574   <listitem>
29575    <para>
29576     the task to handle
29577    </para>
29578   </listitem>
29579  </varlistentry>
29580 </variablelist>
29581</refsect1>
29582<refsect1>
29583<title>Description</title>
29584<para>
29585   Queues task, that will later be run (passed back to drm_flip_func_t
29586   func) on a work queue after <function>drm_flip_work_commit</function> is called.
29587</para>
29588</refsect1>
29589</refentry>
29590
29591<refentry id="API-drm-flip-work-queue">
29592<refentryinfo>
29593 <title>LINUX</title>
29594 <productname>Kernel Hackers Manual</productname>
29595 <date>July 2017</date>
29596</refentryinfo>
29597<refmeta>
29598 <refentrytitle><phrase>drm_flip_work_queue</phrase></refentrytitle>
29599 <manvolnum>9</manvolnum>
29600 <refmiscinfo class="version">4.1.27</refmiscinfo>
29601</refmeta>
29602<refnamediv>
29603 <refname>drm_flip_work_queue</refname>
29604 <refpurpose>
29605     queue work
29606 </refpurpose>
29607</refnamediv>
29608<refsynopsisdiv>
29609 <title>Synopsis</title>
29610  <funcsynopsis><funcprototype>
29611   <funcdef>void <function>drm_flip_work_queue </function></funcdef>
29612   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
29613   <paramdef>void * <parameter>val</parameter></paramdef>
29614  </funcprototype></funcsynopsis>
29615</refsynopsisdiv>
29616<refsect1>
29617 <title>Arguments</title>
29618 <variablelist>
29619  <varlistentry>
29620   <term><parameter>work</parameter></term>
29621   <listitem>
29622    <para>
29623     the flip-work
29624    </para>
29625   </listitem>
29626  </varlistentry>
29627  <varlistentry>
29628   <term><parameter>val</parameter></term>
29629   <listitem>
29630    <para>
29631     the value to queue
29632    </para>
29633   </listitem>
29634  </varlistentry>
29635 </variablelist>
29636</refsect1>
29637<refsect1>
29638<title>Description</title>
29639<para>
29640   Queues work, that will later be run (passed back to drm_flip_func_t
29641   func) on a work queue after <function>drm_flip_work_commit</function> is called.
29642</para>
29643</refsect1>
29644</refentry>
29645
29646<refentry id="API-drm-flip-work-commit">
29647<refentryinfo>
29648 <title>LINUX</title>
29649 <productname>Kernel Hackers Manual</productname>
29650 <date>July 2017</date>
29651</refentryinfo>
29652<refmeta>
29653 <refentrytitle><phrase>drm_flip_work_commit</phrase></refentrytitle>
29654 <manvolnum>9</manvolnum>
29655 <refmiscinfo class="version">4.1.27</refmiscinfo>
29656</refmeta>
29657<refnamediv>
29658 <refname>drm_flip_work_commit</refname>
29659 <refpurpose>
29660     commit queued work
29661 </refpurpose>
29662</refnamediv>
29663<refsynopsisdiv>
29664 <title>Synopsis</title>
29665  <funcsynopsis><funcprototype>
29666   <funcdef>void <function>drm_flip_work_commit </function></funcdef>
29667   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
29668   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
29669  </funcprototype></funcsynopsis>
29670</refsynopsisdiv>
29671<refsect1>
29672 <title>Arguments</title>
29673 <variablelist>
29674  <varlistentry>
29675   <term><parameter>work</parameter></term>
29676   <listitem>
29677    <para>
29678     the flip-work
29679    </para>
29680   </listitem>
29681  </varlistentry>
29682  <varlistentry>
29683   <term><parameter>wq</parameter></term>
29684   <listitem>
29685    <para>
29686     the work-queue to run the queued work on
29687    </para>
29688   </listitem>
29689  </varlistentry>
29690 </variablelist>
29691</refsect1>
29692<refsect1>
29693<title>Description</title>
29694<para>
29695   Trigger work previously queued by <function>drm_flip_work_queue</function> to run
29696   on a workqueue.  The typical usage would be to queue work (via
29697   <function>drm_flip_work_queue</function>) at any point (from vblank irq and/or
29698   prior), and then from vblank irq commit the queued work.
29699</para>
29700</refsect1>
29701</refentry>
29702
29703<refentry id="API-drm-flip-work-init">
29704<refentryinfo>
29705 <title>LINUX</title>
29706 <productname>Kernel Hackers Manual</productname>
29707 <date>July 2017</date>
29708</refentryinfo>
29709<refmeta>
29710 <refentrytitle><phrase>drm_flip_work_init</phrase></refentrytitle>
29711 <manvolnum>9</manvolnum>
29712 <refmiscinfo class="version">4.1.27</refmiscinfo>
29713</refmeta>
29714<refnamediv>
29715 <refname>drm_flip_work_init</refname>
29716 <refpurpose>
29717     initialize flip-work
29718 </refpurpose>
29719</refnamediv>
29720<refsynopsisdiv>
29721 <title>Synopsis</title>
29722  <funcsynopsis><funcprototype>
29723   <funcdef>void <function>drm_flip_work_init </function></funcdef>
29724   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
29725   <paramdef>const char * <parameter>name</parameter></paramdef>
29726   <paramdef>drm_flip_func_t <parameter>func</parameter></paramdef>
29727  </funcprototype></funcsynopsis>
29728</refsynopsisdiv>
29729<refsect1>
29730 <title>Arguments</title>
29731 <variablelist>
29732  <varlistentry>
29733   <term><parameter>work</parameter></term>
29734   <listitem>
29735    <para>
29736     the flip-work to initialize
29737    </para>
29738   </listitem>
29739  </varlistentry>
29740  <varlistentry>
29741   <term><parameter>name</parameter></term>
29742   <listitem>
29743    <para>
29744     debug name
29745    </para>
29746   </listitem>
29747  </varlistentry>
29748  <varlistentry>
29749   <term><parameter>func</parameter></term>
29750   <listitem>
29751    <para>
29752     the callback work function
29753    </para>
29754   </listitem>
29755  </varlistentry>
29756 </variablelist>
29757</refsect1>
29758<refsect1>
29759<title>Description</title>
29760<para>
29761   Initializes/allocates resources for the flip-work
29762</para>
29763</refsect1>
29764</refentry>
29765
29766<refentry id="API-drm-flip-work-cleanup">
29767<refentryinfo>
29768 <title>LINUX</title>
29769 <productname>Kernel Hackers Manual</productname>
29770 <date>July 2017</date>
29771</refentryinfo>
29772<refmeta>
29773 <refentrytitle><phrase>drm_flip_work_cleanup</phrase></refentrytitle>
29774 <manvolnum>9</manvolnum>
29775 <refmiscinfo class="version">4.1.27</refmiscinfo>
29776</refmeta>
29777<refnamediv>
29778 <refname>drm_flip_work_cleanup</refname>
29779 <refpurpose>
29780     cleans up flip-work
29781 </refpurpose>
29782</refnamediv>
29783<refsynopsisdiv>
29784 <title>Synopsis</title>
29785  <funcsynopsis><funcprototype>
29786   <funcdef>void <function>drm_flip_work_cleanup </function></funcdef>
29787   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
29788  </funcprototype></funcsynopsis>
29789</refsynopsisdiv>
29790<refsect1>
29791 <title>Arguments</title>
29792 <variablelist>
29793  <varlistentry>
29794   <term><parameter>work</parameter></term>
29795   <listitem>
29796    <para>
29797     the flip-work to cleanup
29798    </para>
29799   </listitem>
29800  </varlistentry>
29801 </variablelist>
29802</refsect1>
29803<refsect1>
29804<title>Description</title>
29805<para>
29806   Destroy resources allocated for the flip-work
29807</para>
29808</refsect1>
29809</refentry>
29810
29811    </sect2>
29812    <sect2>
29813      <title>HDMI Infoframes Helper Reference</title>
29814      <para>
29815	Strictly speaking this is not a DRM helper library but generally useable
29816	by any driver interfacing with HDMI outputs like v4l or alsa drivers.
29817	But it nicely fits into the overall topic of mode setting helper
29818	libraries and hence is also included here.
29819      </para>
29820<!-- include/linux/hdmi.h -->
29821<refentry id="API-struct-hdmi-infoframe">
29822<refentryinfo>
29823 <title>LINUX</title>
29824 <productname>Kernel Hackers Manual</productname>
29825 <date>July 2017</date>
29826</refentryinfo>
29827<refmeta>
29828 <refentrytitle><phrase>union hdmi_infoframe</phrase></refentrytitle>
29829 <manvolnum>9</manvolnum>
29830 <refmiscinfo class="version">4.1.27</refmiscinfo>
29831</refmeta>
29832<refnamediv>
29833 <refname>union hdmi_infoframe</refname>
29834 <refpurpose>
29835  overall union of all abstract infoframe representations
29836 </refpurpose>
29837</refnamediv>
29838<refsynopsisdiv>
29839 <title>Synopsis</title>
29840  <programlisting>
29841union hdmi_infoframe {
29842  struct hdmi_any_infoframe any;
29843  struct hdmi_avi_infoframe avi;
29844  struct hdmi_spd_infoframe spd;
29845  union hdmi_vendor_any_infoframe vendor;
29846  struct hdmi_audio_infoframe audio;
29847};  </programlisting>
29848</refsynopsisdiv>
29849 <refsect1>
29850  <title>Members</title>
29851  <variablelist>
29852    <varlistentry>      <term>any</term>
29853      <listitem><para>
29854generic infoframe
29855      </para></listitem>
29856    </varlistentry>
29857    <varlistentry>      <term>avi</term>
29858      <listitem><para>
29859avi infoframe
29860      </para></listitem>
29861    </varlistentry>
29862    <varlistentry>      <term>spd</term>
29863      <listitem><para>
29864spd infoframe
29865      </para></listitem>
29866    </varlistentry>
29867    <varlistentry>      <term>vendor</term>
29868      <listitem><para>
29869union of all vendor infoframes
29870      </para></listitem>
29871    </varlistentry>
29872    <varlistentry>      <term>audio</term>
29873      <listitem><para>
29874audio infoframe
29875      </para></listitem>
29876    </varlistentry>
29877  </variablelist>
29878 </refsect1>
29879<refsect1>
29880<title>Description</title>
29881<para>
29882   This is used by the generic pack function. This works since all infoframes
29883   have the same header which also indicates which type of infoframe should be
29884   packed.
29885</para>
29886</refsect1>
29887</refentry>
29888
29889<!-- drivers/video/hdmi.c -->
29890<refentry id="API-hdmi-avi-infoframe-init">
29891<refentryinfo>
29892 <title>LINUX</title>
29893 <productname>Kernel Hackers Manual</productname>
29894 <date>July 2017</date>
29895</refentryinfo>
29896<refmeta>
29897 <refentrytitle><phrase>hdmi_avi_infoframe_init</phrase></refentrytitle>
29898 <manvolnum>9</manvolnum>
29899 <refmiscinfo class="version">4.1.27</refmiscinfo>
29900</refmeta>
29901<refnamediv>
29902 <refname>hdmi_avi_infoframe_init</refname>
29903 <refpurpose>
29904  initialize an HDMI AVI infoframe
29905 </refpurpose>
29906</refnamediv>
29907<refsynopsisdiv>
29908 <title>Synopsis</title>
29909  <funcsynopsis><funcprototype>
29910   <funcdef>int <function>hdmi_avi_infoframe_init </function></funcdef>
29911   <paramdef>struct hdmi_avi_infoframe * <parameter>frame</parameter></paramdef>
29912  </funcprototype></funcsynopsis>
29913</refsynopsisdiv>
29914<refsect1>
29915 <title>Arguments</title>
29916 <variablelist>
29917  <varlistentry>
29918   <term><parameter>frame</parameter></term>
29919   <listitem>
29920    <para>
29921     HDMI AVI infoframe
29922    </para>
29923   </listitem>
29924  </varlistentry>
29925 </variablelist>
29926</refsect1>
29927<refsect1>
29928<title>Description</title>
29929<para>
29930   Returns 0 on success or a negative error code on failure.
29931</para>
29932</refsect1>
29933</refentry>
29934
29935<refentry id="API-hdmi-avi-infoframe-pack">
29936<refentryinfo>
29937 <title>LINUX</title>
29938 <productname>Kernel Hackers Manual</productname>
29939 <date>July 2017</date>
29940</refentryinfo>
29941<refmeta>
29942 <refentrytitle><phrase>hdmi_avi_infoframe_pack</phrase></refentrytitle>
29943 <manvolnum>9</manvolnum>
29944 <refmiscinfo class="version">4.1.27</refmiscinfo>
29945</refmeta>
29946<refnamediv>
29947 <refname>hdmi_avi_infoframe_pack</refname>
29948 <refpurpose>
29949     write HDMI AVI infoframe to binary buffer
29950 </refpurpose>
29951</refnamediv>
29952<refsynopsisdiv>
29953 <title>Synopsis</title>
29954  <funcsynopsis><funcprototype>
29955   <funcdef>ssize_t <function>hdmi_avi_infoframe_pack </function></funcdef>
29956   <paramdef>struct hdmi_avi_infoframe * <parameter>frame</parameter></paramdef>
29957   <paramdef>void * <parameter>buffer</parameter></paramdef>
29958   <paramdef>size_t <parameter>size</parameter></paramdef>
29959  </funcprototype></funcsynopsis>
29960</refsynopsisdiv>
29961<refsect1>
29962 <title>Arguments</title>
29963 <variablelist>
29964  <varlistentry>
29965   <term><parameter>frame</parameter></term>
29966   <listitem>
29967    <para>
29968     HDMI AVI infoframe
29969    </para>
29970   </listitem>
29971  </varlistentry>
29972  <varlistentry>
29973   <term><parameter>buffer</parameter></term>
29974   <listitem>
29975    <para>
29976     destination buffer
29977    </para>
29978   </listitem>
29979  </varlistentry>
29980  <varlistentry>
29981   <term><parameter>size</parameter></term>
29982   <listitem>
29983    <para>
29984     size of buffer
29985    </para>
29986   </listitem>
29987  </varlistentry>
29988 </variablelist>
29989</refsect1>
29990<refsect1>
29991<title>Description</title>
29992<para>
29993   Packs the information contained in the <parameter>frame</parameter> structure into a binary
29994   representation that can be written into the corresponding controller
29995   registers. Also computes the checksum as required by section 5.3.5 of
29996   the HDMI 1.4 specification.
29997   </para><para>
29998
29999   Returns the number of bytes packed into the binary buffer or a negative
30000   error code on failure.
30001</para>
30002</refsect1>
30003</refentry>
30004
30005<refentry id="API-hdmi-spd-infoframe-init">
30006<refentryinfo>
30007 <title>LINUX</title>
30008 <productname>Kernel Hackers Manual</productname>
30009 <date>July 2017</date>
30010</refentryinfo>
30011<refmeta>
30012 <refentrytitle><phrase>hdmi_spd_infoframe_init</phrase></refentrytitle>
30013 <manvolnum>9</manvolnum>
30014 <refmiscinfo class="version">4.1.27</refmiscinfo>
30015</refmeta>
30016<refnamediv>
30017 <refname>hdmi_spd_infoframe_init</refname>
30018 <refpurpose>
30019     initialize an HDMI SPD infoframe
30020 </refpurpose>
30021</refnamediv>
30022<refsynopsisdiv>
30023 <title>Synopsis</title>
30024  <funcsynopsis><funcprototype>
30025   <funcdef>int <function>hdmi_spd_infoframe_init </function></funcdef>
30026   <paramdef>struct hdmi_spd_infoframe * <parameter>frame</parameter></paramdef>
30027   <paramdef>const char * <parameter>vendor</parameter></paramdef>
30028   <paramdef>const char * <parameter>product</parameter></paramdef>
30029  </funcprototype></funcsynopsis>
30030</refsynopsisdiv>
30031<refsect1>
30032 <title>Arguments</title>
30033 <variablelist>
30034  <varlistentry>
30035   <term><parameter>frame</parameter></term>
30036   <listitem>
30037    <para>
30038     HDMI SPD infoframe
30039    </para>
30040   </listitem>
30041  </varlistentry>
30042  <varlistentry>
30043   <term><parameter>vendor</parameter></term>
30044   <listitem>
30045    <para>
30046     vendor string
30047    </para>
30048   </listitem>
30049  </varlistentry>
30050  <varlistentry>
30051   <term><parameter>product</parameter></term>
30052   <listitem>
30053    <para>
30054     product string
30055    </para>
30056   </listitem>
30057  </varlistentry>
30058 </variablelist>
30059</refsect1>
30060<refsect1>
30061<title>Description</title>
30062<para>
30063   Returns 0 on success or a negative error code on failure.
30064</para>
30065</refsect1>
30066</refentry>
30067
30068<refentry id="API-hdmi-spd-infoframe-pack">
30069<refentryinfo>
30070 <title>LINUX</title>
30071 <productname>Kernel Hackers Manual</productname>
30072 <date>July 2017</date>
30073</refentryinfo>
30074<refmeta>
30075 <refentrytitle><phrase>hdmi_spd_infoframe_pack</phrase></refentrytitle>
30076 <manvolnum>9</manvolnum>
30077 <refmiscinfo class="version">4.1.27</refmiscinfo>
30078</refmeta>
30079<refnamediv>
30080 <refname>hdmi_spd_infoframe_pack</refname>
30081 <refpurpose>
30082     write HDMI SPD infoframe to binary buffer
30083 </refpurpose>
30084</refnamediv>
30085<refsynopsisdiv>
30086 <title>Synopsis</title>
30087  <funcsynopsis><funcprototype>
30088   <funcdef>ssize_t <function>hdmi_spd_infoframe_pack </function></funcdef>
30089   <paramdef>struct hdmi_spd_infoframe * <parameter>frame</parameter></paramdef>
30090   <paramdef>void * <parameter>buffer</parameter></paramdef>
30091   <paramdef>size_t <parameter>size</parameter></paramdef>
30092  </funcprototype></funcsynopsis>
30093</refsynopsisdiv>
30094<refsect1>
30095 <title>Arguments</title>
30096 <variablelist>
30097  <varlistentry>
30098   <term><parameter>frame</parameter></term>
30099   <listitem>
30100    <para>
30101     HDMI SPD infoframe
30102    </para>
30103   </listitem>
30104  </varlistentry>
30105  <varlistentry>
30106   <term><parameter>buffer</parameter></term>
30107   <listitem>
30108    <para>
30109     destination buffer
30110    </para>
30111   </listitem>
30112  </varlistentry>
30113  <varlistentry>
30114   <term><parameter>size</parameter></term>
30115   <listitem>
30116    <para>
30117     size of buffer
30118    </para>
30119   </listitem>
30120  </varlistentry>
30121 </variablelist>
30122</refsect1>
30123<refsect1>
30124<title>Description</title>
30125<para>
30126   Packs the information contained in the <parameter>frame</parameter> structure into a binary
30127   representation that can be written into the corresponding controller
30128   registers. Also computes the checksum as required by section 5.3.5 of
30129   the HDMI 1.4 specification.
30130   </para><para>
30131
30132   Returns the number of bytes packed into the binary buffer or a negative
30133   error code on failure.
30134</para>
30135</refsect1>
30136</refentry>
30137
30138<refentry id="API-hdmi-audio-infoframe-init">
30139<refentryinfo>
30140 <title>LINUX</title>
30141 <productname>Kernel Hackers Manual</productname>
30142 <date>July 2017</date>
30143</refentryinfo>
30144<refmeta>
30145 <refentrytitle><phrase>hdmi_audio_infoframe_init</phrase></refentrytitle>
30146 <manvolnum>9</manvolnum>
30147 <refmiscinfo class="version">4.1.27</refmiscinfo>
30148</refmeta>
30149<refnamediv>
30150 <refname>hdmi_audio_infoframe_init</refname>
30151 <refpurpose>
30152     initialize an HDMI audio infoframe
30153 </refpurpose>
30154</refnamediv>
30155<refsynopsisdiv>
30156 <title>Synopsis</title>
30157  <funcsynopsis><funcprototype>
30158   <funcdef>int <function>hdmi_audio_infoframe_init </function></funcdef>
30159   <paramdef>struct hdmi_audio_infoframe * <parameter>frame</parameter></paramdef>
30160  </funcprototype></funcsynopsis>
30161</refsynopsisdiv>
30162<refsect1>
30163 <title>Arguments</title>
30164 <variablelist>
30165  <varlistentry>
30166   <term><parameter>frame</parameter></term>
30167   <listitem>
30168    <para>
30169     HDMI audio infoframe
30170    </para>
30171   </listitem>
30172  </varlistentry>
30173 </variablelist>
30174</refsect1>
30175<refsect1>
30176<title>Description</title>
30177<para>
30178   Returns 0 on success or a negative error code on failure.
30179</para>
30180</refsect1>
30181</refentry>
30182
30183<refentry id="API-hdmi-audio-infoframe-pack">
30184<refentryinfo>
30185 <title>LINUX</title>
30186 <productname>Kernel Hackers Manual</productname>
30187 <date>July 2017</date>
30188</refentryinfo>
30189<refmeta>
30190 <refentrytitle><phrase>hdmi_audio_infoframe_pack</phrase></refentrytitle>
30191 <manvolnum>9</manvolnum>
30192 <refmiscinfo class="version">4.1.27</refmiscinfo>
30193</refmeta>
30194<refnamediv>
30195 <refname>hdmi_audio_infoframe_pack</refname>
30196 <refpurpose>
30197     write HDMI audio infoframe to binary buffer
30198 </refpurpose>
30199</refnamediv>
30200<refsynopsisdiv>
30201 <title>Synopsis</title>
30202  <funcsynopsis><funcprototype>
30203   <funcdef>ssize_t <function>hdmi_audio_infoframe_pack </function></funcdef>
30204   <paramdef>struct hdmi_audio_infoframe * <parameter>frame</parameter></paramdef>
30205   <paramdef>void * <parameter>buffer</parameter></paramdef>
30206   <paramdef>size_t <parameter>size</parameter></paramdef>
30207  </funcprototype></funcsynopsis>
30208</refsynopsisdiv>
30209<refsect1>
30210 <title>Arguments</title>
30211 <variablelist>
30212  <varlistentry>
30213   <term><parameter>frame</parameter></term>
30214   <listitem>
30215    <para>
30216     HDMI audio infoframe
30217    </para>
30218   </listitem>
30219  </varlistentry>
30220  <varlistentry>
30221   <term><parameter>buffer</parameter></term>
30222   <listitem>
30223    <para>
30224     destination buffer
30225    </para>
30226   </listitem>
30227  </varlistentry>
30228  <varlistentry>
30229   <term><parameter>size</parameter></term>
30230   <listitem>
30231    <para>
30232     size of buffer
30233    </para>
30234   </listitem>
30235  </varlistentry>
30236 </variablelist>
30237</refsect1>
30238<refsect1>
30239<title>Description</title>
30240<para>
30241   Packs the information contained in the <parameter>frame</parameter> structure into a binary
30242   representation that can be written into the corresponding controller
30243   registers. Also computes the checksum as required by section 5.3.5 of
30244   the HDMI 1.4 specification.
30245   </para><para>
30246
30247   Returns the number of bytes packed into the binary buffer or a negative
30248   error code on failure.
30249</para>
30250</refsect1>
30251</refentry>
30252
30253<refentry id="API-hdmi-vendor-infoframe-init">
30254<refentryinfo>
30255 <title>LINUX</title>
30256 <productname>Kernel Hackers Manual</productname>
30257 <date>July 2017</date>
30258</refentryinfo>
30259<refmeta>
30260 <refentrytitle><phrase>hdmi_vendor_infoframe_init</phrase></refentrytitle>
30261 <manvolnum>9</manvolnum>
30262 <refmiscinfo class="version">4.1.27</refmiscinfo>
30263</refmeta>
30264<refnamediv>
30265 <refname>hdmi_vendor_infoframe_init</refname>
30266 <refpurpose>
30267     initialize an HDMI vendor infoframe
30268 </refpurpose>
30269</refnamediv>
30270<refsynopsisdiv>
30271 <title>Synopsis</title>
30272  <funcsynopsis><funcprototype>
30273   <funcdef>int <function>hdmi_vendor_infoframe_init </function></funcdef>
30274   <paramdef>struct hdmi_vendor_infoframe * <parameter>frame</parameter></paramdef>
30275  </funcprototype></funcsynopsis>
30276</refsynopsisdiv>
30277<refsect1>
30278 <title>Arguments</title>
30279 <variablelist>
30280  <varlistentry>
30281   <term><parameter>frame</parameter></term>
30282   <listitem>
30283    <para>
30284     HDMI vendor infoframe
30285    </para>
30286   </listitem>
30287  </varlistentry>
30288 </variablelist>
30289</refsect1>
30290<refsect1>
30291<title>Description</title>
30292<para>
30293   Returns 0 on success or a negative error code on failure.
30294</para>
30295</refsect1>
30296</refentry>
30297
30298<refentry id="API-hdmi-vendor-infoframe-pack">
30299<refentryinfo>
30300 <title>LINUX</title>
30301 <productname>Kernel Hackers Manual</productname>
30302 <date>July 2017</date>
30303</refentryinfo>
30304<refmeta>
30305 <refentrytitle><phrase>hdmi_vendor_infoframe_pack</phrase></refentrytitle>
30306 <manvolnum>9</manvolnum>
30307 <refmiscinfo class="version">4.1.27</refmiscinfo>
30308</refmeta>
30309<refnamediv>
30310 <refname>hdmi_vendor_infoframe_pack</refname>
30311 <refpurpose>
30312     write a HDMI vendor infoframe to binary buffer
30313 </refpurpose>
30314</refnamediv>
30315<refsynopsisdiv>
30316 <title>Synopsis</title>
30317  <funcsynopsis><funcprototype>
30318   <funcdef>ssize_t <function>hdmi_vendor_infoframe_pack </function></funcdef>
30319   <paramdef>struct hdmi_vendor_infoframe * <parameter>frame</parameter></paramdef>
30320   <paramdef>void * <parameter>buffer</parameter></paramdef>
30321   <paramdef>size_t <parameter>size</parameter></paramdef>
30322  </funcprototype></funcsynopsis>
30323</refsynopsisdiv>
30324<refsect1>
30325 <title>Arguments</title>
30326 <variablelist>
30327  <varlistentry>
30328   <term><parameter>frame</parameter></term>
30329   <listitem>
30330    <para>
30331     HDMI infoframe
30332    </para>
30333   </listitem>
30334  </varlistentry>
30335  <varlistentry>
30336   <term><parameter>buffer</parameter></term>
30337   <listitem>
30338    <para>
30339     destination buffer
30340    </para>
30341   </listitem>
30342  </varlistentry>
30343  <varlistentry>
30344   <term><parameter>size</parameter></term>
30345   <listitem>
30346    <para>
30347     size of buffer
30348    </para>
30349   </listitem>
30350  </varlistentry>
30351 </variablelist>
30352</refsect1>
30353<refsect1>
30354<title>Description</title>
30355<para>
30356   Packs the information contained in the <parameter>frame</parameter> structure into a binary
30357   representation that can be written into the corresponding controller
30358   registers. Also computes the checksum as required by section 5.3.5 of
30359   the HDMI 1.4 specification.
30360   </para><para>
30361
30362   Returns the number of bytes packed into the binary buffer or a negative
30363   error code on failure.
30364</para>
30365</refsect1>
30366</refentry>
30367
30368<refentry id="API-hdmi-infoframe-pack">
30369<refentryinfo>
30370 <title>LINUX</title>
30371 <productname>Kernel Hackers Manual</productname>
30372 <date>July 2017</date>
30373</refentryinfo>
30374<refmeta>
30375 <refentrytitle><phrase>hdmi_infoframe_pack</phrase></refentrytitle>
30376 <manvolnum>9</manvolnum>
30377 <refmiscinfo class="version">4.1.27</refmiscinfo>
30378</refmeta>
30379<refnamediv>
30380 <refname>hdmi_infoframe_pack</refname>
30381 <refpurpose>
30382     write a HDMI infoframe to binary buffer
30383 </refpurpose>
30384</refnamediv>
30385<refsynopsisdiv>
30386 <title>Synopsis</title>
30387  <funcsynopsis><funcprototype>
30388   <funcdef>ssize_t <function>hdmi_infoframe_pack </function></funcdef>
30389   <paramdef>union hdmi_infoframe * <parameter>frame</parameter></paramdef>
30390   <paramdef>void * <parameter>buffer</parameter></paramdef>
30391   <paramdef>size_t <parameter>size</parameter></paramdef>
30392  </funcprototype></funcsynopsis>
30393</refsynopsisdiv>
30394<refsect1>
30395 <title>Arguments</title>
30396 <variablelist>
30397  <varlistentry>
30398   <term><parameter>frame</parameter></term>
30399   <listitem>
30400    <para>
30401     HDMI infoframe
30402    </para>
30403   </listitem>
30404  </varlistentry>
30405  <varlistentry>
30406   <term><parameter>buffer</parameter></term>
30407   <listitem>
30408    <para>
30409     destination buffer
30410    </para>
30411   </listitem>
30412  </varlistentry>
30413  <varlistentry>
30414   <term><parameter>size</parameter></term>
30415   <listitem>
30416    <para>
30417     size of buffer
30418    </para>
30419   </listitem>
30420  </varlistentry>
30421 </variablelist>
30422</refsect1>
30423<refsect1>
30424<title>Description</title>
30425<para>
30426   Packs the information contained in the <parameter>frame</parameter> structure into a binary
30427   representation that can be written into the corresponding controller
30428   registers. Also computes the checksum as required by section 5.3.5 of
30429   the HDMI 1.4 specification.
30430   </para><para>
30431
30432   Returns the number of bytes packed into the binary buffer or a negative
30433   error code on failure.
30434</para>
30435</refsect1>
30436</refentry>
30437
30438<refentry id="API-hdmi-infoframe-log">
30439<refentryinfo>
30440 <title>LINUX</title>
30441 <productname>Kernel Hackers Manual</productname>
30442 <date>July 2017</date>
30443</refentryinfo>
30444<refmeta>
30445 <refentrytitle><phrase>hdmi_infoframe_log</phrase></refentrytitle>
30446 <manvolnum>9</manvolnum>
30447 <refmiscinfo class="version">4.1.27</refmiscinfo>
30448</refmeta>
30449<refnamediv>
30450 <refname>hdmi_infoframe_log</refname>
30451 <refpurpose>
30452     log info of HDMI infoframe
30453 </refpurpose>
30454</refnamediv>
30455<refsynopsisdiv>
30456 <title>Synopsis</title>
30457  <funcsynopsis><funcprototype>
30458   <funcdef>void <function>hdmi_infoframe_log </function></funcdef>
30459   <paramdef>const char * <parameter>level</parameter></paramdef>
30460   <paramdef>struct device * <parameter>dev</parameter></paramdef>
30461   <paramdef>union hdmi_infoframe * <parameter>frame</parameter></paramdef>
30462  </funcprototype></funcsynopsis>
30463</refsynopsisdiv>
30464<refsect1>
30465 <title>Arguments</title>
30466 <variablelist>
30467  <varlistentry>
30468   <term><parameter>level</parameter></term>
30469   <listitem>
30470    <para>
30471     logging level
30472    </para>
30473   </listitem>
30474  </varlistentry>
30475  <varlistentry>
30476   <term><parameter>dev</parameter></term>
30477   <listitem>
30478    <para>
30479     device
30480    </para>
30481   </listitem>
30482  </varlistentry>
30483  <varlistentry>
30484   <term><parameter>frame</parameter></term>
30485   <listitem>
30486    <para>
30487     HDMI infoframe
30488    </para>
30489   </listitem>
30490  </varlistentry>
30491 </variablelist>
30492</refsect1>
30493</refentry>
30494
30495<refentry id="API-hdmi-infoframe-unpack">
30496<refentryinfo>
30497 <title>LINUX</title>
30498 <productname>Kernel Hackers Manual</productname>
30499 <date>July 2017</date>
30500</refentryinfo>
30501<refmeta>
30502 <refentrytitle><phrase>hdmi_infoframe_unpack</phrase></refentrytitle>
30503 <manvolnum>9</manvolnum>
30504 <refmiscinfo class="version">4.1.27</refmiscinfo>
30505</refmeta>
30506<refnamediv>
30507 <refname>hdmi_infoframe_unpack</refname>
30508 <refpurpose>
30509     unpack binary buffer to a HDMI infoframe
30510 </refpurpose>
30511</refnamediv>
30512<refsynopsisdiv>
30513 <title>Synopsis</title>
30514  <funcsynopsis><funcprototype>
30515   <funcdef>int <function>hdmi_infoframe_unpack </function></funcdef>
30516   <paramdef>union hdmi_infoframe * <parameter>frame</parameter></paramdef>
30517   <paramdef>void * <parameter>buffer</parameter></paramdef>
30518  </funcprototype></funcsynopsis>
30519</refsynopsisdiv>
30520<refsect1>
30521 <title>Arguments</title>
30522 <variablelist>
30523  <varlistentry>
30524   <term><parameter>frame</parameter></term>
30525   <listitem>
30526    <para>
30527     HDMI infoframe
30528    </para>
30529   </listitem>
30530  </varlistentry>
30531  <varlistentry>
30532   <term><parameter>buffer</parameter></term>
30533   <listitem>
30534    <para>
30535     source buffer
30536    </para>
30537   </listitem>
30538  </varlistentry>
30539 </variablelist>
30540</refsect1>
30541<refsect1>
30542<title>Description</title>
30543<para>
30544   Unpacks the information contained in binary buffer <parameter>buffer</parameter> into a structured
30545   <parameter>frame</parameter> of a HDMI infoframe.
30546   Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
30547   specification.
30548   </para><para>
30549
30550   Returns 0 on success or a negative error code on failure.
30551</para>
30552</refsect1>
30553</refentry>
30554
30555    </sect2>
30556    <sect2>
30557      <title id="drm-kms-planehelpers">Plane Helper Reference</title>
30558<!-- drivers/gpu/drm/drm_plane_helper.c -->
30559<refentry id="API-drm-plane-helper-check-update">
30560<refentryinfo>
30561 <title>LINUX</title>
30562 <productname>Kernel Hackers Manual</productname>
30563 <date>July 2017</date>
30564</refentryinfo>
30565<refmeta>
30566 <refentrytitle><phrase>drm_plane_helper_check_update</phrase></refentrytitle>
30567 <manvolnum>9</manvolnum>
30568 <refmiscinfo class="version">4.1.27</refmiscinfo>
30569</refmeta>
30570<refnamediv>
30571 <refname>drm_plane_helper_check_update</refname>
30572 <refpurpose>
30573  Check plane update for validity
30574 </refpurpose>
30575</refnamediv>
30576<refsynopsisdiv>
30577 <title>Synopsis</title>
30578  <funcsynopsis><funcprototype>
30579   <funcdef>int <function>drm_plane_helper_check_update </function></funcdef>
30580   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
30581   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
30582   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
30583   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
30584   <paramdef>struct drm_rect * <parameter>dest</parameter></paramdef>
30585   <paramdef>const struct drm_rect * <parameter>clip</parameter></paramdef>
30586   <paramdef>int <parameter>min_scale</parameter></paramdef>
30587   <paramdef>int <parameter>max_scale</parameter></paramdef>
30588   <paramdef>bool <parameter>can_position</parameter></paramdef>
30589   <paramdef>bool <parameter>can_update_disabled</parameter></paramdef>
30590   <paramdef>bool * <parameter>visible</parameter></paramdef>
30591  </funcprototype></funcsynopsis>
30592</refsynopsisdiv>
30593<refsect1>
30594 <title>Arguments</title>
30595 <variablelist>
30596  <varlistentry>
30597   <term><parameter>plane</parameter></term>
30598   <listitem>
30599    <para>
30600     plane object to update
30601    </para>
30602   </listitem>
30603  </varlistentry>
30604  <varlistentry>
30605   <term><parameter>crtc</parameter></term>
30606   <listitem>
30607    <para>
30608     owning CRTC of owning plane
30609    </para>
30610   </listitem>
30611  </varlistentry>
30612  <varlistentry>
30613   <term><parameter>fb</parameter></term>
30614   <listitem>
30615    <para>
30616     framebuffer to flip onto plane
30617    </para>
30618   </listitem>
30619  </varlistentry>
30620  <varlistentry>
30621   <term><parameter>src</parameter></term>
30622   <listitem>
30623    <para>
30624     source coordinates in 16.16 fixed point
30625    </para>
30626   </listitem>
30627  </varlistentry>
30628  <varlistentry>
30629   <term><parameter>dest</parameter></term>
30630   <listitem>
30631    <para>
30632     integer destination coordinates
30633    </para>
30634   </listitem>
30635  </varlistentry>
30636  <varlistentry>
30637   <term><parameter>clip</parameter></term>
30638   <listitem>
30639    <para>
30640     integer clipping coordinates
30641    </para>
30642   </listitem>
30643  </varlistentry>
30644  <varlistentry>
30645   <term><parameter>min_scale</parameter></term>
30646   <listitem>
30647    <para>
30648     minimum <parameter>src</parameter>:<parameter>dest</parameter> scaling factor in 16.16 fixed point
30649    </para>
30650   </listitem>
30651  </varlistentry>
30652  <varlistentry>
30653   <term><parameter>max_scale</parameter></term>
30654   <listitem>
30655    <para>
30656     maximum <parameter>src</parameter>:<parameter>dest</parameter> scaling factor in 16.16 fixed point
30657    </para>
30658   </listitem>
30659  </varlistentry>
30660  <varlistentry>
30661   <term><parameter>can_position</parameter></term>
30662   <listitem>
30663    <para>
30664     is it legal to position the plane such that it
30665     doesn't cover the entire crtc?  This will generally
30666     only be false for primary planes.
30667    </para>
30668   </listitem>
30669  </varlistentry>
30670  <varlistentry>
30671   <term><parameter>can_update_disabled</parameter></term>
30672   <listitem>
30673    <para>
30674     can the plane be updated while the crtc
30675     is disabled?
30676    </para>
30677   </listitem>
30678  </varlistentry>
30679  <varlistentry>
30680   <term><parameter>visible</parameter></term>
30681   <listitem>
30682    <para>
30683     output parameter indicating whether plane is still visible after
30684     clipping
30685    </para>
30686   </listitem>
30687  </varlistentry>
30688 </variablelist>
30689</refsect1>
30690<refsect1>
30691<title>Description</title>
30692<para>
30693   Checks that a desired plane update is valid.  Drivers that provide
30694   their own plane handling rather than helper-provided implementations may
30695   still wish to call this function to avoid duplication of error checking
30696   code.
30697</para>
30698</refsect1>
30699<refsect1>
30700<title>RETURNS</title>
30701<para>
30702   Zero if update appears valid, error code on failure
30703</para>
30704</refsect1>
30705</refentry>
30706
30707<refentry id="API-drm-primary-helper-update">
30708<refentryinfo>
30709 <title>LINUX</title>
30710 <productname>Kernel Hackers Manual</productname>
30711 <date>July 2017</date>
30712</refentryinfo>
30713<refmeta>
30714 <refentrytitle><phrase>drm_primary_helper_update</phrase></refentrytitle>
30715 <manvolnum>9</manvolnum>
30716 <refmiscinfo class="version">4.1.27</refmiscinfo>
30717</refmeta>
30718<refnamediv>
30719 <refname>drm_primary_helper_update</refname>
30720 <refpurpose>
30721     Helper for primary plane update
30722 </refpurpose>
30723</refnamediv>
30724<refsynopsisdiv>
30725 <title>Synopsis</title>
30726  <funcsynopsis><funcprototype>
30727   <funcdef>int <function>drm_primary_helper_update </function></funcdef>
30728   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
30729   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
30730   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
30731   <paramdef>int <parameter>crtc_x</parameter></paramdef>
30732   <paramdef>int <parameter>crtc_y</parameter></paramdef>
30733   <paramdef>unsigned int <parameter>crtc_w</parameter></paramdef>
30734   <paramdef>unsigned int <parameter>crtc_h</parameter></paramdef>
30735   <paramdef>uint32_t <parameter>src_x</parameter></paramdef>
30736   <paramdef>uint32_t <parameter>src_y</parameter></paramdef>
30737   <paramdef>uint32_t <parameter>src_w</parameter></paramdef>
30738   <paramdef>uint32_t <parameter>src_h</parameter></paramdef>
30739  </funcprototype></funcsynopsis>
30740</refsynopsisdiv>
30741<refsect1>
30742 <title>Arguments</title>
30743 <variablelist>
30744  <varlistentry>
30745   <term><parameter>plane</parameter></term>
30746   <listitem>
30747    <para>
30748     plane object to update
30749    </para>
30750   </listitem>
30751  </varlistentry>
30752  <varlistentry>
30753   <term><parameter>crtc</parameter></term>
30754   <listitem>
30755    <para>
30756     owning CRTC of owning plane
30757    </para>
30758   </listitem>
30759  </varlistentry>
30760  <varlistentry>
30761   <term><parameter>fb</parameter></term>
30762   <listitem>
30763    <para>
30764     framebuffer to flip onto plane
30765    </para>
30766   </listitem>
30767  </varlistentry>
30768  <varlistentry>
30769   <term><parameter>crtc_x</parameter></term>
30770   <listitem>
30771    <para>
30772     x offset of primary plane on crtc
30773    </para>
30774   </listitem>
30775  </varlistentry>
30776  <varlistentry>
30777   <term><parameter>crtc_y</parameter></term>
30778   <listitem>
30779    <para>
30780     y offset of primary plane on crtc
30781    </para>
30782   </listitem>
30783  </varlistentry>
30784  <varlistentry>
30785   <term><parameter>crtc_w</parameter></term>
30786   <listitem>
30787    <para>
30788     width of primary plane rectangle on crtc
30789    </para>
30790   </listitem>
30791  </varlistentry>
30792  <varlistentry>
30793   <term><parameter>crtc_h</parameter></term>
30794   <listitem>
30795    <para>
30796     height of primary plane rectangle on crtc
30797    </para>
30798   </listitem>
30799  </varlistentry>
30800  <varlistentry>
30801   <term><parameter>src_x</parameter></term>
30802   <listitem>
30803    <para>
30804     x offset of <parameter>fb</parameter> for panning
30805    </para>
30806   </listitem>
30807  </varlistentry>
30808  <varlistentry>
30809   <term><parameter>src_y</parameter></term>
30810   <listitem>
30811    <para>
30812     y offset of <parameter>fb</parameter> for panning
30813    </para>
30814   </listitem>
30815  </varlistentry>
30816  <varlistentry>
30817   <term><parameter>src_w</parameter></term>
30818   <listitem>
30819    <para>
30820     width of source rectangle in <parameter>fb</parameter>
30821    </para>
30822   </listitem>
30823  </varlistentry>
30824  <varlistentry>
30825   <term><parameter>src_h</parameter></term>
30826   <listitem>
30827    <para>
30828     height of source rectangle in <parameter>fb</parameter>
30829    </para>
30830   </listitem>
30831  </varlistentry>
30832 </variablelist>
30833</refsect1>
30834<refsect1>
30835<title>Description</title>
30836<para>
30837   Provides a default plane update handler for primary planes.  This is handler
30838   is called in response to a userspace SetPlane operation on the plane with a
30839   non-NULL framebuffer.  We call the driver's modeset handler to update the
30840   framebuffer.
30841   </para><para>
30842
30843   <function>SetPlane</function> on a primary plane of a disabled CRTC is not supported, and will
30844   return an error.
30845   </para><para>
30846
30847   Note that we make some assumptions about hardware limitations that may not be
30848   true for all hardware --
30849   1) Primary plane cannot be repositioned.
30850   2) Primary plane cannot be scaled.
30851   3) Primary plane must cover the entire CRTC.
30852   4) Subpixel positioning is not supported.
30853   Drivers for hardware that don't have these restrictions can provide their
30854   own implementation rather than using this helper.
30855</para>
30856</refsect1>
30857<refsect1>
30858<title>RETURNS</title>
30859<para>
30860   Zero on success, error code on failure
30861</para>
30862</refsect1>
30863</refentry>
30864
30865<refentry id="API-drm-primary-helper-disable">
30866<refentryinfo>
30867 <title>LINUX</title>
30868 <productname>Kernel Hackers Manual</productname>
30869 <date>July 2017</date>
30870</refentryinfo>
30871<refmeta>
30872 <refentrytitle><phrase>drm_primary_helper_disable</phrase></refentrytitle>
30873 <manvolnum>9</manvolnum>
30874 <refmiscinfo class="version">4.1.27</refmiscinfo>
30875</refmeta>
30876<refnamediv>
30877 <refname>drm_primary_helper_disable</refname>
30878 <refpurpose>
30879     Helper for primary plane disable
30880 </refpurpose>
30881</refnamediv>
30882<refsynopsisdiv>
30883 <title>Synopsis</title>
30884  <funcsynopsis><funcprototype>
30885   <funcdef>int <function>drm_primary_helper_disable </function></funcdef>
30886   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
30887  </funcprototype></funcsynopsis>
30888</refsynopsisdiv>
30889<refsect1>
30890 <title>Arguments</title>
30891 <variablelist>
30892  <varlistentry>
30893   <term><parameter>plane</parameter></term>
30894   <listitem>
30895    <para>
30896     plane to disable
30897    </para>
30898   </listitem>
30899  </varlistentry>
30900 </variablelist>
30901</refsect1>
30902<refsect1>
30903<title>Description</title>
30904<para>
30905   Provides a default plane disable handler for primary planes.  This is handler
30906   is called in response to a userspace SetPlane operation on the plane with a
30907   NULL framebuffer parameter.  It unconditionally fails the disable call with
30908   -EINVAL the only way to disable the primary plane without driver support is
30909   to disable the entier CRTC. Which does not match the plane -&gt;disable hook.
30910   </para><para>
30911
30912   Note that some hardware may be able to disable the primary plane without
30913   disabling the whole CRTC.  Drivers for such hardware should provide their
30914   own disable handler that disables just the primary plane (and they'll likely
30915   need to provide their own update handler as well to properly re-enable a
30916   disabled primary plane).
30917</para>
30918</refsect1>
30919<refsect1>
30920<title>RETURNS</title>
30921<para>
30922   Unconditionally returns -EINVAL.
30923</para>
30924</refsect1>
30925</refentry>
30926
30927<refentry id="API-drm-primary-helper-destroy">
30928<refentryinfo>
30929 <title>LINUX</title>
30930 <productname>Kernel Hackers Manual</productname>
30931 <date>July 2017</date>
30932</refentryinfo>
30933<refmeta>
30934 <refentrytitle><phrase>drm_primary_helper_destroy</phrase></refentrytitle>
30935 <manvolnum>9</manvolnum>
30936 <refmiscinfo class="version">4.1.27</refmiscinfo>
30937</refmeta>
30938<refnamediv>
30939 <refname>drm_primary_helper_destroy</refname>
30940 <refpurpose>
30941     Helper for primary plane destruction
30942 </refpurpose>
30943</refnamediv>
30944<refsynopsisdiv>
30945 <title>Synopsis</title>
30946  <funcsynopsis><funcprototype>
30947   <funcdef>void <function>drm_primary_helper_destroy </function></funcdef>
30948   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
30949  </funcprototype></funcsynopsis>
30950</refsynopsisdiv>
30951<refsect1>
30952 <title>Arguments</title>
30953 <variablelist>
30954  <varlistentry>
30955   <term><parameter>plane</parameter></term>
30956   <listitem>
30957    <para>
30958     plane to destroy
30959    </para>
30960   </listitem>
30961  </varlistentry>
30962 </variablelist>
30963</refsect1>
30964<refsect1>
30965<title>Description</title>
30966<para>
30967   Provides a default plane destroy handler for primary planes.  This handler
30968   is called during CRTC destruction.  We disable the primary plane, remove
30969   it from the DRM plane list, and deallocate the plane structure.
30970</para>
30971</refsect1>
30972</refentry>
30973
30974<refentry id="API-drm-crtc-init">
30975<refentryinfo>
30976 <title>LINUX</title>
30977 <productname>Kernel Hackers Manual</productname>
30978 <date>July 2017</date>
30979</refentryinfo>
30980<refmeta>
30981 <refentrytitle><phrase>drm_crtc_init</phrase></refentrytitle>
30982 <manvolnum>9</manvolnum>
30983 <refmiscinfo class="version">4.1.27</refmiscinfo>
30984</refmeta>
30985<refnamediv>
30986 <refname>drm_crtc_init</refname>
30987 <refpurpose>
30988     Legacy CRTC initialization function
30989 </refpurpose>
30990</refnamediv>
30991<refsynopsisdiv>
30992 <title>Synopsis</title>
30993  <funcsynopsis><funcprototype>
30994   <funcdef>int <function>drm_crtc_init </function></funcdef>
30995   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
30996   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
30997   <paramdef>const struct drm_crtc_funcs * <parameter>funcs</parameter></paramdef>
30998  </funcprototype></funcsynopsis>
30999</refsynopsisdiv>
31000<refsect1>
31001 <title>Arguments</title>
31002 <variablelist>
31003  <varlistentry>
31004   <term><parameter>dev</parameter></term>
31005   <listitem>
31006    <para>
31007     DRM device
31008    </para>
31009   </listitem>
31010  </varlistentry>
31011  <varlistentry>
31012   <term><parameter>crtc</parameter></term>
31013   <listitem>
31014    <para>
31015     CRTC object to init
31016    </para>
31017   </listitem>
31018  </varlistentry>
31019  <varlistentry>
31020   <term><parameter>funcs</parameter></term>
31021   <listitem>
31022    <para>
31023     callbacks for the new CRTC
31024    </para>
31025   </listitem>
31026  </varlistentry>
31027 </variablelist>
31028</refsect1>
31029<refsect1>
31030<title>Description</title>
31031<para>
31032   Initialize a CRTC object with a default helper-provided primary plane and no
31033   cursor plane.
31034</para>
31035</refsect1>
31036<refsect1>
31037<title>Returns</title>
31038<para>
31039   Zero on success, error code on failure.
31040</para>
31041</refsect1>
31042</refentry>
31043
31044<refentry id="API-drm-plane-helper-update">
31045<refentryinfo>
31046 <title>LINUX</title>
31047 <productname>Kernel Hackers Manual</productname>
31048 <date>July 2017</date>
31049</refentryinfo>
31050<refmeta>
31051 <refentrytitle><phrase>drm_plane_helper_update</phrase></refentrytitle>
31052 <manvolnum>9</manvolnum>
31053 <refmiscinfo class="version">4.1.27</refmiscinfo>
31054</refmeta>
31055<refnamediv>
31056 <refname>drm_plane_helper_update</refname>
31057 <refpurpose>
31058     Transitional helper for plane update
31059 </refpurpose>
31060</refnamediv>
31061<refsynopsisdiv>
31062 <title>Synopsis</title>
31063  <funcsynopsis><funcprototype>
31064   <funcdef>int <function>drm_plane_helper_update </function></funcdef>
31065   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
31066   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
31067   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
31068   <paramdef>int <parameter>crtc_x</parameter></paramdef>
31069   <paramdef>int <parameter>crtc_y</parameter></paramdef>
31070   <paramdef>unsigned int <parameter>crtc_w</parameter></paramdef>
31071   <paramdef>unsigned int <parameter>crtc_h</parameter></paramdef>
31072   <paramdef>uint32_t <parameter>src_x</parameter></paramdef>
31073   <paramdef>uint32_t <parameter>src_y</parameter></paramdef>
31074   <paramdef>uint32_t <parameter>src_w</parameter></paramdef>
31075   <paramdef>uint32_t <parameter>src_h</parameter></paramdef>
31076  </funcprototype></funcsynopsis>
31077</refsynopsisdiv>
31078<refsect1>
31079 <title>Arguments</title>
31080 <variablelist>
31081  <varlistentry>
31082   <term><parameter>plane</parameter></term>
31083   <listitem>
31084    <para>
31085     plane object to update
31086    </para>
31087   </listitem>
31088  </varlistentry>
31089  <varlistentry>
31090   <term><parameter>crtc</parameter></term>
31091   <listitem>
31092    <para>
31093     owning CRTC of owning plane
31094    </para>
31095   </listitem>
31096  </varlistentry>
31097  <varlistentry>
31098   <term><parameter>fb</parameter></term>
31099   <listitem>
31100    <para>
31101     framebuffer to flip onto plane
31102    </para>
31103   </listitem>
31104  </varlistentry>
31105  <varlistentry>
31106   <term><parameter>crtc_x</parameter></term>
31107   <listitem>
31108    <para>
31109     x offset of primary plane on crtc
31110    </para>
31111   </listitem>
31112  </varlistentry>
31113  <varlistentry>
31114   <term><parameter>crtc_y</parameter></term>
31115   <listitem>
31116    <para>
31117     y offset of primary plane on crtc
31118    </para>
31119   </listitem>
31120  </varlistentry>
31121  <varlistentry>
31122   <term><parameter>crtc_w</parameter></term>
31123   <listitem>
31124    <para>
31125     width of primary plane rectangle on crtc
31126    </para>
31127   </listitem>
31128  </varlistentry>
31129  <varlistentry>
31130   <term><parameter>crtc_h</parameter></term>
31131   <listitem>
31132    <para>
31133     height of primary plane rectangle on crtc
31134    </para>
31135   </listitem>
31136  </varlistentry>
31137  <varlistentry>
31138   <term><parameter>src_x</parameter></term>
31139   <listitem>
31140    <para>
31141     x offset of <parameter>fb</parameter> for panning
31142    </para>
31143   </listitem>
31144  </varlistentry>
31145  <varlistentry>
31146   <term><parameter>src_y</parameter></term>
31147   <listitem>
31148    <para>
31149     y offset of <parameter>fb</parameter> for panning
31150    </para>
31151   </listitem>
31152  </varlistentry>
31153  <varlistentry>
31154   <term><parameter>src_w</parameter></term>
31155   <listitem>
31156    <para>
31157     width of source rectangle in <parameter>fb</parameter>
31158    </para>
31159   </listitem>
31160  </varlistentry>
31161  <varlistentry>
31162   <term><parameter>src_h</parameter></term>
31163   <listitem>
31164    <para>
31165     height of source rectangle in <parameter>fb</parameter>
31166    </para>
31167   </listitem>
31168  </varlistentry>
31169 </variablelist>
31170</refsect1>
31171<refsect1>
31172<title>Description</title>
31173<para>
31174   Provides a default plane update handler using the atomic plane update
31175   functions. It is fully left to the driver to check plane constraints and
31176   handle corner-cases like a fully occluded or otherwise invisible plane.
31177   </para><para>
31178
31179   This is useful for piecewise transitioning of a driver to the atomic helpers.
31180</para>
31181</refsect1>
31182<refsect1>
31183<title>RETURNS</title>
31184<para>
31185   Zero on success, error code on failure
31186</para>
31187</refsect1>
31188</refentry>
31189
31190<refentry id="API-drm-plane-helper-disable">
31191<refentryinfo>
31192 <title>LINUX</title>
31193 <productname>Kernel Hackers Manual</productname>
31194 <date>July 2017</date>
31195</refentryinfo>
31196<refmeta>
31197 <refentrytitle><phrase>drm_plane_helper_disable</phrase></refentrytitle>
31198 <manvolnum>9</manvolnum>
31199 <refmiscinfo class="version">4.1.27</refmiscinfo>
31200</refmeta>
31201<refnamediv>
31202 <refname>drm_plane_helper_disable</refname>
31203 <refpurpose>
31204     Transitional helper for plane disable
31205 </refpurpose>
31206</refnamediv>
31207<refsynopsisdiv>
31208 <title>Synopsis</title>
31209  <funcsynopsis><funcprototype>
31210   <funcdef>int <function>drm_plane_helper_disable </function></funcdef>
31211   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
31212  </funcprototype></funcsynopsis>
31213</refsynopsisdiv>
31214<refsect1>
31215 <title>Arguments</title>
31216 <variablelist>
31217  <varlistentry>
31218   <term><parameter>plane</parameter></term>
31219   <listitem>
31220    <para>
31221     plane to disable
31222    </para>
31223   </listitem>
31224  </varlistentry>
31225 </variablelist>
31226</refsect1>
31227<refsect1>
31228<title>Description</title>
31229<para>
31230   Provides a default plane disable handler using the atomic plane update
31231   functions. It is fully left to the driver to check plane constraints and
31232   handle corner-cases like a fully occluded or otherwise invisible plane.
31233   </para><para>
31234
31235   This is useful for piecewise transitioning of a driver to the atomic helpers.
31236</para>
31237</refsect1>
31238<refsect1>
31239<title>RETURNS</title>
31240<para>
31241   Zero on success, error code on failure
31242</para>
31243</refsect1>
31244</refentry>
31245
31246<para>
31247   </para><para>
31248   This helper library has two parts. The first part has support to implement
31249   primary plane support on top of the normal CRTC configuration interface.
31250   Since the legacy -&gt;set_config interface ties the primary plane together with
31251   the CRTC state this does not allow userspace to disable the primary plane
31252   itself.  To avoid too much duplicated code use
31253   <function>drm_plane_helper_check_update</function> which can be used to enforce the same
31254   restrictions as primary planes had thus. The default primary plane only
31255   expose XRBG8888 and ARGB8888 as valid pixel formats for the attached
31256   framebuffer.
31257   </para><para>
31258   Drivers are highly recommended to implement proper support for primary
31259   planes, and newly merged drivers must not rely upon these transitional
31260   helpers.
31261   </para><para>
31262   The second part also implements transitional helpers which allow drivers to
31263   gradually switch to the atomic helper infrastructure for plane updates. Once
31264   that switch is complete drivers shouldn't use these any longer, instead using
31265   the proper legacy implementations for update and disable plane hooks provided
31266   by the atomic helpers.
31267   </para><para>
31268   Again drivers are strongly urged to switch to the new interfaces.
31269</para>
31270
31271    </sect2>
31272    <sect2>
31273	  <title>Tile group</title>
31274<para>
31275   </para><para>
31276   Tile groups are used to represent tiled monitors with a unique
31277   integer identifier. Tiled monitors using DisplayID v1.3 have
31278   a unique 8-byte handle, we store this in a tile group, so we
31279   have a common identifier for all tiles in a monitor group.
31280</para>
31281
31282    </sect2>
31283  </sect1>
31284
31285  <!-- Internals: kms properties -->
31286
31287  <sect1 id="drm-kms-properties">
31288    <title>KMS Properties</title>
31289    <para>
31290      Drivers may need to expose additional parameters to applications than
31291      those described in the previous sections. KMS supports attaching
31292      properties to CRTCs, connectors and planes and offers a userspace API to
31293      list, get and set the property values.
31294    </para>
31295    <para>
31296      Properties are identified by a name that uniquely defines the property
31297      purpose, and store an associated value. For all property types except blob
31298      properties the value is a 64-bit unsigned integer.
31299    </para>
31300    <para>
31301      KMS differentiates between properties and property instances. Drivers
31302      first create properties and then create and associate individual instances
31303      of those properties to objects. A property can be instantiated multiple
31304      times and associated with different objects. Values are stored in property
31305      instances, and all other property information are stored in the property
31306      and shared between all instances of the property.
31307    </para>
31308    <para>
31309      Every property is created with a type that influences how the KMS core
31310      handles the property. Supported property types are
31311      <variablelist>
31312        <varlistentry>
31313          <term>DRM_MODE_PROP_RANGE</term>
31314          <listitem><para>Range properties report their minimum and maximum
31315            admissible values. The KMS core verifies that values set by
31316            application fit in that range.</para></listitem>
31317        </varlistentry>
31318        <varlistentry>
31319          <term>DRM_MODE_PROP_ENUM</term>
31320          <listitem><para>Enumerated properties take a numerical value that
31321            ranges from 0 to the number of enumerated values defined by the
31322            property minus one, and associate a free-formed string name to each
31323            value. Applications can retrieve the list of defined value-name pairs
31324            and use the numerical value to get and set property instance values.
31325            </para></listitem>
31326        </varlistentry>
31327        <varlistentry>
31328          <term>DRM_MODE_PROP_BITMASK</term>
31329          <listitem><para>Bitmask properties are enumeration properties that
31330            additionally restrict all enumerated values to the 0..63 range.
31331            Bitmask property instance values combine one or more of the
31332            enumerated bits defined by the property.</para></listitem>
31333        </varlistentry>
31334        <varlistentry>
31335          <term>DRM_MODE_PROP_BLOB</term>
31336          <listitem><para>Blob properties store a binary blob without any format
31337            restriction. The binary blobs are created as KMS standalone objects,
31338            and blob property instance values store the ID of their associated
31339            blob object.</para>
31340	    <para>Blob properties are only used for the connector EDID property
31341	    and cannot be created by drivers.</para></listitem>
31342        </varlistentry>
31343      </variablelist>
31344    </para>
31345    <para>
31346      To create a property drivers call one of the following functions depending
31347      on the property type. All property creation functions take property flags
31348      and name, as well as type-specific arguments.
31349      <itemizedlist>
31350        <listitem>
31351          <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
31352                                               const char *name,
31353                                               uint64_t min, uint64_t max);</synopsis>
31354          <para>Create a range property with the given minimum and maximum
31355            values.</para>
31356        </listitem>
31357        <listitem>
31358          <synopsis>struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
31359                                              const char *name,
31360                                              const struct drm_prop_enum_list *props,
31361                                              int num_values);</synopsis>
31362          <para>Create an enumerated property. The <parameter>props</parameter>
31363            argument points to an array of <parameter>num_values</parameter>
31364            value-name pairs.</para>
31365        </listitem>
31366        <listitem>
31367          <synopsis>struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
31368                                                 int flags, const char *name,
31369                                                 const struct drm_prop_enum_list *props,
31370                                                 int num_values);</synopsis>
31371          <para>Create a bitmask property. The <parameter>props</parameter>
31372            argument points to an array of <parameter>num_values</parameter>
31373            value-name pairs.</para>
31374        </listitem>
31375      </itemizedlist>
31376    </para>
31377    <para>
31378      Properties can additionally be created as immutable, in which case they
31379      will be read-only for applications but can be modified by the driver. To
31380      create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE
31381      flag at property creation time.
31382    </para>
31383    <para>
31384      When no array of value-name pairs is readily available at property
31385      creation time for enumerated or range properties, drivers can create
31386      the property using the <function>drm_property_create</function> function
31387      and manually add enumeration value-name pairs by calling the
31388      <function>drm_property_add_enum</function> function. Care must be taken to
31389      properly specify the property type through the <parameter>flags</parameter>
31390      argument.
31391    </para>
31392    <para>
31393      After creating properties drivers can attach property instances to CRTC,
31394      connector and plane objects by calling the
31395      <function>drm_object_attach_property</function>. The function takes a
31396      pointer to the target object, a pointer to the previously created property
31397      and an initial instance value.
31398    </para>
31399    <sect2>
31400	<title>Existing KMS Properties</title>
31401	<para>
31402	The following table gives description of drm properties exposed by various
31403	modules/drivers.
31404	</para>
31405	<table border="1" cellpadding="0" cellspacing="0">
31406	<tbody>
31407	<tr style="font-weight: bold;">
31408	<td valign="top" >Owner Module/Drivers</td>
31409	<td valign="top" >Group</td>
31410	<td valign="top" >Property Name</td>
31411	<td valign="top" >Type</td>
31412	<td valign="top" >Property Values</td>
31413	<td valign="top" >Object attached</td>
31414	<td valign="top" >Description/Restrictions</td>
31415	</tr>
31416	<tr>
31417	<td rowspan="36" valign="top" >DRM</td>
31418	<td rowspan="5" valign="top" >Connector</td>
31419	<td valign="top" >“EDID”</td>
31420	<td valign="top" >BLOB | IMMUTABLE</td>
31421	<td valign="top" >0</td>
31422	<td valign="top" >Connector</td>
31423	<td valign="top" >Contains id of edid blob ptr object.</td>
31424	</tr>
31425	<tr>
31426	<td valign="top" >“DPMS”</td>
31427	<td valign="top" >ENUM</td>
31428	<td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td>
31429	<td valign="top" >Connector</td>
31430	<td valign="top" >Contains DPMS operation mode value.</td>
31431	</tr>
31432	<tr>
31433	<td valign="top" >“PATH”</td>
31434	<td valign="top" >BLOB | IMMUTABLE</td>
31435	<td valign="top" >0</td>
31436	<td valign="top" >Connector</td>
31437	<td valign="top" >Contains topology path to a connector.</td>
31438	</tr>
31439	<tr>
31440	<td valign="top" >“TILE”</td>
31441	<td valign="top" >BLOB | IMMUTABLE</td>
31442	<td valign="top" >0</td>
31443	<td valign="top" >Connector</td>
31444	<td valign="top" >Contains tiling information for a connector.</td>
31445	</tr>
31446	<tr>
31447	<td valign="top" >“CRTC_ID”</td>
31448	<td valign="top" >OBJECT</td>
31449	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
31450	<td valign="top" >Connector</td>
31451	<td valign="top" >CRTC that connector is attached to (atomic)</td>
31452	</tr>
31453	<tr>
31454	<td rowspan="11" valign="top" >Plane</td>
31455	<td valign="top" >“type”</td>
31456	<td valign="top" >ENUM | IMMUTABLE</td>
31457	<td valign="top" >{ "Overlay", "Primary", "Cursor" }</td>
31458	<td valign="top" >Plane</td>
31459	<td valign="top" >Plane type</td>
31460	</tr>
31461	<tr>
31462	<td valign="top" >“SRC_X”</td>
31463	<td valign="top" >RANGE</td>
31464	<td valign="top" >Min=0, Max=UINT_MAX</td>
31465	<td valign="top" >Plane</td>
31466	<td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td>
31467	</tr>
31468	<tr>
31469	<td valign="top" >“SRC_Y”</td>
31470	<td valign="top" >RANGE</td>
31471	<td valign="top" >Min=0, Max=UINT_MAX</td>
31472	<td valign="top" >Plane</td>
31473	<td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td>
31474	</tr>
31475	<tr>
31476	<td valign="top" >“SRC_W”</td>
31477	<td valign="top" >RANGE</td>
31478	<td valign="top" >Min=0, Max=UINT_MAX</td>
31479	<td valign="top" >Plane</td>
31480	<td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td>
31481	</tr>
31482	<tr>
31483	<td valign="top" >“SRC_H”</td>
31484	<td valign="top" >RANGE</td>
31485	<td valign="top" >Min=0, Max=UINT_MAX</td>
31486	<td valign="top" >Plane</td>
31487	<td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td>
31488	</tr>
31489	<tr>
31490	<td valign="top" >“CRTC_X”</td>
31491	<td valign="top" >SIGNED_RANGE</td>
31492	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
31493	<td valign="top" >Plane</td>
31494	<td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td>
31495	</tr>
31496	<tr>
31497	<td valign="top" >“CRTC_Y”</td>
31498	<td valign="top" >SIGNED_RANGE</td>
31499	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
31500	<td valign="top" >Plane</td>
31501	<td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td>
31502	</tr>
31503	<tr>
31504	<td valign="top" >“CRTC_W”</td>
31505	<td valign="top" >RANGE</td>
31506	<td valign="top" >Min=0, Max=UINT_MAX</td>
31507	<td valign="top" >Plane</td>
31508	<td valign="top" >Scanout CRTC (destination) width (atomic)</td>
31509	</tr>
31510	<tr>
31511	<td valign="top" >“CRTC_H”</td>
31512	<td valign="top" >RANGE</td>
31513	<td valign="top" >Min=0, Max=UINT_MAX</td>
31514	<td valign="top" >Plane</td>
31515	<td valign="top" >Scanout CRTC (destination) height (atomic)</td>
31516	</tr>
31517	<tr>
31518	<td valign="top" >“FB_ID”</td>
31519	<td valign="top" >OBJECT</td>
31520	<td valign="top" >DRM_MODE_OBJECT_FB</td>
31521	<td valign="top" >Plane</td>
31522	<td valign="top" >Scanout framebuffer (atomic)</td>
31523	</tr>
31524	<tr>
31525	<td valign="top" >“CRTC_ID”</td>
31526	<td valign="top" >OBJECT</td>
31527	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
31528	<td valign="top" >Plane</td>
31529	<td valign="top" >CRTC that plane is attached to (atomic)</td>
31530	</tr>
31531	<tr>
31532	<td rowspan="2" valign="top" >DVI-I</td>
31533	<td valign="top" >“subconnector”</td>
31534	<td valign="top" >ENUM</td>
31535	<td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td>
31536	<td valign="top" >Connector</td>
31537	<td valign="top" >TBD</td>
31538	</tr>
31539	<tr>
31540	<td valign="top" >“select subconnector”</td>
31541	<td valign="top" >ENUM</td>
31542	<td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td>
31543	<td valign="top" >Connector</td>
31544	<td valign="top" >TBD</td>
31545	</tr>
31546	<tr>
31547	<td rowspan="13" valign="top" >TV</td>
31548	<td valign="top" >“subconnector”</td>
31549	<td valign="top" >ENUM</td>
31550	<td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td>
31551	<td valign="top" >Connector</td>
31552	<td valign="top" >TBD</td>
31553	</tr>
31554	<tr>
31555	<td valign="top" >“select subconnector”</td>
31556	<td valign="top" >ENUM</td>
31557	<td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td>
31558	<td valign="top" >Connector</td>
31559	<td valign="top" >TBD</td>
31560	</tr>
31561	<tr>
31562	<td valign="top" >“mode”</td>
31563	<td valign="top" >ENUM</td>
31564	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
31565	<td valign="top" >Connector</td>
31566	<td valign="top" >TBD</td>
31567	</tr>
31568	<tr>
31569	<td valign="top" >“left margin”</td>
31570	<td valign="top" >RANGE</td>
31571	<td valign="top" >Min=0, Max=100</td>
31572	<td valign="top" >Connector</td>
31573	<td valign="top" >TBD</td>
31574	</tr>
31575	<tr>
31576	<td valign="top" >“right margin”</td>
31577	<td valign="top" >RANGE</td>
31578	<td valign="top" >Min=0, Max=100</td>
31579	<td valign="top" >Connector</td>
31580	<td valign="top" >TBD</td>
31581	</tr>
31582	<tr>
31583	<td valign="top" >“top margin”</td>
31584	<td valign="top" >RANGE</td>
31585	<td valign="top" >Min=0, Max=100</td>
31586	<td valign="top" >Connector</td>
31587	<td valign="top" >TBD</td>
31588	</tr>
31589	<tr>
31590	<td valign="top" >“bottom margin”</td>
31591	<td valign="top" >RANGE</td>
31592	<td valign="top" >Min=0, Max=100</td>
31593	<td valign="top" >Connector</td>
31594	<td valign="top" >TBD</td>
31595	</tr>
31596	<tr>
31597	<td valign="top" >“brightness”</td>
31598	<td valign="top" >RANGE</td>
31599	<td valign="top" >Min=0, Max=100</td>
31600	<td valign="top" >Connector</td>
31601	<td valign="top" >TBD</td>
31602	</tr>
31603	<tr>
31604	<td valign="top" >“contrast”</td>
31605	<td valign="top" >RANGE</td>
31606	<td valign="top" >Min=0, Max=100</td>
31607	<td valign="top" >Connector</td>
31608	<td valign="top" >TBD</td>
31609	</tr>
31610	<tr>
31611	<td valign="top" >“flicker reduction”</td>
31612	<td valign="top" >RANGE</td>
31613	<td valign="top" >Min=0, Max=100</td>
31614	<td valign="top" >Connector</td>
31615	<td valign="top" >TBD</td>
31616	</tr>
31617	<tr>
31618	<td valign="top" >“overscan”</td>
31619	<td valign="top" >RANGE</td>
31620	<td valign="top" >Min=0, Max=100</td>
31621	<td valign="top" >Connector</td>
31622	<td valign="top" >TBD</td>
31623	</tr>
31624	<tr>
31625	<td valign="top" >“saturation”</td>
31626	<td valign="top" >RANGE</td>
31627	<td valign="top" >Min=0, Max=100</td>
31628	<td valign="top" >Connector</td>
31629	<td valign="top" >TBD</td>
31630	</tr>
31631	<tr>
31632	<td valign="top" >“hue”</td>
31633	<td valign="top" >RANGE</td>
31634	<td valign="top" >Min=0, Max=100</td>
31635	<td valign="top" >Connector</td>
31636	<td valign="top" >TBD</td>
31637	</tr>
31638	<tr>
31639	<td rowspan="2" valign="top" >Virtual GPU</td>
31640	<td valign="top" >“suggested X”</td>
31641	<td valign="top" >RANGE</td>
31642	<td valign="top" >Min=0, Max=0xffffffff</td>
31643	<td valign="top" >Connector</td>
31644	<td valign="top" >property to suggest an X offset for a connector</td>
31645	</tr>
31646	<tr>
31647	<td valign="top" >“suggested Y”</td>
31648	<td valign="top" >RANGE</td>
31649	<td valign="top" >Min=0, Max=0xffffffff</td>
31650	<td valign="top" >Connector</td>
31651	<td valign="top" >property to suggest an Y offset for a connector</td>
31652	</tr>
31653	<tr>
31654	<td rowspan="3" valign="top" >Optional</td>
31655	<td valign="top" >“scaling mode”</td>
31656	<td valign="top" >ENUM</td>
31657	<td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td>
31658	<td valign="top" >Connector</td>
31659	<td valign="top" >TBD</td>
31660	</tr>
31661	<tr>
31662	<td valign="top" >"aspect ratio"</td>
31663	<td valign="top" >ENUM</td>
31664	<td valign="top" >{ "None", "4:3", "16:9" }</td>
31665	<td valign="top" >Connector</td>
31666	<td valign="top" >DRM property to set aspect ratio from user space app.
31667		This enum is made generic to allow addition of custom aspect
31668		ratios.</td>
31669	</tr>
31670	<tr>
31671	<td valign="top" >“dirty”</td>
31672	<td valign="top" >ENUM | IMMUTABLE</td>
31673	<td valign="top" >{ "Off", "On", "Annotate" }</td>
31674	<td valign="top" >Connector</td>
31675	<td valign="top" >TBD</td>
31676	</tr>
31677	<tr>
31678	<td rowspan="21" valign="top" >i915</td>
31679	<td rowspan="2" valign="top" >Generic</td>
31680	<td valign="top" >"Broadcast RGB"</td>
31681	<td valign="top" >ENUM</td>
31682	<td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td>
31683	<td valign="top" >Connector</td>
31684	<td valign="top" >TBD</td>
31685	</tr>
31686	<tr>
31687	<td valign="top" >“audio”</td>
31688	<td valign="top" >ENUM</td>
31689	<td valign="top" >{ "force-dvi", "off", "auto", "on" }</td>
31690	<td valign="top" >Connector</td>
31691	<td valign="top" >TBD</td>
31692	</tr>
31693	<tr>
31694	<td rowspan="1" valign="top" >Plane</td>
31695	<td valign="top" >“rotation”</td>
31696	<td valign="top" >BITMASK</td>
31697	<td valign="top" >{ 0, "rotate-0" }, { 2, "rotate-180" }</td>
31698	<td valign="top" >Plane</td>
31699	<td valign="top" >TBD</td>
31700	</tr>
31701	<tr>
31702	<td rowspan="17" valign="top" >SDVO-TV</td>
31703	<td valign="top" >“mode”</td>
31704	<td valign="top" >ENUM</td>
31705	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
31706	<td valign="top" >Connector</td>
31707	<td valign="top" >TBD</td>
31708	</tr>
31709	<tr>
31710	<td valign="top" >"left_margin"</td>
31711	<td valign="top" >RANGE</td>
31712	<td valign="top" >Min=0, Max= SDVO dependent</td>
31713	<td valign="top" >Connector</td>
31714	<td valign="top" >TBD</td>
31715	</tr>
31716	<tr>
31717	<td valign="top" >"right_margin"</td>
31718	<td valign="top" >RANGE</td>
31719	<td valign="top" >Min=0, Max= SDVO dependent</td>
31720	<td valign="top" >Connector</td>
31721	<td valign="top" >TBD</td>
31722	</tr>
31723	<tr>
31724	<td valign="top" >"top_margin"</td>
31725	<td valign="top" >RANGE</td>
31726	<td valign="top" >Min=0, Max= SDVO dependent</td>
31727	<td valign="top" >Connector</td>
31728	<td valign="top" >TBD</td>
31729	</tr>
31730	<tr>
31731	<td valign="top" >"bottom_margin"</td>
31732	<td valign="top" >RANGE</td>
31733	<td valign="top" >Min=0, Max= SDVO dependent</td>
31734	<td valign="top" >Connector</td>
31735	<td valign="top" >TBD</td>
31736	</tr>
31737	<tr>
31738	<td valign="top" >“hpos”</td>
31739	<td valign="top" >RANGE</td>
31740	<td valign="top" >Min=0, Max= SDVO dependent</td>
31741	<td valign="top" >Connector</td>
31742	<td valign="top" >TBD</td>
31743	</tr>
31744	<tr>
31745	<td valign="top" >“vpos”</td>
31746	<td valign="top" >RANGE</td>
31747	<td valign="top" >Min=0, Max= SDVO dependent</td>
31748	<td valign="top" >Connector</td>
31749	<td valign="top" >TBD</td>
31750	</tr>
31751	<tr>
31752	<td valign="top" >“contrast”</td>
31753	<td valign="top" >RANGE</td>
31754	<td valign="top" >Min=0, Max= SDVO dependent</td>
31755	<td valign="top" >Connector</td>
31756	<td valign="top" >TBD</td>
31757	</tr>
31758	<tr>
31759	<td valign="top" >“saturation”</td>
31760	<td valign="top" >RANGE</td>
31761	<td valign="top" >Min=0, Max= SDVO dependent</td>
31762	<td valign="top" >Connector</td>
31763	<td valign="top" >TBD</td>
31764	</tr>
31765	<tr>
31766	<td valign="top" >“hue”</td>
31767	<td valign="top" >RANGE</td>
31768	<td valign="top" >Min=0, Max= SDVO dependent</td>
31769	<td valign="top" >Connector</td>
31770	<td valign="top" >TBD</td>
31771	</tr>
31772	<tr>
31773	<td valign="top" >“sharpness”</td>
31774	<td valign="top" >RANGE</td>
31775	<td valign="top" >Min=0, Max= SDVO dependent</td>
31776	<td valign="top" >Connector</td>
31777	<td valign="top" >TBD</td>
31778	</tr>
31779	<tr>
31780	<td valign="top" >“flicker_filter”</td>
31781	<td valign="top" >RANGE</td>
31782	<td valign="top" >Min=0, Max= SDVO dependent</td>
31783	<td valign="top" >Connector</td>
31784	<td valign="top" >TBD</td>
31785	</tr>
31786	<tr>
31787	<td valign="top" >“flicker_filter_adaptive”</td>
31788	<td valign="top" >RANGE</td>
31789	<td valign="top" >Min=0, Max= SDVO dependent</td>
31790	<td valign="top" >Connector</td>
31791	<td valign="top" >TBD</td>
31792	</tr>
31793	<tr>
31794	<td valign="top" >“flicker_filter_2d”</td>
31795	<td valign="top" >RANGE</td>
31796	<td valign="top" >Min=0, Max= SDVO dependent</td>
31797	<td valign="top" >Connector</td>
31798	<td valign="top" >TBD</td>
31799	</tr>
31800	<tr>
31801	<td valign="top" >“tv_chroma_filter”</td>
31802	<td valign="top" >RANGE</td>
31803	<td valign="top" >Min=0, Max= SDVO dependent</td>
31804	<td valign="top" >Connector</td>
31805	<td valign="top" >TBD</td>
31806	</tr>
31807	<tr>
31808	<td valign="top" >“tv_luma_filter”</td>
31809	<td valign="top" >RANGE</td>
31810	<td valign="top" >Min=0, Max= SDVO dependent</td>
31811	<td valign="top" >Connector</td>
31812	<td valign="top" >TBD</td>
31813	</tr>
31814	<tr>
31815	<td valign="top" >“dot_crawl”</td>
31816	<td valign="top" >RANGE</td>
31817	<td valign="top" >Min=0, Max=1</td>
31818	<td valign="top" >Connector</td>
31819	<td valign="top" >TBD</td>
31820	</tr>
31821	<tr>
31822	<td valign="top" >SDVO-TV/LVDS</td>
31823	<td valign="top" >“brightness”</td>
31824	<td valign="top" >RANGE</td>
31825	<td valign="top" >Min=0, Max= SDVO dependent</td>
31826	<td valign="top" >Connector</td>
31827	<td valign="top" >TBD</td>
31828	</tr>
31829	<tr>
31830	<td rowspan="2" valign="top" >CDV gma-500</td>
31831	<td rowspan="2" valign="top" >Generic</td>
31832	<td valign="top" >"Broadcast RGB"</td>
31833	<td valign="top" >ENUM</td>
31834	<td valign="top" >{ “Full”, “Limited 16:235” }</td>
31835	<td valign="top" >Connector</td>
31836	<td valign="top" >TBD</td>
31837	</tr>
31838	<tr>
31839	<td valign="top" >"Broadcast RGB"</td>
31840	<td valign="top" >ENUM</td>
31841	<td valign="top" >{ “off”, “auto”, “on” }</td>
31842	<td valign="top" >Connector</td>
31843	<td valign="top" >TBD</td>
31844	</tr>
31845	<tr>
31846	<td rowspan="19" valign="top" >Poulsbo</td>
31847	<td rowspan="1" valign="top" >Generic</td>
31848	<td valign="top" >“backlight”</td>
31849	<td valign="top" >RANGE</td>
31850	<td valign="top" >Min=0, Max=100</td>
31851	<td valign="top" >Connector</td>
31852	<td valign="top" >TBD</td>
31853	</tr>
31854	<tr>
31855	<td rowspan="17" valign="top" >SDVO-TV</td>
31856	<td valign="top" >“mode”</td>
31857	<td valign="top" >ENUM</td>
31858	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
31859	<td valign="top" >Connector</td>
31860	<td valign="top" >TBD</td>
31861	</tr>
31862	<tr>
31863	<td valign="top" >"left_margin"</td>
31864	<td valign="top" >RANGE</td>
31865	<td valign="top" >Min=0, Max= SDVO dependent</td>
31866	<td valign="top" >Connector</td>
31867	<td valign="top" >TBD</td>
31868	</tr>
31869	<tr>
31870	<td valign="top" >"right_margin"</td>
31871	<td valign="top" >RANGE</td>
31872	<td valign="top" >Min=0, Max= SDVO dependent</td>
31873	<td valign="top" >Connector</td>
31874	<td valign="top" >TBD</td>
31875	</tr>
31876	<tr>
31877	<td valign="top" >"top_margin"</td>
31878	<td valign="top" >RANGE</td>
31879	<td valign="top" >Min=0, Max= SDVO dependent</td>
31880	<td valign="top" >Connector</td>
31881	<td valign="top" >TBD</td>
31882	</tr>
31883	<tr>
31884	<td valign="top" >"bottom_margin"</td>
31885	<td valign="top" >RANGE</td>
31886	<td valign="top" >Min=0, Max= SDVO dependent</td>
31887	<td valign="top" >Connector</td>
31888	<td valign="top" >TBD</td>
31889	</tr>
31890	<tr>
31891	<td valign="top" >“hpos”</td>
31892	<td valign="top" >RANGE</td>
31893	<td valign="top" >Min=0, Max= SDVO dependent</td>
31894	<td valign="top" >Connector</td>
31895	<td valign="top" >TBD</td>
31896	</tr>
31897	<tr>
31898	<td valign="top" >“vpos”</td>
31899	<td valign="top" >RANGE</td>
31900	<td valign="top" >Min=0, Max= SDVO dependent</td>
31901	<td valign="top" >Connector</td>
31902	<td valign="top" >TBD</td>
31903	</tr>
31904	<tr>
31905	<td valign="top" >“contrast”</td>
31906	<td valign="top" >RANGE</td>
31907	<td valign="top" >Min=0, Max= SDVO dependent</td>
31908	<td valign="top" >Connector</td>
31909	<td valign="top" >TBD</td>
31910	</tr>
31911	<tr>
31912	<td valign="top" >“saturation”</td>
31913	<td valign="top" >RANGE</td>
31914	<td valign="top" >Min=0, Max= SDVO dependent</td>
31915	<td valign="top" >Connector</td>
31916	<td valign="top" >TBD</td>
31917	</tr>
31918	<tr>
31919	<td valign="top" >“hue”</td>
31920	<td valign="top" >RANGE</td>
31921	<td valign="top" >Min=0, Max= SDVO dependent</td>
31922	<td valign="top" >Connector</td>
31923	<td valign="top" >TBD</td>
31924	</tr>
31925	<tr>
31926	<td valign="top" >“sharpness”</td>
31927	<td valign="top" >RANGE</td>
31928	<td valign="top" >Min=0, Max= SDVO dependent</td>
31929	<td valign="top" >Connector</td>
31930	<td valign="top" >TBD</td>
31931	</tr>
31932	<tr>
31933	<td valign="top" >“flicker_filter”</td>
31934	<td valign="top" >RANGE</td>
31935	<td valign="top" >Min=0, Max= SDVO dependent</td>
31936	<td valign="top" >Connector</td>
31937	<td valign="top" >TBD</td>
31938	</tr>
31939	<tr>
31940	<td valign="top" >“flicker_filter_adaptive”</td>
31941	<td valign="top" >RANGE</td>
31942	<td valign="top" >Min=0, Max= SDVO dependent</td>
31943	<td valign="top" >Connector</td>
31944	<td valign="top" >TBD</td>
31945	</tr>
31946	<tr>
31947	<td valign="top" >“flicker_filter_2d”</td>
31948	<td valign="top" >RANGE</td>
31949	<td valign="top" >Min=0, Max= SDVO dependent</td>
31950	<td valign="top" >Connector</td>
31951	<td valign="top" >TBD</td>
31952	</tr>
31953	<tr>
31954	<td valign="top" >“tv_chroma_filter”</td>
31955	<td valign="top" >RANGE</td>
31956	<td valign="top" >Min=0, Max= SDVO dependent</td>
31957	<td valign="top" >Connector</td>
31958	<td valign="top" >TBD</td>
31959	</tr>
31960	<tr>
31961	<td valign="top" >“tv_luma_filter”</td>
31962	<td valign="top" >RANGE</td>
31963	<td valign="top" >Min=0, Max= SDVO dependent</td>
31964	<td valign="top" >Connector</td>
31965	<td valign="top" >TBD</td>
31966	</tr>
31967	<tr>
31968	<td valign="top" >“dot_crawl”</td>
31969	<td valign="top" >RANGE</td>
31970	<td valign="top" >Min=0, Max=1</td>
31971	<td valign="top" >Connector</td>
31972	<td valign="top" >TBD</td>
31973	</tr>
31974	<tr>
31975	<td valign="top" >SDVO-TV/LVDS</td>
31976	<td valign="top" >“brightness”</td>
31977	<td valign="top" >RANGE</td>
31978	<td valign="top" >Min=0, Max= SDVO dependent</td>
31979	<td valign="top" >Connector</td>
31980	<td valign="top" >TBD</td>
31981	</tr>
31982	<tr>
31983	<td rowspan="11" valign="top" >armada</td>
31984	<td rowspan="2" valign="top" >CRTC</td>
31985	<td valign="top" >"CSC_YUV"</td>
31986	<td valign="top" >ENUM</td>
31987	<td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td>
31988	<td valign="top" >CRTC</td>
31989	<td valign="top" >TBD</td>
31990	</tr>
31991	<tr>
31992	<td valign="top" >"CSC_RGB"</td>
31993	<td valign="top" >ENUM</td>
31994	<td valign="top" >{ "Auto", "Computer system", "Studio" }</td>
31995	<td valign="top" >CRTC</td>
31996	<td valign="top" >TBD</td>
31997	</tr>
31998	<tr>
31999	<td rowspan="9" valign="top" >Overlay</td>
32000	<td valign="top" >"colorkey"</td>
32001	<td valign="top" >RANGE</td>
32002	<td valign="top" >Min=0, Max=0xffffff</td>
32003	<td valign="top" >Plane</td>
32004	<td valign="top" >TBD</td>
32005	</tr>
32006	<tr>
32007	<td valign="top" >"colorkey_min"</td>
32008	<td valign="top" >RANGE</td>
32009	<td valign="top" >Min=0, Max=0xffffff</td>
32010	<td valign="top" >Plane</td>
32011	<td valign="top" >TBD</td>
32012	</tr>
32013	<tr>
32014	<td valign="top" >"colorkey_max"</td>
32015	<td valign="top" >RANGE</td>
32016	<td valign="top" >Min=0, Max=0xffffff</td>
32017	<td valign="top" >Plane</td>
32018	<td valign="top" >TBD</td>
32019	</tr>
32020	<tr>
32021	<td valign="top" >"colorkey_val"</td>
32022	<td valign="top" >RANGE</td>
32023	<td valign="top" >Min=0, Max=0xffffff</td>
32024	<td valign="top" >Plane</td>
32025	<td valign="top" >TBD</td>
32026	</tr>
32027	<tr>
32028	<td valign="top" >"colorkey_alpha"</td>
32029	<td valign="top" >RANGE</td>
32030	<td valign="top" >Min=0, Max=0xffffff</td>
32031	<td valign="top" >Plane</td>
32032	<td valign="top" >TBD</td>
32033	</tr>
32034	<tr>
32035	<td valign="top" >"colorkey_mode"</td>
32036	<td valign="top" >ENUM</td>
32037	<td valign="top" >{ "disabled", "Y component", "U component"
32038	, "V component", "RGB", “R component", "G component", "B component" }</td>
32039	<td valign="top" >Plane</td>
32040	<td valign="top" >TBD</td>
32041	</tr>
32042	<tr>
32043	<td valign="top" >"brightness"</td>
32044	<td valign="top" >RANGE</td>
32045	<td valign="top" >Min=0, Max=256 + 255</td>
32046	<td valign="top" >Plane</td>
32047	<td valign="top" >TBD</td>
32048	</tr>
32049	<tr>
32050	<td valign="top" >"contrast"</td>
32051	<td valign="top" >RANGE</td>
32052	<td valign="top" >Min=0, Max=0x7fff</td>
32053	<td valign="top" >Plane</td>
32054	<td valign="top" >TBD</td>
32055	</tr>
32056	<tr>
32057	<td valign="top" >"saturation"</td>
32058	<td valign="top" >RANGE</td>
32059	<td valign="top" >Min=0, Max=0x7fff</td>
32060	<td valign="top" >Plane</td>
32061	<td valign="top" >TBD</td>
32062	</tr>
32063	<tr>
32064	<td rowspan="2" valign="top" >exynos</td>
32065	<td valign="top" >CRTC</td>
32066	<td valign="top" >“mode”</td>
32067	<td valign="top" >ENUM</td>
32068	<td valign="top" >{ "normal", "blank" }</td>
32069	<td valign="top" >CRTC</td>
32070	<td valign="top" >TBD</td>
32071	</tr>
32072	<tr>
32073	<td valign="top" >Overlay</td>
32074	<td valign="top" >“zpos”</td>
32075	<td valign="top" >RANGE</td>
32076	<td valign="top" >Min=0, Max=MAX_PLANE-1</td>
32077	<td valign="top" >Plane</td>
32078	<td valign="top" >TBD</td>
32079	</tr>
32080	<tr>
32081	<td rowspan="2" valign="top" >i2c/ch7006_drv</td>
32082	<td valign="top" >Generic</td>
32083	<td valign="top" >“scale”</td>
32084	<td valign="top" >RANGE</td>
32085	<td valign="top" >Min=0, Max=2</td>
32086	<td valign="top" >Connector</td>
32087	<td valign="top" >TBD</td>
32088	</tr>
32089	<tr>
32090	<td rowspan="1" valign="top" >TV</td>
32091	<td valign="top" >“mode”</td>
32092	<td valign="top" >ENUM</td>
32093	<td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc"
32094	, "PAL-60", "NTSC-M", "NTSC-J" }</td>
32095	<td valign="top" >Connector</td>
32096	<td valign="top" >TBD</td>
32097	</tr>
32098	<tr>
32099	<td rowspan="15" valign="top" >nouveau</td>
32100	<td rowspan="6" valign="top" >NV10 Overlay</td>
32101	<td valign="top" >"colorkey"</td>
32102	<td valign="top" >RANGE</td>
32103	<td valign="top" >Min=0, Max=0x01ffffff</td>
32104	<td valign="top" >Plane</td>
32105	<td valign="top" >TBD</td>
32106	</tr>
32107	<tr>
32108	<td valign="top" >“contrast”</td>
32109	<td valign="top" >RANGE</td>
32110	<td valign="top" >Min=0, Max=8192-1</td>
32111	<td valign="top" >Plane</td>
32112	<td valign="top" >TBD</td>
32113	</tr>
32114	<tr>
32115	<td valign="top" >“brightness”</td>
32116	<td valign="top" >RANGE</td>
32117	<td valign="top" >Min=0, Max=1024</td>
32118	<td valign="top" >Plane</td>
32119	<td valign="top" >TBD</td>
32120	</tr>
32121	<tr>
32122	<td valign="top" >“hue”</td>
32123	<td valign="top" >RANGE</td>
32124	<td valign="top" >Min=0, Max=359</td>
32125	<td valign="top" >Plane</td>
32126	<td valign="top" >TBD</td>
32127	</tr>
32128	<tr>
32129	<td valign="top" >“saturation”</td>
32130	<td valign="top" >RANGE</td>
32131	<td valign="top" >Min=0, Max=8192-1</td>
32132	<td valign="top" >Plane</td>
32133	<td valign="top" >TBD</td>
32134	</tr>
32135	<tr>
32136	<td valign="top" >“iturbt_709”</td>
32137	<td valign="top" >RANGE</td>
32138	<td valign="top" >Min=0, Max=1</td>
32139	<td valign="top" >Plane</td>
32140	<td valign="top" >TBD</td>
32141	</tr>
32142	<tr>
32143	<td rowspan="2" valign="top" >Nv04 Overlay</td>
32144	<td valign="top" >“colorkey”</td>
32145	<td valign="top" >RANGE</td>
32146	<td valign="top" >Min=0, Max=0x01ffffff</td>
32147	<td valign="top" >Plane</td>
32148	<td valign="top" >TBD</td>
32149	</tr>
32150	<tr>
32151	<td valign="top" >“brightness”</td>
32152	<td valign="top" >RANGE</td>
32153	<td valign="top" >Min=0, Max=1024</td>
32154	<td valign="top" >Plane</td>
32155	<td valign="top" >TBD</td>
32156	</tr>
32157	<tr>
32158	<td rowspan="7" valign="top" >Display</td>
32159	<td valign="top" >“dithering mode”</td>
32160	<td valign="top" >ENUM</td>
32161	<td valign="top" >{ "auto", "off", "on" }</td>
32162	<td valign="top" >Connector</td>
32163	<td valign="top" >TBD</td>
32164	</tr>
32165	<tr>
32166	<td valign="top" >“dithering depth”</td>
32167	<td valign="top" >ENUM</td>
32168	<td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td>
32169	<td valign="top" >Connector</td>
32170	<td valign="top" >TBD</td>
32171	</tr>
32172	<tr>
32173	<td valign="top" >“underscan”</td>
32174	<td valign="top" >ENUM</td>
32175	<td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td>
32176	<td valign="top" >Connector</td>
32177	<td valign="top" >TBD</td>
32178	</tr>
32179	<tr>
32180	<td valign="top" >“underscan hborder”</td>
32181	<td valign="top" >RANGE</td>
32182	<td valign="top" >Min=0, Max=128</td>
32183	<td valign="top" >Connector</td>
32184	<td valign="top" >TBD</td>
32185	</tr>
32186	<tr>
32187	<td valign="top" >“underscan vborder”</td>
32188	<td valign="top" >RANGE</td>
32189	<td valign="top" >Min=0, Max=128</td>
32190	<td valign="top" >Connector</td>
32191	<td valign="top" >TBD</td>
32192	</tr>
32193	<tr>
32194	<td valign="top" >“vibrant hue”</td>
32195	<td valign="top" >RANGE</td>
32196	<td valign="top" >Min=0, Max=180</td>
32197	<td valign="top" >Connector</td>
32198	<td valign="top" >TBD</td>
32199	</tr>
32200	<tr>
32201	<td valign="top" >“color vibrance”</td>
32202	<td valign="top" >RANGE</td>
32203	<td valign="top" >Min=0, Max=200</td>
32204	<td valign="top" >Connector</td>
32205	<td valign="top" >TBD</td>
32206	</tr>
32207	<tr>
32208	<td rowspan="2" valign="top" >omap</td>
32209	<td rowspan="2" valign="top" >Generic</td>
32210	<td valign="top" >“rotation”</td>
32211	<td valign="top" >BITMASK</td>
32212	<td valign="top" >{ 0, "rotate-0" },
32213	{ 1, "rotate-90" },
32214	{ 2, "rotate-180" },
32215	{ 3, "rotate-270" },
32216	{ 4, "reflect-x" },
32217	{ 5, "reflect-y" }</td>
32218	<td valign="top" >CRTC, Plane</td>
32219	<td valign="top" >TBD</td>
32220	</tr>
32221	<tr>
32222	<td valign="top" >“zorder”</td>
32223	<td valign="top" >RANGE</td>
32224	<td valign="top" >Min=0, Max=3</td>
32225	<td valign="top" >CRTC, Plane</td>
32226	<td valign="top" >TBD</td>
32227	</tr>
32228	<tr>
32229	<td valign="top" >qxl</td>
32230	<td valign="top" >Generic</td>
32231	<td valign="top" >“hotplug_mode_update"</td>
32232	<td valign="top" >RANGE</td>
32233	<td valign="top" >Min=0, Max=1</td>
32234	<td valign="top" >Connector</td>
32235	<td valign="top" >TBD</td>
32236	</tr>
32237	<tr>
32238	<td rowspan="9" valign="top" >radeon</td>
32239	<td valign="top" >DVI-I</td>
32240	<td valign="top" >“coherent”</td>
32241	<td valign="top" >RANGE</td>
32242	<td valign="top" >Min=0, Max=1</td>
32243	<td valign="top" >Connector</td>
32244	<td valign="top" >TBD</td>
32245	</tr>
32246	<tr>
32247	<td valign="top" >DAC enable load detect</td>
32248	<td valign="top" >“load detection”</td>
32249	<td valign="top" >RANGE</td>
32250	<td valign="top" >Min=0, Max=1</td>
32251	<td valign="top" >Connector</td>
32252	<td valign="top" >TBD</td>
32253	</tr>
32254	<tr>
32255	<td valign="top" >TV Standard</td>
32256	<td valign="top" >"tv standard"</td>
32257	<td valign="top" >ENUM</td>
32258	<td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j"
32259	, "scart-pal", "pal-cn", "secam" }</td>
32260	<td valign="top" >Connector</td>
32261	<td valign="top" >TBD</td>
32262	</tr>
32263	<tr>
32264	<td valign="top" >legacy TMDS PLL detect</td>
32265	<td valign="top" >"tmds_pll"</td>
32266	<td valign="top" >ENUM</td>
32267	<td valign="top" >{ "driver", "bios" }</td>
32268	<td valign="top" >-</td>
32269	<td valign="top" >TBD</td>
32270	</tr>
32271	<tr>
32272	<td rowspan="3" valign="top" >Underscan</td>
32273	<td valign="top" >"underscan"</td>
32274	<td valign="top" >ENUM</td>
32275	<td valign="top" >{ "off", "on", "auto" }</td>
32276	<td valign="top" >Connector</td>
32277	<td valign="top" >TBD</td>
32278	</tr>
32279	<tr>
32280	<td valign="top" >"underscan hborder"</td>
32281	<td valign="top" >RANGE</td>
32282	<td valign="top" >Min=0, Max=128</td>
32283	<td valign="top" >Connector</td>
32284	<td valign="top" >TBD</td>
32285	</tr>
32286	<tr>
32287	<td valign="top" >"underscan vborder"</td>
32288	<td valign="top" >RANGE</td>
32289	<td valign="top" >Min=0, Max=128</td>
32290	<td valign="top" >Connector</td>
32291	<td valign="top" >TBD</td>
32292	</tr>
32293	<tr>
32294	<td valign="top" >Audio</td>
32295	<td valign="top" >“audio”</td>
32296	<td valign="top" >ENUM</td>
32297	<td valign="top" >{ "off", "on", "auto" }</td>
32298	<td valign="top" >Connector</td>
32299	<td valign="top" >TBD</td>
32300	</tr>
32301	<tr>
32302	<td valign="top" >FMT Dithering</td>
32303	<td valign="top" >“dither”</td>
32304	<td valign="top" >ENUM</td>
32305	<td valign="top" >{ "off", "on" }</td>
32306	<td valign="top" >Connector</td>
32307	<td valign="top" >TBD</td>
32308	</tr>
32309	<tr>
32310	<td rowspan="3" valign="top" >rcar-du</td>
32311	<td rowspan="3" valign="top" >Generic</td>
32312	<td valign="top" >"alpha"</td>
32313	<td valign="top" >RANGE</td>
32314	<td valign="top" >Min=0, Max=255</td>
32315	<td valign="top" >Plane</td>
32316	<td valign="top" >TBD</td>
32317	</tr>
32318	<tr>
32319	<td valign="top" >"colorkey"</td>
32320	<td valign="top" >RANGE</td>
32321	<td valign="top" >Min=0, Max=0x01ffffff</td>
32322	<td valign="top" >Plane</td>
32323	<td valign="top" >TBD</td>
32324	</tr>
32325	<tr>
32326	<td valign="top" >"zpos"</td>
32327	<td valign="top" >RANGE</td>
32328	<td valign="top" >Min=1, Max=7</td>
32329	<td valign="top" >Plane</td>
32330	<td valign="top" >TBD</td>
32331	</tr>
32332	</tbody>
32333	</table>
32334    </sect2>
32335  </sect1>
32336
32337  <!-- Internals: vertical blanking -->
32338
32339  <sect1 id="drm-vertical-blank">
32340    <title>Vertical Blanking</title>
32341    <para>
32342      Vertical blanking plays a major role in graphics rendering. To achieve
32343      tear-free display, users must synchronize page flips and/or rendering to
32344      vertical blanking. The DRM API offers ioctls to perform page flips
32345      synchronized to vertical blanking and wait for vertical blanking.
32346    </para>
32347    <para>
32348      The DRM core handles most of the vertical blanking management logic, which
32349      involves filtering out spurious interrupts, keeping race-free blanking
32350      counters, coping with counter wrap-around and resets and keeping use
32351      counts. It relies on the driver to generate vertical blanking interrupts
32352      and optionally provide a hardware vertical blanking counter. Drivers must
32353      implement the following operations.
32354    </para>
32355    <itemizedlist>
32356      <listitem>
32357        <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc);
32358void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis>
32359        <para>
32360	  Enable or disable vertical blanking interrupts for the given CRTC.
32361	</para>
32362      </listitem>
32363      <listitem>
32364        <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis>
32365        <para>
32366	  Retrieve the value of the vertical blanking counter for the given
32367	  CRTC. If the hardware maintains a vertical blanking counter its value
32368	  should be returned. Otherwise drivers can use the
32369	  <function>drm_vblank_count</function> helper function to handle this
32370	  operation.
32371	</para>
32372      </listitem>
32373    </itemizedlist>
32374    <para>
32375      Drivers must initialize the vertical blanking handling core with a call to
32376      <function>drm_vblank_init</function> in their
32377      <methodname>load</methodname> operation. The function will set the struct
32378      <structname>drm_device</structname>
32379      <structfield>vblank_disable_allowed</structfield> field to 0. This will
32380      keep vertical blanking interrupts enabled permanently until the first mode
32381      set operation, where <structfield>vblank_disable_allowed</structfield> is
32382      set to 1. The reason behind this is not clear. Drivers can set the field
32383      to 1 after <function>calling drm_vblank_init</function> to make vertical
32384      blanking interrupts dynamically managed from the beginning.
32385    </para>
32386    <para>
32387      Vertical blanking interrupts can be enabled by the DRM core or by drivers
32388      themselves (for instance to handle page flipping operations). The DRM core
32389      maintains a vertical blanking use count to ensure that the interrupts are
32390      not disabled while a user still needs them. To increment the use count,
32391      drivers call <function>drm_vblank_get</function>. Upon return vertical
32392      blanking interrupts are guaranteed to be enabled.
32393    </para>
32394    <para>
32395      To decrement the use count drivers call
32396      <function>drm_vblank_put</function>. Only when the use count drops to zero
32397      will the DRM core disable the vertical blanking interrupts after a delay
32398      by scheduling a timer. The delay is accessible through the vblankoffdelay
32399      module parameter or the <varname>drm_vblank_offdelay</varname> global
32400      variable and expressed in milliseconds. Its default value is 5000 ms.
32401      Zero means never disable, and a negative value means disable immediately.
32402      Drivers may override the behaviour by setting the
32403      <structname>drm_device</structname>
32404      <structfield>vblank_disable_immediate</structfield> flag, which when set
32405      causes vblank interrupts to be disabled immediately regardless of the
32406      drm_vblank_offdelay value. The flag should only be set if there's a
32407      properly working hardware vblank counter present.
32408    </para>
32409    <para>
32410      When a vertical blanking interrupt occurs drivers only need to call the
32411      <function>drm_handle_vblank</function> function to account for the
32412      interrupt.
32413    </para>
32414    <para>
32415      Resources allocated by <function>drm_vblank_init</function> must be freed
32416      with a call to <function>drm_vblank_cleanup</function> in the driver
32417      <methodname>unload</methodname> operation handler.
32418    </para>
32419    <sect2>
32420      <title>Vertical Blanking and Interrupt Handling Functions Reference</title>
32421<!-- drivers/gpu/drm/drm_irq.c -->
32422<refentry id="API-drm-vblank-cleanup">
32423<refentryinfo>
32424 <title>LINUX</title>
32425 <productname>Kernel Hackers Manual</productname>
32426 <date>July 2017</date>
32427</refentryinfo>
32428<refmeta>
32429 <refentrytitle><phrase>drm_vblank_cleanup</phrase></refentrytitle>
32430 <manvolnum>9</manvolnum>
32431 <refmiscinfo class="version">4.1.27</refmiscinfo>
32432</refmeta>
32433<refnamediv>
32434 <refname>drm_vblank_cleanup</refname>
32435 <refpurpose>
32436  cleanup vblank support
32437 </refpurpose>
32438</refnamediv>
32439<refsynopsisdiv>
32440 <title>Synopsis</title>
32441  <funcsynopsis><funcprototype>
32442   <funcdef>void <function>drm_vblank_cleanup </function></funcdef>
32443   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
32444  </funcprototype></funcsynopsis>
32445</refsynopsisdiv>
32446<refsect1>
32447 <title>Arguments</title>
32448 <variablelist>
32449  <varlistentry>
32450   <term><parameter>dev</parameter></term>
32451   <listitem>
32452    <para>
32453     DRM device
32454    </para>
32455   </listitem>
32456  </varlistentry>
32457 </variablelist>
32458</refsect1>
32459<refsect1>
32460<title>Description</title>
32461<para>
32462   This function cleans up any resources allocated in drm_vblank_init.
32463</para>
32464</refsect1>
32465</refentry>
32466
32467<refentry id="API-drm-vblank-init">
32468<refentryinfo>
32469 <title>LINUX</title>
32470 <productname>Kernel Hackers Manual</productname>
32471 <date>July 2017</date>
32472</refentryinfo>
32473<refmeta>
32474 <refentrytitle><phrase>drm_vblank_init</phrase></refentrytitle>
32475 <manvolnum>9</manvolnum>
32476 <refmiscinfo class="version">4.1.27</refmiscinfo>
32477</refmeta>
32478<refnamediv>
32479 <refname>drm_vblank_init</refname>
32480 <refpurpose>
32481     initialize vblank support
32482 </refpurpose>
32483</refnamediv>
32484<refsynopsisdiv>
32485 <title>Synopsis</title>
32486  <funcsynopsis><funcprototype>
32487   <funcdef>int <function>drm_vblank_init </function></funcdef>
32488   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
32489   <paramdef>int <parameter>num_crtcs</parameter></paramdef>
32490  </funcprototype></funcsynopsis>
32491</refsynopsisdiv>
32492<refsect1>
32493 <title>Arguments</title>
32494 <variablelist>
32495  <varlistentry>
32496   <term><parameter>dev</parameter></term>
32497   <listitem>
32498    <para>
32499     drm_device
32500    </para>
32501   </listitem>
32502  </varlistentry>
32503  <varlistentry>
32504   <term><parameter>num_crtcs</parameter></term>
32505   <listitem>
32506    <para>
32507     number of crtcs supported by <parameter>dev</parameter>
32508    </para>
32509   </listitem>
32510  </varlistentry>
32511 </variablelist>
32512</refsect1>
32513<refsect1>
32514<title>Description</title>
32515<para>
32516   This function initializes vblank support for <parameter>num_crtcs</parameter> display pipelines.
32517</para>
32518</refsect1>
32519<refsect1>
32520<title>Returns</title>
32521<para>
32522   Zero on success or a negative error code on failure.
32523</para>
32524</refsect1>
32525</refentry>
32526
32527<refentry id="API-drm-irq-install">
32528<refentryinfo>
32529 <title>LINUX</title>
32530 <productname>Kernel Hackers Manual</productname>
32531 <date>July 2017</date>
32532</refentryinfo>
32533<refmeta>
32534 <refentrytitle><phrase>drm_irq_install</phrase></refentrytitle>
32535 <manvolnum>9</manvolnum>
32536 <refmiscinfo class="version">4.1.27</refmiscinfo>
32537</refmeta>
32538<refnamediv>
32539 <refname>drm_irq_install</refname>
32540 <refpurpose>
32541     install IRQ handler
32542 </refpurpose>
32543</refnamediv>
32544<refsynopsisdiv>
32545 <title>Synopsis</title>
32546  <funcsynopsis><funcprototype>
32547   <funcdef>int <function>drm_irq_install </function></funcdef>
32548   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
32549   <paramdef>int <parameter>irq</parameter></paramdef>
32550  </funcprototype></funcsynopsis>
32551</refsynopsisdiv>
32552<refsect1>
32553 <title>Arguments</title>
32554 <variablelist>
32555  <varlistentry>
32556   <term><parameter>dev</parameter></term>
32557   <listitem>
32558    <para>
32559     DRM device
32560    </para>
32561   </listitem>
32562  </varlistentry>
32563  <varlistentry>
32564   <term><parameter>irq</parameter></term>
32565   <listitem>
32566    <para>
32567     IRQ number to install the handler for
32568    </para>
32569   </listitem>
32570  </varlistentry>
32571 </variablelist>
32572</refsect1>
32573<refsect1>
32574<title>Description</title>
32575<para>
32576   Initializes the IRQ related data. Installs the handler, calling the driver
32577   <function>irq_preinstall</function> and <function>irq_postinstall</function> functions before and after the
32578   installation.
32579   </para><para>
32580
32581   This is the simplified helper interface provided for drivers with no special
32582   needs. Drivers which need to install interrupt handlers for multiple
32583   interrupts must instead set drm_device-&gt;irq_enabled to signal the DRM core
32584   that vblank interrupts are available.
32585</para>
32586</refsect1>
32587<refsect1>
32588<title>Returns</title>
32589<para>
32590   Zero on success or a negative error code on failure.
32591</para>
32592</refsect1>
32593</refentry>
32594
32595<refentry id="API-drm-irq-uninstall">
32596<refentryinfo>
32597 <title>LINUX</title>
32598 <productname>Kernel Hackers Manual</productname>
32599 <date>July 2017</date>
32600</refentryinfo>
32601<refmeta>
32602 <refentrytitle><phrase>drm_irq_uninstall</phrase></refentrytitle>
32603 <manvolnum>9</manvolnum>
32604 <refmiscinfo class="version">4.1.27</refmiscinfo>
32605</refmeta>
32606<refnamediv>
32607 <refname>drm_irq_uninstall</refname>
32608 <refpurpose>
32609     uninstall the IRQ handler
32610 </refpurpose>
32611</refnamediv>
32612<refsynopsisdiv>
32613 <title>Synopsis</title>
32614  <funcsynopsis><funcprototype>
32615   <funcdef>int <function>drm_irq_uninstall </function></funcdef>
32616   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
32617  </funcprototype></funcsynopsis>
32618</refsynopsisdiv>
32619<refsect1>
32620 <title>Arguments</title>
32621 <variablelist>
32622  <varlistentry>
32623   <term><parameter>dev</parameter></term>
32624   <listitem>
32625    <para>
32626     DRM device
32627    </para>
32628   </listitem>
32629  </varlistentry>
32630 </variablelist>
32631</refsect1>
32632<refsect1>
32633<title>Description</title>
32634<para>
32635   Calls the driver's <function>irq_uninstall</function> function and unregisters the IRQ handler.
32636   This should only be called by drivers which used <function>drm_irq_install</function> to set up
32637   their interrupt handler. Other drivers must only reset
32638   drm_device-&gt;irq_enabled to false.
32639   </para><para>
32640
32641   Note that for kernel modesetting drivers it is a bug if this function fails.
32642   The sanity checks are only to catch buggy user modesetting drivers which call
32643   the same function through an ioctl.
32644</para>
32645</refsect1>
32646<refsect1>
32647<title>Returns</title>
32648<para>
32649   Zero on success or a negative error code on failure.
32650</para>
32651</refsect1>
32652</refentry>
32653
32654<refentry id="API-drm-calc-timestamping-constants">
32655<refentryinfo>
32656 <title>LINUX</title>
32657 <productname>Kernel Hackers Manual</productname>
32658 <date>July 2017</date>
32659</refentryinfo>
32660<refmeta>
32661 <refentrytitle><phrase>drm_calc_timestamping_constants</phrase></refentrytitle>
32662 <manvolnum>9</manvolnum>
32663 <refmiscinfo class="version">4.1.27</refmiscinfo>
32664</refmeta>
32665<refnamediv>
32666 <refname>drm_calc_timestamping_constants</refname>
32667 <refpurpose>
32668     calculate vblank timestamp constants
32669 </refpurpose>
32670</refnamediv>
32671<refsynopsisdiv>
32672 <title>Synopsis</title>
32673  <funcsynopsis><funcprototype>
32674   <funcdef>void <function>drm_calc_timestamping_constants </function></funcdef>
32675   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
32676   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
32677  </funcprototype></funcsynopsis>
32678</refsynopsisdiv>
32679<refsect1>
32680 <title>Arguments</title>
32681 <variablelist>
32682  <varlistentry>
32683   <term><parameter>crtc</parameter></term>
32684   <listitem>
32685    <para>
32686     drm_crtc whose timestamp constants should be updated.
32687    </para>
32688   </listitem>
32689  </varlistentry>
32690  <varlistentry>
32691   <term><parameter>mode</parameter></term>
32692   <listitem>
32693    <para>
32694     display mode containing the scanout timings
32695    </para>
32696   </listitem>
32697  </varlistentry>
32698 </variablelist>
32699</refsect1>
32700<refsect1>
32701<title>Description</title>
32702<para>
32703   Calculate and store various constants which are later
32704   needed by vblank and swap-completion timestamping, e.g,
32705   by <function>drm_calc_vbltimestamp_from_scanoutpos</function>. They are
32706   derived from CRTC's true scanout timing, so they take
32707   things like panel scaling or other adjustments into account.
32708</para>
32709</refsect1>
32710</refentry>
32711
32712<refentry id="API-drm-calc-vbltimestamp-from-scanoutpos">
32713<refentryinfo>
32714 <title>LINUX</title>
32715 <productname>Kernel Hackers Manual</productname>
32716 <date>July 2017</date>
32717</refentryinfo>
32718<refmeta>
32719 <refentrytitle><phrase>drm_calc_vbltimestamp_from_scanoutpos</phrase></refentrytitle>
32720 <manvolnum>9</manvolnum>
32721 <refmiscinfo class="version">4.1.27</refmiscinfo>
32722</refmeta>
32723<refnamediv>
32724 <refname>drm_calc_vbltimestamp_from_scanoutpos</refname>
32725 <refpurpose>
32726     precise vblank timestamp helper
32727 </refpurpose>
32728</refnamediv>
32729<refsynopsisdiv>
32730 <title>Synopsis</title>
32731  <funcsynopsis><funcprototype>
32732   <funcdef>int <function>drm_calc_vbltimestamp_from_scanoutpos </function></funcdef>
32733   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
32734   <paramdef>int <parameter>crtc</parameter></paramdef>
32735   <paramdef>int * <parameter>max_error</parameter></paramdef>
32736   <paramdef>struct timeval * <parameter>vblank_time</parameter></paramdef>
32737   <paramdef>unsigned <parameter>flags</parameter></paramdef>
32738   <paramdef>const struct drm_crtc * <parameter>refcrtc</parameter></paramdef>
32739   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
32740  </funcprototype></funcsynopsis>
32741</refsynopsisdiv>
32742<refsect1>
32743 <title>Arguments</title>
32744 <variablelist>
32745  <varlistentry>
32746   <term><parameter>dev</parameter></term>
32747   <listitem>
32748    <para>
32749     DRM device
32750    </para>
32751   </listitem>
32752  </varlistentry>
32753  <varlistentry>
32754   <term><parameter>crtc</parameter></term>
32755   <listitem>
32756    <para>
32757     Which CRTC's vblank timestamp to retrieve
32758    </para>
32759   </listitem>
32760  </varlistentry>
32761  <varlistentry>
32762   <term><parameter>max_error</parameter></term>
32763   <listitem>
32764    <para>
32765     Desired maximum allowable error in timestamps (nanosecs)
32766     On return contains true maximum error of timestamp
32767    </para>
32768   </listitem>
32769  </varlistentry>
32770  <varlistentry>
32771   <term><parameter>vblank_time</parameter></term>
32772   <listitem>
32773    <para>
32774     Pointer to struct timeval which should receive the timestamp
32775    </para>
32776   </listitem>
32777  </varlistentry>
32778  <varlistentry>
32779   <term><parameter>flags</parameter></term>
32780   <listitem>
32781    <para>
32782     Flags to pass to driver:
32783     0 = Default,
32784     DRM_CALLED_FROM_VBLIRQ = If function is called from vbl IRQ handler
32785    </para>
32786   </listitem>
32787  </varlistentry>
32788  <varlistentry>
32789   <term><parameter>refcrtc</parameter></term>
32790   <listitem>
32791    <para>
32792     CRTC which defines scanout timing
32793    </para>
32794   </listitem>
32795  </varlistentry>
32796  <varlistentry>
32797   <term><parameter>mode</parameter></term>
32798   <listitem>
32799    <para>
32800     mode which defines the scanout timings
32801    </para>
32802   </listitem>
32803  </varlistentry>
32804 </variablelist>
32805</refsect1>
32806<refsect1>
32807<title>Description</title>
32808<para>
32809   Implements calculation of exact vblank timestamps from given drm_display_mode
32810   timings and current video scanout position of a CRTC. This can be called from
32811   within <function>get_vblank_timestamp</function> implementation of a kms driver to implement the
32812   actual timestamping.
32813   </para><para>
32814
32815   Should return timestamps conforming to the OML_sync_control OpenML
32816   extension specification. The timestamp corresponds to the end of
32817   the vblank interval, aka start of scanout of topmost-leftmost display
32818   pixel in the following video frame.
32819   </para><para>
32820
32821   Requires support for optional dev-&gt;driver-&gt;<function>get_scanout_position</function>
32822   in kms driver, plus a bit of setup code to provide a drm_display_mode
32823   that corresponds to the true scanout timing.
32824   </para><para>
32825
32826   The current implementation only handles standard video modes. It
32827   returns as no operation if a doublescan or interlaced video mode is
32828   active. Higher level code is expected to handle this.
32829</para>
32830</refsect1>
32831<refsect1>
32832<title>Returns</title>
32833<para>
32834   Negative value on error, failure or if not supported in current
32835</para>
32836</refsect1>
32837<refsect1>
32838<title>video mode</title>
32839<para>
32840   </para><para>
32841
32842   -EINVAL   - Invalid CRTC.
32843   -EAGAIN   - Temporary unavailable, e.g., called before initial modeset.
32844   -ENOTSUPP - Function not supported in current display mode.
32845   -EIO      - Failed, e.g., due to failed scanout position query.
32846   </para><para>
32847
32848   Returns or'ed positive status flags on success:
32849   </para><para>
32850
32851   DRM_VBLANKTIME_SCANOUTPOS_METHOD - Signal this method used for timestamping.
32852   DRM_VBLANKTIME_INVBL - Timestamp taken while scanout was in vblank interval.
32853</para>
32854</refsect1>
32855</refentry>
32856
32857<refentry id="API-drm-vblank-count">
32858<refentryinfo>
32859 <title>LINUX</title>
32860 <productname>Kernel Hackers Manual</productname>
32861 <date>July 2017</date>
32862</refentryinfo>
32863<refmeta>
32864 <refentrytitle><phrase>drm_vblank_count</phrase></refentrytitle>
32865 <manvolnum>9</manvolnum>
32866 <refmiscinfo class="version">4.1.27</refmiscinfo>
32867</refmeta>
32868<refnamediv>
32869 <refname>drm_vblank_count</refname>
32870 <refpurpose>
32871     retrieve <quote>cooked</quote> vblank counter value
32872 </refpurpose>
32873</refnamediv>
32874<refsynopsisdiv>
32875 <title>Synopsis</title>
32876  <funcsynopsis><funcprototype>
32877   <funcdef>u32 <function>drm_vblank_count </function></funcdef>
32878   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
32879   <paramdef>int <parameter>crtc</parameter></paramdef>
32880  </funcprototype></funcsynopsis>
32881</refsynopsisdiv>
32882<refsect1>
32883 <title>Arguments</title>
32884 <variablelist>
32885  <varlistentry>
32886   <term><parameter>dev</parameter></term>
32887   <listitem>
32888    <para>
32889     DRM device
32890    </para>
32891   </listitem>
32892  </varlistentry>
32893  <varlistentry>
32894   <term><parameter>crtc</parameter></term>
32895   <listitem>
32896    <para>
32897     which counter to retrieve
32898    </para>
32899   </listitem>
32900  </varlistentry>
32901 </variablelist>
32902</refsect1>
32903<refsect1>
32904<title>Description</title>
32905<para>
32906   Fetches the <quote>cooked</quote> vblank count value that represents the number of
32907   vblank events since the system was booted, including lost events due to
32908   modesetting activity.
32909   </para><para>
32910
32911   This is the legacy version of <function>drm_crtc_vblank_count</function>.
32912</para>
32913</refsect1>
32914<refsect1>
32915<title>Returns</title>
32916<para>
32917   The software vblank counter.
32918</para>
32919</refsect1>
32920</refentry>
32921
32922<refentry id="API-drm-crtc-vblank-count">
32923<refentryinfo>
32924 <title>LINUX</title>
32925 <productname>Kernel Hackers Manual</productname>
32926 <date>July 2017</date>
32927</refentryinfo>
32928<refmeta>
32929 <refentrytitle><phrase>drm_crtc_vblank_count</phrase></refentrytitle>
32930 <manvolnum>9</manvolnum>
32931 <refmiscinfo class="version">4.1.27</refmiscinfo>
32932</refmeta>
32933<refnamediv>
32934 <refname>drm_crtc_vblank_count</refname>
32935 <refpurpose>
32936     retrieve <quote>cooked</quote> vblank counter value
32937 </refpurpose>
32938</refnamediv>
32939<refsynopsisdiv>
32940 <title>Synopsis</title>
32941  <funcsynopsis><funcprototype>
32942   <funcdef>u32 <function>drm_crtc_vblank_count </function></funcdef>
32943   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
32944  </funcprototype></funcsynopsis>
32945</refsynopsisdiv>
32946<refsect1>
32947 <title>Arguments</title>
32948 <variablelist>
32949  <varlistentry>
32950   <term><parameter>crtc</parameter></term>
32951   <listitem>
32952    <para>
32953     which counter to retrieve
32954    </para>
32955   </listitem>
32956  </varlistentry>
32957 </variablelist>
32958</refsect1>
32959<refsect1>
32960<title>Description</title>
32961<para>
32962   Fetches the <quote>cooked</quote> vblank count value that represents the number of
32963   vblank events since the system was booted, including lost events due to
32964   modesetting activity.
32965   </para><para>
32966
32967   This is the native KMS version of <function>drm_vblank_count</function>.
32968</para>
32969</refsect1>
32970<refsect1>
32971<title>Returns</title>
32972<para>
32973   The software vblank counter.
32974</para>
32975</refsect1>
32976</refentry>
32977
32978<refentry id="API-drm-vblank-count-and-time">
32979<refentryinfo>
32980 <title>LINUX</title>
32981 <productname>Kernel Hackers Manual</productname>
32982 <date>July 2017</date>
32983</refentryinfo>
32984<refmeta>
32985 <refentrytitle><phrase>drm_vblank_count_and_time</phrase></refentrytitle>
32986 <manvolnum>9</manvolnum>
32987 <refmiscinfo class="version">4.1.27</refmiscinfo>
32988</refmeta>
32989<refnamediv>
32990 <refname>drm_vblank_count_and_time</refname>
32991 <refpurpose>
32992     retrieve <quote>cooked</quote> vblank counter value and the system timestamp corresponding to that vblank counter value.
32993 </refpurpose>
32994</refnamediv>
32995<refsynopsisdiv>
32996 <title>Synopsis</title>
32997  <funcsynopsis><funcprototype>
32998   <funcdef>u32 <function>drm_vblank_count_and_time </function></funcdef>
32999   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33000   <paramdef>int <parameter>crtc</parameter></paramdef>
33001   <paramdef>struct timeval * <parameter>vblanktime</parameter></paramdef>
33002  </funcprototype></funcsynopsis>
33003</refsynopsisdiv>
33004<refsect1>
33005 <title>Arguments</title>
33006 <variablelist>
33007  <varlistentry>
33008   <term><parameter>dev</parameter></term>
33009   <listitem>
33010    <para>
33011     DRM device
33012    </para>
33013   </listitem>
33014  </varlistentry>
33015  <varlistentry>
33016   <term><parameter>crtc</parameter></term>
33017   <listitem>
33018    <para>
33019     which counter to retrieve
33020    </para>
33021   </listitem>
33022  </varlistentry>
33023  <varlistentry>
33024   <term><parameter>vblanktime</parameter></term>
33025   <listitem>
33026    <para>
33027     Pointer to struct timeval to receive the vblank timestamp.
33028    </para>
33029   </listitem>
33030  </varlistentry>
33031 </variablelist>
33032</refsect1>
33033<refsect1>
33034<title>Description</title>
33035<para>
33036   Fetches the <quote>cooked</quote> vblank count value that represents the number of
33037   vblank events since the system was booted, including lost events due to
33038   modesetting activity. Returns corresponding system timestamp of the time
33039   of the vblank interval that corresponds to the current vblank counter value.
33040</para>
33041</refsect1>
33042</refentry>
33043
33044<refentry id="API-drm-send-vblank-event">
33045<refentryinfo>
33046 <title>LINUX</title>
33047 <productname>Kernel Hackers Manual</productname>
33048 <date>July 2017</date>
33049</refentryinfo>
33050<refmeta>
33051 <refentrytitle><phrase>drm_send_vblank_event</phrase></refentrytitle>
33052 <manvolnum>9</manvolnum>
33053 <refmiscinfo class="version">4.1.27</refmiscinfo>
33054</refmeta>
33055<refnamediv>
33056 <refname>drm_send_vblank_event</refname>
33057 <refpurpose>
33058     helper to send vblank event after pageflip
33059 </refpurpose>
33060</refnamediv>
33061<refsynopsisdiv>
33062 <title>Synopsis</title>
33063  <funcsynopsis><funcprototype>
33064   <funcdef>void <function>drm_send_vblank_event </function></funcdef>
33065   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33066   <paramdef>int <parameter>crtc</parameter></paramdef>
33067   <paramdef>struct drm_pending_vblank_event * <parameter>e</parameter></paramdef>
33068  </funcprototype></funcsynopsis>
33069</refsynopsisdiv>
33070<refsect1>
33071 <title>Arguments</title>
33072 <variablelist>
33073  <varlistentry>
33074   <term><parameter>dev</parameter></term>
33075   <listitem>
33076    <para>
33077     DRM device
33078    </para>
33079   </listitem>
33080  </varlistentry>
33081  <varlistentry>
33082   <term><parameter>crtc</parameter></term>
33083   <listitem>
33084    <para>
33085     CRTC in question
33086    </para>
33087   </listitem>
33088  </varlistentry>
33089  <varlistentry>
33090   <term><parameter>e</parameter></term>
33091   <listitem>
33092    <para>
33093     the event to send
33094    </para>
33095   </listitem>
33096  </varlistentry>
33097 </variablelist>
33098</refsect1>
33099<refsect1>
33100<title>Description</title>
33101<para>
33102   Updates sequence # and timestamp on event, and sends it to userspace.
33103   Caller must hold event lock.
33104   </para><para>
33105
33106   This is the legacy version of <function>drm_crtc_send_vblank_event</function>.
33107</para>
33108</refsect1>
33109</refentry>
33110
33111<refentry id="API-drm-crtc-send-vblank-event">
33112<refentryinfo>
33113 <title>LINUX</title>
33114 <productname>Kernel Hackers Manual</productname>
33115 <date>July 2017</date>
33116</refentryinfo>
33117<refmeta>
33118 <refentrytitle><phrase>drm_crtc_send_vblank_event</phrase></refentrytitle>
33119 <manvolnum>9</manvolnum>
33120 <refmiscinfo class="version">4.1.27</refmiscinfo>
33121</refmeta>
33122<refnamediv>
33123 <refname>drm_crtc_send_vblank_event</refname>
33124 <refpurpose>
33125     helper to send vblank event after pageflip
33126 </refpurpose>
33127</refnamediv>
33128<refsynopsisdiv>
33129 <title>Synopsis</title>
33130  <funcsynopsis><funcprototype>
33131   <funcdef>void <function>drm_crtc_send_vblank_event </function></funcdef>
33132   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33133   <paramdef>struct drm_pending_vblank_event * <parameter>e</parameter></paramdef>
33134  </funcprototype></funcsynopsis>
33135</refsynopsisdiv>
33136<refsect1>
33137 <title>Arguments</title>
33138 <variablelist>
33139  <varlistentry>
33140   <term><parameter>crtc</parameter></term>
33141   <listitem>
33142    <para>
33143     the source CRTC of the vblank event
33144    </para>
33145   </listitem>
33146  </varlistentry>
33147  <varlistentry>
33148   <term><parameter>e</parameter></term>
33149   <listitem>
33150    <para>
33151     the event to send
33152    </para>
33153   </listitem>
33154  </varlistentry>
33155 </variablelist>
33156</refsect1>
33157<refsect1>
33158<title>Description</title>
33159<para>
33160   Updates sequence # and timestamp on event, and sends it to userspace.
33161   Caller must hold event lock.
33162   </para><para>
33163
33164   This is the native KMS version of <function>drm_send_vblank_event</function>.
33165</para>
33166</refsect1>
33167</refentry>
33168
33169<refentry id="API-drm-vblank-get">
33170<refentryinfo>
33171 <title>LINUX</title>
33172 <productname>Kernel Hackers Manual</productname>
33173 <date>July 2017</date>
33174</refentryinfo>
33175<refmeta>
33176 <refentrytitle><phrase>drm_vblank_get</phrase></refentrytitle>
33177 <manvolnum>9</manvolnum>
33178 <refmiscinfo class="version">4.1.27</refmiscinfo>
33179</refmeta>
33180<refnamediv>
33181 <refname>drm_vblank_get</refname>
33182 <refpurpose>
33183     get a reference count on vblank events
33184 </refpurpose>
33185</refnamediv>
33186<refsynopsisdiv>
33187 <title>Synopsis</title>
33188  <funcsynopsis><funcprototype>
33189   <funcdef>int <function>drm_vblank_get </function></funcdef>
33190   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33191   <paramdef>int <parameter>crtc</parameter></paramdef>
33192  </funcprototype></funcsynopsis>
33193</refsynopsisdiv>
33194<refsect1>
33195 <title>Arguments</title>
33196 <variablelist>
33197  <varlistentry>
33198   <term><parameter>dev</parameter></term>
33199   <listitem>
33200    <para>
33201     DRM device
33202    </para>
33203   </listitem>
33204  </varlistentry>
33205  <varlistentry>
33206   <term><parameter>crtc</parameter></term>
33207   <listitem>
33208    <para>
33209     which CRTC to own
33210    </para>
33211   </listitem>
33212  </varlistentry>
33213 </variablelist>
33214</refsect1>
33215<refsect1>
33216<title>Description</title>
33217<para>
33218   Acquire a reference count on vblank events to avoid having them disabled
33219   while in use.
33220   </para><para>
33221
33222   This is the legacy version of <function>drm_crtc_vblank_get</function>.
33223</para>
33224</refsect1>
33225<refsect1>
33226<title>Returns</title>
33227<para>
33228   Zero on success, nonzero on failure.
33229</para>
33230</refsect1>
33231</refentry>
33232
33233<refentry id="API-drm-crtc-vblank-get">
33234<refentryinfo>
33235 <title>LINUX</title>
33236 <productname>Kernel Hackers Manual</productname>
33237 <date>July 2017</date>
33238</refentryinfo>
33239<refmeta>
33240 <refentrytitle><phrase>drm_crtc_vblank_get</phrase></refentrytitle>
33241 <manvolnum>9</manvolnum>
33242 <refmiscinfo class="version">4.1.27</refmiscinfo>
33243</refmeta>
33244<refnamediv>
33245 <refname>drm_crtc_vblank_get</refname>
33246 <refpurpose>
33247     get a reference count on vblank events
33248 </refpurpose>
33249</refnamediv>
33250<refsynopsisdiv>
33251 <title>Synopsis</title>
33252  <funcsynopsis><funcprototype>
33253   <funcdef>int <function>drm_crtc_vblank_get </function></funcdef>
33254   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33255  </funcprototype></funcsynopsis>
33256</refsynopsisdiv>
33257<refsect1>
33258 <title>Arguments</title>
33259 <variablelist>
33260  <varlistentry>
33261   <term><parameter>crtc</parameter></term>
33262   <listitem>
33263    <para>
33264     which CRTC to own
33265    </para>
33266   </listitem>
33267  </varlistentry>
33268 </variablelist>
33269</refsect1>
33270<refsect1>
33271<title>Description</title>
33272<para>
33273   Acquire a reference count on vblank events to avoid having them disabled
33274   while in use.
33275   </para><para>
33276
33277   This is the native kms version of <function>drm_vblank_get</function>.
33278</para>
33279</refsect1>
33280<refsect1>
33281<title>Returns</title>
33282<para>
33283   Zero on success, nonzero on failure.
33284</para>
33285</refsect1>
33286</refentry>
33287
33288<refentry id="API-drm-vblank-put">
33289<refentryinfo>
33290 <title>LINUX</title>
33291 <productname>Kernel Hackers Manual</productname>
33292 <date>July 2017</date>
33293</refentryinfo>
33294<refmeta>
33295 <refentrytitle><phrase>drm_vblank_put</phrase></refentrytitle>
33296 <manvolnum>9</manvolnum>
33297 <refmiscinfo class="version">4.1.27</refmiscinfo>
33298</refmeta>
33299<refnamediv>
33300 <refname>drm_vblank_put</refname>
33301 <refpurpose>
33302     give up ownership of vblank events
33303 </refpurpose>
33304</refnamediv>
33305<refsynopsisdiv>
33306 <title>Synopsis</title>
33307  <funcsynopsis><funcprototype>
33308   <funcdef>void <function>drm_vblank_put </function></funcdef>
33309   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33310   <paramdef>int <parameter>crtc</parameter></paramdef>
33311  </funcprototype></funcsynopsis>
33312</refsynopsisdiv>
33313<refsect1>
33314 <title>Arguments</title>
33315 <variablelist>
33316  <varlistentry>
33317   <term><parameter>dev</parameter></term>
33318   <listitem>
33319    <para>
33320     DRM device
33321    </para>
33322   </listitem>
33323  </varlistentry>
33324  <varlistentry>
33325   <term><parameter>crtc</parameter></term>
33326   <listitem>
33327    <para>
33328     which counter to give up
33329    </para>
33330   </listitem>
33331  </varlistentry>
33332 </variablelist>
33333</refsect1>
33334<refsect1>
33335<title>Description</title>
33336<para>
33337   Release ownership of a given vblank counter, turning off interrupts
33338   if possible. Disable interrupts after drm_vblank_offdelay milliseconds.
33339   </para><para>
33340
33341   This is the legacy version of <function>drm_crtc_vblank_put</function>.
33342</para>
33343</refsect1>
33344</refentry>
33345
33346<refentry id="API-drm-crtc-vblank-put">
33347<refentryinfo>
33348 <title>LINUX</title>
33349 <productname>Kernel Hackers Manual</productname>
33350 <date>July 2017</date>
33351</refentryinfo>
33352<refmeta>
33353 <refentrytitle><phrase>drm_crtc_vblank_put</phrase></refentrytitle>
33354 <manvolnum>9</manvolnum>
33355 <refmiscinfo class="version">4.1.27</refmiscinfo>
33356</refmeta>
33357<refnamediv>
33358 <refname>drm_crtc_vblank_put</refname>
33359 <refpurpose>
33360     give up ownership of vblank events
33361 </refpurpose>
33362</refnamediv>
33363<refsynopsisdiv>
33364 <title>Synopsis</title>
33365  <funcsynopsis><funcprototype>
33366   <funcdef>void <function>drm_crtc_vblank_put </function></funcdef>
33367   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33368  </funcprototype></funcsynopsis>
33369</refsynopsisdiv>
33370<refsect1>
33371 <title>Arguments</title>
33372 <variablelist>
33373  <varlistentry>
33374   <term><parameter>crtc</parameter></term>
33375   <listitem>
33376    <para>
33377     which counter to give up
33378    </para>
33379   </listitem>
33380  </varlistentry>
33381 </variablelist>
33382</refsect1>
33383<refsect1>
33384<title>Description</title>
33385<para>
33386   Release ownership of a given vblank counter, turning off interrupts
33387   if possible. Disable interrupts after drm_vblank_offdelay milliseconds.
33388   </para><para>
33389
33390   This is the native kms version of <function>drm_vblank_put</function>.
33391</para>
33392</refsect1>
33393</refentry>
33394
33395<refentry id="API-drm-wait-one-vblank">
33396<refentryinfo>
33397 <title>LINUX</title>
33398 <productname>Kernel Hackers Manual</productname>
33399 <date>July 2017</date>
33400</refentryinfo>
33401<refmeta>
33402 <refentrytitle><phrase>drm_wait_one_vblank</phrase></refentrytitle>
33403 <manvolnum>9</manvolnum>
33404 <refmiscinfo class="version">4.1.27</refmiscinfo>
33405</refmeta>
33406<refnamediv>
33407 <refname>drm_wait_one_vblank</refname>
33408 <refpurpose>
33409     wait for one vblank
33410 </refpurpose>
33411</refnamediv>
33412<refsynopsisdiv>
33413 <title>Synopsis</title>
33414  <funcsynopsis><funcprototype>
33415   <funcdef>void <function>drm_wait_one_vblank </function></funcdef>
33416   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33417   <paramdef>int <parameter>crtc</parameter></paramdef>
33418  </funcprototype></funcsynopsis>
33419</refsynopsisdiv>
33420<refsect1>
33421 <title>Arguments</title>
33422 <variablelist>
33423  <varlistentry>
33424   <term><parameter>dev</parameter></term>
33425   <listitem>
33426    <para>
33427     DRM device
33428    </para>
33429   </listitem>
33430  </varlistentry>
33431  <varlistentry>
33432   <term><parameter>crtc</parameter></term>
33433   <listitem>
33434    <para>
33435     crtc index
33436    </para>
33437   </listitem>
33438  </varlistentry>
33439 </variablelist>
33440</refsect1>
33441<refsect1>
33442<title>Description</title>
33443<para>
33444   This waits for one vblank to pass on <parameter>crtc</parameter>, using the irq driver interfaces.
33445   It is a failure to call this when the vblank irq for <parameter>crtc</parameter> is disabled, e.g.
33446   due to lack of driver support or because the crtc is off.
33447</para>
33448</refsect1>
33449</refentry>
33450
33451<refentry id="API-drm-crtc-wait-one-vblank">
33452<refentryinfo>
33453 <title>LINUX</title>
33454 <productname>Kernel Hackers Manual</productname>
33455 <date>July 2017</date>
33456</refentryinfo>
33457<refmeta>
33458 <refentrytitle><phrase>drm_crtc_wait_one_vblank</phrase></refentrytitle>
33459 <manvolnum>9</manvolnum>
33460 <refmiscinfo class="version">4.1.27</refmiscinfo>
33461</refmeta>
33462<refnamediv>
33463 <refname>drm_crtc_wait_one_vblank</refname>
33464 <refpurpose>
33465     wait for one vblank
33466 </refpurpose>
33467</refnamediv>
33468<refsynopsisdiv>
33469 <title>Synopsis</title>
33470  <funcsynopsis><funcprototype>
33471   <funcdef>void <function>drm_crtc_wait_one_vblank </function></funcdef>
33472   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33473  </funcprototype></funcsynopsis>
33474</refsynopsisdiv>
33475<refsect1>
33476 <title>Arguments</title>
33477 <variablelist>
33478  <varlistentry>
33479   <term><parameter>crtc</parameter></term>
33480   <listitem>
33481    <para>
33482     DRM crtc
33483    </para>
33484   </listitem>
33485  </varlistentry>
33486 </variablelist>
33487</refsect1>
33488<refsect1>
33489<title>Description</title>
33490<para>
33491   This waits for one vblank to pass on <parameter>crtc</parameter>, using the irq driver interfaces.
33492   It is a failure to call this when the vblank irq for <parameter>crtc</parameter> is disabled, e.g.
33493   due to lack of driver support or because the crtc is off.
33494</para>
33495</refsect1>
33496</refentry>
33497
33498<refentry id="API-drm-vblank-off">
33499<refentryinfo>
33500 <title>LINUX</title>
33501 <productname>Kernel Hackers Manual</productname>
33502 <date>July 2017</date>
33503</refentryinfo>
33504<refmeta>
33505 <refentrytitle><phrase>drm_vblank_off</phrase></refentrytitle>
33506 <manvolnum>9</manvolnum>
33507 <refmiscinfo class="version">4.1.27</refmiscinfo>
33508</refmeta>
33509<refnamediv>
33510 <refname>drm_vblank_off</refname>
33511 <refpurpose>
33512     disable vblank events on a CRTC
33513 </refpurpose>
33514</refnamediv>
33515<refsynopsisdiv>
33516 <title>Synopsis</title>
33517  <funcsynopsis><funcprototype>
33518   <funcdef>void <function>drm_vblank_off </function></funcdef>
33519   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33520   <paramdef>int <parameter>crtc</parameter></paramdef>
33521  </funcprototype></funcsynopsis>
33522</refsynopsisdiv>
33523<refsect1>
33524 <title>Arguments</title>
33525 <variablelist>
33526  <varlistentry>
33527   <term><parameter>dev</parameter></term>
33528   <listitem>
33529    <para>
33530     DRM device
33531    </para>
33532   </listitem>
33533  </varlistentry>
33534  <varlistentry>
33535   <term><parameter>crtc</parameter></term>
33536   <listitem>
33537    <para>
33538     CRTC in question
33539    </para>
33540   </listitem>
33541  </varlistentry>
33542 </variablelist>
33543</refsect1>
33544<refsect1>
33545<title>Description</title>
33546<para>
33547   Drivers can use this function to shut down the vblank interrupt handling when
33548   disabling a crtc. This function ensures that the latest vblank frame count is
33549   stored so that <function>drm_vblank_on</function> can restore it again.
33550   </para><para>
33551
33552   Drivers must use this function when the hardware vblank counter can get
33553   reset, e.g. when suspending.
33554   </para><para>
33555
33556   This is the legacy version of <function>drm_crtc_vblank_off</function>.
33557</para>
33558</refsect1>
33559</refentry>
33560
33561<refentry id="API-drm-crtc-vblank-off">
33562<refentryinfo>
33563 <title>LINUX</title>
33564 <productname>Kernel Hackers Manual</productname>
33565 <date>July 2017</date>
33566</refentryinfo>
33567<refmeta>
33568 <refentrytitle><phrase>drm_crtc_vblank_off</phrase></refentrytitle>
33569 <manvolnum>9</manvolnum>
33570 <refmiscinfo class="version">4.1.27</refmiscinfo>
33571</refmeta>
33572<refnamediv>
33573 <refname>drm_crtc_vblank_off</refname>
33574 <refpurpose>
33575     disable vblank events on a CRTC
33576 </refpurpose>
33577</refnamediv>
33578<refsynopsisdiv>
33579 <title>Synopsis</title>
33580  <funcsynopsis><funcprototype>
33581   <funcdef>void <function>drm_crtc_vblank_off </function></funcdef>
33582   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33583  </funcprototype></funcsynopsis>
33584</refsynopsisdiv>
33585<refsect1>
33586 <title>Arguments</title>
33587 <variablelist>
33588  <varlistentry>
33589   <term><parameter>crtc</parameter></term>
33590   <listitem>
33591    <para>
33592     CRTC in question
33593    </para>
33594   </listitem>
33595  </varlistentry>
33596 </variablelist>
33597</refsect1>
33598<refsect1>
33599<title>Description</title>
33600<para>
33601   Drivers can use this function to shut down the vblank interrupt handling when
33602   disabling a crtc. This function ensures that the latest vblank frame count is
33603   stored so that drm_vblank_on can restore it again.
33604   </para><para>
33605
33606   Drivers must use this function when the hardware vblank counter can get
33607   reset, e.g. when suspending.
33608   </para><para>
33609
33610   This is the native kms version of <function>drm_vblank_off</function>.
33611</para>
33612</refsect1>
33613</refentry>
33614
33615<refentry id="API-drm-crtc-vblank-reset">
33616<refentryinfo>
33617 <title>LINUX</title>
33618 <productname>Kernel Hackers Manual</productname>
33619 <date>July 2017</date>
33620</refentryinfo>
33621<refmeta>
33622 <refentrytitle><phrase>drm_crtc_vblank_reset</phrase></refentrytitle>
33623 <manvolnum>9</manvolnum>
33624 <refmiscinfo class="version">4.1.27</refmiscinfo>
33625</refmeta>
33626<refnamediv>
33627 <refname>drm_crtc_vblank_reset</refname>
33628 <refpurpose>
33629     reset vblank state to off on a CRTC
33630 </refpurpose>
33631</refnamediv>
33632<refsynopsisdiv>
33633 <title>Synopsis</title>
33634  <funcsynopsis><funcprototype>
33635   <funcdef>void <function>drm_crtc_vblank_reset </function></funcdef>
33636   <paramdef>struct drm_crtc * <parameter>drm_crtc</parameter></paramdef>
33637  </funcprototype></funcsynopsis>
33638</refsynopsisdiv>
33639<refsect1>
33640 <title>Arguments</title>
33641 <variablelist>
33642  <varlistentry>
33643   <term><parameter>drm_crtc</parameter></term>
33644   <listitem>
33645    <para>
33646     -- undescribed --
33647    </para>
33648   </listitem>
33649  </varlistentry>
33650 </variablelist>
33651</refsect1>
33652<refsect1>
33653<title>Description</title>
33654<para>
33655   Drivers can use this function to reset the vblank state to off at load time.
33656   Drivers should use this together with the <function>drm_crtc_vblank_off</function> and
33657   <function>drm_crtc_vblank_on</function> functions. The difference compared to
33658   <function>drm_crtc_vblank_off</function> is that this function doesn't save the vblank counter
33659   and hence doesn't need to call any driver hooks.
33660</para>
33661</refsect1>
33662</refentry>
33663
33664<refentry id="API-drm-vblank-on">
33665<refentryinfo>
33666 <title>LINUX</title>
33667 <productname>Kernel Hackers Manual</productname>
33668 <date>July 2017</date>
33669</refentryinfo>
33670<refmeta>
33671 <refentrytitle><phrase>drm_vblank_on</phrase></refentrytitle>
33672 <manvolnum>9</manvolnum>
33673 <refmiscinfo class="version">4.1.27</refmiscinfo>
33674</refmeta>
33675<refnamediv>
33676 <refname>drm_vblank_on</refname>
33677 <refpurpose>
33678     enable vblank events on a CRTC
33679 </refpurpose>
33680</refnamediv>
33681<refsynopsisdiv>
33682 <title>Synopsis</title>
33683  <funcsynopsis><funcprototype>
33684   <funcdef>void <function>drm_vblank_on </function></funcdef>
33685   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33686   <paramdef>int <parameter>crtc</parameter></paramdef>
33687  </funcprototype></funcsynopsis>
33688</refsynopsisdiv>
33689<refsect1>
33690 <title>Arguments</title>
33691 <variablelist>
33692  <varlistentry>
33693   <term><parameter>dev</parameter></term>
33694   <listitem>
33695    <para>
33696     DRM device
33697    </para>
33698   </listitem>
33699  </varlistentry>
33700  <varlistentry>
33701   <term><parameter>crtc</parameter></term>
33702   <listitem>
33703    <para>
33704     CRTC in question
33705    </para>
33706   </listitem>
33707  </varlistentry>
33708 </variablelist>
33709</refsect1>
33710<refsect1>
33711<title>Description</title>
33712<para>
33713   This functions restores the vblank interrupt state captured with
33714   <function>drm_vblank_off</function> again. Note that calls to <function>drm_vblank_on</function> and
33715   <function>drm_vblank_off</function> can be unbalanced and so can also be unconditionally called
33716   in driver load code to reflect the current hardware state of the crtc.
33717   </para><para>
33718
33719   This is the legacy version of <function>drm_crtc_vblank_on</function>.
33720</para>
33721</refsect1>
33722</refentry>
33723
33724<refentry id="API-drm-crtc-vblank-on">
33725<refentryinfo>
33726 <title>LINUX</title>
33727 <productname>Kernel Hackers Manual</productname>
33728 <date>July 2017</date>
33729</refentryinfo>
33730<refmeta>
33731 <refentrytitle><phrase>drm_crtc_vblank_on</phrase></refentrytitle>
33732 <manvolnum>9</manvolnum>
33733 <refmiscinfo class="version">4.1.27</refmiscinfo>
33734</refmeta>
33735<refnamediv>
33736 <refname>drm_crtc_vblank_on</refname>
33737 <refpurpose>
33738     enable vblank events on a CRTC
33739 </refpurpose>
33740</refnamediv>
33741<refsynopsisdiv>
33742 <title>Synopsis</title>
33743  <funcsynopsis><funcprototype>
33744   <funcdef>void <function>drm_crtc_vblank_on </function></funcdef>
33745   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33746  </funcprototype></funcsynopsis>
33747</refsynopsisdiv>
33748<refsect1>
33749 <title>Arguments</title>
33750 <variablelist>
33751  <varlistentry>
33752   <term><parameter>crtc</parameter></term>
33753   <listitem>
33754    <para>
33755     CRTC in question
33756    </para>
33757   </listitem>
33758  </varlistentry>
33759 </variablelist>
33760</refsect1>
33761<refsect1>
33762<title>Description</title>
33763<para>
33764   This functions restores the vblank interrupt state captured with
33765   <function>drm_vblank_off</function> again. Note that calls to <function>drm_vblank_on</function> and
33766   <function>drm_vblank_off</function> can be unbalanced and so can also be unconditionally called
33767   in driver load code to reflect the current hardware state of the crtc.
33768   </para><para>
33769
33770   This is the native kms version of <function>drm_vblank_on</function>.
33771</para>
33772</refsect1>
33773</refentry>
33774
33775<refentry id="API-drm-vblank-pre-modeset">
33776<refentryinfo>
33777 <title>LINUX</title>
33778 <productname>Kernel Hackers Manual</productname>
33779 <date>July 2017</date>
33780</refentryinfo>
33781<refmeta>
33782 <refentrytitle><phrase>drm_vblank_pre_modeset</phrase></refentrytitle>
33783 <manvolnum>9</manvolnum>
33784 <refmiscinfo class="version">4.1.27</refmiscinfo>
33785</refmeta>
33786<refnamediv>
33787 <refname>drm_vblank_pre_modeset</refname>
33788 <refpurpose>
33789     account for vblanks across mode sets
33790 </refpurpose>
33791</refnamediv>
33792<refsynopsisdiv>
33793 <title>Synopsis</title>
33794  <funcsynopsis><funcprototype>
33795   <funcdef>void <function>drm_vblank_pre_modeset </function></funcdef>
33796   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33797   <paramdef>int <parameter>crtc</parameter></paramdef>
33798  </funcprototype></funcsynopsis>
33799</refsynopsisdiv>
33800<refsect1>
33801 <title>Arguments</title>
33802 <variablelist>
33803  <varlistentry>
33804   <term><parameter>dev</parameter></term>
33805   <listitem>
33806    <para>
33807     DRM device
33808    </para>
33809   </listitem>
33810  </varlistentry>
33811  <varlistentry>
33812   <term><parameter>crtc</parameter></term>
33813   <listitem>
33814    <para>
33815     CRTC in question
33816    </para>
33817   </listitem>
33818  </varlistentry>
33819 </variablelist>
33820</refsect1>
33821<refsect1>
33822<title>Description</title>
33823<para>
33824   Account for vblank events across mode setting events, which will likely
33825   reset the hardware frame counter.
33826   </para><para>
33827
33828   This is done by grabbing a temporary vblank reference to ensure that the
33829   vblank interrupt keeps running across the modeset sequence. With this the
33830   software-side vblank frame counting will ensure that there are no jumps or
33831   discontinuities.
33832   </para><para>
33833
33834   Unfortunately this approach is racy and also doesn't work when the vblank
33835   interrupt stops running, e.g. across system suspend resume. It is therefore
33836   highly recommended that drivers use the newer <function>drm_vblank_off</function> and
33837   <function>drm_vblank_on</function> instead. <function>drm_vblank_pre_modeset</function> only works correctly when
33838   using <quote>cooked</quote> software vblank frame counters and not relying on any hardware
33839   counters.
33840   </para><para>
33841
33842   Drivers must call <function>drm_vblank_post_modeset</function> when re-enabling the same crtc
33843   again.
33844</para>
33845</refsect1>
33846</refentry>
33847
33848<refentry id="API-drm-vblank-post-modeset">
33849<refentryinfo>
33850 <title>LINUX</title>
33851 <productname>Kernel Hackers Manual</productname>
33852 <date>July 2017</date>
33853</refentryinfo>
33854<refmeta>
33855 <refentrytitle><phrase>drm_vblank_post_modeset</phrase></refentrytitle>
33856 <manvolnum>9</manvolnum>
33857 <refmiscinfo class="version">4.1.27</refmiscinfo>
33858</refmeta>
33859<refnamediv>
33860 <refname>drm_vblank_post_modeset</refname>
33861 <refpurpose>
33862     undo drm_vblank_pre_modeset changes
33863 </refpurpose>
33864</refnamediv>
33865<refsynopsisdiv>
33866 <title>Synopsis</title>
33867  <funcsynopsis><funcprototype>
33868   <funcdef>void <function>drm_vblank_post_modeset </function></funcdef>
33869   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33870   <paramdef>int <parameter>crtc</parameter></paramdef>
33871  </funcprototype></funcsynopsis>
33872</refsynopsisdiv>
33873<refsect1>
33874 <title>Arguments</title>
33875 <variablelist>
33876  <varlistentry>
33877   <term><parameter>dev</parameter></term>
33878   <listitem>
33879    <para>
33880     DRM device
33881    </para>
33882   </listitem>
33883  </varlistentry>
33884  <varlistentry>
33885   <term><parameter>crtc</parameter></term>
33886   <listitem>
33887    <para>
33888     CRTC in question
33889    </para>
33890   </listitem>
33891  </varlistentry>
33892 </variablelist>
33893</refsect1>
33894<refsect1>
33895<title>Description</title>
33896<para>
33897   This function again drops the temporary vblank reference acquired in
33898   drm_vblank_pre_modeset.
33899</para>
33900</refsect1>
33901</refentry>
33902
33903<refentry id="API-drm-handle-vblank">
33904<refentryinfo>
33905 <title>LINUX</title>
33906 <productname>Kernel Hackers Manual</productname>
33907 <date>July 2017</date>
33908</refentryinfo>
33909<refmeta>
33910 <refentrytitle><phrase>drm_handle_vblank</phrase></refentrytitle>
33911 <manvolnum>9</manvolnum>
33912 <refmiscinfo class="version">4.1.27</refmiscinfo>
33913</refmeta>
33914<refnamediv>
33915 <refname>drm_handle_vblank</refname>
33916 <refpurpose>
33917     handle a vblank event
33918 </refpurpose>
33919</refnamediv>
33920<refsynopsisdiv>
33921 <title>Synopsis</title>
33922  <funcsynopsis><funcprototype>
33923   <funcdef>bool <function>drm_handle_vblank </function></funcdef>
33924   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
33925   <paramdef>int <parameter>crtc</parameter></paramdef>
33926  </funcprototype></funcsynopsis>
33927</refsynopsisdiv>
33928<refsect1>
33929 <title>Arguments</title>
33930 <variablelist>
33931  <varlistentry>
33932   <term><parameter>dev</parameter></term>
33933   <listitem>
33934    <para>
33935     DRM device
33936    </para>
33937   </listitem>
33938  </varlistentry>
33939  <varlistentry>
33940   <term><parameter>crtc</parameter></term>
33941   <listitem>
33942    <para>
33943     where this event occurred
33944    </para>
33945   </listitem>
33946  </varlistentry>
33947 </variablelist>
33948</refsect1>
33949<refsect1>
33950<title>Description</title>
33951<para>
33952   Drivers should call this routine in their vblank interrupt handlers to
33953   update the vblank counter and send any signals that may be pending.
33954   </para><para>
33955
33956   This is the legacy version of <function>drm_crtc_handle_vblank</function>.
33957</para>
33958</refsect1>
33959</refentry>
33960
33961<refentry id="API-drm-crtc-handle-vblank">
33962<refentryinfo>
33963 <title>LINUX</title>
33964 <productname>Kernel Hackers Manual</productname>
33965 <date>July 2017</date>
33966</refentryinfo>
33967<refmeta>
33968 <refentrytitle><phrase>drm_crtc_handle_vblank</phrase></refentrytitle>
33969 <manvolnum>9</manvolnum>
33970 <refmiscinfo class="version">4.1.27</refmiscinfo>
33971</refmeta>
33972<refnamediv>
33973 <refname>drm_crtc_handle_vblank</refname>
33974 <refpurpose>
33975     handle a vblank event
33976 </refpurpose>
33977</refnamediv>
33978<refsynopsisdiv>
33979 <title>Synopsis</title>
33980  <funcsynopsis><funcprototype>
33981   <funcdef>bool <function>drm_crtc_handle_vblank </function></funcdef>
33982   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
33983  </funcprototype></funcsynopsis>
33984</refsynopsisdiv>
33985<refsect1>
33986 <title>Arguments</title>
33987 <variablelist>
33988  <varlistentry>
33989   <term><parameter>crtc</parameter></term>
33990   <listitem>
33991    <para>
33992     where this event occurred
33993    </para>
33994   </listitem>
33995  </varlistentry>
33996 </variablelist>
33997</refsect1>
33998<refsect1>
33999<title>Description</title>
34000<para>
34001   Drivers should call this routine in their vblank interrupt handlers to
34002   update the vblank counter and send any signals that may be pending.
34003   </para><para>
34004
34005   This is the native KMS version of <function>drm_handle_vblank</function>.
34006</para>
34007</refsect1>
34008<refsect1>
34009<title>Returns</title>
34010<para>
34011   True if the event was successfully handled, false on failure.
34012</para>
34013</refsect1>
34014</refentry>
34015
34016<refentry id="API-drm-crtc-vblank-waitqueue">
34017<refentryinfo>
34018 <title>LINUX</title>
34019 <productname>Kernel Hackers Manual</productname>
34020 <date>July 2017</date>
34021</refentryinfo>
34022<refmeta>
34023 <refentrytitle><phrase>drm_crtc_vblank_waitqueue</phrase></refentrytitle>
34024 <manvolnum>9</manvolnum>
34025 <refmiscinfo class="version">4.1.27</refmiscinfo>
34026</refmeta>
34027<refnamediv>
34028 <refname>drm_crtc_vblank_waitqueue</refname>
34029 <refpurpose>
34030  get vblank waitqueue for the CRTC
34031 </refpurpose>
34032</refnamediv>
34033<refsynopsisdiv>
34034 <title>Synopsis</title>
34035  <funcsynopsis><funcprototype>
34036   <funcdef>wait_queue_head_t * <function>drm_crtc_vblank_waitqueue </function></funcdef>
34037   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
34038  </funcprototype></funcsynopsis>
34039</refsynopsisdiv>
34040<refsect1>
34041 <title>Arguments</title>
34042 <variablelist>
34043  <varlistentry>
34044   <term><parameter>crtc</parameter></term>
34045   <listitem>
34046    <para>
34047     which CRTC's vblank waitqueue to retrieve
34048    </para>
34049   </listitem>
34050  </varlistentry>
34051 </variablelist>
34052</refsect1>
34053<refsect1>
34054<title>Description</title>
34055<para>
34056   This function returns a pointer to the vblank waitqueue for the CRTC.
34057   Drivers can use this to implement vblank waits using <function>wait_event</function> &amp; co.
34058</para>
34059</refsect1>
34060</refentry>
34061
34062    </sect2>
34063  </sect1>
34064
34065  <!-- Internals: open/close, file operations and ioctls -->
34066
34067  <sect1>
34068    <title>Open/Close, File Operations and IOCTLs</title>
34069    <sect2>
34070      <title>Open and Close</title>
34071      <synopsis>int (*firstopen) (struct drm_device *);
34072void (*lastclose) (struct drm_device *);
34073int (*open) (struct drm_device *, struct drm_file *);
34074void (*preclose) (struct drm_device *, struct drm_file *);
34075void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
34076      <abstract>Open and close handlers. None of those methods are mandatory.
34077      </abstract>
34078      <para>
34079        The <methodname>firstopen</methodname> method is called by the DRM core
34080	for legacy UMS (User Mode Setting) drivers only when an application
34081	opens a device that has no other opened file handle. UMS drivers can
34082	implement it to acquire device resources. KMS drivers can't use the
34083	method and must acquire resources in the <methodname>load</methodname>
34084	method instead.
34085      </para>
34086      <para>
34087	Similarly the <methodname>lastclose</methodname> method is called when
34088	the last application holding a file handle opened on the device closes
34089	it, for both UMS and KMS drivers. Additionally, the method is also
34090	called at module unload time or, for hot-pluggable devices, when the
34091	device is unplugged. The <methodname>firstopen</methodname> and
34092	<methodname>lastclose</methodname> calls can thus be unbalanced.
34093      </para>
34094      <para>
34095        The <methodname>open</methodname> method is called every time the device
34096	is opened by an application. Drivers can allocate per-file private data
34097	in this method and store them in the struct
34098	<structname>drm_file</structname> <structfield>driver_priv</structfield>
34099	field. Note that the <methodname>open</methodname> method is called
34100	before <methodname>firstopen</methodname>.
34101      </para>
34102      <para>
34103        The close operation is split into <methodname>preclose</methodname> and
34104	<methodname>postclose</methodname> methods. Drivers must stop and
34105	cleanup all per-file operations in the <methodname>preclose</methodname>
34106	method. For instance pending vertical blanking and page flip events must
34107	be cancelled. No per-file operation is allowed on the file handle after
34108	returning from the <methodname>preclose</methodname> method.
34109      </para>
34110      <para>
34111        Finally the <methodname>postclose</methodname> method is called as the
34112	last step of the close operation, right before calling the
34113	<methodname>lastclose</methodname> method if no other open file handle
34114	exists for the device. Drivers that have allocated per-file private data
34115	in the <methodname>open</methodname> method should free it here.
34116      </para>
34117      <para>
34118        The <methodname>lastclose</methodname> method should restore CRTC and
34119	plane properties to default value, so that a subsequent open of the
34120	device will not inherit state from the previous user. It can also be
34121	used to execute delayed power switching state changes, e.g. in
34122	conjunction with the vga-switcheroo infrastructure. Beyond that KMS
34123	drivers should not do any further cleanup. Only legacy UMS drivers might
34124	need to clean up device state so that the vga console or an independent
34125	fbdev driver could take over.
34126      </para>
34127    </sect2>
34128    <sect2>
34129      <title>File Operations</title>
34130      <synopsis>const struct file_operations *fops</synopsis>
34131      <abstract>File operations for the DRM device node.</abstract>
34132      <para>
34133        Drivers must define the file operations structure that forms the DRM
34134	userspace API entry point, even though most of those operations are
34135	implemented in the DRM core. The <methodname>open</methodname>,
34136	<methodname>release</methodname> and <methodname>ioctl</methodname>
34137	operations are handled by
34138	<programlisting>
34139	.owner = THIS_MODULE,
34140	.open = drm_open,
34141	.release = drm_release,
34142	.unlocked_ioctl = drm_ioctl,
34143  #ifdef CONFIG_COMPAT
34144	.compat_ioctl = drm_compat_ioctl,
34145  #endif
34146        </programlisting>
34147      </para>
34148      <para>
34149        Drivers that implement private ioctls that requires 32/64bit
34150	compatibility support must provide their own
34151	<methodname>compat_ioctl</methodname> handler that processes private
34152	ioctls and calls <function>drm_compat_ioctl</function> for core ioctls.
34153      </para>
34154      <para>
34155        The <methodname>read</methodname> and <methodname>poll</methodname>
34156	operations provide support for reading DRM events and polling them. They
34157	are implemented by
34158	<programlisting>
34159	.poll = drm_poll,
34160	.read = drm_read,
34161	.llseek = no_llseek,
34162	</programlisting>
34163      </para>
34164      <para>
34165        The memory mapping implementation varies depending on how the driver
34166	manages memory. Pre-GEM drivers will use <function>drm_mmap</function>,
34167	while GEM-aware drivers will use <function>drm_gem_mmap</function>. See
34168	<xref linkend="drm-gem"/>.
34169	<programlisting>
34170	.mmap = drm_gem_mmap,
34171	</programlisting>
34172      </para>
34173      <para>
34174        No other file operation is supported by the DRM API.
34175      </para>
34176    </sect2>
34177    <sect2>
34178      <title>IOCTLs</title>
34179      <synopsis>struct drm_ioctl_desc *ioctls;
34180int num_ioctls;</synopsis>
34181      <abstract>Driver-specific ioctls descriptors table.</abstract>
34182      <para>
34183        Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls
34184	descriptors table is indexed by the ioctl number offset from the base
34185	value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the
34186	table entries.
34187      </para>
34188      <para>
34189        <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting>
34190	<para>
34191	  <parameter>ioctl</parameter> is the ioctl name. Drivers must define
34192	  the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number
34193	  offset from DRM_COMMAND_BASE and the ioctl number respectively. The
34194	  first macro is private to the device while the second must be exposed
34195	  to userspace in a public header.
34196	</para>
34197	<para>
34198	  <parameter>func</parameter> is a pointer to the ioctl handler function
34199	  compatible with the <type>drm_ioctl_t</type> type.
34200	  <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data,
34201		struct drm_file *file_priv);</programlisting>
34202	</para>
34203	<para>
34204	  <parameter>flags</parameter> is a bitmask combination of the following
34205	  values. It restricts how the ioctl is allowed to be called.
34206	  <itemizedlist>
34207	    <listitem><para>
34208	      DRM_AUTH - Only authenticated callers allowed
34209	    </para></listitem>
34210	    <listitem><para>
34211	      DRM_MASTER - The ioctl can only be called on the master file
34212	      handle
34213	    </para></listitem>
34214            <listitem><para>
34215	      DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed
34216	    </para></listitem>
34217            <listitem><para>
34218	      DRM_CONTROL_ALLOW - The ioctl can only be called on a control
34219	      device
34220	    </para></listitem>
34221            <listitem><para>
34222	      DRM_UNLOCKED - The ioctl handler will be called without locking
34223	      the DRM global mutex
34224	    </para></listitem>
34225	  </itemizedlist>
34226	</para>
34227      </para>
34228    </sect2>
34229  </sect1>
34230  <sect1>
34231    <title>Legacy Support Code</title>
34232    <para>
34233      The section very briefly covers some of the old legacy support code which
34234      is only used by old DRM drivers which have done a so-called shadow-attach
34235      to the underlying device instead of registering as a real driver. This
34236      also includes some of the old generic buffer management and command
34237      submission code. Do not use any of this in new and modern drivers.
34238    </para>
34239
34240    <sect2>
34241      <title>Legacy Suspend/Resume</title>
34242      <para>
34243	The DRM core provides some suspend/resume code, but drivers wanting full
34244	suspend/resume support should provide save() and restore() functions.
34245	These are called at suspend, hibernate, or resume time, and should perform
34246	any state save or restore required by your device across suspend or
34247	hibernate states.
34248      </para>
34249      <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);
34250  int (*resume) (struct drm_device *);</synopsis>
34251      <para>
34252	Those are legacy suspend and resume methods which
34253	<emphasis>only</emphasis> work with the legacy shadow-attach driver
34254	registration functions. New driver should use the power management
34255	interface provided by their bus type (usually through
34256	the struct <structname>device_driver</structname> dev_pm_ops) and set
34257	these methods to NULL.
34258      </para>
34259    </sect2>
34260
34261    <sect2>
34262      <title>Legacy DMA Services</title>
34263      <para>
34264	This should cover how DMA mapping etc. is supported by the core.
34265	These functions are deprecated and should not be used.
34266      </para>
34267    </sect2>
34268  </sect1>
34269  </chapter>
34270
34271<!-- TODO
34272
34273- Add a glossary
34274- Document the struct_mutex catch-all lock
34275- Document connector properties
34276
34277- Why is the load method optional?
34278- What are drivers supposed to set the initial display state to, and how?
34279  Connector's DPMS states are not initialized and are thus equal to
34280  DRM_MODE_DPMS_ON. The fbcon compatibility layer calls
34281  drm_helper_disable_unused_functions(), which disables unused encoders and
34282  CRTCs, but doesn't touch the connectors' DPMS state, and
34283  drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers
34284  that don't implement (or just don't use) fbcon compatibility need to call
34285  those functions themselves?
34286- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset()
34287  around mode setting. Should this be done in the DRM core?
34288- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset()
34289  call and never set back to 0. It seems to be safe to permanently set it to 1
34290  in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as
34291  well. This should be investigated.
34292- crtc and connector .save and .restore operations are only used internally in
34293  drivers, should they be removed from the core?
34294- encoder mid-layer .save and .restore operations are only used internally in
34295  drivers, should they be removed from the core?
34296- encoder mid-layer .detect operation is only used internally in drivers,
34297  should it be removed from the core?
34298-->
34299
34300  <!-- External interfaces -->
34301
34302  <chapter id="drmExternals">
34303    <title>Userland interfaces</title>
34304    <para>
34305      The DRM core exports several interfaces to applications,
34306      generally intended to be used through corresponding libdrm
34307      wrapper functions.  In addition, drivers export device-specific
34308      interfaces for use by userspace drivers &amp; device-aware
34309      applications through ioctls and sysfs files.
34310    </para>
34311    <para>
34312      External interfaces include: memory mapping, context management,
34313      DMA operations, AGP management, vblank control, fence
34314      management, memory management, and output management.
34315    </para>
34316    <para>
34317      Cover generic ioctls and sysfs layout here.  We only need high-level
34318      info, since man pages should cover the rest.
34319    </para>
34320
34321  <!-- External: render nodes -->
34322
34323    <sect1>
34324      <title>Render nodes</title>
34325      <para>
34326        DRM core provides multiple character-devices for user-space to use.
34327        Depending on which device is opened, user-space can perform a different
34328        set of operations (mainly ioctls). The primary node is always created
34329        and called card&lt;num&gt;. Additionally, a currently
34330        unused control node, called controlD&lt;num&gt; is also
34331        created. The primary node provides all legacy operations and
34332        historically was the only interface used by userspace. With KMS, the
34333        control node was introduced. However, the planned KMS control interface
34334        has never been written and so the control node stays unused to date.
34335      </para>
34336      <para>
34337        With the increased use of offscreen renderers and GPGPU applications,
34338        clients no longer require running compositors or graphics servers to
34339        make use of a GPU. But the DRM API required unprivileged clients to
34340        authenticate to a DRM-Master prior to getting GPU access. To avoid this
34341        step and to grant clients GPU access without authenticating, render
34342        nodes were introduced. Render nodes solely serve render clients, that
34343        is, no modesetting or privileged ioctls can be issued on render nodes.
34344        Only non-global rendering commands are allowed. If a driver supports
34345        render nodes, it must advertise it via the DRIVER_RENDER
34346        DRM driver capability. If not supported, the primary node must be used
34347        for render clients together with the legacy drmAuth authentication
34348        procedure.
34349      </para>
34350      <para>
34351        If a driver advertises render node support, DRM core will create a
34352        separate render node called renderD&lt;num&gt;. There will
34353        be one render node per device. No ioctls except  PRIME-related ioctls
34354        will be allowed on this node. Especially GEM_OPEN will be
34355        explicitly prohibited. Render nodes are designed to avoid the
34356        buffer-leaks, which occur if clients guess the flink names or mmap
34357        offsets on the legacy interface. Additionally to this basic interface,
34358        drivers must mark their driver-dependent render-only ioctls as
34359        DRM_RENDER_ALLOW so render clients can use them. Driver
34360        authors must be careful not to allow any privileged ioctls on render
34361        nodes.
34362      </para>
34363      <para>
34364        With render nodes, user-space can now control access to the render node
34365        via basic file-system access-modes. A running graphics server which
34366        authenticates clients on the privileged primary/legacy node is no longer
34367        required. Instead, a client can open the render node and is immediately
34368        granted GPU access. Communication between clients (or servers) is done
34369        via PRIME. FLINK from render node to legacy node is not supported. New
34370        clients must not use the insecure FLINK interface.
34371      </para>
34372      <para>
34373        Besides dropping all modeset/global ioctls, render nodes also drop the
34374        DRM-Master concept. There is no reason to associate render clients with
34375        a DRM-Master as they are independent of any graphics server. Besides,
34376        they must work without any running master, anyway.
34377        Drivers must be able to run without a master object if they support
34378        render nodes. If, on the other hand, a driver requires shared state
34379        between clients which is visible to user-space and accessible beyond
34380        open-file boundaries, they cannot support render nodes.
34381      </para>
34382    </sect1>
34383
34384  <!-- External: vblank handling -->
34385
34386    <sect1>
34387      <title>VBlank event handling</title>
34388      <para>
34389        The DRM core exposes two vertical blank related ioctls:
34390        <variablelist>
34391          <varlistentry>
34392            <term>DRM_IOCTL_WAIT_VBLANK</term>
34393            <listitem>
34394              <para>
34395                This takes a struct drm_wait_vblank structure as its argument,
34396                and it is used to block or request a signal when a specified
34397                vblank event occurs.
34398              </para>
34399            </listitem>
34400          </varlistentry>
34401          <varlistentry>
34402            <term>DRM_IOCTL_MODESET_CTL</term>
34403            <listitem>
34404              <para>
34405		This was only used for user-mode-settind drivers around
34406		modesetting changes to allow the kernel to update the vblank
34407		interrupt after mode setting, since on many devices the vertical
34408		blank counter is reset to 0 at some point during modeset. Modern
34409		drivers should not call this any more since with kernel mode
34410		setting it is a no-op.
34411              </para>
34412            </listitem>
34413          </varlistentry>
34414        </variablelist>
34415      </para>
34416    </sect1>
34417
34418  </chapter>
34419</part>
34420<part id="drmDrivers">
34421  <title>DRM Drivers</title>
34422
34423  <partintro>
34424    <para>
34425      This second part of the DRM Developer's Guide documents driver code,
34426      implementation details and also all the driver-specific userspace
34427      interfaces. Especially since all hardware-acceleration interfaces to
34428      userspace are driver specific for efficiency and other reasons these
34429      interfaces can be rather substantial. Hence every driver has its own
34430      chapter.
34431    </para>
34432  </partintro>
34433
34434  <chapter id="drmI915">
34435    <title>drm/i915 Intel GFX Driver</title>
34436    <para>
34437      The drm/i915 driver supports all (with the exception of some very early
34438      models) integrated GFX chipsets with both Intel display and rendering
34439      blocks. This excludes a set of SoC platforms with an SGX rendering unit,
34440      those have basic support through the gma500 drm driver.
34441    </para>
34442    <sect1>
34443      <title>Core Driver Infrastructure</title>
34444      <para>
34445	This section covers core driver infrastructure used by both the display
34446	and the GEM parts of the driver.
34447      </para>
34448      <sect2>
34449        <title>Runtime Power Management</title>
34450<para>
34451   </para><para>
34452   The i915 driver supports dynamic enabling and disabling of entire hardware
34453   blocks at runtime. This is especially important on the display side where
34454   software is supposed to control many power gates manually on recent hardware,
34455   since on the GT side a lot of the power management is done by the hardware.
34456   But even there some manual control at the device level is required.
34457   </para><para>
34458   Since i915 supports a diverse set of platforms with a unified codebase and
34459   hardware engineers just love to shuffle functionality around between power
34460   domains there's a sizeable amount of indirection required. This file provides
34461   generic functions to the driver for grabbing and releasing references for
34462   abstract power domains. It then maps those to the actual power wells
34463   present for a given platform.
34464</para>
34465
34466<!-- drivers/gpu/drm/i915/intel_runtime_pm.c -->
34467<refentry id="API---intel-display-power-is-enabled">
34468<refentryinfo>
34469 <title>LINUX</title>
34470 <productname>Kernel Hackers Manual</productname>
34471 <date>July 2017</date>
34472</refentryinfo>
34473<refmeta>
34474 <refentrytitle><phrase>__intel_display_power_is_enabled</phrase></refentrytitle>
34475 <manvolnum>9</manvolnum>
34476 <refmiscinfo class="version">4.1.27</refmiscinfo>
34477</refmeta>
34478<refnamediv>
34479 <refname>__intel_display_power_is_enabled</refname>
34480 <refpurpose>
34481  unlocked check for a power domain
34482 </refpurpose>
34483</refnamediv>
34484<refsynopsisdiv>
34485 <title>Synopsis</title>
34486  <funcsynopsis><funcprototype>
34487   <funcdef>bool <function>__intel_display_power_is_enabled </function></funcdef>
34488   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34489   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
34490  </funcprototype></funcsynopsis>
34491</refsynopsisdiv>
34492<refsect1>
34493 <title>Arguments</title>
34494 <variablelist>
34495  <varlistentry>
34496   <term><parameter>dev_priv</parameter></term>
34497   <listitem>
34498    <para>
34499     i915 device instance
34500    </para>
34501   </listitem>
34502  </varlistentry>
34503  <varlistentry>
34504   <term><parameter>domain</parameter></term>
34505   <listitem>
34506    <para>
34507     power domain to check
34508    </para>
34509   </listitem>
34510  </varlistentry>
34511 </variablelist>
34512</refsect1>
34513<refsect1>
34514<title>Description</title>
34515<para>
34516   This is the unlocked version of <function>intel_display_power_is_enabled</function> and should
34517   only be used from error capture and recovery code where deadlocks are
34518   possible.
34519</para>
34520</refsect1>
34521<refsect1>
34522<title>Returns</title>
34523<para>
34524   True when the power domain is enabled, false otherwise.
34525</para>
34526</refsect1>
34527</refentry>
34528
34529<refentry id="API-intel-display-power-is-enabled">
34530<refentryinfo>
34531 <title>LINUX</title>
34532 <productname>Kernel Hackers Manual</productname>
34533 <date>July 2017</date>
34534</refentryinfo>
34535<refmeta>
34536 <refentrytitle><phrase>intel_display_power_is_enabled</phrase></refentrytitle>
34537 <manvolnum>9</manvolnum>
34538 <refmiscinfo class="version">4.1.27</refmiscinfo>
34539</refmeta>
34540<refnamediv>
34541 <refname>intel_display_power_is_enabled</refname>
34542 <refpurpose>
34543     check for a power domain
34544 </refpurpose>
34545</refnamediv>
34546<refsynopsisdiv>
34547 <title>Synopsis</title>
34548  <funcsynopsis><funcprototype>
34549   <funcdef>bool <function>intel_display_power_is_enabled </function></funcdef>
34550   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34551   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
34552  </funcprototype></funcsynopsis>
34553</refsynopsisdiv>
34554<refsect1>
34555 <title>Arguments</title>
34556 <variablelist>
34557  <varlistentry>
34558   <term><parameter>dev_priv</parameter></term>
34559   <listitem>
34560    <para>
34561     i915 device instance
34562    </para>
34563   </listitem>
34564  </varlistentry>
34565  <varlistentry>
34566   <term><parameter>domain</parameter></term>
34567   <listitem>
34568    <para>
34569     power domain to check
34570    </para>
34571   </listitem>
34572  </varlistentry>
34573 </variablelist>
34574</refsect1>
34575<refsect1>
34576<title>Description</title>
34577<para>
34578   This function can be used to check the hw power domain state. It is mostly
34579   used in hardware state readout functions. Everywhere else code should rely
34580   upon explicit power domain reference counting to ensure that the hardware
34581   block is powered up before accessing it.
34582   </para><para>
34583
34584   Callers must hold the relevant modesetting locks to ensure that concurrent
34585   threads can't disable the power well while the caller tries to read a few
34586   registers.
34587</para>
34588</refsect1>
34589<refsect1>
34590<title>Returns</title>
34591<para>
34592   True when the power domain is enabled, false otherwise.
34593</para>
34594</refsect1>
34595</refentry>
34596
34597<refentry id="API-intel-display-set-init-power">
34598<refentryinfo>
34599 <title>LINUX</title>
34600 <productname>Kernel Hackers Manual</productname>
34601 <date>July 2017</date>
34602</refentryinfo>
34603<refmeta>
34604 <refentrytitle><phrase>intel_display_set_init_power</phrase></refentrytitle>
34605 <manvolnum>9</manvolnum>
34606 <refmiscinfo class="version">4.1.27</refmiscinfo>
34607</refmeta>
34608<refnamediv>
34609 <refname>intel_display_set_init_power</refname>
34610 <refpurpose>
34611     set the initial power domain state
34612 </refpurpose>
34613</refnamediv>
34614<refsynopsisdiv>
34615 <title>Synopsis</title>
34616  <funcsynopsis><funcprototype>
34617   <funcdef>void <function>intel_display_set_init_power </function></funcdef>
34618   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34619   <paramdef>bool <parameter>enable</parameter></paramdef>
34620  </funcprototype></funcsynopsis>
34621</refsynopsisdiv>
34622<refsect1>
34623 <title>Arguments</title>
34624 <variablelist>
34625  <varlistentry>
34626   <term><parameter>dev_priv</parameter></term>
34627   <listitem>
34628    <para>
34629     i915 device instance
34630    </para>
34631   </listitem>
34632  </varlistentry>
34633  <varlistentry>
34634   <term><parameter>enable</parameter></term>
34635   <listitem>
34636    <para>
34637     whether to enable or disable the initial power domain state
34638    </para>
34639   </listitem>
34640  </varlistentry>
34641 </variablelist>
34642</refsect1>
34643<refsect1>
34644<title>Description</title>
34645<para>
34646   For simplicity our driver load/unload and system suspend/resume code assumes
34647   that all power domains are always enabled. This functions controls the state
34648   of this little hack. While the initial power domain state is enabled runtime
34649   pm is effectively disabled.
34650</para>
34651</refsect1>
34652</refentry>
34653
34654<refentry id="API-intel-display-power-get">
34655<refentryinfo>
34656 <title>LINUX</title>
34657 <productname>Kernel Hackers Manual</productname>
34658 <date>July 2017</date>
34659</refentryinfo>
34660<refmeta>
34661 <refentrytitle><phrase>intel_display_power_get</phrase></refentrytitle>
34662 <manvolnum>9</manvolnum>
34663 <refmiscinfo class="version">4.1.27</refmiscinfo>
34664</refmeta>
34665<refnamediv>
34666 <refname>intel_display_power_get</refname>
34667 <refpurpose>
34668     grab a power domain reference
34669 </refpurpose>
34670</refnamediv>
34671<refsynopsisdiv>
34672 <title>Synopsis</title>
34673  <funcsynopsis><funcprototype>
34674   <funcdef>void <function>intel_display_power_get </function></funcdef>
34675   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34676   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
34677  </funcprototype></funcsynopsis>
34678</refsynopsisdiv>
34679<refsect1>
34680 <title>Arguments</title>
34681 <variablelist>
34682  <varlistentry>
34683   <term><parameter>dev_priv</parameter></term>
34684   <listitem>
34685    <para>
34686     i915 device instance
34687    </para>
34688   </listitem>
34689  </varlistentry>
34690  <varlistentry>
34691   <term><parameter>domain</parameter></term>
34692   <listitem>
34693    <para>
34694     power domain to reference
34695    </para>
34696   </listitem>
34697  </varlistentry>
34698 </variablelist>
34699</refsect1>
34700<refsect1>
34701<title>Description</title>
34702<para>
34703   This function grabs a power domain reference for <parameter>domain</parameter> and ensures that the
34704   power domain and all its parents are powered up. Therefore users should only
34705   grab a reference to the innermost power domain they need.
34706   </para><para>
34707
34708   Any power domain reference obtained by this function must have a symmetric
34709   call to <function>intel_display_power_put</function> to release the reference again.
34710</para>
34711</refsect1>
34712</refentry>
34713
34714<refentry id="API-intel-display-power-put">
34715<refentryinfo>
34716 <title>LINUX</title>
34717 <productname>Kernel Hackers Manual</productname>
34718 <date>July 2017</date>
34719</refentryinfo>
34720<refmeta>
34721 <refentrytitle><phrase>intel_display_power_put</phrase></refentrytitle>
34722 <manvolnum>9</manvolnum>
34723 <refmiscinfo class="version">4.1.27</refmiscinfo>
34724</refmeta>
34725<refnamediv>
34726 <refname>intel_display_power_put</refname>
34727 <refpurpose>
34728     release a power domain reference
34729 </refpurpose>
34730</refnamediv>
34731<refsynopsisdiv>
34732 <title>Synopsis</title>
34733  <funcsynopsis><funcprototype>
34734   <funcdef>void <function>intel_display_power_put </function></funcdef>
34735   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34736   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
34737  </funcprototype></funcsynopsis>
34738</refsynopsisdiv>
34739<refsect1>
34740 <title>Arguments</title>
34741 <variablelist>
34742  <varlistentry>
34743   <term><parameter>dev_priv</parameter></term>
34744   <listitem>
34745    <para>
34746     i915 device instance
34747    </para>
34748   </listitem>
34749  </varlistentry>
34750  <varlistentry>
34751   <term><parameter>domain</parameter></term>
34752   <listitem>
34753    <para>
34754     power domain to reference
34755    </para>
34756   </listitem>
34757  </varlistentry>
34758 </variablelist>
34759</refsect1>
34760<refsect1>
34761<title>Description</title>
34762<para>
34763   This function drops the power domain reference obtained by
34764   <function>intel_display_power_get</function> and might power down the corresponding hardware
34765   block right away if this is the last reference.
34766</para>
34767</refsect1>
34768</refentry>
34769
34770<refentry id="API-intel-power-domains-init">
34771<refentryinfo>
34772 <title>LINUX</title>
34773 <productname>Kernel Hackers Manual</productname>
34774 <date>July 2017</date>
34775</refentryinfo>
34776<refmeta>
34777 <refentrytitle><phrase>intel_power_domains_init</phrase></refentrytitle>
34778 <manvolnum>9</manvolnum>
34779 <refmiscinfo class="version">4.1.27</refmiscinfo>
34780</refmeta>
34781<refnamediv>
34782 <refname>intel_power_domains_init</refname>
34783 <refpurpose>
34784     initializes the power domain structures
34785 </refpurpose>
34786</refnamediv>
34787<refsynopsisdiv>
34788 <title>Synopsis</title>
34789  <funcsynopsis><funcprototype>
34790   <funcdef>int <function>intel_power_domains_init </function></funcdef>
34791   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34792  </funcprototype></funcsynopsis>
34793</refsynopsisdiv>
34794<refsect1>
34795 <title>Arguments</title>
34796 <variablelist>
34797  <varlistentry>
34798   <term><parameter>dev_priv</parameter></term>
34799   <listitem>
34800    <para>
34801     i915 device instance
34802    </para>
34803   </listitem>
34804  </varlistentry>
34805 </variablelist>
34806</refsect1>
34807<refsect1>
34808<title>Description</title>
34809<para>
34810   Initializes the power domain structures for <parameter>dev_priv</parameter> depending upon the
34811   supported platform.
34812</para>
34813</refsect1>
34814</refentry>
34815
34816<refentry id="API-intel-power-domains-fini">
34817<refentryinfo>
34818 <title>LINUX</title>
34819 <productname>Kernel Hackers Manual</productname>
34820 <date>July 2017</date>
34821</refentryinfo>
34822<refmeta>
34823 <refentrytitle><phrase>intel_power_domains_fini</phrase></refentrytitle>
34824 <manvolnum>9</manvolnum>
34825 <refmiscinfo class="version">4.1.27</refmiscinfo>
34826</refmeta>
34827<refnamediv>
34828 <refname>intel_power_domains_fini</refname>
34829 <refpurpose>
34830     finalizes the power domain structures
34831 </refpurpose>
34832</refnamediv>
34833<refsynopsisdiv>
34834 <title>Synopsis</title>
34835  <funcsynopsis><funcprototype>
34836   <funcdef>void <function>intel_power_domains_fini </function></funcdef>
34837   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34838  </funcprototype></funcsynopsis>
34839</refsynopsisdiv>
34840<refsect1>
34841 <title>Arguments</title>
34842 <variablelist>
34843  <varlistentry>
34844   <term><parameter>dev_priv</parameter></term>
34845   <listitem>
34846    <para>
34847     i915 device instance
34848    </para>
34849   </listitem>
34850  </varlistentry>
34851 </variablelist>
34852</refsect1>
34853<refsect1>
34854<title>Description</title>
34855<para>
34856   Finalizes the power domain structures for <parameter>dev_priv</parameter> depending upon the
34857   supported platform. This function also disables runtime pm and ensures that
34858   the device stays powered up so that the driver can be reloaded.
34859</para>
34860</refsect1>
34861</refentry>
34862
34863<refentry id="API-intel-power-domains-init-hw">
34864<refentryinfo>
34865 <title>LINUX</title>
34866 <productname>Kernel Hackers Manual</productname>
34867 <date>July 2017</date>
34868</refentryinfo>
34869<refmeta>
34870 <refentrytitle><phrase>intel_power_domains_init_hw</phrase></refentrytitle>
34871 <manvolnum>9</manvolnum>
34872 <refmiscinfo class="version">4.1.27</refmiscinfo>
34873</refmeta>
34874<refnamediv>
34875 <refname>intel_power_domains_init_hw</refname>
34876 <refpurpose>
34877     initialize hardware power domain state
34878 </refpurpose>
34879</refnamediv>
34880<refsynopsisdiv>
34881 <title>Synopsis</title>
34882  <funcsynopsis><funcprototype>
34883   <funcdef>void <function>intel_power_domains_init_hw </function></funcdef>
34884   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34885  </funcprototype></funcsynopsis>
34886</refsynopsisdiv>
34887<refsect1>
34888 <title>Arguments</title>
34889 <variablelist>
34890  <varlistentry>
34891   <term><parameter>dev_priv</parameter></term>
34892   <listitem>
34893    <para>
34894     i915 device instance
34895    </para>
34896   </listitem>
34897  </varlistentry>
34898 </variablelist>
34899</refsect1>
34900<refsect1>
34901<title>Description</title>
34902<para>
34903   This function initializes the hardware power domain state and enables all
34904   power domains using <function>intel_display_set_init_power</function>.
34905</para>
34906</refsect1>
34907</refentry>
34908
34909<refentry id="API-intel-aux-display-runtime-get">
34910<refentryinfo>
34911 <title>LINUX</title>
34912 <productname>Kernel Hackers Manual</productname>
34913 <date>July 2017</date>
34914</refentryinfo>
34915<refmeta>
34916 <refentrytitle><phrase>intel_aux_display_runtime_get</phrase></refentrytitle>
34917 <manvolnum>9</manvolnum>
34918 <refmiscinfo class="version">4.1.27</refmiscinfo>
34919</refmeta>
34920<refnamediv>
34921 <refname>intel_aux_display_runtime_get</refname>
34922 <refpurpose>
34923     grab an auxiliary power domain reference
34924 </refpurpose>
34925</refnamediv>
34926<refsynopsisdiv>
34927 <title>Synopsis</title>
34928  <funcsynopsis><funcprototype>
34929   <funcdef>void <function>intel_aux_display_runtime_get </function></funcdef>
34930   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34931  </funcprototype></funcsynopsis>
34932</refsynopsisdiv>
34933<refsect1>
34934 <title>Arguments</title>
34935 <variablelist>
34936  <varlistentry>
34937   <term><parameter>dev_priv</parameter></term>
34938   <listitem>
34939    <para>
34940     i915 device instance
34941    </para>
34942   </listitem>
34943  </varlistentry>
34944 </variablelist>
34945</refsect1>
34946<refsect1>
34947<title>Description</title>
34948<para>
34949   This function grabs a power domain reference for the auxiliary power domain
34950   (for access to the GMBUS and DP AUX blocks) and ensures that it and all its
34951   parents are powered up. Therefore users should only grab a reference to the
34952   innermost power domain they need.
34953   </para><para>
34954
34955   Any power domain reference obtained by this function must have a symmetric
34956   call to <function>intel_aux_display_runtime_put</function> to release the reference again.
34957</para>
34958</refsect1>
34959</refentry>
34960
34961<refentry id="API-intel-aux-display-runtime-put">
34962<refentryinfo>
34963 <title>LINUX</title>
34964 <productname>Kernel Hackers Manual</productname>
34965 <date>July 2017</date>
34966</refentryinfo>
34967<refmeta>
34968 <refentrytitle><phrase>intel_aux_display_runtime_put</phrase></refentrytitle>
34969 <manvolnum>9</manvolnum>
34970 <refmiscinfo class="version">4.1.27</refmiscinfo>
34971</refmeta>
34972<refnamediv>
34973 <refname>intel_aux_display_runtime_put</refname>
34974 <refpurpose>
34975     release an auxiliary power domain reference
34976 </refpurpose>
34977</refnamediv>
34978<refsynopsisdiv>
34979 <title>Synopsis</title>
34980  <funcsynopsis><funcprototype>
34981   <funcdef>void <function>intel_aux_display_runtime_put </function></funcdef>
34982   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
34983  </funcprototype></funcsynopsis>
34984</refsynopsisdiv>
34985<refsect1>
34986 <title>Arguments</title>
34987 <variablelist>
34988  <varlistentry>
34989   <term><parameter>dev_priv</parameter></term>
34990   <listitem>
34991    <para>
34992     i915 device instance
34993    </para>
34994   </listitem>
34995  </varlistentry>
34996 </variablelist>
34997</refsect1>
34998<refsect1>
34999<title>Description</title>
35000<para>
35001   This function drops the auxiliary power domain reference obtained by
35002   <function>intel_aux_display_runtime_get</function> and might power down the corresponding
35003   hardware block right away if this is the last reference.
35004</para>
35005</refsect1>
35006</refentry>
35007
35008<refentry id="API-intel-runtime-pm-get">
35009<refentryinfo>
35010 <title>LINUX</title>
35011 <productname>Kernel Hackers Manual</productname>
35012 <date>July 2017</date>
35013</refentryinfo>
35014<refmeta>
35015 <refentrytitle><phrase>intel_runtime_pm_get</phrase></refentrytitle>
35016 <manvolnum>9</manvolnum>
35017 <refmiscinfo class="version">4.1.27</refmiscinfo>
35018</refmeta>
35019<refnamediv>
35020 <refname>intel_runtime_pm_get</refname>
35021 <refpurpose>
35022     grab a runtime pm reference
35023 </refpurpose>
35024</refnamediv>
35025<refsynopsisdiv>
35026 <title>Synopsis</title>
35027  <funcsynopsis><funcprototype>
35028   <funcdef>void <function>intel_runtime_pm_get </function></funcdef>
35029   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35030  </funcprototype></funcsynopsis>
35031</refsynopsisdiv>
35032<refsect1>
35033 <title>Arguments</title>
35034 <variablelist>
35035  <varlistentry>
35036   <term><parameter>dev_priv</parameter></term>
35037   <listitem>
35038    <para>
35039     i915 device instance
35040    </para>
35041   </listitem>
35042  </varlistentry>
35043 </variablelist>
35044</refsect1>
35045<refsect1>
35046<title>Description</title>
35047<para>
35048   This function grabs a device-level runtime pm reference (mostly used for GEM
35049   code to ensure the GTT or GT is on) and ensures that it is powered up.
35050   </para><para>
35051
35052   Any runtime pm reference obtained by this function must have a symmetric
35053   call to <function>intel_runtime_pm_put</function> to release the reference again.
35054</para>
35055</refsect1>
35056</refentry>
35057
35058<refentry id="API-intel-runtime-pm-get-noresume">
35059<refentryinfo>
35060 <title>LINUX</title>
35061 <productname>Kernel Hackers Manual</productname>
35062 <date>July 2017</date>
35063</refentryinfo>
35064<refmeta>
35065 <refentrytitle><phrase>intel_runtime_pm_get_noresume</phrase></refentrytitle>
35066 <manvolnum>9</manvolnum>
35067 <refmiscinfo class="version">4.1.27</refmiscinfo>
35068</refmeta>
35069<refnamediv>
35070 <refname>intel_runtime_pm_get_noresume</refname>
35071 <refpurpose>
35072     grab a runtime pm reference
35073 </refpurpose>
35074</refnamediv>
35075<refsynopsisdiv>
35076 <title>Synopsis</title>
35077  <funcsynopsis><funcprototype>
35078   <funcdef>void <function>intel_runtime_pm_get_noresume </function></funcdef>
35079   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35080  </funcprototype></funcsynopsis>
35081</refsynopsisdiv>
35082<refsect1>
35083 <title>Arguments</title>
35084 <variablelist>
35085  <varlistentry>
35086   <term><parameter>dev_priv</parameter></term>
35087   <listitem>
35088    <para>
35089     i915 device instance
35090    </para>
35091   </listitem>
35092  </varlistentry>
35093 </variablelist>
35094</refsect1>
35095<refsect1>
35096<title>Description</title>
35097<para>
35098   This function grabs a device-level runtime pm reference (mostly used for GEM
35099   code to ensure the GTT or GT is on).
35100   </para><para>
35101
35102   It will _not_ power up the device but instead only check that it's powered
35103   on.  Therefore it is only valid to call this functions from contexts where
35104   the device is known to be powered up and where trying to power it up would
35105   result in hilarity and deadlocks. That pretty much means only the system
35106   suspend/resume code where this is used to grab runtime pm references for
35107   delayed setup down in work items.
35108   </para><para>
35109
35110   Any runtime pm reference obtained by this function must have a symmetric
35111   call to <function>intel_runtime_pm_put</function> to release the reference again.
35112</para>
35113</refsect1>
35114</refentry>
35115
35116<refentry id="API-intel-runtime-pm-put">
35117<refentryinfo>
35118 <title>LINUX</title>
35119 <productname>Kernel Hackers Manual</productname>
35120 <date>July 2017</date>
35121</refentryinfo>
35122<refmeta>
35123 <refentrytitle><phrase>intel_runtime_pm_put</phrase></refentrytitle>
35124 <manvolnum>9</manvolnum>
35125 <refmiscinfo class="version">4.1.27</refmiscinfo>
35126</refmeta>
35127<refnamediv>
35128 <refname>intel_runtime_pm_put</refname>
35129 <refpurpose>
35130     release a runtime pm reference
35131 </refpurpose>
35132</refnamediv>
35133<refsynopsisdiv>
35134 <title>Synopsis</title>
35135  <funcsynopsis><funcprototype>
35136   <funcdef>void <function>intel_runtime_pm_put </function></funcdef>
35137   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35138  </funcprototype></funcsynopsis>
35139</refsynopsisdiv>
35140<refsect1>
35141 <title>Arguments</title>
35142 <variablelist>
35143  <varlistentry>
35144   <term><parameter>dev_priv</parameter></term>
35145   <listitem>
35146    <para>
35147     i915 device instance
35148    </para>
35149   </listitem>
35150  </varlistentry>
35151 </variablelist>
35152</refsect1>
35153<refsect1>
35154<title>Description</title>
35155<para>
35156   This function drops the device-level runtime pm reference obtained by
35157   <function>intel_runtime_pm_get</function> and might power down the corresponding
35158   hardware block right away if this is the last reference.
35159</para>
35160</refsect1>
35161</refentry>
35162
35163<refentry id="API-intel-runtime-pm-enable">
35164<refentryinfo>
35165 <title>LINUX</title>
35166 <productname>Kernel Hackers Manual</productname>
35167 <date>July 2017</date>
35168</refentryinfo>
35169<refmeta>
35170 <refentrytitle><phrase>intel_runtime_pm_enable</phrase></refentrytitle>
35171 <manvolnum>9</manvolnum>
35172 <refmiscinfo class="version">4.1.27</refmiscinfo>
35173</refmeta>
35174<refnamediv>
35175 <refname>intel_runtime_pm_enable</refname>
35176 <refpurpose>
35177     enable runtime pm
35178 </refpurpose>
35179</refnamediv>
35180<refsynopsisdiv>
35181 <title>Synopsis</title>
35182  <funcsynopsis><funcprototype>
35183   <funcdef>void <function>intel_runtime_pm_enable </function></funcdef>
35184   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35185  </funcprototype></funcsynopsis>
35186</refsynopsisdiv>
35187<refsect1>
35188 <title>Arguments</title>
35189 <variablelist>
35190  <varlistentry>
35191   <term><parameter>dev_priv</parameter></term>
35192   <listitem>
35193    <para>
35194     i915 device instance
35195    </para>
35196   </listitem>
35197  </varlistentry>
35198 </variablelist>
35199</refsect1>
35200<refsect1>
35201<title>Description</title>
35202<para>
35203   This function enables runtime pm at the end of the driver load sequence.
35204   </para><para>
35205
35206   Note that this function does currently not enable runtime pm for the
35207   subordinate display power domains. That is only done on the first modeset
35208   using <function>intel_display_set_init_power</function>.
35209</para>
35210</refsect1>
35211</refentry>
35212
35213<!-- drivers/gpu/drm/i915/intel_uncore.c -->
35214<refentry id="API-intel-uncore-forcewake-get">
35215<refentryinfo>
35216 <title>LINUX</title>
35217 <productname>Kernel Hackers Manual</productname>
35218 <date>July 2017</date>
35219</refentryinfo>
35220<refmeta>
35221 <refentrytitle><phrase>intel_uncore_forcewake_get</phrase></refentrytitle>
35222 <manvolnum>9</manvolnum>
35223 <refmiscinfo class="version">4.1.27</refmiscinfo>
35224</refmeta>
35225<refnamediv>
35226 <refname>intel_uncore_forcewake_get</refname>
35227 <refpurpose>
35228  grab forcewake domain references
35229 </refpurpose>
35230</refnamediv>
35231<refsynopsisdiv>
35232 <title>Synopsis</title>
35233  <funcsynopsis><funcprototype>
35234   <funcdef>void <function>intel_uncore_forcewake_get </function></funcdef>
35235   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35236   <paramdef>enum forcewake_domains <parameter>fw_domains</parameter></paramdef>
35237  </funcprototype></funcsynopsis>
35238</refsynopsisdiv>
35239<refsect1>
35240 <title>Arguments</title>
35241 <variablelist>
35242  <varlistentry>
35243   <term><parameter>dev_priv</parameter></term>
35244   <listitem>
35245    <para>
35246     i915 device instance
35247    </para>
35248   </listitem>
35249  </varlistentry>
35250  <varlistentry>
35251   <term><parameter>fw_domains</parameter></term>
35252   <listitem>
35253    <para>
35254     forcewake domains to get reference on
35255    </para>
35256   </listitem>
35257  </varlistentry>
35258 </variablelist>
35259</refsect1>
35260<refsect1>
35261<title>Description</title>
35262<para>
35263   This function can be used get GT's forcewake domain references.
35264   Normal register access will handle the forcewake domains automatically.
35265   However if some sequence requires the GT to not power down a particular
35266   forcewake domains this function should be called at the beginning of the
35267   sequence. And subsequently the reference should be dropped by symmetric
35268   call to <function>intel_unforce_forcewake_put</function>. Usually caller wants all the domains
35269   to be kept awake so the <parameter>fw_domains</parameter> would be then FORCEWAKE_ALL.
35270</para>
35271</refsect1>
35272</refentry>
35273
35274<refentry id="API-intel-uncore-forcewake-put">
35275<refentryinfo>
35276 <title>LINUX</title>
35277 <productname>Kernel Hackers Manual</productname>
35278 <date>July 2017</date>
35279</refentryinfo>
35280<refmeta>
35281 <refentrytitle><phrase>intel_uncore_forcewake_put</phrase></refentrytitle>
35282 <manvolnum>9</manvolnum>
35283 <refmiscinfo class="version">4.1.27</refmiscinfo>
35284</refmeta>
35285<refnamediv>
35286 <refname>intel_uncore_forcewake_put</refname>
35287 <refpurpose>
35288     release a forcewake domain reference
35289 </refpurpose>
35290</refnamediv>
35291<refsynopsisdiv>
35292 <title>Synopsis</title>
35293  <funcsynopsis><funcprototype>
35294   <funcdef>void <function>intel_uncore_forcewake_put </function></funcdef>
35295   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35296   <paramdef>enum forcewake_domains <parameter>fw_domains</parameter></paramdef>
35297  </funcprototype></funcsynopsis>
35298</refsynopsisdiv>
35299<refsect1>
35300 <title>Arguments</title>
35301 <variablelist>
35302  <varlistentry>
35303   <term><parameter>dev_priv</parameter></term>
35304   <listitem>
35305    <para>
35306     i915 device instance
35307    </para>
35308   </listitem>
35309  </varlistentry>
35310  <varlistentry>
35311   <term><parameter>fw_domains</parameter></term>
35312   <listitem>
35313    <para>
35314     forcewake domains to put references
35315    </para>
35316   </listitem>
35317  </varlistentry>
35318 </variablelist>
35319</refsect1>
35320<refsect1>
35321<title>Description</title>
35322<para>
35323   This function drops the device-level forcewakes for specified
35324   domains obtained by <function>intel_uncore_forcewake_get</function>.
35325</para>
35326</refsect1>
35327</refentry>
35328
35329      </sect2>
35330      <sect2>
35331        <title>Interrupt Handling</title>
35332<para>
35333   </para><para>
35334   These functions provide the basic support for enabling and disabling the
35335   interrupt handling support. There's a lot more functionality in i915_irq.c
35336   and related files, but that will be described in separate chapters.
35337</para>
35338
35339<refentry id="API-intel-irq-init">
35340<refentryinfo>
35341 <title>LINUX</title>
35342 <productname>Kernel Hackers Manual</productname>
35343 <date>July 2017</date>
35344</refentryinfo>
35345<refmeta>
35346 <refentrytitle><phrase>intel_irq_init</phrase></refentrytitle>
35347 <manvolnum>9</manvolnum>
35348 <refmiscinfo class="version">4.1.27</refmiscinfo>
35349</refmeta>
35350<refnamediv>
35351 <refname>intel_irq_init</refname>
35352 <refpurpose>
35353  initializes irq support
35354 </refpurpose>
35355</refnamediv>
35356<refsynopsisdiv>
35357 <title>Synopsis</title>
35358  <funcsynopsis><funcprototype>
35359   <funcdef>void <function>intel_irq_init </function></funcdef>
35360   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35361  </funcprototype></funcsynopsis>
35362</refsynopsisdiv>
35363<refsect1>
35364 <title>Arguments</title>
35365 <variablelist>
35366  <varlistentry>
35367   <term><parameter>dev_priv</parameter></term>
35368   <listitem>
35369    <para>
35370     i915 device instance
35371    </para>
35372   </listitem>
35373  </varlistentry>
35374 </variablelist>
35375</refsect1>
35376<refsect1>
35377<title>Description</title>
35378<para>
35379   This function initializes all the irq support including work items, timers
35380   and all the vtables. It does not setup the interrupt itself though.
35381</para>
35382</refsect1>
35383</refentry>
35384
35385<refentry id="API-intel-hpd-init">
35386<refentryinfo>
35387 <title>LINUX</title>
35388 <productname>Kernel Hackers Manual</productname>
35389 <date>July 2017</date>
35390</refentryinfo>
35391<refmeta>
35392 <refentrytitle><phrase>intel_hpd_init</phrase></refentrytitle>
35393 <manvolnum>9</manvolnum>
35394 <refmiscinfo class="version">4.1.27</refmiscinfo>
35395</refmeta>
35396<refnamediv>
35397 <refname>intel_hpd_init</refname>
35398 <refpurpose>
35399     initializes and enables hpd support
35400 </refpurpose>
35401</refnamediv>
35402<refsynopsisdiv>
35403 <title>Synopsis</title>
35404  <funcsynopsis><funcprototype>
35405   <funcdef>void <function>intel_hpd_init </function></funcdef>
35406   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35407  </funcprototype></funcsynopsis>
35408</refsynopsisdiv>
35409<refsect1>
35410 <title>Arguments</title>
35411 <variablelist>
35412  <varlistentry>
35413   <term><parameter>dev_priv</parameter></term>
35414   <listitem>
35415    <para>
35416     i915 device instance
35417    </para>
35418   </listitem>
35419  </varlistentry>
35420 </variablelist>
35421</refsect1>
35422<refsect1>
35423<title>Description</title>
35424<para>
35425   This function enables the hotplug support. It requires that interrupts have
35426   already been enabled with <function>intel_irq_init_hw</function>. From this point on hotplug and
35427   poll request can run concurrently to other code, so locking rules must be
35428   obeyed.
35429   </para><para>
35430
35431   This is a separate step from interrupt enabling to simplify the locking rules
35432   in the driver load and resume code.
35433</para>
35434</refsect1>
35435</refentry>
35436
35437<refentry>
35438 <refnamediv>
35439  <refname>
35440   .//drivers/gpu/drm/i915/i915_irq.c
35441  </refname>
35442  <refpurpose>
35443   Document generation inconsistency
35444  </refpurpose>
35445 </refnamediv>
35446 <refsect1>
35447  <title>
35448   Oops
35449  </title>
35450  <warning>
35451   <para>
35452    The template for this document tried to insert
35453    the structured comment from the file
35454    <filename>.//drivers/gpu/drm/i915/i915_irq.c</filename> at this point,
35455    but none was found.
35456    This dummy section is inserted to allow
35457    generation to continue.
35458   </para>
35459  </warning>
35460 </refsect1>
35461</refentry>
35462<refentry id="API-intel-runtime-pm-disable-interrupts">
35463<refentryinfo>
35464 <title>LINUX</title>
35465 <productname>Kernel Hackers Manual</productname>
35466 <date>July 2017</date>
35467</refentryinfo>
35468<refmeta>
35469 <refentrytitle><phrase>intel_runtime_pm_disable_interrupts</phrase></refentrytitle>
35470 <manvolnum>9</manvolnum>
35471 <refmiscinfo class="version">4.1.27</refmiscinfo>
35472</refmeta>
35473<refnamediv>
35474 <refname>intel_runtime_pm_disable_interrupts</refname>
35475 <refpurpose>
35476  runtime interrupt disabling
35477 </refpurpose>
35478</refnamediv>
35479<refsynopsisdiv>
35480 <title>Synopsis</title>
35481  <funcsynopsis><funcprototype>
35482   <funcdef>void <function>intel_runtime_pm_disable_interrupts </function></funcdef>
35483   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35484  </funcprototype></funcsynopsis>
35485</refsynopsisdiv>
35486<refsect1>
35487 <title>Arguments</title>
35488 <variablelist>
35489  <varlistentry>
35490   <term><parameter>dev_priv</parameter></term>
35491   <listitem>
35492    <para>
35493     i915 device instance
35494    </para>
35495   </listitem>
35496  </varlistentry>
35497 </variablelist>
35498</refsect1>
35499<refsect1>
35500<title>Description</title>
35501<para>
35502   This function is used to disable interrupts at runtime, both in the runtime
35503   pm and the system suspend/resume code.
35504</para>
35505</refsect1>
35506</refentry>
35507
35508<refentry id="API-intel-runtime-pm-enable-interrupts">
35509<refentryinfo>
35510 <title>LINUX</title>
35511 <productname>Kernel Hackers Manual</productname>
35512 <date>July 2017</date>
35513</refentryinfo>
35514<refmeta>
35515 <refentrytitle><phrase>intel_runtime_pm_enable_interrupts</phrase></refentrytitle>
35516 <manvolnum>9</manvolnum>
35517 <refmiscinfo class="version">4.1.27</refmiscinfo>
35518</refmeta>
35519<refnamediv>
35520 <refname>intel_runtime_pm_enable_interrupts</refname>
35521 <refpurpose>
35522  runtime interrupt enabling
35523 </refpurpose>
35524</refnamediv>
35525<refsynopsisdiv>
35526 <title>Synopsis</title>
35527  <funcsynopsis><funcprototype>
35528   <funcdef>void <function>intel_runtime_pm_enable_interrupts </function></funcdef>
35529   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
35530  </funcprototype></funcsynopsis>
35531</refsynopsisdiv>
35532<refsect1>
35533 <title>Arguments</title>
35534 <variablelist>
35535  <varlistentry>
35536   <term><parameter>dev_priv</parameter></term>
35537   <listitem>
35538    <para>
35539     i915 device instance
35540    </para>
35541   </listitem>
35542  </varlistentry>
35543 </variablelist>
35544</refsect1>
35545<refsect1>
35546<title>Description</title>
35547<para>
35548   This function is used to enable interrupts at runtime, both in the runtime
35549   pm and the system suspend/resume code.
35550</para>
35551</refsect1>
35552</refentry>
35553
35554      </sect2>
35555      <sect2>
35556        <title>Intel GVT-g Guest Support(vGPU)</title>
35557<para>
35558   </para><para>
35559   Intel GVT-g is a graphics virtualization technology which shares the
35560   GPU among multiple virtual machines on a time-sharing basis. Each
35561   virtual machine is presented a virtual GPU (vGPU), which has equivalent
35562   features as the underlying physical GPU (pGPU), so i915 driver can run
35563   seamlessly in a virtual machine. This file provides vGPU specific
35564   optimizations when running in a virtual machine, to reduce the complexity
35565   of vGPU emulation and to improve the overall performance.
35566   </para><para>
35567   A primary function introduced here is so-called <quote>address space ballooning</quote>
35568   technique. Intel GVT-g partitions global graphics memory among multiple VMs,
35569   so each VM can directly access a portion of the memory without hypervisor's
35570   intervention, e.g. filling textures or queuing commands. However with the
35571   partitioning an unmodified i915 driver would assume a smaller graphics
35572   memory starting from address ZERO, then requires vGPU emulation module to
35573   translate the graphics address between 'guest view' and 'host view', for
35574   all registers and command opcodes which contain a graphics memory address.
35575   To reduce the complexity, Intel GVT-g introduces <quote>address space ballooning</quote>,
35576   by telling the exact partitioning knowledge to each guest i915 driver, which
35577   then reserves and prevents non-allocated portions from allocation. Thus vGPU
35578   emulation module only needs to scan and validate graphics addresses without
35579   complexity of address translation.
35580   </para><para>
35581</para>
35582
35583<!-- drivers/gpu/drm/i915/i915_vgpu.c -->
35584<refentry id="API-i915-check-vgpu">
35585<refentryinfo>
35586 <title>LINUX</title>
35587 <productname>Kernel Hackers Manual</productname>
35588 <date>July 2017</date>
35589</refentryinfo>
35590<refmeta>
35591 <refentrytitle><phrase>i915_check_vgpu</phrase></refentrytitle>
35592 <manvolnum>9</manvolnum>
35593 <refmiscinfo class="version">4.1.27</refmiscinfo>
35594</refmeta>
35595<refnamediv>
35596 <refname>i915_check_vgpu</refname>
35597 <refpurpose>
35598  detect virtual GPU
35599 </refpurpose>
35600</refnamediv>
35601<refsynopsisdiv>
35602 <title>Synopsis</title>
35603  <funcsynopsis><funcprototype>
35604   <funcdef>void <function>i915_check_vgpu </function></funcdef>
35605   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
35606  </funcprototype></funcsynopsis>
35607</refsynopsisdiv>
35608<refsect1>
35609 <title>Arguments</title>
35610 <variablelist>
35611  <varlistentry>
35612   <term><parameter>dev</parameter></term>
35613   <listitem>
35614    <para>
35615     drm device *
35616    </para>
35617   </listitem>
35618  </varlistentry>
35619 </variablelist>
35620</refsect1>
35621<refsect1>
35622<title>Description</title>
35623<para>
35624   This function is called at the initialization stage, to detect whether
35625   running on a vGPU.
35626</para>
35627</refsect1>
35628</refentry>
35629
35630<refentry id="API-intel-vgt-deballoon">
35631<refentryinfo>
35632 <title>LINUX</title>
35633 <productname>Kernel Hackers Manual</productname>
35634 <date>July 2017</date>
35635</refentryinfo>
35636<refmeta>
35637 <refentrytitle><phrase>intel_vgt_deballoon</phrase></refentrytitle>
35638 <manvolnum>9</manvolnum>
35639 <refmiscinfo class="version">4.1.27</refmiscinfo>
35640</refmeta>
35641<refnamediv>
35642 <refname>intel_vgt_deballoon</refname>
35643 <refpurpose>
35644     deballoon reserved graphics address trunks
35645 </refpurpose>
35646</refnamediv>
35647<refsynopsisdiv>
35648 <title>Synopsis</title>
35649  <funcsynopsis><funcprototype>
35650   <funcdef>void <function>intel_vgt_deballoon </function></funcdef>
35651   <paramdef> <parameter>void</parameter></paramdef>
35652  </funcprototype></funcsynopsis>
35653</refsynopsisdiv>
35654<refsect1>
35655 <title>Arguments</title>
35656 <variablelist>
35657  <varlistentry>
35658   <term><parameter>void</parameter></term>
35659   <listitem>
35660    <para>
35661     no arguments
35662    </para>
35663   </listitem>
35664  </varlistentry>
35665 </variablelist>
35666</refsect1>
35667<refsect1>
35668<title>Description</title>
35669<para>
35670   </para><para>
35671
35672   This function is called to deallocate the ballooned-out graphic memory, when
35673   driver is unloaded or when ballooning fails.
35674</para>
35675</refsect1>
35676</refentry>
35677
35678<refentry id="API-intel-vgt-balloon">
35679<refentryinfo>
35680 <title>LINUX</title>
35681 <productname>Kernel Hackers Manual</productname>
35682 <date>July 2017</date>
35683</refentryinfo>
35684<refmeta>
35685 <refentrytitle><phrase>intel_vgt_balloon</phrase></refentrytitle>
35686 <manvolnum>9</manvolnum>
35687 <refmiscinfo class="version">4.1.27</refmiscinfo>
35688</refmeta>
35689<refnamediv>
35690 <refname>intel_vgt_balloon</refname>
35691 <refpurpose>
35692     balloon out reserved graphics address trunks
35693 </refpurpose>
35694</refnamediv>
35695<refsynopsisdiv>
35696 <title>Synopsis</title>
35697  <funcsynopsis><funcprototype>
35698   <funcdef>int <function>intel_vgt_balloon </function></funcdef>
35699   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
35700  </funcprototype></funcsynopsis>
35701</refsynopsisdiv>
35702<refsect1>
35703 <title>Arguments</title>
35704 <variablelist>
35705  <varlistentry>
35706   <term><parameter>dev</parameter></term>
35707   <listitem>
35708    <para>
35709     drm device
35710    </para>
35711   </listitem>
35712  </varlistentry>
35713 </variablelist>
35714</refsect1>
35715<refsect1>
35716<title>Description</title>
35717<para>
35718   This function is called at the initialization stage, to balloon out the
35719   graphic address space allocated to other vGPUs, by marking these spaces as
35720   reserved. The ballooning related knowledge(starting address and size of
35721   the mappable/unmappable graphic memory) is described in the vgt_if structure
35722   in a reserved mmio range.
35723   </para><para>
35724
35725   To give an example, the drawing below depicts one typical scenario after
35726   ballooning. Here the vGPU1 has 2 pieces of graphic address spaces ballooned
35727   out each for the mappable and the non-mappable part. From the vGPU1 point of
35728   view, the total size is the same as the physical one, with the start address
35729   of its graphic space being zero. Yet there are some portions ballooned out(
35730   the shadow part, which are marked as reserved by drm allocator). From the
35731   host point of view, the graphic address space is partitioned by multiple
35732   vGPUs in different VMs.
35733   </para><para>
35734
35735   vGPU1 view         Host view
35736   0 ------&gt; +-----------+     +-----------+
35737   ^       |///////////|     |   vGPU3   |
35738   |       |///////////|     +-----------+
35739   |       |///////////|     |   vGPU2   |
35740   |       +-----------+     +-----------+
35741   mappable GM    | available | ==&gt; |   vGPU1   |
35742   |       +-----------+     +-----------+
35743   |       |///////////|     |           |
35744   v       |///////////|     |   Host    |
35745   +=======+===========+     +===========+
35746   ^       |///////////|     |   vGPU3   |
35747   |       |///////////|     +-----------+
35748   |       |///////////|     |   vGPU2   |
35749   |       +-----------+     +-----------+
35750   unmappable GM    | available | ==&gt; |   vGPU1   |
35751   |       +-----------+     +-----------+
35752   |       |///////////|     |           |
35753   |       |///////////|     |   Host    |
35754   v       |///////////|     |           |
35755   total GM size ------&gt; +-----------+     +-----------+
35756</para>
35757</refsect1>
35758<refsect1>
35759<title>Returns</title>
35760<para>
35761   zero on success, non-zero if configuration invalid or ballooning failed
35762</para>
35763</refsect1>
35764</refentry>
35765
35766      </sect2>
35767    </sect1>
35768    <sect1>
35769      <title>Display Hardware Handling</title>
35770      <para>
35771        This section covers everything related to the display hardware including
35772        the mode setting infrastructure, plane, sprite and cursor handling and
35773        display, output probing and related topics.
35774      </para>
35775      <sect2>
35776        <title>Mode Setting Infrastructure</title>
35777        <para>
35778          The i915 driver is thus far the only DRM driver which doesn't use the
35779          common DRM helper code to implement mode setting sequences. Thus it
35780          has its own tailor-made infrastructure for executing a display
35781          configuration change.
35782        </para>
35783      </sect2>
35784      <sect2>
35785        <title>Frontbuffer Tracking</title>
35786<para>
35787   </para><para>
35788   Many features require us to track changes to the currently active
35789   frontbuffer, especially rendering targeted at the frontbuffer.
35790   </para><para>
35791   To be able to do so GEM tracks frontbuffers using a bitmask for all possible
35792   frontbuffer slots through <function>i915_gem_track_fb</function>. The function in this file are
35793   then called when the contents of the frontbuffer are invalidated, when
35794   frontbuffer rendering has stopped again to flush out all the changes and when
35795   the frontbuffer is exchanged with a flip. Subsystems interested in
35796   frontbuffer changes (e.g. PSR, FBC, DRRS) should directly put their callbacks
35797   into the relevant places and filter for the frontbuffer slots that they are
35798   interested int.
35799   </para><para>
35800   On a high level there are two types of powersaving features. The first one
35801   work like a special cache (FBC and PSR) and are interested when they should
35802   stop caching and when to restart caching. This is done by placing callbacks
35803   into the invalidate and the flush functions: At invalidate the caching must
35804   be stopped and at flush time it can be restarted. And maybe they need to know
35805   when the frontbuffer changes (e.g. when the hw doesn't initiate an invalidate
35806   and flush on its own) which can be achieved with placing callbacks into the
35807   flip functions.
35808   </para><para>
35809   The other type of display power saving feature only cares about busyness
35810   (e.g. DRRS). In that case all three (invalidate, flush and flip) indicate
35811   busyness. There is no direct way to detect idleness. Instead an idle timer
35812   work delayed work should be started from the flush and flip functions and
35813   cancelled as soon as busyness is detected.
35814   </para><para>
35815   Note that there's also an older frontbuffer activity tracking scheme which
35816   just tracks general activity. This is done by the various mark_busy and
35817   mark_idle functions. For display power management features using these
35818   functions is deprecated and should be avoided.
35819</para>
35820
35821<!-- drivers/gpu/drm/i915/intel_frontbuffer.c -->
35822<refentry id="API-intel-mark-fb-busy">
35823<refentryinfo>
35824 <title>LINUX</title>
35825 <productname>Kernel Hackers Manual</productname>
35826 <date>July 2017</date>
35827</refentryinfo>
35828<refmeta>
35829 <refentrytitle><phrase>intel_mark_fb_busy</phrase></refentrytitle>
35830 <manvolnum>9</manvolnum>
35831 <refmiscinfo class="version">4.1.27</refmiscinfo>
35832</refmeta>
35833<refnamediv>
35834 <refname>intel_mark_fb_busy</refname>
35835 <refpurpose>
35836  mark given planes as busy
35837 </refpurpose>
35838</refnamediv>
35839<refsynopsisdiv>
35840 <title>Synopsis</title>
35841  <funcsynopsis><funcprototype>
35842   <funcdef>void <function>intel_mark_fb_busy </function></funcdef>
35843   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
35844   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
35845   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
35846  </funcprototype></funcsynopsis>
35847</refsynopsisdiv>
35848<refsect1>
35849 <title>Arguments</title>
35850 <variablelist>
35851  <varlistentry>
35852   <term><parameter>dev</parameter></term>
35853   <listitem>
35854    <para>
35855     DRM device
35856    </para>
35857   </listitem>
35858  </varlistentry>
35859  <varlistentry>
35860   <term><parameter>frontbuffer_bits</parameter></term>
35861   <listitem>
35862    <para>
35863     bits for the affected planes
35864    </para>
35865   </listitem>
35866  </varlistentry>
35867  <varlistentry>
35868   <term><parameter>ring</parameter></term>
35869   <listitem>
35870    <para>
35871     optional ring for asynchronous commands
35872    </para>
35873   </listitem>
35874  </varlistentry>
35875 </variablelist>
35876</refsect1>
35877<refsect1>
35878<title>Description</title>
35879<para>
35880   This function gets called every time the screen contents change. It can be
35881   used to keep e.g. the update rate at the nominal refresh rate with DRRS.
35882</para>
35883</refsect1>
35884</refentry>
35885
35886<refentry id="API-intel-fb-obj-invalidate">
35887<refentryinfo>
35888 <title>LINUX</title>
35889 <productname>Kernel Hackers Manual</productname>
35890 <date>July 2017</date>
35891</refentryinfo>
35892<refmeta>
35893 <refentrytitle><phrase>intel_fb_obj_invalidate</phrase></refentrytitle>
35894 <manvolnum>9</manvolnum>
35895 <refmiscinfo class="version">4.1.27</refmiscinfo>
35896</refmeta>
35897<refnamediv>
35898 <refname>intel_fb_obj_invalidate</refname>
35899 <refpurpose>
35900     invalidate frontbuffer object
35901 </refpurpose>
35902</refnamediv>
35903<refsynopsisdiv>
35904 <title>Synopsis</title>
35905  <funcsynopsis><funcprototype>
35906   <funcdef>void <function>intel_fb_obj_invalidate </function></funcdef>
35907   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
35908   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
35909   <paramdef>enum fb_op_origin <parameter>origin</parameter></paramdef>
35910  </funcprototype></funcsynopsis>
35911</refsynopsisdiv>
35912<refsect1>
35913 <title>Arguments</title>
35914 <variablelist>
35915  <varlistentry>
35916   <term><parameter>obj</parameter></term>
35917   <listitem>
35918    <para>
35919     GEM object to invalidate
35920    </para>
35921   </listitem>
35922  </varlistentry>
35923  <varlistentry>
35924   <term><parameter>ring</parameter></term>
35925   <listitem>
35926    <para>
35927     set for asynchronous rendering
35928    </para>
35929   </listitem>
35930  </varlistentry>
35931  <varlistentry>
35932   <term><parameter>origin</parameter></term>
35933   <listitem>
35934    <para>
35935     which operation caused the invalidation
35936    </para>
35937   </listitem>
35938  </varlistentry>
35939 </variablelist>
35940</refsect1>
35941<refsect1>
35942<title>Description</title>
35943<para>
35944   This function gets called every time rendering on the given object starts and
35945   frontbuffer caching (fbc, low refresh rate for DRRS, panel self refresh) must
35946   be invalidated. If <parameter>ring</parameter> is non-NULL any subsequent invalidation will be delayed
35947   until the rendering completes or a flip on this frontbuffer plane is
35948   scheduled.
35949</para>
35950</refsect1>
35951</refentry>
35952
35953<refentry id="API-intel-frontbuffer-flush">
35954<refentryinfo>
35955 <title>LINUX</title>
35956 <productname>Kernel Hackers Manual</productname>
35957 <date>July 2017</date>
35958</refentryinfo>
35959<refmeta>
35960 <refentrytitle><phrase>intel_frontbuffer_flush</phrase></refentrytitle>
35961 <manvolnum>9</manvolnum>
35962 <refmiscinfo class="version">4.1.27</refmiscinfo>
35963</refmeta>
35964<refnamediv>
35965 <refname>intel_frontbuffer_flush</refname>
35966 <refpurpose>
35967     flush frontbuffer
35968 </refpurpose>
35969</refnamediv>
35970<refsynopsisdiv>
35971 <title>Synopsis</title>
35972  <funcsynopsis><funcprototype>
35973   <funcdef>void <function>intel_frontbuffer_flush </function></funcdef>
35974   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
35975   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
35976  </funcprototype></funcsynopsis>
35977</refsynopsisdiv>
35978<refsect1>
35979 <title>Arguments</title>
35980 <variablelist>
35981  <varlistentry>
35982   <term><parameter>dev</parameter></term>
35983   <listitem>
35984    <para>
35985     DRM device
35986    </para>
35987   </listitem>
35988  </varlistentry>
35989  <varlistentry>
35990   <term><parameter>frontbuffer_bits</parameter></term>
35991   <listitem>
35992    <para>
35993     frontbuffer plane tracking bits
35994    </para>
35995   </listitem>
35996  </varlistentry>
35997 </variablelist>
35998</refsect1>
35999<refsect1>
36000<title>Description</title>
36001<para>
36002   This function gets called every time rendering on the given planes has
36003   completed and frontbuffer caching can be started again. Flushes will get
36004   delayed if they're blocked by some outstanding asynchronous rendering.
36005   </para><para>
36006
36007   Can be called without any locks held.
36008</para>
36009</refsect1>
36010</refentry>
36011
36012<refentry id="API-intel-fb-obj-flush">
36013<refentryinfo>
36014 <title>LINUX</title>
36015 <productname>Kernel Hackers Manual</productname>
36016 <date>July 2017</date>
36017</refentryinfo>
36018<refmeta>
36019 <refentrytitle><phrase>intel_fb_obj_flush</phrase></refentrytitle>
36020 <manvolnum>9</manvolnum>
36021 <refmiscinfo class="version">4.1.27</refmiscinfo>
36022</refmeta>
36023<refnamediv>
36024 <refname>intel_fb_obj_flush</refname>
36025 <refpurpose>
36026     flush frontbuffer object
36027 </refpurpose>
36028</refnamediv>
36029<refsynopsisdiv>
36030 <title>Synopsis</title>
36031  <funcsynopsis><funcprototype>
36032   <funcdef>void <function>intel_fb_obj_flush </function></funcdef>
36033   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
36034   <paramdef>bool <parameter>retire</parameter></paramdef>
36035  </funcprototype></funcsynopsis>
36036</refsynopsisdiv>
36037<refsect1>
36038 <title>Arguments</title>
36039 <variablelist>
36040  <varlistentry>
36041   <term><parameter>obj</parameter></term>
36042   <listitem>
36043    <para>
36044     GEM object to flush
36045    </para>
36046   </listitem>
36047  </varlistentry>
36048  <varlistentry>
36049   <term><parameter>retire</parameter></term>
36050   <listitem>
36051    <para>
36052     set when retiring asynchronous rendering
36053    </para>
36054   </listitem>
36055  </varlistentry>
36056 </variablelist>
36057</refsect1>
36058<refsect1>
36059<title>Description</title>
36060<para>
36061   This function gets called every time rendering on the given object has
36062   completed and frontbuffer caching can be started again. If <parameter>retire</parameter> is true
36063   then any delayed flushes will be unblocked.
36064</para>
36065</refsect1>
36066</refentry>
36067
36068<refentry id="API-intel-frontbuffer-flip-prepare">
36069<refentryinfo>
36070 <title>LINUX</title>
36071 <productname>Kernel Hackers Manual</productname>
36072 <date>July 2017</date>
36073</refentryinfo>
36074<refmeta>
36075 <refentrytitle><phrase>intel_frontbuffer_flip_prepare</phrase></refentrytitle>
36076 <manvolnum>9</manvolnum>
36077 <refmiscinfo class="version">4.1.27</refmiscinfo>
36078</refmeta>
36079<refnamediv>
36080 <refname>intel_frontbuffer_flip_prepare</refname>
36081 <refpurpose>
36082     prepare asynchronous frontbuffer flip
36083 </refpurpose>
36084</refnamediv>
36085<refsynopsisdiv>
36086 <title>Synopsis</title>
36087  <funcsynopsis><funcprototype>
36088   <funcdef>void <function>intel_frontbuffer_flip_prepare </function></funcdef>
36089   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
36090   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
36091  </funcprototype></funcsynopsis>
36092</refsynopsisdiv>
36093<refsect1>
36094 <title>Arguments</title>
36095 <variablelist>
36096  <varlistentry>
36097   <term><parameter>dev</parameter></term>
36098   <listitem>
36099    <para>
36100     DRM device
36101    </para>
36102   </listitem>
36103  </varlistentry>
36104  <varlistentry>
36105   <term><parameter>frontbuffer_bits</parameter></term>
36106   <listitem>
36107    <para>
36108     frontbuffer plane tracking bits
36109    </para>
36110   </listitem>
36111  </varlistentry>
36112 </variablelist>
36113</refsect1>
36114<refsect1>
36115<title>Description</title>
36116<para>
36117   This function gets called after scheduling a flip on <parameter>obj</parameter>. The actual
36118   frontbuffer flushing will be delayed until completion is signalled with
36119   intel_frontbuffer_flip_complete. If an invalidate happens in between this
36120   flush will be cancelled.
36121   </para><para>
36122
36123   Can be called without any locks held.
36124</para>
36125</refsect1>
36126</refentry>
36127
36128<refentry id="API-intel-frontbuffer-flip-complete">
36129<refentryinfo>
36130 <title>LINUX</title>
36131 <productname>Kernel Hackers Manual</productname>
36132 <date>July 2017</date>
36133</refentryinfo>
36134<refmeta>
36135 <refentrytitle><phrase>intel_frontbuffer_flip_complete</phrase></refentrytitle>
36136 <manvolnum>9</manvolnum>
36137 <refmiscinfo class="version">4.1.27</refmiscinfo>
36138</refmeta>
36139<refnamediv>
36140 <refname>intel_frontbuffer_flip_complete</refname>
36141 <refpurpose>
36142     complete asynchronous frontbuffer flip
36143 </refpurpose>
36144</refnamediv>
36145<refsynopsisdiv>
36146 <title>Synopsis</title>
36147  <funcsynopsis><funcprototype>
36148   <funcdef>void <function>intel_frontbuffer_flip_complete </function></funcdef>
36149   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
36150   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
36151  </funcprototype></funcsynopsis>
36152</refsynopsisdiv>
36153<refsect1>
36154 <title>Arguments</title>
36155 <variablelist>
36156  <varlistentry>
36157   <term><parameter>dev</parameter></term>
36158   <listitem>
36159    <para>
36160     DRM device
36161    </para>
36162   </listitem>
36163  </varlistentry>
36164  <varlistentry>
36165   <term><parameter>frontbuffer_bits</parameter></term>
36166   <listitem>
36167    <para>
36168     frontbuffer plane tracking bits
36169    </para>
36170   </listitem>
36171  </varlistentry>
36172 </variablelist>
36173</refsect1>
36174<refsect1>
36175<title>Description</title>
36176<para>
36177   This function gets called after the flip has been latched and will complete
36178   on the next vblank. It will execute the flush if it hasn't been cancelled yet.
36179   </para><para>
36180
36181   Can be called without any locks held.
36182</para>
36183</refsect1>
36184</refentry>
36185
36186<refentry id="API-intel-frontbuffer-flip">
36187<refentryinfo>
36188 <title>LINUX</title>
36189 <productname>Kernel Hackers Manual</productname>
36190 <date>July 2017</date>
36191</refentryinfo>
36192<refmeta>
36193 <refentrytitle><phrase>intel_frontbuffer_flip</phrase></refentrytitle>
36194 <manvolnum>9</manvolnum>
36195 <refmiscinfo class="version">4.1.27</refmiscinfo>
36196</refmeta>
36197<refnamediv>
36198 <refname>intel_frontbuffer_flip</refname>
36199 <refpurpose>
36200  synchronous frontbuffer flip
36201 </refpurpose>
36202</refnamediv>
36203<refsynopsisdiv>
36204 <title>Synopsis</title>
36205  <funcsynopsis><funcprototype>
36206   <funcdef>void <function>intel_frontbuffer_flip </function></funcdef>
36207   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
36208   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
36209  </funcprototype></funcsynopsis>
36210</refsynopsisdiv>
36211<refsect1>
36212 <title>Arguments</title>
36213 <variablelist>
36214  <varlistentry>
36215   <term><parameter>dev</parameter></term>
36216   <listitem>
36217    <para>
36218     DRM device
36219    </para>
36220   </listitem>
36221  </varlistentry>
36222  <varlistentry>
36223   <term><parameter>frontbuffer_bits</parameter></term>
36224   <listitem>
36225    <para>
36226     frontbuffer plane tracking bits
36227    </para>
36228   </listitem>
36229  </varlistentry>
36230 </variablelist>
36231</refsect1>
36232<refsect1>
36233<title>Description</title>
36234<para>
36235   This function gets called after scheduling a flip on <parameter>obj</parameter>. This is for
36236   synchronous plane updates which will happen on the next vblank and which will
36237   not get delayed by pending gpu rendering.
36238   </para><para>
36239
36240   Can be called without any locks held.
36241</para>
36242</refsect1>
36243</refentry>
36244
36245<refentry id="API-i915-gem-track-fb">
36246<refentryinfo>
36247 <title>LINUX</title>
36248 <productname>Kernel Hackers Manual</productname>
36249 <date>July 2017</date>
36250</refentryinfo>
36251<refmeta>
36252 <refentrytitle><phrase>i915_gem_track_fb</phrase></refentrytitle>
36253 <manvolnum>9</manvolnum>
36254 <refmiscinfo class="version">4.1.27</refmiscinfo>
36255</refmeta>
36256<refnamediv>
36257 <refname>i915_gem_track_fb</refname>
36258 <refpurpose>
36259  update frontbuffer tracking
36260 </refpurpose>
36261</refnamediv>
36262<refsynopsisdiv>
36263 <title>Synopsis</title>
36264  <funcsynopsis><funcprototype>
36265   <funcdef>void <function>i915_gem_track_fb </function></funcdef>
36266   <paramdef>struct drm_i915_gem_object * <parameter>old</parameter></paramdef>
36267   <paramdef>struct drm_i915_gem_object * <parameter>new</parameter></paramdef>
36268   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
36269  </funcprototype></funcsynopsis>
36270</refsynopsisdiv>
36271<refsect1>
36272 <title>Arguments</title>
36273 <variablelist>
36274  <varlistentry>
36275   <term><parameter>old</parameter></term>
36276   <listitem>
36277    <para>
36278     -- undescribed --
36279    </para>
36280   </listitem>
36281  </varlistentry>
36282  <varlistentry>
36283   <term><parameter>new</parameter></term>
36284   <listitem>
36285    <para>
36286     -- undescribed --
36287    </para>
36288   </listitem>
36289  </varlistentry>
36290  <varlistentry>
36291   <term><parameter>frontbuffer_bits</parameter></term>
36292   <listitem>
36293    <para>
36294     -- undescribed --
36295    </para>
36296   </listitem>
36297  </varlistentry>
36298 </variablelist>
36299</refsect1>
36300<refsect1>
36301<title>old</title>
36302<para>
36303   current GEM buffer for the frontbuffer slots
36304</para>
36305</refsect1>
36306<refsect1>
36307<title>new</title>
36308<para>
36309   new GEM buffer for the frontbuffer slots
36310</para>
36311</refsect1>
36312<refsect1>
36313<title>frontbuffer_bits</title>
36314<para>
36315   bitmask of frontbuffer slots
36316   </para><para>
36317
36318   This updates the frontbuffer tracking bits <parameter>frontbuffer_bits</parameter> by clearing them
36319   from <parameter>old</parameter> and setting them in <parameter>new</parameter>. Both <parameter>old</parameter> and <parameter>new</parameter> can be NULL.
36320</para>
36321</refsect1>
36322</refentry>
36323
36324      </sect2>
36325      <sect2>
36326        <title>Display FIFO Underrun Reporting</title>
36327<para>
36328   </para><para>
36329   The i915 driver checks for display fifo underruns using the interrupt signals
36330   provided by the hardware. This is enabled by default and fairly useful to
36331   debug display issues, especially watermark settings.
36332   </para><para>
36333   If an underrun is detected this is logged into dmesg. To avoid flooding logs
36334   and occupying the cpu underrun interrupts are disabled after the first
36335   occurrence until the next modeset on a given pipe.
36336   </para><para>
36337   Note that underrun detection on gmch platforms is a bit more ugly since there
36338   is no interrupt (despite that the signalling bit is in the PIPESTAT pipe
36339   interrupt register). Also on some other platforms underrun interrupts are
36340   shared, which means that if we detect an underrun we need to disable underrun
36341   reporting on all pipes.
36342   </para><para>
36343   The code also supports underrun detection on the PCH transcoder.
36344</para>
36345
36346<!-- drivers/gpu/drm/i915/intel_fifo_underrun.c -->
36347<refentry id="API-i9xx-check-fifo-underruns">
36348<refentryinfo>
36349 <title>LINUX</title>
36350 <productname>Kernel Hackers Manual</productname>
36351 <date>July 2017</date>
36352</refentryinfo>
36353<refmeta>
36354 <refentrytitle><phrase>i9xx_check_fifo_underruns</phrase></refentrytitle>
36355 <manvolnum>9</manvolnum>
36356 <refmiscinfo class="version">4.1.27</refmiscinfo>
36357</refmeta>
36358<refnamediv>
36359 <refname>i9xx_check_fifo_underruns</refname>
36360 <refpurpose>
36361  check for fifo underruns
36362 </refpurpose>
36363</refnamediv>
36364<refsynopsisdiv>
36365 <title>Synopsis</title>
36366  <funcsynopsis><funcprototype>
36367   <funcdef>void <function>i9xx_check_fifo_underruns </function></funcdef>
36368   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
36369  </funcprototype></funcsynopsis>
36370</refsynopsisdiv>
36371<refsect1>
36372 <title>Arguments</title>
36373 <variablelist>
36374  <varlistentry>
36375   <term><parameter>dev_priv</parameter></term>
36376   <listitem>
36377    <para>
36378     i915 device instance
36379    </para>
36380   </listitem>
36381  </varlistentry>
36382 </variablelist>
36383</refsect1>
36384<refsect1>
36385<title>Description</title>
36386<para>
36387   This function checks for fifo underruns on GMCH platforms. This needs to be
36388   done manually on modeset to make sure that we catch all underruns since they
36389   do not generate an interrupt by themselves on these platforms.
36390</para>
36391</refsect1>
36392</refentry>
36393
36394<refentry id="API-intel-set-cpu-fifo-underrun-reporting">
36395<refentryinfo>
36396 <title>LINUX</title>
36397 <productname>Kernel Hackers Manual</productname>
36398 <date>July 2017</date>
36399</refentryinfo>
36400<refmeta>
36401 <refentrytitle><phrase>intel_set_cpu_fifo_underrun_reporting</phrase></refentrytitle>
36402 <manvolnum>9</manvolnum>
36403 <refmiscinfo class="version">4.1.27</refmiscinfo>
36404</refmeta>
36405<refnamediv>
36406 <refname>intel_set_cpu_fifo_underrun_reporting</refname>
36407 <refpurpose>
36408     set cpu fifo underrrun reporting state
36409 </refpurpose>
36410</refnamediv>
36411<refsynopsisdiv>
36412 <title>Synopsis</title>
36413  <funcsynopsis><funcprototype>
36414   <funcdef>bool <function>intel_set_cpu_fifo_underrun_reporting </function></funcdef>
36415   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
36416   <paramdef>enum pipe <parameter>pipe</parameter></paramdef>
36417   <paramdef>bool <parameter>enable</parameter></paramdef>
36418  </funcprototype></funcsynopsis>
36419</refsynopsisdiv>
36420<refsect1>
36421 <title>Arguments</title>
36422 <variablelist>
36423  <varlistentry>
36424   <term><parameter>dev_priv</parameter></term>
36425   <listitem>
36426    <para>
36427     i915 device instance
36428    </para>
36429   </listitem>
36430  </varlistentry>
36431  <varlistentry>
36432   <term><parameter>pipe</parameter></term>
36433   <listitem>
36434    <para>
36435     (CPU) pipe to set state for
36436    </para>
36437   </listitem>
36438  </varlistentry>
36439  <varlistentry>
36440   <term><parameter>enable</parameter></term>
36441   <listitem>
36442    <para>
36443     whether underruns should be reported or not
36444    </para>
36445   </listitem>
36446  </varlistentry>
36447 </variablelist>
36448</refsect1>
36449<refsect1>
36450<title>Description</title>
36451<para>
36452   This function sets the fifo underrun state for <parameter>pipe</parameter>. It is used in the
36453   modeset code to avoid false positives since on many platforms underruns are
36454   expected when disabling or enabling the pipe.
36455   </para><para>
36456
36457   Notice that on some platforms disabling underrun reports for one pipe
36458   disables for all due to shared interrupts. Actual reporting is still per-pipe
36459   though.
36460   </para><para>
36461
36462   Returns the previous state of underrun reporting.
36463</para>
36464</refsect1>
36465</refentry>
36466
36467<refentry id="API-intel-set-pch-fifo-underrun-reporting">
36468<refentryinfo>
36469 <title>LINUX</title>
36470 <productname>Kernel Hackers Manual</productname>
36471 <date>July 2017</date>
36472</refentryinfo>
36473<refmeta>
36474 <refentrytitle><phrase>intel_set_pch_fifo_underrun_reporting</phrase></refentrytitle>
36475 <manvolnum>9</manvolnum>
36476 <refmiscinfo class="version">4.1.27</refmiscinfo>
36477</refmeta>
36478<refnamediv>
36479 <refname>intel_set_pch_fifo_underrun_reporting</refname>
36480 <refpurpose>
36481     set PCH fifo underrun reporting state
36482 </refpurpose>
36483</refnamediv>
36484<refsynopsisdiv>
36485 <title>Synopsis</title>
36486  <funcsynopsis><funcprototype>
36487   <funcdef>bool <function>intel_set_pch_fifo_underrun_reporting </function></funcdef>
36488   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
36489   <paramdef>enum transcoder <parameter>pch_transcoder</parameter></paramdef>
36490   <paramdef>bool <parameter>enable</parameter></paramdef>
36491  </funcprototype></funcsynopsis>
36492</refsynopsisdiv>
36493<refsect1>
36494 <title>Arguments</title>
36495 <variablelist>
36496  <varlistentry>
36497   <term><parameter>dev_priv</parameter></term>
36498   <listitem>
36499    <para>
36500     i915 device instance
36501    </para>
36502   </listitem>
36503  </varlistentry>
36504  <varlistentry>
36505   <term><parameter>pch_transcoder</parameter></term>
36506   <listitem>
36507    <para>
36508     the PCH transcoder (same as pipe on IVB and older)
36509    </para>
36510   </listitem>
36511  </varlistentry>
36512  <varlistentry>
36513   <term><parameter>enable</parameter></term>
36514   <listitem>
36515    <para>
36516     whether underruns should be reported or not
36517    </para>
36518   </listitem>
36519  </varlistentry>
36520 </variablelist>
36521</refsect1>
36522<refsect1>
36523<title>Description</title>
36524<para>
36525   This function makes us disable or enable PCH fifo underruns for a specific
36526   PCH transcoder. Notice that on some PCHs (e.g. CPT/PPT), disabling FIFO
36527   underrun reporting for one transcoder may also disable all the other PCH
36528   error interruts for the other transcoders, due to the fact that there's just
36529   one interrupt mask/enable bit for all the transcoders.
36530   </para><para>
36531
36532   Returns the previous state of underrun reporting.
36533</para>
36534</refsect1>
36535</refentry>
36536
36537<refentry id="API-intel-cpu-fifo-underrun-irq-handler">
36538<refentryinfo>
36539 <title>LINUX</title>
36540 <productname>Kernel Hackers Manual</productname>
36541 <date>July 2017</date>
36542</refentryinfo>
36543<refmeta>
36544 <refentrytitle><phrase>intel_cpu_fifo_underrun_irq_handler</phrase></refentrytitle>
36545 <manvolnum>9</manvolnum>
36546 <refmiscinfo class="version">4.1.27</refmiscinfo>
36547</refmeta>
36548<refnamediv>
36549 <refname>intel_cpu_fifo_underrun_irq_handler</refname>
36550 <refpurpose>
36551     handle CPU fifo underrun interrupt
36552 </refpurpose>
36553</refnamediv>
36554<refsynopsisdiv>
36555 <title>Synopsis</title>
36556  <funcsynopsis><funcprototype>
36557   <funcdef>void <function>intel_cpu_fifo_underrun_irq_handler </function></funcdef>
36558   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
36559   <paramdef>enum pipe <parameter>pipe</parameter></paramdef>
36560  </funcprototype></funcsynopsis>
36561</refsynopsisdiv>
36562<refsect1>
36563 <title>Arguments</title>
36564 <variablelist>
36565  <varlistentry>
36566   <term><parameter>dev_priv</parameter></term>
36567   <listitem>
36568    <para>
36569     i915 device instance
36570    </para>
36571   </listitem>
36572  </varlistentry>
36573  <varlistentry>
36574   <term><parameter>pipe</parameter></term>
36575   <listitem>
36576    <para>
36577     (CPU) pipe to set state for
36578    </para>
36579   </listitem>
36580  </varlistentry>
36581 </variablelist>
36582</refsect1>
36583<refsect1>
36584<title>Description</title>
36585<para>
36586   This handles a CPU fifo underrun interrupt, generating an underrun warning
36587   into dmesg if underrun reporting is enabled and then disables the underrun
36588   interrupt to avoid an irq storm.
36589</para>
36590</refsect1>
36591</refentry>
36592
36593<refentry id="API-intel-pch-fifo-underrun-irq-handler">
36594<refentryinfo>
36595 <title>LINUX</title>
36596 <productname>Kernel Hackers Manual</productname>
36597 <date>July 2017</date>
36598</refentryinfo>
36599<refmeta>
36600 <refentrytitle><phrase>intel_pch_fifo_underrun_irq_handler</phrase></refentrytitle>
36601 <manvolnum>9</manvolnum>
36602 <refmiscinfo class="version">4.1.27</refmiscinfo>
36603</refmeta>
36604<refnamediv>
36605 <refname>intel_pch_fifo_underrun_irq_handler</refname>
36606 <refpurpose>
36607     handle PCH fifo underrun interrupt
36608 </refpurpose>
36609</refnamediv>
36610<refsynopsisdiv>
36611 <title>Synopsis</title>
36612  <funcsynopsis><funcprototype>
36613   <funcdef>void <function>intel_pch_fifo_underrun_irq_handler </function></funcdef>
36614   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
36615   <paramdef>enum transcoder <parameter>pch_transcoder</parameter></paramdef>
36616  </funcprototype></funcsynopsis>
36617</refsynopsisdiv>
36618<refsect1>
36619 <title>Arguments</title>
36620 <variablelist>
36621  <varlistentry>
36622   <term><parameter>dev_priv</parameter></term>
36623   <listitem>
36624    <para>
36625     i915 device instance
36626    </para>
36627   </listitem>
36628  </varlistentry>
36629  <varlistentry>
36630   <term><parameter>pch_transcoder</parameter></term>
36631   <listitem>
36632    <para>
36633     the PCH transcoder (same as pipe on IVB and older)
36634    </para>
36635   </listitem>
36636  </varlistentry>
36637 </variablelist>
36638</refsect1>
36639<refsect1>
36640<title>Description</title>
36641<para>
36642   This handles a PCH fifo underrun interrupt, generating an underrun warning
36643   into dmesg if underrun reporting is enabled and then disables the underrun
36644   interrupt to avoid an irq storm.
36645</para>
36646</refsect1>
36647</refentry>
36648
36649      </sect2>
36650      <sect2>
36651        <title>Plane Configuration</title>
36652        <para>
36653	  This section covers plane configuration and composition with the
36654	  primary plane, sprites, cursors and overlays. This includes the
36655	  infrastructure to do atomic vsync'ed updates of all this state and
36656	  also tightly coupled topics like watermark setup and computation,
36657	  framebuffer compression and panel self refresh.
36658        </para>
36659      </sect2>
36660      <sect2>
36661        <title>Atomic Plane Helpers</title>
36662<para>
36663   </para><para>
36664   The functions here are used by the atomic plane helper functions to
36665   implement legacy plane updates (i.e., drm_plane-&gt;<function>update_plane</function> and
36666   drm_plane-&gt;<function>disable_plane</function>).  This allows plane updates to use the
36667   atomic state infrastructure and perform plane updates as separate
36668   prepare/check/commit/cleanup steps.
36669</para>
36670
36671<!-- drivers/gpu/drm/i915/intel_atomic_plane.c -->
36672<refentry id="API-intel-create-plane-state">
36673<refentryinfo>
36674 <title>LINUX</title>
36675 <productname>Kernel Hackers Manual</productname>
36676 <date>July 2017</date>
36677</refentryinfo>
36678<refmeta>
36679 <refentrytitle><phrase>intel_create_plane_state</phrase></refentrytitle>
36680 <manvolnum>9</manvolnum>
36681 <refmiscinfo class="version">4.1.27</refmiscinfo>
36682</refmeta>
36683<refnamediv>
36684 <refname>intel_create_plane_state</refname>
36685 <refpurpose>
36686  create plane state object
36687 </refpurpose>
36688</refnamediv>
36689<refsynopsisdiv>
36690 <title>Synopsis</title>
36691  <funcsynopsis><funcprototype>
36692   <funcdef>struct intel_plane_state * <function>intel_create_plane_state </function></funcdef>
36693   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
36694  </funcprototype></funcsynopsis>
36695</refsynopsisdiv>
36696<refsect1>
36697 <title>Arguments</title>
36698 <variablelist>
36699  <varlistentry>
36700   <term><parameter>plane</parameter></term>
36701   <listitem>
36702    <para>
36703     drm plane
36704    </para>
36705   </listitem>
36706  </varlistentry>
36707 </variablelist>
36708</refsect1>
36709<refsect1>
36710<title>Description</title>
36711<para>
36712   Allocates a fresh plane state for the given plane and sets some of
36713   the state values to sensible initial values.
36714</para>
36715</refsect1>
36716<refsect1>
36717<title>Returns</title>
36718<para>
36719   A newly allocated plane state, or NULL on failure
36720</para>
36721</refsect1>
36722</refentry>
36723
36724<refentry id="API-intel-plane-duplicate-state">
36725<refentryinfo>
36726 <title>LINUX</title>
36727 <productname>Kernel Hackers Manual</productname>
36728 <date>July 2017</date>
36729</refentryinfo>
36730<refmeta>
36731 <refentrytitle><phrase>intel_plane_duplicate_state</phrase></refentrytitle>
36732 <manvolnum>9</manvolnum>
36733 <refmiscinfo class="version">4.1.27</refmiscinfo>
36734</refmeta>
36735<refnamediv>
36736 <refname>intel_plane_duplicate_state</refname>
36737 <refpurpose>
36738     duplicate plane state
36739 </refpurpose>
36740</refnamediv>
36741<refsynopsisdiv>
36742 <title>Synopsis</title>
36743  <funcsynopsis><funcprototype>
36744   <funcdef>struct drm_plane_state * <function>intel_plane_duplicate_state </function></funcdef>
36745   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
36746  </funcprototype></funcsynopsis>
36747</refsynopsisdiv>
36748<refsect1>
36749 <title>Arguments</title>
36750 <variablelist>
36751  <varlistentry>
36752   <term><parameter>plane</parameter></term>
36753   <listitem>
36754    <para>
36755     drm plane
36756    </para>
36757   </listitem>
36758  </varlistentry>
36759 </variablelist>
36760</refsect1>
36761<refsect1>
36762<title>Description</title>
36763<para>
36764   Allocates and returns a copy of the plane state (both common and
36765   Intel-specific) for the specified plane.
36766</para>
36767</refsect1>
36768<refsect1>
36769<title>Returns</title>
36770<para>
36771   The newly allocated plane state, or NULL on failure.
36772</para>
36773</refsect1>
36774</refentry>
36775
36776<refentry id="API-intel-plane-destroy-state">
36777<refentryinfo>
36778 <title>LINUX</title>
36779 <productname>Kernel Hackers Manual</productname>
36780 <date>July 2017</date>
36781</refentryinfo>
36782<refmeta>
36783 <refentrytitle><phrase>intel_plane_destroy_state</phrase></refentrytitle>
36784 <manvolnum>9</manvolnum>
36785 <refmiscinfo class="version">4.1.27</refmiscinfo>
36786</refmeta>
36787<refnamediv>
36788 <refname>intel_plane_destroy_state</refname>
36789 <refpurpose>
36790     destroy plane state
36791 </refpurpose>
36792</refnamediv>
36793<refsynopsisdiv>
36794 <title>Synopsis</title>
36795  <funcsynopsis><funcprototype>
36796   <funcdef>void <function>intel_plane_destroy_state </function></funcdef>
36797   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
36798   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
36799  </funcprototype></funcsynopsis>
36800</refsynopsisdiv>
36801<refsect1>
36802 <title>Arguments</title>
36803 <variablelist>
36804  <varlistentry>
36805   <term><parameter>plane</parameter></term>
36806   <listitem>
36807    <para>
36808     drm plane
36809    </para>
36810   </listitem>
36811  </varlistentry>
36812  <varlistentry>
36813   <term><parameter>state</parameter></term>
36814   <listitem>
36815    <para>
36816     state object to destroy
36817    </para>
36818   </listitem>
36819  </varlistentry>
36820 </variablelist>
36821</refsect1>
36822<refsect1>
36823<title>Description</title>
36824<para>
36825   Destroys the plane state (both common and Intel-specific) for the
36826   specified plane.
36827</para>
36828</refsect1>
36829</refentry>
36830
36831<refentry id="API-intel-plane-atomic-get-property">
36832<refentryinfo>
36833 <title>LINUX</title>
36834 <productname>Kernel Hackers Manual</productname>
36835 <date>July 2017</date>
36836</refentryinfo>
36837<refmeta>
36838 <refentrytitle><phrase>intel_plane_atomic_get_property</phrase></refentrytitle>
36839 <manvolnum>9</manvolnum>
36840 <refmiscinfo class="version">4.1.27</refmiscinfo>
36841</refmeta>
36842<refnamediv>
36843 <refname>intel_plane_atomic_get_property</refname>
36844 <refpurpose>
36845     fetch plane property value
36846 </refpurpose>
36847</refnamediv>
36848<refsynopsisdiv>
36849 <title>Synopsis</title>
36850  <funcsynopsis><funcprototype>
36851   <funcdef>int <function>intel_plane_atomic_get_property </function></funcdef>
36852   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
36853   <paramdef>const struct drm_plane_state * <parameter>state</parameter></paramdef>
36854   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
36855   <paramdef>uint64_t * <parameter>val</parameter></paramdef>
36856  </funcprototype></funcsynopsis>
36857</refsynopsisdiv>
36858<refsect1>
36859 <title>Arguments</title>
36860 <variablelist>
36861  <varlistentry>
36862   <term><parameter>plane</parameter></term>
36863   <listitem>
36864    <para>
36865     plane to fetch property for
36866    </para>
36867   </listitem>
36868  </varlistentry>
36869  <varlistentry>
36870   <term><parameter>state</parameter></term>
36871   <listitem>
36872    <para>
36873     state containing the property value
36874    </para>
36875   </listitem>
36876  </varlistentry>
36877  <varlistentry>
36878   <term><parameter>property</parameter></term>
36879   <listitem>
36880    <para>
36881     property to look up
36882    </para>
36883   </listitem>
36884  </varlistentry>
36885  <varlistentry>
36886   <term><parameter>val</parameter></term>
36887   <listitem>
36888    <para>
36889     pointer to write property value into
36890    </para>
36891   </listitem>
36892  </varlistentry>
36893 </variablelist>
36894</refsect1>
36895<refsect1>
36896<title>Description</title>
36897<para>
36898   The DRM core does not store shadow copies of properties for
36899   atomic-capable drivers.  This entrypoint is used to fetch
36900   the current value of a driver-specific plane property.
36901</para>
36902</refsect1>
36903</refentry>
36904
36905<refentry id="API-intel-plane-atomic-set-property">
36906<refentryinfo>
36907 <title>LINUX</title>
36908 <productname>Kernel Hackers Manual</productname>
36909 <date>July 2017</date>
36910</refentryinfo>
36911<refmeta>
36912 <refentrytitle><phrase>intel_plane_atomic_set_property</phrase></refentrytitle>
36913 <manvolnum>9</manvolnum>
36914 <refmiscinfo class="version">4.1.27</refmiscinfo>
36915</refmeta>
36916<refnamediv>
36917 <refname>intel_plane_atomic_set_property</refname>
36918 <refpurpose>
36919     set plane property value
36920 </refpurpose>
36921</refnamediv>
36922<refsynopsisdiv>
36923 <title>Synopsis</title>
36924  <funcsynopsis><funcprototype>
36925   <funcdef>int <function>intel_plane_atomic_set_property </function></funcdef>
36926   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
36927   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
36928   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
36929   <paramdef>uint64_t <parameter>val</parameter></paramdef>
36930  </funcprototype></funcsynopsis>
36931</refsynopsisdiv>
36932<refsect1>
36933 <title>Arguments</title>
36934 <variablelist>
36935  <varlistentry>
36936   <term><parameter>plane</parameter></term>
36937   <listitem>
36938    <para>
36939     plane to set property for
36940    </para>
36941   </listitem>
36942  </varlistentry>
36943  <varlistentry>
36944   <term><parameter>state</parameter></term>
36945   <listitem>
36946    <para>
36947     state to update property value in
36948    </para>
36949   </listitem>
36950  </varlistentry>
36951  <varlistentry>
36952   <term><parameter>property</parameter></term>
36953   <listitem>
36954    <para>
36955     property to set
36956    </para>
36957   </listitem>
36958  </varlistentry>
36959  <varlistentry>
36960   <term><parameter>val</parameter></term>
36961   <listitem>
36962    <para>
36963     value to set property to
36964    </para>
36965   </listitem>
36966  </varlistentry>
36967 </variablelist>
36968</refsect1>
36969<refsect1>
36970<title>Description</title>
36971<para>
36972   Writes the specified property value for a plane into the provided atomic
36973   state object.
36974   </para><para>
36975
36976   Returns 0 on success, -EINVAL on unrecognized properties
36977</para>
36978</refsect1>
36979</refentry>
36980
36981      </sect2>
36982      <sect2>
36983        <title>Output Probing</title>
36984        <para>
36985	  This section covers output probing and related infrastructure like the
36986	  hotplug interrupt storm detection and mitigation code. Note that the
36987	  i915 driver still uses most of the common DRM helper code for output
36988	  probing, so those sections fully apply.
36989        </para>
36990      </sect2>
36991      <sect2>
36992	<title>High Definition Audio</title>
36993<para>
36994   </para><para>
36995   The graphics and audio drivers together support High Definition Audio over
36996   HDMI and Display Port. The audio programming sequences are divided into audio
36997   codec and controller enable and disable sequences. The graphics driver
36998   handles the audio codec sequences, while the audio driver handles the audio
36999   controller sequences.
37000   </para><para>
37001   The disable sequences must be performed before disabling the transcoder or
37002   port. The enable sequences may only be performed after enabling the
37003   transcoder and port, and after completed link training.
37004   </para><para>
37005   The codec and controller sequences could be done either parallel or serial,
37006   but generally the ELDV/PD change in the codec sequence indicates to the audio
37007   driver that the controller sequence should start. Indeed, most of the
37008   co-operation between the graphics and audio drivers is handled via audio
37009   related registers. (The notable exception is the power management, not
37010   covered here.)
37011</para>
37012
37013<!-- drivers/gpu/drm/i915/intel_audio.c -->
37014<refentry id="API-intel-audio-codec-enable">
37015<refentryinfo>
37016 <title>LINUX</title>
37017 <productname>Kernel Hackers Manual</productname>
37018 <date>July 2017</date>
37019</refentryinfo>
37020<refmeta>
37021 <refentrytitle><phrase>intel_audio_codec_enable</phrase></refentrytitle>
37022 <manvolnum>9</manvolnum>
37023 <refmiscinfo class="version">4.1.27</refmiscinfo>
37024</refmeta>
37025<refnamediv>
37026 <refname>intel_audio_codec_enable</refname>
37027 <refpurpose>
37028  Enable the audio codec for HD audio
37029 </refpurpose>
37030</refnamediv>
37031<refsynopsisdiv>
37032 <title>Synopsis</title>
37033  <funcsynopsis><funcprototype>
37034   <funcdef>void <function>intel_audio_codec_enable </function></funcdef>
37035   <paramdef>struct intel_encoder * <parameter>intel_encoder</parameter></paramdef>
37036  </funcprototype></funcsynopsis>
37037</refsynopsisdiv>
37038<refsect1>
37039 <title>Arguments</title>
37040 <variablelist>
37041  <varlistentry>
37042   <term><parameter>intel_encoder</parameter></term>
37043   <listitem>
37044    <para>
37045     encoder on which to enable audio
37046    </para>
37047   </listitem>
37048  </varlistentry>
37049 </variablelist>
37050</refsect1>
37051<refsect1>
37052<title>Description</title>
37053<para>
37054   The enable sequences may only be performed after enabling the transcoder and
37055   port, and after completed link training.
37056</para>
37057</refsect1>
37058</refentry>
37059
37060<refentry id="API-intel-audio-codec-disable">
37061<refentryinfo>
37062 <title>LINUX</title>
37063 <productname>Kernel Hackers Manual</productname>
37064 <date>July 2017</date>
37065</refentryinfo>
37066<refmeta>
37067 <refentrytitle><phrase>intel_audio_codec_disable</phrase></refentrytitle>
37068 <manvolnum>9</manvolnum>
37069 <refmiscinfo class="version">4.1.27</refmiscinfo>
37070</refmeta>
37071<refnamediv>
37072 <refname>intel_audio_codec_disable</refname>
37073 <refpurpose>
37074     Disable the audio codec for HD audio
37075 </refpurpose>
37076</refnamediv>
37077<refsynopsisdiv>
37078 <title>Synopsis</title>
37079  <funcsynopsis><funcprototype>
37080   <funcdef>void <function>intel_audio_codec_disable </function></funcdef>
37081   <paramdef>struct intel_encoder * <parameter>encoder</parameter></paramdef>
37082  </funcprototype></funcsynopsis>
37083</refsynopsisdiv>
37084<refsect1>
37085 <title>Arguments</title>
37086 <variablelist>
37087  <varlistentry>
37088   <term><parameter>encoder</parameter></term>
37089   <listitem>
37090    <para>
37091     encoder on which to disable audio
37092    </para>
37093   </listitem>
37094  </varlistentry>
37095 </variablelist>
37096</refsect1>
37097<refsect1>
37098<title>Description</title>
37099<para>
37100   The disable sequences must be performed before disabling the transcoder or
37101   port.
37102</para>
37103</refsect1>
37104</refentry>
37105
37106<refentry id="API-intel-init-audio">
37107<refentryinfo>
37108 <title>LINUX</title>
37109 <productname>Kernel Hackers Manual</productname>
37110 <date>July 2017</date>
37111</refentryinfo>
37112<refmeta>
37113 <refentrytitle><phrase>intel_init_audio</phrase></refentrytitle>
37114 <manvolnum>9</manvolnum>
37115 <refmiscinfo class="version">4.1.27</refmiscinfo>
37116</refmeta>
37117<refnamediv>
37118 <refname>intel_init_audio</refname>
37119 <refpurpose>
37120     Set up chip specific audio functions
37121 </refpurpose>
37122</refnamediv>
37123<refsynopsisdiv>
37124 <title>Synopsis</title>
37125  <funcsynopsis><funcprototype>
37126   <funcdef>void <function>intel_init_audio </function></funcdef>
37127   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37128  </funcprototype></funcsynopsis>
37129</refsynopsisdiv>
37130<refsect1>
37131 <title>Arguments</title>
37132 <variablelist>
37133  <varlistentry>
37134   <term><parameter>dev</parameter></term>
37135   <listitem>
37136    <para>
37137     drm device
37138    </para>
37139   </listitem>
37140  </varlistentry>
37141 </variablelist>
37142</refsect1>
37143</refentry>
37144
37145<refentry id="API-i915-audio-component-init">
37146<refentryinfo>
37147 <title>LINUX</title>
37148 <productname>Kernel Hackers Manual</productname>
37149 <date>July 2017</date>
37150</refentryinfo>
37151<refmeta>
37152 <refentrytitle><phrase>i915_audio_component_init</phrase></refentrytitle>
37153 <manvolnum>9</manvolnum>
37154 <refmiscinfo class="version">4.1.27</refmiscinfo>
37155</refmeta>
37156<refnamediv>
37157 <refname>i915_audio_component_init</refname>
37158 <refpurpose>
37159     initialize and register the audio component
37160 </refpurpose>
37161</refnamediv>
37162<refsynopsisdiv>
37163 <title>Synopsis</title>
37164  <funcsynopsis><funcprototype>
37165   <funcdef>void <function>i915_audio_component_init </function></funcdef>
37166   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
37167  </funcprototype></funcsynopsis>
37168</refsynopsisdiv>
37169<refsect1>
37170 <title>Arguments</title>
37171 <variablelist>
37172  <varlistentry>
37173   <term><parameter>dev_priv</parameter></term>
37174   <listitem>
37175    <para>
37176     i915 device instance
37177    </para>
37178   </listitem>
37179  </varlistentry>
37180 </variablelist>
37181</refsect1>
37182<refsect1>
37183<title>Description</title>
37184<para>
37185   This will register with the component framework a child component which
37186   will bind dynamically to the snd_hda_intel driver's corresponding master
37187   component when the latter is registered. During binding the child
37188   initializes an instance of struct i915_audio_component which it receives
37189   from the master. The master can then start to use the interface defined by
37190   this struct. Each side can break the binding at any point by deregistering
37191   its own component after which each side's component unbind callback is
37192   called.
37193   </para><para>
37194
37195   We ignore any error during registration and continue with reduced
37196   functionality (i.e. without HDMI audio).
37197</para>
37198</refsect1>
37199</refentry>
37200
37201<refentry id="API-i915-audio-component-cleanup">
37202<refentryinfo>
37203 <title>LINUX</title>
37204 <productname>Kernel Hackers Manual</productname>
37205 <date>July 2017</date>
37206</refentryinfo>
37207<refmeta>
37208 <refentrytitle><phrase>i915_audio_component_cleanup</phrase></refentrytitle>
37209 <manvolnum>9</manvolnum>
37210 <refmiscinfo class="version">4.1.27</refmiscinfo>
37211</refmeta>
37212<refnamediv>
37213 <refname>i915_audio_component_cleanup</refname>
37214 <refpurpose>
37215     deregister the audio component
37216 </refpurpose>
37217</refnamediv>
37218<refsynopsisdiv>
37219 <title>Synopsis</title>
37220  <funcsynopsis><funcprototype>
37221   <funcdef>void <function>i915_audio_component_cleanup </function></funcdef>
37222   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
37223  </funcprototype></funcsynopsis>
37224</refsynopsisdiv>
37225<refsect1>
37226 <title>Arguments</title>
37227 <variablelist>
37228  <varlistentry>
37229   <term><parameter>dev_priv</parameter></term>
37230   <listitem>
37231    <para>
37232     i915 device instance
37233    </para>
37234   </listitem>
37235  </varlistentry>
37236 </variablelist>
37237</refsect1>
37238<refsect1>
37239<title>Description</title>
37240<para>
37241   Deregisters the audio component, breaking any existing binding to the
37242   corresponding snd_hda_intel driver's master component.
37243</para>
37244</refsect1>
37245</refentry>
37246
37247      </sect2>
37248      <sect2>
37249	<title>Panel Self Refresh PSR (PSR/SRD)</title>
37250<para>
37251   </para><para>
37252   Since Haswell Display controller supports Panel Self-Refresh on display
37253   panels witch have a remote frame buffer (RFB) implemented according to PSR
37254   spec in eDP1.3. PSR feature allows the display to go to lower standby states
37255   when system is idle but display is on as it eliminates display refresh
37256   request to DDR memory completely as long as the frame buffer for that
37257   display is unchanged.
37258   </para><para>
37259   Panel Self Refresh must be supported by both Hardware (source) and
37260   Panel (sink).
37261   </para><para>
37262   PSR saves power by caching the framebuffer in the panel RFB, which allows us
37263   to power down the link and memory controller. For DSI panels the same idea
37264   is called <quote>manual mode</quote>.
37265   </para><para>
37266   The implementation uses the hardware-based PSR support which automatically
37267   enters/exits self-refresh mode. The hardware takes care of sending the
37268   required DP aux message and could even retrain the link (that part isn't
37269   enabled yet though). The hardware also keeps track of any frontbuffer
37270   changes to know when to exit self-refresh mode again. Unfortunately that
37271   part doesn't work too well, hence why the i915 PSR support uses the
37272   software frontbuffer tracking to make sure it doesn't miss a screen
37273   update. For this integration <function>intel_psr_invalidate</function> and <function>intel_psr_flush</function>
37274   get called by the frontbuffer tracking code. Note that because of locking
37275   issues the self-refresh re-enable code is done from a work queue, which
37276   must be correctly synchronized/cancelled when shutting down the pipe."
37277</para>
37278
37279<!-- drivers/gpu/drm/i915/intel_psr.c -->
37280<refentry id="API-intel-psr-enable">
37281<refentryinfo>
37282 <title>LINUX</title>
37283 <productname>Kernel Hackers Manual</productname>
37284 <date>July 2017</date>
37285</refentryinfo>
37286<refmeta>
37287 <refentrytitle><phrase>intel_psr_enable</phrase></refentrytitle>
37288 <manvolnum>9</manvolnum>
37289 <refmiscinfo class="version">4.1.27</refmiscinfo>
37290</refmeta>
37291<refnamediv>
37292 <refname>intel_psr_enable</refname>
37293 <refpurpose>
37294  Enable PSR
37295 </refpurpose>
37296</refnamediv>
37297<refsynopsisdiv>
37298 <title>Synopsis</title>
37299  <funcsynopsis><funcprototype>
37300   <funcdef>void <function>intel_psr_enable </function></funcdef>
37301   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
37302  </funcprototype></funcsynopsis>
37303</refsynopsisdiv>
37304<refsect1>
37305 <title>Arguments</title>
37306 <variablelist>
37307  <varlistentry>
37308   <term><parameter>intel_dp</parameter></term>
37309   <listitem>
37310    <para>
37311     Intel DP
37312    </para>
37313   </listitem>
37314  </varlistentry>
37315 </variablelist>
37316</refsect1>
37317<refsect1>
37318<title>Description</title>
37319<para>
37320   This function can only be called after the pipe is fully trained and enabled.
37321</para>
37322</refsect1>
37323</refentry>
37324
37325<refentry id="API-intel-psr-disable">
37326<refentryinfo>
37327 <title>LINUX</title>
37328 <productname>Kernel Hackers Manual</productname>
37329 <date>July 2017</date>
37330</refentryinfo>
37331<refmeta>
37332 <refentrytitle><phrase>intel_psr_disable</phrase></refentrytitle>
37333 <manvolnum>9</manvolnum>
37334 <refmiscinfo class="version">4.1.27</refmiscinfo>
37335</refmeta>
37336<refnamediv>
37337 <refname>intel_psr_disable</refname>
37338 <refpurpose>
37339     Disable PSR
37340 </refpurpose>
37341</refnamediv>
37342<refsynopsisdiv>
37343 <title>Synopsis</title>
37344  <funcsynopsis><funcprototype>
37345   <funcdef>void <function>intel_psr_disable </function></funcdef>
37346   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
37347  </funcprototype></funcsynopsis>
37348</refsynopsisdiv>
37349<refsect1>
37350 <title>Arguments</title>
37351 <variablelist>
37352  <varlistentry>
37353   <term><parameter>intel_dp</parameter></term>
37354   <listitem>
37355    <para>
37356     Intel DP
37357    </para>
37358   </listitem>
37359  </varlistentry>
37360 </variablelist>
37361</refsect1>
37362<refsect1>
37363<title>Description</title>
37364<para>
37365   This function needs to be called before disabling pipe.
37366</para>
37367</refsect1>
37368</refentry>
37369
37370<refentry id="API-intel-psr-invalidate">
37371<refentryinfo>
37372 <title>LINUX</title>
37373 <productname>Kernel Hackers Manual</productname>
37374 <date>July 2017</date>
37375</refentryinfo>
37376<refmeta>
37377 <refentrytitle><phrase>intel_psr_invalidate</phrase></refentrytitle>
37378 <manvolnum>9</manvolnum>
37379 <refmiscinfo class="version">4.1.27</refmiscinfo>
37380</refmeta>
37381<refnamediv>
37382 <refname>intel_psr_invalidate</refname>
37383 <refpurpose>
37384     Invalidade PSR
37385 </refpurpose>
37386</refnamediv>
37387<refsynopsisdiv>
37388 <title>Synopsis</title>
37389  <funcsynopsis><funcprototype>
37390   <funcdef>void <function>intel_psr_invalidate </function></funcdef>
37391   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37392   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
37393  </funcprototype></funcsynopsis>
37394</refsynopsisdiv>
37395<refsect1>
37396 <title>Arguments</title>
37397 <variablelist>
37398  <varlistentry>
37399   <term><parameter>dev</parameter></term>
37400   <listitem>
37401    <para>
37402     DRM device
37403    </para>
37404   </listitem>
37405  </varlistentry>
37406  <varlistentry>
37407   <term><parameter>frontbuffer_bits</parameter></term>
37408   <listitem>
37409    <para>
37410     frontbuffer plane tracking bits
37411    </para>
37412   </listitem>
37413  </varlistentry>
37414 </variablelist>
37415</refsect1>
37416<refsect1>
37417<title>Description</title>
37418<para>
37419   Since the hardware frontbuffer tracking has gaps we need to integrate
37420   with the software frontbuffer tracking. This function gets called every
37421   time frontbuffer rendering starts and a buffer gets dirtied. PSR must be
37422   disabled if the frontbuffer mask contains a buffer relevant to PSR.
37423   </para><para>
37424
37425   Dirty frontbuffers relevant to PSR are tracked in busy_frontbuffer_bits."
37426</para>
37427</refsect1>
37428</refentry>
37429
37430<refentry id="API-intel-psr-flush">
37431<refentryinfo>
37432 <title>LINUX</title>
37433 <productname>Kernel Hackers Manual</productname>
37434 <date>July 2017</date>
37435</refentryinfo>
37436<refmeta>
37437 <refentrytitle><phrase>intel_psr_flush</phrase></refentrytitle>
37438 <manvolnum>9</manvolnum>
37439 <refmiscinfo class="version">4.1.27</refmiscinfo>
37440</refmeta>
37441<refnamediv>
37442 <refname>intel_psr_flush</refname>
37443 <refpurpose>
37444     Flush PSR
37445 </refpurpose>
37446</refnamediv>
37447<refsynopsisdiv>
37448 <title>Synopsis</title>
37449  <funcsynopsis><funcprototype>
37450   <funcdef>void <function>intel_psr_flush </function></funcdef>
37451   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37452   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
37453  </funcprototype></funcsynopsis>
37454</refsynopsisdiv>
37455<refsect1>
37456 <title>Arguments</title>
37457 <variablelist>
37458  <varlistentry>
37459   <term><parameter>dev</parameter></term>
37460   <listitem>
37461    <para>
37462     DRM device
37463    </para>
37464   </listitem>
37465  </varlistentry>
37466  <varlistentry>
37467   <term><parameter>frontbuffer_bits</parameter></term>
37468   <listitem>
37469    <para>
37470     frontbuffer plane tracking bits
37471    </para>
37472   </listitem>
37473  </varlistentry>
37474 </variablelist>
37475</refsect1>
37476<refsect1>
37477<title>Description</title>
37478<para>
37479   Since the hardware frontbuffer tracking has gaps we need to integrate
37480   with the software frontbuffer tracking. This function gets called every
37481   time frontbuffer rendering has completed and flushed out to memory. PSR
37482   can be enabled again if no other frontbuffer relevant to PSR is dirty.
37483   </para><para>
37484
37485   Dirty frontbuffers relevant to PSR are tracked in busy_frontbuffer_bits.
37486</para>
37487</refsect1>
37488</refentry>
37489
37490<refentry id="API-intel-psr-init">
37491<refentryinfo>
37492 <title>LINUX</title>
37493 <productname>Kernel Hackers Manual</productname>
37494 <date>July 2017</date>
37495</refentryinfo>
37496<refmeta>
37497 <refentrytitle><phrase>intel_psr_init</phrase></refentrytitle>
37498 <manvolnum>9</manvolnum>
37499 <refmiscinfo class="version">4.1.27</refmiscinfo>
37500</refmeta>
37501<refnamediv>
37502 <refname>intel_psr_init</refname>
37503 <refpurpose>
37504     Init basic PSR work and mutex.
37505 </refpurpose>
37506</refnamediv>
37507<refsynopsisdiv>
37508 <title>Synopsis</title>
37509  <funcsynopsis><funcprototype>
37510   <funcdef>void <function>intel_psr_init </function></funcdef>
37511   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37512  </funcprototype></funcsynopsis>
37513</refsynopsisdiv>
37514<refsect1>
37515 <title>Arguments</title>
37516 <variablelist>
37517  <varlistentry>
37518   <term><parameter>dev</parameter></term>
37519   <listitem>
37520    <para>
37521     DRM device
37522    </para>
37523   </listitem>
37524  </varlistentry>
37525 </variablelist>
37526</refsect1>
37527<refsect1>
37528<title>Description</title>
37529<para>
37530   This function is  called only once at driver load to initialize basic
37531   PSR stuff.
37532</para>
37533</refsect1>
37534</refentry>
37535
37536      </sect2>
37537      <sect2>
37538	<title>Frame Buffer Compression (FBC)</title>
37539<para>
37540   </para><para>
37541   FBC tries to save memory bandwidth (and so power consumption) by
37542   compressing the amount of memory used by the display. It is total
37543   transparent to user space and completely handled in the kernel.
37544   </para><para>
37545   The benefits of FBC are mostly visible with solid backgrounds and
37546   variation-less patterns. It comes from keeping the memory footprint small
37547   and having fewer memory pages opened and accessed for refreshing the display.
37548   </para><para>
37549   i915 is responsible to reserve stolen memory for FBC and configure its
37550   offset on proper registers. The hardware takes care of all
37551   compress/decompress. However there are many known cases where we have to
37552   forcibly disable it to allow proper screen updates.
37553</para>
37554
37555<!-- drivers/gpu/drm/i915/intel_fbc.c -->
37556<refentry id="API-intel-fbc-enabled">
37557<refentryinfo>
37558 <title>LINUX</title>
37559 <productname>Kernel Hackers Manual</productname>
37560 <date>July 2017</date>
37561</refentryinfo>
37562<refmeta>
37563 <refentrytitle><phrase>intel_fbc_enabled</phrase></refentrytitle>
37564 <manvolnum>9</manvolnum>
37565 <refmiscinfo class="version">4.1.27</refmiscinfo>
37566</refmeta>
37567<refnamediv>
37568 <refname>intel_fbc_enabled</refname>
37569 <refpurpose>
37570  Is FBC enabled?
37571 </refpurpose>
37572</refnamediv>
37573<refsynopsisdiv>
37574 <title>Synopsis</title>
37575  <funcsynopsis><funcprototype>
37576   <funcdef>bool <function>intel_fbc_enabled </function></funcdef>
37577   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37578  </funcprototype></funcsynopsis>
37579</refsynopsisdiv>
37580<refsect1>
37581 <title>Arguments</title>
37582 <variablelist>
37583  <varlistentry>
37584   <term><parameter>dev</parameter></term>
37585   <listitem>
37586    <para>
37587     the drm_device
37588    </para>
37589   </listitem>
37590  </varlistentry>
37591 </variablelist>
37592</refsect1>
37593<refsect1>
37594<title>Description</title>
37595<para>
37596   This function is used to verify the current state of FBC.
37597</para>
37598</refsect1>
37599<refsect1>
37600<title>FIXME</title>
37601<para>
37602   This should be tracked in the plane config eventually
37603   instead of queried at runtime for most callers.
37604</para>
37605</refsect1>
37606</refentry>
37607
37608<refentry id="API-intel-fbc-disable">
37609<refentryinfo>
37610 <title>LINUX</title>
37611 <productname>Kernel Hackers Manual</productname>
37612 <date>July 2017</date>
37613</refentryinfo>
37614<refmeta>
37615 <refentrytitle><phrase>intel_fbc_disable</phrase></refentrytitle>
37616 <manvolnum>9</manvolnum>
37617 <refmiscinfo class="version">4.1.27</refmiscinfo>
37618</refmeta>
37619<refnamediv>
37620 <refname>intel_fbc_disable</refname>
37621 <refpurpose>
37622     disable FBC
37623 </refpurpose>
37624</refnamediv>
37625<refsynopsisdiv>
37626 <title>Synopsis</title>
37627  <funcsynopsis><funcprototype>
37628   <funcdef>void <function>intel_fbc_disable </function></funcdef>
37629   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37630  </funcprototype></funcsynopsis>
37631</refsynopsisdiv>
37632<refsect1>
37633 <title>Arguments</title>
37634 <variablelist>
37635  <varlistentry>
37636   <term><parameter>dev</parameter></term>
37637   <listitem>
37638    <para>
37639     the drm_device
37640    </para>
37641   </listitem>
37642  </varlistentry>
37643 </variablelist>
37644</refsect1>
37645<refsect1>
37646<title>Description</title>
37647<para>
37648   This function disables FBC.
37649</para>
37650</refsect1>
37651</refentry>
37652
37653<refentry id="API-intel-fbc-update">
37654<refentryinfo>
37655 <title>LINUX</title>
37656 <productname>Kernel Hackers Manual</productname>
37657 <date>July 2017</date>
37658</refentryinfo>
37659<refmeta>
37660 <refentrytitle><phrase>intel_fbc_update</phrase></refentrytitle>
37661 <manvolnum>9</manvolnum>
37662 <refmiscinfo class="version">4.1.27</refmiscinfo>
37663</refmeta>
37664<refnamediv>
37665 <refname>intel_fbc_update</refname>
37666 <refpurpose>
37667     enable/disable FBC as needed
37668 </refpurpose>
37669</refnamediv>
37670<refsynopsisdiv>
37671 <title>Synopsis</title>
37672  <funcsynopsis><funcprototype>
37673   <funcdef>void <function>intel_fbc_update </function></funcdef>
37674   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37675  </funcprototype></funcsynopsis>
37676</refsynopsisdiv>
37677<refsect1>
37678 <title>Arguments</title>
37679 <variablelist>
37680  <varlistentry>
37681   <term><parameter>dev</parameter></term>
37682   <listitem>
37683    <para>
37684     the drm_device
37685    </para>
37686   </listitem>
37687  </varlistentry>
37688 </variablelist>
37689</refsect1>
37690<refsect1>
37691<title>Description</title>
37692<para>
37693   Set up the framebuffer compression hardware at mode set time.  We
37694</para>
37695</refsect1>
37696<refsect1>
37697<title>enable it if possible</title>
37698<para>
37699   - plane A only (on pre-965)
37700   - no pixel mulitply/line duplication
37701   - no alpha buffer discard
37702   - no dual wide
37703   - framebuffer &lt;= max_hdisplay in width, max_vdisplay in height
37704   </para><para>
37705
37706   We can't assume that any compression will take place (worst case),
37707   so the compressed buffer has to be the same size as the uncompressed
37708   one.  It also must reside (along with the line length buffer) in
37709   stolen memory.
37710   </para><para>
37711
37712   We need to enable/disable FBC on a global basis.
37713</para>
37714</refsect1>
37715</refentry>
37716
37717<refentry id="API-intel-fbc-init">
37718<refentryinfo>
37719 <title>LINUX</title>
37720 <productname>Kernel Hackers Manual</productname>
37721 <date>July 2017</date>
37722</refentryinfo>
37723<refmeta>
37724 <refentrytitle><phrase>intel_fbc_init</phrase></refentrytitle>
37725 <manvolnum>9</manvolnum>
37726 <refmiscinfo class="version">4.1.27</refmiscinfo>
37727</refmeta>
37728<refnamediv>
37729 <refname>intel_fbc_init</refname>
37730 <refpurpose>
37731     Initialize FBC
37732 </refpurpose>
37733</refnamediv>
37734<refsynopsisdiv>
37735 <title>Synopsis</title>
37736  <funcsynopsis><funcprototype>
37737   <funcdef>void <function>intel_fbc_init </function></funcdef>
37738   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
37739  </funcprototype></funcsynopsis>
37740</refsynopsisdiv>
37741<refsect1>
37742 <title>Arguments</title>
37743 <variablelist>
37744  <varlistentry>
37745   <term><parameter>dev_priv</parameter></term>
37746   <listitem>
37747    <para>
37748     the i915 device
37749    </para>
37750   </listitem>
37751  </varlistentry>
37752 </variablelist>
37753</refsect1>
37754<refsect1>
37755<title>Description</title>
37756<para>
37757   This function might be called during PM init process.
37758</para>
37759</refsect1>
37760</refentry>
37761
37762      </sect2>
37763      <sect2>
37764        <title>Display Refresh Rate Switching (DRRS)</title>
37765<para>
37766   </para><para>
37767   Display Refresh Rate Switching (DRRS) is a power conservation feature
37768   which enables swtching between low and high refresh rates,
37769   dynamically, based on the usage scenario. This feature is applicable
37770   for internal panels.
37771   </para><para>
37772   Indication that the panel supports DRRS is given by the panel EDID, which
37773   would list multiple refresh rates for one resolution.
37774   </para><para>
37775   DRRS is of 2 types - static and seamless.
37776   Static DRRS involves changing refresh rate (RR) by doing a full modeset
37777   (may appear as a blink on screen) and is used in dock-undock scenario.
37778   Seamless DRRS involves changing RR without any visual effect to the user
37779   and can be used during normal system usage. This is done by programming
37780   certain registers.
37781   </para><para>
37782   Support for static/seamless DRRS may be indicated in the VBT based on
37783   inputs from the panel spec.
37784   </para><para>
37785   DRRS saves power by switching to low RR based on usage scenarios.
37786   </para><para>
37787   eDP DRRS:-
37788   The implementation is based on frontbuffer tracking implementation.
37789   When there is a disturbance on the screen triggered by user activity or a
37790   periodic system activity, DRRS is disabled (RR is changed to high RR).
37791   When there is no movement on screen, after a timeout of 1 second, a switch
37792   to low RR is made.
37793   For integration with frontbuffer tracking code,
37794   <function>intel_edp_drrs_invalidate</function> and <function>intel_edp_drrs_flush</function> are called.
37795   </para><para>
37796   DRRS can be further extended to support other internal panels and also
37797   the scenario of video playback wherein RR is set based on the rate
37798   requested by userspace.
37799</para>
37800
37801<refentry id="API-intel-dp-set-drrs-state">
37802<refentryinfo>
37803 <title>LINUX</title>
37804 <productname>Kernel Hackers Manual</productname>
37805 <date>July 2017</date>
37806</refentryinfo>
37807<refmeta>
37808 <refentrytitle><phrase>intel_dp_set_drrs_state</phrase></refentrytitle>
37809 <manvolnum>9</manvolnum>
37810 <refmiscinfo class="version">4.1.27</refmiscinfo>
37811</refmeta>
37812<refnamediv>
37813 <refname>intel_dp_set_drrs_state</refname>
37814 <refpurpose>
37815  program registers for RR switch to take effect
37816 </refpurpose>
37817</refnamediv>
37818<refsynopsisdiv>
37819 <title>Synopsis</title>
37820  <funcsynopsis><funcprototype>
37821   <funcdef>void <function>intel_dp_set_drrs_state </function></funcdef>
37822   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37823   <paramdef>int <parameter>refresh_rate</parameter></paramdef>
37824  </funcprototype></funcsynopsis>
37825</refsynopsisdiv>
37826<refsect1>
37827 <title>Arguments</title>
37828 <variablelist>
37829  <varlistentry>
37830   <term><parameter>dev</parameter></term>
37831   <listitem>
37832    <para>
37833     DRM device
37834    </para>
37835   </listitem>
37836  </varlistentry>
37837  <varlistentry>
37838   <term><parameter>refresh_rate</parameter></term>
37839   <listitem>
37840    <para>
37841     RR to be programmed
37842    </para>
37843   </listitem>
37844  </varlistentry>
37845 </variablelist>
37846</refsect1>
37847<refsect1>
37848<title>Description</title>
37849<para>
37850   This function gets called when refresh rate (RR) has to be changed from
37851   one frequency to another. Switches can be between high and low RR
37852   supported by the panel or to any other RR based on media playback (in
37853   this case, RR value needs to be passed from user space).
37854   </para><para>
37855
37856   The caller of this function needs to take a lock on dev_priv-&gt;drrs.
37857</para>
37858</refsect1>
37859</refentry>
37860
37861<refentry id="API-intel-edp-drrs-enable">
37862<refentryinfo>
37863 <title>LINUX</title>
37864 <productname>Kernel Hackers Manual</productname>
37865 <date>July 2017</date>
37866</refentryinfo>
37867<refmeta>
37868 <refentrytitle><phrase>intel_edp_drrs_enable</phrase></refentrytitle>
37869 <manvolnum>9</manvolnum>
37870 <refmiscinfo class="version">4.1.27</refmiscinfo>
37871</refmeta>
37872<refnamediv>
37873 <refname>intel_edp_drrs_enable</refname>
37874 <refpurpose>
37875  init drrs struct if supported
37876 </refpurpose>
37877</refnamediv>
37878<refsynopsisdiv>
37879 <title>Synopsis</title>
37880  <funcsynopsis><funcprototype>
37881   <funcdef>void <function>intel_edp_drrs_enable </function></funcdef>
37882   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
37883  </funcprototype></funcsynopsis>
37884</refsynopsisdiv>
37885<refsect1>
37886 <title>Arguments</title>
37887 <variablelist>
37888  <varlistentry>
37889   <term><parameter>intel_dp</parameter></term>
37890   <listitem>
37891    <para>
37892     DP struct
37893    </para>
37894   </listitem>
37895  </varlistentry>
37896 </variablelist>
37897</refsect1>
37898<refsect1>
37899<title>Description</title>
37900<para>
37901   Initializes frontbuffer_bits and drrs.dp
37902</para>
37903</refsect1>
37904</refentry>
37905
37906<refentry id="API-intel-edp-drrs-disable">
37907<refentryinfo>
37908 <title>LINUX</title>
37909 <productname>Kernel Hackers Manual</productname>
37910 <date>July 2017</date>
37911</refentryinfo>
37912<refmeta>
37913 <refentrytitle><phrase>intel_edp_drrs_disable</phrase></refentrytitle>
37914 <manvolnum>9</manvolnum>
37915 <refmiscinfo class="version">4.1.27</refmiscinfo>
37916</refmeta>
37917<refnamediv>
37918 <refname>intel_edp_drrs_disable</refname>
37919 <refpurpose>
37920  Disable DRRS
37921 </refpurpose>
37922</refnamediv>
37923<refsynopsisdiv>
37924 <title>Synopsis</title>
37925  <funcsynopsis><funcprototype>
37926   <funcdef>void <function>intel_edp_drrs_disable </function></funcdef>
37927   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
37928  </funcprototype></funcsynopsis>
37929</refsynopsisdiv>
37930<refsect1>
37931 <title>Arguments</title>
37932 <variablelist>
37933  <varlistentry>
37934   <term><parameter>intel_dp</parameter></term>
37935   <listitem>
37936    <para>
37937     DP struct
37938    </para>
37939   </listitem>
37940  </varlistentry>
37941 </variablelist>
37942</refsect1>
37943</refentry>
37944
37945<refentry id="API-intel-edp-drrs-invalidate">
37946<refentryinfo>
37947 <title>LINUX</title>
37948 <productname>Kernel Hackers Manual</productname>
37949 <date>July 2017</date>
37950</refentryinfo>
37951<refmeta>
37952 <refentrytitle><phrase>intel_edp_drrs_invalidate</phrase></refentrytitle>
37953 <manvolnum>9</manvolnum>
37954 <refmiscinfo class="version">4.1.27</refmiscinfo>
37955</refmeta>
37956<refnamediv>
37957 <refname>intel_edp_drrs_invalidate</refname>
37958 <refpurpose>
37959  Invalidate DRRS
37960 </refpurpose>
37961</refnamediv>
37962<refsynopsisdiv>
37963 <title>Synopsis</title>
37964  <funcsynopsis><funcprototype>
37965   <funcdef>void <function>intel_edp_drrs_invalidate </function></funcdef>
37966   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
37967   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
37968  </funcprototype></funcsynopsis>
37969</refsynopsisdiv>
37970<refsect1>
37971 <title>Arguments</title>
37972 <variablelist>
37973  <varlistentry>
37974   <term><parameter>dev</parameter></term>
37975   <listitem>
37976    <para>
37977     DRM device
37978    </para>
37979   </listitem>
37980  </varlistentry>
37981  <varlistentry>
37982   <term><parameter>frontbuffer_bits</parameter></term>
37983   <listitem>
37984    <para>
37985     frontbuffer plane tracking bits
37986    </para>
37987   </listitem>
37988  </varlistentry>
37989 </variablelist>
37990</refsect1>
37991<refsect1>
37992<title>Description</title>
37993<para>
37994   When there is a disturbance on screen (due to cursor movement/time
37995   update etc), DRRS needs to be invalidated, i.e. need to switch to
37996   high RR.
37997   </para><para>
37998
37999   Dirty frontbuffers relevant to DRRS are tracked in busy_frontbuffer_bits.
38000</para>
38001</refsect1>
38002</refentry>
38003
38004<refentry id="API-intel-edp-drrs-flush">
38005<refentryinfo>
38006 <title>LINUX</title>
38007 <productname>Kernel Hackers Manual</productname>
38008 <date>July 2017</date>
38009</refentryinfo>
38010<refmeta>
38011 <refentrytitle><phrase>intel_edp_drrs_flush</phrase></refentrytitle>
38012 <manvolnum>9</manvolnum>
38013 <refmiscinfo class="version">4.1.27</refmiscinfo>
38014</refmeta>
38015<refnamediv>
38016 <refname>intel_edp_drrs_flush</refname>
38017 <refpurpose>
38018  Flush DRRS
38019 </refpurpose>
38020</refnamediv>
38021<refsynopsisdiv>
38022 <title>Synopsis</title>
38023  <funcsynopsis><funcprototype>
38024   <funcdef>void <function>intel_edp_drrs_flush </function></funcdef>
38025   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
38026   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
38027  </funcprototype></funcsynopsis>
38028</refsynopsisdiv>
38029<refsect1>
38030 <title>Arguments</title>
38031 <variablelist>
38032  <varlistentry>
38033   <term><parameter>dev</parameter></term>
38034   <listitem>
38035    <para>
38036     DRM device
38037    </para>
38038   </listitem>
38039  </varlistentry>
38040  <varlistentry>
38041   <term><parameter>frontbuffer_bits</parameter></term>
38042   <listitem>
38043    <para>
38044     frontbuffer plane tracking bits
38045    </para>
38046   </listitem>
38047  </varlistentry>
38048 </variablelist>
38049</refsect1>
38050<refsect1>
38051<title>Description</title>
38052<para>
38053   When there is no movement on screen, DRRS work can be scheduled.
38054   This DRRS work is responsible for setting relevant registers after a
38055   timeout of 1 second.
38056   </para><para>
38057
38058   Dirty frontbuffers relevant to DRRS are tracked in busy_frontbuffer_bits.
38059</para>
38060</refsect1>
38061</refentry>
38062
38063<refentry id="API-intel-dp-drrs-init">
38064<refentryinfo>
38065 <title>LINUX</title>
38066 <productname>Kernel Hackers Manual</productname>
38067 <date>July 2017</date>
38068</refentryinfo>
38069<refmeta>
38070 <refentrytitle><phrase>intel_dp_drrs_init</phrase></refentrytitle>
38071 <manvolnum>9</manvolnum>
38072 <refmiscinfo class="version">4.1.27</refmiscinfo>
38073</refmeta>
38074<refnamediv>
38075 <refname>intel_dp_drrs_init</refname>
38076 <refpurpose>
38077  Init basic DRRS work and mutex.
38078 </refpurpose>
38079</refnamediv>
38080<refsynopsisdiv>
38081 <title>Synopsis</title>
38082  <funcsynopsis><funcprototype>
38083   <funcdef>struct drm_display_mode * <function>intel_dp_drrs_init </function></funcdef>
38084   <paramdef>struct intel_connector * <parameter>intel_connector</parameter></paramdef>
38085   <paramdef>struct drm_display_mode * <parameter>fixed_mode</parameter></paramdef>
38086  </funcprototype></funcsynopsis>
38087</refsynopsisdiv>
38088<refsect1>
38089 <title>Arguments</title>
38090 <variablelist>
38091  <varlistentry>
38092   <term><parameter>intel_connector</parameter></term>
38093   <listitem>
38094    <para>
38095     eDP connector
38096    </para>
38097   </listitem>
38098  </varlistentry>
38099  <varlistentry>
38100   <term><parameter>fixed_mode</parameter></term>
38101   <listitem>
38102    <para>
38103     preferred mode of panel
38104    </para>
38105   </listitem>
38106  </varlistentry>
38107 </variablelist>
38108</refsect1>
38109<refsect1>
38110<title>Description</title>
38111<para>
38112   This function is  called only once at driver load to initialize basic
38113   DRRS stuff.
38114</para>
38115</refsect1>
38116<refsect1>
38117<title>Returns</title>
38118<para>
38119   Downclock mode if panel supports it, else return NULL.
38120   DRRS support is determined by the presence of downclock mode (apart
38121   from VBT setting).
38122</para>
38123</refsect1>
38124</refentry>
38125
38126
38127      </sect2>
38128      <sect2>
38129        <title>DPIO</title>
38130<para>
38131   </para><para>
38132   VLV and CHV have slightly peculiar display PHYs for driving DP/HDMI
38133   ports. DPIO is the name given to such a display PHY. These PHYs
38134   don't follow the standard programming model using direct MMIO
38135   registers, and instead their registers must be accessed trough IOSF
38136   sideband. VLV has one such PHY for driving ports B and C, and CHV
38137   adds another PHY for driving port D. Each PHY responds to specific
38138   IOSF-SB port.
38139   </para><para>
38140   Each display PHY is made up of one or two channels. Each channel
38141   houses a common lane part which contains the PLL and other common
38142   logic. CH0 common lane also contains the IOSF-SB logic for the
38143   Common Register Interface (CRI) ie. the DPIO registers. CRI clock
38144   must be running when any DPIO registers are accessed.
38145   </para><para>
38146   In addition to having their own registers, the PHYs are also
38147   controlled through some dedicated signals from the display
38148   controller. These include PLL reference clock enable, PLL enable,
38149   and CRI clock selection, for example.
38150   </para><para>
38151   Eeach channel also has two splines (also called data lanes), and
38152   each spline is made up of one Physical Access Coding Sub-Layer
38153   (PCS) block and two TX lanes. So each channel has two PCS blocks
38154   and four TX lanes. The TX lanes are used as DP lanes or TMDS
38155   data/clock pairs depending on the output type.
38156   </para><para>
38157   Additionally the PHY also contains an AUX lane with AUX blocks
38158   for each channel. This is used for DP AUX communication, but
38159   this fact isn't really relevant for the driver since AUX is
38160   controlled from the display controller side. No DPIO registers
38161   need to be accessed during AUX communication,
38162   </para><para>
38163   Generally the common lane corresponds to the pipe and
38164   the spline (PCS/TX) corresponds to the port.
38165   </para><para>
38166   For dual channel PHY (VLV/CHV):
38167   </para><para>
38168   pipe A == CMN/PLL/REF CH0
38169   </para><para>
38170   pipe B == CMN/PLL/REF CH1
38171   </para><para>
38172   port B == PCS/TX CH0
38173   </para><para>
38174   port C == PCS/TX CH1
38175   </para><para>
38176   This is especially important when we cross the streams
38177   ie. drive port B with pipe B, or port C with pipe A.
38178   </para><para>
38179   For single channel PHY (CHV):
38180   </para><para>
38181   pipe C == CMN/PLL/REF CH0
38182   </para><para>
38183   port D == PCS/TX CH0
38184   </para><para>
38185   Note: digital port B is DDI0, digital port C is DDI1,
38186   digital port D is DDI2
38187</para>
38188
38189	<table id="dpiox2">
38190	  <title>Dual channel PHY (VLV/CHV)</title>
38191	  <tgroup cols="8">
38192	    <colspec colname="c0" />
38193	    <colspec colname="c1" />
38194	    <colspec colname="c2" />
38195	    <colspec colname="c3" />
38196	    <colspec colname="c4" />
38197	    <colspec colname="c5" />
38198	    <colspec colname="c6" />
38199	    <colspec colname="c7" />
38200	    <spanspec spanname="ch0" namest="c0" nameend="c3" />
38201	    <spanspec spanname="ch1" namest="c4" nameend="c7" />
38202	    <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" />
38203	    <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" />
38204	    <spanspec spanname="ch1pcs01" namest="c4" nameend="c5" />
38205	    <spanspec spanname="ch1pcs23" namest="c6" nameend="c7" />
38206	    <thead>
38207	      <row>
38208		<entry spanname="ch0">CH0</entry>
38209		<entry spanname="ch1">CH1</entry>
38210	      </row>
38211	    </thead>
38212	    <tbody valign="top" align="center">
38213	      <row>
38214		<entry spanname="ch0">CMN/PLL/REF</entry>
38215		<entry spanname="ch1">CMN/PLL/REF</entry>
38216	      </row>
38217	      <row>
38218		<entry spanname="ch0pcs01">PCS01</entry>
38219		<entry spanname="ch0pcs23">PCS23</entry>
38220		<entry spanname="ch1pcs01">PCS01</entry>
38221		<entry spanname="ch1pcs23">PCS23</entry>
38222	      </row>
38223	      <row>
38224		<entry>TX0</entry>
38225		<entry>TX1</entry>
38226		<entry>TX2</entry>
38227		<entry>TX3</entry>
38228		<entry>TX0</entry>
38229		<entry>TX1</entry>
38230		<entry>TX2</entry>
38231		<entry>TX3</entry>
38232	      </row>
38233	      <row>
38234		<entry spanname="ch0">DDI0</entry>
38235		<entry spanname="ch1">DDI1</entry>
38236	      </row>
38237	    </tbody>
38238	  </tgroup>
38239	</table>
38240	<table id="dpiox1">
38241	  <title>Single channel PHY (CHV)</title>
38242	  <tgroup cols="4">
38243	    <colspec colname="c0" />
38244	    <colspec colname="c1" />
38245	    <colspec colname="c2" />
38246	    <colspec colname="c3" />
38247	    <spanspec spanname="ch0" namest="c0" nameend="c3" />
38248	    <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" />
38249	    <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" />
38250	    <thead>
38251	      <row>
38252		<entry spanname="ch0">CH0</entry>
38253	      </row>
38254	    </thead>
38255	    <tbody valign="top" align="center">
38256	      <row>
38257		<entry spanname="ch0">CMN/PLL/REF</entry>
38258	      </row>
38259	      <row>
38260		<entry spanname="ch0pcs01">PCS01</entry>
38261		<entry spanname="ch0pcs23">PCS23</entry>
38262	      </row>
38263	      <row>
38264		<entry>TX0</entry>
38265		<entry>TX1</entry>
38266		<entry>TX2</entry>
38267		<entry>TX3</entry>
38268	      </row>
38269	      <row>
38270		<entry spanname="ch0">DDI2</entry>
38271	      </row>
38272	    </tbody>
38273	  </tgroup>
38274	</table>
38275      </sect2>
38276    </sect1>
38277
38278    <sect1>
38279      <title>Memory Management and Command Submission</title>
38280      <para>
38281	This sections covers all things related to the GEM implementation in the
38282	i915 driver.
38283      </para>
38284      <sect2>
38285        <title>Batchbuffer Parsing</title>
38286<para>
38287   </para><para>
38288   Motivation:
38289   Certain OpenGL features (e.g. transform feedback, performance monitoring)
38290   require userspace code to submit batches containing commands such as
38291   MI_LOAD_REGISTER_IMM to access various registers. Unfortunately, some
38292   generations of the hardware will noop these commands in <quote>unsecure</quote> batches
38293   (which includes all userspace batches submitted via i915) even though the
38294   commands may be safe and represent the intended programming model of the
38295   device.
38296   </para><para>
38297   The software command parser is similar in operation to the command parsing
38298   done in hardware for unsecure batches. However, the software parser allows
38299   some operations that would be noop'd by hardware, if the parser determines
38300   the operation is safe, and submits the batch as <quote>secure</quote> to prevent hardware
38301   parsing.
38302   </para><para>
38303   Threats:
38304   At a high level, the hardware (and software) checks attempt to prevent
38305   granting userspace undue privileges. There are three categories of privilege.
38306   </para><para>
38307   First, commands which are explicitly defined as privileged or which should
38308   only be used by the kernel driver. The parser generally rejects such
38309   commands, though it may allow some from the drm master process.
38310   </para><para>
38311   Second, commands which access registers. To support correct/enhanced
38312   userspace functionality, particularly certain OpenGL extensions, the parser
38313   provides a whitelist of registers which userspace may safely access (for both
38314   normal and drm master processes).
38315   </para><para>
38316   Third, commands which access privileged memory (i.e. GGTT, HWS page, etc).
38317   The parser always rejects such commands.
38318   </para><para>
38319   The majority of the problematic commands fall in the MI_* range, with only a
38320   few specific commands on each ring (e.g. PIPE_CONTROL and MI_FLUSH_DW).
38321   </para><para>
38322   Implementation:
38323   Each ring maintains tables of commands and registers which the parser uses in
38324   scanning batch buffers submitted to that ring.
38325   </para><para>
38326   Since the set of commands that the parser must check for is significantly
38327   smaller than the number of commands supported, the parser tables contain only
38328   those commands required by the parser. This generally works because command
38329   opcode ranges have standard command length encodings. So for commands that
38330   the parser does not need to check, it can easily skip them. This is
38331   implemented via a per-ring length decoding vfunc.
38332   </para><para>
38333   Unfortunately, there are a number of commands that do not follow the standard
38334   length encoding for their opcode range, primarily amongst the MI_* commands.
38335   To handle this, the parser provides a way to define explicit <quote>skip</quote> entries
38336   in the per-ring command tables.
38337   </para><para>
38338   Other command table entries map fairly directly to high level categories
38339   mentioned above: rejected, master-only, register whitelist. The parser
38340   implements a number of checks, including the privileged memory checks, via a
38341   general bitmasking mechanism.
38342</para>
38343
38344<!-- drivers/gpu/drm/i915/i915_cmd_parser.c -->
38345<refentry id="API-i915-cmd-parser-init-ring">
38346<refentryinfo>
38347 <title>LINUX</title>
38348 <productname>Kernel Hackers Manual</productname>
38349 <date>July 2017</date>
38350</refentryinfo>
38351<refmeta>
38352 <refentrytitle><phrase>i915_cmd_parser_init_ring</phrase></refentrytitle>
38353 <manvolnum>9</manvolnum>
38354 <refmiscinfo class="version">4.1.27</refmiscinfo>
38355</refmeta>
38356<refnamediv>
38357 <refname>i915_cmd_parser_init_ring</refname>
38358 <refpurpose>
38359  set cmd parser related fields for a ringbuffer
38360 </refpurpose>
38361</refnamediv>
38362<refsynopsisdiv>
38363 <title>Synopsis</title>
38364  <funcsynopsis><funcprototype>
38365   <funcdef>int <function>i915_cmd_parser_init_ring </function></funcdef>
38366   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
38367  </funcprototype></funcsynopsis>
38368</refsynopsisdiv>
38369<refsect1>
38370 <title>Arguments</title>
38371 <variablelist>
38372  <varlistentry>
38373   <term><parameter>ring</parameter></term>
38374   <listitem>
38375    <para>
38376     the ringbuffer to initialize
38377    </para>
38378   </listitem>
38379  </varlistentry>
38380 </variablelist>
38381</refsect1>
38382<refsect1>
38383<title>Description</title>
38384<para>
38385   Optionally initializes fields related to batch buffer command parsing in the
38386   struct intel_engine_cs based on whether the platform requires software
38387   command parsing.
38388</para>
38389</refsect1>
38390<refsect1>
38391<title>Return</title>
38392<para>
38393   non-zero if initialization fails
38394</para>
38395</refsect1>
38396</refentry>
38397
38398<refentry id="API-i915-cmd-parser-fini-ring">
38399<refentryinfo>
38400 <title>LINUX</title>
38401 <productname>Kernel Hackers Manual</productname>
38402 <date>July 2017</date>
38403</refentryinfo>
38404<refmeta>
38405 <refentrytitle><phrase>i915_cmd_parser_fini_ring</phrase></refentrytitle>
38406 <manvolnum>9</manvolnum>
38407 <refmiscinfo class="version">4.1.27</refmiscinfo>
38408</refmeta>
38409<refnamediv>
38410 <refname>i915_cmd_parser_fini_ring</refname>
38411 <refpurpose>
38412     clean up cmd parser related fields
38413 </refpurpose>
38414</refnamediv>
38415<refsynopsisdiv>
38416 <title>Synopsis</title>
38417  <funcsynopsis><funcprototype>
38418   <funcdef>void <function>i915_cmd_parser_fini_ring </function></funcdef>
38419   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
38420  </funcprototype></funcsynopsis>
38421</refsynopsisdiv>
38422<refsect1>
38423 <title>Arguments</title>
38424 <variablelist>
38425  <varlistentry>
38426   <term><parameter>ring</parameter></term>
38427   <listitem>
38428    <para>
38429     the ringbuffer to clean up
38430    </para>
38431   </listitem>
38432  </varlistentry>
38433 </variablelist>
38434</refsect1>
38435<refsect1>
38436<title>Description</title>
38437<para>
38438   Releases any resources related to command parsing that may have been
38439   initialized for the specified ring.
38440</para>
38441</refsect1>
38442</refentry>
38443
38444<refentry id="API-i915-needs-cmd-parser">
38445<refentryinfo>
38446 <title>LINUX</title>
38447 <productname>Kernel Hackers Manual</productname>
38448 <date>July 2017</date>
38449</refentryinfo>
38450<refmeta>
38451 <refentrytitle><phrase>i915_needs_cmd_parser</phrase></refentrytitle>
38452 <manvolnum>9</manvolnum>
38453 <refmiscinfo class="version">4.1.27</refmiscinfo>
38454</refmeta>
38455<refnamediv>
38456 <refname>i915_needs_cmd_parser</refname>
38457 <refpurpose>
38458     should a given ring use software command parsing?
38459 </refpurpose>
38460</refnamediv>
38461<refsynopsisdiv>
38462 <title>Synopsis</title>
38463  <funcsynopsis><funcprototype>
38464   <funcdef>bool <function>i915_needs_cmd_parser </function></funcdef>
38465   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
38466  </funcprototype></funcsynopsis>
38467</refsynopsisdiv>
38468<refsect1>
38469 <title>Arguments</title>
38470 <variablelist>
38471  <varlistentry>
38472   <term><parameter>ring</parameter></term>
38473   <listitem>
38474    <para>
38475     the ring in question
38476    </para>
38477   </listitem>
38478  </varlistentry>
38479 </variablelist>
38480</refsect1>
38481<refsect1>
38482<title>Description</title>
38483<para>
38484   Only certain platforms require software batch buffer command parsing, and
38485   only when enabled via module parameter.
38486</para>
38487</refsect1>
38488<refsect1>
38489<title>Return</title>
38490<para>
38491   true if the ring requires software command parsing
38492</para>
38493</refsect1>
38494</refentry>
38495
38496<refentry id="API-i915-parse-cmds">
38497<refentryinfo>
38498 <title>LINUX</title>
38499 <productname>Kernel Hackers Manual</productname>
38500 <date>July 2017</date>
38501</refentryinfo>
38502<refmeta>
38503 <refentrytitle><phrase>i915_parse_cmds</phrase></refentrytitle>
38504 <manvolnum>9</manvolnum>
38505 <refmiscinfo class="version">4.1.27</refmiscinfo>
38506</refmeta>
38507<refnamediv>
38508 <refname>i915_parse_cmds</refname>
38509 <refpurpose>
38510     parse a submitted batch buffer for privilege violations
38511 </refpurpose>
38512</refnamediv>
38513<refsynopsisdiv>
38514 <title>Synopsis</title>
38515  <funcsynopsis><funcprototype>
38516   <funcdef>int <function>i915_parse_cmds </function></funcdef>
38517   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
38518   <paramdef>struct drm_i915_gem_object * <parameter>batch_obj</parameter></paramdef>
38519   <paramdef>struct drm_i915_gem_object * <parameter>shadow_batch_obj</parameter></paramdef>
38520   <paramdef>u32 <parameter>batch_start_offset</parameter></paramdef>
38521   <paramdef>u32 <parameter>batch_len</parameter></paramdef>
38522   <paramdef>bool <parameter>is_master</parameter></paramdef>
38523  </funcprototype></funcsynopsis>
38524</refsynopsisdiv>
38525<refsect1>
38526 <title>Arguments</title>
38527 <variablelist>
38528  <varlistentry>
38529   <term><parameter>ring</parameter></term>
38530   <listitem>
38531    <para>
38532     the ring on which the batch is to execute
38533    </para>
38534   </listitem>
38535  </varlistentry>
38536  <varlistentry>
38537   <term><parameter>batch_obj</parameter></term>
38538   <listitem>
38539    <para>
38540     the batch buffer in question
38541    </para>
38542   </listitem>
38543  </varlistentry>
38544  <varlistentry>
38545   <term><parameter>shadow_batch_obj</parameter></term>
38546   <listitem>
38547    <para>
38548     copy of the batch buffer in question
38549    </para>
38550   </listitem>
38551  </varlistentry>
38552  <varlistentry>
38553   <term><parameter>batch_start_offset</parameter></term>
38554   <listitem>
38555    <para>
38556     byte offset in the batch at which execution starts
38557    </para>
38558   </listitem>
38559  </varlistentry>
38560  <varlistentry>
38561   <term><parameter>batch_len</parameter></term>
38562   <listitem>
38563    <para>
38564     length of the commands in batch_obj
38565    </para>
38566   </listitem>
38567  </varlistentry>
38568  <varlistentry>
38569   <term><parameter>is_master</parameter></term>
38570   <listitem>
38571    <para>
38572     is the submitting process the drm master?
38573    </para>
38574   </listitem>
38575  </varlistentry>
38576 </variablelist>
38577</refsect1>
38578<refsect1>
38579<title>Description</title>
38580<para>
38581   Parses the specified batch buffer looking for privilege violations as
38582   described in the overview.
38583</para>
38584</refsect1>
38585<refsect1>
38586<title>Return</title>
38587<para>
38588   non-zero if the parser finds violations or otherwise fails; -EACCES
38589   if the batch appears legal but should use hardware parsing
38590</para>
38591</refsect1>
38592</refentry>
38593
38594<refentry id="API-i915-cmd-parser-get-version">
38595<refentryinfo>
38596 <title>LINUX</title>
38597 <productname>Kernel Hackers Manual</productname>
38598 <date>July 2017</date>
38599</refentryinfo>
38600<refmeta>
38601 <refentrytitle><phrase>i915_cmd_parser_get_version</phrase></refentrytitle>
38602 <manvolnum>9</manvolnum>
38603 <refmiscinfo class="version">4.1.27</refmiscinfo>
38604</refmeta>
38605<refnamediv>
38606 <refname>i915_cmd_parser_get_version</refname>
38607 <refpurpose>
38608     get the cmd parser version number
38609 </refpurpose>
38610</refnamediv>
38611<refsynopsisdiv>
38612 <title>Synopsis</title>
38613  <funcsynopsis><funcprototype>
38614   <funcdef>int <function>i915_cmd_parser_get_version </function></funcdef>
38615   <paramdef> <parameter>void</parameter></paramdef>
38616  </funcprototype></funcsynopsis>
38617</refsynopsisdiv>
38618<refsect1>
38619 <title>Arguments</title>
38620 <variablelist>
38621  <varlistentry>
38622   <term><parameter>void</parameter></term>
38623   <listitem>
38624    <para>
38625     no arguments
38626    </para>
38627   </listitem>
38628  </varlistentry>
38629 </variablelist>
38630</refsect1>
38631<refsect1>
38632<title>Description</title>
38633<para>
38634   </para><para>
38635
38636   The cmd parser maintains a simple increasing integer version number suitable
38637   for passing to userspace clients to determine what operations are permitted.
38638</para>
38639</refsect1>
38640<refsect1>
38641<title>Return</title>
38642<para>
38643   the current version number of the cmd parser
38644</para>
38645</refsect1>
38646</refentry>
38647
38648      </sect2>
38649      <sect2>
38650        <title>Batchbuffer Pools</title>
38651<para>
38652   </para><para>
38653   In order to submit batch buffers as 'secure', the software command parser
38654   must ensure that a batch buffer cannot be modified after parsing. It does
38655   this by copying the user provided batch buffer contents to a kernel owned
38656   buffer from which the hardware will actually execute, and by carefully
38657   managing the address space bindings for such buffers.
38658   </para><para>
38659   The batch pool framework provides a mechanism for the driver to manage a
38660   set of scratch buffers to use for this purpose. The framework can be
38661   extended to support other uses cases should they arise.
38662</para>
38663
38664<!-- drivers/gpu/drm/i915/i915_gem_batch_pool.c -->
38665<refentry id="API-i915-gem-batch-pool-init">
38666<refentryinfo>
38667 <title>LINUX</title>
38668 <productname>Kernel Hackers Manual</productname>
38669 <date>July 2017</date>
38670</refentryinfo>
38671<refmeta>
38672 <refentrytitle><phrase>i915_gem_batch_pool_init</phrase></refentrytitle>
38673 <manvolnum>9</manvolnum>
38674 <refmiscinfo class="version">4.1.27</refmiscinfo>
38675</refmeta>
38676<refnamediv>
38677 <refname>i915_gem_batch_pool_init</refname>
38678 <refpurpose>
38679  initialize a batch buffer pool
38680 </refpurpose>
38681</refnamediv>
38682<refsynopsisdiv>
38683 <title>Synopsis</title>
38684  <funcsynopsis><funcprototype>
38685   <funcdef>void <function>i915_gem_batch_pool_init </function></funcdef>
38686   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
38687   <paramdef>struct i915_gem_batch_pool * <parameter>pool</parameter></paramdef>
38688  </funcprototype></funcsynopsis>
38689</refsynopsisdiv>
38690<refsect1>
38691 <title>Arguments</title>
38692 <variablelist>
38693  <varlistentry>
38694   <term><parameter>dev</parameter></term>
38695   <listitem>
38696    <para>
38697     the drm device
38698    </para>
38699   </listitem>
38700  </varlistentry>
38701  <varlistentry>
38702   <term><parameter>pool</parameter></term>
38703   <listitem>
38704    <para>
38705     the batch buffer pool
38706    </para>
38707   </listitem>
38708  </varlistentry>
38709 </variablelist>
38710</refsect1>
38711</refentry>
38712
38713<refentry id="API-i915-gem-batch-pool-fini">
38714<refentryinfo>
38715 <title>LINUX</title>
38716 <productname>Kernel Hackers Manual</productname>
38717 <date>July 2017</date>
38718</refentryinfo>
38719<refmeta>
38720 <refentrytitle><phrase>i915_gem_batch_pool_fini</phrase></refentrytitle>
38721 <manvolnum>9</manvolnum>
38722 <refmiscinfo class="version">4.1.27</refmiscinfo>
38723</refmeta>
38724<refnamediv>
38725 <refname>i915_gem_batch_pool_fini</refname>
38726 <refpurpose>
38727     clean up a batch buffer pool
38728 </refpurpose>
38729</refnamediv>
38730<refsynopsisdiv>
38731 <title>Synopsis</title>
38732  <funcsynopsis><funcprototype>
38733   <funcdef>void <function>i915_gem_batch_pool_fini </function></funcdef>
38734   <paramdef>struct i915_gem_batch_pool * <parameter>pool</parameter></paramdef>
38735  </funcprototype></funcsynopsis>
38736</refsynopsisdiv>
38737<refsect1>
38738 <title>Arguments</title>
38739 <variablelist>
38740  <varlistentry>
38741   <term><parameter>pool</parameter></term>
38742   <listitem>
38743    <para>
38744     the pool to clean up
38745    </para>
38746   </listitem>
38747  </varlistentry>
38748 </variablelist>
38749</refsect1>
38750<refsect1>
38751<title>Note</title>
38752<para>
38753   Callers must hold the struct_mutex.
38754</para>
38755</refsect1>
38756</refentry>
38757
38758<refentry id="API-i915-gem-batch-pool-get">
38759<refentryinfo>
38760 <title>LINUX</title>
38761 <productname>Kernel Hackers Manual</productname>
38762 <date>July 2017</date>
38763</refentryinfo>
38764<refmeta>
38765 <refentrytitle><phrase>i915_gem_batch_pool_get</phrase></refentrytitle>
38766 <manvolnum>9</manvolnum>
38767 <refmiscinfo class="version">4.1.27</refmiscinfo>
38768</refmeta>
38769<refnamediv>
38770 <refname>i915_gem_batch_pool_get</refname>
38771 <refpurpose>
38772     select a buffer from the pool
38773 </refpurpose>
38774</refnamediv>
38775<refsynopsisdiv>
38776 <title>Synopsis</title>
38777  <funcsynopsis><funcprototype>
38778   <funcdef>struct drm_i915_gem_object * <function>i915_gem_batch_pool_get </function></funcdef>
38779   <paramdef>struct i915_gem_batch_pool * <parameter>pool</parameter></paramdef>
38780   <paramdef>size_t <parameter>size</parameter></paramdef>
38781  </funcprototype></funcsynopsis>
38782</refsynopsisdiv>
38783<refsect1>
38784 <title>Arguments</title>
38785 <variablelist>
38786  <varlistentry>
38787   <term><parameter>pool</parameter></term>
38788   <listitem>
38789    <para>
38790     the batch buffer pool
38791    </para>
38792   </listitem>
38793  </varlistentry>
38794  <varlistentry>
38795   <term><parameter>size</parameter></term>
38796   <listitem>
38797    <para>
38798     the minimum desired size of the returned buffer
38799    </para>
38800   </listitem>
38801  </varlistentry>
38802 </variablelist>
38803</refsect1>
38804<refsect1>
38805<title>Description</title>
38806<para>
38807   Finds or allocates a batch buffer in the pool with at least the requested
38808   size. The caller is responsible for any domain, active/inactive, or
38809   purgeability management for the returned buffer.
38810</para>
38811</refsect1>
38812<refsect1>
38813<title>Note</title>
38814<para>
38815   Callers must hold the struct_mutex
38816</para>
38817</refsect1>
38818<refsect1>
38819<title>Return</title>
38820<para>
38821   the selected batch buffer object
38822</para>
38823</refsect1>
38824</refentry>
38825
38826      </sect2>
38827      <sect2>
38828        <title>Logical Rings, Logical Ring Contexts and Execlists</title>
38829<para>
38830   </para><para>
38831   Motivation:
38832   GEN8 brings an expansion of the HW contexts: <quote>Logical Ring Contexts</quote>.
38833   These expanded contexts enable a number of new abilities, especially
38834   <quote>Execlists</quote> (also implemented in this file).
38835   </para><para>
38836   One of the main differences with the legacy HW contexts is that logical
38837   ring contexts incorporate many more things to the context's state, like
38838   PDPs or ringbuffer control registers:
38839   </para><para>
38840   The reason why PDPs are included in the context is straightforward: as
38841   PPGTTs (per-process GTTs) are actually per-context, having the PDPs
38842   contained there mean you don't need to do a ppgtt-&gt;switch_mm yourself,
38843   instead, the GPU will do it for you on the context switch.
38844   </para><para>
38845   But, what about the ringbuffer control registers (head, tail, etc..)?
38846   shouldn't we just need a set of those per engine command streamer? This is
38847   where the name <quote>Logical Rings</quote> starts to make sense: by virtualizing the
38848   rings, the engine cs shifts to a new <quote>ring buffer</quote> with every context
38849   switch. When you want to submit a workload to the GPU you: A) choose your
38850   context, B) find its appropriate virtualized ring, C) write commands to it
38851   and then, finally, D) tell the GPU to switch to that context.
38852   </para><para>
38853   Instead of the legacy MI_SET_CONTEXT, the way you tell the GPU to switch
38854   to a contexts is via a context execution list, ergo <quote>Execlists</quote>.
38855   </para><para>
38856   LRC implementation:
38857   Regarding the creation of contexts, we have:
38858   </para><para>
38859   - One global default context.
38860   - One local default context for each opened fd.
38861   - One local extra context for each context create ioctl call.
38862   </para><para>
38863   Now that ringbuffers belong per-context (and not per-engine, like before)
38864   and that contexts are uniquely tied to a given engine (and not reusable,
38865   like before) we need:
38866   </para><para>
38867   - One ringbuffer per-engine inside each context.
38868   - One backing object per-engine inside each context.
38869   </para><para>
38870   The global default context starts its life with these new objects fully
38871   allocated and populated. The local default context for each opened fd is
38872   more complex, because we don't know at creation time which engine is going
38873   to use them. To handle this, we have implemented a deferred creation of LR
38874   contexts:
38875   </para><para>
38876   The local context starts its life as a hollow or blank holder, that only
38877   gets populated for a given engine once we receive an execbuffer. If later
38878   on we receive another execbuffer ioctl for the same context but a different
38879   engine, we allocate/populate a new ringbuffer and context backing object and
38880   so on.
38881   </para><para>
38882   Finally, regarding local contexts created using the ioctl call: as they are
38883   only allowed with the render ring, we can allocate &amp; populate them right
38884   away (no need to defer anything, at least for now).
38885   </para><para>
38886   Execlists implementation:
38887   Execlists are the new method by which, on gen8+ hardware, workloads are
38888   submitted for execution (as opposed to the legacy, ringbuffer-based, method).
38889   This method works as follows:
38890   </para><para>
38891   When a request is committed, its commands (the BB start and any leading or
38892   trailing commands, like the seqno breadcrumbs) are placed in the ringbuffer
38893   for the appropriate context. The tail pointer in the hardware context is not
38894   updated at this time, but instead, kept by the driver in the ringbuffer
38895   structure. A structure representing this request is added to a request queue
38896   for the appropriate engine: this structure contains a copy of the context's
38897   tail after the request was written to the ring buffer and a pointer to the
38898   context itself.
38899   </para><para>
38900   If the engine's request queue was empty before the request was added, the
38901   queue is processed immediately. Otherwise the queue will be processed during
38902   a context switch interrupt. In any case, elements on the queue will get sent
38903   (in pairs) to the GPU's ExecLists Submit Port (ELSP, for short) with a
38904   globally unique 20-bits submission ID.
38905   </para><para>
38906   When execution of a request completes, the GPU updates the context status
38907   buffer with a context complete event and generates a context switch interrupt.
38908   During the interrupt handling, the driver examines the events in the buffer:
38909   for each context complete event, if the announced ID matches that on the head
38910   of the request queue, then that request is retired and removed from the queue.
38911   </para><para>
38912   After processing, if any requests were retired and the queue is not empty
38913   then a new execution list can be submitted. The two requests at the front of
38914   the queue are next to be submitted but since a context may not occur twice in
38915   an execution list, if subsequent requests have the same ID as the first then
38916   the two requests must be combined. This is done simply by discarding requests
38917   at the head of the queue until either only one requests is left (in which case
38918   we use a NULL second context) or the first two requests have unique IDs.
38919   </para><para>
38920   By always executing the first two requests in the queue the driver ensures
38921   that the GPU is kept as busy as possible. In the case where a single context
38922   completes but a second context is still executing, the request for this second
38923   context will be at the head of the queue when we remove the first one. This
38924   request will then be resubmitted along with a new request for a different context,
38925   which will cause the hardware to continue executing the second request and queue
38926   the new request (the GPU detects the condition of a context getting preempted
38927   with the same context and optimizes the context switch flow by not doing
38928   preemption, but just sampling the new tail pointer).
38929   </para><para>
38930</para>
38931
38932<!-- drivers/gpu/drm/i915/intel_lrc.c -->
38933<refentry id="API-intel-sanitize-enable-execlists">
38934<refentryinfo>
38935 <title>LINUX</title>
38936 <productname>Kernel Hackers Manual</productname>
38937 <date>July 2017</date>
38938</refentryinfo>
38939<refmeta>
38940 <refentrytitle><phrase>intel_sanitize_enable_execlists</phrase></refentrytitle>
38941 <manvolnum>9</manvolnum>
38942 <refmiscinfo class="version">4.1.27</refmiscinfo>
38943</refmeta>
38944<refnamediv>
38945 <refname>intel_sanitize_enable_execlists</refname>
38946 <refpurpose>
38947  sanitize i915.enable_execlists
38948 </refpurpose>
38949</refnamediv>
38950<refsynopsisdiv>
38951 <title>Synopsis</title>
38952  <funcsynopsis><funcprototype>
38953   <funcdef>int <function>intel_sanitize_enable_execlists </function></funcdef>
38954   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
38955   <paramdef>int <parameter>enable_execlists</parameter></paramdef>
38956  </funcprototype></funcsynopsis>
38957</refsynopsisdiv>
38958<refsect1>
38959 <title>Arguments</title>
38960 <variablelist>
38961  <varlistentry>
38962   <term><parameter>dev</parameter></term>
38963   <listitem>
38964    <para>
38965     DRM device.
38966    </para>
38967   </listitem>
38968  </varlistentry>
38969  <varlistentry>
38970   <term><parameter>enable_execlists</parameter></term>
38971   <listitem>
38972    <para>
38973     value of i915.enable_execlists module parameter.
38974    </para>
38975   </listitem>
38976  </varlistentry>
38977 </variablelist>
38978</refsect1>
38979<refsect1>
38980<title>Description</title>
38981<para>
38982   Only certain platforms support Execlists (the prerequisites being
38983   support for Logical Ring Contexts and Aliasing PPGTT or better).
38984</para>
38985</refsect1>
38986<refsect1>
38987<title>Return</title>
38988<para>
38989   1 if Execlists is supported and has to be enabled.
38990</para>
38991</refsect1>
38992</refentry>
38993
38994<refentry id="API-intel-execlists-ctx-id">
38995<refentryinfo>
38996 <title>LINUX</title>
38997 <productname>Kernel Hackers Manual</productname>
38998 <date>July 2017</date>
38999</refentryinfo>
39000<refmeta>
39001 <refentrytitle><phrase>intel_execlists_ctx_id</phrase></refentrytitle>
39002 <manvolnum>9</manvolnum>
39003 <refmiscinfo class="version">4.1.27</refmiscinfo>
39004</refmeta>
39005<refnamediv>
39006 <refname>intel_execlists_ctx_id</refname>
39007 <refpurpose>
39008     get the Execlists Context ID
39009 </refpurpose>
39010</refnamediv>
39011<refsynopsisdiv>
39012 <title>Synopsis</title>
39013  <funcsynopsis><funcprototype>
39014   <funcdef>u32 <function>intel_execlists_ctx_id </function></funcdef>
39015   <paramdef>struct drm_i915_gem_object * <parameter>ctx_obj</parameter></paramdef>
39016  </funcprototype></funcsynopsis>
39017</refsynopsisdiv>
39018<refsect1>
39019 <title>Arguments</title>
39020 <variablelist>
39021  <varlistentry>
39022   <term><parameter>ctx_obj</parameter></term>
39023   <listitem>
39024    <para>
39025     Logical Ring Context backing object.
39026    </para>
39027   </listitem>
39028  </varlistentry>
39029 </variablelist>
39030</refsect1>
39031<refsect1>
39032<title>Description</title>
39033<para>
39034   Do not confuse with ctx-&gt;id! Unfortunately we have a name overload
39035</para>
39036</refsect1>
39037<refsect1>
39038<title>here</title>
39039<para>
39040   the old context ID we pass to userspace as a handler so that
39041   they can refer to a context, and the new context ID we pass to the
39042   ELSP so that the GPU can inform us of the context status via
39043   interrupts.
39044</para>
39045</refsect1>
39046<refsect1>
39047<title>Return</title>
39048<para>
39049   20-bits globally unique context ID.
39050</para>
39051</refsect1>
39052</refentry>
39053
39054<refentry id="API-intel-lrc-irq-handler">
39055<refentryinfo>
39056 <title>LINUX</title>
39057 <productname>Kernel Hackers Manual</productname>
39058 <date>July 2017</date>
39059</refentryinfo>
39060<refmeta>
39061 <refentrytitle><phrase>intel_lrc_irq_handler</phrase></refentrytitle>
39062 <manvolnum>9</manvolnum>
39063 <refmiscinfo class="version">4.1.27</refmiscinfo>
39064</refmeta>
39065<refnamediv>
39066 <refname>intel_lrc_irq_handler</refname>
39067 <refpurpose>
39068     handle Context Switch interrupts
39069 </refpurpose>
39070</refnamediv>
39071<refsynopsisdiv>
39072 <title>Synopsis</title>
39073  <funcsynopsis><funcprototype>
39074   <funcdef>void <function>intel_lrc_irq_handler </function></funcdef>
39075   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
39076  </funcprototype></funcsynopsis>
39077</refsynopsisdiv>
39078<refsect1>
39079 <title>Arguments</title>
39080 <variablelist>
39081  <varlistentry>
39082   <term><parameter>ring</parameter></term>
39083   <listitem>
39084    <para>
39085     Engine Command Streamer to handle.
39086    </para>
39087   </listitem>
39088  </varlistentry>
39089 </variablelist>
39090</refsect1>
39091<refsect1>
39092<title>Description</title>
39093<para>
39094   Check the unread Context Status Buffers and manage the submission of new
39095   contexts to the ELSP accordingly.
39096</para>
39097</refsect1>
39098</refentry>
39099
39100<refentry id="API-intel-execlists-submission">
39101<refentryinfo>
39102 <title>LINUX</title>
39103 <productname>Kernel Hackers Manual</productname>
39104 <date>July 2017</date>
39105</refentryinfo>
39106<refmeta>
39107 <refentrytitle><phrase>intel_execlists_submission</phrase></refentrytitle>
39108 <manvolnum>9</manvolnum>
39109 <refmiscinfo class="version">4.1.27</refmiscinfo>
39110</refmeta>
39111<refnamediv>
39112 <refname>intel_execlists_submission</refname>
39113 <refpurpose>
39114     submit a batchbuffer for execution, Execlists style
39115 </refpurpose>
39116</refnamediv>
39117<refsynopsisdiv>
39118 <title>Synopsis</title>
39119  <funcsynopsis><funcprototype>
39120   <funcdef>int <function>intel_execlists_submission </function></funcdef>
39121   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
39122   <paramdef>struct drm_file * <parameter>file</parameter></paramdef>
39123   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
39124   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
39125   <paramdef>struct drm_i915_gem_execbuffer2 * <parameter>args</parameter></paramdef>
39126   <paramdef>struct list_head * <parameter>vmas</parameter></paramdef>
39127   <paramdef>struct drm_i915_gem_object * <parameter>batch_obj</parameter></paramdef>
39128   <paramdef>u64 <parameter>exec_start</parameter></paramdef>
39129   <paramdef>u32 <parameter>dispatch_flags</parameter></paramdef>
39130  </funcprototype></funcsynopsis>
39131</refsynopsisdiv>
39132<refsect1>
39133 <title>Arguments</title>
39134 <variablelist>
39135  <varlistentry>
39136   <term><parameter>dev</parameter></term>
39137   <listitem>
39138    <para>
39139     DRM device.
39140    </para>
39141   </listitem>
39142  </varlistentry>
39143  <varlistentry>
39144   <term><parameter>file</parameter></term>
39145   <listitem>
39146    <para>
39147     DRM file.
39148    </para>
39149   </listitem>
39150  </varlistentry>
39151  <varlistentry>
39152   <term><parameter>ring</parameter></term>
39153   <listitem>
39154    <para>
39155     Engine Command Streamer to submit to.
39156    </para>
39157   </listitem>
39158  </varlistentry>
39159  <varlistentry>
39160   <term><parameter>ctx</parameter></term>
39161   <listitem>
39162    <para>
39163     Context to employ for this submission.
39164    </para>
39165   </listitem>
39166  </varlistentry>
39167  <varlistentry>
39168   <term><parameter>args</parameter></term>
39169   <listitem>
39170    <para>
39171     execbuffer call arguments.
39172    </para>
39173   </listitem>
39174  </varlistentry>
39175  <varlistentry>
39176   <term><parameter>vmas</parameter></term>
39177   <listitem>
39178    <para>
39179     list of vmas.
39180    </para>
39181   </listitem>
39182  </varlistentry>
39183  <varlistentry>
39184   <term><parameter>batch_obj</parameter></term>
39185   <listitem>
39186    <para>
39187     the batchbuffer to submit.
39188    </para>
39189   </listitem>
39190  </varlistentry>
39191  <varlistentry>
39192   <term><parameter>exec_start</parameter></term>
39193   <listitem>
39194    <para>
39195     batchbuffer start virtual address pointer.
39196    </para>
39197   </listitem>
39198  </varlistentry>
39199  <varlistentry>
39200   <term><parameter>dispatch_flags</parameter></term>
39201   <listitem>
39202    <para>
39203     translated execbuffer call flags.
39204    </para>
39205   </listitem>
39206  </varlistentry>
39207 </variablelist>
39208</refsect1>
39209<refsect1>
39210<title>Description</title>
39211<para>
39212   This is the evil twin version of i915_gem_ringbuffer_submission. It abstracts
39213   away the submission details of the execbuffer ioctl call.
39214</para>
39215</refsect1>
39216<refsect1>
39217<title>Return</title>
39218<para>
39219   non-zero if the submission fails.
39220</para>
39221</refsect1>
39222</refentry>
39223
39224<refentry id="API-intel-logical-ring-begin">
39225<refentryinfo>
39226 <title>LINUX</title>
39227 <productname>Kernel Hackers Manual</productname>
39228 <date>July 2017</date>
39229</refentryinfo>
39230<refmeta>
39231 <refentrytitle><phrase>intel_logical_ring_begin</phrase></refentrytitle>
39232 <manvolnum>9</manvolnum>
39233 <refmiscinfo class="version">4.1.27</refmiscinfo>
39234</refmeta>
39235<refnamediv>
39236 <refname>intel_logical_ring_begin</refname>
39237 <refpurpose>
39238     prepare the logical ringbuffer to accept some commands
39239 </refpurpose>
39240</refnamediv>
39241<refsynopsisdiv>
39242 <title>Synopsis</title>
39243  <funcsynopsis><funcprototype>
39244   <funcdef>int <function>intel_logical_ring_begin </function></funcdef>
39245   <paramdef>struct intel_ringbuffer * <parameter>ringbuf</parameter></paramdef>
39246   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
39247   <paramdef>int <parameter>num_dwords</parameter></paramdef>
39248  </funcprototype></funcsynopsis>
39249</refsynopsisdiv>
39250<refsect1>
39251 <title>Arguments</title>
39252 <variablelist>
39253  <varlistentry>
39254   <term><parameter>ringbuf</parameter></term>
39255   <listitem>
39256    <para>
39257     Logical ringbuffer.
39258    </para>
39259   </listitem>
39260  </varlistentry>
39261  <varlistentry>
39262   <term><parameter>ctx</parameter></term>
39263   <listitem>
39264    <para>
39265     -- undescribed --
39266    </para>
39267   </listitem>
39268  </varlistentry>
39269  <varlistentry>
39270   <term><parameter>num_dwords</parameter></term>
39271   <listitem>
39272    <para>
39273     number of DWORDs that we plan to write to the ringbuffer.
39274    </para>
39275   </listitem>
39276  </varlistentry>
39277 </variablelist>
39278</refsect1>
39279<refsect1>
39280<title>Description</title>
39281<para>
39282   The ringbuffer might not be ready to accept the commands right away (maybe it needs to
39283   be wrapped, or wait a bit for the tail to be updated). This function takes care of that
39284   and also preallocates a request (every workload submission is still mediated through
39285   requests, same as it did with legacy ringbuffer submission).
39286</para>
39287</refsect1>
39288<refsect1>
39289<title>Return</title>
39290<para>
39291   non-zero if the ringbuffer is not ready to be written to.
39292</para>
39293</refsect1>
39294</refentry>
39295
39296<refentry id="API-intel-logical-ring-cleanup">
39297<refentryinfo>
39298 <title>LINUX</title>
39299 <productname>Kernel Hackers Manual</productname>
39300 <date>July 2017</date>
39301</refentryinfo>
39302<refmeta>
39303 <refentrytitle><phrase>intel_logical_ring_cleanup</phrase></refentrytitle>
39304 <manvolnum>9</manvolnum>
39305 <refmiscinfo class="version">4.1.27</refmiscinfo>
39306</refmeta>
39307<refnamediv>
39308 <refname>intel_logical_ring_cleanup</refname>
39309 <refpurpose>
39310     deallocate the Engine Command Streamer
39311 </refpurpose>
39312</refnamediv>
39313<refsynopsisdiv>
39314 <title>Synopsis</title>
39315  <funcsynopsis><funcprototype>
39316   <funcdef>void <function>intel_logical_ring_cleanup </function></funcdef>
39317   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
39318  </funcprototype></funcsynopsis>
39319</refsynopsisdiv>
39320<refsect1>
39321 <title>Arguments</title>
39322 <variablelist>
39323  <varlistentry>
39324   <term><parameter>ring</parameter></term>
39325   <listitem>
39326    <para>
39327     Engine Command Streamer.
39328    </para>
39329   </listitem>
39330  </varlistentry>
39331 </variablelist>
39332</refsect1>
39333</refentry>
39334
39335<refentry id="API-intel-logical-rings-init">
39336<refentryinfo>
39337 <title>LINUX</title>
39338 <productname>Kernel Hackers Manual</productname>
39339 <date>July 2017</date>
39340</refentryinfo>
39341<refmeta>
39342 <refentrytitle><phrase>intel_logical_rings_init</phrase></refentrytitle>
39343 <manvolnum>9</manvolnum>
39344 <refmiscinfo class="version">4.1.27</refmiscinfo>
39345</refmeta>
39346<refnamediv>
39347 <refname>intel_logical_rings_init</refname>
39348 <refpurpose>
39349     allocate, populate and init the Engine Command Streamers
39350 </refpurpose>
39351</refnamediv>
39352<refsynopsisdiv>
39353 <title>Synopsis</title>
39354  <funcsynopsis><funcprototype>
39355   <funcdef>int <function>intel_logical_rings_init </function></funcdef>
39356   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
39357  </funcprototype></funcsynopsis>
39358</refsynopsisdiv>
39359<refsect1>
39360 <title>Arguments</title>
39361 <variablelist>
39362  <varlistentry>
39363   <term><parameter>dev</parameter></term>
39364   <listitem>
39365    <para>
39366     DRM device.
39367    </para>
39368   </listitem>
39369  </varlistentry>
39370 </variablelist>
39371</refsect1>
39372<refsect1>
39373<title>Description</title>
39374<para>
39375   This function inits the engines for an Execlists submission style (the equivalent in the
39376   legacy ringbuffer submission world would be i915_gem_init_rings). It does it only for
39377   those engines that are present in the hardware.
39378</para>
39379</refsect1>
39380<refsect1>
39381<title>Return</title>
39382<para>
39383   non-zero if the initialization failed.
39384</para>
39385</refsect1>
39386</refentry>
39387
39388<refentry id="API-intel-lr-context-free">
39389<refentryinfo>
39390 <title>LINUX</title>
39391 <productname>Kernel Hackers Manual</productname>
39392 <date>July 2017</date>
39393</refentryinfo>
39394<refmeta>
39395 <refentrytitle><phrase>intel_lr_context_free</phrase></refentrytitle>
39396 <manvolnum>9</manvolnum>
39397 <refmiscinfo class="version">4.1.27</refmiscinfo>
39398</refmeta>
39399<refnamediv>
39400 <refname>intel_lr_context_free</refname>
39401 <refpurpose>
39402     free the LRC specific bits of a context
39403 </refpurpose>
39404</refnamediv>
39405<refsynopsisdiv>
39406 <title>Synopsis</title>
39407  <funcsynopsis><funcprototype>
39408   <funcdef>void <function>intel_lr_context_free </function></funcdef>
39409   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
39410  </funcprototype></funcsynopsis>
39411</refsynopsisdiv>
39412<refsect1>
39413 <title>Arguments</title>
39414 <variablelist>
39415  <varlistentry>
39416   <term><parameter>ctx</parameter></term>
39417   <listitem>
39418    <para>
39419     the LR context to free.
39420    </para>
39421   </listitem>
39422  </varlistentry>
39423 </variablelist>
39424</refsect1>
39425<refsect1>
39426<title>The real context freeing is done in i915_gem_context_free</title>
39427<para>
39428   this only
39429</para>
39430</refsect1>
39431<refsect1>
39432<title>takes care of the bits that are LRC related</title>
39433<para>
39434   the per-engine backing
39435   objects and the logical ringbuffer.
39436</para>
39437</refsect1>
39438</refentry>
39439
39440<refentry id="API-intel-lr-context-deferred-create">
39441<refentryinfo>
39442 <title>LINUX</title>
39443 <productname>Kernel Hackers Manual</productname>
39444 <date>July 2017</date>
39445</refentryinfo>
39446<refmeta>
39447 <refentrytitle><phrase>intel_lr_context_deferred_create</phrase></refentrytitle>
39448 <manvolnum>9</manvolnum>
39449 <refmiscinfo class="version">4.1.27</refmiscinfo>
39450</refmeta>
39451<refnamediv>
39452 <refname>intel_lr_context_deferred_create</refname>
39453 <refpurpose>
39454     create the LRC specific bits of a context
39455 </refpurpose>
39456</refnamediv>
39457<refsynopsisdiv>
39458 <title>Synopsis</title>
39459  <funcsynopsis><funcprototype>
39460   <funcdef>int <function>intel_lr_context_deferred_create </function></funcdef>
39461   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
39462   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
39463  </funcprototype></funcsynopsis>
39464</refsynopsisdiv>
39465<refsect1>
39466 <title>Arguments</title>
39467 <variablelist>
39468  <varlistentry>
39469   <term><parameter>ctx</parameter></term>
39470   <listitem>
39471    <para>
39472     LR context to create.
39473    </para>
39474   </listitem>
39475  </varlistentry>
39476  <varlistentry>
39477   <term><parameter>ring</parameter></term>
39478   <listitem>
39479    <para>
39480     engine to be used with the context.
39481    </para>
39482   </listitem>
39483  </varlistentry>
39484 </variablelist>
39485</refsect1>
39486<refsect1>
39487<title>Description</title>
39488<para>
39489   This function can be called more than once, with different engines, if we plan
39490   to use the context with them. The context backing objects and the ringbuffers
39491   (specially the ringbuffer backing objects) suck a lot of memory up, and that's why
39492</para>
39493</refsect1>
39494<refsect1>
39495<title>the creation is a deferred call</title>
39496<para>
39497   it's better to make sure first that we need to use
39498   a given ring with the context.
39499</para>
39500</refsect1>
39501<refsect1>
39502<title>Return</title>
39503<para>
39504   non-zero on error.
39505</para>
39506</refsect1>
39507</refentry>
39508
39509      </sect2>
39510      <sect2>
39511        <title>Global GTT views</title>
39512<para>
39513   </para><para>
39514   Background and previous state
39515   </para><para>
39516   Historically objects could exists (be bound) in global GTT space only as
39517   singular instances with a view representing all of the object's backing pages
39518   in a linear fashion. This view will be called a normal view.
39519   </para><para>
39520   To support multiple views of the same object, where the number of mapped
39521   pages is not equal to the backing store, or where the layout of the pages
39522   is not linear, concept of a GGTT view was added.
39523   </para><para>
39524   One example of an alternative view is a stereo display driven by a single
39525   image. In this case we would have a framebuffer looking like this
39526   (2x2 pages):
39527   </para><para>
39528   12
39529   34
39530   </para><para>
39531   Above would represent a normal GGTT view as normally mapped for GPU or CPU
39532   rendering. In contrast, fed to the display engine would be an alternative
39533   view which could look something like this:
39534   </para><para>
39535   1212
39536   3434
39537   </para><para>
39538   In this example both the size and layout of pages in the alternative view is
39539   different from the normal view.
39540   </para><para>
39541   Implementation and usage
39542   </para><para>
39543   GGTT views are implemented using VMAs and are distinguished via enum
39544   i915_ggtt_view_type and struct i915_ggtt_view.
39545   </para><para>
39546   A new flavour of core GEM functions which work with GGTT bound objects were
39547   added with the _ggtt_ infix, and sometimes with _view postfix to avoid
39548   renaming  in large amounts of code. They take the struct i915_ggtt_view
39549   parameter encapsulating all metadata required to implement a view.
39550   </para><para>
39551   As a helper for callers which are only interested in the normal view,
39552   globally const i915_ggtt_view_normal singleton instance exists. All old core
39553   GEM API functions, the ones not taking the view parameter, are operating on,
39554   or with the normal GGTT view.
39555   </para><para>
39556   Code wanting to add or use a new GGTT view needs to:
39557   </para><para>
39558   1. Add a new enum with a suitable name.
39559   2. Extend the metadata in the i915_ggtt_view structure if required.
39560   3. Add support to <function>i915_get_vma_pages</function>.
39561   </para><para>
39562   New views are required to build a scatter-gather table from within the
39563   i915_get_vma_pages function. This table is stored in the vma.ggtt_view and
39564   exists for the lifetime of an VMA.
39565   </para><para>
39566   Core API is designed to have copy semantics which means that passed in
39567   struct i915_ggtt_view does not need to be persistent (left around after
39568   calling the core API functions).
39569   </para><para>
39570</para>
39571
39572<!-- drivers/gpu/drm/i915/i915_gem_gtt.c -->
39573<refentry id="API-i915-dma-map-single">
39574<refentryinfo>
39575 <title>LINUX</title>
39576 <productname>Kernel Hackers Manual</productname>
39577 <date>July 2017</date>
39578</refentryinfo>
39579<refmeta>
39580 <refentrytitle><phrase>i915_dma_map_single</phrase></refentrytitle>
39581 <manvolnum>9</manvolnum>
39582 <refmiscinfo class="version">4.1.27</refmiscinfo>
39583</refmeta>
39584<refnamediv>
39585 <refname>i915_dma_map_single</refname>
39586 <refpurpose>
39587  Create a dma mapping for a page table/dir/etc.
39588 </refpurpose>
39589</refnamediv>
39590<refsynopsisdiv>
39591 <title>Synopsis</title>
39592  <funcsynopsis><funcprototype>
39593   <funcdef> <function>i915_dma_map_single </function></funcdef>
39594   <paramdef> <parameter>px</parameter></paramdef>
39595   <paramdef> <parameter>dev</parameter></paramdef>
39596  </funcprototype></funcsynopsis>
39597</refsynopsisdiv>
39598<refsect1>
39599 <title>Arguments</title>
39600 <variablelist>
39601  <varlistentry>
39602   <term><parameter>px</parameter></term>
39603   <listitem>
39604    <para>
39605     Page table/dir/etc to get a DMA map for
39606    </para>
39607   </listitem>
39608  </varlistentry>
39609  <varlistentry>
39610   <term><parameter>dev</parameter></term>
39611   <listitem>
39612    <para>
39613     drm device
39614    </para>
39615   </listitem>
39616  </varlistentry>
39617 </variablelist>
39618</refsect1>
39619<refsect1>
39620<title>Description</title>
39621<para>
39622   Page table allocations are unified across all gens. They always require a
39623   single 4k allocation, as well as a DMA mapping. If we keep the structs
39624   symmetric here, the simple macro covers us for every page table type.
39625</para>
39626</refsect1>
39627<refsect1>
39628<title>Return</title>
39629<para>
39630   0 if success.
39631</para>
39632</refsect1>
39633</refentry>
39634
39635<refentry id="API-alloc-pt-range">
39636<refentryinfo>
39637 <title>LINUX</title>
39638 <productname>Kernel Hackers Manual</productname>
39639 <date>July 2017</date>
39640</refentryinfo>
39641<refmeta>
39642 <refentrytitle><phrase>alloc_pt_range</phrase></refentrytitle>
39643 <manvolnum>9</manvolnum>
39644 <refmiscinfo class="version">4.1.27</refmiscinfo>
39645</refmeta>
39646<refnamediv>
39647 <refname>alloc_pt_range</refname>
39648 <refpurpose>
39649     Allocate a multiple page tables
39650 </refpurpose>
39651</refnamediv>
39652<refsynopsisdiv>
39653 <title>Synopsis</title>
39654  <funcsynopsis><funcprototype>
39655   <funcdef>int <function>alloc_pt_range </function></funcdef>
39656   <paramdef>struct i915_page_directory_entry * <parameter>pd</parameter></paramdef>
39657   <paramdef>uint16_t <parameter>pde</parameter></paramdef>
39658   <paramdef>size_t <parameter>count</parameter></paramdef>
39659   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
39660  </funcprototype></funcsynopsis>
39661</refsynopsisdiv>
39662<refsect1>
39663 <title>Arguments</title>
39664 <variablelist>
39665  <varlistentry>
39666   <term><parameter>pd</parameter></term>
39667   <listitem>
39668    <para>
39669     The page directory which will have at least <parameter>count</parameter> entries
39670     available to point to the allocated page tables.
39671    </para>
39672   </listitem>
39673  </varlistentry>
39674  <varlistentry>
39675   <term><parameter>pde</parameter></term>
39676   <listitem>
39677    <para>
39678     First page directory entry for which we are allocating.
39679    </para>
39680   </listitem>
39681  </varlistentry>
39682  <varlistentry>
39683   <term><parameter>count</parameter></term>
39684   <listitem>
39685    <para>
39686     Number of pages to allocate.
39687    </para>
39688   </listitem>
39689  </varlistentry>
39690  <varlistentry>
39691   <term><parameter>dev</parameter></term>
39692   <listitem>
39693    <para>
39694     DRM device.
39695    </para>
39696   </listitem>
39697  </varlistentry>
39698 </variablelist>
39699</refsect1>
39700<refsect1>
39701<title>Description</title>
39702<para>
39703   Allocates multiple page table pages and sets the appropriate entries in the
39704   page table structure within the page directory. Function cleans up after
39705   itself on any failures.
39706</para>
39707</refsect1>
39708<refsect1>
39709<title>Return</title>
39710<para>
39711   0 if allocation succeeded.
39712</para>
39713</refsect1>
39714</refentry>
39715
39716<refentry id="API-i915-vma-bind">
39717<refentryinfo>
39718 <title>LINUX</title>
39719 <productname>Kernel Hackers Manual</productname>
39720 <date>July 2017</date>
39721</refentryinfo>
39722<refmeta>
39723 <refentrytitle><phrase>i915_vma_bind</phrase></refentrytitle>
39724 <manvolnum>9</manvolnum>
39725 <refmiscinfo class="version">4.1.27</refmiscinfo>
39726</refmeta>
39727<refnamediv>
39728 <refname>i915_vma_bind</refname>
39729 <refpurpose>
39730     Sets up PTEs for an VMA in it's corresponding address space.
39731 </refpurpose>
39732</refnamediv>
39733<refsynopsisdiv>
39734 <title>Synopsis</title>
39735  <funcsynopsis><funcprototype>
39736   <funcdef>int <function>i915_vma_bind </function></funcdef>
39737   <paramdef>struct i915_vma * <parameter>vma</parameter></paramdef>
39738   <paramdef>enum i915_cache_level <parameter>cache_level</parameter></paramdef>
39739   <paramdef>u32 <parameter>flags</parameter></paramdef>
39740  </funcprototype></funcsynopsis>
39741</refsynopsisdiv>
39742<refsect1>
39743 <title>Arguments</title>
39744 <variablelist>
39745  <varlistentry>
39746   <term><parameter>vma</parameter></term>
39747   <listitem>
39748    <para>
39749     VMA to map
39750    </para>
39751   </listitem>
39752  </varlistentry>
39753  <varlistentry>
39754   <term><parameter>cache_level</parameter></term>
39755   <listitem>
39756    <para>
39757     mapping cache level
39758    </para>
39759   </listitem>
39760  </varlistentry>
39761  <varlistentry>
39762   <term><parameter>flags</parameter></term>
39763   <listitem>
39764    <para>
39765     flags like global or local mapping
39766    </para>
39767   </listitem>
39768  </varlistentry>
39769 </variablelist>
39770</refsect1>
39771<refsect1>
39772<title>Description</title>
39773<para>
39774   DMA addresses are taken from the scatter-gather table of this object (or of
39775   this VMA in case of non-default GGTT views) and PTE entries set up.
39776   Note that DMA addresses are also the only part of the SG table we care about.
39777</para>
39778</refsect1>
39779</refentry>
39780
39781      </sect2>
39782      <sect2>
39783        <title>Buffer Object Eviction</title>
39784	<para>
39785	  This section documents the interface functions for evicting buffer
39786	  objects to make space available in the virtual gpu address spaces.
39787	  Note that this is mostly orthogonal to shrinking buffer objects
39788	  caches, which has the goal to make main memory (shared with the gpu
39789	  through the unified memory architecture) available.
39790	</para>
39791<!-- drivers/gpu/drm/i915/i915_gem_evict.c -->
39792<refentry id="API-i915-gem-evict-something">
39793<refentryinfo>
39794 <title>LINUX</title>
39795 <productname>Kernel Hackers Manual</productname>
39796 <date>July 2017</date>
39797</refentryinfo>
39798<refmeta>
39799 <refentrytitle><phrase>i915_gem_evict_something</phrase></refentrytitle>
39800 <manvolnum>9</manvolnum>
39801 <refmiscinfo class="version">4.1.27</refmiscinfo>
39802</refmeta>
39803<refnamediv>
39804 <refname>i915_gem_evict_something</refname>
39805 <refpurpose>
39806  Evict vmas to make room for binding a new one
39807 </refpurpose>
39808</refnamediv>
39809<refsynopsisdiv>
39810 <title>Synopsis</title>
39811  <funcsynopsis><funcprototype>
39812   <funcdef>int <function>i915_gem_evict_something </function></funcdef>
39813   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
39814   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
39815   <paramdef>int <parameter>min_size</parameter></paramdef>
39816   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
39817   <paramdef>unsigned <parameter>cache_level</parameter></paramdef>
39818   <paramdef>unsigned long <parameter>start</parameter></paramdef>
39819   <paramdef>unsigned long <parameter>end</parameter></paramdef>
39820   <paramdef>unsigned <parameter>flags</parameter></paramdef>
39821  </funcprototype></funcsynopsis>
39822</refsynopsisdiv>
39823<refsect1>
39824 <title>Arguments</title>
39825 <variablelist>
39826  <varlistentry>
39827   <term><parameter>dev</parameter></term>
39828   <listitem>
39829    <para>
39830     drm_device
39831    </para>
39832   </listitem>
39833  </varlistentry>
39834  <varlistentry>
39835   <term><parameter>vm</parameter></term>
39836   <listitem>
39837    <para>
39838     address space to evict from
39839    </para>
39840   </listitem>
39841  </varlistentry>
39842  <varlistentry>
39843   <term><parameter>min_size</parameter></term>
39844   <listitem>
39845    <para>
39846     size of the desired free space
39847    </para>
39848   </listitem>
39849  </varlistentry>
39850  <varlistentry>
39851   <term><parameter>alignment</parameter></term>
39852   <listitem>
39853    <para>
39854     alignment constraint of the desired free space
39855    </para>
39856   </listitem>
39857  </varlistentry>
39858  <varlistentry>
39859   <term><parameter>cache_level</parameter></term>
39860   <listitem>
39861    <para>
39862     cache_level for the desired space
39863    </para>
39864   </listitem>
39865  </varlistentry>
39866  <varlistentry>
39867   <term><parameter>start</parameter></term>
39868   <listitem>
39869    <para>
39870     start (inclusive) of the range from which to evict objects
39871    </para>
39872   </listitem>
39873  </varlistentry>
39874  <varlistentry>
39875   <term><parameter>end</parameter></term>
39876   <listitem>
39877    <para>
39878     end (exclusive) of the range from which to evict objects
39879    </para>
39880   </listitem>
39881  </varlistentry>
39882  <varlistentry>
39883   <term><parameter>flags</parameter></term>
39884   <listitem>
39885    <para>
39886     additional flags to control the eviction algorithm
39887    </para>
39888   </listitem>
39889  </varlistentry>
39890 </variablelist>
39891</refsect1>
39892<refsect1>
39893<title>Description</title>
39894<para>
39895   This function will try to evict vmas until a free space satisfying the
39896   requirements is found. Callers must check first whether any such hole exists
39897   already before calling this function.
39898   </para><para>
39899
39900   This function is used by the object/vma binding code.
39901   </para><para>
39902
39903   Since this function is only used to free up virtual address space it only
39904   ignores pinned vmas, and not object where the backing storage itself is
39905   pinned. Hence obj-&gt;pages_pin_count does not protect against eviction.
39906</para>
39907</refsect1>
39908<refsect1>
39909<title>To clarify</title>
39910<para>
39911   This is for freeing up virtual address space, not for freeing
39912   memory in e.g. the shrinker.
39913</para>
39914</refsect1>
39915</refentry>
39916
39917<refentry id="API-i915-gem-evict-vm">
39918<refentryinfo>
39919 <title>LINUX</title>
39920 <productname>Kernel Hackers Manual</productname>
39921 <date>July 2017</date>
39922</refentryinfo>
39923<refmeta>
39924 <refentrytitle><phrase>i915_gem_evict_vm</phrase></refentrytitle>
39925 <manvolnum>9</manvolnum>
39926 <refmiscinfo class="version">4.1.27</refmiscinfo>
39927</refmeta>
39928<refnamediv>
39929 <refname>i915_gem_evict_vm</refname>
39930 <refpurpose>
39931     Evict all idle vmas from a vm
39932 </refpurpose>
39933</refnamediv>
39934<refsynopsisdiv>
39935 <title>Synopsis</title>
39936  <funcsynopsis><funcprototype>
39937   <funcdef>int <function>i915_gem_evict_vm </function></funcdef>
39938   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
39939   <paramdef>bool <parameter>do_idle</parameter></paramdef>
39940  </funcprototype></funcsynopsis>
39941</refsynopsisdiv>
39942<refsect1>
39943 <title>Arguments</title>
39944 <variablelist>
39945  <varlistentry>
39946   <term><parameter>vm</parameter></term>
39947   <listitem>
39948    <para>
39949     Address space to cleanse
39950    </para>
39951   </listitem>
39952  </varlistentry>
39953  <varlistentry>
39954   <term><parameter>do_idle</parameter></term>
39955   <listitem>
39956    <para>
39957     Boolean directing whether to idle first.
39958    </para>
39959   </listitem>
39960  </varlistentry>
39961 </variablelist>
39962</refsect1>
39963<refsect1>
39964<title>Description</title>
39965<para>
39966   This function evicts all idles vmas from a vm. If all unpinned vmas should be
39967   evicted the <parameter>do_idle</parameter> needs to be set to true.
39968   </para><para>
39969
39970   This is used by the execbuf code as a last-ditch effort to defragment the
39971   address space.
39972</para>
39973</refsect1>
39974<refsect1>
39975<title>To clarify</title>
39976<para>
39977   This is for freeing up virtual address space, not for freeing
39978   memory in e.g. the shrinker.
39979</para>
39980</refsect1>
39981</refentry>
39982
39983<refentry id="API-i915-gem-evict-everything">
39984<refentryinfo>
39985 <title>LINUX</title>
39986 <productname>Kernel Hackers Manual</productname>
39987 <date>July 2017</date>
39988</refentryinfo>
39989<refmeta>
39990 <refentrytitle><phrase>i915_gem_evict_everything</phrase></refentrytitle>
39991 <manvolnum>9</manvolnum>
39992 <refmiscinfo class="version">4.1.27</refmiscinfo>
39993</refmeta>
39994<refnamediv>
39995 <refname>i915_gem_evict_everything</refname>
39996 <refpurpose>
39997     Try to evict all objects
39998 </refpurpose>
39999</refnamediv>
40000<refsynopsisdiv>
40001 <title>Synopsis</title>
40002  <funcsynopsis><funcprototype>
40003   <funcdef>int <function>i915_gem_evict_everything </function></funcdef>
40004   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
40005  </funcprototype></funcsynopsis>
40006</refsynopsisdiv>
40007<refsect1>
40008 <title>Arguments</title>
40009 <variablelist>
40010  <varlistentry>
40011   <term><parameter>dev</parameter></term>
40012   <listitem>
40013    <para>
40014     Device to evict objects for
40015    </para>
40016   </listitem>
40017  </varlistentry>
40018 </variablelist>
40019</refsect1>
40020<refsect1>
40021<title>Description</title>
40022<para>
40023   This functions tries to evict all gem objects from all address spaces. Used
40024   by the shrinker as a last-ditch effort and for suspend, before releasing the
40025   backing storage of all unbound objects.
40026</para>
40027</refsect1>
40028</refentry>
40029
40030      </sect2>
40031      <sect2>
40032        <title>Buffer Object Memory Shrinking</title>
40033	<para>
40034	  This section documents the interface function for shrinking memory
40035	  usage of buffer object caches. Shrinking is used to make main memory
40036	  available.  Note that this is mostly orthogonal to evicting buffer
40037	  objects, which has the goal to make space in gpu virtual address
40038	  spaces.
40039	</para>
40040<!-- drivers/gpu/drm/i915/i915_gem_shrinker.c -->
40041<refentry id="API-i915-gem-shrink">
40042<refentryinfo>
40043 <title>LINUX</title>
40044 <productname>Kernel Hackers Manual</productname>
40045 <date>July 2017</date>
40046</refentryinfo>
40047<refmeta>
40048 <refentrytitle><phrase>i915_gem_shrink</phrase></refentrytitle>
40049 <manvolnum>9</manvolnum>
40050 <refmiscinfo class="version">4.1.27</refmiscinfo>
40051</refmeta>
40052<refnamediv>
40053 <refname>i915_gem_shrink</refname>
40054 <refpurpose>
40055  Shrink buffer object caches
40056 </refpurpose>
40057</refnamediv>
40058<refsynopsisdiv>
40059 <title>Synopsis</title>
40060  <funcsynopsis><funcprototype>
40061   <funcdef>unsigned long <function>i915_gem_shrink </function></funcdef>
40062   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
40063   <paramdef>long <parameter>target</parameter></paramdef>
40064   <paramdef>unsigned <parameter>flags</parameter></paramdef>
40065  </funcprototype></funcsynopsis>
40066</refsynopsisdiv>
40067<refsect1>
40068 <title>Arguments</title>
40069 <variablelist>
40070  <varlistentry>
40071   <term><parameter>dev_priv</parameter></term>
40072   <listitem>
40073    <para>
40074     i915 device
40075    </para>
40076   </listitem>
40077  </varlistentry>
40078  <varlistentry>
40079   <term><parameter>target</parameter></term>
40080   <listitem>
40081    <para>
40082     amount of memory to make available, in pages
40083    </para>
40084   </listitem>
40085  </varlistentry>
40086  <varlistentry>
40087   <term><parameter>flags</parameter></term>
40088   <listitem>
40089    <para>
40090     control flags for selecting cache types
40091    </para>
40092   </listitem>
40093  </varlistentry>
40094 </variablelist>
40095</refsect1>
40096<refsect1>
40097<title>Description</title>
40098<para>
40099   This function is the main interface to the shrinker. It will try to release
40100   up to <parameter>target</parameter> pages of main memory backing storage from buffer objects.
40101   Selection of the specific caches can be done with <parameter>flags</parameter>. This is e.g. useful
40102   when purgeable objects should be removed from caches preferentially.
40103   </para><para>
40104
40105   Note that it's not guaranteed that released amount is actually available as
40106   free system memory - the pages might still be in-used to due to other reasons
40107   (like cpu mmaps) or the mm core has reused them before we could grab them.
40108   Therefore code that needs to explicitly shrink buffer objects caches (e.g. to
40109   avoid deadlocks in memory reclaim) must fall back to <function>i915_gem_shrink_all</function>.
40110   </para><para>
40111
40112   Also note that any kind of pinning (both per-vma address space pins and
40113   backing storage pins at the buffer object level) result in the shrinker code
40114   having to skip the object.
40115</para>
40116</refsect1>
40117<refsect1>
40118<title>Returns</title>
40119<para>
40120   The number of pages of backing storage actually released.
40121</para>
40122</refsect1>
40123</refentry>
40124
40125<refentry id="API-i915-gem-shrink-all">
40126<refentryinfo>
40127 <title>LINUX</title>
40128 <productname>Kernel Hackers Manual</productname>
40129 <date>July 2017</date>
40130</refentryinfo>
40131<refmeta>
40132 <refentrytitle><phrase>i915_gem_shrink_all</phrase></refentrytitle>
40133 <manvolnum>9</manvolnum>
40134 <refmiscinfo class="version">4.1.27</refmiscinfo>
40135</refmeta>
40136<refnamediv>
40137 <refname>i915_gem_shrink_all</refname>
40138 <refpurpose>
40139     Shrink buffer object caches completely
40140 </refpurpose>
40141</refnamediv>
40142<refsynopsisdiv>
40143 <title>Synopsis</title>
40144  <funcsynopsis><funcprototype>
40145   <funcdef>unsigned long <function>i915_gem_shrink_all </function></funcdef>
40146   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
40147  </funcprototype></funcsynopsis>
40148</refsynopsisdiv>
40149<refsect1>
40150 <title>Arguments</title>
40151 <variablelist>
40152  <varlistentry>
40153   <term><parameter>dev_priv</parameter></term>
40154   <listitem>
40155    <para>
40156     i915 device
40157    </para>
40158   </listitem>
40159  </varlistentry>
40160 </variablelist>
40161</refsect1>
40162<refsect1>
40163<title>Description</title>
40164<para>
40165   This is a simple wraper around <function>i915_gem_shrink</function> to aggressively shrink all
40166   caches completely. It also first waits for and retires all outstanding
40167   requests to also be able to release backing storage for active objects.
40168   </para><para>
40169
40170   This should only be used in code to intentionally quiescent the gpu or as a
40171   last-ditch effort when memory seems to have run out.
40172</para>
40173</refsect1>
40174<refsect1>
40175<title>Returns</title>
40176<para>
40177   The number of pages of backing storage actually released.
40178</para>
40179</refsect1>
40180</refentry>
40181
40182<refentry id="API-i915-gem-shrinker-init">
40183<refentryinfo>
40184 <title>LINUX</title>
40185 <productname>Kernel Hackers Manual</productname>
40186 <date>July 2017</date>
40187</refentryinfo>
40188<refmeta>
40189 <refentrytitle><phrase>i915_gem_shrinker_init</phrase></refentrytitle>
40190 <manvolnum>9</manvolnum>
40191 <refmiscinfo class="version">4.1.27</refmiscinfo>
40192</refmeta>
40193<refnamediv>
40194 <refname>i915_gem_shrinker_init</refname>
40195 <refpurpose>
40196     Initialize i915 shrinker
40197 </refpurpose>
40198</refnamediv>
40199<refsynopsisdiv>
40200 <title>Synopsis</title>
40201  <funcsynopsis><funcprototype>
40202   <funcdef>void <function>i915_gem_shrinker_init </function></funcdef>
40203   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
40204  </funcprototype></funcsynopsis>
40205</refsynopsisdiv>
40206<refsect1>
40207 <title>Arguments</title>
40208 <variablelist>
40209  <varlistentry>
40210   <term><parameter>dev_priv</parameter></term>
40211   <listitem>
40212    <para>
40213     i915 device
40214    </para>
40215   </listitem>
40216  </varlistentry>
40217 </variablelist>
40218</refsect1>
40219<refsect1>
40220<title>Description</title>
40221<para>
40222   This function registers and sets up the i915 shrinker and OOM handler.
40223</para>
40224</refsect1>
40225</refentry>
40226
40227      </sect2>
40228    </sect1>
40229
40230    <sect1>
40231      <title> Tracing </title>
40232      <para>
40233    This sections covers all things related to the tracepoints implemented in
40234    the i915 driver.
40235      </para>
40236      <sect2>
40237        <title> i915_ppgtt_create and i915_ppgtt_release </title>
40238<para>
40239   </para><para>
40240   With full ppgtt enabled each process using drm will allocate at least one
40241   translation table. With these traces it is possible to keep track of the
40242   allocation and of the lifetime of the tables; this can be used during
40243   testing/debug to verify that we are not leaking ppgtts.
40244   These traces identify the ppgtt through the vm pointer, which is also printed
40245   by the i915_vma_bind and i915_vma_unbind tracepoints.
40246</para>
40247
40248      </sect2>
40249      <sect2>
40250        <title> i915_context_create and i915_context_free </title>
40251<para>
40252   </para><para>
40253   These tracepoints are used to track creation and deletion of contexts.
40254   If full ppgtt is enabled, they also print the address of the vm assigned to
40255   the context.
40256</para>
40257
40258      </sect2>
40259      <sect2>
40260        <title> switch_mm </title>
40261<para>
40262   </para><para>
40263   This tracepoint allows tracking of the mm switch, which is an important point
40264   in the lifetime of the vm in the legacy submission path. This tracepoint is
40265   called only if full ppgtt is enabled.
40266</para>
40267
40268      </sect2>
40269    </sect1>
40270
40271  </chapter>
40272</part>
40273</book>
40274