xref: /linux-4.4.14/Documentation/DocBook/gpu.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>

<book id="gpuDevelopersGuide">
  <bookinfo>
    <title>Linux GPU Driver Developer's Guide</title>

    <authorgroup>
      <author>
	<firstname>Jesse</firstname>
	<surname>Barnes</surname>
	<contrib>Initial version</contrib>
	<affiliation>
	  <orgname>Intel Corporation</orgname>
	  <address>
	    <email>jesse.barnes@intel.com</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Laurent</firstname>
	<surname>Pinchart</surname>
	<contrib>Driver internals</contrib>
	<affiliation>
	  <orgname>Ideas on board SPRL</orgname>
	  <address>
	    <email>laurent.pinchart@ideasonboard.com</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Daniel</firstname>
	<surname>Vetter</surname>
	<contrib>Contributions all over the place</contrib>
	<affiliation>
	  <orgname>Intel Corporation</orgname>
	  <address>
	    <email>daniel.vetter@ffwll.ch</email>
	  </address>
	</affiliation>
      </author>
      <author>
	<firstname>Lukas</firstname>
	<surname>Wunner</surname>
	<contrib>vga_switcheroo documentation</contrib>
	<affiliation>
	  <address>
	    <email>lukas@wunner.de</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2008-2009</year>
      <year>2013-2014</year>
      <holder>Intel Corporation</holder>
    </copyright>
    <copyright>
      <year>2012</year>
      <holder>Laurent Pinchart</holder>
    </copyright>
    <copyright>
      <year>2015</year>
      <holder>Lukas Wunner</holder>
    </copyright>

    <legalnotice>
      <para>
	The contents of this file may be used under the terms of the GNU
	General Public License version 2 (the "GPL") as distributed in
	the kernel source COPYING file.
      </para>
    </legalnotice>

    <revhistory>
      <!-- Put document revisions here, newest first. -->
      <revision>
	<revnumber>1.0</revnumber>
	<date>2012-07-13</date>
	<authorinitials>LP</authorinitials>
	<revremark>Added extensive documentation about driver internals.
	</revremark>
      </revision>
      <revision>
	<revnumber>1.1</revnumber>
	<date>2015-10-11</date>
	<authorinitials>LW</authorinitials>
	<revremark>Added vga_switcheroo documentation.
	</revremark>
      </revision>
    </revhistory>
  </bookinfo>

<toc></toc>

<part id="drmCore">
  <title>DRM Core</title>
  <partintro>
    <para>
      This first part of the GPU Driver Developer's Guide documents core DRM
      code, helper libraries for writing drivers and generic userspace
      interfaces exposed by DRM drivers.
    </para>
  </partintro>

  <chapter id="drmIntroduction">
    <title>Introduction</title>
    <para>
      The Linux DRM layer contains code intended to support the needs
      of complex graphics devices, usually containing programmable
      pipelines well suited to 3D graphics acceleration.  Graphics
      drivers in the kernel may make use of DRM functions to make
      tasks like memory management, interrupt handling and DMA easier,
      and provide a uniform interface to applications.
    </para>
    <para>
      A note on versions: this guide covers features found in the DRM
      tree, including the TTM memory manager, output configuration and
      mode setting, and the new vblank internals, in addition to all
      the regular features found in current kernels.
    </para>
    <para>
      [Insert diagram of typical DRM stack here]
    </para>
  </chapter>

  <!-- Internals -->

  <chapter id="drmInternals">
    <title>DRM Internals</title>
    <para>
      This chapter documents DRM internals relevant to driver authors
      and developers working to add support for the latest features to
      existing drivers.
    </para>
    <para>
      First, we go over some typical driver initialization
      requirements, like setting up command buffers, creating an
      initial output configuration, and initializing core services.
      Subsequent sections cover core internals in more detail,
      providing implementation notes and examples.
    </para>
    <para>
      The DRM layer provides several services to graphics drivers,
      many of them driven by the application interfaces it provides
      through libdrm, the library that wraps most of the DRM ioctls.
      These include vblank event handling, memory
      management, output management, framebuffer management, command
      submission &amp; fencing, suspend/resume support, and DMA
      services.
    </para>

  <!-- Internals: driver init -->

  <sect1>
    <title>Driver Initialization</title>
    <para>
      At the core of every DRM driver is a <structname>drm_driver</structname>
      structure. Drivers typically statically initialize a drm_driver structure,
      and then pass it to <function>drm_dev_alloc()</function> to allocate a
      device instance. After the device instance is fully initialized it can be
      registered (which makes it accessible from userspace) using
      <function>drm_dev_register()</function>.
    </para>
    <para>
      The <structname>drm_driver</structname> structure contains static
      information that describes the driver and features it supports, and
      pointers to methods that the DRM core will call to implement the DRM API.
      We will first go through the <structname>drm_driver</structname> static
      information fields, and will then describe individual operations in
      details as they get used in later sections.
    </para>
    <sect2>
      <title>Driver Information</title>
      <sect3>
        <title>Driver Features</title>
        <para>
          Drivers inform the DRM core about their requirements and supported
          features by setting appropriate flags in the
          <structfield>driver_features</structfield> field. Since those flags
          influence the DRM core behaviour since registration time, most of them
          must be set to registering the <structname>drm_driver</structname>
          instance.
        </para>
        <synopsis>u32 driver_features;</synopsis>
        <variablelist>
          <title>Driver Feature Flags</title>
          <varlistentry>
            <term>DRIVER_USE_AGP</term>
            <listitem><para>
              Driver uses AGP interface, the DRM core will manage AGP resources.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_REQUIRE_AGP</term>
            <listitem><para>
              Driver needs AGP interface to function. AGP initialization failure
              will become a fatal error.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_PCI_DMA</term>
            <listitem><para>
              Driver is capable of PCI DMA, mapping of PCI DMA buffers to
              userspace will be enabled. Deprecated.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_SG</term>
            <listitem><para>
              Driver can perform scatter/gather DMA, allocation and mapping of
              scatter/gather buffers will be enabled. Deprecated.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_HAVE_DMA</term>
            <listitem><para>
              Driver supports DMA, the userspace DMA API will be supported.
              Deprecated.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term>
            <listitem><para>
              DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler
              managed by the DRM Core. The core will support simple IRQ handler
              installation when the flag is set. The installation process is
              described in <xref linkend="drm-irq-registration"/>.</para>
              <para>DRIVER_IRQ_SHARED indicates whether the device &amp; handler
              support shared IRQs (note that this is required of PCI  drivers).
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_GEM</term>
            <listitem><para>
              Driver use the GEM memory manager.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_MODESET</term>
            <listitem><para>
              Driver supports mode setting interfaces (KMS).
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_PRIME</term>
            <listitem><para>
              Driver implements DRM PRIME buffer sharing.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_RENDER</term>
            <listitem><para>
              Driver supports dedicated render nodes.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>DRIVER_ATOMIC</term>
            <listitem><para>
              Driver supports atomic properties.  In this case the driver
              must implement appropriate obj->atomic_get_property() vfuncs
              for any modeset objects with driver specific properties.
            </para></listitem>
          </varlistentry>
        </variablelist>
      </sect3>
      <sect3>
        <title>Major, Minor and Patchlevel</title>
        <synopsis>int major;
int minor;
int patchlevel;</synopsis>
        <para>
          The DRM core identifies driver versions by a major, minor and patch
          level triplet. The information is printed to the kernel log at
          initialization time and passed to userspace through the
          DRM_IOCTL_VERSION ioctl.
        </para>
        <para>
          The major and minor numbers are also used to verify the requested driver
          API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes
          between minor versions, applications can call DRM_IOCTL_SET_VERSION to
          select a specific version of the API. If the requested major isn't equal
          to the driver major, or the requested minor is larger than the driver
          minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise
          the driver's set_version() method will be called with the requested
          version.
        </para>
      </sect3>
      <sect3>
        <title>Name, Description and Date</title>
        <synopsis>char *name;
char *desc;
char *date;</synopsis>
        <para>
          The driver name is printed to the kernel log at initialization time,
          used for IRQ registration and passed to userspace through
          DRM_IOCTL_VERSION.
        </para>
        <para>
          The driver description is a purely informative string passed to
          userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
          the kernel.
        </para>
        <para>
          The driver date, formatted as YYYYMMDD, is meant to identify the date of
          the latest modification to the driver. However, as most drivers fail to
          update it, its value is mostly useless. The DRM core prints it to the
          kernel log at initialization time and passes it to userspace through the
          DRM_IOCTL_VERSION ioctl.
        </para>
      </sect3>
    </sect2>
    <sect2>
      <title>Device Instance and Driver Handling</title>
<para>
   </para><para>
   A device instance for a drm driver is represented by struct <structname>drm_device</structname>. This
   is allocated with <function>drm_dev_alloc</function>, usually from bus-specific -&gt;<function>probe</function>
   callbacks implemented by the driver. The driver then needs to initialize all
   the various subsystems for the drm device like memory management, vblank
   handling, modesetting support and intial output configuration plus obviously
   initialize all the corresponding hardware bits. An important part of this is
   also calling <function>drm_dev_set_unique</function> to set the userspace-visible unique name of
   this device instance. Finally when everything is up and running and ready for
   userspace the device instance can be published using <function>drm_dev_register</function>.
   </para><para>
   There is also deprecated support for initalizing device instances using
   bus-specific helpers and the -&gt;<function>load</function> callback. But due to
   backwards-compatibility needs the device instance have to be published too
   early, which requires unpretty global locking to make safe and is therefore
   only support for existing drivers not yet converted to the new scheme.
   </para><para>
   When cleaning up a device instance everything needs to be done in reverse:
   First unpublish the device instance with <function>drm_dev_unregister</function>. Then clean up
   any other resources allocated at device initialization and drop the driver's
   reference to <structname>drm_device</structname> using <function>drm_dev_unref</function>.
   </para><para>
   Note that the lifetime rules for <structname>drm_device</structname> instance has still a lot of
   historical baggage. Hence use the reference counting provided by
   <function>drm_dev_ref</function> and <function>drm_dev_unref</function> only carefully.
   </para><para>
   Also note that embedding of <structname>drm_device</structname> is currently not (yet) supported (but
   it would be easy to add). Drivers can store driver-private data in the
   dev_priv field of <structname>drm_device</structname>.
</para>

<!-- drivers/gpu/drm/drm_drv.c -->
<refentry id="API-drm-put-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_put_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_put_dev</refname>
 <refpurpose>
  Unregister and release a DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_put_dev </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called at module unload time or when a PCI device is unplugged.
   </para><para>

   Cleans up all DRM device, calling <function>drm_lastclose</function>.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Use of this function is deprecated. It will eventually go away
   completely.  Please use <function>drm_dev_unregister</function> and <function>drm_dev_unref</function> explicitly
   instead to make sure that the device isn't userspace accessible any more
   while teardown is in progress, ensuring that userspace can't access an
   inconsistent state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dev-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dev_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dev_alloc</refname>
 <refpurpose>
     Allocate new DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_device * <function>drm_dev_alloc </function></funcdef>
   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
   <paramdef>struct device * <parameter>parent</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     DRM driver to allocate device for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>parent</parameter></term>
   <listitem>
    <para>
     Parent device object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate and initialize a new DRM device. No device registration is done.
   Call <function>drm_dev_register</function> to advertice the device to user space and register it
   with other core subsystems. This should be done last in the device
   initialization sequence to make sure userspace can't access an inconsistent
   state.
   </para><para>

   The initial ref-count of the object is 1. Use <function>drm_dev_ref</function> and
   <function>drm_dev_unref</function> to take and drop further ref-counts.
   </para><para>

   Note that for purely virtual devices <parameter>parent</parameter> can be NULL.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Pointer to new DRM device, or NULL if out of memory.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dev-ref">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dev_ref</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dev_ref</refname>
 <refpurpose>
     Take reference of a DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dev_ref </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to take reference of or NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This increases the ref-count of <parameter>dev</parameter> by one. You *must* already own a
   reference when calling this. Use <function>drm_dev_unref</function> to drop this reference
   again.
   </para><para>

   This function never fails. However, this function does not provide *any*
   guarantee whether the device is alive or running. It only provides a
   reference to the object and the memory associated with it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dev-unref">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dev_unref</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dev_unref</refname>
 <refpurpose>
     Drop reference of a DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dev_unref </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to drop reference of or NULL
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This decreases the ref-count of <parameter>dev</parameter> by one. The device is destroyed if the
   ref-count drops to zero.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dev-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dev_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dev_register</refname>
 <refpurpose>
     Register DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dev_register </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned long <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Flags passed to the driver's .<function>load</function> function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register the DRM device <parameter>dev</parameter> with the system, advertise device to user-space
   and start normal device operation. <parameter>dev</parameter> must be allocated via <function>drm_dev_alloc</function>
   previously.
   </para><para>

   Never call this twice on any device!
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   To ensure backward compatibility with existing drivers method this
   function calls the -&gt;<function>load</function> method after registering the device nodes,
   creating race conditions. Usage of the -&gt;<function>load</function> methods is therefore
   deprecated, drivers must perform all initialization before calling
   <function>drm_dev_register</function>.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dev-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dev_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dev_unregister</refname>
 <refpurpose>
     Unregister DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dev_unregister </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     Device to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister the DRM device from the system. This does the reverse of
   <function>drm_dev_register</function> but does not deallocate the device. The caller must call
   <function>drm_dev_unref</function> to drop their final reference.
   </para><para>

   This should be called first in the device teardown code to make sure
   userspace can't access the device instance any more.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dev-set-unique">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dev_set_unique</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dev_set_unique</refname>
 <refpurpose>
     Set the unique name of a DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dev_set_unique </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>const char * <parameter>fmt</parameter></paramdef>
   <paramdef> <parameter>...</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device of which to set the unique name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fmt</parameter></term>
   <listitem>
    <para>
     format string for unique name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>...</parameter></term>
   <listitem>
    <para>
     variable arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the unique name of a DRM device using the specified format string and
   a variable list of arguments. Drivers can use this at driver probe time if
   the unique name of the devices they drive is static.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Driver Load</title>
      <sect3 id="drm-irq-registration">
        <title>IRQ Registration</title>
        <para>
          The DRM core tries to facilitate IRQ handler registration and
          unregistration by providing <function>drm_irq_install</function> and
          <function>drm_irq_uninstall</function> functions. Those functions only
          support a single interrupt per device, devices that use more than one
          IRQs need to be handled manually.
        </para>
        <sect4>
          <title>Managed IRQ Registration</title>
          <para>
            <function>drm_irq_install</function> starts by calling the
            <methodname>irq_preinstall</methodname> driver operation. The operation
            is optional and must make sure that the interrupt will not get fired by
            clearing all pending interrupt flags or disabling the interrupt.
          </para>
          <para>
            The passed-in IRQ will then be requested by a call to
            <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver
            feature flag is set, a shared (IRQF_SHARED) IRQ handler will be
            requested.
          </para>
          <para>
            The IRQ handler function must be provided as the mandatory irq_handler
            driver operation. It will get passed directly to
            <function>request_irq</function> and thus has the same prototype as all
            IRQ handlers. It will get called with a pointer to the DRM device as the
            second argument.
          </para>
          <para>
            Finally the function calls the optional
            <methodname>irq_postinstall</methodname> driver operation. The operation
            usually enables interrupts (excluding the vblank interrupt, which is
            enabled separately), but drivers may choose to enable/disable interrupts
            at a different time.
          </para>
          <para>
            <function>drm_irq_uninstall</function> is similarly used to uninstall an
            IRQ handler. It starts by waking up all processes waiting on a vblank
            interrupt to make sure they don't hang, and then calls the optional
            <methodname>irq_uninstall</methodname> driver operation. The operation
            must disable all hardware interrupts. Finally the function frees the IRQ
            by calling <function>free_irq</function>.
          </para>
        </sect4>
        <sect4>
          <title>Manual IRQ Registration</title>
          <para>
            Drivers that require multiple interrupt handlers can't use the managed
            IRQ registration functions. In that case IRQs must be registered and
            unregistered manually (usually with the <function>request_irq</function>
            and <function>free_irq</function> functions, or their devm_* equivalent).
          </para>
          <para>
            When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ
            driver feature flag, and must not provide the
	    <methodname>irq_handler</methodname> driver operation. They must set the
	    <structname>drm_device</structname> <structfield>irq_enabled</structfield>
	    field to 1 upon registration of the IRQs, and clear it to 0 after
	    unregistering the IRQs.
          </para>
        </sect4>
      </sect3>
      <sect3>
        <title>Memory Manager Initialization</title>
        <para>
          Every DRM driver requires a memory manager which must be initialized at
          load time. DRM currently contains two memory managers, the Translation
          Table Manager (TTM) and the Graphics Execution Manager (GEM).
          This document describes the use of the GEM memory manager only. See
          <xref linkend="drm-memory-management"/> for details.
        </para>
      </sect3>
      <sect3>
        <title>Miscellaneous Device Configuration</title>
        <para>
          Another task that may be necessary for PCI devices during configuration
          is mapping the video BIOS. On many devices, the VBIOS describes device
          configuration, LCD panel timings (if any), and contains flags indicating
          device state. Mapping the BIOS can be done using the pci_map_rom() call,
          a convenience function that takes care of mapping the actual ROM,
          whether it has been shadowed into memory (typically at address 0xc0000)
          or exists on the PCI device in the ROM BAR. Note that after the ROM has
          been mapped and any necessary information has been extracted, it should
          be unmapped; on many devices, the ROM address decoder is shared with
          other BARs, so leaving it mapped could cause undesired behaviour like
          hangs or memory corruption.
  <!--!Fdrivers/pci/rom.c pci_map_rom-->
        </para>
      </sect3>
    </sect2>
    <sect2>
      <title>Bus-specific Device Registration and PCI Support</title>
      <para>
        A number of functions are provided to help with device registration.
	The functions deal with PCI and platform devices respectively and are
	only provided for historical reasons. These are all deprecated and
	shouldn't be used in new drivers. Besides that there's a few
	helpers for pci drivers.
      </para>
<!-- drivers/gpu/drm/drm_pci.c -->
<refentry id="API-drm-pci-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_pci_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_pci_alloc</refname>
 <refpurpose>
  Allocate a PCI consistent memory block, for DMA.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>drm_dma_handle_t * <function>drm_pci_alloc </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
   <paramdef>size_t <parameter>align</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of block to allocate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>align</parameter></term>
   <listitem>
    <para>
     alignment of block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   A handle to the allocated memory block on success or NULL on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-pci-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_pci_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_pci_free</refname>
 <refpurpose>
     Free a PCI consistent memory block
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_pci_free </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>drm_dma_handle_t * <parameter>dmah</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmah</parameter></term>
   <listitem>
    <para>
     handle to memory block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-get-pci-dev">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_get_pci_dev</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_get_pci_dev</refname>
 <refpurpose>
     Register a PCI device with the DRM subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_get_pci_dev </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct pci_device_id * <parameter>ent</parameter></paramdef>
   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     PCI device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ent</parameter></term>
   <listitem>
    <para>
     entry from the PCI ID table that matches <parameter>pdev</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     DRM device driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Attempt to gets inter module <quote>drm</quote> information. If we are first
   then register the character device and inter module information.
   Try and register, if we fail to register, backout previous work.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This function is deprecated, please use <function>drm_dev_alloc</function> and
   <function>drm_dev_register</function> instead and remove your -&gt;<function>load</function> callback.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-pci-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_pci_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_pci_init</refname>
 <refpurpose>
     Register matching PCI devices with the DRM subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_pci_init </function></funcdef>
   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
   <paramdef>struct pci_driver * <parameter>pdriver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     DRM device driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pdriver</parameter></term>
   <listitem>
    <para>
     PCI device driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes a drm_device structures, registering the stubs and initializing
   the AGP device.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This function is deprecated. Modern modesetting drm drivers should use
   <function>pci_register_driver</function> directly, this function only provides shadow-binding
   support for old legacy drivers on top of that core pci function.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-pci-exit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_pci_exit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_pci_exit</refname>
 <refpurpose>
     Unregister matching PCI devices from the DRM subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_pci_exit </function></funcdef>
   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
   <paramdef>struct pci_driver * <parameter>pdriver</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     DRM device driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pdriver</parameter></term>
   <listitem>
    <para>
     PCI device driver
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregisters one or more devices matched by a PCI driver from the DRM
   subsystem.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This function is deprecated. Modern modesetting drm drivers should use
   <function>pci_unregister_driver</function> directly, this function only provides shadow-binding
   support for old legacy drivers on top of that core pci function.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_platform.c -->
<refentry id="API-drm-platform-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_platform_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_platform_init</refname>
 <refpurpose>
  Register a platform device with the DRM subsystem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_platform_init </function></funcdef>
   <paramdef>struct drm_driver * <parameter>driver</parameter></paramdef>
   <paramdef>struct platform_device * <parameter>platform_device</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>driver</parameter></term>
   <listitem>
    <para>
     DRM device driver
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>platform_device</parameter></term>
   <listitem>
    <para>
     platform device to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Registers the specified DRM device driver and platform device with the DRM
   subsystem, initializing a drm_device structure and calling the driver's
   .<function>load</function> function.
</para>
</refsect1>
<refsect1>
<title>NOTE</title>
<para>
   This function is deprecated, please use <function>drm_dev_alloc</function> and
   <function>drm_dev_register</function> instead and remove your -&gt;<function>load</function> callback.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

    </sect2>
  </sect1>

  <!-- Internals: memory management -->

  <sect1 id="drm-memory-management">
    <title>Memory management</title>
    <para>
      Modern Linux systems require large amount of graphics memory to store
      frame buffers, textures, vertices and other graphics-related data. Given
      the very dynamic nature of many of that data, managing graphics memory
      efficiently is thus crucial for the graphics stack and plays a central
      role in the DRM infrastructure.
    </para>
    <para>
      The DRM core includes two memory managers, namely Translation Table Maps
      (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory
      manager to be developed and tried to be a one-size-fits-them all
      solution. It provides a single userspace API to accommodate the need of
      all hardware, supporting both Unified Memory Architecture (UMA) devices
      and devices with dedicated video RAM (i.e. most discrete video cards).
      This resulted in a large, complex piece of code that turned out to be
      hard to use for driver development.
    </para>
    <para>
      GEM started as an Intel-sponsored project in reaction to TTM's
      complexity. Its design philosophy is completely different: instead of
      providing a solution to every graphics memory-related problems, GEM
      identified common code between drivers and created a support library to
      share it. GEM has simpler initialization and execution requirements than
      TTM, but has no video RAM management capabilities and is thus limited to
      UMA devices.
    </para>
    <sect2>
      <title>The Translation Table Manager (TTM)</title>
      <para>
        TTM design background and information belongs here.
      </para>
      <sect3>
        <title>TTM initialization</title>
        <warning><para>This section is outdated.</para></warning>
        <para>
          Drivers wishing to support TTM must fill out a drm_bo_driver
          structure. The structure contains several fields with function
          pointers for initializing the TTM, allocating and freeing memory,
          waiting for command completion and fence synchronization, and memory
          migration. See the radeon_ttm.c file for an example of usage.
        </para>
        <para>
          The ttm_global_reference structure is made up of several fields:
        </para>
        <programlisting>
          struct ttm_global_reference {
                  enum ttm_global_types global_type;
                  size_t size;
                  void *object;
                  int (*init) (struct ttm_global_reference *);
                  void (*release) (struct ttm_global_reference *);
          };
        </programlisting>
        <para>
          There should be one global reference structure for your memory
          manager as a whole, and there will be others for each object
          created by the memory manager at runtime.  Your global TTM should
          have a type of TTM_GLOBAL_TTM_MEM.  The size field for the global
          object should be sizeof(struct ttm_mem_global), and the init and
          release hooks should point at your driver-specific init and
          release routines, which probably eventually call
          ttm_mem_global_init and ttm_mem_global_release, respectively.
        </para>
        <para>
          Once your global TTM accounting structure is set up and initialized
          by calling ttm_global_item_ref() on it,
          you need to create a buffer object TTM to
          provide a pool for buffer object allocation by clients and the
          kernel itself.  The type of this object should be TTM_GLOBAL_TTM_BO,
          and its size should be sizeof(struct ttm_bo_global).  Again,
          driver-specific init and release functions may be provided,
          likely eventually calling ttm_bo_global_init() and
          ttm_bo_global_release(), respectively.  Also, like the previous
          object, ttm_global_item_ref() is used to create an initial reference
          count for the TTM, which will call your initialization function.
        </para>
      </sect3>
    </sect2>
    <sect2 id="drm-gem">
      <title>The Graphics Execution Manager (GEM)</title>
      <para>
        The GEM design approach has resulted in a memory manager that doesn't
        provide full coverage of all (or even all common) use cases in its
        userspace or kernel API. GEM exposes a set of standard memory-related
        operations to userspace and a set of helper functions to drivers, and let
        drivers implement hardware-specific operations with their own private API.
      </para>
      <para>
        The GEM userspace API is described in the
        <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics
        Execution Manager</citetitle></ulink> article on LWN. While slightly
        outdated, the document provides a good overview of the GEM API principles.
        Buffer allocation and read and write operations, described as part of the
        common GEM API, are currently implemented using driver-specific ioctls.
      </para>
      <para>
        GEM is data-agnostic. It manages abstract buffer objects without knowing
        what individual buffers contain. APIs that require knowledge of buffer
        contents or purpose, such as buffer allocation or synchronization
        primitives, are thus outside of the scope of GEM and must be implemented
        using driver-specific ioctls.
      </para>
      <para>
        On a fundamental level, GEM involves several operations:
        <itemizedlist>
          <listitem>Memory allocation and freeing</listitem>
          <listitem>Command execution</listitem>
          <listitem>Aperture management at command execution time</listitem>
        </itemizedlist>
        Buffer object allocation is relatively straightforward and largely
        provided by Linux's shmem layer, which provides memory to back each
        object.
      </para>
      <para>
        Device-specific operations, such as command execution, pinning, buffer
        read &amp; write, mapping, and domain ownership transfers are left to
        driver-specific ioctls.
      </para>
      <sect3>
        <title>GEM Initialization</title>
        <para>
          Drivers that use GEM must set the DRIVER_GEM bit in the struct
          <structname>drm_driver</structname>
          <structfield>driver_features</structfield> field. The DRM core will
          then automatically initialize the GEM core before calling the
          <methodname>load</methodname> operation. Behind the scene, this will
          create a DRM Memory Manager object which provides an address space
          pool for object allocation.
        </para>
        <para>
          In a KMS configuration, drivers need to allocate and initialize a
          command ring buffer following core GEM initialization if required by
          the hardware. UMA devices usually have what is called a "stolen"
          memory region, which provides space for the initial framebuffer and
          large, contiguous memory regions required by the device. This space is
          typically not managed by GEM, and must be initialized separately into
          its own DRM MM object.
        </para>
      </sect3>
      <sect3>
        <title>GEM Objects Creation</title>
        <para>
          GEM splits creation of GEM objects and allocation of the memory that
          backs them in two distinct operations.
        </para>
        <para>
          GEM objects are represented by an instance of struct
          <structname>drm_gem_object</structname>. Drivers usually need to extend
          GEM objects with private information and thus create a driver-specific
          GEM object structure type that embeds an instance of struct
          <structname>drm_gem_object</structname>.
        </para>
        <para>
          To create a GEM object, a driver allocates memory for an instance of its
          specific GEM object type and initializes the embedded struct
          <structname>drm_gem_object</structname> with a call to
          <function>drm_gem_object_init</function>. The function takes a pointer to
          the DRM device, a pointer to the GEM object and the buffer object size
          in bytes.
        </para>
        <para>
          GEM uses shmem to allocate anonymous pageable memory.
          <function>drm_gem_object_init</function> will create an shmfs file of
          the requested size and store it into the struct
          <structname>drm_gem_object</structname> <structfield>filp</structfield>
          field. The memory is used as either main storage for the object when the
          graphics hardware uses system memory directly or as a backing store
          otherwise.
        </para>
        <para>
          Drivers are responsible for the actual physical pages allocation by
          calling <function>shmem_read_mapping_page_gfp</function> for each page.
          Note that they can decide to allocate pages when initializing the GEM
          object, or to delay allocation until the memory is needed (for instance
          when a page fault occurs as a result of a userspace memory access or
          when the driver needs to start a DMA transfer involving the memory).
        </para>
        <para>
          Anonymous pageable memory allocation is not always desired, for instance
          when the hardware requires physically contiguous system memory as is
          often the case in embedded devices. Drivers can create GEM objects with
          no shmfs backing (called private GEM objects) by initializing them with
          a call to <function>drm_gem_private_object_init</function> instead of
          <function>drm_gem_object_init</function>. Storage for private GEM
          objects must be managed by drivers.
        </para>
        <para>
          Drivers that do not need to extend GEM objects with private information
          can call the <function>drm_gem_object_alloc</function> function to
          allocate and initialize a struct <structname>drm_gem_object</structname>
          instance. The GEM core will call the optional driver
          <methodname>gem_init_object</methodname> operation after initializing
          the GEM object with <function>drm_gem_object_init</function>.
          <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis>
        </para>
        <para>
          No alloc-and-init function exists for private GEM objects.
        </para>
      </sect3>
      <sect3>
        <title>GEM Objects Lifetime</title>
        <para>
          All GEM objects are reference-counted by the GEM core. References can be
          acquired and release by <function>calling drm_gem_object_reference</function>
          and <function>drm_gem_object_unreference</function> respectively. The
          caller must hold the <structname>drm_device</structname>
          <structfield>struct_mutex</structfield> lock. As a convenience, GEM
          provides the <function>drm_gem_object_reference_unlocked</function> and
          <function>drm_gem_object_unreference_unlocked</function> functions that
          can be called without holding the lock.
        </para>
        <para>
          When the last reference to a GEM object is released the GEM core calls
          the <structname>drm_driver</structname>
          <methodname>gem_free_object</methodname> operation. That operation is
          mandatory for GEM-enabled drivers and must free the GEM object and all
          associated resources.
        </para>
        <para>
          <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis>
          Drivers are responsible for freeing all GEM object resources, including
          the resources created by the GEM core. If an mmap offset has been
          created for the object (in which case
          <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield>
          is not NULL) it must be freed by a call to
          <function>drm_gem_free_mmap_offset</function>. The shmfs backing store
          must be released by calling <function>drm_gem_object_release</function>
          (that function can safely be called if no shmfs backing store has been
          created).
        </para>
      </sect3>
      <sect3>
        <title>GEM Objects Naming</title>
        <para>
          Communication between userspace and the kernel refers to GEM objects
          using local handles, global names or, more recently, file descriptors.
          All of those are 32-bit integer values; the usual Linux kernel limits
          apply to the file descriptors.
        </para>
        <para>
          GEM handles are local to a DRM file. Applications get a handle to a GEM
          object through a driver-specific ioctl, and can use that handle to refer
          to the GEM object in other standard or driver-specific ioctls. Closing a
          DRM file handle frees all its GEM handles and dereferences the
          associated GEM objects.
        </para>
        <para>
          To create a handle for a GEM object drivers call
          <function>drm_gem_handle_create</function>. The function takes a pointer
          to the DRM file and the GEM object and returns a locally unique handle.
          When the handle is no longer needed drivers delete it with a call to
          <function>drm_gem_handle_delete</function>. Finally the GEM object
          associated with a handle can be retrieved by a call to
          <function>drm_gem_object_lookup</function>.
        </para>
        <para>
          Handles don't take ownership of GEM objects, they only take a reference
          to the object that will be dropped when the handle is destroyed. To
          avoid leaking GEM objects, drivers must make sure they drop the
          reference(s) they own (such as the initial reference taken at object
          creation time) as appropriate, without any special consideration for the
          handle. For example, in the particular case of combined GEM object and
          handle creation in the implementation of the
          <methodname>dumb_create</methodname> operation, drivers must drop the
          initial reference to the GEM object before returning the handle.
        </para>
        <para>
          GEM names are similar in purpose to handles but are not local to DRM
          files. They can be passed between processes to reference a GEM object
          globally. Names can't be used directly to refer to objects in the DRM
          API, applications must convert handles to names and names to handles
          using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls
          respectively. The conversion is handled by the DRM core without any
          driver-specific support.
        </para>
        <para>
          GEM also supports buffer sharing with dma-buf file descriptors through
          PRIME. GEM-based drivers must use the provided helpers functions to
          implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />.
          Since sharing file descriptors is inherently more secure than the
          easily guessable and global GEM names it is the preferred buffer
          sharing mechanism. Sharing buffers through GEM names is only supported
          for legacy userspace. Furthermore PRIME also allows cross-device
          buffer sharing since it is based on dma-bufs.
        </para>
      </sect3>
      <sect3 id="drm-gem-objects-mapping">
        <title>GEM Objects Mapping</title>
        <para>
          Because mapping operations are fairly heavyweight GEM favours
          read/write-like access to buffers, implemented through driver-specific
          ioctls, over mapping buffers to userspace. However, when random access
          to the buffer is needed (to perform software rendering for instance),
          direct access to the object can be more efficient.
        </para>
        <para>
          The mmap system call can't be used directly to map GEM objects, as they
          don't have their own file handle. Two alternative methods currently
          co-exist to map GEM objects to userspace. The first method uses a
          driver-specific ioctl to perform the mapping operation, calling
          <function>do_mmap</function> under the hood. This is often considered
          dubious, seems to be discouraged for new GEM-enabled drivers, and will
          thus not be described here.
        </para>
        <para>
          The second method uses the mmap system call on the DRM file handle.
          <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd,
             off_t offset);</synopsis>
          DRM identifies the GEM object to be mapped by a fake offset passed
          through the mmap offset argument. Prior to being mapped, a GEM object
          must thus be associated with a fake offset. To do so, drivers must call
          <function>drm_gem_create_mmap_offset</function> on the object. The
          function allocates a fake offset range from a pool and stores the
          offset divided by PAGE_SIZE in
          <literal>obj-&gt;map_list.hash.key</literal>. Care must be taken not to
          call <function>drm_gem_create_mmap_offset</function> if a fake offset
          has already been allocated for the object. This can be tested by
          <literal>obj-&gt;map_list.map</literal> being non-NULL.
        </para>
        <para>
          Once allocated, the fake offset value
          (<literal>obj-&gt;map_list.hash.key &lt;&lt; PAGE_SHIFT</literal>)
          must be passed to the application in a driver-specific way and can then
          be used as the mmap offset argument.
        </para>
        <para>
          The GEM core provides a helper method <function>drm_gem_mmap</function>
          to handle object mapping. The method can be set directly as the mmap
          file operation handler. It will look up the GEM object based on the
          offset value and set the VMA operations to the
          <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
          field. Note that <function>drm_gem_mmap</function> doesn't map memory to
          userspace, but relies on the driver-provided fault handler to map pages
          individually.
        </para>
        <para>
          To use <function>drm_gem_mmap</function>, drivers must fill the struct
          <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield>
          field with a pointer to VM operations.
        </para>
        <para>
          <synopsis>struct vm_operations_struct *gem_vm_ops

  struct vm_operations_struct {
          void (*open)(struct vm_area_struct * area);
          void (*close)(struct vm_area_struct * area);
          int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf);
  };</synopsis>
        </para>
        <para>
          The <methodname>open</methodname> and <methodname>close</methodname>
          operations must update the GEM object reference count. Drivers can use
          the <function>drm_gem_vm_open</function> and
          <function>drm_gem_vm_close</function> helper functions directly as open
          and close handlers.
        </para>
        <para>
          The fault operation handler is responsible for mapping individual pages
          to userspace when a page fault occurs. Depending on the memory
          allocation scheme, drivers can allocate pages at fault time, or can
          decide to allocate memory for the GEM object at the time the object is
          created.
        </para>
        <para>
          Drivers that want to map the GEM object upfront instead of handling page
          faults can implement their own mmap file operation handler.
        </para>
      </sect3>
      <sect3>
        <title>Memory Coherency</title>
        <para>
          When mapped to the device or used in a command buffer, backing pages
          for an object are flushed to memory and marked write combined so as to
          be coherent with the GPU. Likewise, if the CPU accesses an object
          after the GPU has finished rendering to the object, then the object
          must be made coherent with the CPU's view of memory, usually involving
          GPU cache flushing of various kinds. This core CPU&lt;-&gt;GPU
          coherency management is provided by a device-specific ioctl, which
          evaluates an object's current domain and performs any necessary
          flushing or synchronization to put the object into the desired
          coherency domain (note that the object may be busy, i.e. an active
          render target; in that case, setting the domain blocks the client and
          waits for rendering to complete before performing any necessary
          flushing operations).
        </para>
      </sect3>
      <sect3>
        <title>Command Execution</title>
        <para>
          Perhaps the most important GEM function for GPU devices is providing a
          command execution interface to clients. Client programs construct
          command buffers containing references to previously allocated memory
          objects, and then submit them to GEM. At that point, GEM takes care to
          bind all the objects into the GTT, execute the buffer, and provide
          necessary synchronization between clients accessing the same buffers.
          This often involves evicting some objects from the GTT and re-binding
          others (a fairly expensive operation), and providing relocation
          support which hides fixed GTT offsets from clients. Clients must take
          care not to submit command buffers that reference more objects than
          can fit in the GTT; otherwise, GEM will reject them and no rendering
          will occur. Similarly, if several objects in the buffer require fence
          registers to be allocated for correct rendering (e.g. 2D blits on
          pre-965 chips), care must be taken not to require more fence registers
          than are available to the client. Such resource management should be
          abstracted from the client in libdrm.
        </para>
      </sect3>
      <sect3>
        <title>GEM Function Reference</title>
<!-- drivers/gpu/drm/drm_gem.c -->
<refentry id="API-drm-gem-object-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_object_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_object_init</refname>
 <refpurpose>
  initialize an allocated shmem-backed GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_object_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device the object should be initialized for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     drm_gem_object to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     object size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize an already allocated GEM object of the specified size with
   shmfs backing store.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-private-object-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_private_object_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_private_object_init</refname>
 <refpurpose>
     initialize an allocated private GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_private_object_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device the object should be initialized for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     drm_gem_object to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     object size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize an already allocated GEM object of the specified size with
   no GEM provided backing store. Instead the caller is responsible for
   backing the object and handling it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-handle-delete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_handle_delete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_handle_delete</refname>
 <refpurpose>
     deletes the given file-private handle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_handle_delete </function></funcdef>
   <paramdef>struct drm_file * <parameter>filp</parameter></paramdef>
   <paramdef>u32 <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     drm file-private structure to use for the handle look up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     userspace handle to delete
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Removes the GEM handle from the <parameter>filp</parameter> lookup table and if this is the last
   handle also cleans up linked resources like GEM names.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-dumb-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_dumb_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_dumb_destroy</refname>
 <refpurpose>
     dumb fb callback helper for gem based drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_dumb_destroy </function></funcdef>
   <paramdef>struct drm_file * <parameter>file</parameter></paramdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>uint32_t <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     drm file-private structure to remove the dumb handle from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     corresponding drm_device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     the dumb handle to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This implements the -&gt;dumb_destroy kms driver callback for drivers which use
   gem to manage their backing storage.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-handle-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_handle_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_handle_create</refname>
 <refpurpose>
     create a gem handle for an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_handle_create </function></funcdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>u32 * <parameter>handlep</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     drm file-private structure to register the handle for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     object to register
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handlep</parameter></term>
   <listitem>
    <para>
     pionter to return the created handle to the caller
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create a handle for this object. This adds a handle reference
   to the object, which includes a regular reference count. Callers
   will likely want to dereference the object afterwards.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-free-mmap-offset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_free_mmap_offset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_free_mmap_offset</refname>
 <refpurpose>
     release a fake mmap offset for an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_free_mmap_offset </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     obj in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This routine frees fake offsets allocated by <function>drm_gem_create_mmap_offset</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-create-mmap-offset-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_create_mmap_offset_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_create_mmap_offset_size</refname>
 <refpurpose>
     create a fake mmap offset for an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_create_mmap_offset_size </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     obj in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the virtual size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   GEM memory mapping works by handing back to userspace a fake mmap offset
   it can use in a subsequent mmap(2) call.  The DRM core code then looks
   up the object based on the offset and sets up the various memory mapping
   structures.
   </para><para>

   This routine allocates and attaches a fake offset for <parameter>obj</parameter>, in cases where
   the virtual size differs from the physical size (ie. obj-&gt;size).  Otherwise
   just use <function>drm_gem_create_mmap_offset</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-create-mmap-offset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_create_mmap_offset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_create_mmap_offset</refname>
 <refpurpose>
     create a fake mmap offset for an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_create_mmap_offset </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     obj in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   GEM memory mapping works by handing back to userspace a fake mmap offset
   it can use in a subsequent mmap(2) call.  The DRM core code then looks
   up the object based on the offset and sets up the various memory mapping
   structures.
   </para><para>

   This routine allocates and attaches a fake offset for <parameter>obj</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-get-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_get_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_get_pages</refname>
 <refpurpose>
     helper to allocate backing pages for a GEM object from shmem
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct page ** <function>drm_gem_get_pages </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     obj in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This reads the page-array of the shmem-backing storage of the given gem
   object. An array of pages is returned. If a page is not allocated or
   swapped-out, this will allocate/swap-in the required pages. Note that the
   whole object is covered by the page-array and pinned in memory.
   </para><para>

   Use <function>drm_gem_put_pages</function> to release the array and unpin all pages.
   </para><para>

   This uses the GFP-mask set on the shmem-mapping (see <function>mapping_set_gfp_mask</function>).
   If you require other GFP-masks, you have to do those allocations yourself.
   </para><para>

   Note that you are not allowed to change gfp-zones during runtime. That is,
   <function>shmem_read_mapping_page_gfp</function> must be called with the same gfp_zone(gfp) as
   set during initialization. If you have special zone constraints, set them
   after <function>drm_gem_init_object</function> via <function>mapping_set_gfp_mask</function>. shmem-core takes care
   to keep pages in the required zone during swap-in.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-put-pages">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_put_pages</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_put_pages</refname>
 <refpurpose>
     helper to free backing pages for a GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_put_pages </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
   <paramdef>bool <parameter>dirty</parameter></paramdef>
   <paramdef>bool <parameter>accessed</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     obj in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     pages to free
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dirty</parameter></term>
   <listitem>
    <para>
     if true, pages will be marked as dirty
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>accessed</parameter></term>
   <listitem>
    <para>
     if true, the pages will be marked as accessed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-gem-object-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_object_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_object_free</refname>
 <refpurpose>
     free a GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_object_free </function></funcdef>
   <paramdef>struct kref * <parameter>kref</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>kref</parameter></term>
   <listitem>
    <para>
     kref of the object to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called after the last reference to the object has been lost.
   Must be called holding struct_ mutex
   </para><para>

   Frees the object
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-mmap-obj">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_mmap_obj</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_mmap_obj</refname>
 <refpurpose>
     memory map a GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_mmap_obj </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>unsigned long <parameter>obj_size</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     the GEM object to map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>obj_size</parameter></term>
   <listitem>
    <para>
     the object size to be mapped, in bytes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     VMA for the area to be mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set up the VMA to prepare mapping of the GEM object using the gem_vm_ops
   provided by the driver. Depending on their requirements, drivers can either
   provide a fault handler in their gem_vm_ops (in which case any accesses to
   the object will be trapped, to perform migration, GTT binding, surface
   register allocation, or performance monitoring), or mmap the buffer memory
   synchronously after calling drm_gem_mmap_obj.
   </para><para>

   This function is mainly intended to implement the DMABUF mmap operation, when
   the GEM object is not looked up based on its fake offset. To implement the
   DRM mmap operation, drivers should use the <function>drm_gem_mmap</function> function.
   </para><para>

   <function>drm_gem_mmap_obj</function> assumes the user is granted access to the buffer while
   <function>drm_gem_mmap</function> prevents unprivileged users from mapping random objects. So
   callers must verify access restrictions before calling this helper.
   </para><para>

   Return 0 or success or -EINVAL if the object size is smaller than the VMA
   size, or if no gem_vm_ops are provided.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-mmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_mmap</refname>
 <refpurpose>
     memory map routine for GEM objects
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_mmap </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     DRM file pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     VMA for the area to be mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If a driver supports GEM object mapping, mmap calls on the DRM file
   descriptor will end up here.
   </para><para>

   Look up the GEM object based on the offset passed in (vma-&gt;vm_pgoff will
   contain the fake offset we created when the GTT map ioctl was called on
   the object) and map it with a call to <function>drm_gem_mmap_obj</function>.
   </para><para>

   If the caller is not granted access to the buffer object, the mmap will fail
   with EACCES. Please see the vma manager for more information.
</para>
</refsect1>
</refentry>

      </sect3>
    </sect2>
    <sect2>
      <title>VMA Offset Manager</title>
<para>
   </para><para>
   The vma-manager is responsible to map arbitrary driver-dependent memory
   regions into the linear user address-space. It provides offsets to the
   caller which can then be used on the address_space of the drm-device. It
   takes care to not overlap regions, size them appropriately and to not
   confuse mm-core by inconsistent fake vm_pgoff fields.
   Drivers shouldn't use this for object placement in VMEM. This manager should
   only be used to manage mappings into linear user-space VMs.
   </para><para>
   We use drm_mm as backend to manage object allocations. But it is highly
   optimized for alloc/free calls, not lookups. Hence, we use an rb-tree to
   speed up offset lookups.
   </para><para>
   You must not use multiple offset managers on a single address_space.
   Otherwise, mm-core will be unable to tear down memory mappings as the VM will
   no longer be linear.
   </para><para>
   This offset manager works on page-based addresses. That is, every argument
   and return code (with the exception of <function>drm_vma_node_offset_addr</function>) is given
   in number of pages, not number of bytes. That means, object sizes and offsets
   must always be page-aligned (as usual).
   If you want to get a valid byte-based user-space address for a given offset,
   please see <function>drm_vma_node_offset_addr</function>.
   </para><para>
   Additionally to offset management, the vma offset manager also handles access
   management. For every open-file context that is allowed to access a given
   node, you must call <function>drm_vma_node_allow</function>. Otherwise, an <function>mmap</function> call on this
   open-file with the offset of the node will fail with -EACCES. To revoke
   access again, use <function>drm_vma_node_revoke</function>. However, the caller is responsible
   for destroying already existing mappings, if required.
</para>

<!-- drivers/gpu/drm/drm_vma_manager.c -->
<refentry id="API-drm-vma-offset-manager-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_manager_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_manager_init</refname>
 <refpurpose>
  Initialize new offset-manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_offset_manager_init </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
   <paramdef>unsigned long <parameter>page_offset</parameter></paramdef>
   <paramdef>unsigned long <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>page_offset</parameter></term>
   <listitem>
    <para>
     Offset of available memory area (page-based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     Size of available address space range (page-based)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize a new offset-manager. The offset and area size available for the
   manager are given as <parameter>page_offset</parameter> and <parameter>size</parameter>. Both are interpreted as
   page-numbers, not bytes.
   </para><para>

   Adding/removing nodes from the manager is locked internally and protected
   against concurrent access. However, node allocation and destruction is left
   for the caller. While calling into the vma-manager, a given node must
   always be guaranteed to be referenced.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-offset-manager-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_manager_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_manager_destroy</refname>
 <refpurpose>
     Destroy offset manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_offset_manager_destroy </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Destroy an object manager which was previously created via
   <function>drm_vma_offset_manager_init</function>. The caller must remove all allocated nodes
   before destroying the manager. Otherwise, drm_mm will refuse to free the
   requested resources.
   </para><para>

   The manager must not be accessed after this function is called.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-offset-lookup-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_lookup_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_lookup_locked</refname>
 <refpurpose>
     Find node in offset space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_vma_offset_node * <function>drm_vma_offset_lookup_locked </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
   <paramdef>unsigned long <parameter>start</parameter></paramdef>
   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Start address for object (page-based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     Size of object (page-based)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Find a node given a start address and object size. This returns the _best_
   match for the given node. That is, <parameter>start</parameter> may point somewhere into a valid
   region and the given node will be returned, as long as the node spans the
   whole requested area (given the size in number of pages as <parameter>pages</parameter>).
   </para><para>

   Note that before lookup the vma offset manager lookup lock must be acquired
   with <function>drm_vma_offset_lock_lookup</function>. See there for an example. This can then be
   used to implement weakly referenced lookups using <function>kref_get_unless_zero</function>.
</para>
</refsect1>
<refsect1>
<title>Example</title>
<informalexample><programlisting>
       drm_vma_offset_lock_lookup(mgr);
       node = drm_vma_offset_lookup_locked(mgr);
       if (node)
           kref_get_unless_zero(container_of(node, sth, entr));
       drm_vma_offset_unlock_lookup(mgr);
</programlisting></informalexample>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Returns NULL if no suitable node can be found. Otherwise, the best match
   is returned. It's the caller's responsibility to make sure the node doesn't
   get destroyed before the caller can access it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-offset-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_add</refname>
 <refpurpose>
     Add offset node to manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_vma_offset_add </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to be added
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     Allocation size visible to user-space (in number of pages)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a node to the offset-manager. If the node was already added, this does
   nothing and return 0. <parameter>pages</parameter> is the size of the object given in number of
   pages.
   After this call succeeds, you can access the offset of the node until it
   is removed again.
   </para><para>

   If this call fails, it is safe to retry the operation or call
   <function>drm_vma_offset_remove</function>, anyway. However, no cleanup is required in that
   case.
   </para><para>

   <parameter>pages</parameter> is not required to be the same size as the underlying memory object
   that you want to map. It only limits the size that user-space can map into
   their address space.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-offset-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_remove</refname>
 <refpurpose>
     Remove offset node from manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_offset_remove </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to be removed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Remove a node from the offset manager. If the node wasn't added before, this
   does nothing. After this call returns, the offset and size will be 0 until a
   new offset is allocated via <function>drm_vma_offset_add</function> again. Helper functions like
   <function>drm_vma_node_start</function> and <function>drm_vma_node_offset_addr</function> will return 0 if no
   offset is allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-allow">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_allow</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_allow</refname>
 <refpurpose>
     Add open-file to list of allowed users
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_vma_node_allow </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to modify
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     Open file to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add <parameter>filp</parameter> to the list of allowed open-files for this node. If <parameter>filp</parameter> is
   already on this list, the ref-count is incremented.
   </para><para>

   The list of allowed-users is preserved across <function>drm_vma_offset_add</function> and
   <function>drm_vma_offset_remove</function> calls. You may even call it if the node is currently
   not added to any offset-manager.
   </para><para>

   You must remove all open-files the same number of times as you added them
   before destroying the node. Otherwise, you will leak memory.
   </para><para>

   This is locked against concurrent access internally.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success, negative error code on internal failure (out-of-mem)
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-revoke">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_revoke</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_revoke</refname>
 <refpurpose>
     Remove open-file from list of allowed users
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_node_revoke </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to modify
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     Open file to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Decrement the ref-count of <parameter>filp</parameter> in the list of allowed open-files on <parameter>node</parameter>.
   If the ref-count drops to zero, remove <parameter>filp</parameter> from the list. You must call
   this once for every <function>drm_vma_node_allow</function> on <parameter>filp</parameter>.
   </para><para>

   This is locked against concurrent access internally.
   </para><para>

   If <parameter>filp</parameter> is not on the list, nothing is done.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-is-allowed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_is_allowed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_is_allowed</refname>
 <refpurpose>
     Check whether an open-file is granted access
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_vma_node_is_allowed </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     Open-file to check for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Search the list in <parameter>node</parameter> whether <parameter>filp</parameter> is currently on the list of allowed
   open-files (see <function>drm_vma_node_allow</function>).
   </para><para>

   This is locked against concurrent access internally.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   true iff <parameter>filp</parameter> is on the list
</para>
</refsect1>
</refentry>

<!-- include/drm/drm_vma_manager.h -->
<refentry id="API-drm-vma-offset-exact-lookup-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_exact_lookup_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_exact_lookup_locked</refname>
 <refpurpose>
  Look up node by exact address
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_vma_offset_node * <function>drm_vma_offset_exact_lookup_locked </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
   <paramdef>unsigned long <parameter>start</parameter></paramdef>
   <paramdef>unsigned long <parameter>pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Start address (page-based, not byte-based)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     Size of object (page-based)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as <function>drm_vma_offset_lookup_locked</function> but does not allow any offset into the node.
   It only returns the exact object with the given start address.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Node at exact start address <parameter>start</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-offset-lock-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_lock_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_lock_lookup</refname>
 <refpurpose>
     Lock lookup for extended private use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_offset_lock_lookup </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Lock VMA manager for extended lookups. Only locked VMA function calls
   are allowed while holding this lock. All other contexts are blocked from VMA
   until the lock is released via <function>drm_vma_offset_unlock_lookup</function>.
   </para><para>

   Use this if you need to take a reference to the objects returned by
   <function>drm_vma_offset_lookup_locked</function> before releasing this lock again.
   </para><para>

   This lock must not be used for anything else than extended lookups. You must
   not call any other VMA helpers while holding this lock.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   You're in atomic-context while holding this lock!
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-offset-unlock-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_offset_unlock_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_offset_unlock_lookup</refname>
 <refpurpose>
     Unlock lookup for extended private use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_offset_unlock_lookup </function></funcdef>
   <paramdef>struct drm_vma_offset_manager * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     Manager object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release lookup-lock. See <function>drm_vma_offset_lock_lookup</function> for more information.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_reset</refname>
 <refpurpose>
     Initialize or reset node object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_node_reset </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to initialize or reset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Reset a node to its initial state. This must be called before using it with
   any VMA offset manager.
   </para><para>

   This must not be called on an already allocated node, or you will leak
   memory.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_start</refname>
 <refpurpose>
     Return start address for page-based addressing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>drm_vma_node_start </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to inspect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the start address of the given node. This can be used as offset into
   the linear VM space that is provided by the VMA offset manager. Note that
   this can only be used for page-based addressing. If you need a proper offset
   for user-space mappings, you must apply <quote>&lt;&lt; PAGE_SHIFT</quote> or use the
   <function>drm_vma_node_offset_addr</function> helper instead.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Start address of <parameter>node</parameter> for page-based addressing. 0 if the node does not
   have an offset allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_size</refname>
 <refpurpose>
     Return size (page-based)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>drm_vma_node_size </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to inspect
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return the size as number of pages for the given node. This is the same size
   that was passed to <function>drm_vma_offset_add</function>. If no offset is allocated for the
   node, this is 0.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Size of <parameter>node</parameter> as number of pages. 0 if the node does not have an offset
   allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-has-offset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_has_offset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_has_offset</refname>
 <refpurpose>
     Check whether node is added to offset manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_vma_node_has_offset </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Node to be checked
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   true iff the node was previously allocated an offset and added to
   an vma offset manager.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-offset-addr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_offset_addr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_offset_addr</refname>
 <refpurpose>
     Return sanitized offset for user-space mmaps
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>__u64 <function>drm_vma_node_offset_addr </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Linked offset node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Same as <function>drm_vma_node_start</function> but returns the address as a valid offset that
   can be used for user-space mappings during <function>mmap</function>.
   This must not be called on unlinked nodes.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Offset of <parameter>node</parameter> for byte-based addressing. 0 if the node does not have an
   object allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-unmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_unmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_unmap</refname>
 <refpurpose>
     Unmap offset node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vma_node_unmap </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
   <paramdef>struct address_space * <parameter>file_mapping</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Offset node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file_mapping</parameter></term>
   <listitem>
    <para>
     Address space to unmap <parameter>node</parameter> from
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unmap all userspace mappings for a given offset node. The mappings must be
   associated with the <parameter>file_mapping</parameter> address-space. If no offset exists
   nothing is done.
   </para><para>

   This call is unlocked. The caller must guarantee that <function>drm_vma_offset_remove</function>
   is not called on this node concurrently.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vma-node-verify-access">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vma_node_verify_access</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vma_node_verify_access</refname>
 <refpurpose>
     Access verification helper for TTM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_vma_node_verify_access </function></funcdef>
   <paramdef>struct drm_vma_offset_node * <parameter>node</parameter></paramdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     Offset node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     Open-file
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This checks whether <parameter>filp</parameter> is granted access to <parameter>node</parameter>. It is the same as
   <function>drm_vma_node_is_allowed</function> but suitable as drop-in helper for TTM
   <function>verify_access</function> callbacks.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 if access is granted, -EACCES otherwise.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2 id="drm-prime-support">
      <title>PRIME Buffer Sharing</title>
      <para>
        PRIME is the cross device buffer sharing framework in drm, originally
        created for the OPTIMUS range of multi-gpu platforms. To userspace
        PRIME buffers are dma-buf based file descriptors.
      </para>
      <sect3>
        <title>Overview and Driver Interface</title>
        <para>
          Similar to GEM global names, PRIME file descriptors are
          also used to share buffer objects across processes. They offer
          additional security: as file descriptors must be explicitly sent over
          UNIX domain sockets to be shared between applications, they can't be
          guessed like the globally unique GEM names.
        </para>
        <para>
          Drivers that support the PRIME
          API must set the DRIVER_PRIME bit in the struct
          <structname>drm_driver</structname>
          <structfield>driver_features</structfield> field, and implement the
          <methodname>prime_handle_to_fd</methodname> and
          <methodname>prime_fd_to_handle</methodname> operations.
        </para>
        <para>
          <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev,
                          struct drm_file *file_priv, uint32_t handle,
                          uint32_t flags, int *prime_fd);
int (*prime_fd_to_handle)(struct drm_device *dev,
                          struct drm_file *file_priv, int prime_fd,
                          uint32_t *handle);</synopsis>
            Those two operations convert a handle to a PRIME file descriptor and
            vice versa. Drivers must use the kernel dma-buf buffer sharing framework
            to manage the PRIME file descriptors. Similar to the mode setting
            API PRIME is agnostic to the underlying buffer object manager, as
            long as handles are 32bit unsigned integers.
          </para>
          <para>
            While non-GEM drivers must implement the operations themselves, GEM
            drivers must use the <function>drm_gem_prime_handle_to_fd</function>
            and <function>drm_gem_prime_fd_to_handle</function> helper functions.
            Those helpers rely on the driver
            <methodname>gem_prime_export</methodname> and
            <methodname>gem_prime_import</methodname> operations to create a dma-buf
            instance from a GEM object (dma-buf exporter role) and to create a GEM
            object from a dma-buf instance (dma-buf importer role).
          </para>
          <para>
            <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev,
                             struct drm_gem_object *obj,
                             int flags);
struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev,
                                            struct dma_buf *dma_buf);</synopsis>
            These two operations are mandatory for GEM drivers that support
            PRIME.
          </para>
        </sect3>
      <sect3>
        <title>PRIME Helper Functions</title>
<para>
   </para><para>
   Drivers can implement <parameter>gem_prime_export</parameter> and <parameter>gem_prime_import</parameter> in terms of
   simpler APIs by using the helper functions <parameter>drm_gem_prime_export</parameter> and
   <parameter>drm_gem_prime_import</parameter>.  These functions implement dma-buf support in terms of
   six lower-level driver callbacks:
   </para><para>
   Export callbacks:
   </para><para>
   - <parameter>gem_prime_pin</parameter> (optional): prepare a GEM object for exporting
   </para><para>
   - <parameter>gem_prime_get_sg_table</parameter>: provide a scatter/gather table of pinned pages
   </para><para>
   - <parameter>gem_prime_vmap</parameter>: vmap a buffer exported by your driver
   </para><para>
   - <parameter>gem_prime_vunmap</parameter>: vunmap a buffer exported by your driver
   </para><para>
   - <parameter>gem_prime_mmap</parameter> (optional): mmap a buffer exported by your driver
   </para><para>
   Import callback:
   </para><para>
   - <parameter>gem_prime_import_sg_table</parameter> (import): produce a GEM object from another
   driver's scatter/gather table
</para>

      </sect3>
    </sect2>
    <sect2>
      <title>PRIME Function References</title>
<!-- drivers/gpu/drm/drm_prime.c -->
<refentry id="API-drm-gem-dmabuf-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_dmabuf_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_dmabuf_release</refname>
 <refpurpose>
  dma_buf release implementation for GEM
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_dmabuf_release </function></funcdef>
   <paramdef>struct dma_buf * <parameter>dma_buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dma_buf</parameter></term>
   <listitem>
    <para>
     buffer to be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Generic release function for dma_bufs exported as PRIME buffers. GEM drivers
   must use this in their dma_buf ops structure as the release callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-prime-export">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_prime_export</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_prime_export</refname>
 <refpurpose>
     helper library implementation of the export callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct dma_buf * <function>drm_gem_prime_export </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device to export from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object to export
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags like DRM_CLOEXEC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the implementation of the gem_prime_export functions for GEM drivers
   using the PRIME helpers.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-prime-handle-to-fd">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_prime_handle_to_fd</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_prime_handle_to_fd</refname>
 <refpurpose>
     PRIME export function for GEM drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_prime_handle_to_fd </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
   <paramdef>uint32_t <parameter>handle</parameter></paramdef>
   <paramdef>uint32_t <parameter>flags</parameter></paramdef>
   <paramdef>int * <parameter>prime_fd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     dev to export the buffer from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     drm file-private structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     buffer handle to export
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags like DRM_CLOEXEC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prime_fd</parameter></term>
   <listitem>
    <para>
     pointer to storage for the fd id of the create dma-buf
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the PRIME export function which must be used mandatorily by GEM
   drivers to ensure correct lifetime management of the underlying GEM object.
   The actual exporting from GEM object to a dma-buf is done through the
   gem_prime_export driver callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-prime-import">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_prime_import</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_prime_import</refname>
 <refpurpose>
     helper library implementation of the import callback
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_gem_object * <function>drm_gem_prime_import </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct dma_buf * <parameter>dma_buf</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device to import into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dma_buf</parameter></term>
   <listitem>
    <para>
     dma-buf object to import
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the implementation of the gem_prime_import functions for GEM drivers
   using the PRIME helpers.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-prime-fd-to-handle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_prime_fd_to_handle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_prime_fd_to_handle</refname>
 <refpurpose>
     PRIME import function for GEM drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_prime_fd_to_handle </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
   <paramdef>int <parameter>prime_fd</parameter></paramdef>
   <paramdef>uint32_t * <parameter>handle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     dev to export the buffer from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     drm file-private structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prime_fd</parameter></term>
   <listitem>
    <para>
     fd id of the dma-buf which should be imported
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     pointer to storage for the handle of the imported buffer object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the PRIME import function which must be used mandatorily by GEM
   drivers to ensure correct lifetime management of the underlying GEM object.
   The actual importing of GEM object from the dma-buf is done through the
   gem_import_export driver callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-prime-pages-to-sg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_prime_pages_to_sg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_prime_pages_to_sg</refname>
 <refpurpose>
     converts a page array into an sg list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sg_table * <function>drm_prime_pages_to_sg </function></funcdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
   <paramdef>unsigned int <parameter>nr_pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     pointer to the array of page pointers to convert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>nr_pages</parameter></term>
   <listitem>
    <para>
     length of the page vector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper creates an sg table object from a set of pages
   the driver is responsible for mapping the pages into the
   importers address space for use with dma_buf itself.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-prime-sg-to-page-addr-arrays">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_prime_sg_to_page_addr_arrays</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_prime_sg_to_page_addr_arrays</refname>
 <refpurpose>
     convert an sg table into a page array
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_prime_sg_to_page_addr_arrays </function></funcdef>
   <paramdef>struct sg_table * <parameter>sgt</parameter></paramdef>
   <paramdef>struct page ** <parameter>pages</parameter></paramdef>
   <paramdef>dma_addr_t * <parameter>addrs</parameter></paramdef>
   <paramdef>int <parameter>max_pages</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>sgt</parameter></term>
   <listitem>
    <para>
     scatter-gather table to convert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pages</parameter></term>
   <listitem>
    <para>
     array of page pointers to store the page array in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>addrs</parameter></term>
   <listitem>
    <para>
     optional array to store the dma bus address of each page
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_pages</parameter></term>
   <listitem>
    <para>
     size of both the passed-in arrays
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Exports an sg table into an array of pages and addresses. This is currently
   required by the TTM driver in order to do correct fault handling.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-prime-gem-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_prime_gem_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_prime_gem_destroy</refname>
 <refpurpose>
     helper to clean up a PRIME-imported GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_prime_gem_destroy </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>struct sg_table * <parameter>sg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object which was created from a dma-buf
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sg</parameter></term>
   <listitem>
    <para>
     the sg-table which was pinned at import time
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the cleanup functions which GEM drivers need to call when they use
   <parameter>drm_gem_prime_import</parameter> to import dma-bufs.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>DRM MM Range Allocator</title>
      <sect3>
        <title>Overview</title>
<para>
   </para><para>
   drm_mm provides a simple range allocator. The drivers are free to use the
   resource allocator from the linux core if it suits them, the upside of drm_mm
   is that it's in the DRM core. Which means that it's easier to extend for
   some of the crazier special purpose needs of gpus.
   </para><para>
   The main data struct is <structname>drm_mm</structname>, allocations are tracked in <structname>drm_mm_node</structname>.
   Drivers are free to embed either of them into their own suitable
   datastructures. drm_mm itself will not do any allocations of its own, so if
   drivers choose not to embed nodes they need to still allocate them
   themselves.
   </para><para>
   The range allocator also supports reservation of preallocated blocks. This is
   useful for taking over initial mode setting configurations from the firmware,
   where an object needs to be created which exactly matches the firmware's
   scanout target. As long as the range is still free it can be inserted anytime
   after the allocator is initialized, which helps with avoiding looped
   depencies in the driver load sequence.
   </para><para>
   drm_mm maintains a stack of most recently freed holes, which of all
   simplistic datastructures seems to be a fairly decent approach to clustering
   allocations and avoiding too much fragmentation. This means free space
   searches are O(num_holes). Given that all the fancy features drm_mm supports
   something better would be fairly complex and since gfx thrashing is a fairly
   steep cliff not a real concern. Removing a node again is O(1).
   </para><para>
   drm_mm supports a few features: Alignment and range restrictions can be
   supplied. Further more every <structname>drm_mm_node</structname> has a color value (which is just an
   opaqua unsigned long) which in conjunction with a driver callback can be used
   to implement sophisticated placement restrictions. The i915 DRM driver uses
   this to implement guard pages between incompatible caching domains in the
   graphics TT.
   </para><para>
   Two behaviors are supported for searching and allocating: bottom-up and top-down.
   The default is bottom-up. Top-down allocation can be used if the memory area
   has different restrictions, or just to reduce fragmentation.
   </para><para>
   Finally iteration helpers to walk all nodes and all holes are provided as are
   some basic allocator dumpers for debugging.
</para>

      </sect3>
      <sect3>
        <title>LRU Scan/Eviction Support</title>
<para>
   </para><para>
   Very often GPUs need to have continuous allocations for a given object. When
   evicting objects to make space for a new one it is therefore not most
   efficient when we simply start to select all objects from the tail of an LRU
   until there's a suitable hole: Especially for big objects or nodes that
   otherwise have special allocation constraints there's a good chance we evict
   lots of (smaller) objects unecessarily.
   </para><para>
   The DRM range allocator supports this use-case through the scanning
   interfaces. First a scan operation needs to be initialized with
   <function>drm_mm_init_scan</function> or <function>drm_mm_init_scan_with_range</function>. The the driver adds
   objects to the roaster (probably by walking an LRU list, but this can be
   freely implemented) until a suitable hole is found or there's no further
   evitable object.
   </para><para>
   The the driver must walk through all objects again in exactly the reverse
   order to restore the allocator state. Note that while the allocator is used
   in the scan mode no other operation is allowed.
   </para><para>
   Finally the driver evicts all objects selected in the scan. Adding and
   removing an object is O(1), and since freeing a node is also O(1) the overall
   complexity is O(scanned_objects). So like the free stack which needs to be
   walked before a scan operation even begins this is linear in the number of
   objects. It doesn't seem to hurt badly.
</para>

      </sect3>
      </sect2>
    <sect2>
      <title>DRM MM Range Allocator Function References</title>
<!-- drivers/gpu/drm/drm_mm.c -->
<refentry id="API-drm-mm-reserve-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_reserve_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_reserve_node</refname>
 <refpurpose>
  insert an pre-initialized node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mm_reserve_node </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to insert <parameter>node</parameter> into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     drm_mm_node to insert
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions inserts an already set-up drm_mm_node into the allocator,
   meaning that start, size and color must be set by the caller. This is useful
   to initialize the allocator with preallocated objects which must be set-up
   before the range allocator can be set-up, e.g. when taking over a firmware
   framebuffer.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, -ENOSPC if there's no hole where <parameter>node</parameter> is.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-insert-node-generic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_insert_node_generic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_insert_node_generic</refname>
 <refpurpose>
     search for space and insert <parameter>node</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mm_insert_node_generic </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>unsigned long <parameter>color</parameter></paramdef>
   <paramdef>enum drm_mm_search_flags <parameter>sflags</parameter></paramdef>
   <paramdef>enum drm_mm_allocator_flags <parameter>aflags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to allocate from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     preallocate node to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>color</parameter></term>
   <listitem>
    <para>
     opaque tag value to use for this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sflags</parameter></term>
   <listitem>
    <para>
     flags to fine-tune the allocation search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>aflags</parameter></term>
   <listitem>
    <para>
     flags to fine-tune the allocation behavior
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The preallocated node must be cleared to 0.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, -ENOSPC if there's no suitable hole.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-insert-node-in-range-generic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_insert_node_in_range_generic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_insert_node_in_range_generic</refname>
 <refpurpose>
     ranged search for space and insert <parameter>node</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mm_insert_node_in_range_generic </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>unsigned long <parameter>color</parameter></paramdef>
   <paramdef>u64 <parameter>start</parameter></paramdef>
   <paramdef>u64 <parameter>end</parameter></paramdef>
   <paramdef>enum drm_mm_search_flags <parameter>sflags</parameter></paramdef>
   <paramdef>enum drm_mm_allocator_flags <parameter>aflags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to allocate from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     preallocate node to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>color</parameter></term>
   <listitem>
    <para>
     opaque tag value to use for this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of the allowed range for this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     end of the allowed range for this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sflags</parameter></term>
   <listitem>
    <para>
     flags to fine-tune the allocation search
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>aflags</parameter></term>
   <listitem>
    <para>
     flags to fine-tune the allocation behavior
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The preallocated node must be cleared to 0.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, -ENOSPC if there's no suitable hole.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-remove-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_remove_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_remove_node</refname>
 <refpurpose>
     Remove a memory node from the allocator.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_remove_node </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     drm_mm_node to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This just removes a node from its drm_mm allocator. The node does not need to
   be cleared again before it can be re-inserted into this or any other drm_mm
   allocator. It is a bug to call this function on a un-allocated node.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-replace-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_replace_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_replace_node</refname>
 <refpurpose>
     move an allocation from <parameter>old</parameter> to <parameter>new</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_replace_node </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>old</parameter></paramdef>
   <paramdef>struct drm_mm_node * <parameter>new</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     drm_mm_node to remove from the allocator
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     drm_mm_node which should inherit <parameter>old</parameter>'s allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is useful for when drivers embed the drm_mm_node structure and hence
   can't move allocations by reassigning pointers. It's a combination of remove
   and insert with the guarantee that the allocation start will match.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-init-scan">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_init_scan</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_init_scan</refname>
 <refpurpose>
     initialize lru scanning
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_init_scan </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>unsigned long <parameter>color</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to scan
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>color</parameter></term>
   <listitem>
    <para>
     opaque tag value to use for the allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This simply sets up the scanning routines with the parameters for the desired
   hole. Note that there's no need to specify allocation flags, since they only
   change the place a node is allocated from within a suitable hole.
</para>
</refsect1>
<refsect1>
<title>Warning</title>
<para>
   As long as the scan list is non-empty, no other operations than
   adding/removing nodes to/from the scan list are allowed.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-init-scan-with-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_init_scan_with_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_init_scan_with_range</refname>
 <refpurpose>
     initialize range-restricted lru scanning
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_init_scan_with_range </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>unsigned long <parameter>color</parameter></paramdef>
   <paramdef>u64 <parameter>start</parameter></paramdef>
   <paramdef>u64 <parameter>end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to scan
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>color</parameter></term>
   <listitem>
    <para>
     opaque tag value to use for the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of the allowed range for the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     end of the allowed range for the allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This simply sets up the scanning routines with the parameters for the desired
   hole. Note that there's no need to specify allocation flags, since they only
   change the place a node is allocated from within a suitable hole.
</para>
</refsect1>
<refsect1>
<title>Warning</title>
<para>
   As long as the scan list is non-empty, no other operations than
   adding/removing nodes to/from the scan list are allowed.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-scan-add-block">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_scan_add_block</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_scan_add_block</refname>
 <refpurpose>
     add a node to the scan list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mm_scan_add_block </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     drm_mm_node to add
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add a node to the scan list that might be freed to make space for the desired
   hole.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if a hole has been found, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-scan-remove-block">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_scan_remove_block</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_scan_remove_block</refname>
 <refpurpose>
     remove a node from the scan list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mm_scan_remove_block </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     drm_mm_node to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Nodes _must_ be removed in the exact same order from the scan list as they
   have been added, otherwise the internal state of the memory manager will be
   corrupted.
   </para><para>

   When the scan list is empty, the selected memory nodes can be freed. An
   immediately following drm_mm_search_free with !DRM_MM_SEARCH_BEST will then
   return the just freed block (because its at the top of the free_stack list).
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if this block should be evicted, false otherwise. Will always
   return false when no hole has been found.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-clean">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_clean</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_clean</refname>
 <refpurpose>
     checks whether an allocator is clean
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mm_clean </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the allocator is completely free, false if there's still a node
   allocated in it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_init</refname>
 <refpurpose>
     initialize a drm-mm allocator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_init </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>u64 <parameter>start</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     the drm_mm structure to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of the range managed by <parameter>mm</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     end of the range managed by <parameter>mm</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that <parameter>mm</parameter> must be cleared to 0 before calling this function.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-takedown">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_takedown</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_takedown</refname>
 <refpurpose>
     clean up a drm_mm allocator
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_takedown </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to clean up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that it is a bug to call this function on an allocator which is not
   clean.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-debug-table">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_debug_table</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_debug_table</refname>
 <refpurpose>
     dump allocator state to dmesg
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mm_debug_table </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>const char * <parameter>prefix</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to dump
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>prefix</parameter></term>
   <listitem>
    <para>
     prefix to use for dumping to dmesg
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-mm-dump-table">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_dump_table</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_dump_table</refname>
 <refpurpose>
     dump allocator state to a seq_file
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mm_dump_table </function></funcdef>
   <paramdef>struct seq_file * <parameter>m</parameter></paramdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     seq_file to dump to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to dump
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- include/drm/drm_mm.h -->
<refentry id="API-drm-mm-node-allocated">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_node_allocated</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_node_allocated</refname>
 <refpurpose>
  checks whether a node is allocated
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mm_node_allocated </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     drm_mm_node to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers should use this helpers for proper encapusulation of drm_mm
   internals.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the <parameter>node</parameter> is allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-initialized">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_initialized</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_initialized</refname>
 <refpurpose>
     checks whether an allocator is initialized
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mm_initialized </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers should use this helpers for proper encapusulation of drm_mm
   internals.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the <parameter>mm</parameter> is initialized.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-hole-node-start">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_hole_node_start</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_hole_node_start</refname>
 <refpurpose>
     computes the start of the hole following <parameter>node</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u64 <function>drm_mm_hole_node_start </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>hole_node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hole_node</parameter></term>
   <listitem>
    <para>
     drm_mm_node which implicitly tracks the following hole
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is useful for driver-sepific debug dumpers. Otherwise drivers should not
   inspect holes themselves. Drivers must check first whether a hole indeed
   follows by looking at node-&gt;hole_follows.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Start of the subsequent hole.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-hole-node-end">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_hole_node_end</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_hole_node_end</refname>
 <refpurpose>
     computes the end of the hole following <parameter>node</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u64 <function>drm_mm_hole_node_end </function></funcdef>
   <paramdef>struct drm_mm_node * <parameter>hole_node</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>hole_node</parameter></term>
   <listitem>
    <para>
     drm_mm_node which implicitly tracks the following hole
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is useful for driver-sepific debug dumpers. Otherwise drivers should not
   inspect holes themselves. Drivers must check first whether a hole indeed
   follows by looking at node-&gt;hole_follows.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   End of the subsequent hole.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-for-each-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_for_each_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_for_each_node</refname>
 <refpurpose>
     iterator to walk over all allocated nodes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>drm_mm_for_each_node </function></funcdef>
   <paramdef> <parameter>entry</parameter></paramdef>
   <paramdef> <parameter>mm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     drm_mm_node structure to assign to in each iteration step
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to walk
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This iterator walks over all nodes in the range allocator. It is implemented
   with list_for_each, so not save against removal of elements.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-for-each-hole">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_for_each_hole</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_for_each_hole</refname>
 <refpurpose>
     iterator to walk over all holes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>drm_mm_for_each_hole </function></funcdef>
   <paramdef> <parameter>entry</parameter></paramdef>
   <paramdef> <parameter>mm</parameter></paramdef>
   <paramdef> <parameter>hole_start</parameter></paramdef>
   <paramdef> <parameter>hole_end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>entry</parameter></term>
   <listitem>
    <para>
     drm_mm_node used internally to track progress
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm allocator to walk
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hole_start</parameter></term>
   <listitem>
    <para>
     ulong variable to assign the hole start to on each iteration
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hole_end</parameter></term>
   <listitem>
    <para>
     ulong variable to assign the hole end to on each iteration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This iterator walks over all holes in the range allocator. It is implemented
   with list_for_each, so not save against removal of elements. <parameter>entry</parameter> is used
   internally and will not reflect a real drm_mm_node for the very first hole.
   Hence users of this iterator may not access it.
</para>
</refsect1>
<refsect1>
<title>Implementation Note</title>
<para>
   We need to inline list_for_each_entry in order to be able to set hole_start
   and hole_end on each iteration while keeping the macro sane.
   </para><para>

   The __drm_mm_for_each_hole version is similar, but with added support for
   going backwards.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-insert-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_insert_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_insert_node</refname>
 <refpurpose>
     search for space and insert <parameter>node</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mm_insert_node </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>enum drm_mm_search_flags <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to allocate from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     preallocate node to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags to fine-tune the allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a simplified version of <function>drm_mm_insert_node_generic</function> with <parameter>color</parameter> set
   to 0.
   </para><para>

   The preallocated node must be cleared to 0.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, -ENOSPC if there's no suitable hole.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mm-insert-node-in-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mm_insert_node_in_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mm_insert_node_in_range</refname>
 <refpurpose>
     ranged search for space and insert <parameter>node</parameter>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mm_insert_node_in_range </function></funcdef>
   <paramdef>struct drm_mm * <parameter>mm</parameter></paramdef>
   <paramdef>struct drm_mm_node * <parameter>node</parameter></paramdef>
   <paramdef>u64 <parameter>size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>u64 <parameter>start</parameter></paramdef>
   <paramdef>u64 <parameter>end</parameter></paramdef>
   <paramdef>enum drm_mm_search_flags <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mm</parameter></term>
   <listitem>
    <para>
     drm_mm to allocate from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>node</parameter></term>
   <listitem>
    <para>
     preallocate node to insert
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment of the allocation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start of the allowed range for this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     end of the allowed range for this node
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags to fine-tune the allocation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a simplified version of <function>drm_mm_insert_node_in_range_generic</function> with
   <parameter>color</parameter> set to 0.
   </para><para>

   The preallocated node must be cleared to 0.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, -ENOSPC if there's no suitable hole.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>CMA Helper Functions Reference</title>
<para>
   </para><para>
   The Contiguous Memory Allocator reserves a pool of memory at early boot
   that is used to service requests for large blocks of contiguous memory.
   </para><para>
   The DRM GEM/CMA helpers use this allocator as a means to provide buffer
   objects that are physically contiguous in memory. This is useful for
   display drivers that are unable to map scattered buffers via an IOMMU.
</para>

<!-- drivers/gpu/drm/drm_gem_cma_helper.c -->
<refentry id="API-drm-gem-cma-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_create</refname>
 <refpurpose>
  allocate an object with the given size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_gem_cma_object * <function>drm_gem_cma_create </function></funcdef>
   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drm</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of the object to allocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a CMA GEM object and allocates a contiguous chunk of
   memory as backing store. The backing memory has the writecombine attribute
   set.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A struct drm_gem_cma_object * on success or an <function>ERR_PTR</function>-encoded negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-free-object">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_free_object</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_free_object</refname>
 <refpurpose>
     free resources associated with a CMA GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_cma_free_object </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>gem_obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>gem_obj</parameter></term>
   <listitem>
    <para>
     GEM object to free
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function frees the backing memory of the CMA GEM object, cleans up the
   GEM object state and frees the memory used to store the object itself.
   Drivers using the CMA helpers should set this as their DRM driver's
   -&gt;<function>gem_free_object</function> callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-dumb-create-internal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_dumb_create_internal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_dumb_create_internal</refname>
 <refpurpose>
     create a dumb buffer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_cma_dumb_create_internal </function></funcdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
   <paramdef>struct drm_mode_create_dumb * <parameter>args</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     DRM file-private structure to create the dumb buffer for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drm</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     IOCTL data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This aligns the pitch and size arguments to the minimum required. This is
   an internal helper that can be wrapped by a driver to account for hardware
   with more specific alignment requirements. It should not be used directly
   as the -&gt;<function>dumb_create</function> callback in a DRM driver.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-dumb-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_dumb_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_dumb_create</refname>
 <refpurpose>
     create a dumb buffer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_cma_dumb_create </function></funcdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
   <paramdef>struct drm_mode_create_dumb * <parameter>args</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     DRM file-private structure to create the dumb buffer for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drm</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     IOCTL data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function computes the pitch of the dumb buffer and rounds it up to an
   integer number of bytes per pixel. Drivers for hardware that doesn't have
   any additional restrictions on the pitch can directly use this function as
   their -&gt;<function>dumb_create</function> callback.
   </para><para>

   For hardware with additional restrictions, drivers can adjust the fields
   set up by userspace and pass the IOCTL data along to the
   <function>drm_gem_cma_dumb_create_internal</function> function.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-dumb-map-offset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_dumb_map_offset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_dumb_map_offset</refname>
 <refpurpose>
     return the fake mmap offset for a CMA GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_cma_dumb_map_offset </function></funcdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
   <paramdef>struct drm_device * <parameter>drm</parameter></paramdef>
   <paramdef>u32 <parameter>handle</parameter></paramdef>
   <paramdef>u64 * <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     DRM file-private structure containing the GEM object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>drm</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handle</parameter></term>
   <listitem>
    <para>
     GEM object handle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     return location for the fake mmap offset
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function look up an object by its handle and returns the fake mmap
   offset associated with it. Drivers using the CMA helpers should set this
   as their DRM driver's -&gt;<function>dumb_map_offset</function> callback.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-mmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_mmap</refname>
 <refpurpose>
     memory-map a CMA GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_cma_mmap </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     file object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     VMA for the area to be mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function implements an augmented version of the GEM DRM file mmap
</para>
</refsect1>
<refsect1>
<title>operation for CMA objects</title>
<para>
   In addition to the usual GEM VMA setup it
   immediately faults in the entire object instead of using on-demaind
   faulting. Drivers which employ the CMA helpers should use this function
   as their -&gt;<function>mmap</function> handler in the DRM device file's file_operations
   structure.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-describe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_describe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_describe</refname>
 <refpurpose>
     describe a CMA GEM object for debugfs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_cma_describe </function></funcdef>
   <paramdef>struct drm_gem_cma_object * <parameter>cma_obj</parameter></paramdef>
   <paramdef>struct seq_file * <parameter>m</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cma_obj</parameter></term>
   <listitem>
    <para>
     CMA GEM object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     debugfs file handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used to dump a human-readable representation of the
   CMA GEM object into a synthetic file.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-prime-get-sg-table">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_prime_get_sg_table</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_prime_get_sg_table</refname>
 <refpurpose>
     provide a scatter/gather table of pinned pages for a CMA GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct sg_table * <function>drm_gem_cma_prime_get_sg_table </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function exports a scatter/gather table suitable for PRIME usage by
   calling the standard DMA mapping API. Drivers using the CMA helpers should
   set this as their DRM driver's -&gt;<function>gem_prime_get_sg_table</function> callback.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the scatter/gather table of pinned pages or NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-prime-import-sg-table">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_prime_import_sg_table</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_prime_import_sg_table</refname>
 <refpurpose>
     produce a CMA GEM object from another driver's scatter/gather table of pinned pages
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_gem_object * <function>drm_gem_cma_prime_import_sg_table </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct dma_buf_attachment * <parameter>attach</parameter></paramdef>
   <paramdef>struct sg_table * <parameter>sgt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device to import into
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>attach</parameter></term>
   <listitem>
    <para>
     DMA-BUF attachment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sgt</parameter></term>
   <listitem>
    <para>
     scatter/gather table of pinned pages
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function imports a scatter/gather table exported via DMA-BUF by
   another driver. Imported buffers must be physically contiguous in memory
   (i.e. the scatter/gather table must contain a single entry). Drivers that
   use the CMA helpers should set this as their DRM driver's
   -&gt;<function>gem_prime_import_sg_table</function> callback.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to a newly created GEM object or an ERR_PTR-encoded negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-prime-mmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_prime_mmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_prime_mmap</refname>
 <refpurpose>
     memory-map an exported CMA GEM object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_gem_cma_prime_mmap </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>struct vm_area_struct * <parameter>vma</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     VMA for the area to be mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function maps a buffer imported via DRM PRIME into a userspace
   process's address space. Drivers that use the CMA helpers should set this
   as their DRM driver's -&gt;<function>gem_prime_mmap</function> callback.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-prime-vmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_prime_vmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_prime_vmap</refname>
 <refpurpose>
     map a CMA GEM object into the kernel's virtual address space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void * <function>drm_gem_cma_prime_vmap </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function maps a buffer exported via DRM PRIME into the kernel's
   virtual address space. Since the CMA buffers are already mapped into the
   kernel virtual address space this simply returns the cached virtual
   address. Drivers using the CMA helpers should set this as their DRM
   driver's -&gt;<function>gem_prime_vmap</function> callback.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The kernel virtual address of the CMA GEM object's backing store.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gem-cma-prime-vunmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gem_cma_prime_vunmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gem_cma_prime_vunmap</refname>
 <refpurpose>
     unmap a CMA GEM object from the kernel's virtual address space
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_gem_cma_prime_vunmap </function></funcdef>
   <paramdef>struct drm_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>void * <parameter>vaddr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vaddr</parameter></term>
   <listitem>
    <para>
     kernel virtual address where the CMA GEM object was mapped
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function removes a buffer exported via DRM PRIME from the kernel's
   virtual address space. This is a no-op because CMA buffers cannot be
   unmapped from kernel space. Drivers using the CMA helpers should set this
   as their DRM driver's -&gt;<function>gem_prime_vunmap</function> callback.
</para>
</refsect1>
</refentry>

<!-- include/drm/drm_gem_cma_helper.h -->
<refentry id="API-struct-drm-gem-cma-object">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_gem_cma_object</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_gem_cma_object</refname>
 <refpurpose>
  GEM object backed by CMA memory allocations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_gem_cma_object {
  struct drm_gem_object base;
  dma_addr_t paddr;
  struct sg_table * sgt;
  void * vaddr;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>base</term>
      <listitem><para>
base GEM object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>paddr</term>
      <listitem><para>
physical address of the backing memory
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sgt</term>
      <listitem><para>
scatter/gather table for imported PRIME buffers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>vaddr</term>
      <listitem><para>
kernel virtual address of the backing memory
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

    </sect2>
  </sect1>

  <!-- Internals: mode setting -->

  <sect1 id="drm-mode-setting">
    <title>Mode Setting</title>
    <para>
      Drivers must initialize the mode setting core by calling
      <function>drm_mode_config_init</function> on the DRM device. The function
      initializes the <structname>drm_device</structname>
      <structfield>mode_config</structfield> field and never fails. Once done,
      mode configuration must be setup by initializing the following fields.
    </para>
    <itemizedlist>
      <listitem>
        <synopsis>int min_width, min_height;
int max_width, max_height;</synopsis>
        <para>
	  Minimum and maximum width and height of the frame buffers in pixel
	  units.
	</para>
      </listitem>
      <listitem>
        <synopsis>struct drm_mode_config_funcs *funcs;</synopsis>
	<para>Mode setting functions.</para>
      </listitem>
    </itemizedlist>
    <sect2>
      <title>Display Modes Function Reference</title>
<!-- include/drm/drm_modes.h -->
<refentry id="API-drm-mode-is-stereo">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_is_stereo</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_is_stereo</refname>
 <refpurpose>
  check for stereo mode flags
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mode_is_stereo </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     drm_display_mode to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the mode is one of the stereo modes (like side-by-side), false if
   not.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_modes.c -->
<refentry id="API-drm-mode-debug-printmodeline">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_debug_printmodeline</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_debug_printmodeline</refname>
 <refpurpose>
  print a mode to dmesg
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_debug_printmodeline </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to print
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Describe <parameter>mode</parameter> using DRM_DEBUG.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create</refname>
 <refpurpose>
     create a new display mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>drm_mode_create </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create a new, cleared drm_display_mode with kzalloc, allocate an ID for it
   and return it.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Pointer to new mode on success, NULL on error.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_destroy</refname>
 <refpurpose>
     remove a mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_destroy </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release <parameter>mode</parameter>'s unique ID, then free it <parameter>mode</parameter> structure itself using kfree.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-probed-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_probed_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_probed_add</refname>
 <refpurpose>
     add a mode to a connector's probed_mode list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_probed_add </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector the new mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add <parameter>mode</parameter> to <parameter>connector</parameter>'s probed_mode list for later use. This list should
   then in a second step get filtered and all the modes actually supported by
   the hardware moved to the <parameter>connector</parameter>'s modes list.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-cvt-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_cvt_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_cvt_mode</refname>
 <refpurpose>
     create a modeline based on the CVT algorithm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>drm_cvt_mode </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>hdisplay</parameter></paramdef>
   <paramdef>int <parameter>vdisplay</parameter></paramdef>
   <paramdef>int <parameter>vrefresh</parameter></paramdef>
   <paramdef>bool <parameter>reduced</parameter></paramdef>
   <paramdef>bool <parameter>interlaced</parameter></paramdef>
   <paramdef>bool <parameter>margins</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hdisplay</parameter></term>
   <listitem>
    <para>
     hdisplay size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdisplay</parameter></term>
   <listitem>
    <para>
     vdisplay size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vrefresh</parameter></term>
   <listitem>
    <para>
     vrefresh rate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>reduced</parameter></term>
   <listitem>
    <para>
     whether to use reduced blanking
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interlaced</parameter></term>
   <listitem>
    <para>
     whether to compute an interlaced mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>margins</parameter></term>
   <listitem>
    <para>
     whether to add margins (borders)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called to generate the modeline based on CVT algorithm
   according to the hdisplay, vdisplay, vrefresh.
   It is based from the VESA(TM) Coordinated Video Timing Generator by
   Graham Loveridge April 9, 2003 available at
</para>
</refsect1>
<refsect1>
<title>http</title>
<para>
   //www.elo.utfsm.cl/~elo212/docs/CVTd6r1.xls 
   </para><para>

   And it is copied from xf86CVTmode in xserver/hw/xfree86/modes/xf86cvt.c.
   What I have done is to translate it by using integer calculation.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The modeline based on the CVT algorithm stored in a drm_display_mode object.
   The display mode object is allocated with <function>drm_mode_create</function>. Returns NULL
   when no mode could be allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gtf-mode-complex">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gtf_mode_complex</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gtf_mode_complex</refname>
 <refpurpose>
     create the modeline based on the full GTF algorithm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>drm_gtf_mode_complex </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>hdisplay</parameter></paramdef>
   <paramdef>int <parameter>vdisplay</parameter></paramdef>
   <paramdef>int <parameter>vrefresh</parameter></paramdef>
   <paramdef>bool <parameter>interlaced</parameter></paramdef>
   <paramdef>int <parameter>margins</parameter></paramdef>
   <paramdef>int <parameter>GTF_M</parameter></paramdef>
   <paramdef>int <parameter>GTF_2C</parameter></paramdef>
   <paramdef>int <parameter>GTF_K</parameter></paramdef>
   <paramdef>int <parameter>GTF_2J</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hdisplay</parameter></term>
   <listitem>
    <para>
     hdisplay size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdisplay</parameter></term>
   <listitem>
    <para>
     vdisplay size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vrefresh</parameter></term>
   <listitem>
    <para>
     vrefresh rate.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interlaced</parameter></term>
   <listitem>
    <para>
     whether to compute an interlaced mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>margins</parameter></term>
   <listitem>
    <para>
     desired margin (borders) size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>GTF_M</parameter></term>
   <listitem>
    <para>
     extended GTF formula parameters
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>GTF_2C</parameter></term>
   <listitem>
    <para>
     extended GTF formula parameters
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>GTF_K</parameter></term>
   <listitem>
    <para>
     extended GTF formula parameters
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>GTF_2J</parameter></term>
   <listitem>
    <para>
     extended GTF formula parameters
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   GTF feature blocks specify C and J in multiples of 0.5, so we pass them
   in here multiplied by two.  For a C of 40, pass in 80.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The modeline based on the full GTF algorithm stored in a drm_display_mode object.
   The display mode object is allocated with <function>drm_mode_create</function>. Returns NULL
   when no mode could be allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-gtf-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_gtf_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_gtf_mode</refname>
 <refpurpose>
     create the modeline based on the GTF algorithm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>drm_gtf_mode </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>hdisplay</parameter></paramdef>
   <paramdef>int <parameter>vdisplay</parameter></paramdef>
   <paramdef>int <parameter>vrefresh</parameter></paramdef>
   <paramdef>bool <parameter>interlaced</parameter></paramdef>
   <paramdef>int <parameter>margins</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hdisplay</parameter></term>
   <listitem>
    <para>
     hdisplay size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdisplay</parameter></term>
   <listitem>
    <para>
     vdisplay size
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vrefresh</parameter></term>
   <listitem>
    <para>
     vrefresh rate.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>interlaced</parameter></term>
   <listitem>
    <para>
     whether to compute an interlaced mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>margins</parameter></term>
   <listitem>
    <para>
     desired margin (borders) size
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   return the modeline based on GTF algorithm
   </para><para>

   This function is to create the modeline based on the GTF algorithm.
</para>
</refsect1>
<refsect1>
<title>Generalized Timing Formula is derived from</title>
<para>
   GTF Spreadsheet by Andy Morrish (1/5/97)
</para>
</refsect1>
<refsect1>
<title>available at http</title>
<para>
   //www.vesa.org
   </para><para>

   And it is copied from the file of xserver/hw/xfree86/modes/xf86gtf.c.
   What I have done is to translate it by using integer calculation.
   I also refer to the function of fb_get_mode in the file of
   drivers/video/fbmon.c
</para>
</refsect1>
<refsect1>
<title>Standard GTF parameters</title>
<para>
   M = 600
   C = 40
   K = 128
   J = 20
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The modeline based on the GTF algorithm stored in a drm_display_mode object.
   The display mode object is allocated with <function>drm_mode_create</function>. Returns NULL
   when no mode could be allocated.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-display-mode-from-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_display_mode_from_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_display_mode_from_videomode</refname>
 <refpurpose>
     fill in <parameter>dmode</parameter> using <parameter>vm</parameter>,
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_display_mode_from_videomode </function></funcdef>
   <paramdef>const struct videomode * <parameter>vm</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>dmode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     videomode structure to use as source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmode</parameter></term>
   <listitem>
    <para>
     drm_display_mode structure to use as destination
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fills out <parameter>dmode</parameter> using the display mode specified in <parameter>vm</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-display-mode-to-videomode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_display_mode_to_videomode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_display_mode_to_videomode</refname>
 <refpurpose>
     fill in <parameter>vm</parameter> using <parameter>dmode</parameter>,
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_display_mode_to_videomode </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>dmode</parameter></paramdef>
   <paramdef>struct videomode * <parameter>vm</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dmode</parameter></term>
   <listitem>
    <para>
     drm_display_mode structure to use as source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     videomode structure to use as destination
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fills out <parameter>vm</parameter> using the display mode specified in <parameter>dmode</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-of-get-drm-display-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>of_get_drm_display_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>of_get_drm_display_mode</refname>
 <refpurpose>
     get a drm_display_mode from devicetree
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>of_get_drm_display_mode </function></funcdef>
   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>dmode</parameter></paramdef>
   <paramdef>int <parameter>index</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>np</parameter></term>
   <listitem>
    <para>
     device_node with the timing specification
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dmode</parameter></term>
   <listitem>
    <para>
     will be set to the return value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     index into the list of display timings in devicetree
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is expensive and should only be used, if only one mode is to be
   read from DT. To get multiple modes start with of_get_display_timings and
   work with that instead.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, a negative errno code when no of videomode node was found.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-set-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_set_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_set_name</refname>
 <refpurpose>
     set the name on a mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_set_name </function></funcdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     name will be set in this mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the name of <parameter>mode</parameter> to a standard format which is &lt;hdisplay&gt;x&lt;vdisplay&gt;
   with an optional 'i' suffix for interlaced modes.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-vrefresh">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_vrefresh</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_vrefresh</refname>
 <refpurpose>
     get the vrefresh of a mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_vrefresh </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   <parameter>modes</parameter>'s vrefresh rate in Hz, rounded to the nearest integer. Calculates the
   value first if it is not yet set.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-set-crtcinfo">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_set_crtcinfo</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_set_crtcinfo</refname>
 <refpurpose>
     set CRTC modesetting timing parameters
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_set_crtcinfo </function></funcdef>
   <paramdef>struct drm_display_mode * <parameter>p</parameter></paramdef>
   <paramdef>int <parameter>adjust_flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>p</parameter></term>
   <listitem>
    <para>
     mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adjust_flags</parameter></term>
   <listitem>
    <para>
     a combination of adjustment flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Setup the CRTC modesetting timing parameters for <parameter>p</parameter>, adjusting if necessary.
   </para><para>

   - The CRTC_INTERLACE_HALVE_V flag can be used to halve vertical timings of
   interlaced modes.
   - The CRTC_STEREO_DOUBLE flag can be used to compute the timings for
   buffers containing two eyes (only adjust the timings when needed, eg. for
   <quote>frame packing</quote> or <quote>side by side full</quote>).
   - The CRTC_NO_DBLSCAN and CRTC_NO_VSCAN flags request that adjustment *not*
   be performed for doublescan and vscan &gt; 1 modes respectively.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-copy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_copy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_copy</refname>
 <refpurpose>
     copy the mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_copy </function></funcdef>
   <paramdef>struct drm_display_mode * <parameter>dst</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>src</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     mode to overwrite
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     mode to copy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copy an existing mode into another mode, preserving the object id and
   list head of the destination mode.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-duplicate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_duplicate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_duplicate</refname>
 <refpurpose>
     allocate and duplicate an existing mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>drm_mode_duplicate </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device to allocate the duplicated mode for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to duplicate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Just allocate a new mode, copy the existing mode into it, and return
   a pointer to it.  Used to create new instances of established modes.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Pointer to duplicated mode on success, NULL on error.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-equal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_equal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_equal</refname>
 <refpurpose>
     test modes for equality
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mode_equal </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode1</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode1</parameter></term>
   <listitem>
    <para>
     first mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode2</parameter></term>
   <listitem>
    <para>
     second mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check to see if <parameter>mode1</parameter> and <parameter>mode2</parameter> are equivalent.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the modes are equal, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-equal-no-clocks-no-stereo">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_equal_no_clocks_no_stereo</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_equal_no_clocks_no_stereo</refname>
 <refpurpose>
     test modes for equality
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mode_equal_no_clocks_no_stereo </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode1</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode1</parameter></term>
   <listitem>
    <para>
     first mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode2</parameter></term>
   <listitem>
    <para>
     second mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check to see if <parameter>mode1</parameter> and <parameter>mode2</parameter> are equivalent, but
   don't check the pixel clocks nor the stereo layout.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the modes are equal, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-validate-basic">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_validate_basic</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_validate_basic</refname>
 <refpurpose>
     make sure the mode is somewhat sane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum drm_mode_status <function>drm_mode_validate_basic </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check that the mode timings are at least somewhat reasonable.
   Any hardware specific limits are left up for each driver to check.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The mode status
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-validate-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_validate_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_validate_size</refname>
 <refpurpose>
     make sure modes adhere to size constraints
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum drm_mode_status <function>drm_mode_validate_size </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>int <parameter>maxX</parameter></paramdef>
   <paramdef>int <parameter>maxY</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxX</parameter></term>
   <listitem>
    <para>
     maximum width
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxY</parameter></term>
   <listitem>
    <para>
     maximum height
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is a helper which can be used to validate modes against size
   limitations of the DRM device/connector. If a mode is too big its status
   member is updated with the appropriate validation failure code. The list
   itself is not changed.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The mode status
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-prune-invalid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_prune_invalid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_prune_invalid</refname>
 <refpurpose>
     remove invalid modes from mode list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_prune_invalid </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct list_head * <parameter>mode_list</parameter></paramdef>
   <paramdef>bool <parameter>verbose</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode_list</parameter></term>
   <listitem>
    <para>
     list of modes to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>verbose</parameter></term>
   <listitem>
    <para>
     be verbose about it
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper function can be used to prune a display mode list after
   validation has been completed. All modes who's status is not MODE_OK will be
   removed from the list, and if <parameter>verbose</parameter> the status code and mode name is also
   printed to dmesg.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-sort">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_sort</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_sort</refname>
 <refpurpose>
     sort mode list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_sort </function></funcdef>
   <paramdef>struct list_head * <parameter>mode_list</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode_list</parameter></term>
   <listitem>
    <para>
     list of drm_display_mode structures to sort
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sort <parameter>mode_list</parameter> by favorability, moving good modes to the head of the list.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-connector-list-update">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_connector_list_update</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_connector_list_update</refname>
 <refpurpose>
     update the mode list for the connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_connector_list_update </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>bool <parameter>merge_type_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     the connector to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>merge_type_bits</parameter></term>
   <listitem>
    <para>
     whether to merge or overwrite type bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This moves the modes from the <parameter>connector</parameter> probed_modes list
   to the actual mode list. It compares the probed mode against the current
   list and only adds different/new modes.
   </para><para>

   This is just a helper functions doesn't validate any modes itself and also
   doesn't prune any invalid modes. Callers need to do that themselves.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-parse-command-line-for-connector">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_parse_command_line_for_connector</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_parse_command_line_for_connector</refname>
 <refpurpose>
     parse command line modeline for connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_mode_parse_command_line_for_connector </function></funcdef>
   <paramdef>const char * <parameter>mode_option</parameter></paramdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_cmdline_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode_option</parameter></term>
   <listitem>
    <para>
     optional per connector mode option
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to parse modeline for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     preallocated drm_cmdline_mode structure to fill out
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This parses <parameter>mode_option</parameter> command line modeline for modes and options to
   configure the connector. If <parameter>mode_option</parameter> is NULL the default command line
   modeline in fb_mode_option will be parsed instead.
   </para><para>

   This uses the same parameters as the fb modedb.c, except for an extra
   force-enable, force-enable-digital and force-disable bit at the end:
   </para><para>

   &lt;xres&gt;x&lt;yres&gt;[M][R][-&lt;bpp&gt;][@&lt;refresh&gt;][i][m][eDd]
   </para><para>

   The intermediate drm_cmdline_mode structure is required to store additional
   options from the command line modline like the force-enable/disable flag.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if a valid modeline has been parsed, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-from-cmdline-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_from_cmdline_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_from_cmdline_mode</refname>
 <refpurpose>
     convert a command line modeline into a DRM display mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>drm_mode_create_from_cmdline_mode </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_cmdline_mode * <parameter>cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device to create the new mode for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     input command line modeline
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Pointer to converted mode on success, NULL on error.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Atomic Mode Setting Function Reference</title>
<!-- drivers/gpu/drm/drm_atomic.c -->
<refentry id="API-drm-atomic-state-default-release">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_state_default_release</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_state_default_release</refname>
 <refpurpose>
  release memory initialized by drm_atomic_state_init
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_state_default_release </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free all the memory allocated by drm_atomic_state_init.
   This is useful for drivers that subclass the atomic state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-state-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_state_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_state_init</refname>
 <refpurpose>
     init new atomic state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_state_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default implementation for filling in a new atomic state.
   This is useful for drivers that subclass the atomic state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-state-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_state_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_state_alloc</refname>
 <refpurpose>
     allocate atomic state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_atomic_state * <function>drm_atomic_state_alloc </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This allocates an empty atomic state to track updates.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-state-default-clear">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_state_default_clear</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_state_default_clear</refname>
 <refpurpose>
     clear base atomic state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_state_default_clear </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default implementation for clearing atomic state.
   This is useful for drivers that subclass the atomic state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-state-clear">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_state_clear</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_state_clear</refname>
 <refpurpose>
     clear state object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_state_clear </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When the w/w mutex algorithm detects a deadlock we need to back off and drop
   all locks. So someone else could sneak in and change the current modeset
   configuration. Which means that all the state assembled in <parameter>state</parameter> is no
   longer an atomic update to the current state, but to some arbitrary earlier
   state. Which could break assumptions the driver's -&gt;atomic_check likely
   relies on.
   </para><para>

   Hence we must clear all cached state and completely start over, using this
   function.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-state-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_state_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_state_free</refname>
 <refpurpose>
     free all memory for an atomic state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_state_free </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state to deallocate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This frees all memory associated with an atomic state, including all the
   per-object state for planes, crtcs and connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-get-crtc-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_get_crtc_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_get_crtc_state</refname>
 <refpurpose>
     get crtc state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_crtc_state * <function>drm_atomic_get_crtc_state </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     global atomic state object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     crtc to get state object for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the crtc state for the given crtc, allocating it if
   needed. It will also grab the relevant crtc lock to make sure that the state
   is consistent.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   </para><para>

   Either the allocated state or the error code encoded into the pointer. When
   the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   entire atomic sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-set-mode-for-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_set_mode_for_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_set_mode_for_crtc</refname>
 <refpurpose>
     set mode for CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_set_mode_for_crtc </function></funcdef>
   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the CRTC whose incoming state to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     kernel-internal mode to use for the CRTC, or NULL to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set a mode (originating from the kernel) on the desired CRTC state. Does
   not change any other state properties, including enable, active, or
   mode_changed.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure. Cannot return -EDEADLK.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-set-mode-prop-for-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_set_mode_prop_for_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_set_mode_prop_for_crtc</refname>
 <refpurpose>
     set mode for CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_set_mode_prop_for_crtc </function></funcdef>
   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_property_blob * <parameter>blob</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the CRTC whose incoming state to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>blob</parameter></term>
   <listitem>
    <para>
     pointer to blob property to use for mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set a mode (originating from a blob property) on the desired CRTC state.
   This function will take a reference on the blob property for the CRTC state,
   and release the reference held on the state's existing mode property, if any
   was set.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure. Cannot return -EDEADLK.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-crtc-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_crtc_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_crtc_set_property</refname>
 <refpurpose>
     set property on CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_crtc_set_property </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     the drm CRTC to set a property on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the state object to update with the new property value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     the property to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     the new property value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this instead of calling crtc-&gt;atomic_set_property directly.
   This function handles generic/core properties and calls out to
   driver's -&gt;<function>atomic_set_property</function> for driver properties.  To ensure
   consistent behavior you must call this function rather than the
   driver hook directly.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-get-plane-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_get_plane_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_get_plane_state</refname>
 <refpurpose>
     get plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_plane_state * <function>drm_atomic_get_plane_state </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     global atomic state object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to get state object for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the plane state for the given plane, allocating it if
   needed. It will also grab the relevant plane lock to make sure that the state
   is consistent.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   </para><para>

   Either the allocated state or the error code encoded into the pointer. When
   the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   entire atomic sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-plane-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_plane_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_plane_set_property</refname>
 <refpurpose>
     set property on plane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_plane_set_property </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     the drm plane to set a property on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the state object to update with the new property value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     the property to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     the new property value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this instead of calling plane-&gt;atomic_set_property directly.
   This function handles generic/core properties and calls out to
   driver's -&gt;<function>atomic_set_property</function> for driver properties.  To ensure
   consistent behavior you must call this function rather than the
   driver hook directly.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-get-connector-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_get_connector_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_get_connector_state</refname>
 <refpurpose>
     get connector state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_connector_state * <function>drm_atomic_get_connector_state </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     global atomic state object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to get state object for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns the connector state for the given connector,
   allocating it if needed. It will also grab the relevant connector lock to
   make sure that the state is consistent.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   </para><para>

   Either the allocated state or the error code encoded into the pointer. When
   the error is EDEADLK then the w/w mutex code has detected a deadlock and the
   entire atomic sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-connector-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_connector_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_connector_set_property</refname>
 <refpurpose>
     set property on connector.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_connector_set_property </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     the drm connector to set a property on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the state object to update with the new property value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     the property to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     the new property value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use this instead of calling connector-&gt;atomic_set_property directly.
   This function handles generic/core properties and calls out to
   driver's -&gt;<function>atomic_set_property</function> for driver properties.  To ensure
   consistent behavior you must call this function rather than the
   driver hook directly.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-set-crtc-for-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_set_crtc_for_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_set_crtc_for_plane</refname>
 <refpurpose>
     set crtc for plane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_set_crtc_for_plane </function></funcdef>
   <paramdef>struct drm_plane_state * <parameter>plane_state</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane_state</parameter></term>
   <listitem>
    <para>
     the plane whose incoming state to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     crtc to use for the plane
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Changing the assigned crtc for a plane requires us to grab the lock and state
   for the new crtc, as needed. This function takes care of all these details
   besides updating the pointer in the state object itself.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
   then the w/w mutex code has detected a deadlock and the entire atomic
   sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-set-fb-for-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_set_fb_for_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_set_fb_for_plane</refname>
 <refpurpose>
     set framebuffer for plane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_set_fb_for_plane </function></funcdef>
   <paramdef>struct drm_plane_state * <parameter>plane_state</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane_state</parameter></term>
   <listitem>
    <para>
     atomic state object for the plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     fb to use for the plane
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Changing the assigned framebuffer for a plane requires us to grab a reference
   to the new fb and drop the reference to the old fb, if there is one. This
   function takes care of all these details besides updating the pointer in the
   state object itself.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-set-crtc-for-connector">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_set_crtc_for_connector</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_set_crtc_for_connector</refname>
 <refpurpose>
     set crtc for connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_set_crtc_for_connector </function></funcdef>
   <paramdef>struct drm_connector_state * <parameter>conn_state</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>conn_state</parameter></term>
   <listitem>
    <para>
     atomic state object for the connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     crtc to use for the connector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Changing the assigned crtc for a connector requires us to grab the lock and
   state for the new crtc, as needed. This function takes care of all these
   details besides updating the pointer in the state object itself.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
   then the w/w mutex code has detected a deadlock and the entire atomic
   sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-add-affected-connectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_add_affected_connectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_add_affected_connectors</refname>
 <refpurpose>
     add connectors for crtc
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_add_affected_connectors </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM crtc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function walks the current configuration and adds all connectors
   currently using <parameter>crtc</parameter> to the atomic configuration <parameter>state</parameter>. Note that this
   function must acquire the connection mutex. This can potentially cause
   unneeded seralization if the update is just for the planes on one crtc. Hence
   drivers and helpers should only call this when really needed (e.g. when a
   full modeset needs to happen due to some change).
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
   then the w/w mutex code has detected a deadlock and the entire atomic
   sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-add-affected-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_add_affected_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_add_affected_planes</refname>
 <refpurpose>
     add planes for crtc
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_add_affected_planes </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM crtc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function walks the current configuration and adds all planes
   currently used by <parameter>crtc</parameter> to the atomic configuration <parameter>state</parameter>. This is useful
   when an atomic commit also needs to check all currently enabled plane on
   <parameter>crtc</parameter>, e.g. when changing the mode. It's also useful when re-enabling a CRTC
   to avoid special code to force-enable all planes.
   </para><para>

   Since acquiring a plane state will always also acquire the w/w mutex of the
   current CRTC for that plane (if there is any) adding all the plane states for
   a CRTC will not reduce parallism of atomic updates.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success or can fail with -EDEADLK or -ENOMEM. When the error is EDEADLK
   then the w/w mutex code has detected a deadlock and the entire atomic
   sequence must be restarted. All other errors are fatal.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-connectors-for-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_connectors_for_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_connectors_for_crtc</refname>
 <refpurpose>
     count number of connected outputs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_connectors_for_crtc </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM crtc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function counts all connectors which will be connected to <parameter>crtc</parameter>
   according to <parameter>state</parameter>. Useful to recompute the enable state for <parameter>crtc</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-legacy-backoff">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_legacy_backoff</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_legacy_backoff</refname>
 <refpurpose>
     locking backoff for legacy ioctls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_legacy_backoff </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function should be used by legacy entry points which don't understand
   -EDEADLK semantics. For simplicity this one will grab all modeset locks after
   the slowpath completed.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-check-only">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_check_only</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_check_only</refname>
 <refpurpose>
     check whether a given config would work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_check_only </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic configuration to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that this function can return -EDEADLK if the driver needed to acquire
   more locks but encountered a deadlock. The caller must then do the usual w/w
   backoff dance and restart. All other errors are fatal.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-commit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_commit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_commit</refname>
 <refpurpose>
     commit configuration atomically
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_commit </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic configuration to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that this function can return -EDEADLK if the driver needed to acquire
   more locks but encountered a deadlock. The caller must then do the usual w/w
   backoff dance and restart. All other errors are fatal.
   </para><para>

   Also note that on successful execution ownership of <parameter>state</parameter> is transferred
   from the caller of this function to the function itself. The caller must not
   free or in any other way access <parameter>state</parameter>. If the function fails then the caller
   must clean up <parameter>state</parameter> itself.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-async-commit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_async_commit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_async_commit</refname>
 <refpurpose>
     atomic<structname>async</structname> configuration commit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_async_commit </function></funcdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic configuration to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that this function can return -EDEADLK if the driver needed to acquire
   more locks but encountered a deadlock. The caller must then do the usual w/w
   backoff dance and restart. All other errors are fatal.
   </para><para>

   Also note that on successful execution ownership of <parameter>state</parameter> is transferred
   from the caller of this function to the function itself. The caller must not
   free or in any other way access <parameter>state</parameter>. If the function fails then the caller
   must clean up <parameter>state</parameter> itself.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-clean-old-fb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_clean_old_fb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_clean_old_fb</refname>
 <refpurpose>
     - Unset old_fb pointers and set plane-&gt;fb pointers.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_clean_old_fb </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>plane_mask</parameter></paramdef>
   <paramdef>int <parameter>ret</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device to check.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane_mask</parameter></term>
   <listitem>
    <para>
     plane mask for planes that were updated.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ret</parameter></term>
   <listitem>
    <para>
     return value, can be -EDEADLK for a retry.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Before doing an update plane-&gt;old_fb is set to plane-&gt;fb,
   but before dropping the locks old_fb needs to be set to NULL
   and plane-&gt;fb updated. This is a common operation for each
   atomic update, so this call is split off as a helper.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Frame Buffer Creation</title>
      <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev,
				     struct drm_file *file_priv,
				     struct drm_mode_fb_cmd2 *mode_cmd);</synopsis>
      <para>
        Frame buffers are abstract memory objects that provide a source of
        pixels to scanout to a CRTC. Applications explicitly request the
        creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and
        receive an opaque handle that can be passed to the KMS CRTC control,
        plane configuration and page flip functions.
      </para>
      <para>
        Frame buffers rely on the underneath memory manager for low-level memory
        operations. When creating a frame buffer applications pass a memory
        handle (or a list of memory handles for multi-planar formats) through
	the <parameter>drm_mode_fb_cmd2</parameter> argument. For drivers using
	GEM as their userspace buffer management interface this would be a GEM
	handle.  Drivers are however free to use their own backing storage object
	handles, e.g. vmwgfx directly exposes special TTM handles to userspace
	and so expects TTM handles in the create ioctl and not GEM handles.
      </para>
      <para>
        Drivers must first validate the requested frame buffer parameters passed
        through the mode_cmd argument. In particular this is where invalid
        sizes, pixel formats or pitches can be caught.
      </para>
      <para>
        If the parameters are deemed valid, drivers then create, initialize and
        return an instance of struct <structname>drm_framebuffer</structname>.
        If desired the instance can be embedded in a larger driver-specific
	structure. Drivers must fill its <structfield>width</structfield>,
	<structfield>height</structfield>, <structfield>pitches</structfield>,
        <structfield>offsets</structfield>, <structfield>depth</structfield>,
        <structfield>bits_per_pixel</structfield> and
        <structfield>pixel_format</structfield> fields from the values passed
        through the <parameter>drm_mode_fb_cmd2</parameter> argument. They
        should call the <function>drm_helper_mode_fill_fb_struct</function>
        helper function to do so.
      </para>

      <para>
	The initialization of the new framebuffer instance is finalized with a
	call to <function>drm_framebuffer_init</function> which takes a pointer
	to DRM frame buffer operations (struct
	<structname>drm_framebuffer_funcs</structname>). Note that this function
	publishes the framebuffer and so from this point on it can be accessed
	concurrently from other threads. Hence it must be the last step in the
	driver's framebuffer initialization sequence. Frame buffer operations
	are
        <itemizedlist>
          <listitem>
            <synopsis>int (*create_handle)(struct drm_framebuffer *fb,
		     struct drm_file *file_priv, unsigned int *handle);</synopsis>
            <para>
              Create a handle to the frame buffer underlying memory object. If
              the frame buffer uses a multi-plane format, the handle will
              reference the memory object associated with the first plane.
            </para>
            <para>
              Drivers call <function>drm_gem_handle_create</function> to create
              the handle.
            </para>
          </listitem>
          <listitem>
            <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis>
            <para>
              Destroy the frame buffer object and frees all associated
              resources. Drivers must call
              <function>drm_framebuffer_cleanup</function> to free resources
              allocated by the DRM core for the frame buffer object, and must
              make sure to unreference all memory objects associated with the
              frame buffer. Handles created by the
              <methodname>create_handle</methodname> operation are released by
              the DRM core.
            </para>
          </listitem>
          <listitem>
            <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer,
	     struct drm_file *file_priv, unsigned flags, unsigned color,
	     struct drm_clip_rect *clips, unsigned num_clips);</synopsis>
            <para>
              This optional operation notifies the driver that a region of the
              frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB
              ioctl call.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
	The lifetime of a drm framebuffer is controlled with a reference count,
	drivers can grab additional references with
	<function>drm_framebuffer_reference</function>and drop them
	again with <function>drm_framebuffer_unreference</function>. For
	driver-private framebuffers for which the last reference is never
	dropped (e.g. for the fbdev framebuffer when the struct
	<structname>drm_framebuffer</structname> is embedded into the fbdev
	helper struct) drivers can manually clean up a framebuffer at module
	unload time with
	<function>drm_framebuffer_unregister_private</function>.
      </para>
    </sect2>
    <sect2>
      <title>Dumb Buffer Objects</title>
      <para>
	The KMS API doesn't standardize backing storage object creation and
	leaves it to driver-specific ioctls. Furthermore actually creating a
	buffer object even for GEM-based drivers is done through a
	driver-specific ioctl - GEM only has a common userspace interface for
	sharing and destroying objects. While not an issue for full-fledged
	graphics stacks that include device-specific userspace components (in
	libdrm for instance), this limit makes DRM-based early boot graphics
	unnecessarily complex.
      </para>
      <para>
        Dumb objects partly alleviate the problem by providing a standard
        API to create dumb buffers suitable for scanout, which can then be used
        to create KMS frame buffers.
      </para>
      <para>
        To support dumb objects drivers must implement the
        <methodname>dumb_create</methodname>,
        <methodname>dumb_destroy</methodname> and
        <methodname>dumb_map_offset</methodname> operations.
      </para>
      <itemizedlist>
        <listitem>
          <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev,
                   struct drm_mode_create_dumb *args);</synopsis>
          <para>
            The <methodname>dumb_create</methodname> operation creates a driver
	    object (GEM or TTM handle) suitable for scanout based on the
	    width, height and depth from the struct
	    <structname>drm_mode_create_dumb</structname> argument. It fills the
	    argument's <structfield>handle</structfield>,
	    <structfield>pitch</structfield> and <structfield>size</structfield>
	    fields with a handle for the newly created object and its line
            pitch and size in bytes.
          </para>
        </listitem>
        <listitem>
          <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev,
                    uint32_t handle);</synopsis>
          <para>
            The <methodname>dumb_destroy</methodname> operation destroys a dumb
            object created by <methodname>dumb_create</methodname>.
          </para>
        </listitem>
        <listitem>
          <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev,
                       uint32_t handle, uint64_t *offset);</synopsis>
          <para>
            The <methodname>dumb_map_offset</methodname> operation associates an
            mmap fake offset with the object given by the handle and returns
            it. Drivers must use the
            <function>drm_gem_create_mmap_offset</function> function to
            associate the fake offset as described in
            <xref linkend="drm-gem-objects-mapping"/>.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        Note that dumb objects may not be used for gpu acceleration, as has been
	attempted on some ARM embedded platforms. Such drivers really must have
	a hardware-specific ioctl to allocate suitable buffer objects.
      </para>
    </sect2>
    <sect2>
      <title>Output Polling</title>
      <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis>
      <para>
        This operation notifies the driver that the status of one or more
        connectors has changed. Drivers that use the fb helper can just call the
        <function>drm_fb_helper_hotplug_event</function> function to handle this
        operation.
      </para>
    </sect2>
    <sect2>
      <title>Locking</title>
      <para>
        Beside some lookup structures with their own locking (which is hidden
	behind the interface functions) most of the modeset state is protected
	by the <code>dev-&lt;mode_config.lock</code> mutex and additionally
	per-crtc locks to allow cursor updates, pageflips and similar operations
	to occur concurrently with background tasks like output detection.
	Operations which cross domains like a full modeset always grab all
	locks. Drivers there need to protect resources shared between crtcs with
	additional locking. They also need to be careful to always grab the
	relevant crtc locks if a modset functions touches crtc state, e.g. for
	load detection (which does only grab the <code>mode_config.lock</code>
	to allow concurrent screen updates on live crtcs).
      </para>
    </sect2>
  </sect1>

  <!-- Internals: kms initialization and cleanup -->

  <sect1 id="drm-kms-init">
    <title>KMS Initialization and Cleanup</title>
    <para>
      A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders
      and connectors. KMS drivers must thus create and initialize all those
      objects at load time after initializing mode setting.
    </para>
    <sect2>
      <title>CRTCs (struct <structname>drm_crtc</structname>)</title>
      <para>
        A CRTC is an abstraction representing a part of the chip that contains a
	pointer to a scanout buffer. Therefore, the number of CRTCs available
	determines how many independent scanout buffers can be active at any
	given time. The CRTC structure contains several fields to support this:
	a pointer to some video memory (abstracted as a frame buffer object), a
	display mode, and an (x, y) offset into the video memory to support
	panning or configurations where one piece of video memory spans multiple
	CRTCs.
      </para>
      <sect3>
        <title>CRTC Initialization</title>
        <para>
          A KMS device must create and register at least one struct
          <structname>drm_crtc</structname> instance. The instance is allocated
          and zeroed by the driver, possibly as part of a larger structure, and
          registered with a call to <function>drm_crtc_init</function> with a
          pointer to CRTC functions.
        </para>
      </sect3>
      <sect3 id="drm-kms-crtcops">
        <title>CRTC Operations</title>
        <sect4>
          <title>Set Configuration</title>
          <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis>
          <para>
            Apply a new CRTC configuration to the device. The configuration
            specifies a CRTC, a frame buffer to scan out from, a (x,y) position in
            the frame buffer, a display mode and an array of connectors to drive
            with the CRTC if possible.
          </para>
          <para>
            If the frame buffer specified in the configuration is NULL, the driver
            must detach all encoders connected to the CRTC and all connectors
            attached to those encoders and disable them.
          </para>
          <para>
            This operation is called with the mode config lock held.
          </para>
          <note><para>
	    Note that the drm core has no notion of restoring the mode setting
	    state after resume, since all resume handling is in the full
	    responsibility of the driver. The common mode setting helper library
	    though provides a helper which can be used for this:
	    <function>drm_helper_resume_force_mode</function>.
          </para></note>
        </sect4>
        <sect4>
          <title>Page Flipping</title>
          <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb,
                   struct drm_pending_vblank_event *event);</synopsis>
          <para>
            Schedule a page flip to the given frame buffer for the CRTC. This
            operation is called with the mode config mutex held.
          </para>
          <para>
            Page flipping is a synchronization mechanism that replaces the frame
            buffer being scanned out by the CRTC with a new frame buffer during
            vertical blanking, avoiding tearing. When an application requests a page
            flip the DRM core verifies that the new frame buffer is large enough to
            be scanned out by  the CRTC in the currently configured mode and then
            calls the CRTC <methodname>page_flip</methodname> operation with a
            pointer to the new frame buffer.
          </para>
          <para>
            The <methodname>page_flip</methodname> operation schedules a page flip.
            Once any pending rendering targeting the new frame buffer has
            completed, the CRTC will be reprogrammed to display that frame buffer
            after the next vertical refresh. The operation must return immediately
            without waiting for rendering or page flip to complete and must block
            any new rendering to the frame buffer until the page flip completes.
          </para>
          <para>
            If a page flip can be successfully scheduled the driver must set the
            <code>drm_crtc-&gt;fb</code> field to the new framebuffer pointed to
            by <code>fb</code>. This is important so that the reference counting
            on framebuffers stays balanced.
          </para>
          <para>
            If a page flip is already pending, the
            <methodname>page_flip</methodname> operation must return
            -<errorname>EBUSY</errorname>.
          </para>
          <para>
            To synchronize page flip to vertical blanking the driver will likely
            need to enable vertical blanking interrupts. It should call
            <function>drm_vblank_get</function> for that purpose, and call
            <function>drm_vblank_put</function> after the page flip completes.
          </para>
          <para>
            If the application has requested to be notified when page flip completes
            the <methodname>page_flip</methodname> operation will be called with a
            non-NULL <parameter>event</parameter> argument pointing to a
            <structname>drm_pending_vblank_event</structname> instance. Upon page
            flip completion the driver must call <methodname>drm_send_vblank_event</methodname>
            to fill in the event and send to wake up any waiting processes.
            This can be performed with
            <programlisting><![CDATA[
            spin_lock_irqsave(&dev->event_lock, flags);
            ...
            drm_send_vblank_event(dev, pipe, event);
            spin_unlock_irqrestore(&dev->event_lock, flags);
            ]]></programlisting>
          </para>
          <note><para>
            FIXME: Could drivers that don't need to wait for rendering to complete
            just add the event to <literal>dev-&gt;vblank_event_list</literal> and
            let the DRM core handle everything, as for "normal" vertical blanking
            events?
          </para></note>
          <para>
            While waiting for the page flip to complete, the
            <literal>event-&gt;base.link</literal> list head can be used freely by
            the driver to store the pending event in a driver-specific list.
          </para>
          <para>
            If the file handle is closed before the event is signaled, drivers must
            take care to destroy the event in their
            <methodname>preclose</methodname> operation (and, if needed, call
            <function>drm_vblank_put</function>).
          </para>
        </sect4>
        <sect4>
          <title>Miscellaneous</title>
          <itemizedlist>
            <listitem>
              <synopsis>void (*set_property)(struct drm_crtc *crtc,
                     struct drm_property *property, uint64_t value);</synopsis>
              <para>
                Set the value of the given CRTC property to
                <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
                for more information about properties.
              </para>
            </listitem>
            <listitem>
              <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,
                        uint32_t start, uint32_t size);</synopsis>
              <para>
                Apply a gamma table to the device. The operation is optional.
              </para>
            </listitem>
            <listitem>
              <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis>
              <para>
                Destroy the CRTC when not needed anymore. See
                <xref linkend="drm-kms-init"/>.
              </para>
            </listitem>
          </itemizedlist>
        </sect4>
      </sect3>
    </sect2>
    <sect2>
      <title>Planes (struct <structname>drm_plane</structname>)</title>
      <para>
        A plane represents an image source that can be blended with or overlayed
	on top of a CRTC during the scanout process. Planes are associated with
	a frame buffer to crop a portion of the image memory (source) and
	optionally scale it to a destination size. The result is then blended
	with or overlayed on top of a CRTC.
      </para>
      <para>
      The DRM core recognizes three types of planes:
      <itemizedlist>
        <listitem>
        DRM_PLANE_TYPE_PRIMARY represents a "main" plane for a CRTC.  Primary
        planes are the planes operated upon by CRTC modesetting and flipping
        operations described in <xref linkend="drm-kms-crtcops"/>.
        </listitem>
        <listitem>
        DRM_PLANE_TYPE_CURSOR represents a "cursor" plane for a CRTC.  Cursor
        planes are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and
        DRM_IOCTL_MODE_CURSOR2 ioctls.
        </listitem>
        <listitem>
        DRM_PLANE_TYPE_OVERLAY represents all non-primary, non-cursor planes.
        Some drivers refer to these types of planes as "sprites" internally.
        </listitem>
      </itemizedlist>
      For compatibility with legacy userspace, only overlay planes are made
      available to userspace by default.  Userspace clients may set the
      DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that
      they wish to receive a universal plane list containing all plane types.
      </para>
      <sect3>
        <title>Plane Initialization</title>
        <para>
          To create a plane, a KMS drivers allocates and
          zeroes an instances of struct <structname>drm_plane</structname>
          (possibly as part of a larger structure) and registers it with a call
          to <function>drm_universal_plane_init</function>. The function takes a bitmask
          of the CRTCs that can be associated with the plane, a pointer to the
          plane functions, a list of format supported formats, and the type of
          plane (primary, cursor, or overlay) being initialized.
        </para>
        <para>
          Cursor and overlay planes are optional.  All drivers should provide
          one primary plane per CRTC (although this requirement may change in
          the future); drivers that do not wish to provide special handling for
          primary planes may make use of the helper functions described in
          <xref linkend="drm-kms-planehelpers"/> to create and register a
          primary plane with standard capabilities.
        </para>
      </sect3>
      <sect3>
        <title>Plane Operations</title>
        <itemizedlist>
          <listitem>
            <synopsis>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);</synopsis>
            <para>
              Enable and configure the plane to use the given CRTC and frame buffer.
            </para>
            <para>
              The source rectangle in frame buffer memory coordinates is given by
              the <parameter>src_x</parameter>, <parameter>src_y</parameter>,
              <parameter>src_w</parameter> and <parameter>src_h</parameter>
              parameters (as 16.16 fixed point values). Devices that don't support
              subpixel plane coordinates can ignore the fractional part.
            </para>
            <para>
              The destination rectangle in CRTC coordinates is given by the
              <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>,
              <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter>
              parameters (as integer values). Devices scale the source rectangle to
              the destination rectangle. If scaling is not supported, and the source
              rectangle size doesn't match the destination rectangle size, the
              driver must return a -<errorname>EINVAL</errorname> error.
            </para>
          </listitem>
          <listitem>
            <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis>
            <para>
              Disable the plane. The DRM core calls this method in response to a
              DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0.
              Disabled planes must not be processed by the CRTC.
            </para>
          </listitem>
          <listitem>
            <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis>
            <para>
              Destroy the plane when not needed anymore. See
              <xref linkend="drm-kms-init"/>.
            </para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>
    <sect2>
      <title>Encoders (struct <structname>drm_encoder</structname>)</title>
      <para>
        An encoder takes pixel data from a CRTC and converts it to a format
	suitable for any attached connectors. On some devices, it may be
	possible to have a CRTC send data to more than one encoder. In that
	case, both encoders would receive data from the same scanout buffer,
	resulting in a "cloned" display configuration across the connectors
	attached to each encoder.
      </para>
      <sect3>
        <title>Encoder Initialization</title>
        <para>
          As for CRTCs, a KMS driver must create, initialize and register at
          least one struct <structname>drm_encoder</structname> instance. The
          instance is allocated and zeroed by the driver, possibly as part of a
          larger structure.
        </para>
        <para>
          Drivers must initialize the struct <structname>drm_encoder</structname>
          <structfield>possible_crtcs</structfield> and
          <structfield>possible_clones</structfield> fields before registering the
          encoder. Both fields are bitmasks of respectively the CRTCs that the
          encoder can be connected to, and sibling encoders candidate for cloning.
        </para>
        <para>
          After being initialized, the encoder must be registered with a call to
          <function>drm_encoder_init</function>. The function takes a pointer to
          the encoder functions and an encoder type. Supported types are
          <itemizedlist>
            <listitem>
              DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A
              </listitem>
            <listitem>
              DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort
            </listitem>
            <listitem>
              DRM_MODE_ENCODER_LVDS for display panels
            </listitem>
            <listitem>
              DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component,
              SCART)
            </listitem>
            <listitem>
              DRM_MODE_ENCODER_VIRTUAL for virtual machine displays
            </listitem>
          </itemizedlist>
        </para>
        <para>
          Encoders must be attached to a CRTC to be used. DRM drivers leave
          encoders unattached at initialization time. Applications (or the fbdev
          compatibility layer when implemented) are responsible for attaching the
          encoders they want to use to a CRTC.
        </para>
      </sect3>
      <sect3>
        <title>Encoder Operations</title>
        <itemizedlist>
          <listitem>
            <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis>
            <para>
              Called to destroy the encoder when not needed anymore. See
              <xref linkend="drm-kms-init"/>.
            </para>
          </listitem>
          <listitem>
            <synopsis>void (*set_property)(struct drm_plane *plane,
                     struct drm_property *property, uint64_t value);</synopsis>
            <para>
              Set the value of the given plane property to
              <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
              for more information about properties.
            </para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>
    <sect2>
      <title>Connectors (struct <structname>drm_connector</structname>)</title>
      <para>
        A connector is the final destination for pixel data on a device, and
	usually connects directly to an external display device like a monitor
	or laptop panel. A connector can only be attached to one encoder at a
	time. The connector is also the structure where information about the
	attached display is kept, so it contains fields for display data, EDID
	data, DPMS &amp; connection status, and information about modes
	supported on the attached displays.
      </para>
      <sect3>
        <title>Connector Initialization</title>
        <para>
          Finally a KMS driver must create, initialize, register and attach at
          least one struct <structname>drm_connector</structname> instance. The
          instance is created as other KMS objects and initialized by setting the
          following fields.
        </para>
        <variablelist>
          <varlistentry>
            <term><structfield>interlace_allowed</structfield></term>
            <listitem><para>
              Whether the connector can handle interlaced modes.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term><structfield>doublescan_allowed</structfield></term>
            <listitem><para>
              Whether the connector can handle doublescan.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term><structfield>display_info
            </structfield></term>
            <listitem><para>
              Display information is filled from EDID information when a display
              is detected. For non hot-pluggable displays such as flat panels in
              embedded systems, the driver should initialize the
              <structfield>display_info</structfield>.<structfield>width_mm</structfield>
              and
              <structfield>display_info</structfield>.<structfield>height_mm</structfield>
              fields with the physical size of the display.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term id="drm-kms-connector-polled"><structfield>polled</structfield></term>
            <listitem><para>
              Connector polling mode, a combination of
              <variablelist>
                <varlistentry>
                  <term>DRM_CONNECTOR_POLL_HPD</term>
                  <listitem><para>
                    The connector generates hotplug events and doesn't need to be
                    periodically polled. The CONNECT and DISCONNECT flags must not
                    be set together with the HPD flag.
                  </para></listitem>
                </varlistentry>
                <varlistentry>
                  <term>DRM_CONNECTOR_POLL_CONNECT</term>
                  <listitem><para>
                    Periodically poll the connector for connection.
                  </para></listitem>
                </varlistentry>
                <varlistentry>
                  <term>DRM_CONNECTOR_POLL_DISCONNECT</term>
                  <listitem><para>
                    Periodically poll the connector for disconnection.
                  </para></listitem>
                </varlistentry>
              </variablelist>
              Set to 0 for connectors that don't support connection status
              discovery.
            </para></listitem>
          </varlistentry>
        </variablelist>
        <para>
          The connector is then registered with a call to
          <function>drm_connector_init</function> with a pointer to the connector
          functions and a connector type, and exposed through sysfs with a call to
          <function>drm_connector_register</function>.
        </para>
        <para>
          Supported connector types are
          <itemizedlist>
            <listitem>DRM_MODE_CONNECTOR_VGA</listitem>
            <listitem>DRM_MODE_CONNECTOR_DVII</listitem>
            <listitem>DRM_MODE_CONNECTOR_DVID</listitem>
            <listitem>DRM_MODE_CONNECTOR_DVIA</listitem>
            <listitem>DRM_MODE_CONNECTOR_Composite</listitem>
            <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem>
            <listitem>DRM_MODE_CONNECTOR_LVDS</listitem>
            <listitem>DRM_MODE_CONNECTOR_Component</listitem>
            <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem>
            <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem>
            <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem>
            <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem>
            <listitem>DRM_MODE_CONNECTOR_TV</listitem>
            <listitem>DRM_MODE_CONNECTOR_eDP</listitem>
            <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem>
          </itemizedlist>
        </para>
        <para>
          Connectors must be attached to an encoder to be used. For devices that
          map connectors to encoders 1:1, the connector should be attached at
          initialization time with a call to
          <function>drm_mode_connector_attach_encoder</function>. The driver must
          also set the <structname>drm_connector</structname>
          <structfield>encoder</structfield> field to point to the attached
          encoder.
        </para>
        <para>
          Finally, drivers must initialize the connectors state change detection
          with a call to <function>drm_kms_helper_poll_init</function>. If at
          least one connector is pollable but can't generate hotplug interrupts
          (indicated by the DRM_CONNECTOR_POLL_CONNECT and
          DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will
          automatically be queued to periodically poll for changes. Connectors
          that can generate hotplug interrupts must be marked with the
          DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must
          call <function>drm_helper_hpd_irq_event</function>. The function will
          queue a delayed work to check the state of all connectors, but no
          periodic polling will be done.
        </para>
      </sect3>
      <sect3>
        <title>Connector Operations</title>
        <note><para>
          Unless otherwise state, all operations are mandatory.
        </para></note>
        <sect4>
          <title>DPMS</title>
          <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis>
          <para>
            The DPMS operation sets the power state of a connector. The mode
            argument is one of
            <itemizedlist>
              <listitem><para>DRM_MODE_DPMS_ON</para></listitem>
              <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem>
              <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem>
              <listitem><para>DRM_MODE_DPMS_OFF</para></listitem>
            </itemizedlist>
          </para>
          <para>
            In all but DPMS_ON mode the encoder to which the connector is attached
            should put the display in low-power mode by driving its signals
            appropriately. If more than one connector is attached to the encoder
            care should be taken not to change the power state of other displays as
            a side effect. Low-power mode should be propagated to the encoders and
            CRTCs when all related connectors are put in low-power mode.
          </para>
        </sect4>
        <sect4>
          <title>Modes</title>
          <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width,
                      uint32_t max_height);</synopsis>
          <para>
            Fill the mode list with all supported modes for the connector. If the
            <parameter>max_width</parameter> and <parameter>max_height</parameter>
            arguments are non-zero, the implementation must ignore all modes wider
            than <parameter>max_width</parameter> or higher than
            <parameter>max_height</parameter>.
          </para>
          <para>
            The connector must also fill in this operation its
            <structfield>display_info</structfield>
            <structfield>width_mm</structfield> and
            <structfield>height_mm</structfield> fields with the connected display
            physical size in millimeters. The fields should be set to 0 if the value
            isn't known or is not applicable (for instance for projector devices).
          </para>
        </sect4>
        <sect4>
          <title>Connection Status</title>
          <para>
            The connection status is updated through polling or hotplug events when
            supported (see <xref linkend="drm-kms-connector-polled"/>). The status
            value is reported to userspace through ioctls and must not be used
            inside the driver, as it only gets initialized by a call to
            <function>drm_mode_getconnector</function> from userspace.
          </para>
          <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector,
                                        bool force);</synopsis>
          <para>
            Check to see if anything is attached to the connector. The
            <parameter>force</parameter> parameter is set to false whilst polling or
            to true when checking the connector due to user request.
            <parameter>force</parameter> can be used by the driver to avoid
            expensive, destructive operations during automated probing.
          </para>
          <para>
            Return connector_status_connected if something is connected to the
            connector, connector_status_disconnected if nothing is connected and
            connector_status_unknown if the connection state isn't known.
          </para>
          <para>
            Drivers should only return connector_status_connected if the connection
            status has really been probed as connected. Connectors that can't detect
            the connection status, or failed connection status probes, should return
            connector_status_unknown.
          </para>
        </sect4>
        <sect4>
          <title>Miscellaneous</title>
          <itemizedlist>
            <listitem>
              <synopsis>void (*set_property)(struct drm_connector *connector,
                     struct drm_property *property, uint64_t value);</synopsis>
              <para>
                Set the value of the given connector property to
                <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/>
                for more information about properties.
              </para>
            </listitem>
            <listitem>
              <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis>
              <para>
                Destroy the connector when not needed anymore. See
                <xref linkend="drm-kms-init"/>.
              </para>
            </listitem>
          </itemizedlist>
        </sect4>
      </sect3>
    </sect2>
    <sect2>
      <title>Cleanup</title>
      <para>
        The DRM core manages its objects' lifetime. When an object is not needed
	anymore the core calls its destroy function, which must clean up and
	free every resource allocated for the object. Every
	<function>drm_*_init</function> call must be matched with a
	corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs
	(<function>drm_crtc_cleanup</function>), planes
	(<function>drm_plane_cleanup</function>), encoders
	(<function>drm_encoder_cleanup</function>) and connectors
	(<function>drm_connector_cleanup</function>). Furthermore, connectors
	that have been added to sysfs must be removed by a call to
	<function>drm_connector_unregister</function> before calling
	<function>drm_connector_cleanup</function>.
      </para>
      <para>
        Connectors state change detection must be cleanup up with a call to
	<function>drm_kms_helper_poll_fini</function>.
      </para>
    </sect2>
    <sect2>
      <title>Output discovery and initialization example</title>
      <programlisting><![CDATA[
void intel_crt_init(struct drm_device *dev)
{
	struct drm_connector *connector;
	struct intel_output *intel_output;

	intel_output = kzalloc(sizeof(struct intel_output), GFP_KERNEL);
	if (!intel_output)
		return;

	connector = &intel_output->base;
	drm_connector_init(dev, &intel_output->base,
			   &intel_crt_connector_funcs, DRM_MODE_CONNECTOR_VGA);

	drm_encoder_init(dev, &intel_output->enc, &intel_crt_enc_funcs,
			 DRM_MODE_ENCODER_DAC);

	drm_mode_connector_attach_encoder(&intel_output->base,
					  &intel_output->enc);

	/* Set up the DDC bus. */
	intel_output->ddc_bus = intel_i2c_create(dev, GPIOA, "CRTDDC_A");
	if (!intel_output->ddc_bus) {
		dev_printk(KERN_ERR, &dev->pdev->dev, "DDC bus registration "
			   "failed.\n");
		return;
	}

	intel_output->type = INTEL_OUTPUT_ANALOG;
	connector->interlace_allowed = 0;
	connector->doublescan_allowed = 0;

	drm_encoder_helper_add(&intel_output->enc, &intel_crt_helper_funcs);
	drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs);

	drm_connector_register(connector);
}]]></programlisting>
      <para>
        In the example above (taken from the i915 driver), a CRTC, connector and
        encoder combination is created. A device-specific i2c bus is also
        created for fetching EDID data and performing monitor detection. Once
        the process is complete, the new connector is registered with sysfs to
        make its properties available to applications.
      </para>
    </sect2>
    <sect2>
      <title>KMS API Functions</title>
<!-- drivers/gpu/drm/drm_crtc.c -->
<refentry id="API-drm-get-connector-status-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_get_connector_status_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_get_connector_status_name</refname>
 <refpurpose>
  return a string for connector status
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>drm_get_connector_status_name </function></funcdef>
   <paramdef>enum drm_connector_status <parameter>status</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>status</parameter></term>
   <listitem>
    <para>
     connector status to compute name of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   In contrast to the other drm_get_*_name functions this one here returns a
   const pointer and hence is threadsafe.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-get-subpixel-order-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_get_subpixel_order_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_get_subpixel_order_name</refname>
 <refpurpose>
     return a string for a given subpixel enum
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>drm_get_subpixel_order_name </function></funcdef>
   <paramdef>enum subpixel_order <parameter>order</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>order</parameter></term>
   <listitem>
    <para>
     enum of subpixel_order
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note you could abuse this and return something out of bounds, but that
   would be a caller error.  No unscrubbed user data should make it here.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-get-format-name">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_get_format_name</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_get_format_name</refname>
 <refpurpose>
     return a string for drm fourcc format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>const char * <function>drm_get_format_name </function></funcdef>
   <paramdef>uint32_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     format to compute name of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that the buffer used by this function is globally shared and owned by
   the function itself.
</para>
</refsect1>
<refsect1>
<title>FIXME</title>
<para>
   This isn't really multithreading safe.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-object-find">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_object_find</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_object_find</refname>
 <refpurpose>
     look up a drm object with static lifetime
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_mode_object * <function>drm_mode_object_find </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>uint32_t <parameter>id</parameter></paramdef>
   <paramdef>uint32_t <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     id of the mode object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of the mode object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that framebuffers cannot be looked up with this functions - since those
   are reference counted, they need special treatment.  Even with
   DRM_MODE_OBJECT_ANY (although that will simply return NULL
   rather than <function>WARN_ON</function>).
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_init</refname>
 <refpurpose>
     initialize a framebuffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_framebuffer_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>const struct drm_framebuffer_funcs * <parameter>funcs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to be initialized
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     ... with these functions
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates an ID for the framebuffer's parent mode object, sets its mode
   functions &amp; device file and adds it to the master fd list.
</para>
</refsect1>
<refsect1>
<title>IMPORTANT</title>
<para>
   This functions publishes the fb and makes it available for concurrent access
   by other users. Which means by this point the fb _must_ be fully set up -
   since all the fb attributes are invariant over its lifetime, no further
   locking but only correct reference counting is required.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-lookup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_lookup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_lookup</refname>
 <refpurpose>
     look up a drm framebuffer and grab a reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_framebuffer * <function>drm_framebuffer_lookup </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>uint32_t <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     id of the fb object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If successful, this grabs an additional reference to the framebuffer -
   callers need to make sure to eventually unreference the returned framebuffer
   again, using <parameter>drm_framebuffer_unreference</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-unreference">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_unreference</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_unreference</refname>
 <refpurpose>
     unref a framebuffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_framebuffer_unreference </function></funcdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to unref
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions decrements the fb's refcount and frees it if it drops to zero.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-reference">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_reference</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_reference</refname>
 <refpurpose>
     incr the fb refcnt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_framebuffer_reference </function></funcdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions increments the fb's refcount.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-unregister-private">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_unregister_private</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_unregister_private</refname>
 <refpurpose>
     unregister a private fb from the lookup idr
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_framebuffer_unregister_private </function></funcdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     fb to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers need to call this when cleaning up driver-private framebuffers, e.g.
   those used for fbdev. Note that the caller must hold a reference of it's own,
   i.e. the object may not be destroyed through this call (since it'll lead to a
   locking inversion).
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_cleanup</refname>
 <refpurpose>
     remove a framebuffer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_framebuffer_cleanup </function></funcdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Cleanup framebuffer. This function is intended to be used from the drivers
   -&gt;destroy callback. It can also be used to clean up driver private
   framebuffers embedded into a larger structure.
   </para><para>

   Note that this function does not remove the fb from active usuage - if it is
   still used anywhere, hilarity can ensue since userspace could call getfb on
   the id and get back -EINVAL. Obviously no concern at driver unload time.
   </para><para>

   Also, the framebuffer will not be removed from the lookup idr - for
   user-created framebuffers this will happen in in the rmfb ioctl. For
   driver-private objects (e.g. for fbdev) drivers need to explicitly call
   drm_framebuffer_unregister_private.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-framebuffer-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_framebuffer_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_framebuffer_remove</refname>
 <refpurpose>
     remove and unreference a framebuffer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_framebuffer_remove </function></funcdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to remove
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scans all the CRTCs and planes in <parameter>dev</parameter>'s mode_config.  If they're
   using <parameter>fb</parameter>, removes it, setting it to NULL. Then drops the reference to the
   passed-in framebuffer. Might take the modeset locks.
   </para><para>

   Note that this function optimizes the cleanup away if the caller holds the
   last reference to the framebuffer. It is also guaranteed to not take the
   modeset locks in this case.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-init-with-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_init_with_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_init_with_planes</refname>
 <refpurpose>
     Initialise a new CRTC object with specified primary and cursor planes.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_crtc_init_with_planes </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_plane * <parameter>primary</parameter></paramdef>
   <paramdef>struct drm_plane * <parameter>cursor</parameter></paramdef>
   <paramdef>const struct drm_crtc_funcs * <parameter>funcs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC object to init
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>primary</parameter></term>
   <listitem>
    <para>
     Primary plane for CRTC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cursor</parameter></term>
   <listitem>
    <para>
     Cursor plane for CRTC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     callbacks for the new CRTC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Inits a new object created as base part of a driver crtc object.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_cleanup</refname>
 <refpurpose>
     Clean up the core crtc usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_cleanup </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function cleans up <parameter>crtc</parameter> and removes it from the DRM mode setting
   core. Note that the function does *not* free the crtc structure itself,
   this is the responsibility of the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-index">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_index</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_index</refname>
 <refpurpose>
     find the index of a registered CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>drm_crtc_index </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC to find index for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a registered CRTC, return the index of that CRTC within a DRM
   device's list of CRTCs.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-display-info-set-bus-formats">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_display_info_set_bus_formats</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_display_info_set_bus_formats</refname>
 <refpurpose>
     set the supported bus formats
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_display_info_set_bus_formats </function></funcdef>
   <paramdef>struct drm_display_info * <parameter>info</parameter></paramdef>
   <paramdef>const u32 * <parameter>formats</parameter></paramdef>
   <paramdef>unsigned int <parameter>num_formats</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     display info to store bus formats in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>formats</parameter></term>
   <listitem>
    <para>
     array containing the supported bus formats
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_formats</parameter></term>
   <listitem>
    <para>
     the number of entries in the fmts array
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Store the supported bus formats in display info structure.
   See MEDIA_BUS_FMT_* definitions in include/uapi/linux/media-bus-format.h for
   a full list of available formats.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-connector-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_connector_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_connector_init</refname>
 <refpurpose>
     Init a preallocated connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_connector_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>const struct drm_connector_funcs * <parameter>funcs</parameter></paramdef>
   <paramdef>int <parameter>connector_type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     the connector to init
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     callbacks for this connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>connector_type</parameter></term>
   <listitem>
    <para>
     user visible type of the connector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialises a preallocated connector. Connectors should be
   subclassed as part of driver connector objects.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-connector-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_connector_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_connector_cleanup</refname>
 <refpurpose>
     cleans up an initialised connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_connector_cleanup </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Cleans up the connector but doesn't free the object.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-connector-index">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_connector_index</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_connector_index</refname>
 <refpurpose>
     find the index of a registered connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>drm_connector_index </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to find index for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a registered connector, return the index of that connector within a DRM
   device's list of connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-connector-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_connector_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_connector_register</refname>
 <refpurpose>
     register a connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_connector_register </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     the connector to register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register userspace interfaces for a connector
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-connector-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_connector_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_connector_unregister</refname>
 <refpurpose>
     unregister a connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_connector_unregister </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     the connector to unregister
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister userspace interfaces for a connector
</para>
</refsect1>
</refentry>

<refentry id="API-drm-connector-unplug-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_connector_unplug_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_connector_unplug_all</refname>
 <refpurpose>
     unregister connector userspace interfaces
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_connector_unplug_all </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function unregisters all connector userspace interfaces in sysfs. Should
   be call when the device is disconnected, e.g. from an usb driver's
   -&gt;disconnect callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-encoder-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_encoder_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_encoder_init</refname>
 <refpurpose>
     Init a preallocated encoder
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_encoder_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
   <paramdef>const struct drm_encoder_funcs * <parameter>funcs</parameter></paramdef>
   <paramdef>int <parameter>encoder_type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>encoder</parameter></term>
   <listitem>
    <para>
     the encoder to init
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     callbacks for this encoder
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>encoder_type</parameter></term>
   <listitem>
    <para>
     user visible type of the encoder
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialises a preallocated encoder. Encoder should be
   subclassed as part of driver encoder objects.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-encoder-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_encoder_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_encoder_cleanup</refname>
 <refpurpose>
     cleans up an initialised encoder
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_encoder_cleanup </function></funcdef>
   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>encoder</parameter></term>
   <listitem>
    <para>
     encoder to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Cleans up the encoder but doesn't free the object.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-universal-plane-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_universal_plane_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_universal_plane_init</refname>
 <refpurpose>
     Initialize a new universal plane object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_universal_plane_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>unsigned long <parameter>possible_crtcs</parameter></paramdef>
   <paramdef>const struct drm_plane_funcs * <parameter>funcs</parameter></paramdef>
   <paramdef>const uint32_t * <parameter>formats</parameter></paramdef>
   <paramdef>unsigned int <parameter>format_count</parameter></paramdef>
   <paramdef>enum drm_plane_type <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object to init
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>possible_crtcs</parameter></term>
   <listitem>
    <para>
     bitmask of possible CRTCs
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     callbacks for the new plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>formats</parameter></term>
   <listitem>
    <para>
     array of supported formats (<constant>DRM_FORMAT_</constant>*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>format_count</parameter></term>
   <listitem>
    <para>
     number of elements in <parameter>formats</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     type of plane (overlay, primary, cursor)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes a plane object of type <parameter>type</parameter>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_init</refname>
 <refpurpose>
     Initialize a legacy plane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_plane_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>unsigned long <parameter>possible_crtcs</parameter></paramdef>
   <paramdef>const struct drm_plane_funcs * <parameter>funcs</parameter></paramdef>
   <paramdef>const uint32_t * <parameter>formats</parameter></paramdef>
   <paramdef>unsigned int <parameter>format_count</parameter></paramdef>
   <paramdef>bool <parameter>is_primary</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object to init
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>possible_crtcs</parameter></term>
   <listitem>
    <para>
     bitmask of possible CRTCs
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     callbacks for the new plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>formats</parameter></term>
   <listitem>
    <para>
     array of supported formats (<constant>DRM_FORMAT_</constant>*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>format_count</parameter></term>
   <listitem>
    <para>
     number of elements in <parameter>formats</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>is_primary</parameter></term>
   <listitem>
    <para>
     plane type (primary vs overlay)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Legacy API to initialize a DRM plane.
   </para><para>

   New drivers should call <function>drm_universal_plane_init</function> instead.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_cleanup</refname>
 <refpurpose>
     Clean up the core plane usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_plane_cleanup </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function cleans up <parameter>plane</parameter> and removes it from the DRM mode setting
   core. Note that the function does *not* free the plane structure itself,
   this is the responsibility of the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-index">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_index</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_index</refname>
 <refpurpose>
     find the index of a registered plane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>drm_plane_index </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to find index for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a registered plane, return the index of that CRTC within a DRM
   device's list of planes.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-from-index">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_from_index</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_from_index</refname>
 <refpurpose>
     find the registered plane at an index
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_plane * <function>drm_plane_from_index </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>idx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>idx</parameter></term>
   <listitem>
    <para>
     index of registered plane to find for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a plane index, return the registered plane from DRM device's
   list of planes with matching index.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-force-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_force_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_force_disable</refname>
 <refpurpose>
     Forcibly disable a plane
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_plane_force_disable </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Forces the plane to be disabled.
   </para><para>

   Used when the plane's current framebuffer is destroyed,
   and when restoring fbdev mode.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-dvi-i-properties">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_dvi_i_properties</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_dvi_i_properties</refname>
 <refpurpose>
     create DVI-I specific connector properties
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_create_dvi_i_properties </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by a driver the first time a DVI-I connector is made.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-tv-properties">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_tv_properties</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_tv_properties</refname>
 <refpurpose>
     create TV specific connector properties
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_create_tv_properties </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>num_modes</parameter></paramdef>
   <paramdef>const char *const <parameter>modes[]</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_modes</parameter></term>
   <listitem>
    <para>
     number of different TV formats (modes) supported
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>modes[]</parameter></term>
   <listitem>
    <para>
     array of pointers to strings containing name of each format
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by a driver's TV initialization routine, this function creates
   the TV specific connector properties for a given device.  Caller is
   responsible for allocating a list of format names and passing them to
   this routine.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-scaling-mode-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_scaling_mode_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_scaling_mode_property</refname>
 <refpurpose>
     create scaling mode property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_create_scaling_mode_property </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by a driver the first time it's needed, must be attached to desired
   connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-aspect-ratio-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_aspect_ratio_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_aspect_ratio_property</refname>
 <refpurpose>
     create aspect ratio property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_create_aspect_ratio_property </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by a driver the first time it's needed, must be attached to desired
   connectors.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-dirty-info-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_dirty_info_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_dirty_info_property</refname>
 <refpurpose>
     create dirty property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_create_dirty_info_property </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called by a driver the first time it's needed, must be attached to desired
   connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-suggested-offset-properties">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_suggested_offset_properties</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_suggested_offset_properties</refname>
 <refpurpose>
     create suggests offset properties
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_create_suggested_offset_properties </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create the the suggested x/y offset property for connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-set-config-internal">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_set_config_internal</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_set_config_internal</refname>
 <refpurpose>
     helper to call -&gt;set_config
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_set_config_internal </function></funcdef>
   <paramdef>struct drm_mode_set * <parameter>set</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>set</parameter></term>
   <listitem>
    <para>
     modeset config to set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a little helper to wrap internal calls to the -&gt;set_config driver
   interface. The only thing it adds is correct refcounting dance.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-get-hv-timing">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_get_hv_timing</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_get_hv_timing</refname>
 <refpurpose>
     Fetches hdisplay/vdisplay for given mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_get_hv_timing </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>int * <parameter>hdisplay</parameter></paramdef>
   <paramdef>int * <parameter>vdisplay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to query
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hdisplay</parameter></term>
   <listitem>
    <para>
     hdisplay value to fill in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdisplay</parameter></term>
   <listitem>
    <para>
     vdisplay value to fill in
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The vdisplay value will be doubled if the specified mode is a stereo mode of
   the appropriate layout.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-check-viewport">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_check_viewport</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_check_viewport</refname>
 <refpurpose>
     Checks that a framebuffer is big enough for the CRTC viewport
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_crtc_check_viewport </function></funcdef>
   <paramdef>const struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>int <parameter>x</parameter></paramdef>
   <paramdef>int <parameter>y</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>const struct drm_framebuffer * <parameter>fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC that framebuffer will be displayed on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     x panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>y</parameter></term>
   <listitem>
    <para>
     y panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode that framebuffer will be displayed under
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to check size of
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-mode-legacy-fb-format">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_legacy_fb_format</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_legacy_fb_format</refname>
 <refpurpose>
     compute drm fourcc code from legacy description
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>uint32_t <function>drm_mode_legacy_fb_format </function></funcdef>
   <paramdef>uint32_t <parameter>bpp</parameter></paramdef>
   <paramdef>uint32_t <parameter>depth</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bpp</parameter></term>
   <listitem>
    <para>
     bits per pixels
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>depth</parameter></term>
   <listitem>
    <para>
     bit depth per pixel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Computes a drm fourcc pixel format code for the given <parameter>bpp</parameter>/<parameter>depth</parameter> values.
   Useful in fbdev emulation code, since that deals in those values.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create</refname>
 <refpurpose>
     create a new property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int <parameter>num_values</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_values</parameter></term>
   <listitem>
    <para>
     number of pre-defined values
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new generic drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   Note that the DRM core keeps a per-device list of properties and that, if
   <function>drm_mode_config_cleanup</function> is called, it will destroy all properties created
   by the driver.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-enum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_enum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_enum</refname>
 <refpurpose>
     create a new enumeration property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create_enum </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>const struct drm_prop_enum_list * <parameter>props</parameter></paramdef>
   <paramdef>int <parameter>num_values</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>props</parameter></term>
   <listitem>
    <para>
     enumeration lists with property values
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_values</parameter></term>
   <listitem>
    <para>
     number of pre-defined values
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new generic drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   Userspace is only allowed to set one of the predefined values for enumeration
   properties.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-bitmask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_bitmask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_bitmask</refname>
 <refpurpose>
     create a new bitmask property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create_bitmask </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>const struct drm_prop_enum_list * <parameter>props</parameter></paramdef>
   <paramdef>int <parameter>num_props</parameter></paramdef>
   <paramdef>uint64_t <parameter>supported_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>props</parameter></term>
   <listitem>
    <para>
     enumeration lists with property bitflags
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_props</parameter></term>
   <listitem>
    <para>
     size of the <parameter>props</parameter> array
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>supported_bits</parameter></term>
   <listitem>
    <para>
     bitmask of all supported enumeration values
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new bitmask drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   Compared to plain enumeration properties userspace is allowed to set any
   or'ed together combination of the predefined property bitflag values
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_range</refname>
 <refpurpose>
     create a new unsigned ranged property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create_range </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>uint64_t <parameter>min</parameter></paramdef>
   <paramdef>uint64_t <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     minimum value of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     maximum value of the property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new generic drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   Userspace is allowed to set any unsigned integer value in the (min, max)
   range inclusive.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-signed-range">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_signed_range</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_signed_range</refname>
 <refpurpose>
     create a new signed ranged property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create_signed_range </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>int64_t <parameter>min</parameter></paramdef>
   <paramdef>int64_t <parameter>max</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min</parameter></term>
   <listitem>
    <para>
     minimum value of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max</parameter></term>
   <listitem>
    <para>
     maximum value of the property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new generic drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   Userspace is allowed to set any signed integer value in the (min, max)
   range inclusive.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-object">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_object</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_object</refname>
 <refpurpose>
     create a new object property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create_object </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>uint32_t <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     object type from DRM_MODE_OBJECT_* defines
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new generic drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   Userspace is only allowed to set this to any property value of the given
   <parameter>type</parameter>. Only useful for atomic properties, which is enforced.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-bool">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_bool</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_bool</refname>
 <refpurpose>
     create a new boolean property type
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property * <function>drm_property_create_bool </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>flags</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags specifying the property type
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     name of the property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a new generic drm property which can then be attached to a drm
   object with drm_object_attach_property. The returned property object must be
   freed with drm_property_destroy.
   </para><para>

   This is implemented as a ranged property with only {0, 1} as valid values.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the newly created property on success, NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-add-enum">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_add_enum</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_add_enum</refname>
 <refpurpose>
     add a possible value to an enumeration property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_property_add_enum </function></funcdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>int <parameter>index</parameter></paramdef>
   <paramdef>uint64_t <parameter>value</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     enumeration property to change
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>index</parameter></term>
   <listitem>
    <para>
     index of the new enumeration
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value of the new enumeration
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     symbolic name of the new enumeration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions adds enumerations to a property.
   </para><para>

   It's use is deprecated, drivers should use one of the more specific helpers
   to directly create the property with all enumerations already attached.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_destroy</refname>
 <refpurpose>
     destroy a drm property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_property_destroy </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to destry
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function frees a property including any attached resources like
   enumeration values.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-object-attach-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_object_attach_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_object_attach_property</refname>
 <refpurpose>
     attach a property to a modeset object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_object_attach_property </function></funcdef>
   <paramdef>struct drm_mode_object * <parameter>obj</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>init_val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     drm modeset object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to attach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>init_val</parameter></term>
   <listitem>
    <para>
     initial value of the property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This attaches the given property to the modeset object with the given initial
   value. Currently this function cannot fail since the properties are stored in
   a statically sized array.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-object-property-set-value">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_object_property_set_value</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_object_property_set_value</refname>
 <refpurpose>
     set the value of a property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_object_property_set_value </function></funcdef>
   <paramdef>struct drm_mode_object * <parameter>obj</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     drm mode object to set property value for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value the property should be set to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions sets a given property on a given object. This function only
   changes the software state of the property, it does not call into the
   driver's -&gt;set_property callback.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-object-property-get-value">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_object_property_get_value</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_object_property_get_value</refname>
 <refpurpose>
     retrieve the value of a property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_object_property_get_value </function></funcdef>
   <paramdef>struct drm_mode_object * <parameter>obj</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t * <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     drm mode object to get property value from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     storage for the property value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function retrieves the softare state of the given property for the given
   property. Since there is no driver callback to retrieve the current property
   value this might be out of sync with the hardware, depending upon the driver
   and property.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-create-blob">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_create_blob</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_create_blob</refname>
 <refpurpose>
     Create new blob property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property_blob * <function>drm_property_create_blob </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>size_t <parameter>length</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device to create property for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     Length to allocate for blob data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     If specified, copies data into blob
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Creates a new blob property for a specified DRM device, optionally
   copying data.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   New blob property with a single reference on success, or an ERR_PTR
   value on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-unreference-blob">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_unreference_blob</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_unreference_blob</refname>
 <refpurpose>
     Unreference a blob property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_property_unreference_blob </function></funcdef>
   <paramdef>struct drm_property_blob * <parameter>blob</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>blob</parameter></term>
   <listitem>
    <para>
     Pointer to blob property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Drop a reference on a blob property. May free the object.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-reference-blob">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_reference_blob</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_reference_blob</refname>
 <refpurpose>
     Take a reference on an existing property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property_blob * <function>drm_property_reference_blob </function></funcdef>
   <paramdef>struct drm_property_blob * <parameter>blob</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>blob</parameter></term>
   <listitem>
    <para>
     Pointer to blob property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Take a new reference on an existing blob property.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-property-lookup-blob">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_property_lookup_blob</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_property_lookup_blob</refname>
 <refpurpose>
     look up a blob property and take a reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_property_blob * <function>drm_property_lookup_blob </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>uint32_t <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     id of the blob property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If successful, this takes an additional reference to the blob property.
   callers need to make sure to eventually unreference the returned property
   again, using <parameter>drm_property_unreference_blob</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-connector-set-path-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_connector_set_path_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_connector_set_path_property</refname>
 <refpurpose>
     set tile property on connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_connector_set_path_property </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>const char * <parameter>path</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to set property on.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>path</parameter></term>
   <listitem>
    <para>
     path to use for property; must not be NULL.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This creates a property to expose to userspace to specify a
   connector path. This is mainly used for DisplayPort MST where
   connectors have a topology and we want to allow userspace to give
   them more meaningful names.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-connector-set-tile-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_connector_set_tile_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_connector_set_tile_property</refname>
 <refpurpose>
     set tile property on connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_connector_set_tile_property </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to set property on.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This looks up the tile information for a connector, and creates a
   property for userspace to parse if it exists. The property is of
   the form of 8 integers using ':' as a separator.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-connector-update-edid-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_connector_update_edid_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_connector_update_edid_property</refname>
 <refpurpose>
     update the edid property of a connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_connector_update_edid_property </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>const struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     drm connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     new value of the edid property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function creates a new blob modeset object and assigns its id to the
   connector's edid property.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-plane-set-obj-prop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_plane_set_obj_prop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_plane_set_obj_prop</refname>
 <refpurpose>
     set the value of a property
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_plane_set_obj_prop </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane object to set property value for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value the property should be set to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions sets a given property on a given plane object. This function
   calls the driver's -&gt;set_property callback and changes the software state of
   the property if the callback succeeds.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-connector-attach-encoder">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_connector_attach_encoder</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_connector_attach_encoder</refname>
 <refpurpose>
     attach a connector to an encoder
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_connector_attach_encoder </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to attach
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>encoder</parameter></term>
   <listitem>
    <para>
     encoder to attach <parameter>connector</parameter> to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function links up a connector to an encoder. Note that the routing
   restrictions between encoders and crtcs are exposed to userspace through the
   possible_clones and possible_crtcs bitmasks.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-crtc-set-gamma-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_crtc_set_gamma_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_crtc_set_gamma_size</refname>
 <refpurpose>
     set the gamma table size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_mode_crtc_set_gamma_size </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>int <parameter>gamma_size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC to set the gamma table size for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>gamma_size</parameter></term>
   <listitem>
    <para>
     size of the gamma table
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers which support gamma tables should set this to the supported gamma
   table size when initializing the CRTC. Currently the drm core only supports a
   fixed gamma table size.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-config-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_config_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_config_reset</refname>
 <refpurpose>
     call -&gt;reset callbacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_config_reset </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions calls all the crtc's, encoder's and connector's -&gt;reset
   callback. Drivers can use this in e.g. their driver load or resume code to
   reset hardware and software state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-get-bpp-depth">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_get_bpp_depth</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_get_bpp_depth</refname>
 <refpurpose>
     get the bpp/depth values for format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_get_bpp_depth </function></funcdef>
   <paramdef>uint32_t <parameter>format</parameter></paramdef>
   <paramdef>unsigned int * <parameter>depth</parameter></paramdef>
   <paramdef>int * <parameter>bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     pixel format (DRM_FORMAT_*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>depth</parameter></term>
   <listitem>
    <para>
     storage for the depth value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bpp</parameter></term>
   <listitem>
    <para>
     storage for the bpp value
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This only supports RGB formats here for compat with code that doesn't use
   pixel formats directly yet.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-format-num-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_format_num_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_format_num_planes</refname>
 <refpurpose>
     get the number of planes for format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_format_num_planes </function></funcdef>
   <paramdef>uint32_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     pixel format (DRM_FORMAT_*)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The number of planes used by the specified pixel format.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-format-plane-cpp">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_format_plane_cpp</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_format_plane_cpp</refname>
 <refpurpose>
     determine the bytes per pixel value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_format_plane_cpp </function></funcdef>
   <paramdef>uint32_t <parameter>format</parameter></paramdef>
   <paramdef>int <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     pixel format (DRM_FORMAT_*)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The bytes per pixel value for the specified plane.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-format-horz-chroma-subsampling">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_format_horz_chroma_subsampling</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_format_horz_chroma_subsampling</refname>
 <refpurpose>
     get the horizontal chroma subsampling factor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_format_horz_chroma_subsampling </function></funcdef>
   <paramdef>uint32_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     pixel format (DRM_FORMAT_*)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The horizontal chroma subsampling factor for the
   specified pixel format.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-format-vert-chroma-subsampling">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_format_vert_chroma_subsampling</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_format_vert_chroma_subsampling</refname>
 <refpurpose>
     get the vertical chroma subsampling factor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_format_vert_chroma_subsampling </function></funcdef>
   <paramdef>uint32_t <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     pixel format (DRM_FORMAT_*)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The vertical chroma subsampling factor for the
   specified pixel format.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rotation-simplify">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rotation_simplify</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rotation_simplify</refname>
 <refpurpose>
     Try to simplify the rotation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned int <function>drm_rotation_simplify </function></funcdef>
   <paramdef>unsigned int <parameter>rotation</parameter></paramdef>
   <paramdef>unsigned int <parameter>supported_rotations</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>rotation</parameter></term>
   <listitem>
    <para>
     Rotation to be simplified
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>supported_rotations</parameter></term>
   <listitem>
    <para>
     Supported rotations
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Attempt to simplify the rotation to a form that is supported.
   Eg. if the hardware supports everything except DRM_REFLECT_X
</para>
</refsect1>
<refsect1>
<title>one could call this function like this</title>
<para>
   </para><para>

   drm_rotation_simplify(rotation, BIT(DRM_ROTATE_0) |
   BIT(DRM_ROTATE_90) | BIT(DRM_ROTATE_180) |
   BIT(DRM_ROTATE_270) | BIT(DRM_REFLECT_Y));
   </para><para>

   to eliminate the DRM_ROTATE_X flag. Depending on what kind of
   transforms the hardware supports, this function may not
   be able to produce a supported transform, so the caller should
   check the result afterwards.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-config-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_config_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_config_init</refname>
 <refpurpose>
     initialize DRM mode_configuration structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_config_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize <parameter>dev</parameter>'s mode_config structure, used for tracking the graphics
   configuration of <parameter>dev</parameter>.
   </para><para>

   Since this initializes the modeset locks, no locking is possible. Which is no
   problem, since this should happen single threaded at init time. It is the
   driver's problem to ensure this guarantee.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-config-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_config_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_config_cleanup</refname>
 <refpurpose>
     free up DRM mode_config info
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_mode_config_cleanup </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Free up all the connectors and CRTCs associated with this DRM device, then
   free up the framebuffers and associated buffer objects.
   </para><para>

   Note that since this /should/ happen single-threaded at driver/device
   teardown time, no locking is required. It's the driver's job to ensure that
   this guarantee actually holds true.
</para>
</refsect1>
<refsect1>
<title>FIXME</title>
<para>
   cleanup any dangling user buffer objects too
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-get-tile-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_get_tile_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_get_tile_group</refname>
 <refpurpose>
     get a reference to an existing tile group
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_tile_group * <function>drm_mode_get_tile_group </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>char <parameter>topology[8]</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>topology[8]</parameter></term>
   <listitem>
    <para>
     8-bytes unique per monitor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Use the unique bytes to get a reference to an existing tile group.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   tile group or NULL if not found.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-mode-create-tile-group">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_mode_create_tile_group</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_mode_create_tile_group</refname>
 <refpurpose>
     create a tile group from a displayid description
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_tile_group * <function>drm_mode_create_tile_group </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>char <parameter>topology[8]</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>topology[8]</parameter></term>
   <listitem>
    <para>
     8-bytes unique per monitor.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Create a tile group for the unique monitor, and get a unique
   identifier for the tile group.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   new tile group or error.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>KMS Data Structures</title>
<!-- include/drm/drm_crtc.h -->
<refentry id="API-struct-drm-crtc-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_crtc_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_crtc_state</refname>
 <refpurpose>
  mutable CRTC state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_crtc_state {
  struct drm_crtc * crtc;
  bool enable;
  bool active;
  bool planes_changed:1;
  bool mode_changed:1;
  bool active_changed:1;
  bool connectors_changed:1;
  u32 plane_mask;
  u32 last_vblank_count;
  struct drm_display_mode adjusted_mode;
  struct drm_display_mode mode;
  struct drm_pending_vblank_event * event;
  struct drm_atomic_state * state;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>crtc</term>
      <listitem><para>
backpointer to the CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable</term>
      <listitem><para>
whether the CRTC should be enabled, gates all other state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>active</term>
      <listitem><para>
whether the CRTC is actively displaying (used for DPMS)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>planes_changed</term>
      <listitem><para>
planes on this crtc are updated
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_changed</term>
      <listitem><para>
crtc_state-&gt;mode or crtc_state-&gt;enable has been changed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>active_changed</term>
      <listitem><para>
crtc_state-&gt;active has been toggled.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connectors_changed</term>
      <listitem><para>
connectors to this crtc have been updated
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>plane_mask</term>
      <listitem><para>
bitmask of (1 &lt;&lt; drm_plane_index(plane)) of attached planes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>last_vblank_count</term>
      <listitem><para>
for helpers and drivers to capture the vblank of the
update to ensure framebuffer cleanup isn't done too early
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>adjusted_mode</term>
      <listitem><para>
for use by helpers and drivers to compute adjusted mode timings
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
current mode timings
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>event</term>
      <listitem><para>
optional pointer to a DRM event to signal upon completion of the
state update
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
backpointer to global drm_atomic_state
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that the distinction between <parameter>enable</parameter> and <parameter>active</parameter> is rather subtile:
   Flipping <parameter>active</parameter> while <parameter>enable</parameter> is set without changing anything else may
   never return in a failure from the -&gt;atomic_check callback. Userspace assumes
   that a DPMS On will always succeed. In other words: <parameter>enable</parameter> controls resource
   assignment, <parameter>active</parameter> controls the actual hardware state.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-crtc-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_crtc_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_crtc_funcs</refname>
 <refpurpose>
     control CRTCs for a given device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_crtc_funcs {
  void (* save) (struct drm_crtc *crtc);
  void (* restore) (struct drm_crtc *crtc);
  void (* reset) (struct drm_crtc *crtc);
  int (* cursor_set) (struct drm_crtc *crtc, struct drm_file *file_priv,uint32_t handle, uint32_t width, uint32_t height);
  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);
  int (* cursor_move) (struct drm_crtc *crtc, int x, int y);
  void (* gamma_set) (struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b,uint32_t start, uint32_t size);
  void (* destroy) (struct drm_crtc *crtc);
  int (* set_config) (struct drm_mode_set *set);
  int (* page_flip) (struct drm_crtc *crtc,struct drm_framebuffer *fb,struct drm_pending_vblank_event *event,uint32_t flags);
  int (* set_property) (struct drm_crtc *crtc,struct drm_property *property, uint64_t val);
  struct drm_crtc_state *(* atomic_duplicate_state) (struct drm_crtc *crtc);
  void (* atomic_destroy_state) (struct drm_crtc *crtc,struct drm_crtc_state *state);
  int (* atomic_set_property) (struct drm_crtc *crtc,struct drm_crtc_state *state,struct drm_property *property,uint64_t val);
  int (* atomic_get_property) (struct drm_crtc *crtc,const struct drm_crtc_state *state,struct drm_property *property,uint64_t *val);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>save</term>
      <listitem><para>
   save CRTC state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>restore</term>
      <listitem><para>
   restore CRTC state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reset</term>
      <listitem><para>
   reset CRTC after state has been invalidated (e.g. resume)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_set</term>
      <listitem><para>
   setup the cursor
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_set2</term>
      <listitem><para>
   setup the cursor with hotspot, superseeds <parameter>cursor_set</parameter> if set
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_move</term>
      <listitem><para>
   move the cursor
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>gamma_set</term>
      <listitem><para>
   specify color ramp for CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destroy</term>
      <listitem><para>
   deinit and free object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_config</term>
      <listitem><para>
   apply a new CRTC configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>page_flip</term>
      <listitem><para>
   initiate a page flip
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_property</term>
      <listitem><para>
   called when a property is changed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_duplicate_state</term>
      <listitem><para>
   duplicate the atomic state for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_destroy_state</term>
      <listitem><para>
   destroy an atomic state for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_set_property</term>
      <listitem><para>
   set a property on an atomic state for this CRTC
   (do not call directly, use <function>drm_atomic_crtc_set_property</function>)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_get_property</term>
      <listitem><para>
   get a property on an atomic state for this CRTC
   (do not call directly, use <function>drm_atomic_crtc_get_property</function>)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The drm_crtc_funcs structure is the central CRTC management structure
   in the DRM.  Each CRTC controls one or more connectors (note that the name
   CRTC is simply historical, a CRTC may control LVDS, VGA, DVI, TV out, etc.
   connectors, not just CRTs).
   </para><para>

   Each driver is responsible for filling out this structure at startup time,
   in addition to providing other modesetting features, like i2c and DDC
   bus accessors.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_crtc</refname>
 <refpurpose>
     central CRTC control structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_crtc {
  struct drm_device * dev;
  struct device_node * port;
  struct list_head head;
  struct drm_modeset_lock mutex;
  struct drm_mode_object base;
  struct drm_plane * primary;
  struct drm_plane * cursor;
  int cursor_x;
  int cursor_y;
  bool enabled;
  struct drm_display_mode mode;
  struct drm_display_mode hwmode;
  int x;
  int y;
  const struct drm_crtc_funcs * funcs;
  uint32_t gamma_size;
  uint16_t * gamma_store;
  const void * helper_private;
  struct drm_object_properties properties;
  struct drm_crtc_state * state;
  struct drm_modeset_acquire_ctx * acquire_ctx;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   parent DRM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port</term>
      <listitem><para>
   OF node used by <function>drm_of_find_possible_crtcs</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>head</term>
      <listitem><para>
   list management
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   per-CRTC locking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
   base KMS object for ID tracking etc.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>primary</term>
      <listitem><para>
   primary plane for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor</term>
      <listitem><para>
   cursor plane for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_x</term>
      <listitem><para>
   current x position of the cursor, used for universal cursor planes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_y</term>
      <listitem><para>
   current y position of the cursor, used for universal cursor planes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enabled</term>
      <listitem><para>
   is this CRTC enabled?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   current mode timings
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hwmode</term>
      <listitem><para>
   mode timings as programmed to hw regs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>x</term>
      <listitem><para>
   x position on screen
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>y</term>
      <listitem><para>
   y position on screen
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   CRTC control functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>gamma_size</term>
      <listitem><para>
   size of gamma ramp
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>gamma_store</term>
      <listitem><para>
   gamma ramp values
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>helper_private</term>
      <listitem><para>
   mid-layer private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>properties</term>
      <listitem><para>
   property tracking for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   current atomic state for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>acquire_ctx</term>
      <listitem><para>
   per-CRTC implicit acquire context used by atomic drivers for
   legacy ioctls
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each CRTC may have one or more connectors associated with it.  This structure
   allows the CRTC to be controlled.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-connector-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_connector_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_connector_state</refname>
 <refpurpose>
     mutable connector state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_connector_state {
  struct drm_connector * connector;
  struct drm_crtc * crtc;
  struct drm_encoder * best_encoder;
  struct drm_atomic_state * state;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>connector</term>
      <listitem><para>
   backpointer to the connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc</term>
      <listitem><para>
   CRTC to connect connector to, NULL if disabled
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>best_encoder</term>
      <listitem><para>
   can be used by helpers and drivers to select the encoder
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   backpointer to global drm_atomic_state
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-connector-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_connector_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_connector_funcs</refname>
 <refpurpose>
     control connectors on a given device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_connector_funcs {
  int (* dpms) (struct drm_connector *connector, int mode);
  void (* save) (struct drm_connector *connector);
  void (* restore) (struct drm_connector *connector);
  void (* reset) (struct drm_connector *connector);
  enum drm_connector_status (* detect) (struct drm_connector *connector,bool force);
  int (* fill_modes) (struct drm_connector *connector, uint32_t max_width, uint32_t max_height);
  int (* set_property) (struct drm_connector *connector, struct drm_property *property,uint64_t val);
  void (* destroy) (struct drm_connector *connector);
  void (* force) (struct drm_connector *connector);
  struct drm_connector_state *(* atomic_duplicate_state) (struct drm_connector *connector);
  void (* atomic_destroy_state) (struct drm_connector *connector,struct drm_connector_state *state);
  int (* atomic_set_property) (struct drm_connector *connector,struct drm_connector_state *state,struct drm_property *property,uint64_t val);
  int (* atomic_get_property) (struct drm_connector *connector,const struct drm_connector_state *state,struct drm_property *property,uint64_t *val);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dpms</term>
      <listitem><para>
   set power state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>save</term>
      <listitem><para>
   save connector state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>restore</term>
      <listitem><para>
   restore connector state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reset</term>
      <listitem><para>
   reset connector after state has been invalidated (e.g. resume)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>detect</term>
      <listitem><para>
   is this connector active?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fill_modes</term>
      <listitem><para>
   fill mode list for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_property</term>
      <listitem><para>
   property for this connector may need an update
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destroy</term>
      <listitem><para>
   make object go away
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>force</term>
      <listitem><para>
   notify the driver that the connector is forced on
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_duplicate_state</term>
      <listitem><para>
   duplicate the atomic state for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_destroy_state</term>
      <listitem><para>
   destroy an atomic state for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_set_property</term>
      <listitem><para>
   set a property on an atomic state for this connector
   (do not call directly, use <function>drm_atomic_connector_set_property</function>)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_get_property</term>
      <listitem><para>
   get a property on an atomic state for this connector
   (do not call directly, use <function>drm_atomic_connector_get_property</function>)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each CRTC may have one or more connectors attached to it.  The functions
   below allow the core DRM code to control connectors, enumerate available modes,
   etc.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-encoder-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_encoder_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_encoder_funcs</refname>
 <refpurpose>
     encoder controls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_encoder_funcs {
  void (* reset) (struct drm_encoder *encoder);
  void (* destroy) (struct drm_encoder *encoder);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>reset</term>
      <listitem><para>
   reset state (e.g. at init or resume time)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destroy</term>
      <listitem><para>
   cleanup and free associated data
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Encoders sit between CRTCs and connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-encoder">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_encoder</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_encoder</refname>
 <refpurpose>
     central DRM encoder structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_encoder {
  struct drm_device * dev;
  struct list_head head;
  struct drm_mode_object base;
  char * name;
  int encoder_type;
  uint32_t possible_crtcs;
  uint32_t possible_clones;
  struct drm_crtc * crtc;
  struct drm_bridge * bridge;
  const struct drm_encoder_funcs * funcs;
  const void * helper_private;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   parent DRM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>head</term>
      <listitem><para>
   list management
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
   base KMS object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   encoder name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>encoder_type</term>
      <listitem><para>
   one of the <constant>DRM_MODE_ENCODER_</constant>&lt;foo&gt; types in drm_mode.h
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>possible_crtcs</term>
      <listitem><para>
   bitmask of potential CRTC bindings
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>possible_clones</term>
      <listitem><para>
   bitmask of potential sibling encoders for cloning
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc</term>
      <listitem><para>
   currently bound CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bridge</term>
      <listitem><para>
   bridge associated to the encoder
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   control functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>helper_private</term>
      <listitem><para>
   mid-layer private data
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   CRTCs drive pixels to encoders, which convert them into signals
   appropriate for a given connector or set of connectors.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-connector">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_connector</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_connector</refname>
 <refpurpose>
     central DRM connector control structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_connector {
  struct drm_device * dev;
  struct device * kdev;
  struct device_attribute * attr;
  struct list_head head;
  struct drm_mode_object base;
  char * name;
  int connector_type;
  int connector_type_id;
  bool interlace_allowed;
  bool doublescan_allowed;
  bool stereo_allowed;
  struct list_head modes;
  enum drm_connector_status status;
  struct list_head probed_modes;
  struct drm_display_info display_info;
  const struct drm_connector_funcs * funcs;
  struct drm_property_blob * edid_blob_ptr;
  struct drm_object_properties properties;
  struct drm_property_blob * path_blob_ptr;
  uint8_t polled;
  int dpms;
  const void * helper_private;
  struct drm_cmdline_mode cmdline_mode;
  enum drm_connector_force force;
  bool override_edid;
  uint32_t encoder_ids[DRM_CONNECTOR_MAX_ENCODER];
  struct drm_encoder * encoder;
  uint8_t eld[MAX_ELD_BYTES];
  bool dvi_dual;
  int max_tmds_clock;
  bool latency_present[2];
  int video_latency[2];
  int audio_latency[2];
  int null_edid_counter;
  unsigned bad_edid_counter;
  bool edid_corrupt;
  struct dentry * debugfs_entry;
  struct drm_connector_state * state;
  bool has_tile;
  struct drm_tile_group * tile_group;
  bool tile_is_single_monitor;
  uint8_t num_h_tile;
  uint8_t num_v_tile;
  uint8_t tile_h_loc;
  uint8_t tile_v_loc;
  uint16_t tile_h_size;
  uint16_t tile_v_size;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   parent DRM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>kdev</term>
      <listitem><para>
   kernel device for sysfs attributes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>attr</term>
      <listitem><para>
   sysfs attributes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>head</term>
      <listitem><para>
   list management
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
   base KMS object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>name</term>
      <listitem><para>
   connector name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector_type</term>
      <listitem><para>
   one of the <constant>DRM_MODE_CONNECTOR_</constant>&lt;foo&gt; types from drm_mode.h
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector_type_id</term>
      <listitem><para>
   index into connector type enum
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>interlace_allowed</term>
      <listitem><para>
   can this connector handle interlaced modes?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>doublescan_allowed</term>
      <listitem><para>
   can this connector handle doublescan?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>stereo_allowed</term>
      <listitem><para>
   can this connector handle stereo modes?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>modes</term>
      <listitem><para>
   modes available on this connector (from <function>fill_modes</function> + user)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>status</term>
      <listitem><para>
   one of the drm_connector_status enums (connected, not, or unknown)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probed_modes</term>
      <listitem><para>
   list of modes derived directly from the display
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>display_info</term>
      <listitem><para>
   information about attached display (e.g. from EDID)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   connector control functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>edid_blob_ptr</term>
      <listitem><para>
   DRM property containing EDID if present
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>properties</term>
      <listitem><para>
   property tracking for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>path_blob_ptr</term>
      <listitem><para>
   DRM blob property data for the DP MST path property
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>polled</term>
      <listitem><para>
   a <constant>DRM_CONNECTOR_POLL_</constant>&lt;foo&gt; value for core driven polling
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dpms</term>
      <listitem><para>
   current dpms state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>helper_private</term>
      <listitem><para>
   mid-layer private data
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cmdline_mode</term>
      <listitem><para>
   mode line parsed from the kernel cmdline for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>force</term>
      <listitem><para>
   a <constant>DRM_FORCE_</constant>&lt;foo&gt; state for forced mode sets
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>override_edid</term>
      <listitem><para>
   has the EDID been overwritten through debugfs for testing?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>encoder_ids[DRM_CONNECTOR_MAX_ENCODER]</term>
      <listitem><para>
   valid encoders for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>encoder</term>
      <listitem><para>
   encoder driving this connector, if any
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>eld[MAX_ELD_BYTES]</term>
      <listitem><para>
   EDID-like data, if present
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dvi_dual</term>
      <listitem><para>
   dual link DVI, if found
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_tmds_clock</term>
      <listitem><para>
   max clock rate, if found
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>latency_present[2]</term>
      <listitem><para>
   AV delay info from ELD, if found
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>video_latency[2]</term>
      <listitem><para>
   video latency info from ELD, if found
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>audio_latency[2]</term>
      <listitem><para>
   audio latency info from ELD, if found
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>null_edid_counter</term>
      <listitem><para>
   track sinks that give us all zeros for the EDID
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>bad_edid_counter</term>
      <listitem><para>
   track sinks that give us an EDID with invalid checksum
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>edid_corrupt</term>
      <listitem><para>
   indicates whether the last read EDID was corrupt
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>debugfs_entry</term>
      <listitem><para>
   debugfs directory for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   current atomic state for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>has_tile</term>
      <listitem><para>
   is this connector connected to a tiled monitor
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tile_group</term>
      <listitem><para>
   tile group for the connected monitor
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tile_is_single_monitor</term>
      <listitem><para>
   whether the tile is one monitor housing
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_h_tile</term>
      <listitem><para>
   number of horizontal tiles in the tile group
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_v_tile</term>
      <listitem><para>
   number of vertical tiles in the tile group
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tile_h_loc</term>
      <listitem><para>
   horizontal location of this tile
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tile_v_loc</term>
      <listitem><para>
   vertical location of this tile
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tile_h_size</term>
      <listitem><para>
   horizontal size of this tile.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tile_v_size</term>
      <listitem><para>
   vertical size of this tile.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each connector may be connected to one or more CRTCs, or may be clonable by
   another connector if they can share a CRTC.  Each connector also has a specific
   position in the broader display (referred to as a 'screen' though it could
   span multiple monitors).
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-plane-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_plane_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_plane_state</refname>
 <refpurpose>
     mutable plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_plane_state {
  struct drm_plane * plane;
  struct drm_crtc * crtc;
  struct drm_framebuffer * fb;
  struct fence * fence;
  int32_t crtc_x;
  int32_t crtc_y;
  uint32_t crtc_w;
  uint32_t crtc_h;
  uint32_t src_x;
  uint32_t src_y;
  uint32_t src_h;
  uint32_t src_w;
  struct drm_atomic_state * state;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>plane</term>
      <listitem><para>
   backpointer to the plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc</term>
      <listitem><para>
   currently bound CRTC, NULL if disabled
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb</term>
      <listitem><para>
   currently bound framebuffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fence</term>
      <listitem><para>
   optional fence to wait for before scanning out <parameter>fb</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_x</term>
      <listitem><para>
   left position of visible portion of plane on crtc
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_y</term>
      <listitem><para>
   upper position of visible portion of plane on crtc
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_w</term>
      <listitem><para>
   width of visible portion of plane on crtc
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_h</term>
      <listitem><para>
   height of visible portion of plane on crtc
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>src_x</term>
      <listitem><para>
   left position of visible portion of plane within
   plane (in 16.16)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>src_y</term>
      <listitem><para>
   upper position of visible portion of plane within
   plane (in 16.16)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>src_h</term>
      <listitem><para>
   height of visible portion of plane (in 16.16)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>src_w</term>
      <listitem><para>
   width of visible portion of plane (in 16.16)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   backpointer to global drm_atomic_state
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-plane-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_plane_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_plane_funcs</refname>
 <refpurpose>
     driver plane control functions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_plane_funcs {
  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);
  int (* disable_plane) (struct drm_plane *plane);
  void (* destroy) (struct drm_plane *plane);
  void (* reset) (struct drm_plane *plane);
  int (* set_property) (struct drm_plane *plane,struct drm_property *property, uint64_t val);
  struct drm_plane_state *(* atomic_duplicate_state) (struct drm_plane *plane);
  void (* atomic_destroy_state) (struct drm_plane *plane,struct drm_plane_state *state);
  int (* atomic_set_property) (struct drm_plane *plane,struct drm_plane_state *state,struct drm_property *property,uint64_t val);
  int (* atomic_get_property) (struct drm_plane *plane,const struct drm_plane_state *state,struct drm_property *property,uint64_t *val);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>update_plane</term>
      <listitem><para>
   update the plane configuration
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disable_plane</term>
      <listitem><para>
   shut down the plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>destroy</term>
      <listitem><para>
   clean up plane resources
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reset</term>
      <listitem><para>
   reset plane after state has been invalidated (e.g. resume)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>set_property</term>
      <listitem><para>
   called when a property is changed
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_duplicate_state</term>
      <listitem><para>
   duplicate the atomic state for this plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_destroy_state</term>
      <listitem><para>
   destroy an atomic state for this plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_set_property</term>
      <listitem><para>
   set a property on an atomic state for this plane
   (do not call directly, use <function>drm_atomic_plane_set_property</function>)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_get_property</term>
      <listitem><para>
   get a property on an atomic state for this plane
   (do not call directly, use <function>drm_atomic_plane_get_property</function>)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_plane</refname>
 <refpurpose>
     central DRM plane control structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_plane {
  struct drm_device * dev;
  struct list_head head;
  struct drm_mode_object base;
  uint32_t possible_crtcs;
  uint32_t * format_types;
  unsigned int format_count;
  bool format_default;
  struct drm_crtc * crtc;
  struct drm_framebuffer * fb;
  struct drm_framebuffer * old_fb;
  const struct drm_plane_funcs * funcs;
  struct drm_object_properties properties;
  enum drm_plane_type type;
  struct drm_plane_state * state;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   DRM device this plane belongs to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>head</term>
      <listitem><para>
   for list management
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>base</term>
      <listitem><para>
   base mode object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>possible_crtcs</term>
      <listitem><para>
   pipes this plane can be bound to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>format_types</term>
      <listitem><para>
   array of formats supported by this plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>format_count</term>
      <listitem><para>
   number of formats supported
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>format_default</term>
      <listitem><para>
   driver hasn't supplied supported formats for the plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc</term>
      <listitem><para>
   currently bound CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb</term>
      <listitem><para>
   currently bound fb
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>old_fb</term>
      <listitem><para>
   Temporary tracking of the old fb while a modeset is ongoing. Used by
   <function>drm_mode_set_config_internal</function> to implement correct refcounting.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   helper functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>properties</term>
      <listitem><para>
   property tracking for this plane
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
   type of plane (overlay, primary, cursor)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>state</term>
      <listitem><para>
   current atomic state for this plane
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-bridge-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_bridge_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_bridge_funcs</refname>
 <refpurpose>
     drm_bridge control functions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_bridge_funcs {
  int (* attach) (struct drm_bridge *bridge);
  bool (* mode_fixup) (struct drm_bridge *bridge,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
  void (* disable) (struct drm_bridge *bridge);
  void (* post_disable) (struct drm_bridge *bridge);
  void (* mode_set) (struct drm_bridge *bridge,struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
  void (* pre_enable) (struct drm_bridge *bridge);
  void (* enable) (struct drm_bridge *bridge);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>attach</term>
      <listitem><para>
   Called during drm_bridge_attach
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_fixup</term>
      <listitem><para>
   Try to fixup (or reject entirely) proposed mode for this bridge
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disable</term>
      <listitem><para>
   Called right before encoder prepare, disables the bridge
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>post_disable</term>
      <listitem><para>
   Called right after encoder prepare, for lockstepped disable
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_set</term>
      <listitem><para>
   Set this mode to the bridge
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pre_enable</term>
      <listitem><para>
   Called right before encoder commit, for lockstepped commit
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable</term>
      <listitem><para>
   Called right after encoder commit, enables the bridge
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-bridge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_bridge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_bridge</refname>
 <refpurpose>
     central DRM bridge control structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_bridge {
  struct drm_device * dev;
  struct drm_encoder * encoder;
  struct drm_bridge * next;
#ifdef CONFIG_OF
  struct device_node * of_node;
#endif
  struct list_head list;
  const struct drm_bridge_funcs * funcs;
  void * driver_private;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   DRM device this bridge belongs to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>encoder</term>
      <listitem><para>
   encoder to which this bridge is connected
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>next</term>
      <listitem><para>
   the next bridge in the encoder chain
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>of_node</term>
      <listitem><para>
   device node pointer to the bridge
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
   to keep track of all added bridges
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   control functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_private</term>
      <listitem><para>
   pointer to the bridge driver's internal context
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-atomic-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_atomic_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_atomic_state</refname>
 <refpurpose>
     the global state object for atomic updates
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_atomic_state {
  struct drm_device * dev;
  bool allow_modeset:1;
  bool legacy_cursor_update:1;
  struct drm_plane ** planes;
  struct drm_plane_state ** plane_states;
  struct drm_crtc ** crtcs;
  struct drm_crtc_state ** crtc_states;
  int num_connector;
  struct drm_connector ** connectors;
  struct drm_connector_state ** connector_states;
  struct drm_modeset_acquire_ctx * acquire_ctx;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   parent DRM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>allow_modeset</term>
      <listitem><para>
   allow full modeset
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>legacy_cursor_update</term>
      <listitem><para>
   hint to enforce legacy cursor ioctl semantics
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>planes</term>
      <listitem><para>
   pointer to array of plane pointers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>plane_states</term>
      <listitem><para>
   pointer to array of plane states pointers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtcs</term>
      <listitem><para>
   pointer to array of CRTC pointers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_states</term>
      <listitem><para>
   pointer to array of CRTC states pointers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_connector</term>
      <listitem><para>
   size of the <parameter>connectors</parameter> and <parameter>connector_states</parameter> arrays
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connectors</term>
      <listitem><para>
   pointer to array of connector pointers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector_states</term>
      <listitem><para>
   pointer to array of connector states pointers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>acquire_ctx</term>
      <listitem><para>
   acquire context for this atomic modeset state update
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-mode-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_mode_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_mode_set</refname>
 <refpurpose>
     new values for a CRTC config change
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_mode_set {
  struct drm_framebuffer * fb;
  struct drm_crtc * crtc;
  struct drm_display_mode * mode;
  uint32_t x;
  uint32_t y;
  struct drm_connector ** connectors;
  size_t num_connectors;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>fb</term>
      <listitem><para>
   framebuffer to use for new config
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc</term>
      <listitem><para>
   CRTC whose configuration we're about to change
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode</term>
      <listitem><para>
   mode timings to use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>x</term>
      <listitem><para>
   position of this CRTC relative to <parameter>fb</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>y</term>
      <listitem><para>
   position of this CRTC relative to <parameter>fb</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connectors</term>
      <listitem><para>
   array of connectors to drive with this CRTC if possible
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_connectors</term>
      <listitem><para>
   size of <parameter>connectors</parameter> array
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Represents a single crtc the connectors that it drives with what mode
   and from which framebuffer it scans out from.
   </para><para>

   This is used to set modes.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-mode-config-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_mode_config_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_mode_config_funcs</refname>
 <refpurpose>
     basic driver provided mode setting functions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_mode_config_funcs {
  struct drm_framebuffer *(* fb_create) (struct drm_device *dev,struct drm_file *file_priv,struct drm_mode_fb_cmd2 *mode_cmd);
  void (* output_poll_changed) (struct drm_device *dev);
  int (* atomic_check) (struct drm_device *dev,struct drm_atomic_state *a);
  int (* atomic_commit) (struct drm_device *dev,struct drm_atomic_state *a,bool async);
  struct drm_atomic_state *(* atomic_state_alloc) (struct drm_device *dev);
  void (* atomic_state_clear) (struct drm_atomic_state *state);
  void (* atomic_state_free) (struct drm_atomic_state *state);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>fb_create</term>
      <listitem><para>
   create a new framebuffer object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>output_poll_changed</term>
      <listitem><para>
   function to handle output configuration changes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_check</term>
      <listitem><para>
   check whether a given atomic state update is possible
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_commit</term>
      <listitem><para>
   commit an atomic state update previously verified with
   <function>atomic_check</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_state_alloc</term>
      <listitem><para>
   allocate a new atomic state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_state_clear</term>
      <listitem><para>
   clear the atomic state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_state_free</term>
      <listitem><para>
   free the atomic state
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Some global (i.e. not per-CRTC, connector, etc) mode setting functions that
   involve drivers.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-mode-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_mode_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_mode_config</refname>
 <refpurpose>
     Mode configuration control structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_mode_config {
  struct mutex mutex;
  struct drm_modeset_lock connection_mutex;
  struct drm_modeset_acquire_ctx * acquire_ctx;
  struct mutex idr_mutex;
  struct idr crtc_idr;
  struct mutex fb_lock;
  int num_fb;
  struct list_head fb_list;
  int num_connector;
  struct list_head connector_list;
  int num_encoder;
  struct list_head encoder_list;
  int num_overlay_plane;
  int num_total_plane;
  struct list_head plane_list;
  int num_crtc;
  struct list_head crtc_list;
  struct list_head property_list;
  int min_width;
  int min_height;
  int max_width;
  int max_height;
  const struct drm_mode_config_funcs * funcs;
  resource_size_t fb_base;
  bool poll_enabled;
  bool poll_running;
  struct delayed_work output_poll_work;
  struct mutex blob_lock;
  struct list_head property_blob_list;
  uint32_t preferred_depth;
  uint32_t prefer_shadow;
  bool async_page_flip;
  uint32_t cursor_width;
  uint32_t cursor_height;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   mutex protecting KMS related lists and structures
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connection_mutex</term>
      <listitem><para>
   ww mutex protecting connector state and routing
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>acquire_ctx</term>
      <listitem><para>
   global implicit acquire context used by atomic drivers for
   legacy ioctls
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>idr_mutex</term>
      <listitem><para>
   mutex for KMS ID allocation and management
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_idr</term>
      <listitem><para>
   main KMS ID tracking object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb_lock</term>
      <listitem><para>
   mutex to protect fb state and lists
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_fb</term>
      <listitem><para>
   number of fbs available
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb_list</term>
      <listitem><para>
   list of framebuffers available
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_connector</term>
      <listitem><para>
   number of connectors on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector_list</term>
      <listitem><para>
   list of connector objects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_encoder</term>
      <listitem><para>
   number of encoders on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>encoder_list</term>
      <listitem><para>
   list of encoder objects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_overlay_plane</term>
      <listitem><para>
   number of overlay planes on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_total_plane</term>
      <listitem><para>
   number of universal (i.e. with primary/curso) planes on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>plane_list</term>
      <listitem><para>
   list of plane objects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_crtc</term>
      <listitem><para>
   number of CRTCs on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_list</term>
      <listitem><para>
   list of CRTC objects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>property_list</term>
      <listitem><para>
   list of property objects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min_width</term>
      <listitem><para>
   minimum pixel width on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>min_height</term>
      <listitem><para>
   minimum pixel height on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_width</term>
      <listitem><para>
   maximum pixel width on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_height</term>
      <listitem><para>
   maximum pixel height on this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   core driver provided mode setting functions
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb_base</term>
      <listitem><para>
   base address of the framebuffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll_enabled</term>
      <listitem><para>
   track polling support for this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>poll_running</term>
      <listitem><para>
   track polling status for this device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>output_poll_work</term>
      <listitem><para>
   delayed work for polling in process context
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>blob_lock</term>
      <listitem><para>
   mutex for blob property allocation and management
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>property_blob_list</term>
      <listitem><para>
   list of all the blob property objects
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>preferred_depth</term>
      <listitem><para>
   preferred RBG pixel depth, used by fb helpers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prefer_shadow</term>
      <listitem><para>
   hint to userspace to prefer shadow-fb rendering
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>async_page_flip</term>
      <listitem><para>
   does this device support async flips on the primary plane?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_width</term>
      <listitem><para>
   hint to userspace for max cursor width
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cursor_height</term>
      <listitem><para>
   hint to userspace for max cursor height
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>_property</title>
<para>
   core property tracking
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Core mode resource tracking structure.  All CRTC, encoders, and connectors
   enumerated by the driver are added here, as are global properties.  Some
   global restrictions are also here, e.g. dimension restrictions.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-for-each-plane-mask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_for_each_plane_mask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_for_each_plane_mask</refname>
 <refpurpose>
     iterate over planes specified by bitmask
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>drm_for_each_plane_mask </function></funcdef>
   <paramdef> <parameter>plane</parameter></paramdef>
   <paramdef> <parameter>dev</parameter></paramdef>
   <paramdef> <parameter>plane_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     the loop cursor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane_mask</parameter></term>
   <listitem>
    <para>
     bitmask of plane indices
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Iterate over all planes specified by bitmask.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-mask">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_mask</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_mask</refname>
 <refpurpose>
     find the mask of a registered CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>uint32_t <function>drm_crtc_mask </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC to find mask for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Given a registered CRTC, return the mask bit of that CRTC for an
   encoder's possible_crtcs field.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-encoder-crtc-ok">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_encoder_crtc_ok</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_encoder_crtc_ok</refname>
 <refpurpose>
     can a given crtc drive a given encoder?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_encoder_crtc_ok </function></funcdef>
   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>encoder</parameter></term>
   <listitem>
    <para>
     encoder to test
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     crtc to test
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return false if <parameter>encoder</parameter> can't be driven by <parameter>crtc</parameter>, true otherwise.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>KMS Locking</title>
<para>
   </para><para>
   As KMS moves toward more fine grained locking, and atomic ioctl where
   userspace can indirectly control locking order, it becomes necessary
   to use ww_mutex and acquire-contexts to avoid deadlocks.  But because
   the locking is more distributed around the driver code, we want a bit
   of extra utility/tracking out of our acquire-ctx.  This is provided
   by drm_modeset_lock / drm_modeset_acquire_ctx.
   </para><para>
   For basic principles of ww_mutex, see: Documentation/locking/ww-mutex-design.txt
   </para><para>
   The basic usage pattern is to:
   </para><para>
   drm_modeset_acquire_init(<structname>ctx</structname>)
   retry:
   foreach (lock in random_ordered_set_of_locks) {
   ret = drm_modeset_lock(lock, <structname>ctx</structname>)
   if (ret == -EDEADLK) {
   drm_modeset_backoff(<structname>ctx</structname>);
   goto retry;
   }
   }
   </para><para>
   ... do stuff ...
   </para><para>
   drm_modeset_drop_locks(<structname>ctx</structname>);
   drm_modeset_acquire_fini(<structname>ctx</structname>);
</para>

<!-- include/drm/drm_modeset_lock.h -->
<refentry id="API-struct-drm-modeset-acquire-ctx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_modeset_acquire_ctx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_modeset_acquire_ctx</refname>
 <refpurpose>
  locking context (see ww_acquire_ctx)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_modeset_acquire_ctx {
  struct ww_acquire_ctx ww_ctx;
  struct drm_modeset_lock * contended;
  struct list_head locked;
  bool trylock_only;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>ww_ctx</term>
      <listitem><para>
base acquire ctx
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>contended</term>
      <listitem><para>
used internally for -EDEADLK handling
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>locked</term>
      <listitem><para>
list of held locks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>trylock_only</term>
      <listitem><para>
trylock mode used in atomic contexts/panic notifiers
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Each thread competing for a set of locks must use one acquire
   ctx.  And if any lock fxn returns -EDEADLK, it must backoff and
   retry.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-modeset-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_modeset_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_modeset_lock</refname>
 <refpurpose>
     used for locking modeset resources.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_modeset_lock {
  struct ww_mutex mutex;
  struct list_head head;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>mutex</term>
      <listitem><para>
   resource locking
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>head</term>
      <listitem><para>
   used to hold it's place on state-&gt;locked list when
   part of an atomic update
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Used for locking CRTCs and other modeset resources.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-lock-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_lock_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_lock_init</refname>
 <refpurpose>
     initialize lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_lock_init </function></funcdef>
   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     lock to init
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-lock-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_lock_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_lock_fini</refname>
 <refpurpose>
     cleanup lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_lock_fini </function></funcdef>
   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     lock to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-is-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_is_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_is_locked</refname>
 <refpurpose>
     equivalent to <function>mutex_is_locked</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_modeset_is_locked </function></funcdef>
   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     lock to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_modeset_lock.c -->
<refentry id="API-drm-modeset-lock-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_lock_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_lock_all</refname>
 <refpurpose>
  take all modeset locks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_lock_all </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function takes all modeset locks, suitable where a more fine-grained
   scheme isn't (yet) implemented. Locks must be dropped with
   drm_modeset_unlock_all.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-unlock-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_unlock_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_unlock_all</refname>
 <refpurpose>
     drop all modeset locks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_unlock_all </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function drop all modeset locks taken by drm_modeset_lock_all.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-lock-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_lock_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_lock_crtc</refname>
 <refpurpose>
     lock crtc with hidden acquire ctx for a plane update
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_lock_crtc </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM CRTC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     DRM plane to be updated on <parameter>crtc</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function locks the given crtc and plane (which should be either the
   primary or cursor plane) using a hidden acquire context. This is necessary so
   that drivers internally using the atomic interfaces can grab further locks
   with the lock acquire context.
   </para><para>

   Note that <parameter>plane</parameter> can be NULL, e.g. when the cursor support hasn't yet been
   converted to universal planes yet.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-legacy-acquire-ctx">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_legacy_acquire_ctx</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_legacy_acquire_ctx</refname>
 <refpurpose>
     find acquire ctx for legacy ioctls
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_modeset_acquire_ctx * <function>drm_modeset_legacy_acquire_ctx </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     drm crtc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Legacy ioctl operations like cursor updates or page flips only have per-crtc
   locking, and store the acquire ctx in the corresponding crtc. All other
   legacy operations take all locks and use a global acquire context. This
   function grabs the right one.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-unlock-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_unlock_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_unlock_crtc</refname>
 <refpurpose>
     drop crtc lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_unlock_crtc </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     drm crtc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This drops the crtc lock acquire with <function>drm_modeset_lock_crtc</function> and all other
   locks acquired through the hidden context.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-warn-on-modeset-not-all-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_warn_on_modeset_not_all_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_warn_on_modeset_not_all_locked</refname>
 <refpurpose>
     check that all modeset locks are locked
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_warn_on_modeset_not_all_locked </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Useful as a debug assert.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-acquire-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_acquire_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_acquire_init</refname>
 <refpurpose>
     initialize acquire context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_acquire_init </function></funcdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
   <paramdef>uint32_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     the acquire context
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     for future
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-acquire-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_acquire_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_acquire_fini</refname>
 <refpurpose>
     cleanup acquire context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_acquire_fini </function></funcdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     the acquire context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-drop-locks">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_drop_locks</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_drop_locks</refname>
 <refpurpose>
     drop all locks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_drop_locks </function></funcdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     the acquire context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drop all locks currently held against this acquire context.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-backoff">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_backoff</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_backoff</refname>
 <refpurpose>
     deadlock avoidance backoff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_backoff </function></funcdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     the acquire context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If deadlock is detected (ie. <function>drm_modeset_lock</function> returns -EDEADLK),
   you must call this function to drop all currently held locks and
   block until the contended lock becomes available.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-backoff-interruptible">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_backoff_interruptible</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_backoff_interruptible</refname>
 <refpurpose>
     deadlock avoidance backoff
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_modeset_backoff_interruptible </function></funcdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     the acquire context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Interruptible version of <function>drm_modeset_backoff</function>
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-lock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_lock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_lock</refname>
 <refpurpose>
     take modeset lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_modeset_lock </function></funcdef>
   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     lock to take
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     acquire ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   If ctx is not NULL, then its ww acquire context is used and the
   lock will be tracked by the context and can be released by calling
   <function>drm_modeset_drop_locks</function>.  If -EDEADLK is returned, this means a
   deadlock scenario has been detected and it is an error to attempt
   to take any more locks without first calling <function>drm_modeset_backoff</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-lock-interruptible">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_lock_interruptible</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_lock_interruptible</refname>
 <refpurpose>
     take modeset lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_modeset_lock_interruptible </function></funcdef>
   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     lock to take
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     acquire ctx
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Interruptible version of <function>drm_modeset_lock</function>
</para>
</refsect1>
</refentry>

<refentry id="API-drm-modeset-unlock">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_modeset_unlock</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_modeset_unlock</refname>
 <refpurpose>
     drop modeset lock
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_modeset_unlock </function></funcdef>
   <paramdef>struct drm_modeset_lock * <parameter>lock</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>lock</parameter></term>
   <listitem>
    <para>
     lock to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

    </sect2>
  </sect1>

  <!-- Internals: kms helper functions -->

  <sect1>
    <title>Mode Setting Helper Functions</title>
    <para>
      The plane, CRTC, encoder and connector functions provided by the drivers
      implement the DRM API. They're called by the DRM core and ioctl handlers
      to handle device state changes and configuration request. As implementing
      those functions often requires logic not specific to drivers, mid-layer
      helper functions are available to avoid duplicating boilerplate code.
    </para>
    <para>
      The DRM core contains one mid-layer implementation. The mid-layer provides
      implementations of several plane, CRTC, encoder and connector functions
      (called from the top of the mid-layer) that pre-process requests and call
      lower-level functions provided by the driver (at the bottom of the
      mid-layer). For instance, the
      <function>drm_crtc_helper_set_config</function> function can be used to
      fill the struct <structname>drm_crtc_funcs</structname>
      <structfield>set_config</structfield> field. When called, it will split
      the <methodname>set_config</methodname> operation in smaller, simpler
      operations and call the driver to handle them.
    </para>
    <para>
      To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>,
      <function>drm_encoder_helper_add</function> and
      <function>drm_connector_helper_add</function> functions to install their
      mid-layer bottom operations handlers, and fill the
      <structname>drm_crtc_funcs</structname>,
      <structname>drm_encoder_funcs</structname> and
      <structname>drm_connector_funcs</structname> structures with pointers to
      the mid-layer top API functions. Installing the mid-layer bottom operation
      handlers is best done right after registering the corresponding KMS object.
    </para>
    <para>
      The mid-layer is not split between CRTC, encoder and connector operations.
      To use it, a driver must provide bottom functions for all of the three KMS
      entities.
    </para>
    <sect2>
      <title>Helper Functions</title>
      <itemizedlist>
        <listitem>
          <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis>
          <para>
            The <function>drm_crtc_helper_set_config</function> helper function
            is a CRTC <methodname>set_config</methodname> implementation. It
            first tries to locate the best encoder for each connector by calling
            the connector <methodname>best_encoder</methodname> helper
            operation.
          </para>
          <para>
            After locating the appropriate encoders, the helper function will
            call the <methodname>mode_fixup</methodname> encoder and CRTC helper
            operations to adjust the requested mode, or reject it completely in
            which case an error will be returned to the application. If the new
            configuration after mode adjustment is identical to the current
            configuration the helper function will return without performing any
            other operation.
          </para>
          <para>
            If the adjusted mode is identical to the current mode but changes to
            the frame buffer need to be applied, the
            <function>drm_crtc_helper_set_config</function> function will call
            the CRTC <methodname>mode_set_base</methodname> helper operation. If
            the adjusted mode differs from the current mode, or if the
            <methodname>mode_set_base</methodname> helper operation is not
            provided, the helper function performs a full mode set sequence by
            calling the <methodname>prepare</methodname>,
            <methodname>mode_set</methodname> and
            <methodname>commit</methodname> CRTC and encoder helper operations,
            in that order.
          </para>
        </listitem>
        <listitem>
          <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis>
          <para>
            The <function>drm_helper_connector_dpms</function> helper function
            is a connector <methodname>dpms</methodname> implementation that
            tracks power state of connectors. To use the function, drivers must
            provide <methodname>dpms</methodname> helper operations for CRTCs
            and encoders to apply the DPMS state to the device.
          </para>
          <para>
            The mid-layer doesn't track the power state of CRTCs and encoders.
            The <methodname>dpms</methodname> helper operations can thus be
            called with a mode identical to the currently active mode.
          </para>
        </listitem>
        <listitem>
          <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector,
                                            uint32_t maxX, uint32_t maxY);</synopsis>
          <para>
            The <function>drm_helper_probe_single_connector_modes</function> helper
            function is a connector <methodname>fill_modes</methodname>
            implementation that updates the connection status for the connector
            and then retrieves a list of modes by calling the connector
            <methodname>get_modes</methodname> helper operation.
          </para>
         <para>
            If the helper operation returns no mode, and if the connector status
            is connector_status_connected, standard VESA DMT modes up to
            1024x768 are automatically added to the modes list by a call to
            <function>drm_add_modes_noedid</function>.
          </para>
          <para>
            The function then filters out modes larger than
            <parameter>max_width</parameter> and <parameter>max_height</parameter>
            if specified. It finally calls the optional connector
            <methodname>mode_valid</methodname> helper operation for each mode in
            the probed list to check whether the mode is valid for the connector.
          </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>CRTC Helper Operations</title>
      <itemizedlist>
        <listitem id="drm-helper-crtc-mode-fixup">
          <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc,
                       const struct drm_display_mode *mode,
                       struct drm_display_mode *adjusted_mode);</synopsis>
          <para>
            Let CRTCs adjust the requested mode or reject it completely. This
            operation returns true if the mode is accepted (possibly after being
            adjusted) or false if it is rejected.
          </para>
          <para>
            The <methodname>mode_fixup</methodname> operation should reject the
            mode if it can't reasonably use it. The definition of "reasonable"
            is currently fuzzy in this context. One possible behaviour would be
            to set the adjusted mode to the panel timings when a fixed-mode
            panel is used with hardware capable of scaling. Another behaviour
            would be to accept any input mode and adjust it to the closest mode
            supported by the hardware (FIXME: This needs to be clarified).
          </para>
        </listitem>
        <listitem>
          <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y,
                     struct drm_framebuffer *old_fb)</synopsis>
          <para>
            Move the CRTC on the current frame buffer (stored in
            <literal>crtc-&gt;fb</literal>) to position (x,y). Any of the frame
            buffer, x position or y position may have been modified.
          </para>
          <para>
            This helper operation is optional. If not provided, the
            <function>drm_crtc_helper_set_config</function> function will fall
            back to the <methodname>mode_set</methodname> helper operation.
          </para>
          <note><para>
            FIXME: Why are x and y passed as arguments, as they can be accessed
            through <literal>crtc-&gt;x</literal> and
            <literal>crtc-&gt;y</literal>?
          </para></note>
        </listitem>
        <listitem>
          <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis>
          <para>
            Prepare the CRTC for mode setting. This operation is called after
            validating the requested mode. Drivers use it to perform
            device-specific operations required before setting the new mode.
          </para>
        </listitem>
        <listitem>
          <synopsis>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);</synopsis>
          <para>
            Set a new mode, position and frame buffer. Depending on the device
            requirements, the mode can be stored internally by the driver and
            applied in the <methodname>commit</methodname> operation, or
            programmed to the hardware immediately.
          </para>
          <para>
            The <methodname>mode_set</methodname> operation returns 0 on success
	    or a negative error code if an error occurs.
          </para>
        </listitem>
        <listitem>
          <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis>
          <para>
            Commit a mode. This operation is called after setting the new mode.
            Upon return the device must use the new mode and be fully
            operational.
          </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>Encoder Helper Operations</title>
      <itemizedlist>
        <listitem>
          <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder,
                       const struct drm_display_mode *mode,
                       struct drm_display_mode *adjusted_mode);</synopsis>
          <para>
            Let encoders adjust the requested mode or reject it completely. This
            operation returns true if the mode is accepted (possibly after being
            adjusted) or false if it is rejected. See the
            <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper
            operation</link> for an explanation of the allowed adjustments.
          </para>
        </listitem>
        <listitem>
          <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis>
          <para>
            Prepare the encoder for mode setting. This operation is called after
            validating the requested mode. Drivers use it to perform
            device-specific operations required before setting the new mode.
          </para>
        </listitem>
        <listitem>
          <synopsis>void (*mode_set)(struct drm_encoder *encoder,
                 struct drm_display_mode *mode,
                 struct drm_display_mode *adjusted_mode);</synopsis>
          <para>
            Set a new mode. Depending on the device requirements, the mode can
            be stored internally by the driver and applied in the
            <methodname>commit</methodname> operation, or programmed to the
            hardware immediately.
          </para>
        </listitem>
        <listitem>
          <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis>
          <para>
            Commit a mode. This operation is called after setting the new mode.
            Upon return the device must use the new mode and be fully
            operational.
          </para>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>Connector Helper Operations</title>
      <itemizedlist>
        <listitem>
          <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis>
          <para>
            Return a pointer to the best encoder for the connecter. Device that
            map connectors to encoders 1:1 simply return the pointer to the
            associated encoder. This operation is mandatory.
          </para>
        </listitem>
        <listitem>
          <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis>
          <para>
            Fill the connector's <structfield>probed_modes</structfield> list
            by parsing EDID data with <function>drm_add_edid_modes</function>,
            adding standard VESA DMT modes with <function>drm_add_modes_noedid</function>,
            or calling <function>drm_mode_probed_add</function> directly for every
            supported mode and return the number of modes it has detected. This
            operation is mandatory.
          </para>
          <para>
            Note that the caller function will automatically add standard VESA
            DMT modes up to 1024x768 if the <methodname>get_modes</methodname>
            helper operation returns no mode and if the connector status is
            connector_status_connected. There is no need to call
            <function>drm_add_edid_modes</function> manually in that case.
          </para>
          <para>
            When adding modes manually the driver creates each mode with a call to
            <function>drm_mode_create</function> and must fill the following fields.
            <itemizedlist>
              <listitem>
                <synopsis>__u32 type;</synopsis>
                <para>
                  Mode type bitmask, a combination of
                  <variablelist>
                    <varlistentry>
                      <term>DRM_MODE_TYPE_BUILTIN</term>
                      <listitem><para>not used?</para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_TYPE_CLOCK_C</term>
                      <listitem><para>not used?</para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_TYPE_CRTC_C</term>
                      <listitem><para>not used?</para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>
        DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector
                      </term>
                      <listitem>
                        <para>not used?</para>
                      </listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_TYPE_DEFAULT</term>
                      <listitem><para>not used?</para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_TYPE_USERDEF</term>
                      <listitem><para>not used?</para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_TYPE_DRIVER</term>
                      <listitem>
                        <para>
                          The mode has been created by the driver (as opposed to
                          to user-created modes).
                        </para>
                      </listitem>
                    </varlistentry>
                  </variablelist>
                  Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they
                  create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred
                  mode.
                </para>
              </listitem>
              <listitem>
                <synopsis>__u32 clock;</synopsis>
                <para>Pixel clock frequency in kHz unit</para>
              </listitem>
              <listitem>
                <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal;
    __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis>
                <para>Horizontal and vertical timing information</para>
                <screen><![CDATA[
             Active                 Front           Sync           Back
             Region                 Porch                          Porch
    <-----------------------><----------------><-------------><-------------->

      //////////////////////|
     ////////////////////// |
    //////////////////////  |..................               ................
                                               _______________

    <----- [hv]display ----->
    <------------- [hv]sync_start ------------>
    <--------------------- [hv]sync_end --------------------->
    <-------------------------------- [hv]total ----------------------------->
]]></screen>
              </listitem>
              <listitem>
                <synopsis>__u16 hskew;
    __u16 vscan;</synopsis>
                <para>Unknown</para>
              </listitem>
              <listitem>
                <synopsis>__u32 flags;</synopsis>
                <para>
                  Mode flags, a combination of
                  <variablelist>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_PHSYNC</term>
                      <listitem><para>
                        Horizontal sync is active high
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_NHSYNC</term>
                      <listitem><para>
                        Horizontal sync is active low
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_PVSYNC</term>
                      <listitem><para>
                        Vertical sync is active high
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_NVSYNC</term>
                      <listitem><para>
                        Vertical sync is active low
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_INTERLACE</term>
                      <listitem><para>
                        Mode is interlaced
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_DBLSCAN</term>
                      <listitem><para>
                        Mode uses doublescan
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_CSYNC</term>
                      <listitem><para>
                        Mode uses composite sync
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_PCSYNC</term>
                      <listitem><para>
                        Composite sync is active high
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_NCSYNC</term>
                      <listitem><para>
                        Composite sync is active low
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_HSKEW</term>
                      <listitem><para>
                        hskew provided (not used?)
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_BCAST</term>
                      <listitem><para>
                        not used?
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_PIXMUX</term>
                      <listitem><para>
                        not used?
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_DBLCLK</term>
                      <listitem><para>
                        not used?
                      </para></listitem>
                    </varlistentry>
                    <varlistentry>
                      <term>DRM_MODE_FLAG_CLKDIV2</term>
                      <listitem><para>
                        ?
                      </para></listitem>
                    </varlistentry>
                  </variablelist>
                </para>
                <para>
                  Note that modes marked with the INTERLACE or DBLSCAN flags will be
                  filtered out by
                  <function>drm_helper_probe_single_connector_modes</function> if
                  the connector's <structfield>interlace_allowed</structfield> or
                  <structfield>doublescan_allowed</structfield> field is set to 0.
                </para>
              </listitem>
              <listitem>
                <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis>
                <para>
                  Mode name. The driver must call
                  <function>drm_mode_set_name</function> to fill the mode name from
                  <structfield>hdisplay</structfield>,
                  <structfield>vdisplay</structfield> and interlace flag after
                  filling the corresponding fields.
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            The <structfield>vrefresh</structfield> value is computed by
            <function>drm_helper_probe_single_connector_modes</function>.
          </para>
          <para>
            When parsing EDID data, <function>drm_add_edid_modes</function> fills the
            connector <structfield>display_info</structfield>
            <structfield>width_mm</structfield> and
            <structfield>height_mm</structfield> fields. When creating modes
            manually the <methodname>get_modes</methodname> helper operation must
            set the <structfield>display_info</structfield>
            <structfield>width_mm</structfield> and
            <structfield>height_mm</structfield> fields if they haven't been set
            already (for instance at initialization time when a fixed-size panel is
            attached to the connector). The mode <structfield>width_mm</structfield>
            and <structfield>height_mm</structfield> fields are only used internally
            during EDID parsing and should not be set when creating modes manually.
          </para>
        </listitem>
        <listitem>
          <synopsis>int (*mode_valid)(struct drm_connector *connector,
		  struct drm_display_mode *mode);</synopsis>
          <para>
            Verify whether a mode is valid for the connector. Return MODE_OK for
            supported modes and one of the enum drm_mode_status values (MODE_*)
            for unsupported modes. This operation is optional.
          </para>
          <para>
            As the mode rejection reason is currently not used beside for
            immediately removing the unsupported mode, an implementation can
            return MODE_BAD regardless of the exact reason why the mode is not
            valid.
          </para>
          <note><para>
            Note that the <methodname>mode_valid</methodname> helper operation is
            only called for modes detected by the device, and
            <emphasis>not</emphasis> for modes set by the user through the CRTC
            <methodname>set_config</methodname> operation.
          </para></note>
        </listitem>
      </itemizedlist>
    </sect2>
    <sect2>
      <title>Atomic Modeset Helper Functions Reference</title>
      <sect3>
	<title>Overview</title>
<para>
   </para><para>
   This helper library provides implementations of check and commit functions on
   top of the CRTC modeset helper callbacks and the plane helper callbacks. It
   also provides convenience implementations for the atomic state handling
   callbacks for drivers which don't need to subclass the drm core structures to
   add their own additional internal state.
   </para><para>
   This library also provides default implementations for the check callback in
   <function>drm_atomic_helper_check</function> and for the commit callback with
   <function>drm_atomic_helper_commit</function>. But the individual stages and callbacks are
   exposed to allow drivers to mix and match and e.g. use the plane helpers only
   together with a driver private modeset implementation.
   </para><para>
   This library also provides implementations for all the legacy driver
   interfaces on top of the atomic interface. See <function>drm_atomic_helper_set_config</function>,
   <function>drm_atomic_helper_disable_plane</function>, <function>drm_atomic_helper_disable_plane</function> and the
   various functions to implement set_property callbacks. New drivers must not
   implement these functions themselves but must use the provided helpers.
</para>

      </sect3>
      <sect3>
	<title>Implementing Asynchronous Atomic Commit</title>
<para>
   </para><para>
   For now the atomic helpers don't support async commit directly. If there is
   real need it could be added though, using the dma-buf fence infrastructure
   for generic synchronization with outstanding rendering.
   </para><para>
   For now drivers have to implement async commit themselves, with the following
   sequence being the recommended one:
   </para><para>
   1. Run <function>drm_atomic_helper_prepare_planes</function> first. This is the only function
   which commit needs to call which can fail, so we want to run it first and
   synchronously.
   </para><para>
   2. Synchronize with any outstanding asynchronous commit worker threads which
   might be affected the new state update. This can be done by either cancelling
   or flushing the work items, depending upon whether the driver can deal with
   cancelled updates. Note that it is important to ensure that the framebuffer
   cleanup is still done when cancelling.
   </para><para>
   For sufficient parallelism it is recommended to have a work item per crtc
   (for updates which don't touch global state) and a global one. Then we only
   need to synchronize with the crtc work items for changed crtcs and the global
   work item, which allows nice concurrent updates on disjoint sets of crtcs.
   </para><para>
   3. The software state is updated synchronously with
   <function>drm_atomic_helper_swap_state</function>. Doing this under the protection of all modeset
   locks means concurrent callers never see inconsistent state. And doing this
   while it's guaranteed that no relevant async worker runs means that async
   workers do not need grab any locks. Actually they must not grab locks, for
   otherwise the work flushing will deadlock.
   </para><para>
   4. Schedule a work item to do all subsequent steps, using the split-out
   commit helpers: a) pre-plane commit b) plane commit c) post-plane commit and
   then cleaning up the framebuffers after the old framebuffer is no longer
   being displayed.
</para>

      </sect3>
      <sect3>
	<title>Atomic State Reset and Initialization</title>
<para>
   </para><para>
   Both the drm core and the atomic helpers assume that there is always the full
   and correct atomic software state for all connectors, CRTCs and planes
   available. Which is a bit a problem on driver load and also after system
   suspend. One way to solve this is to have a hardware state read-out
   infrastructure which reconstructs the full software state (e.g. the i915
   driver).
   </para><para>
   The simpler solution is to just reset the software state to everything off,
   which is easiest to do by calling <function>drm_mode_config_reset</function>. To facilitate this
   the atomic helpers provide default reset implementations for all hooks.
</para>

      </sect3>
<!-- include/drm/drm_atomic_helper.h -->
<refentry id="API-drm-atomic-crtc-for-each-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_crtc_for_each_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_crtc_for_each_plane</refname>
 <refpurpose>
  iterate over planes currently attached to CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>drm_atomic_crtc_for_each_plane </function></funcdef>
   <paramdef> <parameter>plane</parameter></paramdef>
   <paramdef> <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     the loop cursor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     the crtc whose planes are iterated
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This iterates over the current state, useful (for example) when applying
   atomic state after it has been checked and swapped.  To iterate over the
   planes which *will* be attached (for -&gt;<function>atomic_check</function>) see
   <function>drm_crtc_for_each_pending_plane</function>
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-crtc-state-for-each-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_crtc_state_for_each_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_crtc_state_for_each_plane</refname>
 <refpurpose>
     iterate over attached planes in new state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef> <function>drm_atomic_crtc_state_for_each_plane </function></funcdef>
   <paramdef> <parameter>plane</parameter></paramdef>
   <paramdef> <parameter>crtc_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     the loop cursor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_state</parameter></term>
   <listitem>
    <para>
     the incoming crtc-state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Similar to <function>drm_crtc_for_each_plane</function>, but iterates the planes that will be
   attached if the specified state is applied.  Useful during (for example)
   -&gt;<function>atomic_check</function> operations, to validate the incoming state
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_atomic_helper.c -->
<refentry id="API-drm-atomic-helper-check-modeset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_check_modeset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_check_modeset</refname>
 <refpurpose>
  validate state object for modeset changes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_check_modeset </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the driver state object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the state object to see if the requested state is physically possible.
   This does all the crtc and connector related computations for an atomic
   update and adds any additional connectors needed for full modesets and calls
   down into -&gt;mode_fixup functions of the driver backend.
   </para><para>

   crtc_state-&gt;mode_changed is set when the input mode is changed.
   crtc_state-&gt;connectors_changed is set when a connector is added or
   removed from the crtc.
   crtc_state-&gt;active_changed is set when crtc_state-&gt;active changes,
   which is used for dpms.
</para>
</refsect1>
<refsect1>
<title>IMPORTANT</title>
<para>
   </para><para>

   Drivers which update -&gt;mode_changed (e.g. in their -&gt;atomic_check hooks if a
   plane update can't be done without a full modeset) _must_ call this function
   afterwards after that change. It is permitted to call this function multiple
   times for the same update, e.g. when the -&gt;atomic_check functions depend upon
   the adjusted dotclock for fifo space allocation and watermark computation.
   </para><para>

   RETURNS
   Zero for success or -errno
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-check-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_check_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_check_planes</refname>
 <refpurpose>
     validate state object for planes changes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_check_planes </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the driver state object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the state object to see if the requested state is physically possible.
   This does all the plane update related checks using by calling into the
   -&gt;atomic_check hooks provided by the driver.
   </para><para>

   It also sets crtc_state-&gt;planes_changed to indicate that a crtc has
   updated planes.
   </para><para>

   RETURNS
   Zero for success or -errno
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-check">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_check</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_check</refname>
 <refpurpose>
     validate state object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_check </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the driver state object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the state object to see if the requested state is physically possible.
   Only crtcs and planes have check callbacks, so for any additional (global)
   checking that a driver needs it can simply wrap that around this function.
   Drivers without such needs can directly use this as their -&gt;<function>atomic_check</function>
   callback.
   </para><para>

   This just wraps the two parts of the state checking for planes and modeset
</para>
</refsect1>
<refsect1>
<title>state in the default order</title>
<para>
   First it calls <function>drm_atomic_helper_check_modeset</function>
   and then <function>drm_atomic_helper_check_planes</function>. The assumption is that the
   -&gt;atomic_check functions depend upon an updated adjusted_mode.clock to
   e.g. properly compute watermarks.
   </para><para>

   RETURNS
   Zero for success or -errno
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-update-legacy-modeset-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_update_legacy_modeset_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_update_legacy_modeset_state</refname>
 <refpurpose>
     update legacy modeset state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_update_legacy_modeset_state </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_state</parameter></term>
   <listitem>
    <para>
     atomic state object with old state structures
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function updates all the various legacy modeset state pointers in
   connectors, encoders and crtcs. It also updates the timestamping constants
   used for precise vblank timestamps by calling
   <function>drm_calc_timestamping_constants</function>.
   </para><para>

   Drivers can use this for building their own atomic commit if they don't have
   a pure helper-based modeset implementation.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-commit-modeset-disables">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_commit_modeset_disables</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_commit_modeset_disables</refname>
 <refpurpose>
     modeset commit to disable outputs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_commit_modeset_disables </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_state</parameter></term>
   <listitem>
    <para>
     atomic state object with old state structures
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function shuts down all the outputs that need to be shut down and
   prepares them (if required) with the new mode.
   </para><para>

   For compatibility with legacy crtc helpers this should be called before
   <function>drm_atomic_helper_commit_planes</function>, which is what the default commit function
   does. But drivers with different needs can group the modeset commits together
   and do the plane commits at the end. This is useful for drivers doing runtime
   PM since planes updates then only happen when the CRTC is actually enabled.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-commit-modeset-enables">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_commit_modeset_enables</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_commit_modeset_enables</refname>
 <refpurpose>
     modeset commit to enable outputs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_commit_modeset_enables </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_state</parameter></term>
   <listitem>
    <para>
     atomic state object with old state structures
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function enables all the outputs with the new configuration which had to
   be turned off for the update.
   </para><para>

   For compatibility with legacy crtc helpers this should be called after
   <function>drm_atomic_helper_commit_planes</function>, which is what the default commit function
   does. But drivers with different needs can group the modeset commits together
   and do the plane commits at the end. This is useful for drivers doing runtime
   PM since planes updates then only happen when the CRTC is actually enabled.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-wait-for-vblanks">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_wait_for_vblanks</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_wait_for_vblanks</refname>
 <refpurpose>
     wait for vblank on crtcs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_wait_for_vblanks </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_state</parameter></term>
   <listitem>
    <para>
     atomic state object with old state structures
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper to, after atomic commit, wait for vblanks on all effected
   crtcs (ie. before cleaning up old framebuffers using
   <function>drm_atomic_helper_cleanup_planes</function>). It will only wait on crtcs where the
   framebuffers have actually changed to optimize for the legacy cursor and
   plane update use-case.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-commit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_commit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_commit</refname>
 <refpurpose>
     commit validated state object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_commit </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
   <paramdef>bool <parameter>async</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     the driver state object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>async</parameter></term>
   <listitem>
    <para>
     asynchronous commit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function commits a with <function>drm_atomic_helper_check</function> pre-validated state
   object. This can still fail when e.g. the framebuffer reservation fails. For
   now this doesn't implement asynchronous commits.
   </para><para>

   Note that right now this function does not support async commits, and hence
   driver writers must implement their own version for now. Also note that the
   default ordering of how the various stages are called is to match the legacy
   modeset helper library closest. One peculiarity of that is that it doesn't
   mesh well with runtime PM at all.
   </para><para>

   For drivers supporting runtime PM the recommended sequence is
   </para><para>

   drm_atomic_helper_commit_modeset_disables(dev, state);
   </para><para>

   drm_atomic_helper_commit_modeset_enables(dev, state);
   </para><para>

   drm_atomic_helper_commit_planes(dev, state, true);
   </para><para>

   See the kerneldoc entries for these three functions for more details.
   </para><para>

   RETURNS
   Zero for success or -errno.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-prepare-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_prepare_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_prepare_planes</refname>
 <refpurpose>
     prepare plane resources before commit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_prepare_planes </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state object with new state structures
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function prepares plane state, specifically framebuffers, for the new
   configuration. If any failure is encountered this function will call
   -&gt;cleanup_fb on any already successfully prepared framebuffer.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-commit-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_commit_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_commit_planes</refname>
 <refpurpose>
     commit plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_commit_planes </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
   <paramdef>bool <parameter>active_only</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_state</parameter></term>
   <listitem>
    <para>
     atomic state object with old state structures
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>active_only</parameter></term>
   <listitem>
    <para>
     Only commit on active CRTC if set
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function commits the new plane state using the plane and atomic helper
   functions for planes and crtcs. It assumes that the atomic state has already
   been pushed into the relevant object state pointers, since this step can no
   longer fail.
   </para><para>

   It still requires the global state object <parameter>old_state</parameter> to know which planes and
   crtcs need to be updated though.
   </para><para>

   Note that this function does all plane updates across all CRTCs in one step.
   If the hardware can't support this approach look at
   <function>drm_atomic_helper_commit_planes_on_crtc</function> instead.
   </para><para>

   Plane parameters can be updated by applications while the associated CRTC is
   disabled. The DRM/KMS core will store the parameters in the plane state,
   which will be available to the driver when the CRTC is turned on. As a result
   most drivers don't need to be immediately notified of plane updates for a
   disabled CRTC.
   </para><para>

   Unless otherwise needed, drivers are advised to set the <parameter>active_only</parameter>
   parameters to true in order not to receive plane update notifications related
   to a disabled CRTC. This avoids the need to manually ignore plane updates in
   driver code when the driver and/or hardware can't or just don't need to deal
   with updates on disabled CRTCs, for example when supporting runtime PM.
   </para><para>

   The <function>drm_atomic_helper_commit</function> default implementation only sets <parameter>active_only</parameter>
   to false to most closely match the behaviour of the legacy helpers. This should
   not be copied blindly by drivers.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-commit-planes-on-crtc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_commit_planes_on_crtc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_commit_planes_on_crtc</refname>
 <refpurpose>
     commit plane state for a crtc
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_commit_planes_on_crtc </function></funcdef>
   <paramdef>struct drm_crtc_state * <parameter>old_crtc_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old_crtc_state</parameter></term>
   <listitem>
    <para>
     atomic state object with the old crtc state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function commits the new plane state using the plane and atomic helper
   functions for planes on the specific crtc. It assumes that the atomic state
   has already been pushed into the relevant object state pointers, since this
   step can no longer fail.
   </para><para>

   This function is useful when plane updates should be done crtc-by-crtc
   instead of one global step like <function>drm_atomic_helper_commit_planes</function> does.
   </para><para>

   This function can only be savely used when planes are not allowed to move
   between different CRTCs because this function doesn't handle inter-CRTC
   depencies. Callers need to ensure that either no such depencies exist,
   resolve them through ordering of commit calls or through some other means.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-cleanup-planes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_cleanup_planes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_cleanup_planes</refname>
 <refpurpose>
     cleanup plane resources after commit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_cleanup_planes </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>old_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_state</parameter></term>
   <listitem>
    <para>
     atomic state object with old state structures
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function cleans up plane state, specifically framebuffers, from the old
   configuration. Hence the old configuration must be perserved in <parameter>old_state</parameter> to
   be able to call this function.
   </para><para>

   This function must also be called on the new state when the atomic update
   fails at any point after calling <function>drm_atomic_helper_prepare_planes</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-swap-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_swap_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_swap_state</refname>
 <refpurpose>
     store atomic state into current sw state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_swap_state </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_atomic_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function stores the atomic state into the current state pointers in all
   driver objects. It should be called after all failing steps have been done
   and succeeded, but before the actual hardware state is committed.
   </para><para>

   For cleanup and error recovery the current state for all changed objects will
   be swaped into <parameter>state</parameter>.
   </para><para>

   With that sequence it fits perfectly into the plane prepare/cleanup sequence:
   </para><para>

   1. Call <function>drm_atomic_helper_prepare_planes</function> with the staged atomic state.
   </para><para>

   2. Do any other steps that might fail.
   </para><para>

   3. Put the staged state into the current state pointers with this function.
   </para><para>

   4. Actually commit the hardware state.
   </para><para>

   5. Call <function>drm_atomic_helper_cleanup_planes</function> with <parameter>state</parameter>, which since step 3
   contains the old state. Also do any other cleanup required with that state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-update-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_update_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_update_plane</refname>
 <refpurpose>
     Helper for primary plane update using atomic
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_update_plane </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>int <parameter>crtc_x</parameter></paramdef>
   <paramdef>int <parameter>crtc_y</parameter></paramdef>
   <paramdef>unsigned int <parameter>crtc_w</parameter></paramdef>
   <paramdef>unsigned int <parameter>crtc_h</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_x</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_y</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_w</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_h</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     owning CRTC of owning plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to flip onto plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_x</parameter></term>
   <listitem>
    <para>
     x offset of primary plane on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_y</parameter></term>
   <listitem>
    <para>
     y offset of primary plane on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_w</parameter></term>
   <listitem>
    <para>
     width of primary plane rectangle on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_h</parameter></term>
   <listitem>
    <para>
     height of primary plane rectangle on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_x</parameter></term>
   <listitem>
    <para>
     x offset of <parameter>fb</parameter> for panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_y</parameter></term>
   <listitem>
    <para>
     y offset of <parameter>fb</parameter> for panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_w</parameter></term>
   <listitem>
    <para>
     width of source rectangle in <parameter>fb</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_h</parameter></term>
   <listitem>
    <para>
     height of source rectangle in <parameter>fb</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane update handler using the atomic driver interface.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-disable-plane">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_disable_plane</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_disable_plane</refname>
 <refpurpose>
     Helper for primary plane disable using * atomic
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_disable_plane </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane disable handler using the atomic driver interface.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-set-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_set_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_set_config</refname>
 <refpurpose>
     set a new config from userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_set_config </function></funcdef>
   <paramdef>struct drm_mode_set * <parameter>set</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>set</parameter></term>
   <listitem>
    <para>
     mode set configuration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default crtc set_config handler using the atomic driver interface.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Returns 0 on success, negative errno numbers on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-crtc-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_crtc_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_crtc_set_property</refname>
 <refpurpose>
     helper for crtc properties
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_crtc_set_property </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     DRM property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value of property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default crtc set_property handler using the atomic driver
   interface.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-plane-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_plane_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_plane_set_property</refname>
 <refpurpose>
     helper for plane properties
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_plane_set_property </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     DRM plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     DRM property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value of property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane set_property handler using the atomic driver
   interface.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-connector-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_connector_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_connector_set_property</refname>
 <refpurpose>
     helper for connector properties
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_connector_set_property </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     DRM connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     DRM property
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value of property
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default connector set_property handler using the atomic driver
   interface.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-page-flip">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_page_flip</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_page_flip</refname>
 <refpurpose>
     execute a legacy page flip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_page_flip </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>struct drm_pending_vblank_event * <parameter>event</parameter></paramdef>
   <paramdef>uint32_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     DRM framebuffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>event</parameter></term>
   <listitem>
    <para>
     optional DRM event to signal upon completion
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flip flags for non-vblank sync'ed updates
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default page flip implementation using the atomic driver interface.
   </para><para>

   Note that for now so called async page flips (i.e. updates which are not
   synchronized to vblank) are not supported, since the atomic interfaces have
   no provisions for this yet.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Returns 0 on success, negative errno numbers on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-connector-dpms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_connector_dpms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_connector_dpms</refname>
 <refpurpose>
     connector dpms helper implementation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_atomic_helper_connector_dpms </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>int <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     affected connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     DPMS mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the main helper function provided by the atomic helper framework for
   implementing the legacy DPMS connector interface. It computes the new desired
   -&gt;active state for the corresponding CRTC (if the connector is enabled) and
   updates it.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Returns 0 on success, negative errno numbers on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-crtc-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_crtc_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_crtc_reset</refname>
 <refpurpose>
     default -&gt;reset hook for CRTCs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_crtc_reset </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     drm CRTC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Resets the atomic state for <parameter>crtc</parameter> by freeing the state pointer (which might
   be NULL, e.g. at driver load time) and allocating a new empty state object.
</para>
</refsect1>
</refentry>

<refentry id="API---drm-atomic-helper-crtc-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__drm_atomic_helper_crtc_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__drm_atomic_helper_crtc_duplicate_state</refname>
 <refpurpose>
     copy atomic CRTC state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__drm_atomic_helper_crtc_duplicate_state </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic CRTC state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies atomic state from a CRTC's current state and resets inferred values.
   This is useful for drivers that subclass the CRTC state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-crtc-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_crtc_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_crtc_duplicate_state</refname>
 <refpurpose>
     default state duplicate hook
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_crtc_state * <function>drm_atomic_helper_crtc_duplicate_state </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     drm CRTC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default CRTC state duplicate hook for drivers which don't have their own
   subclassed CRTC state structure.
</para>
</refsect1>
</refentry>

<refentry id="API---drm-atomic-helper-crtc-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__drm_atomic_helper_crtc_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__drm_atomic_helper_crtc_destroy_state</refname>
 <refpurpose>
     release CRTC state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__drm_atomic_helper_crtc_destroy_state </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     CRTC state object to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases all resources stored in the CRTC state without actually freeing
   the memory of the CRTC state. This is useful for drivers that subclass the
   CRTC state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-crtc-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_crtc_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_crtc_destroy_state</refname>
 <refpurpose>
     default state destroy hook
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_crtc_destroy_state </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_crtc_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     drm CRTC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     CRTC state object to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default CRTC state destroy hook for drivers which don't have their own
   subclassed CRTC state structure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-plane-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_plane_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_plane_reset</refname>
 <refpurpose>
     default -&gt;reset hook for planes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_plane_reset </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Resets the atomic state for <parameter>plane</parameter> by freeing the state pointer (which might
   be NULL, e.g. at driver load time) and allocating a new empty state object.
</para>
</refsect1>
</refentry>

<refentry id="API---drm-atomic-helper-plane-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__drm_atomic_helper_plane_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__drm_atomic_helper_plane_duplicate_state</refname>
 <refpurpose>
     copy atomic plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__drm_atomic_helper_plane_duplicate_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic plane state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies atomic state from a plane's current state. This is useful for
   drivers that subclass the plane state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-plane-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_plane_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_plane_duplicate_state</refname>
 <refpurpose>
     default state duplicate hook
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_plane_state * <function>drm_atomic_helper_plane_duplicate_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default plane state duplicate hook for drivers which don't have their own
   subclassed plane state structure.
</para>
</refsect1>
</refentry>

<refentry id="API---drm-atomic-helper-plane-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__drm_atomic_helper_plane_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__drm_atomic_helper_plane_destroy_state</refname>
 <refpurpose>
     release plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__drm_atomic_helper_plane_destroy_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     plane state object to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases all resources stored in the plane state without actually freeing
   the memory of the plane state. This is useful for drivers that subclass the
   plane state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-plane-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_plane_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_plane_destroy_state</refname>
 <refpurpose>
     default state destroy hook
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_plane_destroy_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     plane state object to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default plane state destroy hook for drivers which don't have their own
   subclassed plane state structure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-connector-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_connector_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_connector_reset</refname>
 <refpurpose>
     default -&gt;reset hook for connectors
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_connector_reset </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     drm connector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Resets the atomic state for <parameter>connector</parameter> by freeing the state pointer (which
   might be NULL, e.g. at driver load time) and allocating a new empty state
   object.
</para>
</refsect1>
</refentry>

<refentry id="API---drm-atomic-helper-connector-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__drm_atomic_helper_connector_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__drm_atomic_helper_connector_duplicate_state</refname>
 <refpurpose>
     copy atomic connector state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__drm_atomic_helper_connector_duplicate_state </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     atomic connector state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Copies atomic state from a connector's current state. This is useful for
   drivers that subclass the connector state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-connector-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_connector_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_connector_duplicate_state</refname>
 <refpurpose>
     default state duplicate hook
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_connector_state * <function>drm_atomic_helper_connector_duplicate_state </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     drm connector
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default connector state duplicate hook for drivers which don't have their own
   subclassed connector state structure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_duplicate_state</refname>
 <refpurpose>
     duplicate an atomic state object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_atomic_state * <function>drm_atomic_helper_duplicate_state </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_modeset_acquire_ctx * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     lock acquisition context
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Makes a copy of the current atomic state by looping over all objects and
   duplicating their respective states.
   </para><para>

   Note that this treats atomic state as persistent between save and restore.
   Drivers must make sure that this is possible and won't result in confusion
   or erroneous behaviour.
   </para><para>

   Note that if callers haven't already acquired all modeset locks this might
   return -EDEADLK, which must be handled by calling <function>drm_modeset_backoff</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A pointer to the copy of the atomic state object on success or an
   <function>ERR_PTR</function>-encoded error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API---drm-atomic-helper-connector-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__drm_atomic_helper_connector_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__drm_atomic_helper_connector_destroy_state</refname>
 <refpurpose>
     release connector state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__drm_atomic_helper_connector_destroy_state </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector object
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     connector state object to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases all resources stored in the connector state without actually
   freeing the memory of the connector state. This is useful for drivers that
   subclass the connector state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-atomic-helper-connector-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_atomic_helper_connector_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_atomic_helper_connector_destroy_state</refname>
 <refpurpose>
     default state destroy hook
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_atomic_helper_connector_destroy_state </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_connector_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     drm connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     connector state object to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Default connector state destroy hook for drivers which don't have their own
   subclassed connector state structure.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Modeset Helper Functions Reference</title>
<!-- include/drm/drm_crtc_helper.h -->
<refentry id="API-struct-drm-crtc-helper-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_crtc_helper_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_crtc_helper_funcs</refname>
 <refpurpose>
  helper operations for CRTCs
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_crtc_helper_funcs {
  void (* dpms) (struct drm_crtc *crtc, int mode);
  void (* prepare) (struct drm_crtc *crtc);
  void (* commit) (struct drm_crtc *crtc);
  bool (* mode_fixup) (struct drm_crtc *crtc,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
  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);
  void (* mode_set_nofb) (struct drm_crtc *crtc);
  int (* mode_set_base) (struct drm_crtc *crtc, int x, int y,struct drm_framebuffer *old_fb);
  int (* mode_set_base_atomic) (struct drm_crtc *crtc,struct drm_framebuffer *fb, int x, int y,enum mode_set_atomic);
  void (* load_lut) (struct drm_crtc *crtc);
  void (* disable) (struct drm_crtc *crtc);
  void (* enable) (struct drm_crtc *crtc);
  int (* atomic_check) (struct drm_crtc *crtc,struct drm_crtc_state *state);
  void (* atomic_begin) (struct drm_crtc *crtc,struct drm_crtc_state *old_crtc_state);
  void (* atomic_flush) (struct drm_crtc *crtc,struct drm_crtc_state *old_crtc_state);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dpms</term>
      <listitem><para>
set power state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prepare</term>
      <listitem><para>
prepare the CRTC, called before <parameter>mode_set</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>commit</term>
      <listitem><para>
commit changes to CRTC, called after <parameter>mode_set</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_fixup</term>
      <listitem><para>
try to fixup proposed mode for this CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_set</term>
      <listitem><para>
set this mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_set_nofb</term>
      <listitem><para>
set mode only (no scanout buffer attached)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_set_base</term>
      <listitem><para>
update the scanout buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_set_base_atomic</term>
      <listitem><para>
non-blocking mode set (used for kgdb support)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>load_lut</term>
      <listitem><para>
load color palette
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disable</term>
      <listitem><para>
disable CRTC when no longer in use
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable</term>
      <listitem><para>
enable CRTC
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_check</term>
      <listitem><para>
check for validity of an atomic state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_begin</term>
      <listitem><para>
begin atomic update
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_flush</term>
      <listitem><para>
flush atomic update
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The helper operations are called by the mid-layer CRTC helper.
   </para><para>

   Note that with atomic helpers <parameter>dpms</parameter>, <parameter>prepare</parameter> and <parameter>commit</parameter> hooks are
   deprecated. Used <parameter>enable</parameter> and <parameter>disable</parameter> instead exclusively.
   </para><para>

   With legacy crtc helpers there's a big semantic difference between <parameter>disable</parameter>
</para>
</refsect1>
<refsect1>
<title>and the other hooks</title>
<para>
   <parameter>disable</parameter> also needs to release any resources acquired in
   <parameter>mode_set</parameter> (like shared PLLs).
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-encoder-helper-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_encoder_helper_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_encoder_helper_funcs</refname>
 <refpurpose>
     helper operations for encoders
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_encoder_helper_funcs {
  void (* dpms) (struct drm_encoder *encoder, int mode);
  void (* save) (struct drm_encoder *encoder);
  void (* restore) (struct drm_encoder *encoder);
  bool (* mode_fixup) (struct drm_encoder *encoder,const struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
  void (* prepare) (struct drm_encoder *encoder);
  void (* commit) (struct drm_encoder *encoder);
  void (* mode_set) (struct drm_encoder *encoder,struct drm_display_mode *mode,struct drm_display_mode *adjusted_mode);
  struct drm_crtc *(* get_crtc) (struct drm_encoder *encoder);
  enum drm_connector_status (* detect) (struct drm_encoder *encoder,struct drm_connector *connector);
  void (* disable) (struct drm_encoder *encoder);
  void (* enable) (struct drm_encoder *encoder);
  int (* atomic_check) (struct drm_encoder *encoder,struct drm_crtc_state *crtc_state,struct drm_connector_state *conn_state);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dpms</term>
      <listitem><para>
   set power state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>save</term>
      <listitem><para>
   save connector state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>restore</term>
      <listitem><para>
   restore connector state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_fixup</term>
      <listitem><para>
   try to fixup proposed mode for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>prepare</term>
      <listitem><para>
   part of the disable sequence, called before the CRTC modeset
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>commit</term>
      <listitem><para>
   called after the CRTC modeset
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_set</term>
      <listitem><para>
   set this mode, optional for atomic helpers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_crtc</term>
      <listitem><para>
   return CRTC that the encoder is currently attached to
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>detect</term>
      <listitem><para>
   connection status detection
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>disable</term>
      <listitem><para>
   disable encoder when not in use (overrides DPMS off)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>enable</term>
      <listitem><para>
   enable encoder
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_check</term>
      <listitem><para>
   check for validity of an atomic update
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The helper operations are called by the mid-layer CRTC helper.
   </para><para>

   Note that with atomic helpers <parameter>dpms</parameter>, <parameter>prepare</parameter> and <parameter>commit</parameter> hooks are
   deprecated. Used <parameter>enable</parameter> and <parameter>disable</parameter> instead exclusively.
   </para><para>

   With legacy crtc helpers there's a big semantic difference between <parameter>disable</parameter>
</para>
</refsect1>
<refsect1>
<title>and the other hooks</title>
<para>
   <parameter>disable</parameter> also needs to release any resources acquired in
   <parameter>mode_set</parameter> (like shared PLLs).
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-connector-helper-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_connector_helper_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_connector_helper_funcs</refname>
 <refpurpose>
     helper operations for connectors
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_connector_helper_funcs {
  int (* get_modes) (struct drm_connector *connector);
  enum drm_mode_status (* mode_valid) (struct drm_connector *connector,struct drm_display_mode *mode);
  struct drm_encoder *(* best_encoder) (struct drm_connector *connector);
  struct drm_encoder *(* atomic_best_encoder) (struct drm_connector *connector,struct drm_connector_state *connector_state);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>get_modes</term>
      <listitem><para>
   get mode list for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_valid</term>
      <listitem><para>
   is this mode valid on the given connector? (optional)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>best_encoder</term>
      <listitem><para>
   return the preferred encoder for this connector
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic_best_encoder</term>
      <listitem><para>
   atomic version of <parameter>best_encoder</parameter>
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The helper operations are called by the mid-layer CRTC helper.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_crtc_helper.c -->
<refentry id="API-drm-helper-move-panel-connectors-to-head">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_move_panel_connectors_to_head</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_move_panel_connectors_to_head</refname>
 <refpurpose>
  move panels to the front in the connector list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_helper_move_panel_connectors_to_head </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device to operate on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some userspace presumes that the first connected connector is the main
   display, where it's supposed to display e.g. the login screen. For
   laptops, this should be the main panel. Use this function to sort all
   (eDP/LVDS) panels to the front of the connector list, instead of
   painstakingly trying to initialize them in the right order.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-encoder-in-use">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_encoder_in_use</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_encoder_in_use</refname>
 <refpurpose>
     check if a given encoder is in use
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_helper_encoder_in_use </function></funcdef>
   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>encoder</parameter></term>
   <listitem>
    <para>
     encoder to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether <parameter>encoder</parameter> is with the current mode setting output configuration
   in use by any connector. This doesn't mean that it is actually enabled since
   the DPMS state is tracked separately.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if <parameter>encoder</parameter> is used, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-crtc-in-use">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_crtc_in_use</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_crtc_in_use</refname>
 <refpurpose>
     check if a given CRTC is in a mode_config
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_helper_crtc_in_use </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks whether <parameter>crtc</parameter> is with the current mode setting output configuration
   in use by any connector. This doesn't mean that it is actually enabled since
   the DPMS state is tracked separately.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if <parameter>crtc</parameter> is used, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-disable-unused-functions">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_disable_unused_functions</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_disable_unused_functions</refname>
 <refpurpose>
     disable unused objects
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_helper_disable_unused_functions </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function walks through the entire mode setting configuration of <parameter>dev</parameter>. It
   will remove any crtc links of unused encoders and encoder links of
   disconnected connectors. Then it will disable all unused encoders and crtcs
   either by calling their disable callback if available or by calling their
   dpms callback with DRM_MODE_DPMS_OFF.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-helper-set-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_helper_set_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_helper_set_mode</refname>
 <refpurpose>
     internal helper to set a mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_crtc_helper_set_mode </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>int <parameter>x</parameter></paramdef>
   <paramdef>int <parameter>y</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>old_fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC to program
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     horizontal offset into the surface
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>y</parameter></term>
   <listitem>
    <para>
     vertical offset into the surface
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_fb</parameter></term>
   <listitem>
    <para>
     old framebuffer, for cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Try to set <parameter>mode</parameter> on <parameter>crtc</parameter>.  Give <parameter>crtc</parameter> and its associated connectors a chance
   to fixup or reject the mode prior to trying to set it. This is an internal
   helper that drivers could e.g. use to update properties that require the
   entire output pipe to be disabled and re-enabled in a new configuration. For
   example for changing whether audio is enabled on a hdmi link or for changing
   panel fitter or dither attributes. It is also called by the
   <function>drm_crtc_helper_set_config</function> helper function to drive the mode setting
   sequence.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the mode was set successfully, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-helper-set-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_helper_set_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_helper_set_config</refname>
 <refpurpose>
     set a new config from userspace
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_crtc_helper_set_config </function></funcdef>
   <paramdef>struct drm_mode_set * <parameter>set</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>set</parameter></term>
   <listitem>
    <para>
     mode set configuration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Setup a new configuration, provided by the upper layers (either an ioctl call
   from userspace or internally e.g. from the fbdev support code) in <parameter>set</parameter>, and
   enable it. This is the main helper functions for drivers that implement
   kernel mode setting with the crtc helper functions and the assorted
   -&gt;<function>prepare</function>, -&gt;<function>modeset</function> and -&gt;<function>commit</function> helper callbacks.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Returns 0 on success, negative errno numbers on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-connector-dpms">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_connector_dpms</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_connector_dpms</refname>
 <refpurpose>
     connector dpms helper implementation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_helper_connector_dpms </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>int <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     affected connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     DPMS mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the main helper function provided by the crtc helper framework for
   implementing the DPMS connector attribute. It computes the new desired DPMS
   state for all encoders and crtcs in the output mesh and calls the -&gt;<function>dpms</function>
   callback provided by the driver appropriately.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Always returns 0.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-mode-fill-fb-struct">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_mode_fill_fb_struct</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_mode_fill_fb_struct</refname>
 <refpurpose>
     fill out framebuffer metadata
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_helper_mode_fill_fb_struct </function></funcdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>struct drm_mode_fb_cmd2 * <parameter>mode_cmd</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     drm_framebuffer object to fill out
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode_cmd</parameter></term>
   <listitem>
    <para>
     metadata from the userspace fb creation request
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This helper can be used in a drivers fb_create callback to pre-fill the fb's
   metadata fields.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-resume-force-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_resume_force_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_resume_force_mode</refname>
 <refpurpose>
     force-restore mode setting configuration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_helper_resume_force_mode </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device which should be restored
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers which use the mode setting helpers can use this function to
   force-restore the mode setting configuration e.g. on resume or when something
   else might have trampled over the hw state (like some overzealous old BIOSen
   tended to do).
   </para><para>

   This helper doesn't provide a error return value since restoring the old
   config should never fail due to resource allocation issues since the driver
   has successfully set the restored configuration already. Hence this should
   boil down to the equivalent of a few dpms on calls, which also don't provide
   an error code.
   </para><para>

   Drivers where simply restoring an old configuration again might fail (e.g.
   due to slight differences in allocating shared resources when the
   configuration is restored in a different order than when userspace set it up)
   need to use their own restore logic.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-crtc-mode-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_crtc_mode_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_crtc_mode_set</refname>
 <refpurpose>
     mode_set implementation for atomic plane helpers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_helper_crtc_mode_set </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>adjusted_mode</parameter></paramdef>
   <paramdef>int <parameter>x</parameter></paramdef>
   <paramdef>int <parameter>y</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>old_fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM CRTC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     DRM display mode which userspace requested
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adjusted_mode</parameter></term>
   <listitem>
    <para>
     DRM display mode adjusted by -&gt;mode_fixup callbacks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     x offset of the CRTC scanout area on the underlying framebuffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>y</parameter></term>
   <listitem>
    <para>
     y offset of the CRTC scanout area on the underlying framebuffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_fb</parameter></term>
   <listitem>
    <para>
     previous framebuffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function implements a callback useable as the -&gt;mode_set callback
   required by the crtc helpers. Besides the atomic plane helper functions for
   the primary plane the driver must also provide the -&gt;mode_set_nofb callback
   to set up the crtc.
   </para><para>

   This is a transitional helper useful for converting drivers to the atomic
   interfaces.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-crtc-mode-set-base">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_crtc_mode_set_base</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_crtc_mode_set_base</refname>
 <refpurpose>
     mode_set_base implementation for atomic plane helpers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_helper_crtc_mode_set_base </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>int <parameter>x</parameter></paramdef>
   <paramdef>int <parameter>y</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>old_fb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM CRTC
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>x</parameter></term>
   <listitem>
    <para>
     x offset of the CRTC scanout area on the underlying framebuffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>y</parameter></term>
   <listitem>
    <para>
     y offset of the CRTC scanout area on the underlying framebuffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>old_fb</parameter></term>
   <listitem>
    <para>
     previous framebuffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function implements a callback useable as the -&gt;mode_set_base used
   required by the crtc helpers. The driver must provide the atomic plane helper
   functions for the primary plane.
   </para><para>

   This is a transitional helper useful for converting drivers to the atomic
   interfaces.
</para>
</refsect1>
</refentry>

<para>
   </para><para>
   The CRTC modeset helper library provides a default set_config implementation
   in <function>drm_crtc_helper_set_config</function>. Plus a few other convenience functions using
   the same callbacks which drivers can use to e.g. restore the modeset
   configuration on resume with <function>drm_helper_resume_force_mode</function>.
   </para><para>
   The driver callbacks are mostly compatible with the atomic modeset helpers,
   except for the handling of the primary plane: Atomic helpers require that the
   primary plane is implemented as a real standalone plane and not directly tied
   to the CRTC state. For easier transition this library provides functions to
   implement the old semantics required by the CRTC helpers using the new plane
   and atomic helper callbacks.
   </para><para>
   Drivers are strongly urged to convert to the atomic helpers (by way of first
   converting to the plane helpers). New drivers must not use these functions
   but need to implement the atomic interface instead, potentially using the
   atomic helpers for that.
</para>

    </sect2>
    <sect2>
      <title>Output Probing Helper Functions Reference</title>
<para>
   </para><para>
   This library provides some helper code for output probing. It provides an
   implementation of the core connector-&gt;fill_modes interface with
   drm_helper_probe_single_connector_modes.
   </para><para>
   It also provides support for polling connectors with a work item and for
   generic hotplug interrupt handling where the driver doesn't or cannot keep
   track of a per-connector hpd interrupt.
   </para><para>
   This helper library can be used independently of the modeset helper library.
   Drivers can also overwrite different parts e.g. use their own hotplug
   handling code to avoid probing unrelated outputs.
</para>

<!-- drivers/gpu/drm/drm_probe_helper.c -->
<refentry id="API-drm-kms-helper-poll-enable-locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_kms_helper_poll_enable_locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_kms_helper_poll_enable_locked</refname>
 <refpurpose>
  re-enable output polling.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_kms_helper_poll_enable_locked </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function re-enables the output polling work without
   locking the mode_config mutex.
   </para><para>

   This is like <function>drm_kms_helper_poll_enable</function> however it is to be
   called from a context where the mode_config mutex is locked
   already.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-probe-single-connector-modes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_probe_single_connector_modes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_probe_single_connector_modes</refname>
 <refpurpose>
     get complete set of display modes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_helper_probe_single_connector_modes </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>uint32_t <parameter>maxX</parameter></paramdef>
   <paramdef>uint32_t <parameter>maxY</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to probe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxX</parameter></term>
   <listitem>
    <para>
     max width for modes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxY</parameter></term>
   <listitem>
    <para>
     max height for modes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Based on the helper callbacks implemented by <parameter>connector</parameter> try to detect all
   valid modes.  Modes will first be added to the connector's probed_modes list,
   then culled (based on validity and the <parameter>maxX</parameter>, <parameter>maxY</parameter> parameters) and put into
   the normal modes list.
   </para><para>

   Intended to be use as a generic implementation of the -&gt;<function>fill_modes</function>
   <parameter>connector</parameter> vfunc for drivers that use the crtc helpers for output mode
   filtering and detection.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The number of modes found on <parameter>connector</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-helper-probe-single-connector-modes-nomerge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_probe_single_connector_modes_nomerge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_probe_single_connector_modes_nomerge</refname>
 <refpurpose>
     get complete set of display modes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_helper_probe_single_connector_modes_nomerge </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>uint32_t <parameter>maxX</parameter></paramdef>
   <paramdef>uint32_t <parameter>maxY</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector to probe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxX</parameter></term>
   <listitem>
    <para>
     max width for modes
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>maxY</parameter></term>
   <listitem>
    <para>
     max height for modes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This operates like drm_hehlper_probe_single_connector_modes except it
   replaces the mode bits instead of merging them for preferred modes.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-kms-helper-hotplug-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_kms_helper_hotplug_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_kms_helper_hotplug_event</refname>
 <refpurpose>
     fire off KMS hotplug events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_kms_helper_hotplug_event </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device whose connector state changed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function fires off the uevent for userspace and also calls the
   output_poll_changed function, which is most commonly used to inform the fbdev
   emulation code and allow it to update the fbcon output configuration.
   </para><para>

   Drivers should call this from their hotplug handling code when a change is
   detected. Note that this function does not do any output detection of its
   own, like <function>drm_helper_hpd_irq_event</function> does - this is assumed to be done by the
   driver already.
   </para><para>

   This function must be called from process context with no mode
   setting locks held.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-kms-helper-poll-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_kms_helper_poll_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_kms_helper_poll_disable</refname>
 <refpurpose>
     disable output polling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_kms_helper_poll_disable </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function disables the output polling work.
   </para><para>

   Drivers can call this helper from their device suspend implementation. It is
   not an error to call this even when output polling isn't enabled or arlready
   disabled.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-kms-helper-poll-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_kms_helper_poll_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_kms_helper_poll_enable</refname>
 <refpurpose>
     re-enable output polling.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_kms_helper_poll_enable </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function re-enables the output polling work.
   </para><para>

   Drivers can call this helper from their device resume implementation. It is
   an error to call this when the output polling support has not yet been set
   up.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-kms-helper-poll-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_kms_helper_poll_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_kms_helper_poll_init</refname>
 <refpurpose>
     initialize and enable output polling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_kms_helper_poll_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function intializes and then also enables output polling support for
   <parameter>dev</parameter>. Drivers which do not have reliable hotplug support in hardware can use
   this helper infrastructure to regularly poll such connectors for changes in
   their connection state.
   </para><para>

   Drivers can control which connectors are polled by setting the
   DRM_CONNECTOR_POLL_CONNECT and DRM_CONNECTOR_POLL_DISCONNECT flags. On
   connectors where probing live outputs can result in visual distortion drivers
   should not set the DRM_CONNECTOR_POLL_DISCONNECT flag to avoid this.
   Connectors which have no flag or only DRM_CONNECTOR_POLL_HPD set are
   completely ignored by the polling logic.
   </para><para>

   Note that a connector can be both polled and probed from the hotplug handler,
   in case the hotplug interrupt is known to be unreliable.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-kms-helper-poll-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_kms_helper_poll_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_kms_helper_poll_fini</refname>
 <refpurpose>
     disable output polling and clean it up
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_kms_helper_poll_fini </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-helper-hpd-irq-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_helper_hpd_irq_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_helper_hpd_irq_event</refname>
 <refpurpose>
     hotplug processing
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_helper_hpd_irq_event </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers can use this helper function to run a detect cycle on all connectors
   which have the DRM_CONNECTOR_POLL_HPD flag set in their <structname>polled</structname> member. All
   other connectors are ignored, which is useful to avoid reprobing fixed
   panels.
   </para><para>

   This helper function is useful for drivers which can't or don't track hotplug
   interrupts for each connector.
   </para><para>

   Drivers which support hotplug interrupts for each connector individually and
   which have a more fine-grained detect logic should bypass this code and
   directly call <function>drm_kms_helper_hotplug_event</function> in case the connector state
   changed.
   </para><para>

   This function must be called from process context with no mode
   setting locks held.
   </para><para>

   Note that a connector can be both polled and probed from the hotplug handler,
   in case the hotplug interrupt is known to be unreliable.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>fbdev Helper Functions Reference</title>
<para>
   </para><para>
   The fb helper functions are useful to provide an fbdev on top of a drm kernel
   mode setting driver. They can be used mostly independently from the crtc
   helper functions used by many drivers to implement the kernel mode setting
   interfaces.
   </para><para>
   Initialization is done as a four-step process with <function>drm_fb_helper_prepare</function>,
   <function>drm_fb_helper_init</function>, <function>drm_fb_helper_single_add_all_connectors</function> and
   <function>drm_fb_helper_initial_config</function>. Drivers with fancier requirements than the
   default behaviour can override the third step with their own code.
   Teardown is done with <function>drm_fb_helper_fini</function>.
   </para><para>
   At runtime drivers should restore the fbdev console by calling
   <function>drm_fb_helper_restore_fbdev_mode_unlocked</function> from their -&gt;lastclose callback.
   They should also notify the fb helper code from updates to the output
   configuration by calling <function>drm_fb_helper_hotplug_event</function>. For easier
   integration with the output polling code in drm_crtc_helper.c the modeset
   code provides a -&gt;output_poll_changed callback.
   </para><para>
   All other functions exported by the fb helper library can be used to
   implement the fbdev driver interface by the driver.
   </para><para>
   It is possible, though perhaps somewhat tricky, to implement race-free
   hotplug detection using the fbdev helpers. The <function>drm_fb_helper_prepare</function>
   helper must be called first to initialize the minimum required to make
   hotplug detection work. Drivers also need to make sure to properly set up
   the dev-&gt;mode_config.funcs member. After calling <function>drm_kms_helper_poll_init</function>
   it is safe to enable interrupts and start processing hotplug events. At the
   same time, drivers should initialize all modeset objects such as CRTCs,
   encoders and connectors. To finish up the fbdev helper initialization, the
   <function>drm_fb_helper_init</function> function is called. To probe for all attached displays
   and set up an initial configuration using the detected hardware, drivers
   should call <function>drm_fb_helper_single_add_all_connectors</function> followed by
   <function>drm_fb_helper_initial_config</function>.
</para>

<!-- drivers/gpu/drm/drm_fb_helper.c -->
<refentry id="API-drm-fb-helper-single-add-all-connectors">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_single_add_all_connectors</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_single_add_all_connectors</refname>
 <refpurpose>
  add all connectors to fbdev emulation helper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_single_add_all_connectors </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     fbdev initialized with drm_fb_helper_init
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions adds all the available connectors for use with the given
   fb_helper. This is a separate step to allow drivers to freely assign
   connectors to the fbdev, e.g. if some are reserved for special purposes or
   not adequate to be used for the fbcon.
   </para><para>

   This function is protected against concurrent connector hotadds/removals
   using <function>drm_fb_helper_add_one_connector</function> and
   <function>drm_fb_helper_remove_one_connector</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-debug-enter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_debug_enter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_debug_enter</refname>
 <refpurpose>
     implementation for -&gt;fb_debug_enter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_debug_enter </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-debug-leave">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_debug_leave</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_debug_leave</refname>
 <refpurpose>
     implementation for -&gt;fb_debug_leave
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_debug_leave </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-restore-fbdev-mode-unlocked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_restore_fbdev_mode_unlocked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_restore_fbdev_mode_unlocked</refname>
 <refpurpose>
     restore fbdev configuration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_restore_fbdev_mode_unlocked </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     fbcon to restore
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be called from driver's drm -&gt;lastclose callback
   when implementing an fbcon on top of kms using this helper. This ensures that
   the user isn't greeted with a black screen when e.g. X dies.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero if everything went ok, negative error code otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-blank">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_blank</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_blank</refname>
 <refpurpose>
     implementation for -&gt;fb_blank
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_blank </function></funcdef>
   <paramdef>int <parameter>blank</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>blank</parameter></term>
   <listitem>
    <para>
     desired blanking state
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-prepare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_prepare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_prepare</refname>
 <refpurpose>
     setup a drm_fb_helper structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_prepare </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_fb_helper * <parameter>helper</parameter></paramdef>
   <paramdef>const struct drm_fb_helper_funcs * <parameter>funcs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper structure to set up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     pointer to structure of functions associate with this helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets up the bare minimum to make the framebuffer helper usable. This is
   useful to implement race-free initialization of the polling helpers.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_init</refname>
 <refpurpose>
     initialize a drm_fb_helper structure
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
   <paramdef>int <parameter>crtc_count</parameter></paramdef>
   <paramdef>int <parameter>max_conn_count</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper structure to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_count</parameter></term>
   <listitem>
    <para>
     maximum number of crtcs to support in this fbdev emulation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_conn_count</parameter></term>
   <listitem>
    <para>
     max connector count
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This allocates the structures for the fbdev helper with the given limits.
   Note that this won't yet touch the hardware (through the driver interfaces)
   nor register the fbdev. This is only done in <function>drm_fb_helper_initial_config</function>
   to allow driver writes more control over the exact init sequence.
   </para><para>

   Drivers must call <function>drm_fb_helper_prepare</function> before calling this function.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero if everything went ok, nonzero otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-alloc-fbi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_alloc_fbi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_alloc_fbi</refname>
 <refpurpose>
     allocate fb_info and some of its members
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct fb_info * <function>drm_fb_helper_alloc_fbi </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A helper to alloc fb_info and the members cmap and apertures. Called
   by the driver within the fb_probe fb_helper callback function.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   fb_info pointer if things went okay, pointer containing error code
   otherwise
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-unregister-fbi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_unregister_fbi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_unregister_fbi</refname>
 <refpurpose>
     unregister fb_info framebuffer device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_unregister_fbi </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around unregister_framebuffer, to release the fb_info
   framebuffer device
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-release-fbi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_release_fbi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_release_fbi</refname>
 <refpurpose>
     dealloc fb_info and its members
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_release_fbi </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A helper to free memory taken by fb_info and the members cmap and
   apertures
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-unlink-fbi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_unlink_fbi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_unlink_fbi</refname>
 <refpurpose>
     wrapper around unlink_framebuffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_unlink_fbi </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around unlink_framebuffer implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-sys-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_sys_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_sys_read</refname>
 <refpurpose>
     wrapper around fb_sys_read
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>drm_fb_helper_sys_read </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>char __user * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fb_info struct pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     userspace buffer to read from framebuffer memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to read from framebuffer memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     read offset within framebuffer memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around fb_sys_read implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-sys-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_sys_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_sys_write</refname>
 <refpurpose>
     wrapper around fb_sys_write
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>drm_fb_helper_sys_write </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const char __user * <parameter>buf</parameter></paramdef>
   <paramdef>size_t <parameter>count</parameter></paramdef>
   <paramdef>loff_t * <parameter>ppos</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fb_info struct pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buf</parameter></term>
   <listitem>
    <para>
     userspace buffer to write to framebuffer memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>count</parameter></term>
   <listitem>
    <para>
     number of bytes to write to framebuffer memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ppos</parameter></term>
   <listitem>
    <para>
     write offset within framebuffer memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around fb_sys_write implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-sys-fillrect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_sys_fillrect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_sys_fillrect</refname>
 <refpurpose>
     wrapper around sys_fillrect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_sys_fillrect </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_fillrect * <parameter>rect</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rect</parameter></term>
   <listitem>
    <para>
     info about rectangle to fill
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around sys_fillrect implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-sys-copyarea">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_sys_copyarea</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_sys_copyarea</refname>
 <refpurpose>
     wrapper around sys_copyarea
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_sys_copyarea </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_copyarea * <parameter>area</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>area</parameter></term>
   <listitem>
    <para>
     info about area to copy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around sys_copyarea implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-sys-imageblit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_sys_imageblit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_sys_imageblit</refname>
 <refpurpose>
     wrapper around sys_imageblit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_sys_imageblit </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_image * <parameter>image</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>image</parameter></term>
   <listitem>
    <para>
     info about image to blit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around sys_imageblit implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-cfb-fillrect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_cfb_fillrect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_cfb_fillrect</refname>
 <refpurpose>
     wrapper around cfb_fillrect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_cfb_fillrect </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_fillrect * <parameter>rect</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rect</parameter></term>
   <listitem>
    <para>
     info about rectangle to fill
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around cfb_imageblit implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-cfb-copyarea">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_cfb_copyarea</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_cfb_copyarea</refname>
 <refpurpose>
     wrapper around cfb_copyarea
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_cfb_copyarea </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_copyarea * <parameter>area</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>area</parameter></term>
   <listitem>
    <para>
     info about area to copy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around cfb_copyarea implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-cfb-imageblit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_cfb_imageblit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_cfb_imageblit</refname>
 <refpurpose>
     wrapper around cfb_imageblit
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_cfb_imageblit </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>const struct fb_image * <parameter>image</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>image</parameter></term>
   <listitem>
    <para>
     info about image to blit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around cfb_imageblit implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-set-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_set_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_set_suspend</refname>
 <refpurpose>
     wrapper around fb_set_suspend
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_set_suspend </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
   <paramdef>int <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     driver-allocated fbdev helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     desired state, zero to resume, non-zero to suspend
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A wrapper around fb_set_suspend implemented by fbdev core
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-setcmap">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_setcmap</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_setcmap</refname>
 <refpurpose>
     implementation for -&gt;fb_setcmap
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_setcmap </function></funcdef>
   <paramdef>struct fb_cmap * <parameter>cmap</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>cmap</parameter></term>
   <listitem>
    <para>
     cmap to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-check-var">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_check_var</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_check_var</refname>
 <refpurpose>
     implementation for -&gt;fb_check_var
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_check_var </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     screeninfo to check
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-set-par">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_set_par</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_set_par</refname>
 <refpurpose>
     implementation for -&gt;fb_set_par
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_set_par </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will let fbcon do the mode init and is called at initialization time by
   the fbdev core when registering the driver, and later on through the hotplug
   callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-pan-display">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_pan_display</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_pan_display</refname>
 <refpurpose>
     implementation for -&gt;fb_pan_display
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_pan_display </function></funcdef>
   <paramdef>struct fb_var_screeninfo * <parameter>var</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>var</parameter></term>
   <listitem>
    <para>
     updated screen information
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-fill-fix">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_fill_fix</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_fill_fix</refname>
 <refpurpose>
     initializes fixed fbdev information
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_fill_fix </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>uint32_t <parameter>pitch</parameter></paramdef>
   <paramdef>uint32_t <parameter>depth</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev registered by the helper
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pitch</parameter></term>
   <listitem>
    <para>
     desired pitch
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>depth</parameter></term>
   <listitem>
    <para>
     desired depth
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper to fill in the fixed fbdev information useful for a non-accelerated
   fbdev emulations. Drivers which support acceleration methods which impose
   additional constraints need to set up their own limits.
   </para><para>

   Drivers should call this (or their equivalent setup code) from their
   -&gt;fb_probe callback.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-fill-var">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_fill_var</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_fill_var</refname>
 <refpurpose>
     initalizes variable fbdev information
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_fb_helper_fill_var </function></funcdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
   <paramdef>uint32_t <parameter>fb_width</parameter></paramdef>
   <paramdef>uint32_t <parameter>fb_height</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     fbdev instance to set up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     fb helper instance to use as template
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb_width</parameter></term>
   <listitem>
    <para>
     desired fb width
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb_height</parameter></term>
   <listitem>
    <para>
     desired fb height
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets up the variable fbdev metainformation from the given fb helper instance
   and the drm framebuffer allocated in fb_helper-&gt;fb.
   </para><para>

   Drivers should call this (or their equivalent setup code) from their
   -&gt;fb_probe callback after having allocated the fbdev backing
   storage framebuffer.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-initial-config">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_initial_config</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_initial_config</refname>
 <refpurpose>
     setup a sane initial connector configuration
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_initial_config </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
   <paramdef>int <parameter>bpp_sel</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     fb_helper device struct
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bpp_sel</parameter></term>
   <listitem>
    <para>
     bpp value to use for the framebuffer configuration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scans the CRTCs and connectors and tries to put together an initial setup.
   At the moment, this is a cloned configuration across all heads with
   a new framebuffer object as the backing store.
   </para><para>

   Note that this also registers the fbdev and so allows userspace to call into
   the driver through the fbdev interfaces.
   </para><para>

   This function will call down into the -&gt;fb_probe callback to let
   the driver allocate and initialize the fbdev info structure and the drm
   framebuffer used to back the fbdev. <function>drm_fb_helper_fill_var</function> and
   <function>drm_fb_helper_fill_fix</function> are provided as helpers to setup simple default
   values for the fbdev info structure.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero if everything went ok, nonzero otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-fb-helper-hotplug-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_fb_helper_hotplug_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_fb_helper_hotplug_event</refname>
 <refpurpose>
     respond to a hotplug notification by probing all the outputs attached to the fb
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_fb_helper_hotplug_event </function></funcdef>
   <paramdef>struct drm_fb_helper * <parameter>fb_helper</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>fb_helper</parameter></term>
   <listitem>
    <para>
     the drm_fb_helper
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Scan the connectors attached to the fb_helper and try to put together a
   setup after *notification of a change in output configuration.
   </para><para>

   Called at runtime, takes the mode config locks to be able to check/change the
   modeset configuration. Must be run from process context (which usually means
   either the output polling work or a work item launched from the driver's
   hotplug interrupt).
   </para><para>

   Note that drivers may call this even before calling
   drm_fb_helper_initial_config but only aftert drm_fb_helper_init. This allows
   for a race-free fbcon setup and will make sure that the fbdev emulation will
   not miss any hotplug events.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   0 on success and a non-zero error code otherwise.
</para>
</refsect1>
</refentry>

<!-- include/drm/drm_fb_helper.h -->
<refentry id="API-struct-drm-fb-helper-surface-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_fb_helper_surface_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_fb_helper_surface_size</refname>
 <refpurpose>
  describes fbdev size and scanout surface size
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_fb_helper_surface_size {
  u32 fb_width;
  u32 fb_height;
  u32 surface_width;
  u32 surface_height;
  u32 surface_bpp;
  u32 surface_depth;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>fb_width</term>
      <listitem><para>
fbdev width
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb_height</term>
      <listitem><para>
fbdev height
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>surface_width</term>
      <listitem><para>
scanout buffer width
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>surface_height</term>
      <listitem><para>
scanout buffer height
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>surface_bpp</term>
      <listitem><para>
scanout buffer bpp
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>surface_depth</term>
      <listitem><para>
scanout buffer depth
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that the scanout surface width/height may be larger than the fbdev
   width/height.  In case of multiple displays, the scanout surface is sized
   according to the largest width/height (so it is large enough for all CRTCs
   to scanout).  But the fbdev width/height is sized to the minimum width/
   height of all the displays.  This ensures that fbcon fits on the smallest
   of the attached displays.
   </para><para>

   So what is passed to <function>drm_fb_helper_fill_var</function> should be fb_width/fb_height,
   rather than the surface size.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-fb-helper-funcs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_fb_helper_funcs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_fb_helper_funcs</refname>
 <refpurpose>
     driver callbacks for the fbdev emulation library
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_fb_helper_funcs {
  void (* gamma_set) (struct drm_crtc *crtc, u16 red, u16 green,u16 blue, int regno);
  void (* gamma_get) (struct drm_crtc *crtc, u16 *red, u16 *green,u16 *blue, int regno);
  int (* fb_probe) (struct drm_fb_helper *helper,struct drm_fb_helper_surface_size *sizes);
  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);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>gamma_set</term>
      <listitem><para>
   Set the given gamma lut register on the given crtc.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>gamma_get</term>
      <listitem><para>
   Read the given gamma lut register on the given crtc, used to
   save the current lut when force-restoring the fbdev for e.g.
   kdbg.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb_probe</term>
      <listitem><para>
   Driver callback to allocate and initialize the fbdev info
   structure. Furthermore it also needs to allocate the drm
   framebuffer used to back the fbdev.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>initial_config</term>
      <listitem><para>
   Setup an initial fbdev display configuration
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Driver callbacks used by the fbdev emulation helper library.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-fb-helper">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_fb_helper</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_fb_helper</refname>
 <refpurpose>
     helper to emulate fbdev on top of kms
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_fb_helper {
  struct drm_framebuffer * fb;
  struct drm_device * dev;
  int crtc_count;
  struct drm_fb_helper_crtc * crtc_info;
  int connector_count;
  int connector_info_alloc_count;
  const struct drm_fb_helper_funcs * funcs;
  struct fb_info * fbdev;
  u32 pseudo_palette[17];
  struct list_head kernel_fb_list;
  bool delayed_hotplug;
  bool atomic;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>fb</term>
      <listitem><para>
   Scanout framebuffer object
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   DRM device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_count</term>
      <listitem><para>
   number of possible CRTCs
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>crtc_info</term>
      <listitem><para>
   per-CRTC helper state (mode, x/y offset, etc)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector_count</term>
      <listitem><para>
   number of connected connectors
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector_info_alloc_count</term>
      <listitem><para>
   size of connector_info
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>funcs</term>
      <listitem><para>
   driver callbacks for fb helper
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fbdev</term>
      <listitem><para>
   emulated fbdev device info struct
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pseudo_palette[17]</term>
      <listitem><para>
   fake palette of 16 colors
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>kernel_fb_list</term>
      <listitem><para>
   list_head in kernel_fb_helper_list
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delayed_hotplug</term>
      <listitem><para>
   was there a hotplug while kms master active?
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>atomic</term>
      <listitem><para>
   </para><para>

   Use atomic updates for <function>restore_fbdev_mode</function>, etc.  This defaults to
   true if driver has DRIVER_ATOMIC feature flag, but drivers can
   override it to true after <function>drm_fb_helper_init</function> if they support atomic
   modeset but do not yet advertise DRIVER_ATOMIC (note that fb-helper
   does not require ASYNC commits).
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Display Port Helper Functions Reference</title>
<para>
   </para><para>
   These functions contain some common logic and helpers at various abstraction
   levels to deal with Display Port sink devices and related things like DP aux
   channel transfers, EDID reading over DP aux channels, decoding certain DPCD
   blocks, ...
</para>

<para>
   </para><para>
   The DisplayPort AUX channel is an abstraction to allow generic, driver-
   independent access to AUX functionality. Drivers can take advantage of
   this by filling in the fields of the drm_dp_aux structure.
   </para><para>
   Transactions are described using a hardware-independent drm_dp_aux_msg
   structure, which is passed into a driver's .<function>transfer</function> implementation.
   Both native and I2C-over-AUX transactions are supported.
</para>

<!-- include/drm/drm_dp_helper.h -->
<refentry id="API-struct-drm-dp-aux-msg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_dp_aux_msg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_dp_aux_msg</refname>
 <refpurpose>
  DisplayPort AUX channel transaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_dp_aux_msg {
  unsigned int address;
  u8 request;
  u8 reply;
  void * buffer;
  size_t size;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>address</term>
      <listitem><para>
address of the (first) register to access
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>request</term>
      <listitem><para>
contains the type of transaction (see DP_AUX_* macros)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reply</term>
      <listitem><para>
upon completion, contains the reply type of the transaction
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>buffer</term>
      <listitem><para>
pointer to a transmission or reception buffer
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>size</term>
      <listitem><para>
size of <parameter>buffer</parameter>
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-dp-aux">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_dp_aux</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_dp_aux</refname>
 <refpurpose>
     DisplayPort AUX channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_dp_aux {
  const char * name;
  struct i2c_adapter ddc;
  struct device * dev;
  struct mutex hw_mutex;
  ssize_t (* transfer) (struct drm_dp_aux *aux,struct drm_dp_aux_msg *msg);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   user-visible name of this AUX channel and the I2C-over-AUX adapter
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ddc</term>
      <listitem><para>
   I2C adapter that can be used for I2C-over-AUX communication
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   pointer to struct device that is the parent for this AUX channel
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>hw_mutex</term>
      <listitem><para>
   internal mutex used for locking transfers
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer</term>
      <listitem><para>
   transfers a message representing a single AUX transaction
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   The .dev field should be set to a pointer to the device that implements
   the AUX channel.
   </para><para>

   The .name field may be used to specify the name of the I2C adapter. If set to
   NULL, <function>dev_name</function> of .dev will be used.
   </para><para>

   Drivers provide a hardware-specific implementation of how transactions
   are executed via the .<function>transfer</function> function. A pointer to a drm_dp_aux_msg
   structure describing the transaction is passed into this function. Upon
   success, the implementation should return the number of payload bytes
   that were transferred, or a negative error-code on failure. Helpers
   propagate errors from the .<function>transfer</function> function, with the exception of
   the -EBUSY error, which causes a transaction to be retried. On a short,
   helpers will return -EPROTO to make it simpler to check for failure.
   </para><para>

   An AUX channel can also be used to transport I2C messages to a sink. A
   typical application of that is to access an EDID that's present in the
   sink device. The .<function>transfer</function> function can also be used to execute such
   transactions. The <function>drm_dp_aux_register</function> function registers an I2C
   adapter that can be passed to <function>drm_probe_ddc</function>. Upon removal, drivers
   should call <function>drm_dp_aux_unregister</function> to remove the I2C adapter.
   The I2C adapter uses long transfers by default; if a partial response is
   received, the adapter will drop down to the size given by the partial
   response for this transaction only.
   </para><para>

   Note that the aux helper code assumes that the .<function>transfer</function> function
   only modifies the reply field of the drm_dp_aux_msg structure.  The
   retry logic and i2c helpers assume this is the case.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-dpcd-readb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_dpcd_readb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_dpcd_readb</refname>
 <refpurpose>
     read a single byte from the DPCD
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>drm_dp_dpcd_readb </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
   <paramdef>u8 * <parameter>valuep</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     address of the register to read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>valuep</parameter></term>
   <listitem>
    <para>
     location where the value of the register will be stored
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes transferred (1) on success, or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-dpcd-writeb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_dpcd_writeb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_dpcd_writeb</refname>
 <refpurpose>
     write a single byte to the DPCD
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>drm_dp_dpcd_writeb </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
   <paramdef>u8 <parameter>value</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     address of the register to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>value</parameter></term>
   <listitem>
    <para>
     value to write to the register
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes transferred (1) on success, or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_dp_helper.c -->
<refentry id="API-drm-dp-dpcd-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_dpcd_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_dpcd_read</refname>
 <refpurpose>
  read a series of bytes from the DPCD
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>drm_dp_dpcd_read </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     address of the (first) register to read
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     buffer to store the register values
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     number of bytes in <parameter>buffer</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes transferred on success, or a negative error
   code on failure. -EIO is returned if the request was NAKed by the sink or
   if the retry count was exceeded. If not all bytes were transferred, this
   function returns -EPROTO. Errors from the underlying AUX channel transfer
   function, with the exception of -EBUSY (which causes the transaction to
   be retried), are propagated to the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-dpcd-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_dpcd_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_dpcd_write</refname>
 <refpurpose>
     write a series of bytes to the DPCD
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>drm_dp_dpcd_write </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>unsigned int <parameter>offset</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     address of the (first) register to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     buffer containing the values to write
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     number of bytes in <parameter>buffer</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes transferred on success, or a negative error
   code on failure. -EIO is returned if the request was NAKed by the sink or
   if the retry count was exceeded. If not all bytes were transferred, this
   function returns -EPROTO. Errors from the underlying AUX channel transfer
   function, with the exception of -EBUSY (which causes the transaction to
   be retried), are propagated to the caller.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-dpcd-read-link-status">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_dpcd_read_link_status</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_dpcd_read_link_status</refname>
 <refpurpose>
     read DPCD link status (bytes 0x202-0x207)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_dpcd_read_link_status </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>u8 <parameter>status[DP_LINK_STATUS_SIZE]</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>status[DP_LINK_STATUS_SIZE]</parameter></term>
   <listitem>
    <para>
     buffer to store the link status in (must be at least 6 bytes)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the number of bytes transferred on success or a negative error
   code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-link-probe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_link_probe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_link_probe</refname>
 <refpurpose>
     probe a DisplayPort link for capabilities
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_link_probe </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>link</parameter></term>
   <listitem>
    <para>
     pointer to structure in which to return link capabilities
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The structure filled in by this function can usually be passed directly
   into <function>drm_dp_link_power_up</function> and <function>drm_dp_link_configure</function> to power up and
   configure the link based on the link's capabilities.
   </para><para>

   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-link-power-up">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_link_power_up</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_link_power_up</refname>
 <refpurpose>
     power up a DisplayPort link
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_link_power_up </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>link</parameter></term>
   <listitem>
    <para>
     pointer to a structure containing the link configuration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-link-power-down">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_link_power_down</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_link_power_down</refname>
 <refpurpose>
     power down a DisplayPort link
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_link_power_down </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>link</parameter></term>
   <listitem>
    <para>
     pointer to a structure containing the link configuration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-link-configure">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_link_configure</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_link_configure</refname>
 <refpurpose>
     configure a DisplayPort link
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_link_configure </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>struct drm_dp_link * <parameter>link</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>link</parameter></term>
   <listitem>
    <para>
     pointer to a structure containing the link configuration
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-aux-register">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_aux_register</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_aux_register</refname>
 <refpurpose>
     initialise and register aux channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_aux_register </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-aux-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_aux_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_aux_unregister</refname>
 <refpurpose>
     unregister an AUX adapter
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dp_aux_unregister </function></funcdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DisplayPort AUX channel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Display Port MST Helper Functions Reference</title>
<para>
   </para><para>
   These functions contain parts of the DisplayPort 1.2a MultiStream Transport
   protocol. The helpers contain a topology manager and bandwidth manager.
   The helpers encapsulate the sending and received of sideband msgs.
</para>

<!-- include/drm/drm_dp_mst_helper.h -->
<refentry id="API-struct-drm-dp-vcpi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_dp_vcpi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_dp_vcpi</refname>
 <refpurpose>
  Virtual Channel Payload Identifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_dp_vcpi {
  int vcpi;
  int pbn;
  int aligned_pbn;
  int num_slots;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>vcpi</term>
      <listitem><para>
Virtual channel ID.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pbn</term>
      <listitem><para>
Payload Bandwidth Number for this channel
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>aligned_pbn</term>
      <listitem><para>
PBN aligned with slot size
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_slots</term>
      <listitem><para>
number of slots for this PBN
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-dp-mst-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_dp_mst_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_dp_mst_port</refname>
 <refpurpose>
     MST port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_dp_mst_port {
  struct kref kref;
  u8 port_num;
  bool input;
  bool mcs;
  bool ddps;
  u8 pdt;
  bool ldps;
  u8 dpcd_rev;
  u8 num_sdp_streams;
  u8 num_sdp_stream_sinks;
  uint16_t available_pbn;
  struct list_head next;
  struct drm_dp_mst_branch * mstb;
  struct drm_dp_aux aux;
  struct drm_dp_mst_branch * parent;
  struct drm_dp_vcpi vcpi;
  struct drm_connector * connector;
  struct drm_dp_mst_topology_mgr * mgr;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>kref</term>
      <listitem><para>
   reference count for this port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port_num</term>
      <listitem><para>
   port number
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>input</term>
      <listitem><para>
   if this port is an input port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mcs</term>
      <listitem><para>
   message capability status - DP 1.2 spec.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ddps</term>
      <listitem><para>
   DisplayPort Device Plug Status - DP 1.2
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pdt</term>
      <listitem><para>
   Peer Device Type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ldps</term>
      <listitem><para>
   Legacy Device Plug Status
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dpcd_rev</term>
      <listitem><para>
   DPCD revision of device on this port
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_sdp_streams</term>
      <listitem><para>
   Number of simultaneous streams
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_sdp_stream_sinks</term>
      <listitem><para>
   Number of stream sinks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>available_pbn</term>
      <listitem><para>
   Available bandwidth for this port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>next</term>
      <listitem><para>
   link to next port on this branch device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mstb</term>
      <listitem><para>
   branch device attach below this port
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>aux</term>
      <listitem><para>
   i2c aux transport to talk to device connected to this port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>parent</term>
      <listitem><para>
   branch device parent of this port
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>vcpi</term>
      <listitem><para>
   Virtual Channel Payload info for this port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>connector</term>
      <listitem><para>
   DRM connector this port is connected to.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mgr</term>
      <listitem><para>
   topology manager this port lives under.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure represents an MST port endpoint on a device somewhere
   in the MST topology.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-dp-mst-branch">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_dp_mst_branch</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_dp_mst_branch</refname>
 <refpurpose>
     MST branch device.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_dp_mst_branch {
  struct kref kref;
  u8 rad[8];
  u8 lct;
  int num_ports;
  int msg_slots;
  struct list_head ports;
  struct drm_dp_mst_port * port_parent;
  struct drm_dp_mst_topology_mgr * mgr;
  struct drm_dp_sideband_msg_tx * tx_slots[2];
  int last_seqno;
  bool link_address_sent;
  u8 guid[16];
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>kref</term>
      <listitem><para>
   reference count for this port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rad[8]</term>
      <listitem><para>
   Relative Address to talk to this branch device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lct</term>
      <listitem><para>
   Link count total to talk to this branch device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>num_ports</term>
      <listitem><para>
   number of ports on the branch.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>msg_slots</term>
      <listitem><para>
   one bit per transmitted msg slot.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ports</term>
      <listitem><para>
   linked list of ports on this branch.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>port_parent</term>
      <listitem><para>
   pointer to the port parent, NULL if toplevel.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mgr</term>
      <listitem><para>
   topology manager for this branch device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_slots[2]</term>
      <listitem><para>
   transmission slots for this device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>last_seqno</term>
      <listitem><para>
   last sequence number used to talk to this.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>link_address_sent</term>
      <listitem><para>
   if a link address message has been sent to this device yet.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>guid[16]</term>
      <listitem><para>
   guid for DP 1.2 branch device. port under this branch can be
   identified by port #.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This structure represents an MST branch device, there is one
   primary branch device at the root, along with any other branches connected
   to downstream port of parent branches.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-drm-dp-mst-topology-mgr">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_dp_mst_topology_mgr</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_dp_mst_topology_mgr</refname>
 <refpurpose>
     DisplayPort MST manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_dp_mst_topology_mgr {
  struct device * dev;
  struct drm_dp_mst_topology_cbs * cbs;
  struct drm_dp_aux * aux;
  int max_payloads;
  int conn_base_id;
  struct drm_dp_sideband_msg_rx down_rep_recv;
  struct drm_dp_sideband_msg_rx up_req_recv;
  struct mutex lock;
  bool mst_state;
  struct drm_dp_mst_branch * mst_primary;
  u8 dpcd[DP_RECEIVER_CAP_SIZE];
  int pbn_div;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   device pointer for adding i2c devices etc.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>cbs</term>
      <listitem><para>
   callbacks for connector addition and destruction.
   <parameter>max_dpcd_transaction_bytes</parameter> - maximum number of bytes to read/write in one go.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>aux</term>
      <listitem><para>
   aux channel for the DP connector.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>max_payloads</term>
      <listitem><para>
   maximum number of payloads the GPU can generate.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>conn_base_id</term>
      <listitem><para>
   DRM connector ID this mgr is connected to.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>down_rep_recv</term>
      <listitem><para>
   msg receiver state for down replies.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>up_req_recv</term>
      <listitem><para>
   msg receiver state for up requests.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   protects mst state, primary, dpcd.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mst_state</term>
      <listitem><para>
   if this manager is enabled for an MST capable port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mst_primary</term>
      <listitem><para>
   pointer to the primary branch device.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dpcd[DP_RECEIVER_CAP_SIZE]</term>
      <listitem><para>
   cache of DPCD for primary port.
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pbn_div</term>
      <listitem><para>
   PBN to slots divisor.
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This struct represents the toplevel displayport MST topology manager.
   There should be one instance of this for every MST capable DP connector
   on the GPU.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_dp_mst_topology.c -->
<refentry id="API-drm-dp-update-payload-part1">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_update_payload_part1</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_update_payload_part1</refname>
 <refpurpose>
  Execute payload update part 1
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_update_payload_part1 </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to use.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This iterates over all proposed virtual channels, and tries to
   allocate space in the link for them. For 0-&gt;slots transitions,
   this step just writes the VCPI to the MST device. For slots-&gt;0
   transitions, this writes the updated VCPIs and removes the
   remote VC payloads.
   </para><para>

   after calling this the driver should generate ACT and payload
   packets.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-update-payload-part2">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_update_payload_part2</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_update_payload_part2</refname>
 <refpurpose>
     Execute payload update part 2
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_update_payload_part2 </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to use.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This iterates over all proposed virtual channels, and tries to
   allocate space in the link for them. For 0-&gt;slots transitions,
   this step writes the remote VC payload commands. For slots-&gt;0
   this just resets some internal state.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-topology-mgr-set-mst">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_topology_mgr_set_mst</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_topology_mgr_set_mst</refname>
 <refpurpose>
     Set the MST state for a topology manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_mst_topology_mgr_set_mst </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>bool <parameter>mst_state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to set state for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mst_state</parameter></term>
   <listitem>
    <para>
     true to enable MST on this connector - false to disable.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is called by the driver when it detects an MST capable device plugged
   into a DP MST capable port, or when a DP MST capable device is unplugged.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-topology-mgr-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_topology_mgr_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_topology_mgr_suspend</refname>
 <refpurpose>
     suspend the MST manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dp_mst_topology_mgr_suspend </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to suspend
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function tells the MST device that we can't handle UP messages
   anymore. This should stop it from sending any since we are suspended.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-topology-mgr-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_topology_mgr_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_topology_mgr_resume</refname>
 <refpurpose>
     resume the MST manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_mst_topology_mgr_resume </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to resume
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will fetch DPCD and see if the device is still there,
   if it is, it will rewrite the MSTM control bits, and return.
   </para><para>

   if the device fails this returns -1, and the driver should do
   a full MST reprobe, in case we were undocked.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-hpd-irq">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_hpd_irq</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_hpd_irq</refname>
 <refpurpose>
     MST hotplug IRQ notify
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_mst_hpd_irq </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>u8 * <parameter>esi</parameter></paramdef>
   <paramdef>bool * <parameter>handled</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to notify irq for.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>esi</parameter></term>
   <listitem>
    <para>
     4 bytes from SINK_COUNT_ESI
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>handled</parameter></term>
   <listitem>
    <para>
     whether the hpd interrupt was consumed or not
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This should be called from the driver when it detects a short IRQ,
   along with the value of the DEVICE_SERVICE_IRQ_VECTOR_ESI0. The
   topology manager will process the sideband messages received as a result
   of this.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-detect-port">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_detect_port</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_detect_port</refname>
 <refpurpose>
     get connection status for an MST port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum drm_connector_status <function>drm_dp_mst_detect_port </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     -- undescribed --
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     unverified pointer to a port
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns the current connection state for a port. It validates the
   port pointer still exists so the caller doesn't require a reference
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-get-edid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_get_edid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_get_edid</refname>
 <refpurpose>
     get EDID for an MST port
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct edid * <function>drm_dp_mst_get_edid </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     toplevel connector to get EDID for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     unverified pointer to a port.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This returns an EDID for the port connected to a connector,
   It validates the pointer still exists so the caller doesn't require a
   reference.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-find-vcpi-slots">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_find_vcpi_slots</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_find_vcpi_slots</refname>
 <refpurpose>
     find slots for this PBN value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_find_vcpi_slots </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>int <parameter>pbn</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to use
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pbn</parameter></term>
   <listitem>
    <para>
     payload bandwidth to convert into slots.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-allocate-vcpi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_allocate_vcpi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_allocate_vcpi</refname>
 <refpurpose>
     Allocate a virtual channel
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_dp_mst_allocate_vcpi </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
   <paramdef>int <parameter>pbn</parameter></paramdef>
   <paramdef>int * <parameter>slots</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     port to allocate a virtual channel for.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pbn</parameter></term>
   <listitem>
    <para>
     payload bandwidth number to request
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>slots</parameter></term>
   <listitem>
    <para>
     returned number of slots for this PBN.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-reset-vcpi-slots">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_reset_vcpi_slots</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_reset_vcpi_slots</refname>
 <refpurpose>
     Reset number of slots to 0 for VCPI
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dp_mst_reset_vcpi_slots </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     unverified pointer to a port.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This just resets the number of slots for the ports VCPI for later programming.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-deallocate-vcpi">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_deallocate_vcpi</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_deallocate_vcpi</refname>
 <refpurpose>
     deallocate a VCPI
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dp_mst_deallocate_vcpi </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>struct drm_dp_mst_port * <parameter>port</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager for this port
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>port</parameter></term>
   <listitem>
    <para>
     unverified port to deallocate vcpi for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-dp-check-act-status">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_check_act_status</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_check_act_status</refname>
 <refpurpose>
     Check ACT handled status.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_check_act_status </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to use
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the payload status bits in the DPCD for ACT handled completion.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-calc-pbn-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_calc_pbn_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_calc_pbn_mode</refname>
 <refpurpose>
     Calculate the PBN for a mode.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_calc_pbn_mode </function></funcdef>
   <paramdef>int <parameter>clock</parameter></paramdef>
   <paramdef>int <parameter>bpp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>clock</parameter></term>
   <listitem>
    <para>
     dot clock for the mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bpp</parameter></term>
   <listitem>
    <para>
     bpp for the mode.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This uses the formula in the spec to calculate the PBN value for a mode.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-dump-topology">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_dump_topology</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_dump_topology</refname>
 <refpurpose>
   </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dp_mst_dump_topology </function></funcdef>
   <paramdef>struct seq_file * <parameter>m</parameter></paramdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>m</parameter></term>
   <listitem>
    <para>
     seq_file to dump output to
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to dump current topology for.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   helper to dump MST topology to a seq file for debugfs.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-topology-mgr-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_topology_mgr_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_topology_mgr_init</refname>
 <refpurpose>
     initialise a topology manager
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_dp_mst_topology_mgr_init </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_dp_aux * <parameter>aux</parameter></paramdef>
   <paramdef>int <parameter>max_dpcd_transaction_bytes</parameter></paramdef>
   <paramdef>int <parameter>max_payloads</parameter></paramdef>
   <paramdef>int <parameter>conn_base_id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager struct to initialise
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device providing this structure - for i2c addition.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>aux</parameter></term>
   <listitem>
    <para>
     DP helper aux channel to talk to this device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_dpcd_transaction_bytes</parameter></term>
   <listitem>
    <para>
     hw specific DPCD transaction limit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_payloads</parameter></term>
   <listitem>
    <para>
     maximum number of payloads this GPU can source
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>conn_base_id</parameter></term>
   <listitem>
    <para>
     the connector object ID the MST device is connected to.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Return 0 for success, or negative error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-dp-mst-topology-mgr-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_dp_mst_topology_mgr_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_dp_mst_topology_mgr_destroy</refname>
 <refpurpose>
     destroy topology manager.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_dp_mst_topology_mgr_destroy </function></funcdef>
   <paramdef>struct drm_dp_mst_topology_mgr * <parameter>mgr</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>mgr</parameter></term>
   <listitem>
    <para>
     manager to destroy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>MIPI DSI Helper Functions Reference</title>
<para>
   </para><para>
   These functions contain some common logic and helpers to deal with MIPI DSI
   peripherals.
   </para><para>
   Helpers are provided for a number of standard MIPI DSI command as well as a
   subset of the MIPI DCS command set.
</para>

<!-- include/drm/drm_mipi_dsi.h -->
<refentry id="API-struct-mipi-dsi-msg">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct mipi_dsi_msg</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct mipi_dsi_msg</refname>
 <refpurpose>
  read/write DSI buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct mipi_dsi_msg {
  u8 channel;
  u8 type;
  u16 flags;
  size_t tx_len;
  const void * tx_buf;
  size_t rx_len;
  void * rx_buf;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>channel</term>
      <listitem><para>
virtual channel id
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>type</term>
      <listitem><para>
payload data type
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>flags</term>
      <listitem><para>
flags controlling this message transmission
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_len</term>
      <listitem><para>
length of <parameter>tx_buf</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>tx_buf</term>
      <listitem><para>
data to be written
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_len</term>
      <listitem><para>
length of <parameter>rx_buf</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>rx_buf</term>
      <listitem><para>
data to be read, or NULL
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-mipi-dsi-packet">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct mipi_dsi_packet</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct mipi_dsi_packet</refname>
 <refpurpose>
     represents a MIPI DSI packet in protocol format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct mipi_dsi_packet {
  size_t size;
  u8 header[4];
  size_t payload_length;
  const u8 * payload;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>size</term>
      <listitem><para>
   size (in bytes) of the packet
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>header[4]</term>
      <listitem><para>
   the four bytes that make up the header (Data ID, Word Count or
   Packet Data, and ECC)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>payload_length</term>
      <listitem><para>
   number of bytes in the payload
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>payload</term>
      <listitem><para>
   a pointer to a buffer containing the payload, if any
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-mipi-dsi-host-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct mipi_dsi_host_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct mipi_dsi_host_ops</refname>
 <refpurpose>
     DSI bus operations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct mipi_dsi_host_ops {
  int (* attach) (struct mipi_dsi_host *host,struct mipi_dsi_device *dsi);
  int (* detach) (struct mipi_dsi_host *host,struct mipi_dsi_device *dsi);
  ssize_t (* transfer) (struct mipi_dsi_host *host,const struct mipi_dsi_msg *msg);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>attach</term>
      <listitem><para>
   attach DSI device to DSI host
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>detach</term>
      <listitem><para>
   detach DSI device from DSI host
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>transfer</term>
      <listitem><para>
   transmit a DSI packet
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   DSI packets transmitted by .<function>transfer</function> are passed in as mipi_dsi_msg
   structures. This structure contains information about the type of packet
   being transmitted as well as the transmit and receive buffers. When an
   error is encountered during transmission, this function will return a
   negative error code. On success it shall return the number of bytes
   transmitted for write packets or the number of bytes received for read
   packets.
   </para><para>

   Note that typically DSI packet transmission is atomic, so the .<function>transfer</function>
   function will seldomly return anything other than the number of bytes
   contained in the transmit buffer on success.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-mipi-dsi-host">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct mipi_dsi_host</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct mipi_dsi_host</refname>
 <refpurpose>
     DSI host device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct mipi_dsi_host {
  struct device * dev;
  const struct mipi_dsi_host_ops * ops;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   driver model device node for this DSI host
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   DSI host operations
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-mipi-dsi-device">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct mipi_dsi_device</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct mipi_dsi_device</refname>
 <refpurpose>
     DSI peripheral device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct mipi_dsi_device {
  struct mipi_dsi_host * host;
  struct device dev;
  unsigned int channel;
  unsigned int lanes;
  enum mipi_dsi_pixel_format format;
  unsigned long mode_flags;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>host</term>
      <listitem><para>
   DSI host for this peripheral
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   driver model device node for this peripheral
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>channel</term>
      <listitem><para>
   virtual channel assigned to the peripheral
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lanes</term>
      <listitem><para>
   number of active data lanes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>format</term>
      <listitem><para>
   pixel format for video mode
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>mode_flags</term>
      <listitem><para>
   DSI operation mode related flags
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-enum-mipi-dsi-dcs-tear-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum mipi_dsi_dcs_tear_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum mipi_dsi_dcs_tear_mode</refname>
 <refpurpose>
     Tearing Effect Output Line mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum mipi_dsi_dcs_tear_mode {
  MIPI_DSI_DCS_TEAR_MODE_VBLANK,
  MIPI_DSI_DCS_TEAR_MODE_VHBLANK
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>MIPI_DSI_DCS_TEAR_MODE_VBLANK</term>
      <listitem><para>
   the TE output line consists of V-Blanking
   information only
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>MIPI_DSI_DCS_TEAR_MODE_VHBLANK</term>
      <listitem><para>
   the TE output line consists of both
   V-Blanking and H-Blanking information
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
</refentry>

<refentry id="API-struct-mipi-dsi-driver">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct mipi_dsi_driver</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct mipi_dsi_driver</refname>
 <refpurpose>
     DSI driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct mipi_dsi_driver {
  struct device_driver driver;
  int(* probe) (struct mipi_dsi_device *dsi);
  int(* remove) (struct mipi_dsi_device *dsi);
  void (* shutdown) (struct mipi_dsi_device *dsi);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>driver</term>
      <listitem><para>
   device driver model driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>probe</term>
      <listitem><para>
   callback for device binding
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>remove</term>
      <listitem><para>
   callback for device unbinding
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>shutdown</term>
      <listitem><para>
   called at shutdown time to quiesce the device
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_mipi_dsi.c -->
<refentry id="API-of-find-mipi-dsi-device-by-node">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>of_find_mipi_dsi_device_by_node</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>of_find_mipi_dsi_device_by_node</refname>
 <refpurpose>
  find the MIPI DSI device matching a device tree node
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct mipi_dsi_device * <function>of_find_mipi_dsi_device_by_node </function></funcdef>
   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>np</parameter></term>
   <listitem>
    <para>
     device tree node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   A pointer to the MIPI DSI device corresponding to <parameter>np</parameter> or NULL if no
   such device exists (or has not been registered yet).
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_attach</refname>
 <refpurpose>
     attach a DSI device to its DSI host
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_attach </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-detach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_detach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_detach</refname>
 <refpurpose>
     detach a DSI device from its DSI host
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_detach </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-packet-format-is-short">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_packet_format_is_short</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_packet_format_is_short</refname>
 <refpurpose>
     check if a packet is of the short format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>mipi_dsi_packet_format_is_short </function></funcdef>
   <paramdef>u8 <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     MIPI DSI data type of the packet
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   true if the packet for the given data type is a short packet, false
   otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-packet-format-is-long">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_packet_format_is_long</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_packet_format_is_long</refname>
 <refpurpose>
     check if a packet is of the long format
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>mipi_dsi_packet_format_is_long </function></funcdef>
   <paramdef>u8 <parameter>type</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>type</parameter></term>
   <listitem>
    <para>
     MIPI DSI data type of the packet
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   true if the packet for the given data type is a long packet, false
   otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-create-packet">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_create_packet</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_create_packet</refname>
 <refpurpose>
     create a packet from a message according to the DSI protocol
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_create_packet </function></funcdef>
   <paramdef>struct mipi_dsi_packet * <parameter>packet</parameter></paramdef>
   <paramdef>const struct mipi_dsi_msg * <parameter>msg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>packet</parameter></term>
   <listitem>
    <para>
     pointer to a DSI packet structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>msg</parameter></term>
   <listitem>
    <para>
     message to translate into a packet
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-generic-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_generic_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_generic_write</refname>
 <refpurpose>
     transmit data using a generic write packet
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>mipi_dsi_generic_write </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>const void * <parameter>payload</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>payload</parameter></term>
   <listitem>
    <para>
     buffer containing the payload
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of payload buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will automatically choose the right data type depending on
   the payload length.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of bytes transmitted on success or a negative error code
   on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-generic-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_generic_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_generic_read</refname>
 <refpurpose>
     receive data using a generic read packet
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>mipi_dsi_generic_read </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>const void * <parameter>params</parameter></paramdef>
   <paramdef>size_t <parameter>num_params</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     buffer containing the request parameters
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_params</parameter></term>
   <listitem>
    <para>
     number of request parameters
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     buffer in which to return the received data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of receive buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will automatically choose the right data type depending on
   the number of parameters passed in.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of bytes successfully read or a negative error code on
   failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-write-buffer">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_write_buffer</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_write_buffer</refname>
 <refpurpose>
     transmit a DCS command with payload
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>mipi_dsi_dcs_write_buffer </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     buffer containing data to be transmitted
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     size of transmission buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will automatically choose the right data type depending on
   the command payload length.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of bytes successfully transmitted or a negative error
   code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-write">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_write</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_write</refname>
 <refpurpose>
     send DCS write command
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>mipi_dsi_dcs_write </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
   <paramdef>const void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     DCS command
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     buffer containing the command payload
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     command payload length
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will automatically choose the right data type depending on
   the command payload length.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of bytes successfully transmitted or a negative error
   code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-read">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_read</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_read</refname>
 <refpurpose>
     send DCS read request command
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>mipi_dsi_dcs_read </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u8 <parameter>cmd</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>size_t <parameter>len</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     DCS command
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     buffer in which to receive data
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>len</parameter></term>
   <listitem>
    <para>
     size of receive buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of bytes read or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-nop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_nop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_nop</refname>
 <refpurpose>
     send DCS nop packet
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_nop </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-soft-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_soft_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_soft_reset</refname>
 <refpurpose>
     perform a software reset of the display module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_soft_reset </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-get-power-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_get_power_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_get_power_mode</refname>
 <refpurpose>
     query the display module's current power mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_get_power_mode </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u8 * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     return location for the current power mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-get-pixel-format">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_get_pixel_format</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_get_pixel_format</refname>
 <refpurpose>
     gets the pixel format for the RGB image data used by the interface
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_get_pixel_format </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u8 * <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     return location for the pixel format
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-enter-sleep-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_enter_sleep_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_enter_sleep_mode</refname>
 <refpurpose>
     disable all unnecessary blocks inside the display module except interface communication
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_enter_sleep_mode </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-exit-sleep-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_exit_sleep_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_exit_sleep_mode</refname>
 <refpurpose>
     enable all blocks inside the display module
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_exit_sleep_mode </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-display-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_display_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_display_off</refname>
 <refpurpose>
     stop displaying the image data on the display device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_display_off </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-display-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_display_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_display_on</refname>
 <refpurpose>
     start displaying the image data on the display device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_display_on </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-column-address">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_column_address</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_column_address</refname>
 <refpurpose>
     define the column extent of the frame memory accessed by the host processor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_column_address </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u16 <parameter>start</parameter></paramdef>
   <paramdef>u16 <parameter>end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     first column of frame memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     last column of frame memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-page-address">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_page_address</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_page_address</refname>
 <refpurpose>
     define the page extent of the frame memory accessed by the host processor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_page_address </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u16 <parameter>start</parameter></paramdef>
   <paramdef>u16 <parameter>end</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     first page of frame memory
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     last page of frame memory
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-tear-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_tear_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_tear_off</refname>
 <refpurpose>
     turn off the display module's Tearing Effect output signal on the TE signal line
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_tear_off </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-tear-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_tear_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_tear_on</refname>
 <refpurpose>
     turn on the display module's Tearing Effect output signal on the TE signal line.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_tear_on </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>enum mipi_dsi_dcs_tear_mode <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the Tearing Effect Output Line mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-dcs-set-pixel-format">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_dcs_set_pixel_format</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_dcs_set_pixel_format</refname>
 <refpurpose>
     sets the pixel format for the RGB image data used by the interface
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_dcs_set_pixel_format </function></funcdef>
   <paramdef>struct mipi_dsi_device * <parameter>dsi</parameter></paramdef>
   <paramdef>u8 <parameter>format</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dsi</parameter></term>
   <listitem>
    <para>
     DSI peripheral device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>format</parameter></term>
   <listitem>
    <para>
     pixel format
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-driver-register-full">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_driver_register_full</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_driver_register_full</refname>
 <refpurpose>
     register a driver for DSI devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>mipi_dsi_driver_register_full </function></funcdef>
   <paramdef>struct mipi_dsi_driver * <parameter>drv</parameter></paramdef>
   <paramdef>struct module * <parameter>owner</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     DSI driver structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>owner</parameter></term>
   <listitem>
    <para>
     owner module
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-mipi-dsi-driver-unregister">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>mipi_dsi_driver_unregister</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>mipi_dsi_driver_unregister</refname>
 <refpurpose>
     unregister a driver for DSI devices
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>mipi_dsi_driver_unregister </function></funcdef>
   <paramdef>struct mipi_dsi_driver * <parameter>drv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>drv</parameter></term>
   <listitem>
    <para>
     DSI driver structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>EDID Helper Functions Reference</title>
<!-- drivers/gpu/drm/drm_edid.c -->
<refentry id="API-drm-edid-header-is-valid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_header_is_valid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_header_is_valid</refname>
 <refpurpose>
  sanity check the header of the base EDID block
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_edid_header_is_valid </function></funcdef>
   <paramdef>const u8 * <parameter>raw_edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>raw_edid</parameter></term>
   <listitem>
    <para>
     pointer to raw base EDID block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sanity check the header of the base EDID block.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   8 if the header is perfect, down to 0 if it's totally wrong.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-edid-block-valid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_block_valid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_block_valid</refname>
 <refpurpose>
     Sanity check the EDID block (base or extension)
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_edid_block_valid </function></funcdef>
   <paramdef>u8 * <parameter>raw_edid</parameter></paramdef>
   <paramdef>int <parameter>block</parameter></paramdef>
   <paramdef>bool <parameter>print_bad_edid</parameter></paramdef>
   <paramdef>bool * <parameter>edid_corrupt</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>raw_edid</parameter></term>
   <listitem>
    <para>
     pointer to raw EDID block
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>block</parameter></term>
   <listitem>
    <para>
     type of block to validate (0 for base, extension otherwise)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>print_bad_edid</parameter></term>
   <listitem>
    <para>
     if true, dump bad EDID blocks to the console
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>edid_corrupt</parameter></term>
   <listitem>
    <para>
     if true, the header or checksum is invalid
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Validate a base or extension EDID block and optionally dump bad blocks to
   the console.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   True if the block is valid, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-edid-is-valid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_is_valid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_is_valid</refname>
 <refpurpose>
     sanity check EDID data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_edid_is_valid </function></funcdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sanity-check an entire EDID record (including extensions)
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   True if the EDID data is valid, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-do-get-edid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_do_get_edid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_do_get_edid</refname>
 <refpurpose>
     get EDID data using a custom EDID block read function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct edid * <function>drm_do_get_edid </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>int (*<parameter>get_edid_block</parameter>)
     <funcparams>void *data, u8 *buf, unsigned int block, 			      size_t len</funcparams></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector we're probing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>get_edid_block</parameter></term>
   <listitem>
    <para>
     EDID block read function
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     private data passed to the block read function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When the I2C adapter connected to the DDC bus is hidden behind a device that
   exposes a different interface to read EDID blocks this function can be used
   to get EDID data using a custom block read function.
   </para><para>

   As in the general case the DDC bus is accessible by the kernel at the I2C
   level, drivers must make all reasonable efforts to expose it as an I2C
   adapter and use <function>drm_get_edid</function> instead of abusing this function.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Pointer to valid EDID or NULL if we couldn't find any.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-probe-ddc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_probe_ddc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_probe_ddc</refname>
 <refpurpose>
     probe DDC presence
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_probe_ddc </function></funcdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     I2C adapter to probe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   True on success, false on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-get-edid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_get_edid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_get_edid</refname>
 <refpurpose>
     get EDID data, if available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct edid * <function>drm_get_edid </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct i2c_adapter * <parameter>adapter</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector we're probing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adapter</parameter></term>
   <listitem>
    <para>
     I2C adapter to use for DDC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Poke the given I2C channel to grab EDID data if possible.  If found,
   attach it to the connector.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Pointer to valid EDID or NULL if we couldn't find any.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-edid-duplicate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_duplicate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_duplicate</refname>
 <refpurpose>
     duplicate an EDID and the extensions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct edid * <function>drm_edid_duplicate </function></funcdef>
   <paramdef>const struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID to duplicate
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Pointer to duplicated EDID or NULL on allocation failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-match-cea-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_match_cea_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_match_cea_mode</refname>
 <refpurpose>
     look for a CEA mode matching given mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u8 <function>drm_match_cea_mode </function></funcdef>
   <paramdef>const struct drm_display_mode * <parameter>to_match</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>to_match</parameter></term>
   <listitem>
    <para>
     display mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The CEA Video ID (VIC) of the mode or 0 if it isn't a CEA-861
   mode.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-get-cea-aspect-ratio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_get_cea_aspect_ratio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_get_cea_aspect_ratio</refname>
 <refpurpose>
     get the picture aspect ratio corresponding to the input VIC from the CEA mode list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum hdmi_picture_aspect <function>drm_get_cea_aspect_ratio </function></funcdef>
   <paramdef>const u8 <parameter>video_code</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>video_code</parameter></term>
   <listitem>
    <para>
     ID given to each of the CEA modes
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns picture aspect ratio
</para>
</refsect1>
</refentry>

<refentry id="API-drm-edid-to-eld">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_to_eld</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_to_eld</refname>
 <refpurpose>
     build ELD from EDID
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_edid_to_eld </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector corresponding to the HDMI/DP sink
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID to parse
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fill the ELD (EDID-Like Data) buffer for passing to the audio driver. The
   Conn_Type, HDCP and Port_ID ELD fields are left for the graphics driver to
   fill in.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-edid-to-sad">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_to_sad</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_to_sad</refname>
 <refpurpose>
     extracts SADs from EDID
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_edid_to_sad </function></funcdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
   <paramdef>struct cea_sad ** <parameter>sads</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID to parse
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sads</parameter></term>
   <listitem>
    <para>
     pointer that will be set to the extracted SADs
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Looks for CEA EDID block and extracts SADs (Short Audio Descriptors) from it.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The returned pointer needs to be freed using <function>kfree</function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of found SADs or negative number on error.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-edid-to-speaker-allocation">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_edid_to_speaker_allocation</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_edid_to_speaker_allocation</refname>
 <refpurpose>
     extracts Speaker Allocation Data Blocks from EDID
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_edid_to_speaker_allocation </function></funcdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
   <paramdef>u8 ** <parameter>sadb</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID to parse
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>sadb</parameter></term>
   <listitem>
    <para>
     pointer to the speaker block
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Looks for CEA EDID block and extracts the Speaker Allocation Data Block from it.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   The returned pointer needs to be freed using <function>kfree</function>.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of found Speaker Allocation Blocks or negative number on
   error.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-av-sync-delay">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_av_sync_delay</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_av_sync_delay</refname>
 <refpurpose>
     compute the HDMI/DP sink audio-video sync delay
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_av_sync_delay </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector associated with the HDMI/DP sink
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     the display mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The HDMI/DP sink's audio-video sync delay in milliseconds or 0 if
   the sink doesn't support audio or video.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-select-eld">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_select_eld</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_select_eld</refname>
 <refpurpose>
     select one ELD from multiple HDMI/DP sinks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_connector * <function>drm_select_eld </function></funcdef>
   <paramdef>struct drm_encoder * <parameter>encoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>encoder</parameter></term>
   <listitem>
    <para>
     the encoder just changed display mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   It's possible for one encoder to be associated with multiple HDMI/DP sinks.
   The policy is now hard coded to simply use the first HDMI/DP sink's ELD.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The connector associated with the first HDMI/DP sink that has ELD
   attached to it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-detect-hdmi-monitor">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_detect_hdmi_monitor</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_detect_hdmi_monitor</refname>
 <refpurpose>
     detect whether monitor is HDMI
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_detect_hdmi_monitor </function></funcdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     monitor EDID information
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Parse the CEA extension according to CEA-861-B.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   True if the monitor is HDMI, false if not or unknown.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-detect-monitor-audio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_detect_monitor_audio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_detect_monitor_audio</refname>
 <refpurpose>
     check monitor audio capability
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_detect_monitor_audio </function></funcdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID block to scan
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Monitor should have CEA extension block.
   If monitor has 'basic audio', but no CEA audio blocks, it's 'basic
   audio' only. If there is any audio extension block and supported
   audio format, assume at least 'basic audio' support, even if 'basic
   audio' is not defined in EDID.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   True if the monitor supports audio, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rgb-quant-range-selectable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rgb_quant_range_selectable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rgb_quant_range_selectable</refname>
 <refpurpose>
     is RGB quantization range selectable?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_rgb_quant_range_selectable </function></funcdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID block to scan
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check whether the monitor reports the RGB quantization range selection
   as supported. The AVI infoframe can then be used to inform the monitor
   which quantization range (full or limited) is used.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   True if the RGB quantization range is selectable, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-add-edid-modes">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_add_edid_modes</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_add_edid_modes</refname>
 <refpurpose>
     add modes from EDID data, if available
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_add_edid_modes </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>struct edid * <parameter>edid</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector we're probing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>edid</parameter></term>
   <listitem>
    <para>
     EDID data
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add the specified modes to the connector's mode list.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of modes added or 0 if we couldn't find any.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-add-modes-noedid">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_add_modes_noedid</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_add_modes_noedid</refname>
 <refpurpose>
     add modes for the connectors without EDID
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_add_modes_noedid </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>int <parameter>hdisplay</parameter></paramdef>
   <paramdef>int <parameter>vdisplay</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector we're probing
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hdisplay</parameter></term>
   <listitem>
    <para>
     the horizontal display limit
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vdisplay</parameter></term>
   <listitem>
    <para>
     the vertical display limit
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Add the specified modes to the connector's mode list. Only when the
   hdisplay/vdisplay is not beyond the given limit, it will be added.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   The number of modes added or 0 if we couldn't find any.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-set-preferred-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_set_preferred_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_set_preferred_mode</refname>
 <refpurpose>
     Sets the preferred mode of a connector
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_set_preferred_mode </function></funcdef>
   <paramdef>struct drm_connector * <parameter>connector</parameter></paramdef>
   <paramdef>int <parameter>hpref</parameter></paramdef>
   <paramdef>int <parameter>vpref</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>connector</parameter></term>
   <listitem>
    <para>
     connector whose mode list should be processed
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hpref</parameter></term>
   <listitem>
    <para>
     horizontal resolution of preferred mode
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vpref</parameter></term>
   <listitem>
    <para>
     vertical resolution of preferred mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Marks a mode as preferred if it matches the resolution specified by <parameter>hpref</parameter>
   and <parameter>vpref</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-hdmi-avi-infoframe-from-display-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_hdmi_avi_infoframe_from_display_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_hdmi_avi_infoframe_from_display_mode</refname>
 <refpurpose>
     fill an HDMI AVI infoframe with data from a DRM display mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_hdmi_avi_infoframe_from_display_mode </function></funcdef>
   <paramdef>struct hdmi_avi_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI AVI infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     DRM display mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-hdmi-vendor-infoframe-from-display-mode">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_hdmi_vendor_infoframe_from_display_mode</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_hdmi_vendor_infoframe_from_display_mode</refname>
 <refpurpose>
     fill an HDMI infoframe with data from a DRM display mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_hdmi_vendor_infoframe_from_display_mode </function></funcdef>
   <paramdef>struct hdmi_vendor_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI vendor infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     DRM display mode
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Note that there's is a need to send HDMI vendor infoframes only when using a
   4k or stereoscopic 3D mode. So when giving any other mode as input this
   function will return -EINVAL, error that can be safely ignored.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Rectangle Utilities Reference</title>
<para>
   </para><para>
   Utility functions to help manage rectangular areas for
   clipping, scaling, etc. calculations.
</para>

<!-- include/drm/drm_rect.h -->
<refentry id="API-struct-drm-rect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_rect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_rect</refname>
 <refpurpose>
  two dimensional rectangle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_rect {
  int x1;
  int y1;
  int x2;
  int y2;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>x1</term>
      <listitem><para>
horizontal starting coordinate (inclusive)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>y1</term>
      <listitem><para>
vertical starting coordinate (inclusive)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>x2</term>
      <listitem><para>
horizontal ending coordinate (exclusive)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>y2</term>
      <listitem><para>
vertical ending coordinate (exclusive)
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-drm-rect-adjust-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_adjust_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_adjust_size</refname>
 <refpurpose>
     adjust the size of the rectangle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_rect_adjust_size </function></funcdef>
   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
   <paramdef>int <parameter>dw</parameter></paramdef>
   <paramdef>int <parameter>dh</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle to be adjusted
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dw</parameter></term>
   <listitem>
    <para>
     horizontal adjustment
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dh</parameter></term>
   <listitem>
    <para>
     vertical adjustment
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Change the size of rectangle <parameter>r</parameter> by <parameter>dw</parameter> in the horizontal direction,
   and by <parameter>dh</parameter> in the vertical direction, while keeping the center
   of <parameter>r</parameter> stationary.
   </para><para>

   Positive <parameter>dw</parameter> and <parameter>dh</parameter> increase the size, negative values decrease it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-translate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_translate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_translate</refname>
 <refpurpose>
     translate the rectangle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_rect_translate </function></funcdef>
   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
   <paramdef>int <parameter>dx</parameter></paramdef>
   <paramdef>int <parameter>dy</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle to be tranlated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dx</parameter></term>
   <listitem>
    <para>
     horizontal translation
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dy</parameter></term>
   <listitem>
    <para>
     vertical translation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Move rectangle <parameter>r</parameter> by <parameter>dx</parameter> in the horizontal direction,
   and by <parameter>dy</parameter> in the vertical direction.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-downscale">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_downscale</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_downscale</refname>
 <refpurpose>
     downscale a rectangle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_rect_downscale </function></funcdef>
   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
   <paramdef>int <parameter>horz</parameter></paramdef>
   <paramdef>int <parameter>vert</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle to be downscaled
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>horz</parameter></term>
   <listitem>
    <para>
     horizontal downscale factor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vert</parameter></term>
   <listitem>
    <para>
     vertical downscale factor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Divide the coordinates of rectangle <parameter>r</parameter> by <parameter>horz</parameter> and <parameter>vert</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-width">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_width</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_width</refname>
 <refpurpose>
     determine the rectangle width
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_rect_width </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle whose width is returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The width of the rectangle.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-height">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_height</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_height</refname>
 <refpurpose>
     determine the rectangle height
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_rect_height </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle whose height is returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The height of the rectangle.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-visible">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_visible</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_visible</refname>
 <refpurpose>
     determine if the the rectangle is visible
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_rect_visible </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle whose visibility is returned
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>true</constant> if the rectangle is visible, <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-equals">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_equals</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_equals</refname>
 <refpurpose>
     determine if two rectangles are equal
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_rect_equals </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>r1</parameter></paramdef>
   <paramdef>const struct drm_rect * <parameter>r2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r1</parameter></term>
   <listitem>
    <para>
     first rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r2</parameter></term>
   <listitem>
    <para>
     second rectangle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>true</constant> if the rectangles are equal, <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_rect.c -->
<refentry id="API-drm-rect-intersect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_intersect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_intersect</refname>
 <refpurpose>
  intersect two rectangles
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_rect_intersect </function></funcdef>
   <paramdef>struct drm_rect * <parameter>r1</parameter></paramdef>
   <paramdef>const struct drm_rect * <parameter>r2</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r1</parameter></term>
   <listitem>
    <para>
     first rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>r2</parameter></term>
   <listitem>
    <para>
     second rectangle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the intersection of rectangles <parameter>r1</parameter> and <parameter>r2</parameter>.
   <parameter>r1</parameter> will be overwritten with the intersection.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>true</constant> if rectangle <parameter>r1</parameter> is still visible after the operation,
   <constant>false</constant> otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-clip-scaled">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_clip_scaled</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_clip_scaled</refname>
 <refpurpose>
     perform a scaled clip operation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_rect_clip_scaled </function></funcdef>
   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
   <paramdef>struct drm_rect * <parameter>dst</parameter></paramdef>
   <paramdef>const struct drm_rect * <parameter>clip</parameter></paramdef>
   <paramdef>int <parameter>hscale</parameter></paramdef>
   <paramdef>int <parameter>vscale</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>clip</parameter></term>
   <listitem>
    <para>
     clip rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>hscale</parameter></term>
   <listitem>
    <para>
     horizontal scaling factor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vscale</parameter></term>
   <listitem>
    <para>
     vertical scaling factor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Clip rectangle <parameter>dst</parameter> by rectangle <parameter>clip</parameter>. Clip rectangle <parameter>src</parameter> by the
   same amounts multiplied by <parameter>hscale</parameter> and <parameter>vscale</parameter>.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   <constant>true</constant> if rectangle <parameter>dst</parameter> is still visible after being clipped,
   <constant>false</constant> otherwise
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-calc-hscale">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_calc_hscale</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_calc_hscale</refname>
 <refpurpose>
     calculate the horizontal scaling factor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_rect_calc_hscale </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>src</parameter></paramdef>
   <paramdef>const struct drm_rect * <parameter>dst</parameter></paramdef>
   <paramdef>int <parameter>min_hscale</parameter></paramdef>
   <paramdef>int <parameter>max_hscale</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min_hscale</parameter></term>
   <listitem>
    <para>
     minimum allowed horizontal scaling factor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_hscale</parameter></term>
   <listitem>
    <para>
     maximum allowed horizontal scaling factor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the horizontal scaling factor as
   (<parameter>src</parameter> width) / (<parameter>dst</parameter> width).
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The horizontal scaling factor, or errno of out of limits.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-calc-vscale">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_calc_vscale</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_calc_vscale</refname>
 <refpurpose>
     calculate the vertical scaling factor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_rect_calc_vscale </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>src</parameter></paramdef>
   <paramdef>const struct drm_rect * <parameter>dst</parameter></paramdef>
   <paramdef>int <parameter>min_vscale</parameter></paramdef>
   <paramdef>int <parameter>max_vscale</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min_vscale</parameter></term>
   <listitem>
    <para>
     minimum allowed vertical scaling factor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_vscale</parameter></term>
   <listitem>
    <para>
     maximum allowed vertical scaling factor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the vertical scaling factor as
   (<parameter>src</parameter> height) / (<parameter>dst</parameter> height).
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The vertical scaling factor, or errno of out of limits.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-calc-hscale-relaxed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_calc_hscale_relaxed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_calc_hscale_relaxed</refname>
 <refpurpose>
     calculate the horizontal scaling factor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_rect_calc_hscale_relaxed </function></funcdef>
   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
   <paramdef>struct drm_rect * <parameter>dst</parameter></paramdef>
   <paramdef>int <parameter>min_hscale</parameter></paramdef>
   <paramdef>int <parameter>max_hscale</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min_hscale</parameter></term>
   <listitem>
    <para>
     minimum allowed horizontal scaling factor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_hscale</parameter></term>
   <listitem>
    <para>
     maximum allowed horizontal scaling factor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the horizontal scaling factor as
   (<parameter>src</parameter> width) / (<parameter>dst</parameter> width).
   </para><para>

   If the calculated scaling factor is below <parameter>min_vscale</parameter>,
   decrease the height of rectangle <parameter>dst</parameter> to compensate.
   </para><para>

   If the calculated scaling factor is above <parameter>max_vscale</parameter>,
   decrease the height of rectangle <parameter>src</parameter> to compensate.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The horizontal scaling factor.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-calc-vscale-relaxed">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_calc_vscale_relaxed</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_calc_vscale_relaxed</refname>
 <refpurpose>
     calculate the vertical scaling factor
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_rect_calc_vscale_relaxed </function></funcdef>
   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
   <paramdef>struct drm_rect * <parameter>dst</parameter></paramdef>
   <paramdef>int <parameter>min_vscale</parameter></paramdef>
   <paramdef>int <parameter>max_vscale</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dst</parameter></term>
   <listitem>
    <para>
     destination window rectangle
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min_vscale</parameter></term>
   <listitem>
    <para>
     minimum allowed vertical scaling factor
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_vscale</parameter></term>
   <listitem>
    <para>
     maximum allowed vertical scaling factor
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate the vertical scaling factor as
   (<parameter>src</parameter> height) / (<parameter>dst</parameter> height).
   </para><para>

   If the calculated scaling factor is below <parameter>min_vscale</parameter>,
   decrease the height of rectangle <parameter>dst</parameter> to compensate.
   </para><para>

   If the calculated scaling factor is above <parameter>max_vscale</parameter>,
   decrease the height of rectangle <parameter>src</parameter> to compensate.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   The vertical scaling factor.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-debug-print">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_debug_print</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_debug_print</refname>
 <refpurpose>
     print the rectangle information
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_rect_debug_print </function></funcdef>
   <paramdef>const struct drm_rect * <parameter>r</parameter></paramdef>
   <paramdef>bool <parameter>fixed_point</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle to print
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fixed_point</parameter></term>
   <listitem>
    <para>
     rectangle is in 16.16 fixed point format
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-rect-rotate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_rotate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_rotate</refname>
 <refpurpose>
     Rotate the rectangle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_rect_rotate </function></funcdef>
   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
   <paramdef>int <parameter>width</parameter></paramdef>
   <paramdef>int <parameter>height</parameter></paramdef>
   <paramdef>unsigned int <parameter>rotation</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle to be rotated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>width</parameter></term>
   <listitem>
    <para>
     Width of the coordinate space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>height</parameter></term>
   <listitem>
    <para>
     Height of the coordinate space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rotation</parameter></term>
   <listitem>
    <para>
     Transformation to be applied
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply <parameter>rotation</parameter> to the coordinates of rectangle <parameter>r</parameter>.
   </para><para>

   <parameter>width</parameter> and <parameter>height</parameter> combined with <parameter>rotation</parameter> define
   the location of the new origin.
   </para><para>

   <parameter>width</parameter> correcsponds to the horizontal and <parameter>height</parameter>
   to the vertical axis of the untransformed coordinate
   space.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-rect-rotate-inv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_rect_rotate_inv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_rect_rotate_inv</refname>
 <refpurpose>
     Inverse rotate the rectangle
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_rect_rotate_inv </function></funcdef>
   <paramdef>struct drm_rect * <parameter>r</parameter></paramdef>
   <paramdef>int <parameter>width</parameter></paramdef>
   <paramdef>int <parameter>height</parameter></paramdef>
   <paramdef>unsigned int <parameter>rotation</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>r</parameter></term>
   <listitem>
    <para>
     rectangle to be rotated
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>width</parameter></term>
   <listitem>
    <para>
     Width of the coordinate space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>height</parameter></term>
   <listitem>
    <para>
     Height of the coordinate space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rotation</parameter></term>
   <listitem>
    <para>
     Transformation whose inverse is to be applied
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Apply the inverse of <parameter>rotation</parameter> to the coordinates
   of rectangle <parameter>r</parameter>.
   </para><para>

   <parameter>width</parameter> and <parameter>height</parameter> combined with <parameter>rotation</parameter> define
   the location of the new origin.
   </para><para>

   <parameter>width</parameter> correcsponds to the horizontal and <parameter>height</parameter>
   to the vertical axis of the original untransformed
   coordinate space, so that you never have to flip
   them when doing a rotatation and its inverse.
   That is, if you do:
   </para><para>

   drm_rotate(<structname>r</structname>, width, height, rotation);
   drm_rotate_inv(<structname>r</structname>, width, height, rotation);
   </para><para>

   you will always get back the original rectangle.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>Flip-work Helper Reference</title>
<para>
   </para><para>
   Util to queue up work to run from work-queue context after flip/vblank.
   Typically this can be used to defer unref of framebuffer's, cursor
   bo's, etc until after vblank.  The APIs are all thread-safe.
   Moreover, drm_flip_work_queue_task and drm_flip_work_queue can be called
   in atomic context.
</para>

<!-- include/drm/drm_flip_work.h -->
<refentry id="API-struct-drm-flip-task">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_flip_task</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_flip_task</refname>
 <refpurpose>
  flip work task
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_flip_task {
  struct list_head node;
  void * data;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>node</term>
      <listitem><para>
list entry element
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>data</term>
      <listitem><para>
data to pass to work-&gt;func
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-drm-flip-work">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct drm_flip_work</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct drm_flip_work</refname>
 <refpurpose>
     flip work queue
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct drm_flip_work {
  const char * name;
  drm_flip_func_t func;
  struct work_struct worker;
  struct list_head queued;
  struct list_head commited;
  spinlock_t lock;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>name</term>
      <listitem><para>
   debug name
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>func</term>
      <listitem><para>
   callback fxn called for each committed item
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>worker</term>
      <listitem><para>
   worker which calls <parameter>func</parameter>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>queued</term>
      <listitem><para>
   queued tasks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>commited</term>
      <listitem><para>
   commited tasks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>lock</term>
      <listitem><para>
   lock to access queued and commited lists
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- drivers/gpu/drm/drm_flip_work.c -->
<refentry id="API-drm-flip-work-allocate-task">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_flip_work_allocate_task</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_flip_work_allocate_task</refname>
 <refpurpose>
  allocate a flip-work task
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_flip_task * <function>drm_flip_work_allocate_task </function></funcdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>gfp_t <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data associated to the task
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     allocator flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate a drm_flip_task object and attach private data to it.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-flip-work-queue-task">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_flip_work_queue_task</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_flip_work_queue_task</refname>
 <refpurpose>
     queue a specific task
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_flip_work_queue_task </function></funcdef>
   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
   <paramdef>struct drm_flip_task * <parameter>task</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the flip-work
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>task</parameter></term>
   <listitem>
    <para>
     the task to handle
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queues task, that will later be run (passed back to drm_flip_func_t
   func) on a work queue after <function>drm_flip_work_commit</function> is called.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-flip-work-queue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_flip_work_queue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_flip_work_queue</refname>
 <refpurpose>
     queue work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_flip_work_queue </function></funcdef>
   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
   <paramdef>void * <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the flip-work
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     the value to queue
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Queues work, that will later be run (passed back to drm_flip_func_t
   func) on a work queue after <function>drm_flip_work_commit</function> is called.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-flip-work-commit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_flip_work_commit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_flip_work_commit</refname>
 <refpurpose>
     commit queued work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_flip_work_commit </function></funcdef>
   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
   <paramdef>struct workqueue_struct * <parameter>wq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the flip-work
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wq</parameter></term>
   <listitem>
    <para>
     the work-queue to run the queued work on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Trigger work previously queued by <function>drm_flip_work_queue</function> to run
   on a workqueue.  The typical usage would be to queue work (via
   <function>drm_flip_work_queue</function>) at any point (from vblank irq and/or
   prior), and then from vblank irq commit the queued work.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-flip-work-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_flip_work_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_flip_work_init</refname>
 <refpurpose>
     initialize flip-work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_flip_work_init </function></funcdef>
   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
   <paramdef>const char * <parameter>name</parameter></paramdef>
   <paramdef>drm_flip_func_t <parameter>func</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the flip-work to initialize
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>name</parameter></term>
   <listitem>
    <para>
     debug name
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>func</parameter></term>
   <listitem>
    <para>
     the callback work function
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes/allocates resources for the flip-work
</para>
</refsect1>
</refentry>

<refentry id="API-drm-flip-work-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_flip_work_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_flip_work_cleanup</refname>
 <refpurpose>
     cleans up flip-work
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_flip_work_cleanup </function></funcdef>
   <paramdef>struct drm_flip_work * <parameter>work</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>work</parameter></term>
   <listitem>
    <para>
     the flip-work to cleanup
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Destroy resources allocated for the flip-work
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title>HDMI Infoframes Helper Reference</title>
      <para>
	Strictly speaking this is not a DRM helper library but generally useable
	by any driver interfacing with HDMI outputs like v4l or alsa drivers.
	But it nicely fits into the overall topic of mode setting helper
	libraries and hence is also included here.
      </para>
<!-- include/linux/hdmi.h -->
<refentry id="API-struct-hdmi-infoframe">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>union hdmi_infoframe</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>union hdmi_infoframe</refname>
 <refpurpose>
  overall union of all abstract infoframe representations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
union hdmi_infoframe {
  struct hdmi_any_infoframe any;
  struct hdmi_avi_infoframe avi;
  struct hdmi_spd_infoframe spd;
  union hdmi_vendor_any_infoframe vendor;
  struct hdmi_audio_infoframe audio;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>any</term>
      <listitem><para>
generic infoframe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>avi</term>
      <listitem><para>
avi infoframe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>spd</term>
      <listitem><para>
spd infoframe
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>vendor</term>
      <listitem><para>
union of all vendor infoframes
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>audio</term>
      <listitem><para>
audio infoframe
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   This is used by the generic pack function. This works since all infoframes
   have the same header which also indicates which type of infoframe should be
   packed.
</para>
</refsect1>
</refentry>

<!-- drivers/video/hdmi.c -->
<refentry id="API-hdmi-avi-infoframe-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_avi_infoframe_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_avi_infoframe_init</refname>
 <refpurpose>
  initialize an HDMI AVI infoframe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hdmi_avi_infoframe_init </function></funcdef>
   <paramdef>struct hdmi_avi_infoframe * <parameter>frame</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI AVI infoframe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-avi-infoframe-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_avi_infoframe_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_avi_infoframe_pack</refname>
 <refpurpose>
     write HDMI AVI infoframe to binary buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>hdmi_avi_infoframe_pack </function></funcdef>
   <paramdef>struct hdmi_avi_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI AVI infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Packs the information contained in the <parameter>frame</parameter> structure into a binary
   representation that can be written into the corresponding controller
   registers. Also computes the checksum as required by section 5.3.5 of
   the HDMI 1.4 specification.
   </para><para>

   Returns the number of bytes packed into the binary buffer or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-spd-infoframe-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_spd_infoframe_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_spd_infoframe_init</refname>
 <refpurpose>
     initialize an HDMI SPD infoframe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hdmi_spd_infoframe_init </function></funcdef>
   <paramdef>struct hdmi_spd_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>const char * <parameter>vendor</parameter></paramdef>
   <paramdef>const char * <parameter>product</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI SPD infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vendor</parameter></term>
   <listitem>
    <para>
     vendor string
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>product</parameter></term>
   <listitem>
    <para>
     product string
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-spd-infoframe-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_spd_infoframe_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_spd_infoframe_pack</refname>
 <refpurpose>
     write HDMI SPD infoframe to binary buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>hdmi_spd_infoframe_pack </function></funcdef>
   <paramdef>struct hdmi_spd_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI SPD infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Packs the information contained in the <parameter>frame</parameter> structure into a binary
   representation that can be written into the corresponding controller
   registers. Also computes the checksum as required by section 5.3.5 of
   the HDMI 1.4 specification.
   </para><para>

   Returns the number of bytes packed into the binary buffer or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-audio-infoframe-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_audio_infoframe_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_audio_infoframe_init</refname>
 <refpurpose>
     initialize an HDMI audio infoframe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hdmi_audio_infoframe_init </function></funcdef>
   <paramdef>struct hdmi_audio_infoframe * <parameter>frame</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI audio infoframe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-audio-infoframe-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_audio_infoframe_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_audio_infoframe_pack</refname>
 <refpurpose>
     write HDMI audio infoframe to binary buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>hdmi_audio_infoframe_pack </function></funcdef>
   <paramdef>struct hdmi_audio_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI audio infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Packs the information contained in the <parameter>frame</parameter> structure into a binary
   representation that can be written into the corresponding controller
   registers. Also computes the checksum as required by section 5.3.5 of
   the HDMI 1.4 specification.
   </para><para>

   Returns the number of bytes packed into the binary buffer or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-vendor-infoframe-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_vendor_infoframe_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_vendor_infoframe_init</refname>
 <refpurpose>
     initialize an HDMI vendor infoframe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hdmi_vendor_infoframe_init </function></funcdef>
   <paramdef>struct hdmi_vendor_infoframe * <parameter>frame</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI vendor infoframe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-vendor-infoframe-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_vendor_infoframe_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_vendor_infoframe_pack</refname>
 <refpurpose>
     write a HDMI vendor infoframe to binary buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>hdmi_vendor_infoframe_pack </function></funcdef>
   <paramdef>struct hdmi_vendor_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Packs the information contained in the <parameter>frame</parameter> structure into a binary
   representation that can be written into the corresponding controller
   registers. Also computes the checksum as required by section 5.3.5 of
   the HDMI 1.4 specification.
   </para><para>

   Returns the number of bytes packed into the binary buffer or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-infoframe-pack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_infoframe_pack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_infoframe_pack</refname>
 <refpurpose>
     write a HDMI infoframe to binary buffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>ssize_t <function>hdmi_infoframe_pack </function></funcdef>
   <paramdef>union hdmi_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     destination buffer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Packs the information contained in the <parameter>frame</parameter> structure into a binary
   representation that can be written into the corresponding controller
   registers. Also computes the checksum as required by section 5.3.5 of
   the HDMI 1.4 specification.
   </para><para>

   Returns the number of bytes packed into the binary buffer or a negative
   error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-hdmi-infoframe-log">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_infoframe_log</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_infoframe_log</refname>
 <refpurpose>
     log info of HDMI infoframe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>hdmi_infoframe_log </function></funcdef>
   <paramdef>const char * <parameter>level</parameter></paramdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>union hdmi_infoframe * <parameter>frame</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>level</parameter></term>
   <listitem>
    <para>
     logging level
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI infoframe
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-hdmi-infoframe-unpack">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>hdmi_infoframe_unpack</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>hdmi_infoframe_unpack</refname>
 <refpurpose>
     unpack binary buffer to a HDMI infoframe
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>hdmi_infoframe_unpack </function></funcdef>
   <paramdef>union hdmi_infoframe * <parameter>frame</parameter></paramdef>
   <paramdef>void * <parameter>buffer</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>frame</parameter></term>
   <listitem>
    <para>
     HDMI infoframe
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>buffer</parameter></term>
   <listitem>
    <para>
     source buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unpacks the information contained in binary buffer <parameter>buffer</parameter> into a structured
   <parameter>frame</parameter> of a HDMI infoframe.
   Also verifies the checksum as required by section 5.3.5 of the HDMI 1.4
   specification.
   </para><para>

   Returns 0 on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

    </sect2>
    <sect2>
      <title id="drm-kms-planehelpers">Plane Helper Reference</title>
<!-- drivers/gpu/drm/drm_plane_helper.c -->
<refentry id="API-drm-plane-helper-check-update">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_helper_check_update</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_helper_check_update</refname>
 <refpurpose>
  Check plane update for validity
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_plane_helper_check_update </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>struct drm_rect * <parameter>src</parameter></paramdef>
   <paramdef>struct drm_rect * <parameter>dest</parameter></paramdef>
   <paramdef>const struct drm_rect * <parameter>clip</parameter></paramdef>
   <paramdef>int <parameter>min_scale</parameter></paramdef>
   <paramdef>int <parameter>max_scale</parameter></paramdef>
   <paramdef>bool <parameter>can_position</parameter></paramdef>
   <paramdef>bool <parameter>can_update_disabled</parameter></paramdef>
   <paramdef>bool * <parameter>visible</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     owning CRTC of owning plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to flip onto plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src</parameter></term>
   <listitem>
    <para>
     source coordinates in 16.16 fixed point
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dest</parameter></term>
   <listitem>
    <para>
     integer destination coordinates
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>clip</parameter></term>
   <listitem>
    <para>
     integer clipping coordinates
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min_scale</parameter></term>
   <listitem>
    <para>
     minimum <parameter>src</parameter>:<parameter>dest</parameter> scaling factor in 16.16 fixed point
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_scale</parameter></term>
   <listitem>
    <para>
     maximum <parameter>src</parameter>:<parameter>dest</parameter> scaling factor in 16.16 fixed point
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>can_position</parameter></term>
   <listitem>
    <para>
     is it legal to position the plane such that it
     doesn't cover the entire crtc?  This will generally
     only be false for primary planes.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>can_update_disabled</parameter></term>
   <listitem>
    <para>
     can the plane be updated while the crtc
     is disabled?
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>visible</parameter></term>
   <listitem>
    <para>
     output parameter indicating whether plane is still visible after
     clipping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Checks that a desired plane update is valid.  Drivers that provide
   their own plane handling rather than helper-provided implementations may
   still wish to call this function to avoid duplication of error checking
   code.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero if update appears valid, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-primary-helper-update">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_primary_helper_update</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_primary_helper_update</refname>
 <refpurpose>
     Helper for primary plane update
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_primary_helper_update </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>int <parameter>crtc_x</parameter></paramdef>
   <paramdef>int <parameter>crtc_y</parameter></paramdef>
   <paramdef>unsigned int <parameter>crtc_w</parameter></paramdef>
   <paramdef>unsigned int <parameter>crtc_h</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_x</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_y</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_w</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_h</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     owning CRTC of owning plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to flip onto plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_x</parameter></term>
   <listitem>
    <para>
     x offset of primary plane on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_y</parameter></term>
   <listitem>
    <para>
     y offset of primary plane on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_w</parameter></term>
   <listitem>
    <para>
     width of primary plane rectangle on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_h</parameter></term>
   <listitem>
    <para>
     height of primary plane rectangle on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_x</parameter></term>
   <listitem>
    <para>
     x offset of <parameter>fb</parameter> for panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_y</parameter></term>
   <listitem>
    <para>
     y offset of <parameter>fb</parameter> for panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_w</parameter></term>
   <listitem>
    <para>
     width of source rectangle in <parameter>fb</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_h</parameter></term>
   <listitem>
    <para>
     height of source rectangle in <parameter>fb</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane update handler for primary planes.  This is handler
   is called in response to a userspace SetPlane operation on the plane with a
   non-NULL framebuffer.  We call the driver's modeset handler to update the
   framebuffer.
   </para><para>

   <function>SetPlane</function> on a primary plane of a disabled CRTC is not supported, and will
   return an error.
   </para><para>

   Note that we make some assumptions about hardware limitations that may not be
   true for all hardware --
   1) Primary plane cannot be repositioned.
   2) Primary plane cannot be scaled.
   3) Primary plane must cover the entire CRTC.
   4) Subpixel positioning is not supported.
   Drivers for hardware that don't have these restrictions can provide their
   own implementation rather than using this helper.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-primary-helper-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_primary_helper_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_primary_helper_disable</refname>
 <refpurpose>
     Helper for primary plane disable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_primary_helper_disable </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane disable handler for primary planes.  This is handler
   is called in response to a userspace SetPlane operation on the plane with a
   NULL framebuffer parameter.  It unconditionally fails the disable call with
   -EINVAL the only way to disable the primary plane without driver support is
   to disable the entier CRTC. Which does not match the plane -&gt;disable hook.
   </para><para>

   Note that some hardware may be able to disable the primary plane without
   disabling the whole CRTC.  Drivers for such hardware should provide their
   own disable handler that disables just the primary plane (and they'll likely
   need to provide their own update handler as well to properly re-enable a
   disabled primary plane).
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Unconditionally returns -EINVAL.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-primary-helper-destroy">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_primary_helper_destroy</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_primary_helper_destroy</refname>
 <refpurpose>
     Helper for primary plane destruction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_primary_helper_destroy </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to destroy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane destroy handler for primary planes.  This handler
   is called during CRTC destruction.  We disable the primary plane, remove
   it from the DRM plane list, and deallocate the plane structure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_init</refname>
 <refpurpose>
     Legacy CRTC initialization function
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_crtc_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>const struct drm_crtc_funcs * <parameter>funcs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC object to init
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>funcs</parameter></term>
   <listitem>
    <para>
     callbacks for the new CRTC
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initialize a CRTC object with a default helper-provided primary plane and no
   cursor plane.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-helper-update">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_helper_update</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_helper_update</refname>
 <refpurpose>
     Transitional helper for plane update
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_plane_helper_update </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_framebuffer * <parameter>fb</parameter></paramdef>
   <paramdef>int <parameter>crtc_x</parameter></paramdef>
   <paramdef>int <parameter>crtc_y</parameter></paramdef>
   <paramdef>unsigned int <parameter>crtc_w</parameter></paramdef>
   <paramdef>unsigned int <parameter>crtc_h</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_x</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_y</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_w</parameter></paramdef>
   <paramdef>uint32_t <parameter>src_h</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane object to update
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     owning CRTC of owning plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fb</parameter></term>
   <listitem>
    <para>
     framebuffer to flip onto plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_x</parameter></term>
   <listitem>
    <para>
     x offset of primary plane on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_y</parameter></term>
   <listitem>
    <para>
     y offset of primary plane on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_w</parameter></term>
   <listitem>
    <para>
     width of primary plane rectangle on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>crtc_h</parameter></term>
   <listitem>
    <para>
     height of primary plane rectangle on crtc
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_x</parameter></term>
   <listitem>
    <para>
     x offset of <parameter>fb</parameter> for panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_y</parameter></term>
   <listitem>
    <para>
     y offset of <parameter>fb</parameter> for panning
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_w</parameter></term>
   <listitem>
    <para>
     width of source rectangle in <parameter>fb</parameter>
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>src_h</parameter></term>
   <listitem>
    <para>
     height of source rectangle in <parameter>fb</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane update handler using the atomic plane update
   functions. It is fully left to the driver to check plane constraints and
   handle corner-cases like a fully occluded or otherwise invisible plane.
   </para><para>

   This is useful for piecewise transitioning of a driver to the atomic helpers.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-plane-helper-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_plane_helper_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_plane_helper_disable</refname>
 <refpurpose>
     Transitional helper for plane disable
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_plane_helper_disable </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to disable
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Provides a default plane disable handler using the atomic plane update
   functions. It is fully left to the driver to check plane constraints and
   handle corner-cases like a fully occluded or otherwise invisible plane.
   </para><para>

   This is useful for piecewise transitioning of a driver to the atomic helpers.
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<para>
   </para><para>
   This helper library has two parts. The first part has support to implement
   primary plane support on top of the normal CRTC configuration interface.
   Since the legacy -&gt;set_config interface ties the primary plane together with
   the CRTC state this does not allow userspace to disable the primary plane
   itself.  To avoid too much duplicated code use
   <function>drm_plane_helper_check_update</function> which can be used to enforce the same
   restrictions as primary planes had thus. The default primary plane only
   expose XRBG8888 and ARGB8888 as valid pixel formats for the attached
   framebuffer.
   </para><para>
   Drivers are highly recommended to implement proper support for primary
   planes, and newly merged drivers must not rely upon these transitional
   helpers.
   </para><para>
   The second part also implements transitional helpers which allow drivers to
   gradually switch to the atomic helper infrastructure for plane updates. Once
   that switch is complete drivers shouldn't use these any longer, instead using
   the proper legacy implementations for update and disable plane hooks provided
   by the atomic helpers.
   </para><para>
   Again drivers are strongly urged to switch to the new interfaces.
</para>

    </sect2>
    <sect2>
	  <title>Tile group</title>
<para>
   </para><para>
   Tile groups are used to represent tiled monitors with a unique
   integer identifier. Tiled monitors using DisplayID v1.3 have
   a unique 8-byte handle, we store this in a tile group, so we
   have a common identifier for all tiles in a monitor group.
</para>

    </sect2>
    <sect2>
	<title>Bridges</title>
      <sect3>
	 <title>Overview</title>
<para>
   </para><para>
   drm_bridge represents a device that hangs on to an encoder. These are handy
   when a regular drm_encoder entity isn't enough to represent the entire
   encoder chain.
   </para><para>
   A bridge is always associated to a single drm_encoder at a time, but can be
   either connected to it directly, or through an intermediate bridge:
   </para><para>
   encoder ---&gt; bridge B ---&gt; bridge A
   </para><para>
   Here, the output of the encoder feeds to bridge B, and that furthers feeds to
   bridge A.
   </para><para>
   The driver using the bridge is responsible to make the associations between
   the encoder and bridges. Once these links are made, the bridges will
   participate along with encoder functions to perform mode_set/enable/disable
   through the ops provided in drm_bridge_funcs.
   </para><para>
   drm_bridge, like drm_panel, aren't drm_mode_object entities like planes,
   crtcs, encoders or connectors. They just provide additional hooks to get the
   desired output at the end of the encoder chain.
</para>

      </sect3>
      <sect3>
	 <title>Default bridge callback sequence</title>
<para>
   </para><para>
   The drm_bridge_funcs ops are populated by the bridge driver. The drm
   internals(atomic and crtc helpers) use the helpers defined in drm_bridge.c
   These helpers call a specific drm_bridge_funcs op for all the bridges
   during encoder configuration.
   </para><para>
   When creating a bridge driver, one can implement drm_bridge_funcs op with
   the help of these rough rules:
   </para><para>
   pre_enable: this contains things needed to be done for the bridge before
   its clock and timings are enabled by its source. For a bridge, its source
   is generally the encoder or bridge just before it in the encoder chain.
   </para><para>
   enable: this contains things needed to be done for the bridge once its
   source is enabled. In other words, enable is called once the source is
   ready with clock and timing needed by the bridge.
   </para><para>
   disable: this contains things needed to be done for the bridge assuming
   that its source is still enabled, i.e. clock and timings are still on.
   </para><para>
   post_disable: this contains things needed to be done for the bridge once
   its source is disabled, i.e. once clocks and timings are off.
   </para><para>
   mode_fixup: this should fixup the given mode for the bridge. It is called
   after the encoder's mode fixup. mode_fixup can also reject a mode completely
   if it's unsuitable for the hardware.
   </para><para>
   mode_set: this sets up the mode for the bridge. It assumes that its source
   (an encoder or a bridge) has set the mode too.
</para>

      </sect3>
<!-- drivers/gpu/drm/drm_bridge.c -->
<refentry id="API-drm-bridge-add">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_add</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_add</refname>
 <refpurpose>
  add the given bridge to the global bridge list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_bridge_add </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Unconditionally returns Zero.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-remove">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_remove</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_remove</refname>
 <refpurpose>
     remove the given bridge from the global bridge list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_bridge_remove </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-attach">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_attach</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_attach</refname>
 <refpurpose>
     associate given bridge to our DRM device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_bridge_attach </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   called by a kms driver to link one of our encoder/bridge to the given
   bridge.
   </para><para>

   Note that setting up links between the bridge and our encoder/bridge
   objects needs to be handled by the kms driver itself
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   Zero on success, error code on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-mode-fixup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_mode_fixup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_mode_fixup</refname>
 <refpurpose>
     fixup proposed mode for all bridges in the encoder chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_bridge_mode_fixup </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>adjusted_mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     desired mode to be set for the bridge
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adjusted_mode</parameter></term>
   <listitem>
    <para>
     updated mode that works for this bridge
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls 'mode_fixup' drm_bridge_funcs op for all the bridges in the
   encoder chain, starting from the first bridge to the last.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the bridge passed should be the one closest to the encoder
</para>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   true on success, false on failure
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_disable</refname>
 <refpurpose>
     calls 'disable' drm_bridge_funcs op for all bridges in the encoder chain.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_bridge_disable </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls 'disable' drm_bridge_funcs op for all the bridges in the encoder
   chain, starting from the last bridge to the first. These are called before
   calling the encoder's prepare op.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the bridge passed should be the one closest to the encoder
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-post-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_post_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_post_disable</refname>
 <refpurpose>
     calls 'post_disable' drm_bridge_funcs op for all bridges in the encoder chain.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_bridge_post_disable </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls 'post_disable' drm_bridge_funcs op for all the bridges in the
   encoder chain, starting from the first bridge to the last. These are called
   after completing the encoder's prepare op.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the bridge passed should be the one closest to the encoder
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-mode-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_mode_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_mode_set</refname>
 <refpurpose>
     set proposed mode for all bridges in the encoder chain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_bridge_mode_set </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>mode</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>adjusted_mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     desired mode to be set for the bridge
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>adjusted_mode</parameter></term>
   <listitem>
    <para>
     updated mode that works for this bridge
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls 'mode_set' drm_bridge_funcs op for all the bridges in the
   encoder chain, starting from the first bridge to the last.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the bridge passed should be the one closest to the encoder
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-pre-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_pre_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_pre_enable</refname>
 <refpurpose>
     calls 'pre_enable' drm_bridge_funcs op for all bridges in the encoder chain.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_bridge_pre_enable </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls 'pre_enable' drm_bridge_funcs op for all the bridges in the encoder
   chain, starting from the last bridge to the first. These are called
   before calling the encoder's commit op.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   the bridge passed should be the one closest to the encoder
</para>
</refsect1>
</refentry>

<refentry id="API-drm-bridge-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_bridge_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_bridge_enable</refname>
 <refpurpose>
     calls 'enable' drm_bridge_funcs op for all bridges in the encoder chain.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_bridge_enable </function></funcdef>
   <paramdef>struct drm_bridge * <parameter>bridge</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>bridge</parameter></term>
   <listitem>
    <para>
     bridge control structure
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls 'enable' drm_bridge_funcs op for all the bridges in the encoder
   chain, starting from the first bridge to the last. These are called
   after completing the encoder's commit op.
   </para><para>

   Note that the bridge passed should be the one closest to the encoder
</para>
</refsect1>
</refentry>

<refentry id="API-of-drm-find-bridge">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>of_drm_find_bridge</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>of_drm_find_bridge</refname>
 <refpurpose>
     find the bridge corresponding to the device node in the global bridge list
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_bridge * <function>of_drm_find_bridge </function></funcdef>
   <paramdef>struct device_node * <parameter>np</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>np</parameter></term>
   <listitem>
    <para>
     device node
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>RETURNS</title>
<para>
   drm_bridge control struct on success, NULL on failure
</para>
</refsect1>
</refentry>

    </sect2>
  </sect1>

  <!-- Internals: kms properties -->

  <sect1 id="drm-kms-properties">
    <title>KMS Properties</title>
    <para>
      Drivers may need to expose additional parameters to applications than
      those described in the previous sections. KMS supports attaching
      properties to CRTCs, connectors and planes and offers a userspace API to
      list, get and set the property values.
    </para>
    <para>
      Properties are identified by a name that uniquely defines the property
      purpose, and store an associated value. For all property types except blob
      properties the value is a 64-bit unsigned integer.
    </para>
    <para>
      KMS differentiates between properties and property instances. Drivers
      first create properties and then create and associate individual instances
      of those properties to objects. A property can be instantiated multiple
      times and associated with different objects. Values are stored in property
      instances, and all other property information are stored in the property
      and shared between all instances of the property.
    </para>
    <para>
      Every property is created with a type that influences how the KMS core
      handles the property. Supported property types are
      <variablelist>
        <varlistentry>
          <term>DRM_MODE_PROP_RANGE</term>
          <listitem><para>Range properties report their minimum and maximum
            admissible values. The KMS core verifies that values set by
            application fit in that range.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>DRM_MODE_PROP_ENUM</term>
          <listitem><para>Enumerated properties take a numerical value that
            ranges from 0 to the number of enumerated values defined by the
            property minus one, and associate a free-formed string name to each
            value. Applications can retrieve the list of defined value-name pairs
            and use the numerical value to get and set property instance values.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term>DRM_MODE_PROP_BITMASK</term>
          <listitem><para>Bitmask properties are enumeration properties that
            additionally restrict all enumerated values to the 0..63 range.
            Bitmask property instance values combine one or more of the
            enumerated bits defined by the property.</para></listitem>
        </varlistentry>
        <varlistentry>
          <term>DRM_MODE_PROP_BLOB</term>
          <listitem><para>Blob properties store a binary blob without any format
            restriction. The binary blobs are created as KMS standalone objects,
            and blob property instance values store the ID of their associated
            blob object.</para>
	    <para>Blob properties are only used for the connector EDID property
	    and cannot be created by drivers.</para></listitem>
        </varlistentry>
      </variablelist>
    </para>
    <para>
      To create a property drivers call one of the following functions depending
      on the property type. All property creation functions take property flags
      and name, as well as type-specific arguments.
      <itemizedlist>
        <listitem>
          <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags,
                                               const char *name,
                                               uint64_t min, uint64_t max);</synopsis>
          <para>Create a range property with the given minimum and maximum
            values.</para>
        </listitem>
        <listitem>
          <synopsis>struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags,
                                              const char *name,
                                              const struct drm_prop_enum_list *props,
                                              int num_values);</synopsis>
          <para>Create an enumerated property. The <parameter>props</parameter>
            argument points to an array of <parameter>num_values</parameter>
            value-name pairs.</para>
        </listitem>
        <listitem>
          <synopsis>struct drm_property *drm_property_create_bitmask(struct drm_device *dev,
                                                 int flags, const char *name,
                                                 const struct drm_prop_enum_list *props,
                                                 int num_values);</synopsis>
          <para>Create a bitmask property. The <parameter>props</parameter>
            argument points to an array of <parameter>num_values</parameter>
            value-name pairs.</para>
        </listitem>
      </itemizedlist>
    </para>
    <para>
      Properties can additionally be created as immutable, in which case they
      will be read-only for applications but can be modified by the driver. To
      create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE
      flag at property creation time.
    </para>
    <para>
      When no array of value-name pairs is readily available at property
      creation time for enumerated or range properties, drivers can create
      the property using the <function>drm_property_create</function> function
      and manually add enumeration value-name pairs by calling the
      <function>drm_property_add_enum</function> function. Care must be taken to
      properly specify the property type through the <parameter>flags</parameter>
      argument.
    </para>
    <para>
      After creating properties drivers can attach property instances to CRTC,
      connector and plane objects by calling the
      <function>drm_object_attach_property</function>. The function takes a
      pointer to the target object, a pointer to the previously created property
      and an initial instance value.
    </para>
    <sect2>
	<title>Existing KMS Properties</title>
	<para>
	The following table gives description of drm properties exposed by various
	modules/drivers.
	</para>
	<table border="1" cellpadding="0" cellspacing="0">
	<tbody>
	<tr style="font-weight: bold;">
	<td valign="top" >Owner Module/Drivers</td>
	<td valign="top" >Group</td>
	<td valign="top" >Property Name</td>
	<td valign="top" >Type</td>
	<td valign="top" >Property Values</td>
	<td valign="top" >Object attached</td>
	<td valign="top" >Description/Restrictions</td>
	</tr>
	<tr>
	<td rowspan="37" valign="top" >DRM</td>
	<td valign="top" >Generic</td>
	<td valign="top" >“rotation”</td>
	<td valign="top" >BITMASK</td>
	<td valign="top" >{ 0, "rotate-0" },
	{ 1, "rotate-90" },
	{ 2, "rotate-180" },
	{ 3, "rotate-270" },
	{ 4, "reflect-x" },
	{ 5, "reflect-y" }</td>
	<td valign="top" >CRTC, Plane</td>
	<td valign="top" >rotate-(degrees) rotates the image by the specified amount in degrees
	in counter clockwise direction. reflect-x and reflect-y reflects the
	image along the specified axis prior to rotation</td>
	</tr>
	<tr>
	<td rowspan="5" valign="top" >Connector</td>
	<td valign="top" >“EDID”</td>
	<td valign="top" >BLOB | IMMUTABLE</td>
	<td valign="top" >0</td>
	<td valign="top" >Connector</td>
	<td valign="top" >Contains id of edid blob ptr object.</td>
	</tr>
	<tr>
	<td valign="top" >“DPMS”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >Contains DPMS operation mode value.</td>
	</tr>
	<tr>
	<td valign="top" >“PATH”</td>
	<td valign="top" >BLOB | IMMUTABLE</td>
	<td valign="top" >0</td>
	<td valign="top" >Connector</td>
	<td valign="top" >Contains topology path to a connector.</td>
	</tr>
	<tr>
	<td valign="top" >“TILE”</td>
	<td valign="top" >BLOB | IMMUTABLE</td>
	<td valign="top" >0</td>
	<td valign="top" >Connector</td>
	<td valign="top" >Contains tiling information for a connector.</td>
	</tr>
	<tr>
	<td valign="top" >“CRTC_ID”</td>
	<td valign="top" >OBJECT</td>
	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
	<td valign="top" >Connector</td>
	<td valign="top" >CRTC that connector is attached to (atomic)</td>
	</tr>
	<tr>
	<td rowspan="11" valign="top" >Plane</td>
	<td valign="top" >“type”</td>
	<td valign="top" >ENUM | IMMUTABLE</td>
	<td valign="top" >{ "Overlay", "Primary", "Cursor" }</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Plane type</td>
	</tr>
	<tr>
	<td valign="top" >“SRC_X”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=UINT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“SRC_Y”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=UINT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“SRC_W”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=UINT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“SRC_H”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=UINT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“CRTC_X”</td>
	<td valign="top" >SIGNED_RANGE</td>
	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“CRTC_Y”</td>
	<td valign="top" >SIGNED_RANGE</td>
	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“CRTC_W”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=UINT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout CRTC (destination) width (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“CRTC_H”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=UINT_MAX</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout CRTC (destination) height (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“FB_ID”</td>
	<td valign="top" >OBJECT</td>
	<td valign="top" >DRM_MODE_OBJECT_FB</td>
	<td valign="top" >Plane</td>
	<td valign="top" >Scanout framebuffer (atomic)</td>
	</tr>
	<tr>
	<td valign="top" >“CRTC_ID”</td>
	<td valign="top" >OBJECT</td>
	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
	<td valign="top" >Plane</td>
	<td valign="top" >CRTC that plane is attached to (atomic)</td>
	</tr>
	<tr>
	<td rowspan="2" valign="top" >DVI-I</td>
	<td valign="top" >“subconnector”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“select subconnector”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="13" valign="top" >TV</td>
	<td valign="top" >“subconnector”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“select subconnector”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“left margin”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“right margin”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“top margin”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“bottom margin”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“brightness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“contrast”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker reduction”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“overscan”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“saturation”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“hue”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="2" valign="top" >Virtual GPU</td>
	<td valign="top" >“suggested X”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffffff</td>
	<td valign="top" >Connector</td>
	<td valign="top" >property to suggest an X offset for a connector</td>
	</tr>
	<tr>
	<td valign="top" >“suggested Y”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffffff</td>
	<td valign="top" >Connector</td>
	<td valign="top" >property to suggest an Y offset for a connector</td>
	</tr>
	<tr>
	<td rowspan="3" valign="top" >Optional</td>
	<td valign="top" >“scaling mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"aspect ratio"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "None", "4:3", "16:9" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >DRM property to set aspect ratio from user space app.
		This enum is made generic to allow addition of custom aspect
		ratios.</td>
	</tr>
	<tr>
	<td valign="top" >“dirty”</td>
	<td valign="top" >ENUM | IMMUTABLE</td>
	<td valign="top" >{ "Off", "On", "Annotate" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="20" valign="top" >i915</td>
	<td rowspan="2" valign="top" >Generic</td>
	<td valign="top" >"Broadcast RGB"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“audio”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "force-dvi", "off", "auto", "on" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="17" valign="top" >SDVO-TV</td>
	<td valign="top" >“mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"left_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"right_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"top_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"bottom_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“hpos”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“vpos”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“contrast”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“saturation”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“hue”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“sharpness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker_filter”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker_filter_adaptive”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker_filter_2d”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“tv_chroma_filter”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“tv_luma_filter”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“dot_crawl”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >SDVO-TV/LVDS</td>
	<td valign="top" >“brightness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="2" valign="top" >CDV gma-500</td>
	<td rowspan="2" valign="top" >Generic</td>
	<td valign="top" >"Broadcast RGB"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ “Full”, “Limited 16:235” }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"Broadcast RGB"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ “off”, “auto”, “on” }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="19" valign="top" >Poulsbo</td>
	<td rowspan="1" valign="top" >Generic</td>
	<td valign="top" >“backlight”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=100</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="17" valign="top" >SDVO-TV</td>
	<td valign="top" >“mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"left_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"right_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"top_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"bottom_margin"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“hpos”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“vpos”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“contrast”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“saturation”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“hue”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“sharpness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker_filter”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker_filter_adaptive”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“flicker_filter_2d”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“tv_chroma_filter”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“tv_luma_filter”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“dot_crawl”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >SDVO-TV/LVDS</td>
	<td valign="top" >“brightness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max= SDVO dependent</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="11" valign="top" >armada</td>
	<td rowspan="2" valign="top" >CRTC</td>
	<td valign="top" >"CSC_YUV"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td>
	<td valign="top" >CRTC</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"CSC_RGB"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "Auto", "Computer system", "Studio" }</td>
	<td valign="top" >CRTC</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="9" valign="top" >Overlay</td>
	<td valign="top" >"colorkey"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"colorkey_min"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"colorkey_max"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"colorkey_val"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"colorkey_alpha"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0xffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"colorkey_mode"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "disabled", "Y component", "U component"
	, "V component", "RGB", “R component", "G component", "B component" }</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"brightness"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=256 + 255</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"contrast"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0x7fff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"saturation"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0x7fff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="2" valign="top" >exynos</td>
	<td valign="top" >CRTC</td>
	<td valign="top" >“mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "normal", "blank" }</td>
	<td valign="top" >CRTC</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >Overlay</td>
	<td valign="top" >“zpos”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=MAX_PLANE-1</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="2" valign="top" >i2c/ch7006_drv</td>
	<td valign="top" >Generic</td>
	<td valign="top" >“scale”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=2</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="1" valign="top" >TV</td>
	<td valign="top" >“mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc"
	, "PAL-60", "NTSC-M", "NTSC-J" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="15" valign="top" >nouveau</td>
	<td rowspan="6" valign="top" >NV10 Overlay</td>
	<td valign="top" >"colorkey"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0x01ffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“contrast”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=8192-1</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“brightness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1024</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“hue”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=359</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“saturation”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=8192-1</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“iturbt_709”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="2" valign="top" >Nv04 Overlay</td>
	<td valign="top" >“colorkey”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0x01ffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“brightness”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1024</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="7" valign="top" >Display</td>
	<td valign="top" >“dithering mode”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "auto", "off", "on" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“dithering depth”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“underscan”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“underscan hborder”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=128</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“underscan vborder”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=128</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“vibrant hue”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=180</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >“color vibrance”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=200</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >omap</td>
	<td valign="top" >Generic</td>
	<td valign="top" >“zorder”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=3</td>
	<td valign="top" >CRTC, Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >qxl</td>
	<td valign="top" >Generic</td>
	<td valign="top" >“hotplug_mode_update"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="9" valign="top" >radeon</td>
	<td valign="top" >DVI-I</td>
	<td valign="top" >“coherent”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >DAC enable load detect</td>
	<td valign="top" >“load detection”</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=1</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >TV Standard</td>
	<td valign="top" >"tv standard"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j"
	, "scart-pal", "pal-cn", "secam" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >legacy TMDS PLL detect</td>
	<td valign="top" >"tmds_pll"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "driver", "bios" }</td>
	<td valign="top" >-</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="3" valign="top" >Underscan</td>
	<td valign="top" >"underscan"</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "off", "on", "auto" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"underscan hborder"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=128</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"underscan vborder"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=128</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >Audio</td>
	<td valign="top" >“audio”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "off", "on", "auto" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >FMT Dithering</td>
	<td valign="top" >“dither”</td>
	<td valign="top" >ENUM</td>
	<td valign="top" >{ "off", "on" }</td>
	<td valign="top" >Connector</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td rowspan="3" valign="top" >rcar-du</td>
	<td rowspan="3" valign="top" >Generic</td>
	<td valign="top" >"alpha"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=255</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"colorkey"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=0, Max=0x01ffffff</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	<tr>
	<td valign="top" >"zpos"</td>
	<td valign="top" >RANGE</td>
	<td valign="top" >Min=1, Max=7</td>
	<td valign="top" >Plane</td>
	<td valign="top" >TBD</td>
	</tr>
	</tbody>
	</table>
    </sect2>
  </sect1>

  <!-- Internals: vertical blanking -->

  <sect1 id="drm-vertical-blank">
    <title>Vertical Blanking</title>
    <para>
      Vertical blanking plays a major role in graphics rendering. To achieve
      tear-free display, users must synchronize page flips and/or rendering to
      vertical blanking. The DRM API offers ioctls to perform page flips
      synchronized to vertical blanking and wait for vertical blanking.
    </para>
    <para>
      The DRM core handles most of the vertical blanking management logic, which
      involves filtering out spurious interrupts, keeping race-free blanking
      counters, coping with counter wrap-around and resets and keeping use
      counts. It relies on the driver to generate vertical blanking interrupts
      and optionally provide a hardware vertical blanking counter. Drivers must
      implement the following operations.
    </para>
    <itemizedlist>
      <listitem>
        <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc);
void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis>
        <para>
	  Enable or disable vertical blanking interrupts for the given CRTC.
	</para>
      </listitem>
      <listitem>
        <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis>
        <para>
	  Retrieve the value of the vertical blanking counter for the given
	  CRTC. If the hardware maintains a vertical blanking counter its value
	  should be returned. Otherwise drivers can use the
	  <function>drm_vblank_count</function> helper function to handle this
	  operation.
	</para>
      </listitem>
    </itemizedlist>
    <para>
      Drivers must initialize the vertical blanking handling core with a call to
      <function>drm_vblank_init</function> in their
      <methodname>load</methodname> operation. The function will set the struct
      <structname>drm_device</structname>
      <structfield>vblank_disable_allowed</structfield> field to 0. This will
      keep vertical blanking interrupts enabled permanently until the first mode
      set operation, where <structfield>vblank_disable_allowed</structfield> is
      set to 1. The reason behind this is not clear. Drivers can set the field
      to 1 after <function>calling drm_vblank_init</function> to make vertical
      blanking interrupts dynamically managed from the beginning.
    </para>
    <para>
      Vertical blanking interrupts can be enabled by the DRM core or by drivers
      themselves (for instance to handle page flipping operations). The DRM core
      maintains a vertical blanking use count to ensure that the interrupts are
      not disabled while a user still needs them. To increment the use count,
      drivers call <function>drm_vblank_get</function>. Upon return vertical
      blanking interrupts are guaranteed to be enabled.
    </para>
    <para>
      To decrement the use count drivers call
      <function>drm_vblank_put</function>. Only when the use count drops to zero
      will the DRM core disable the vertical blanking interrupts after a delay
      by scheduling a timer. The delay is accessible through the vblankoffdelay
      module parameter or the <varname>drm_vblank_offdelay</varname> global
      variable and expressed in milliseconds. Its default value is 5000 ms.
      Zero means never disable, and a negative value means disable immediately.
      Drivers may override the behaviour by setting the
      <structname>drm_device</structname>
      <structfield>vblank_disable_immediate</structfield> flag, which when set
      causes vblank interrupts to be disabled immediately regardless of the
      drm_vblank_offdelay value. The flag should only be set if there's a
      properly working hardware vblank counter present.
    </para>
    <para>
      When a vertical blanking interrupt occurs drivers only need to call the
      <function>drm_handle_vblank</function> function to account for the
      interrupt.
    </para>
    <para>
      Resources allocated by <function>drm_vblank_init</function> must be freed
      with a call to <function>drm_vblank_cleanup</function> in the driver
      <methodname>unload</methodname> operation handler.
    </para>
    <sect2>
      <title>Vertical Blanking and Interrupt Handling Functions Reference</title>
<!-- drivers/gpu/drm/drm_irq.c -->
<refentry id="API-drm-vblank-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_cleanup</refname>
 <refpurpose>
  cleanup vblank support
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vblank_cleanup </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function cleans up any resources allocated in drm_vblank_init.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_init</refname>
 <refpurpose>
     initialize vblank support
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_vblank_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>num_crtcs</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_crtcs</parameter></term>
   <listitem>
    <para>
     number of CRTCs supported by <parameter>dev</parameter>
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function initializes vblank support for <parameter>num_crtcs</parameter> display pipelines.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-irq-install">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_irq_install</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_irq_install</refname>
 <refpurpose>
     install IRQ handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_irq_install </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>irq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>irq</parameter></term>
   <listitem>
    <para>
     IRQ number to install the handler for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes the IRQ related data. Installs the handler, calling the driver
   <function>irq_preinstall</function> and <function>irq_postinstall</function> functions before and after the
   installation.
   </para><para>

   This is the simplified helper interface provided for drivers with no special
   needs. Drivers which need to install interrupt handlers for multiple
   interrupts must instead set drm_device-&gt;irq_enabled to signal the DRM core
   that vblank interrupts are available.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-irq-uninstall">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_irq_uninstall</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_irq_uninstall</refname>
 <refpurpose>
     uninstall the IRQ handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_irq_uninstall </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calls the driver's <function>irq_uninstall</function> function and unregisters the IRQ handler.
   This should only be called by drivers which used <function>drm_irq_install</function> to set up
   their interrupt handler. Other drivers must only reset
   drm_device-&gt;irq_enabled to false.
   </para><para>

   Note that for kernel modesetting drivers it is a bug if this function fails.
   The sanity checks are only to catch buggy user modesetting drivers which call
   the same function through an ioctl.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-calc-timestamping-constants">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_calc_timestamping_constants</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_calc_timestamping_constants</refname>
 <refpurpose>
     calculate vblank timestamp constants
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_calc_timestamping_constants </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     drm_crtc whose timestamp constants should be updated.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     display mode containing the scanout timings
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Calculate and store various constants which are later
   needed by vblank and swap-completion timestamping, e.g,
   by <function>drm_calc_vbltimestamp_from_scanoutpos</function>. They are
   derived from CRTC's true scanout timing, so they take
   things like panel scaling or other adjustments into account.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-calc-vbltimestamp-from-scanoutpos">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_calc_vbltimestamp_from_scanoutpos</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_calc_vbltimestamp_from_scanoutpos</refname>
 <refpurpose>
     precise vblank timestamp helper
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_calc_vbltimestamp_from_scanoutpos </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
   <paramdef>int * <parameter>max_error</parameter></paramdef>
   <paramdef>struct timeval * <parameter>vblank_time</parameter></paramdef>
   <paramdef>unsigned <parameter>flags</parameter></paramdef>
   <paramdef>const struct drm_display_mode * <parameter>mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     index of CRTC whose vblank timestamp to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>max_error</parameter></term>
   <listitem>
    <para>
     Desired maximum allowable error in timestamps (nanosecs)
     On return contains true maximum error of timestamp
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vblank_time</parameter></term>
   <listitem>
    <para>
     Pointer to struct timeval which should receive the timestamp
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     Flags to pass to driver:
     0 = Default,
     DRM_CALLED_FROM_VBLIRQ = If function is called from vbl IRQ handler
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>mode</parameter></term>
   <listitem>
    <para>
     mode which defines the scanout timings
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Implements calculation of exact vblank timestamps from given drm_display_mode
   timings and current video scanout position of a CRTC. This can be called from
   within <function>get_vblank_timestamp</function> implementation of a kms driver to implement the
   actual timestamping.
   </para><para>

   Should return timestamps conforming to the OML_sync_control OpenML
   extension specification. The timestamp corresponds to the end of
   the vblank interval, aka start of scanout of topmost-leftmost display
   pixel in the following video frame.
   </para><para>

   Requires support for optional dev-&gt;driver-&gt;<function>get_scanout_position</function>
   in kms driver, plus a bit of setup code to provide a drm_display_mode
   that corresponds to the true scanout timing.
   </para><para>

   The current implementation only handles standard video modes. It
   returns as no operation if a doublescan or interlaced video mode is
   active. Higher level code is expected to handle this.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Negative value on error, failure or if not supported in current
</para>
</refsect1>
<refsect1>
<title>video mode</title>
<para>
   </para><para>

   -EINVAL   - Invalid CRTC.
   -EAGAIN   - Temporary unavailable, e.g., called before initial modeset.
   -ENOTSUPP - Function not supported in current display mode.
   -EIO      - Failed, e.g., due to failed scanout position query.
   </para><para>

   Returns or'ed positive status flags on success:
   </para><para>

   DRM_VBLANKTIME_SCANOUTPOS_METHOD - Signal this method used for timestamping.
   DRM_VBLANKTIME_INVBL - Timestamp taken while scanout was in vblank interval.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-count">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_count</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_count</refname>
 <refpurpose>
     retrieve <quote>cooked</quote> vblank counter value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>drm_vblank_count </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     index of CRTC for which to retrieve the counter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fetches the <quote>cooked</quote> vblank count value that represents the number of
   vblank events since the system was booted, including lost events due to
   modesetting activity.
   </para><para>

   This is the legacy version of <function>drm_crtc_vblank_count</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The software vblank counter.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-count">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_count</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_count</refname>
 <refpurpose>
     retrieve <quote>cooked</quote> vblank counter value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>drm_crtc_vblank_count </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     which counter to retrieve
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fetches the <quote>cooked</quote> vblank count value that represents the number of
   vblank events since the system was booted, including lost events due to
   modesetting activity.
   </para><para>

   This is the native KMS version of <function>drm_vblank_count</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The software vblank counter.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-count-and-time">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_count_and_time</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_count_and_time</refname>
 <refpurpose>
     retrieve <quote>cooked</quote> vblank counter value and the system timestamp corresponding to that vblank counter value.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>drm_vblank_count_and_time </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
   <paramdef>struct timeval * <parameter>vblanktime</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     index of CRTC whose counter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vblanktime</parameter></term>
   <listitem>
    <para>
     Pointer to struct timeval to receive the vblank timestamp.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fetches the <quote>cooked</quote> vblank count value that represents the number of
   vblank events since the system was booted, including lost events due to
   modesetting activity. Returns corresponding system timestamp of the time
   of the vblank interval that corresponds to the current vblank counter value.
   </para><para>

   This is the legacy version of <function>drm_crtc_vblank_count_and_time</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-count-and-time">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_count_and_time</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_count_and_time</refname>
 <refpurpose>
     retrieve <quote>cooked</quote> vblank counter value and the system timestamp corresponding to that vblank counter value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>drm_crtc_vblank_count_and_time </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct timeval * <parameter>vblanktime</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     which counter to retrieve
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vblanktime</parameter></term>
   <listitem>
    <para>
     Pointer to struct timeval to receive the vblank timestamp.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Fetches the <quote>cooked</quote> vblank count value that represents the number of
   vblank events since the system was booted, including lost events due to
   modesetting activity. Returns corresponding system timestamp of the time
   of the vblank interval that corresponds to the current vblank counter value.
   </para><para>

   This is the native KMS version of <function>drm_vblank_count_and_time</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-arm-vblank-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_arm_vblank_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_arm_vblank_event</refname>
 <refpurpose>
     arm vblank event after pageflip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_arm_vblank_event </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
   <paramdef>struct drm_pending_vblank_event * <parameter>e</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>e</parameter></term>
   <listitem>
    <para>
     the event to prepare to send
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A lot of drivers need to generate vblank events for the very next vblank
   interrupt. For example when the page flip interrupt happens when the page
   flip gets armed, but not when it actually executes within the next vblank
   period. This helper function implements exactly the required vblank arming
   behaviour.
   </para><para>

   Caller must hold event lock. Caller must also hold a vblank reference for
   the event <parameter>e</parameter>, which will be dropped when the next vblank arrives.
   </para><para>

   This is the legacy version of <function>drm_crtc_arm_vblank_event</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-arm-vblank-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_arm_vblank_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_arm_vblank_event</refname>
 <refpurpose>
     arm vblank event after pageflip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_arm_vblank_event </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_pending_vblank_event * <parameter>e</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     the source CRTC of the vblank event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>e</parameter></term>
   <listitem>
    <para>
     the event to send
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   A lot of drivers need to generate vblank events for the very next vblank
   interrupt. For example when the page flip interrupt happens when the page
   flip gets armed, but not when it actually executes within the next vblank
   period. This helper function implements exactly the required vblank arming
   behaviour.
   </para><para>

   Caller must hold event lock. Caller must also hold a vblank reference for
   the event <parameter>e</parameter>, which will be dropped when the next vblank arrives.
   </para><para>

   This is the native KMS version of <function>drm_arm_vblank_event</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-send-vblank-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_send_vblank_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_send_vblank_event</refname>
 <refpurpose>
     helper to send vblank event after pageflip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_send_vblank_event </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
   <paramdef>struct drm_pending_vblank_event * <parameter>e</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>e</parameter></term>
   <listitem>
    <para>
     the event to send
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Updates sequence # and timestamp on event, and sends it to userspace.
   Caller must hold event lock.
   </para><para>

   This is the legacy version of <function>drm_crtc_send_vblank_event</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-send-vblank-event">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_send_vblank_event</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_send_vblank_event</refname>
 <refpurpose>
     helper to send vblank event after pageflip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_send_vblank_event </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
   <paramdef>struct drm_pending_vblank_event * <parameter>e</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     the source CRTC of the vblank event
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>e</parameter></term>
   <listitem>
    <para>
     the event to send
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Updates sequence # and timestamp on event, and sends it to userspace.
   Caller must hold event lock.
   </para><para>

   This is the native KMS version of <function>drm_send_vblank_event</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_get</refname>
 <refpurpose>
     get a reference count on vblank events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_vblank_get </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     index of CRTC to own
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Acquire a reference count on vblank events to avoid having them disabled
   while in use.
   </para><para>

   This is the legacy version of <function>drm_crtc_vblank_get</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_get</refname>
 <refpurpose>
     get a reference count on vblank events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_crtc_vblank_get </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     which CRTC to own
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Acquire a reference count on vblank events to avoid having them disabled
   while in use.
   </para><para>

   This is the native kms version of <function>drm_vblank_get</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success or a negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_put</refname>
 <refpurpose>
     release ownership of vblank events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vblank_put </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     index of CRTC to release
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release ownership of a given vblank counter, turning off interrupts
   if possible. Disable interrupts after drm_vblank_offdelay milliseconds.
   </para><para>

   This is the legacy version of <function>drm_crtc_vblank_put</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_put</refname>
 <refpurpose>
     give up ownership of vblank events
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_vblank_put </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     which counter to give up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Release ownership of a given vblank counter, turning off interrupts
   if possible. Disable interrupts after drm_vblank_offdelay milliseconds.
   </para><para>

   This is the native kms version of <function>drm_vblank_put</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-wait-one-vblank">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_wait_one_vblank</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_wait_one_vblank</refname>
 <refpurpose>
     wait for one vblank
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_wait_one_vblank </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This waits for one vblank to pass on <parameter>pipe</parameter>, using the irq driver interfaces.
   It is a failure to call this when the vblank irq for <parameter>pipe</parameter> is disabled, e.g.
   due to lack of driver support or because the crtc is off.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-wait-one-vblank">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_wait_one_vblank</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_wait_one_vblank</refname>
 <refpurpose>
     wait for one vblank
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_wait_one_vblank </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     DRM crtc
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This waits for one vblank to pass on <parameter>crtc</parameter>, using the irq driver interfaces.
   It is a failure to call this when the vblank irq for <parameter>crtc</parameter> is disabled, e.g.
   due to lack of driver support or because the crtc is off.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_off</refname>
 <refpurpose>
     disable vblank events on a CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vblank_off </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers can use this function to shut down the vblank interrupt handling when
   disabling a crtc. This function ensures that the latest vblank frame count is
   stored so that <function>drm_vblank_on</function> can restore it again.
   </para><para>

   Drivers must use this function when the hardware vblank counter can get
   reset, e.g. when suspending.
   </para><para>

   This is the legacy version of <function>drm_crtc_vblank_off</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-off">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_off</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_off</refname>
 <refpurpose>
     disable vblank events on a CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_vblank_off </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers can use this function to shut down the vblank interrupt handling when
   disabling a crtc. This function ensures that the latest vblank frame count is
   stored so that drm_vblank_on can restore it again.
   </para><para>

   Drivers must use this function when the hardware vblank counter can get
   reset, e.g. when suspending.
   </para><para>

   This is the native kms version of <function>drm_vblank_off</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-reset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_reset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_reset</refname>
 <refpurpose>
     reset vblank state to off on a CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_vblank_reset </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers can use this function to reset the vblank state to off at load time.
   Drivers should use this together with the <function>drm_crtc_vblank_off</function> and
   <function>drm_crtc_vblank_on</function> functions. The difference compared to
   <function>drm_crtc_vblank_off</function> is that this function doesn't save the vblank counter
   and hence doesn't need to call any driver hooks.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_on</refname>
 <refpurpose>
     enable vblank events on a CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vblank_on </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions restores the vblank interrupt state captured with
   <function>drm_vblank_off</function> again. Note that calls to <function>drm_vblank_on</function> and
   <function>drm_vblank_off</function> can be unbalanced and so can also be unconditionally called
   in driver load code to reflect the current hardware state of the crtc.
   </para><para>

   This is the legacy version of <function>drm_crtc_vblank_on</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-on">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_on</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_on</refname>
 <refpurpose>
     enable vblank events on a CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_crtc_vblank_on </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     CRTC in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This functions restores the vblank interrupt state captured with
   <function>drm_vblank_off</function> again. Note that calls to <function>drm_vblank_on</function> and
   <function>drm_vblank_off</function> can be unbalanced and so can also be unconditionally called
   in driver load code to reflect the current hardware state of the crtc.
   </para><para>

   This is the native kms version of <function>drm_vblank_on</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-pre-modeset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_pre_modeset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_pre_modeset</refname>
 <refpurpose>
     account for vblanks across mode sets
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vblank_pre_modeset </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Account for vblank events across mode setting events, which will likely
   reset the hardware frame counter.
   </para><para>

   This is done by grabbing a temporary vblank reference to ensure that the
   vblank interrupt keeps running across the modeset sequence. With this the
   software-side vblank frame counting will ensure that there are no jumps or
   discontinuities.
   </para><para>

   Unfortunately this approach is racy and also doesn't work when the vblank
   interrupt stops running, e.g. across system suspend resume. It is therefore
   highly recommended that drivers use the newer <function>drm_vblank_off</function> and
   <function>drm_vblank_on</function> instead. <function>drm_vblank_pre_modeset</function> only works correctly when
   using <quote>cooked</quote> software vblank frame counters and not relying on any hardware
   counters.
   </para><para>

   Drivers must call <function>drm_vblank_post_modeset</function> when re-enabling the same crtc
   again.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-post-modeset">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_post_modeset</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_post_modeset</refname>
 <refpurpose>
     undo drm_vblank_pre_modeset changes
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>drm_vblank_post_modeset </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC index
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function again drops the temporary vblank reference acquired in
   drm_vblank_pre_modeset.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-handle-vblank">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_handle_vblank</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_handle_vblank</refname>
 <refpurpose>
     handle a vblank event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_handle_vblank </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     index of CRTC where this event occurred
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers should call this routine in their vblank interrupt handlers to
   update the vblank counter and send any signals that may be pending.
   </para><para>

   This is the legacy version of <function>drm_crtc_handle_vblank</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-handle-vblank">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_handle_vblank</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_handle_vblank</refname>
 <refpurpose>
     handle a vblank event
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_crtc_handle_vblank </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     where this event occurred
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers should call this routine in their vblank interrupt handlers to
   update the vblank counter and send any signals that may be pending.
   </para><para>

   This is the native KMS version of <function>drm_handle_vblank</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the event was successfully handled, false on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-vblank-no-hw-counter">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_vblank_no_hw_counter</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_vblank_no_hw_counter</refname>
 <refpurpose>
     "No hw counter" implementation of .<function>get_vblank_counter</function>
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>drm_vblank_no_hw_counter </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned int <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     CRTC for which to read the counter
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Drivers can plug this into the .<function>get_vblank_counter</function> function if
   there is no useable hardware frame counter available.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   0
</para>
</refsect1>
</refentry>

<refentry id="API-drm-crtc-vblank-waitqueue">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_crtc_vblank_waitqueue</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_crtc_vblank_waitqueue</refname>
 <refpurpose>
  get vblank waitqueue for the CRTC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>wait_queue_head_t * <function>drm_crtc_vblank_waitqueue </function></funcdef>
   <paramdef>struct drm_crtc * <parameter>crtc</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>crtc</parameter></term>
   <listitem>
    <para>
     which CRTC's vblank waitqueue to retrieve
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function returns a pointer to the vblank waitqueue for the CRTC.
   Drivers can use this to implement vblank waits using <function>wait_event</function> &amp; co.
</para>
</refsect1>
</refentry>

    </sect2>
  </sect1>

  <!-- Internals: open/close, file operations and ioctls -->

  <sect1>
    <title>Open/Close, File Operations and IOCTLs</title>
    <sect2>
      <title>Open and Close</title>
      <synopsis>int (*firstopen) (struct drm_device *);
void (*lastclose) (struct drm_device *);
int (*open) (struct drm_device *, struct drm_file *);
void (*preclose) (struct drm_device *, struct drm_file *);
void (*postclose) (struct drm_device *, struct drm_file *);</synopsis>
      <abstract>Open and close handlers. None of those methods are mandatory.
      </abstract>
      <para>
        The <methodname>firstopen</methodname> method is called by the DRM core
	for legacy UMS (User Mode Setting) drivers only when an application
	opens a device that has no other opened file handle. UMS drivers can
	implement it to acquire device resources. KMS drivers can't use the
	method and must acquire resources in the <methodname>load</methodname>
	method instead.
      </para>
      <para>
	Similarly the <methodname>lastclose</methodname> method is called when
	the last application holding a file handle opened on the device closes
	it, for both UMS and KMS drivers. Additionally, the method is also
	called at module unload time or, for hot-pluggable devices, when the
	device is unplugged. The <methodname>firstopen</methodname> and
	<methodname>lastclose</methodname> calls can thus be unbalanced.
      </para>
      <para>
        The <methodname>open</methodname> method is called every time the device
	is opened by an application. Drivers can allocate per-file private data
	in this method and store them in the struct
	<structname>drm_file</structname> <structfield>driver_priv</structfield>
	field. Note that the <methodname>open</methodname> method is called
	before <methodname>firstopen</methodname>.
      </para>
      <para>
        The close operation is split into <methodname>preclose</methodname> and
	<methodname>postclose</methodname> methods. Drivers must stop and
	cleanup all per-file operations in the <methodname>preclose</methodname>
	method. For instance pending vertical blanking and page flip events must
	be cancelled. No per-file operation is allowed on the file handle after
	returning from the <methodname>preclose</methodname> method.
      </para>
      <para>
        Finally the <methodname>postclose</methodname> method is called as the
	last step of the close operation, right before calling the
	<methodname>lastclose</methodname> method if no other open file handle
	exists for the device. Drivers that have allocated per-file private data
	in the <methodname>open</methodname> method should free it here.
      </para>
      <para>
        The <methodname>lastclose</methodname> method should restore CRTC and
	plane properties to default value, so that a subsequent open of the
	device will not inherit state from the previous user. It can also be
	used to execute delayed power switching state changes, e.g. in
	conjunction with the vga_switcheroo infrastructure (see
	<xref linkend="vga_switcheroo"/>). Beyond that KMS drivers should not
	do any further cleanup. Only legacy UMS drivers might need to clean up
	device state so that the vga console or an independent fbdev driver
	could take over.
      </para>
    </sect2>
    <sect2>
      <title>File Operations</title>
      <synopsis>const struct file_operations *fops</synopsis>
      <abstract>File operations for the DRM device node.</abstract>
      <para>
        Drivers must define the file operations structure that forms the DRM
	userspace API entry point, even though most of those operations are
	implemented in the DRM core. The <methodname>open</methodname>,
	<methodname>release</methodname> and <methodname>ioctl</methodname>
	operations are handled by
	<programlisting>
	.owner = THIS_MODULE,
	.open = drm_open,
	.release = drm_release,
	.unlocked_ioctl = drm_ioctl,
  #ifdef CONFIG_COMPAT
	.compat_ioctl = drm_compat_ioctl,
  #endif
        </programlisting>
      </para>
      <para>
        Drivers that implement private ioctls that requires 32/64bit
	compatibility support must provide their own
	<methodname>compat_ioctl</methodname> handler that processes private
	ioctls and calls <function>drm_compat_ioctl</function> for core ioctls.
      </para>
      <para>
        The <methodname>read</methodname> and <methodname>poll</methodname>
	operations provide support for reading DRM events and polling them. They
	are implemented by
	<programlisting>
	.poll = drm_poll,
	.read = drm_read,
	.llseek = no_llseek,
	</programlisting>
      </para>
      <para>
        The memory mapping implementation varies depending on how the driver
	manages memory. Pre-GEM drivers will use <function>drm_mmap</function>,
	while GEM-aware drivers will use <function>drm_gem_mmap</function>. See
	<xref linkend="drm-gem"/>.
	<programlisting>
	.mmap = drm_gem_mmap,
	</programlisting>
      </para>
      <para>
        No other file operation is supported by the DRM API.
      </para>
    </sect2>
    <sect2>
      <title>IOCTLs</title>
      <synopsis>struct drm_ioctl_desc *ioctls;
int num_ioctls;</synopsis>
      <abstract>Driver-specific ioctls descriptors table.</abstract>
      <para>
        Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls
	descriptors table is indexed by the ioctl number offset from the base
	value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the
	table entries.
      </para>
      <para>
        <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting>
	<para>
	  <parameter>ioctl</parameter> is the ioctl name. Drivers must define
	  the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number
	  offset from DRM_COMMAND_BASE and the ioctl number respectively. The
	  first macro is private to the device while the second must be exposed
	  to userspace in a public header.
	</para>
	<para>
	  <parameter>func</parameter> is a pointer to the ioctl handler function
	  compatible with the <type>drm_ioctl_t</type> type.
	  <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data,
		struct drm_file *file_priv);</programlisting>
	</para>
	<para>
	  <parameter>flags</parameter> is a bitmask combination of the following
	  values. It restricts how the ioctl is allowed to be called.
	  <itemizedlist>
	    <listitem><para>
	      DRM_AUTH - Only authenticated callers allowed
	    </para></listitem>
	    <listitem><para>
	      DRM_MASTER - The ioctl can only be called on the master file
	      handle
	    </para></listitem>
            <listitem><para>
	      DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed
	    </para></listitem>
            <listitem><para>
	      DRM_CONTROL_ALLOW - The ioctl can only be called on a control
	      device
	    </para></listitem>
            <listitem><para>
	      DRM_UNLOCKED - The ioctl handler will be called without locking
	      the DRM global mutex. This is the enforced default for kms drivers
	      (i.e. using the DRIVER_MODESET flag) and hence shouldn't be used
	      any more for new drivers.
	    </para></listitem>
	  </itemizedlist>
	</para>
      </para>
<!-- drivers/gpu/drm/drm_ioctl.c -->
<refentry id="API-drm-noop">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_noop</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_noop</refname>
 <refpurpose>
  DRM no-op ioctl implemntation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_noop </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device for the ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data pointer for the ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     DRM file for the ioctl call
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This no-op implementation for drm ioctls is useful for deprecated
   functionality where we can't return a failure code because existing userspace
   checks the result of the ioctl, but doesn't care about the action.
   </para><para>

   Always returns successfully with 0.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-invalid-op">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_invalid_op</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_invalid_op</refname>
 <refpurpose>
     DRM invalid ioctl implemntation
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>drm_invalid_op </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>struct drm_file * <parameter>file_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device for the ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data pointer for the ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file_priv</parameter></term>
   <listitem>
    <para>
     DRM file for the ioctl call
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This no-op implementation for drm ioctls is useful for deprecated
   functionality where we really don't want to allow userspace to call the ioctl
   any more. This is the case for old ums interfaces for drivers that
   transitioned to kms gradually and so kept the old legacy tables around. This
   only applies to radeon and i915 kms drivers, other drivers shouldn't need to
   use this function.
   </para><para>

   Always fails with a return value of -EINVAL.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-ioctl">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_ioctl</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_ioctl</refname>
 <refpurpose>
     ioctl callback implementation for DRM drivers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>long <function>drm_ioctl </function></funcdef>
   <paramdef>struct file * <parameter>filp</parameter></paramdef>
   <paramdef>unsigned int <parameter>cmd</parameter></paramdef>
   <paramdef>unsigned long <parameter>arg</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>filp</parameter></term>
   <listitem>
    <para>
     file this ioctl is called on
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cmd</parameter></term>
   <listitem>
    <para>
     ioctl cmd number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>arg</parameter></term>
   <listitem>
    <para>
     user argument
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Looks up the ioctl function in the </title>
<para>
   :ioctls table, checking for root
   previleges if so required, and dispatches to the respective function.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-drm-ioctl-flags">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>drm_ioctl_flags</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>drm_ioctl_flags</refname>
 <refpurpose>
     Check for core ioctl and return ioctl permission flags
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>drm_ioctl_flags </function></funcdef>
   <paramdef>unsigned int <parameter>nr</parameter></paramdef>
   <paramdef>unsigned int * <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>nr</parameter></term>
   <listitem>
    <para>
     ioctl number
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     where to return the ioctl permission flags
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This ioctl is only used by the vmwgfx driver to augment the access checks
   done by the drm core and insofar a pretty decent layering violation. This
   shouldn't be used by any drivers.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True if the <parameter>nr</parameter> corresponds to a DRM core ioctl numer, false otherwise.
</para>
</refsect1>
</refentry>

    </sect2>
  </sect1>
  <sect1>
    <title>Legacy Support Code</title>
    <para>
      The section very briefly covers some of the old legacy support code which
      is only used by old DRM drivers which have done a so-called shadow-attach
      to the underlying device instead of registering as a real driver. This
      also includes some of the old generic buffer management and command
      submission code. Do not use any of this in new and modern drivers.
    </para>

    <sect2>
      <title>Legacy Suspend/Resume</title>
      <para>
	The DRM core provides some suspend/resume code, but drivers wanting full
	suspend/resume support should provide save() and restore() functions.
	These are called at suspend, hibernate, or resume time, and should perform
	any state save or restore required by your device across suspend or
	hibernate states.
      </para>
      <synopsis>int (*suspend) (struct drm_device *, pm_message_t state);
  int (*resume) (struct drm_device *);</synopsis>
      <para>
	Those are legacy suspend and resume methods which
	<emphasis>only</emphasis> work with the legacy shadow-attach driver
	registration functions. New driver should use the power management
	interface provided by their bus type (usually through
	the struct <structname>device_driver</structname> dev_pm_ops) and set
	these methods to NULL.
      </para>
    </sect2>

    <sect2>
      <title>Legacy DMA Services</title>
      <para>
	This should cover how DMA mapping etc. is supported by the core.
	These functions are deprecated and should not be used.
      </para>
    </sect2>
  </sect1>
  </chapter>

<!-- TODO

- Add a glossary
- Document the struct_mutex catch-all lock
- Document connector properties

- Why is the load method optional?
- What are drivers supposed to set the initial display state to, and how?
  Connector's DPMS states are not initialized and are thus equal to
  DRM_MODE_DPMS_ON. The fbcon compatibility layer calls
  drm_helper_disable_unused_functions(), which disables unused encoders and
  CRTCs, but doesn't touch the connectors' DPMS state, and
  drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers
  that don't implement (or just don't use) fbcon compatibility need to call
  those functions themselves?
- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset()
  around mode setting. Should this be done in the DRM core?
- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset()
  call and never set back to 0. It seems to be safe to permanently set it to 1
  in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as
  well. This should be investigated.
- crtc and connector .save and .restore operations are only used internally in
  drivers, should they be removed from the core?
- encoder mid-layer .save and .restore operations are only used internally in
  drivers, should they be removed from the core?
- encoder mid-layer .detect operation is only used internally in drivers,
  should it be removed from the core?
-->

  <!-- External interfaces -->

  <chapter id="drmExternals">
    <title>Userland interfaces</title>
    <para>
      The DRM core exports several interfaces to applications,
      generally intended to be used through corresponding libdrm
      wrapper functions.  In addition, drivers export device-specific
      interfaces for use by userspace drivers &amp; device-aware
      applications through ioctls and sysfs files.
    </para>
    <para>
      External interfaces include: memory mapping, context management,
      DMA operations, AGP management, vblank control, fence
      management, memory management, and output management.
    </para>
    <para>
      Cover generic ioctls and sysfs layout here.  We only need high-level
      info, since man pages should cover the rest.
    </para>

  <!-- External: render nodes -->

    <sect1>
      <title>Render nodes</title>
      <para>
        DRM core provides multiple character-devices for user-space to use.
        Depending on which device is opened, user-space can perform a different
        set of operations (mainly ioctls). The primary node is always created
        and called card&lt;num&gt;. Additionally, a currently
        unused control node, called controlD&lt;num&gt; is also
        created. The primary node provides all legacy operations and
        historically was the only interface used by userspace. With KMS, the
        control node was introduced. However, the planned KMS control interface
        has never been written and so the control node stays unused to date.
      </para>
      <para>
        With the increased use of offscreen renderers and GPGPU applications,
        clients no longer require running compositors or graphics servers to
        make use of a GPU. But the DRM API required unprivileged clients to
        authenticate to a DRM-Master prior to getting GPU access. To avoid this
        step and to grant clients GPU access without authenticating, render
        nodes were introduced. Render nodes solely serve render clients, that
        is, no modesetting or privileged ioctls can be issued on render nodes.
        Only non-global rendering commands are allowed. If a driver supports
        render nodes, it must advertise it via the DRIVER_RENDER
        DRM driver capability. If not supported, the primary node must be used
        for render clients together with the legacy drmAuth authentication
        procedure.
      </para>
      <para>
        If a driver advertises render node support, DRM core will create a
        separate render node called renderD&lt;num&gt;. There will
        be one render node per device. No ioctls except  PRIME-related ioctls
        will be allowed on this node. Especially GEM_OPEN will be
        explicitly prohibited. Render nodes are designed to avoid the
        buffer-leaks, which occur if clients guess the flink names or mmap
        offsets on the legacy interface. Additionally to this basic interface,
        drivers must mark their driver-dependent render-only ioctls as
        DRM_RENDER_ALLOW so render clients can use them. Driver
        authors must be careful not to allow any privileged ioctls on render
        nodes.
      </para>
      <para>
        With render nodes, user-space can now control access to the render node
        via basic file-system access-modes. A running graphics server which
        authenticates clients on the privileged primary/legacy node is no longer
        required. Instead, a client can open the render node and is immediately
        granted GPU access. Communication between clients (or servers) is done
        via PRIME. FLINK from render node to legacy node is not supported. New
        clients must not use the insecure FLINK interface.
      </para>
      <para>
        Besides dropping all modeset/global ioctls, render nodes also drop the
        DRM-Master concept. There is no reason to associate render clients with
        a DRM-Master as they are independent of any graphics server. Besides,
        they must work without any running master, anyway.
        Drivers must be able to run without a master object if they support
        render nodes. If, on the other hand, a driver requires shared state
        between clients which is visible to user-space and accessible beyond
        open-file boundaries, they cannot support render nodes.
      </para>
    </sect1>

  <!-- External: vblank handling -->

    <sect1>
      <title>VBlank event handling</title>
      <para>
        The DRM core exposes two vertical blank related ioctls:
        <variablelist>
          <varlistentry>
            <term>DRM_IOCTL_WAIT_VBLANK</term>
            <listitem>
              <para>
                This takes a struct drm_wait_vblank structure as its argument,
                and it is used to block or request a signal when a specified
                vblank event occurs.
              </para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term>DRM_IOCTL_MODESET_CTL</term>
            <listitem>
              <para>
		This was only used for user-mode-settind drivers around
		modesetting changes to allow the kernel to update the vblank
		interrupt after mode setting, since on many devices the vertical
		blank counter is reset to 0 at some point during modeset. Modern
		drivers should not call this any more since with kernel mode
		setting it is a no-op.
              </para>
            </listitem>
          </varlistentry>
        </variablelist>
      </para>
    </sect1>

  </chapter>
</part>
<part id="drmDrivers">
  <title>DRM Drivers</title>

  <partintro>
    <para>
      This second part of the GPU Driver Developer's Guide documents driver
      code, implementation details and also all the driver-specific userspace
      interfaces. Especially since all hardware-acceleration interfaces to
      userspace are driver specific for efficiency and other reasons these
      interfaces can be rather substantial. Hence every driver has its own
      chapter.
    </para>
  </partintro>

  <chapter id="drmI915">
    <title>drm/i915 Intel GFX Driver</title>
    <para>
      The drm/i915 driver supports all (with the exception of some very early
      models) integrated GFX chipsets with both Intel display and rendering
      blocks. This excludes a set of SoC platforms with an SGX rendering unit,
      those have basic support through the gma500 drm driver.
    </para>
    <sect1>
      <title>Core Driver Infrastructure</title>
      <para>
	This section covers core driver infrastructure used by both the display
	and the GEM parts of the driver.
      </para>
      <sect2>
        <title>Runtime Power Management</title>
<para>
   </para><para>
   The i915 driver supports dynamic enabling and disabling of entire hardware
   blocks at runtime. This is especially important on the display side where
   software is supposed to control many power gates manually on recent hardware,
   since on the GT side a lot of the power management is done by the hardware.
   But even there some manual control at the device level is required.
   </para><para>
   Since i915 supports a diverse set of platforms with a unified codebase and
   hardware engineers just love to shuffle functionality around between power
   domains there's a sizeable amount of indirection required. This file provides
   generic functions to the driver for grabbing and releasing references for
   abstract power domains. It then maps those to the actual power wells
   present for a given platform.
</para>

<!-- drivers/gpu/drm/i915/intel_runtime_pm.c -->
<refentry id="API---intel-display-power-is-enabled">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__intel_display_power_is_enabled</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__intel_display_power_is_enabled</refname>
 <refpurpose>
  unlocked check for a power domain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>__intel_display_power_is_enabled </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     power domain to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the unlocked version of <function>intel_display_power_is_enabled</function> and should
   only be used from error capture and recovery code where deadlocks are
   possible.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True when the power domain is enabled, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-display-power-is-enabled">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_display_power_is_enabled</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_display_power_is_enabled</refname>
 <refpurpose>
     check for a power domain
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>intel_display_power_is_enabled </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     power domain to check
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used to check the hw power domain state. It is mostly
   used in hardware state readout functions. Everywhere else code should rely
   upon explicit power domain reference counting to ensure that the hardware
   block is powered up before accessing it.
   </para><para>

   Callers must hold the relevant modesetting locks to ensure that concurrent
   threads can't disable the power well while the caller tries to read a few
   registers.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   True when the power domain is enabled, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-display-set-init-power">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_display_set_init_power</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_display_set_init_power</refname>
 <refpurpose>
     set the initial power domain state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_display_set_init_power </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>bool <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     whether to enable or disable the initial power domain state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   For simplicity our driver load/unload and system suspend/resume code assumes
   that all power domains are always enabled. This functions controls the state
   of this little hack. While the initial power domain state is enabled runtime
   pm is effectively disabled.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-display-power-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_display_power_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_display_power_get</refname>
 <refpurpose>
     grab a power domain reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_display_power_get </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     power domain to reference
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function grabs a power domain reference for <parameter>domain</parameter> and ensures that the
   power domain and all its parents are powered up. Therefore users should only
   grab a reference to the innermost power domain they need.
   </para><para>

   Any power domain reference obtained by this function must have a symmetric
   call to <function>intel_display_power_put</function> to release the reference again.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-display-power-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_display_power_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_display_power_put</refname>
 <refpurpose>
     release a power domain reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_display_power_put </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum intel_display_power_domain <parameter>domain</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     power domain to reference
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function drops the power domain reference obtained by
   <function>intel_display_power_get</function> and might power down the corresponding hardware
   block right away if this is the last reference.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-power-domains-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_power_domains_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_power_domains_init</refname>
 <refpurpose>
     initializes the power domain structures
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_power_domains_init </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes the power domain structures for <parameter>dev_priv</parameter> depending upon the
   supported platform.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-power-domains-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_power_domains_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_power_domains_fini</refname>
 <refpurpose>
     finalizes the power domain structures
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_power_domains_fini </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Finalizes the power domain structures for <parameter>dev_priv</parameter> depending upon the
   supported platform. This function also disables runtime pm and ensures that
   the device stays powered up so that the driver can be reloaded.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-power-domains-init-hw">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_power_domains_init_hw</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_power_domains_init_hw</refname>
 <refpurpose>
     initialize hardware power domain state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_power_domains_init_hw </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function initializes the hardware power domain state and enables all
   power domains using <function>intel_display_set_init_power</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-runtime-pm-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_runtime_pm_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_runtime_pm_get</refname>
 <refpurpose>
     grab a runtime pm reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_runtime_pm_get </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function grabs a device-level runtime pm reference (mostly used for GEM
   code to ensure the GTT or GT is on) and ensures that it is powered up.
   </para><para>

   Any runtime pm reference obtained by this function must have a symmetric
   call to <function>intel_runtime_pm_put</function> to release the reference again.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-runtime-pm-get-noresume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_runtime_pm_get_noresume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_runtime_pm_get_noresume</refname>
 <refpurpose>
     grab a runtime pm reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_runtime_pm_get_noresume </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function grabs a device-level runtime pm reference (mostly used for GEM
   code to ensure the GTT or GT is on).
   </para><para>

   It will _not_ power up the device but instead only check that it's powered
   on.  Therefore it is only valid to call this functions from contexts where
   the device is known to be powered up and where trying to power it up would
   result in hilarity and deadlocks. That pretty much means only the system
   suspend/resume code where this is used to grab runtime pm references for
   delayed setup down in work items.
   </para><para>

   Any runtime pm reference obtained by this function must have a symmetric
   call to <function>intel_runtime_pm_put</function> to release the reference again.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-runtime-pm-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_runtime_pm_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_runtime_pm_put</refname>
 <refpurpose>
     release a runtime pm reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_runtime_pm_put </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function drops the device-level runtime pm reference obtained by
   <function>intel_runtime_pm_get</function> and might power down the corresponding
   hardware block right away if this is the last reference.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-runtime-pm-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_runtime_pm_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_runtime_pm_enable</refname>
 <refpurpose>
     enable runtime pm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_runtime_pm_enable </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function enables runtime pm at the end of the driver load sequence.
   </para><para>

   Note that this function does currently not enable runtime pm for the
   subordinate display power domains. That is only done on the first modeset
   using <function>intel_display_set_init_power</function>.
</para>
</refsect1>
</refentry>

<!-- drivers/gpu/drm/i915/intel_uncore.c -->
<refentry id="API-intel-uncore-forcewake-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_uncore_forcewake_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_uncore_forcewake_get</refname>
 <refpurpose>
  grab forcewake domain references
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_uncore_forcewake_get </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum forcewake_domains <parameter>fw_domains</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fw_domains</parameter></term>
   <listitem>
    <para>
     forcewake domains to get reference on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be used get GT's forcewake domain references.
   Normal register access will handle the forcewake domains automatically.
   However if some sequence requires the GT to not power down a particular
   forcewake domains this function should be called at the beginning of the
   sequence. And subsequently the reference should be dropped by symmetric
   call to <function>intel_unforce_forcewake_put</function>. Usually caller wants all the domains
   to be kept awake so the <parameter>fw_domains</parameter> would be then FORCEWAKE_ALL.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-uncore-forcewake-get--locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_uncore_forcewake_get__locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_uncore_forcewake_get__locked</refname>
 <refpurpose>
     grab forcewake domain references
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_uncore_forcewake_get__locked </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum forcewake_domains <parameter>fw_domains</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fw_domains</parameter></term>
   <listitem>
    <para>
     forcewake domains to get reference on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See <function>intel_uncore_forcewake_get</function>. This variant places the onus
   on the caller to explicitly handle the dev_priv-&gt;uncore.lock spinlock.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-uncore-forcewake-put">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_uncore_forcewake_put</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_uncore_forcewake_put</refname>
 <refpurpose>
     release a forcewake domain reference
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_uncore_forcewake_put </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum forcewake_domains <parameter>fw_domains</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fw_domains</parameter></term>
   <listitem>
    <para>
     forcewake domains to put references
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function drops the device-level forcewakes for specified
   domains obtained by <function>intel_uncore_forcewake_get</function>.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-uncore-forcewake-put--locked">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_uncore_forcewake_put__locked</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_uncore_forcewake_put__locked</refname>
 <refpurpose>
     grab forcewake domain references
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_uncore_forcewake_put__locked </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum forcewake_domains <parameter>fw_domains</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fw_domains</parameter></term>
   <listitem>
    <para>
     forcewake domains to get reference on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   See <function>intel_uncore_forcewake_put</function>. This variant places the onus
   on the caller to explicitly handle the dev_priv-&gt;uncore.lock spinlock.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Interrupt Handling</title>
<para>
   </para><para>
   These functions provide the basic support for enabling and disabling the
   interrupt handling support. There's a lot more functionality in i915_irq.c
   and related files, but that will be described in separate chapters.
</para>

<refentry id="API-intel-irq-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_irq_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_irq_init</refname>
 <refpurpose>
  initializes irq support
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_irq_init </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function initializes all the irq support including work items, timers
   and all the vtables. It does not setup the interrupt itself though.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-runtime-pm-disable-interrupts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_runtime_pm_disable_interrupts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_runtime_pm_disable_interrupts</refname>
 <refpurpose>
  runtime interrupt disabling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_runtime_pm_disable_interrupts </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to disable interrupts at runtime, both in the runtime
   pm and the system suspend/resume code.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-runtime-pm-enable-interrupts">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_runtime_pm_enable_interrupts</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_runtime_pm_enable_interrupts</refname>
 <refpurpose>
  runtime interrupt enabling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_runtime_pm_enable_interrupts </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to enable interrupts at runtime, both in the runtime
   pm and the system suspend/resume code.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Intel GVT-g Guest Support(vGPU)</title>
<para>
   </para><para>
   Intel GVT-g is a graphics virtualization technology which shares the
   GPU among multiple virtual machines on a time-sharing basis. Each
   virtual machine is presented a virtual GPU (vGPU), which has equivalent
   features as the underlying physical GPU (pGPU), so i915 driver can run
   seamlessly in a virtual machine. This file provides vGPU specific
   optimizations when running in a virtual machine, to reduce the complexity
   of vGPU emulation and to improve the overall performance.
   </para><para>
   A primary function introduced here is so-called <quote>address space ballooning</quote>
   technique. Intel GVT-g partitions global graphics memory among multiple VMs,
   so each VM can directly access a portion of the memory without hypervisor's
   intervention, e.g. filling textures or queuing commands. However with the
   partitioning an unmodified i915 driver would assume a smaller graphics
   memory starting from address ZERO, then requires vGPU emulation module to
   translate the graphics address between 'guest view' and 'host view', for
   all registers and command opcodes which contain a graphics memory address.
   To reduce the complexity, Intel GVT-g introduces <quote>address space ballooning</quote>,
   by telling the exact partitioning knowledge to each guest i915 driver, which
   then reserves and prevents non-allocated portions from allocation. Thus vGPU
   emulation module only needs to scan and validate graphics addresses without
   complexity of address translation.
   </para><para>
</para>

<!-- drivers/gpu/drm/i915/i915_vgpu.c -->
<refentry id="API-i915-check-vgpu">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_check_vgpu</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_check_vgpu</refname>
 <refpurpose>
  detect virtual GPU
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_check_vgpu </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device *
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called at the initialization stage, to detect whether
   running on a vGPU.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-vgt-deballoon">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_vgt_deballoon</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_vgt_deballoon</refname>
 <refpurpose>
     deballoon reserved graphics address trunks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_vgt_deballoon </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   This function is called to deallocate the ballooned-out graphic memory, when
   driver is unloaded or when ballooning fails.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-vgt-balloon">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_vgt_balloon</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_vgt_balloon</refname>
 <refpurpose>
     balloon out reserved graphics address trunks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_vgt_balloon </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called at the initialization stage, to balloon out the
   graphic address space allocated to other vGPUs, by marking these spaces as
   reserved. The ballooning related knowledge(starting address and size of
   the mappable/unmappable graphic memory) is described in the vgt_if structure
   in a reserved mmio range.
   </para><para>

   To give an example, the drawing below depicts one typical scenario after
   ballooning. Here the vGPU1 has 2 pieces of graphic address spaces ballooned
   out each for the mappable and the non-mappable part. From the vGPU1 point of
   view, the total size is the same as the physical one, with the start address
   of its graphic space being zero. Yet there are some portions ballooned out(
   the shadow part, which are marked as reserved by drm allocator). From the
   host point of view, the graphic address space is partitioned by multiple
   vGPUs in different VMs.
   </para><para>

   vGPU1 view         Host view
   0 ------&gt; +-----------+     +-----------+
   ^       |///////////|     |   vGPU3   |
   |       |///////////|     +-----------+
   |       |///////////|     |   vGPU2   |
   |       +-----------+     +-----------+
   mappable GM    | available | ==&gt; |   vGPU1   |
   |       +-----------+     +-----------+
   |       |///////////|     |           |
   v       |///////////|     |   Host    |
   +=======+===========+     +===========+
   ^       |///////////|     |   vGPU3   |
   |       |///////////|     +-----------+
   |       |///////////|     |   vGPU2   |
   |       +-----------+     +-----------+
   unmappable GM    | available | ==&gt; |   vGPU1   |
   |       +-----------+     +-----------+
   |       |///////////|     |           |
   |       |///////////|     |   Host    |
   v       |///////////|     |           |
   total GM size ------&gt; +-----------+     +-----------+
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   zero on success, non-zero if configuration invalid or ballooning failed
</para>
</refsect1>
</refentry>

      </sect2>
    </sect1>
    <sect1>
      <title>Display Hardware Handling</title>
      <para>
        This section covers everything related to the display hardware including
        the mode setting infrastructure, plane, sprite and cursor handling and
        display, output probing and related topics.
      </para>
      <sect2>
        <title>Mode Setting Infrastructure</title>
        <para>
          The i915 driver is thus far the only DRM driver which doesn't use the
          common DRM helper code to implement mode setting sequences. Thus it
          has its own tailor-made infrastructure for executing a display
          configuration change.
        </para>
      </sect2>
      <sect2>
        <title>Frontbuffer Tracking</title>
<para>
   </para><para>
   Many features require us to track changes to the currently active
   frontbuffer, especially rendering targeted at the frontbuffer.
   </para><para>
   To be able to do so GEM tracks frontbuffers using a bitmask for all possible
   frontbuffer slots through <function>i915_gem_track_fb</function>. The function in this file are
   then called when the contents of the frontbuffer are invalidated, when
   frontbuffer rendering has stopped again to flush out all the changes and when
   the frontbuffer is exchanged with a flip. Subsystems interested in
   frontbuffer changes (e.g. PSR, FBC, DRRS) should directly put their callbacks
   into the relevant places and filter for the frontbuffer slots that they are
   interested int.
   </para><para>
   On a high level there are two types of powersaving features. The first one
   work like a special cache (FBC and PSR) and are interested when they should
   stop caching and when to restart caching. This is done by placing callbacks
   into the invalidate and the flush functions: At invalidate the caching must
   be stopped and at flush time it can be restarted. And maybe they need to know
   when the frontbuffer changes (e.g. when the hw doesn't initiate an invalidate
   and flush on its own) which can be achieved with placing callbacks into the
   flip functions.
   </para><para>
   The other type of display power saving feature only cares about busyness
   (e.g. DRRS). In that case all three (invalidate, flush and flip) indicate
   busyness. There is no direct way to detect idleness. Instead an idle timer
   work delayed work should be started from the flush and flip functions and
   cancelled as soon as busyness is detected.
   </para><para>
   Note that there's also an older frontbuffer activity tracking scheme which
   just tracks general activity. This is done by the various mark_busy and
   mark_idle functions. For display power management features using these
   functions is deprecated and should be avoided.
</para>

<!-- drivers/gpu/drm/i915/intel_frontbuffer.c -->
<refentry id="API-intel-fb-obj-invalidate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_fb_obj_invalidate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_fb_obj_invalidate</refname>
 <refpurpose>
  invalidate frontbuffer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_fb_obj_invalidate </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>enum fb_op_origin <parameter>origin</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object to invalidate
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>origin</parameter></term>
   <listitem>
    <para>
     which operation caused the invalidation
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called every time rendering on the given object starts and
   frontbuffer caching (fbc, low refresh rate for DRRS, panel self refresh) must
   be invalidated. For ORIGIN_CS any subsequent invalidation will be delayed
   until the rendering completes or a flip on this frontbuffer plane is
   scheduled.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-frontbuffer-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_frontbuffer_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_frontbuffer_flush</refname>
 <refpurpose>
     flush frontbuffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_frontbuffer_flush </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
   <paramdef>enum fb_op_origin <parameter>origin</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>origin</parameter></term>
   <listitem>
    <para>
     which operation caused the flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called every time rendering on the given planes has
   completed and frontbuffer caching can be started again. Flushes will get
   delayed if they're blocked by some outstanding asynchronous rendering.
   </para><para>

   Can be called without any locks held.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-fb-obj-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_fb_obj_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_fb_obj_flush</refname>
 <refpurpose>
     flush frontbuffer object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_fb_obj_flush </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>bool <parameter>retire</parameter></paramdef>
   <paramdef>enum fb_op_origin <parameter>origin</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     GEM object to flush
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>retire</parameter></term>
   <listitem>
    <para>
     set when retiring asynchronous rendering
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>origin</parameter></term>
   <listitem>
    <para>
     which operation caused the flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called every time rendering on the given object has
   completed and frontbuffer caching can be started again. If <parameter>retire</parameter> is true
   then any delayed flushes will be unblocked.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-frontbuffer-flip-prepare">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_frontbuffer_flip_prepare</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_frontbuffer_flip_prepare</refname>
 <refpurpose>
     prepare asynchronous frontbuffer flip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_frontbuffer_flip_prepare </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called after scheduling a flip on <parameter>obj</parameter>. The actual
   frontbuffer flushing will be delayed until completion is signalled with
   intel_frontbuffer_flip_complete. If an invalidate happens in between this
   flush will be cancelled.
   </para><para>

   Can be called without any locks held.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-frontbuffer-flip-complete">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_frontbuffer_flip_complete</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_frontbuffer_flip_complete</refname>
 <refpurpose>
     complete asynchronous frontbuffer flip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_frontbuffer_flip_complete </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called after the flip has been latched and will complete
   on the next vblank. It will execute the flush if it hasn't been cancelled yet.
   </para><para>

   Can be called without any locks held.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-frontbuffer-flip">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_frontbuffer_flip</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_frontbuffer_flip</refname>
 <refpurpose>
     synchronous frontbuffer flip
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_frontbuffer_flip </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called after scheduling a flip on <parameter>obj</parameter>. This is for
   synchronous plane updates which will happen on the next vblank and which will
   not get delayed by pending gpu rendering.
   </para><para>

   Can be called without any locks held.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-track-fb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_track_fb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_track_fb</refname>
 <refpurpose>
  update frontbuffer tracking
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_track_fb </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>old</parameter></paramdef>
   <paramdef>struct drm_i915_gem_object * <parameter>new</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>old</parameter></term>
   <listitem>
    <para>
     current GEM buffer for the frontbuffer slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new</parameter></term>
   <listitem>
    <para>
     new GEM buffer for the frontbuffer slots
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     bitmask of frontbuffer slots
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This updates the frontbuffer tracking bits <parameter>frontbuffer_bits</parameter> by clearing them
   from <parameter>old</parameter> and setting them in <parameter>new</parameter>. Both <parameter>old</parameter> and <parameter>new</parameter> can be NULL.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Display FIFO Underrun Reporting</title>
<para>
   </para><para>
   The i915 driver checks for display fifo underruns using the interrupt signals
   provided by the hardware. This is enabled by default and fairly useful to
   debug display issues, especially watermark settings.
   </para><para>
   If an underrun is detected this is logged into dmesg. To avoid flooding logs
   and occupying the cpu underrun interrupts are disabled after the first
   occurrence until the next modeset on a given pipe.
   </para><para>
   Note that underrun detection on gmch platforms is a bit more ugly since there
   is no interrupt (despite that the signalling bit is in the PIPESTAT pipe
   interrupt register). Also on some other platforms underrun interrupts are
   shared, which means that if we detect an underrun we need to disable underrun
   reporting on all pipes.
   </para><para>
   The code also supports underrun detection on the PCH transcoder.
</para>

<!-- drivers/gpu/drm/i915/intel_fifo_underrun.c -->
<refentry id="API-i9xx-check-fifo-underruns">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i9xx_check_fifo_underruns</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i9xx_check_fifo_underruns</refname>
 <refpurpose>
  check for fifo underruns
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i9xx_check_fifo_underruns </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function checks for fifo underruns on GMCH platforms. This needs to be
   done manually on modeset to make sure that we catch all underruns since they
   do not generate an interrupt by themselves on these platforms.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-set-cpu-fifo-underrun-reporting">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_set_cpu_fifo_underrun_reporting</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_set_cpu_fifo_underrun_reporting</refname>
 <refpurpose>
     set cpu fifo underrrun reporting state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>intel_set_cpu_fifo_underrun_reporting </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum pipe <parameter>pipe</parameter></paramdef>
   <paramdef>bool <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     (CPU) pipe to set state for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     whether underruns should be reported or not
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function sets the fifo underrun state for <parameter>pipe</parameter>. It is used in the
   modeset code to avoid false positives since on many platforms underruns are
   expected when disabling or enabling the pipe.
   </para><para>

   Notice that on some platforms disabling underrun reports for one pipe
   disables for all due to shared interrupts. Actual reporting is still per-pipe
   though.
   </para><para>

   Returns the previous state of underrun reporting.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-set-pch-fifo-underrun-reporting">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_set_pch_fifo_underrun_reporting</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_set_pch_fifo_underrun_reporting</refname>
 <refpurpose>
     set PCH fifo underrun reporting state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>intel_set_pch_fifo_underrun_reporting </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum transcoder <parameter>pch_transcoder</parameter></paramdef>
   <paramdef>bool <parameter>enable</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pch_transcoder</parameter></term>
   <listitem>
    <para>
     the PCH transcoder (same as pipe on IVB and older)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable</parameter></term>
   <listitem>
    <para>
     whether underruns should be reported or not
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function makes us disable or enable PCH fifo underruns for a specific
   PCH transcoder. Notice that on some PCHs (e.g. CPT/PPT), disabling FIFO
   underrun reporting for one transcoder may also disable all the other PCH
   error interruts for the other transcoders, due to the fact that there's just
   one interrupt mask/enable bit for all the transcoders.
   </para><para>

   Returns the previous state of underrun reporting.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-cpu-fifo-underrun-irq-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_cpu_fifo_underrun_irq_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_cpu_fifo_underrun_irq_handler</refname>
 <refpurpose>
     handle CPU fifo underrun interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_cpu_fifo_underrun_irq_handler </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum pipe <parameter>pipe</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pipe</parameter></term>
   <listitem>
    <para>
     (CPU) pipe to set state for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This handles a CPU fifo underrun interrupt, generating an underrun warning
   into dmesg if underrun reporting is enabled and then disables the underrun
   interrupt to avoid an irq storm.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-pch-fifo-underrun-irq-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_pch_fifo_underrun_irq_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_pch_fifo_underrun_irq_handler</refname>
 <refpurpose>
     handle PCH fifo underrun interrupt
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_pch_fifo_underrun_irq_handler </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum transcoder <parameter>pch_transcoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pch_transcoder</parameter></term>
   <listitem>
    <para>
     the PCH transcoder (same as pipe on IVB and older)
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This handles a PCH fifo underrun interrupt, generating an underrun warning
   into dmesg if underrun reporting is enabled and then disables the underrun
   interrupt to avoid an irq storm.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Plane Configuration</title>
        <para>
	  This section covers plane configuration and composition with the
	  primary plane, sprites, cursors and overlays. This includes the
	  infrastructure to do atomic vsync'ed updates of all this state and
	  also tightly coupled topics like watermark setup and computation,
	  framebuffer compression and panel self refresh.
        </para>
      </sect2>
      <sect2>
        <title>Atomic Plane Helpers</title>
<para>
   </para><para>
   The functions here are used by the atomic plane helper functions to
   implement legacy plane updates (i.e., drm_plane-&gt;<function>update_plane</function> and
   drm_plane-&gt;<function>disable_plane</function>).  This allows plane updates to use the
   atomic state infrastructure and perform plane updates as separate
   prepare/check/commit/cleanup steps.
</para>

<!-- drivers/gpu/drm/i915/intel_atomic_plane.c -->
<refentry id="API-intel-create-plane-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_create_plane_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_create_plane_state</refname>
 <refpurpose>
  create plane state object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct intel_plane_state * <function>intel_create_plane_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates a fresh plane state for the given plane and sets some of
   the state values to sensible initial values.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   A newly allocated plane state, or NULL on failure
</para>
</refsect1>
</refentry>

<refentry id="API-intel-plane-duplicate-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_plane_duplicate_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_plane_duplicate_state</refname>
 <refpurpose>
     duplicate plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_plane_state * <function>intel_plane_duplicate_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocates and returns a copy of the plane state (both common and
   Intel-specific) for the specified plane.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The newly allocated plane state, or NULL on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-plane-destroy-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_plane_destroy_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_plane_destroy_state</refname>
 <refpurpose>
     destroy plane state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_plane_destroy_state </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     drm plane
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     state object to destroy
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Destroys the plane state (both common and Intel-specific) for the
   specified plane.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-plane-atomic-get-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_plane_atomic_get_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_plane_atomic_get_property</refname>
 <refpurpose>
     fetch plane property value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_plane_atomic_get_property </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>const struct drm_plane_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t * <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to fetch property for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     state containing the property value
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to look up
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     pointer to write property value into
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The DRM core does not store shadow copies of properties for
   atomic-capable drivers.  This entrypoint is used to fetch
   the current value of a driver-specific plane property.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-plane-atomic-set-property">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_plane_atomic_set_property</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_plane_atomic_set_property</refname>
 <refpurpose>
     set plane property value
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_plane_atomic_set_property </function></funcdef>
   <paramdef>struct drm_plane * <parameter>plane</parameter></paramdef>
   <paramdef>struct drm_plane_state * <parameter>state</parameter></paramdef>
   <paramdef>struct drm_property * <parameter>property</parameter></paramdef>
   <paramdef>uint64_t <parameter>val</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>plane</parameter></term>
   <listitem>
    <para>
     plane to set property for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     state to update property value in
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>property</parameter></term>
   <listitem>
    <para>
     property to set
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>val</parameter></term>
   <listitem>
    <para>
     value to set property to
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Writes the specified property value for a plane into the provided atomic
   state object.
   </para><para>

   Returns 0 on success, -EINVAL on unrecognized properties
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Output Probing</title>
        <para>
	  This section covers output probing and related infrastructure like the
	  hotplug interrupt storm detection and mitigation code. Note that the
	  i915 driver still uses most of the common DRM helper code for output
	  probing, so those sections fully apply.
        </para>
      </sect2>
      <sect2>
        <title>Hotplug</title>
<para>
   </para><para>
   Simply put, hotplug occurs when a display is connected to or disconnected
   from the system. However, there may be adapters and docking stations and
   Display Port short pulses and MST devices involved, complicating matters.
   </para><para>
   Hotplug in i915 is handled in many different levels of abstraction.
   </para><para>
   The platform dependent interrupt handling code in i915_irq.c enables,
   disables, and does preliminary handling of the interrupts. The interrupt
   handlers gather the hotplug detect (HPD) information from relevant registers
   into a platform independent mask of hotplug pins that have fired.
   </para><para>
   The platform independent interrupt handler <function>intel_hpd_irq_handler</function> in
   intel_hotplug.c does hotplug irq storm detection and mitigation, and passes
   further processing to appropriate bottom halves (Display Port specific and
   regular hotplug).
   </para><para>
   The Display Port work function <function>i915_digport_work_func</function> calls into
   <function>intel_dp_hpd_pulse</function> via hooks, which handles DP short pulses and DP MST long
   pulses, with failures and non-MST long pulses triggering regular hotplug
   processing on the connector.
   </para><para>
   The regular hotplug work function <function>i915_hotplug_work_func</function> calls connector
   detect hooks, and, if connector status changes, triggers sending of hotplug
   uevent to userspace via <function>drm_kms_helper_hotplug_event</function>.
   </para><para>
   Finally, the userspace is responsible for triggering a modeset upon receiving
   the hotplug uevent, disabling or enabling the crtc as needed.
   </para><para>
   The hotplug interrupt storm detection and mitigation code keeps track of the
   number of interrupts per hotplug pin per a period of time, and if the number
   of interrupts exceeds a certain threshold, the interrupt is disabled for a
   while before being re-enabled. The intention is to mitigate issues raising
   from broken hardware triggering massive amounts of interrupts and grinding
   the system to a halt.
   </para><para>
   Current implementation expects that hotplug interrupt storm will not be
   seen when display port sink is connected, hence on platforms whose DP
   callback is handled by i915_digport_work_func reenabling of hpd is not
   performed (it was never expected to be disabled in the first place ;) )
   this is specific to DP sinks handled by this routine and any other display
   such as HDMI or DVI enabled on the same port will have proper logic since
   it will use i915_hotplug_work_func where this logic is handled.
</para>

<!-- drivers/gpu/drm/i915/intel_hotplug.c -->
<refentry id="API-intel-hpd-irq-storm-detect">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_hpd_irq_storm_detect</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_hpd_irq_storm_detect</refname>
 <refpurpose>
  gather stats and detect HPD irq storm on a pin
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>intel_hpd_irq_storm_detect </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum hpd_pin <parameter>pin</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     private driver data pointer
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pin</parameter></term>
   <listitem>
    <para>
     the pin to gather stats on
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Gather stats about HPD irqs from the specified <parameter>pin</parameter>, and detect irq
   storms. Only the pin specific stats and state are changed, the caller is
   responsible for further action.
   </para><para>

   <parameter>HPD_STORM_THRESHOLD</parameter> irqs are allowed within <parameter>HPD_STORM_DETECT_PERIOD</parameter> ms,
   otherwise it's considered an irq storm, and the irq state is set to
   <parameter>HPD_MARK_DISABLED</parameter>.
   </para><para>

   Return true if an irq storm was detected on <parameter>pin</parameter>.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-hpd-irq-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_hpd_irq_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_hpd_irq_handler</refname>
 <refpurpose>
     main hotplug irq handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_hpd_irq_handler </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>u32 <parameter>pin_mask</parameter></paramdef>
   <paramdef>u32 <parameter>long_mask</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pin_mask</parameter></term>
   <listitem>
    <para>
     a mask of hpd pins that have triggered the irq
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>long_mask</parameter></term>
   <listitem>
    <para>
     a mask of hpd pins that may be long hpd pulses
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the main hotplug irq handler for all platforms. The platform specific
   irq handlers call the platform specific hotplug irq handlers, which read and
   decode the appropriate registers into bitmasks about hpd pins that have
   triggered (<parameter>pin_mask</parameter>), and which of those pins may be long pulses
   (<parameter>long_mask</parameter>). The <parameter>long_mask</parameter> is ignored if the port corresponding to the pin
   is not a digital port.
   </para><para>

   Here, we do hotplug irq storm detection and mitigation, and pass further
   processing to appropriate bottom halves.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-hpd-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_hpd_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_hpd_init</refname>
 <refpurpose>
     initializes and enables hpd support
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_hpd_init </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function enables the hotplug support. It requires that interrupts have
   already been enabled with <function>intel_irq_init_hw</function>. From this point on hotplug and
   poll request can run concurrently to other code, so locking rules must be
   obeyed.
   </para><para>

   This is a separate step from interrupt enabling to simplify the locking rules
   in the driver load and resume code.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
	<title>High Definition Audio</title>
<para>
   </para><para>
   The graphics and audio drivers together support High Definition Audio over
   HDMI and Display Port. The audio programming sequences are divided into audio
   codec and controller enable and disable sequences. The graphics driver
   handles the audio codec sequences, while the audio driver handles the audio
   controller sequences.
   </para><para>
   The disable sequences must be performed before disabling the transcoder or
   port. The enable sequences may only be performed after enabling the
   transcoder and port, and after completed link training. Therefore the audio
   enable/disable sequences are part of the modeset sequence.
   </para><para>
   The codec and controller sequences could be done either parallel or serial,
   but generally the ELDV/PD change in the codec sequence indicates to the audio
   driver that the controller sequence should start. Indeed, most of the
   co-operation between the graphics and audio drivers is handled via audio
   related registers. (The notable exception is the power management, not
   covered here.)
   </para><para>
   The struct i915_audio_component is used to interact between the graphics
   and audio drivers. The struct i915_audio_component_ops *ops in it is
   defined in graphics driver and called in audio driver. The
   struct i915_audio_component_audio_ops *audio_ops is called from i915 driver.
</para>

<!-- drivers/gpu/drm/i915/intel_audio.c -->
<refentry id="API-intel-audio-codec-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_audio_codec_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_audio_codec_enable</refname>
 <refpurpose>
  Enable the audio codec for HD audio
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_audio_codec_enable </function></funcdef>
   <paramdef>struct intel_encoder * <parameter>intel_encoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_encoder</parameter></term>
   <listitem>
    <para>
     encoder on which to enable audio
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The enable sequences may only be performed after enabling the transcoder and
   port, and after completed link training.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-audio-codec-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_audio_codec_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_audio_codec_disable</refname>
 <refpurpose>
     Disable the audio codec for HD audio
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_audio_codec_disable </function></funcdef>
   <paramdef>struct intel_encoder * <parameter>intel_encoder</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_encoder</parameter></term>
   <listitem>
    <para>
     encoder on which to disable audio
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The disable sequences must be performed before disabling the transcoder or
   port.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-init-audio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_init_audio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_init_audio</refname>
 <refpurpose>
     Set up chip specific audio functions
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_init_audio </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-i915-audio-component-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_audio_component_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_audio_component_init</refname>
 <refpurpose>
     initialize and register the audio component
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_audio_component_init </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This will register with the component framework a child component which
   will bind dynamically to the snd_hda_intel driver's corresponding master
   component when the latter is registered. During binding the child
   initializes an instance of struct i915_audio_component which it receives
   from the master. The master can then start to use the interface defined by
   this struct. Each side can break the binding at any point by deregistering
   its own component after which each side's component unbind callback is
   called.
   </para><para>

   We ignore any error during registration and continue with reduced
   functionality (i.e. without HDMI audio).
</para>
</refsect1>
</refentry>

<refentry id="API-i915-audio-component-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_audio_component_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_audio_component_cleanup</refname>
 <refpurpose>
     deregister the audio component
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_audio_component_cleanup </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Deregisters the audio component, breaking any existing binding to the
   corresponding snd_hda_intel driver's master component.
</para>
</refsect1>
</refentry>

<!-- include/drm/i915_component.h -->
<refentry id="API-struct-i915-audio-component-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i915_audio_component_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i915_audio_component_ops</refname>
 <refpurpose>
  callbacks defined in gfx driver
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i915_audio_component_ops {
  struct module * owner;
  void (* get_power) (struct device *);
  void (* put_power) (struct device *);
  void (* codec_wake_override) (struct device *, bool enable);
  int (* get_cdclk_freq) (struct device *);
  int (* sync_audio_rate) (struct device *, int port, int rate);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>owner</term>
      <listitem><para>
the module owner
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_power</term>
      <listitem><para>
get the POWER_DOMAIN_AUDIO power well
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>put_power</term>
      <listitem><para>
put the POWER_DOMAIN_AUDIO power well
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>codec_wake_override</term>
      <listitem><para>
Enable/Disable generating the codec wake signal
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_cdclk_freq</term>
      <listitem><para>
get the Core Display Clock in KHz
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>sync_audio_rate</term>
      <listitem><para>
set n/cts based on the sample rate
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<refentry id="API-struct-i915-audio-component">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct i915_audio_component</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct i915_audio_component</refname>
 <refpurpose>
     used for audio video interaction
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct i915_audio_component {
  struct device * dev;
  int aud_sample_rate[MAX_PORTS];
  const struct i915_audio_component_ops * ops;
  const struct i915_audio_component_audio_ops * audio_ops;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>dev</term>
      <listitem><para>
   the device from gfx driver
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>aud_sample_rate[MAX_PORTS]</term>
      <listitem><para>
   the array of audio sample rate per port
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
   callback for audio driver calling
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>audio_ops</term>
      <listitem><para>
   Call from i915 driver
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

      </sect2>
      <sect2>
	<title>Panel Self Refresh PSR (PSR/SRD)</title>
<para>
   </para><para>
   Since Haswell Display controller supports Panel Self-Refresh on display
   panels witch have a remote frame buffer (RFB) implemented according to PSR
   spec in eDP1.3. PSR feature allows the display to go to lower standby states
   when system is idle but display is on as it eliminates display refresh
   request to DDR memory completely as long as the frame buffer for that
   display is unchanged.
   </para><para>
   Panel Self Refresh must be supported by both Hardware (source) and
   Panel (sink).
   </para><para>
   PSR saves power by caching the framebuffer in the panel RFB, which allows us
   to power down the link and memory controller. For DSI panels the same idea
   is called <quote>manual mode</quote>.
   </para><para>
   The implementation uses the hardware-based PSR support which automatically
   enters/exits self-refresh mode. The hardware takes care of sending the
   required DP aux message and could even retrain the link (that part isn't
   enabled yet though). The hardware also keeps track of any frontbuffer
   changes to know when to exit self-refresh mode again. Unfortunately that
   part doesn't work too well, hence why the i915 PSR support uses the
   software frontbuffer tracking to make sure it doesn't miss a screen
   update. For this integration <function>intel_psr_invalidate</function> and <function>intel_psr_flush</function>
   get called by the frontbuffer tracking code. Note that because of locking
   issues the self-refresh re-enable code is done from a work queue, which
   must be correctly synchronized/cancelled when shutting down the pipe."
</para>

<!-- drivers/gpu/drm/i915/intel_psr.c -->
<refentry id="API-intel-psr-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_psr_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_psr_enable</refname>
 <refpurpose>
  Enable PSR
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_psr_enable </function></funcdef>
   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_dp</parameter></term>
   <listitem>
    <para>
     Intel DP
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can only be called after the pipe is fully trained and enabled.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-psr-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_psr_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_psr_disable</refname>
 <refpurpose>
     Disable PSR
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_psr_disable </function></funcdef>
   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_dp</parameter></term>
   <listitem>
    <para>
     Intel DP
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function needs to be called before disabling pipe.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-psr-single-frame-update">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_psr_single_frame_update</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_psr_single_frame_update</refname>
 <refpurpose>
     Single Frame Update
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_psr_single_frame_update </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Some platforms support a single frame update feature that is used to
   send and update only one frame on Remote Frame Buffer.
   So far it is only implemented for Valleyview and Cherryview because
   hardware requires this to be done before a page flip.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-psr-invalidate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_psr_invalidate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_psr_invalidate</refname>
 <refpurpose>
     Invalidade PSR
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_psr_invalidate </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Since the hardware frontbuffer tracking has gaps we need to integrate
   with the software frontbuffer tracking. This function gets called every
   time frontbuffer rendering starts and a buffer gets dirtied. PSR must be
   disabled if the frontbuffer mask contains a buffer relevant to PSR.
   </para><para>

   Dirty frontbuffers relevant to PSR are tracked in busy_frontbuffer_bits."
</para>
</refsect1>
</refentry>

<refentry id="API-intel-psr-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_psr_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_psr_flush</refname>
 <refpurpose>
     Flush PSR
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_psr_flush </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
   <paramdef>enum fb_op_origin <parameter>origin</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>origin</parameter></term>
   <listitem>
    <para>
     which operation caused the flush
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Since the hardware frontbuffer tracking has gaps we need to integrate
   with the software frontbuffer tracking. This function gets called every
   time frontbuffer rendering has completed and flushed out to memory. PSR
   can be enabled again if no other frontbuffer relevant to PSR is dirty.
   </para><para>

   Dirty frontbuffers relevant to PSR are tracked in busy_frontbuffer_bits.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-psr-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_psr_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_psr_init</refname>
 <refpurpose>
     Init basic PSR work and mutex.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_psr_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is  called only once at driver load to initialize basic
   PSR stuff.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
	<title>Frame Buffer Compression (FBC)</title>
<para>
   </para><para>
   FBC tries to save memory bandwidth (and so power consumption) by
   compressing the amount of memory used by the display. It is total
   transparent to user space and completely handled in the kernel.
   </para><para>
   The benefits of FBC are mostly visible with solid backgrounds and
   variation-less patterns. It comes from keeping the memory footprint small
   and having fewer memory pages opened and accessed for refreshing the display.
   </para><para>
   i915 is responsible to reserve stolen memory for FBC and configure its
   offset on proper registers. The hardware takes care of all
   compress/decompress. However there are many known cases where we have to
   forcibly disable it to allow proper screen updates.
</para>

<!-- drivers/gpu/drm/i915/intel_fbc.c -->
<refentry id="API-intel-fbc-enabled">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_fbc_enabled</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_fbc_enabled</refname>
 <refpurpose>
  Is FBC enabled?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>intel_fbc_enabled </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is used to verify the current state of FBC.
</para>
</refsect1>
<refsect1>
<title>FIXME</title>
<para>
   This should be tracked in the plane config eventually
   instead of queried at runtime for most callers.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-fbc-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_fbc_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_fbc_disable</refname>
 <refpurpose>
     disable FBC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_fbc_disable </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function disables FBC.
</para>
</refsect1>
</refentry>

<refentry id="API---intel-fbc-update">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>__intel_fbc_update</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>__intel_fbc_update</refname>
 <refpurpose>
     enable/disable FBC as needed, unlocked
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>__intel_fbc_update </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device instance
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set up the framebuffer compression hardware at mode set time.  We
</para>
</refsect1>
<refsect1>
<title>enable it if possible</title>
<para>
   - plane A only (on pre-965)
   - no pixel mulitply/line duplication
   - no alpha buffer discard
   - no dual wide
   - framebuffer &lt;= max_hdisplay in width, max_vdisplay in height
   </para><para>

   We can't assume that any compression will take place (worst case),
   so the compressed buffer has to be the same size as the uncompressed
   one.  It also must reside (along with the line length buffer) in
   stolen memory.
   </para><para>

   We need to enable/disable FBC on a global basis.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-fbc-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_fbc_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_fbc_init</refname>
 <refpurpose>
     Initialize FBC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_fbc_init </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     the i915 device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function might be called during PM init process.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Display Refresh Rate Switching (DRRS)</title>
<para>
   </para><para>
   Display Refresh Rate Switching (DRRS) is a power conservation feature
   which enables swtching between low and high refresh rates,
   dynamically, based on the usage scenario. This feature is applicable
   for internal panels.
   </para><para>
   Indication that the panel supports DRRS is given by the panel EDID, which
   would list multiple refresh rates for one resolution.
   </para><para>
   DRRS is of 2 types - static and seamless.
   Static DRRS involves changing refresh rate (RR) by doing a full modeset
   (may appear as a blink on screen) and is used in dock-undock scenario.
   Seamless DRRS involves changing RR without any visual effect to the user
   and can be used during normal system usage. This is done by programming
   certain registers.
   </para><para>
   Support for static/seamless DRRS may be indicated in the VBT based on
   inputs from the panel spec.
   </para><para>
   DRRS saves power by switching to low RR based on usage scenarios.
   </para><para>
   eDP DRRS:-
   The implementation is based on frontbuffer tracking implementation.
   When there is a disturbance on the screen triggered by user activity or a
   periodic system activity, DRRS is disabled (RR is changed to high RR).
   When there is no movement on screen, after a timeout of 1 second, a switch
   to low RR is made.
   For integration with frontbuffer tracking code,
   <function>intel_edp_drrs_invalidate</function> and <function>intel_edp_drrs_flush</function> are called.
   </para><para>
   DRRS can be further extended to support other internal panels and also
   the scenario of video playback wherein RR is set based on the rate
   requested by userspace.
</para>

<refentry id="API-intel-dp-set-drrs-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_dp_set_drrs_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_dp_set_drrs_state</refname>
 <refpurpose>
  program registers for RR switch to take effect
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_dp_set_drrs_state </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>refresh_rate</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>refresh_rate</parameter></term>
   <listitem>
    <para>
     RR to be programmed
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called when refresh rate (RR) has to be changed from
   one frequency to another. Switches can be between high and low RR
   supported by the panel or to any other RR based on media playback (in
   this case, RR value needs to be passed from user space).
   </para><para>

   The caller of this function needs to take a lock on dev_priv-&gt;drrs.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-edp-drrs-enable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_edp_drrs_enable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_edp_drrs_enable</refname>
 <refpurpose>
  init drrs struct if supported
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_edp_drrs_enable </function></funcdef>
   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_dp</parameter></term>
   <listitem>
    <para>
     DP struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Initializes frontbuffer_bits and drrs.dp
</para>
</refsect1>
</refentry>

<refentry id="API-intel-edp-drrs-disable">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_edp_drrs_disable</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_edp_drrs_disable</refname>
 <refpurpose>
  Disable DRRS
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_edp_drrs_disable </function></funcdef>
   <paramdef>struct intel_dp * <parameter>intel_dp</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_dp</parameter></term>
   <listitem>
    <para>
     DP struct
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-intel-edp-drrs-invalidate">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_edp_drrs_invalidate</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_edp_drrs_invalidate</refname>
 <refpurpose>
  Disable Idleness DRRS
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_edp_drrs_invalidate </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called everytime rendering on the given planes start.
   Hence DRRS needs to be Upclocked, i.e. (LOW_RR -&gt; HIGH_RR).
   </para><para>

   Dirty frontbuffers relevant to DRRS are tracked in busy_frontbuffer_bits.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-edp-drrs-flush">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_edp_drrs_flush</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_edp_drrs_flush</refname>
 <refpurpose>
  Restart Idleness DRRS
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_edp_drrs_flush </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>unsigned <parameter>frontbuffer_bits</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>frontbuffer_bits</parameter></term>
   <listitem>
    <para>
     frontbuffer plane tracking bits
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function gets called every time rendering on the given planes has
   completed or flip on a crtc is completed. So DRRS should be upclocked
   (LOW_RR -&gt; HIGH_RR). And also Idleness detection should be started again,
   if no other planes are dirty.
   </para><para>

   Dirty frontbuffers relevant to DRRS are tracked in busy_frontbuffer_bits.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-dp-drrs-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_dp_drrs_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_dp_drrs_init</refname>
 <refpurpose>
  Init basic DRRS work and mutex.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_display_mode * <function>intel_dp_drrs_init </function></funcdef>
   <paramdef>struct intel_connector * <parameter>intel_connector</parameter></paramdef>
   <paramdef>struct drm_display_mode * <parameter>fixed_mode</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>intel_connector</parameter></term>
   <listitem>
    <para>
     eDP connector
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>fixed_mode</parameter></term>
   <listitem>
    <para>
     preferred mode of panel
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is  called only once at driver load to initialize basic
   DRRS stuff.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Downclock mode if panel supports it, else return NULL.
   DRRS support is determined by the presence of downclock mode (apart
   from VBT setting).
</para>
</refsect1>
</refentry>


      </sect2>
      <sect2>
        <title>DPIO</title>
<para>
   </para><para>
   VLV, CHV and BXT have slightly peculiar display PHYs for driving DP/HDMI
   ports. DPIO is the name given to such a display PHY. These PHYs
   don't follow the standard programming model using direct MMIO
   registers, and instead their registers must be accessed trough IOSF
   sideband. VLV has one such PHY for driving ports B and C, and CHV
   adds another PHY for driving port D. Each PHY responds to specific
   IOSF-SB port.
   </para><para>
   Each display PHY is made up of one or two channels. Each channel
   houses a common lane part which contains the PLL and other common
   logic. CH0 common lane also contains the IOSF-SB logic for the
   Common Register Interface (CRI) ie. the DPIO registers. CRI clock
   must be running when any DPIO registers are accessed.
   </para><para>
   In addition to having their own registers, the PHYs are also
   controlled through some dedicated signals from the display
   controller. These include PLL reference clock enable, PLL enable,
   and CRI clock selection, for example.
   </para><para>
   Eeach channel also has two splines (also called data lanes), and
   each spline is made up of one Physical Access Coding Sub-Layer
   (PCS) block and two TX lanes. So each channel has two PCS blocks
   and four TX lanes. The TX lanes are used as DP lanes or TMDS
   data/clock pairs depending on the output type.
   </para><para>
   Additionally the PHY also contains an AUX lane with AUX blocks
   for each channel. This is used for DP AUX communication, but
   this fact isn't really relevant for the driver since AUX is
   controlled from the display controller side. No DPIO registers
   need to be accessed during AUX communication,
   </para><para>
   Generally on VLV/CHV the common lane corresponds to the pipe and
   the spline (PCS/TX) corresponds to the port.
   </para><para>
   For dual channel PHY (VLV/CHV):
   </para><para>
   pipe A == CMN/PLL/REF CH0
   </para><para>
   pipe B == CMN/PLL/REF CH1
   </para><para>
   port B == PCS/TX CH0
   </para><para>
   port C == PCS/TX CH1
   </para><para>
   This is especially important when we cross the streams
   ie. drive port B with pipe B, or port C with pipe A.
   </para><para>
   For single channel PHY (CHV):
   </para><para>
   pipe C == CMN/PLL/REF CH0
   </para><para>
   port D == PCS/TX CH0
   </para><para>
   On BXT the entire PHY channel corresponds to the port. That means
   the PLL is also now associated with the port rather than the pipe,
   and so the clock needs to be routed to the appropriate transcoder.
   Port A PLL is directly connected to transcoder EDP and port B/C
   PLLs can be routed to any transcoder A/B/C.
   </para><para>
   Note: DDI0 is digital port B, DD1 is digital port C, and DDI2 is
   digital port D (CHV) or port A (BXT).
</para>

	<table id="dpiox2">
	  <title>Dual channel PHY (VLV/CHV/BXT)</title>
	  <tgroup cols="8">
	    <colspec colname="c0" />
	    <colspec colname="c1" />
	    <colspec colname="c2" />
	    <colspec colname="c3" />
	    <colspec colname="c4" />
	    <colspec colname="c5" />
	    <colspec colname="c6" />
	    <colspec colname="c7" />
	    <spanspec spanname="ch0" namest="c0" nameend="c3" />
	    <spanspec spanname="ch1" namest="c4" nameend="c7" />
	    <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" />
	    <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" />
	    <spanspec spanname="ch1pcs01" namest="c4" nameend="c5" />
	    <spanspec spanname="ch1pcs23" namest="c6" nameend="c7" />
	    <thead>
	      <row>
		<entry spanname="ch0">CH0</entry>
		<entry spanname="ch1">CH1</entry>
	      </row>
	    </thead>
	    <tbody valign="top" align="center">
	      <row>
		<entry spanname="ch0">CMN/PLL/REF</entry>
		<entry spanname="ch1">CMN/PLL/REF</entry>
	      </row>
	      <row>
		<entry spanname="ch0pcs01">PCS01</entry>
		<entry spanname="ch0pcs23">PCS23</entry>
		<entry spanname="ch1pcs01">PCS01</entry>
		<entry spanname="ch1pcs23">PCS23</entry>
	      </row>
	      <row>
		<entry>TX0</entry>
		<entry>TX1</entry>
		<entry>TX2</entry>
		<entry>TX3</entry>
		<entry>TX0</entry>
		<entry>TX1</entry>
		<entry>TX2</entry>
		<entry>TX3</entry>
	      </row>
	      <row>
		<entry spanname="ch0">DDI0</entry>
		<entry spanname="ch1">DDI1</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	<table id="dpiox1">
	  <title>Single channel PHY (CHV/BXT)</title>
	  <tgroup cols="4">
	    <colspec colname="c0" />
	    <colspec colname="c1" />
	    <colspec colname="c2" />
	    <colspec colname="c3" />
	    <spanspec spanname="ch0" namest="c0" nameend="c3" />
	    <spanspec spanname="ch0pcs01" namest="c0" nameend="c1" />
	    <spanspec spanname="ch0pcs23" namest="c2" nameend="c3" />
	    <thead>
	      <row>
		<entry spanname="ch0">CH0</entry>
	      </row>
	    </thead>
	    <tbody valign="top" align="center">
	      <row>
		<entry spanname="ch0">CMN/PLL/REF</entry>
	      </row>
	      <row>
		<entry spanname="ch0pcs01">PCS01</entry>
		<entry spanname="ch0pcs23">PCS23</entry>
	      </row>
	      <row>
		<entry>TX0</entry>
		<entry>TX1</entry>
		<entry>TX2</entry>
		<entry>TX3</entry>
	      </row>
	      <row>
		<entry spanname="ch0">DDI2</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </sect2>

      <sect2>
       <title>CSR firmware support for DMC</title>
<para>
   </para><para>
   Display Context Save and Restore (CSR) firmware support added from gen9
   onwards to drive newly added DMC (Display microcontroller) in display
   engine to save and restore the state of display engine when it enter into
   low-power state and comes back to normal.
   </para><para>
   Firmware loading status will be one of the below states: FW_UNINITIALIZED,
   FW_LOADED, FW_FAILED.
   </para><para>
   Once the firmware is written into the registers status will be moved from
   FW_UNINITIALIZED to FW_LOADED and for any erroneous condition status will
   be moved to FW_FAILED.
</para>

<!-- drivers/gpu/drm/i915/intel_csr.c -->
<refentry id="API-intel-csr-load-status-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_csr_load_status_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_csr_load_status_get</refname>
 <refpurpose>
  to get firmware loading status.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum csr_state <function>intel_csr_load_status_get </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function helps to get the firmware loading status.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Firmware loading status.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-csr-load-status-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_csr_load_status_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_csr_load_status_set</refname>
 <refpurpose>
     help to set firmware loading status.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_csr_load_status_set </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>enum csr_state <parameter>state</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>state</parameter></term>
   <listitem>
    <para>
     enumeration of firmware loading status.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set the firmware loading status.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-csr-load-program">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_csr_load_program</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_csr_load_program</refname>
 <refpurpose>
     write the firmware from memory to register.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_csr_load_program </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   CSR firmware is read from a .bin file and kept in internal memory one time.
   Everytime display comes back from low power state this function is called to
   copy the firmware from internal memory to registers.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-csr-ucode-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_csr_ucode_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_csr_ucode_init</refname>
 <refpurpose>
     initialize the firmware loading.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_csr_ucode_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is called at the time of loading the display driver to read
   firmware from a .bin file and copied into a internal memory.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-csr-ucode-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_csr_ucode_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_csr_ucode_fini</refname>
 <refpurpose>
     unload the CSR firmware.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_csr_ucode_fini </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Firmmware unloading includes freeing the internal momory and reset the
   firmware loading status.
</para>
</refsect1>
</refentry>

      </sect2>
    </sect1>

    <sect1>
      <title>Memory Management and Command Submission</title>
      <para>
	This sections covers all things related to the GEM implementation in the
	i915 driver.
      </para>
      <sect2>
        <title>Batchbuffer Parsing</title>
<para>
   </para><para>
   Motivation:
   Certain OpenGL features (e.g. transform feedback, performance monitoring)
   require userspace code to submit batches containing commands such as
   MI_LOAD_REGISTER_IMM to access various registers. Unfortunately, some
   generations of the hardware will noop these commands in <quote>unsecure</quote> batches
   (which includes all userspace batches submitted via i915) even though the
   commands may be safe and represent the intended programming model of the
   device.
   </para><para>
   The software command parser is similar in operation to the command parsing
   done in hardware for unsecure batches. However, the software parser allows
   some operations that would be noop'd by hardware, if the parser determines
   the operation is safe, and submits the batch as <quote>secure</quote> to prevent hardware
   parsing.
   </para><para>
   Threats:
   At a high level, the hardware (and software) checks attempt to prevent
   granting userspace undue privileges. There are three categories of privilege.
   </para><para>
   First, commands which are explicitly defined as privileged or which should
   only be used by the kernel driver. The parser generally rejects such
   commands, though it may allow some from the drm master process.
   </para><para>
   Second, commands which access registers. To support correct/enhanced
   userspace functionality, particularly certain OpenGL extensions, the parser
   provides a whitelist of registers which userspace may safely access (for both
   normal and drm master processes).
   </para><para>
   Third, commands which access privileged memory (i.e. GGTT, HWS page, etc).
   The parser always rejects such commands.
   </para><para>
   The majority of the problematic commands fall in the MI_* range, with only a
   few specific commands on each ring (e.g. PIPE_CONTROL and MI_FLUSH_DW).
   </para><para>
   Implementation:
   Each ring maintains tables of commands and registers which the parser uses in
   scanning batch buffers submitted to that ring.
   </para><para>
   Since the set of commands that the parser must check for is significantly
   smaller than the number of commands supported, the parser tables contain only
   those commands required by the parser. This generally works because command
   opcode ranges have standard command length encodings. So for commands that
   the parser does not need to check, it can easily skip them. This is
   implemented via a per-ring length decoding vfunc.
   </para><para>
   Unfortunately, there are a number of commands that do not follow the standard
   length encoding for their opcode range, primarily amongst the MI_* commands.
   To handle this, the parser provides a way to define explicit <quote>skip</quote> entries
   in the per-ring command tables.
   </para><para>
   Other command table entries map fairly directly to high level categories
   mentioned above: rejected, master-only, register whitelist. The parser
   implements a number of checks, including the privileged memory checks, via a
   general bitmasking mechanism.
</para>

<!-- drivers/gpu/drm/i915/i915_cmd_parser.c -->
<refentry id="API-i915-cmd-parser-init-ring">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_cmd_parser_init_ring</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_cmd_parser_init_ring</refname>
 <refpurpose>
  set cmd parser related fields for a ringbuffer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_cmd_parser_init_ring </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     the ringbuffer to initialize
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Optionally initializes fields related to batch buffer command parsing in the
   struct intel_engine_cs based on whether the platform requires software
   command parsing.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero if initialization fails
</para>
</refsect1>
</refentry>

<refentry id="API-i915-cmd-parser-fini-ring">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_cmd_parser_fini_ring</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_cmd_parser_fini_ring</refname>
 <refpurpose>
     clean up cmd parser related fields
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_cmd_parser_fini_ring </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     the ringbuffer to clean up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Releases any resources related to command parsing that may have been
   initialized for the specified ring.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-needs-cmd-parser">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_needs_cmd_parser</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_needs_cmd_parser</refname>
 <refpurpose>
     should a given ring use software command parsing?
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>i915_needs_cmd_parser </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     the ring in question
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Only certain platforms require software batch buffer command parsing, and
   only when enabled via module parameter.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   true if the ring requires software command parsing
</para>
</refsect1>
</refentry>

<refentry id="API-i915-parse-cmds">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_parse_cmds</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_parse_cmds</refname>
 <refpurpose>
     parse a submitted batch buffer for privilege violations
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_parse_cmds </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
   <paramdef>struct drm_i915_gem_object * <parameter>batch_obj</parameter></paramdef>
   <paramdef>struct drm_i915_gem_object * <parameter>shadow_batch_obj</parameter></paramdef>
   <paramdef>u32 <parameter>batch_start_offset</parameter></paramdef>
   <paramdef>u32 <parameter>batch_len</parameter></paramdef>
   <paramdef>bool <parameter>is_master</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     the ring on which the batch is to execute
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>batch_obj</parameter></term>
   <listitem>
    <para>
     the batch buffer in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>shadow_batch_obj</parameter></term>
   <listitem>
    <para>
     copy of the batch buffer in question
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>batch_start_offset</parameter></term>
   <listitem>
    <para>
     byte offset in the batch at which execution starts
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>batch_len</parameter></term>
   <listitem>
    <para>
     length of the commands in batch_obj
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>is_master</parameter></term>
   <listitem>
    <para>
     is the submitting process the drm master?
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Parses the specified batch buffer looking for privilege violations as
   described in the overview.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero if the parser finds violations or otherwise fails; -EACCES
   if the batch appears legal but should use hardware parsing
</para>
</refsect1>
</refentry>

<refentry id="API-i915-cmd-parser-get-version">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_cmd_parser_get_version</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_cmd_parser_get_version</refname>
 <refpurpose>
     get the cmd parser version number
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_cmd_parser_get_version </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   The cmd parser maintains a simple increasing integer version number suitable
   for passing to userspace clients to determine what operations are permitted.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the current version number of the cmd parser
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Batchbuffer Pools</title>
<para>
   </para><para>
   In order to submit batch buffers as 'secure', the software command parser
   must ensure that a batch buffer cannot be modified after parsing. It does
   this by copying the user provided batch buffer contents to a kernel owned
   buffer from which the hardware will actually execute, and by carefully
   managing the address space bindings for such buffers.
   </para><para>
   The batch pool framework provides a mechanism for the driver to manage a
   set of scratch buffers to use for this purpose. The framework can be
   extended to support other uses cases should they arise.
</para>

<!-- drivers/gpu/drm/i915/i915_gem_batch_pool.c -->
<refentry id="API-i915-gem-batch-pool-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_batch_pool_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_batch_pool_init</refname>
 <refpurpose>
  initialize a batch buffer pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_batch_pool_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct i915_gem_batch_pool * <parameter>pool</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     the drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     the batch buffer pool
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-i915-gem-batch-pool-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_batch_pool_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_batch_pool_fini</refname>
 <refpurpose>
     clean up a batch buffer pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_batch_pool_fini </function></funcdef>
   <paramdef>struct i915_gem_batch_pool * <parameter>pool</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     the pool to clean up
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Callers must hold the struct_mutex.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-batch-pool-get">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_batch_pool_get</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_batch_pool_get</refname>
 <refpurpose>
     allocate a buffer from the pool
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_i915_gem_object * <function>i915_gem_batch_pool_get </function></funcdef>
   <paramdef>struct i915_gem_batch_pool * <parameter>pool</parameter></paramdef>
   <paramdef>size_t <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pool</parameter></term>
   <listitem>
    <para>
     the batch buffer pool
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     the minimum desired size of the returned buffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns an inactive buffer from <parameter>pool</parameter> with at least <parameter>size</parameter> bytes,
   with the pages pinned. The caller must <function>i915_gem_object_unpin_pages</function>
   on the returned object.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
   Callers must hold the struct_mutex
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   the buffer object or an error pointer
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Logical Rings, Logical Ring Contexts and Execlists</title>
<para>
   </para><para>
   Motivation:
   GEN8 brings an expansion of the HW contexts: <quote>Logical Ring Contexts</quote>.
   These expanded contexts enable a number of new abilities, especially
   <quote>Execlists</quote> (also implemented in this file).
   </para><para>
   One of the main differences with the legacy HW contexts is that logical
   ring contexts incorporate many more things to the context's state, like
   PDPs or ringbuffer control registers:
   </para><para>
   The reason why PDPs are included in the context is straightforward: as
   PPGTTs (per-process GTTs) are actually per-context, having the PDPs
   contained there mean you don't need to do a ppgtt-&gt;switch_mm yourself,
   instead, the GPU will do it for you on the context switch.
   </para><para>
   But, what about the ringbuffer control registers (head, tail, etc..)?
   shouldn't we just need a set of those per engine command streamer? This is
   where the name <quote>Logical Rings</quote> starts to make sense: by virtualizing the
   rings, the engine cs shifts to a new <quote>ring buffer</quote> with every context
   switch. When you want to submit a workload to the GPU you: A) choose your
   context, B) find its appropriate virtualized ring, C) write commands to it
   and then, finally, D) tell the GPU to switch to that context.
   </para><para>
   Instead of the legacy MI_SET_CONTEXT, the way you tell the GPU to switch
   to a contexts is via a context execution list, ergo <quote>Execlists</quote>.
   </para><para>
   LRC implementation:
   Regarding the creation of contexts, we have:
   </para><para>
   - One global default context.
   - One local default context for each opened fd.
   - One local extra context for each context create ioctl call.
   </para><para>
   Now that ringbuffers belong per-context (and not per-engine, like before)
   and that contexts are uniquely tied to a given engine (and not reusable,
   like before) we need:
   </para><para>
   - One ringbuffer per-engine inside each context.
   - One backing object per-engine inside each context.
   </para><para>
   The global default context starts its life with these new objects fully
   allocated and populated. The local default context for each opened fd is
   more complex, because we don't know at creation time which engine is going
   to use them. To handle this, we have implemented a deferred creation of LR
   contexts:
   </para><para>
   The local context starts its life as a hollow or blank holder, that only
   gets populated for a given engine once we receive an execbuffer. If later
   on we receive another execbuffer ioctl for the same context but a different
   engine, we allocate/populate a new ringbuffer and context backing object and
   so on.
   </para><para>
   Finally, regarding local contexts created using the ioctl call: as they are
   only allowed with the render ring, we can allocate &amp; populate them right
   away (no need to defer anything, at least for now).
   </para><para>
   Execlists implementation:
   Execlists are the new method by which, on gen8+ hardware, workloads are
   submitted for execution (as opposed to the legacy, ringbuffer-based, method).
   This method works as follows:
   </para><para>
   When a request is committed, its commands (the BB start and any leading or
   trailing commands, like the seqno breadcrumbs) are placed in the ringbuffer
   for the appropriate context. The tail pointer in the hardware context is not
   updated at this time, but instead, kept by the driver in the ringbuffer
   structure. A structure representing this request is added to a request queue
   for the appropriate engine: this structure contains a copy of the context's
   tail after the request was written to the ring buffer and a pointer to the
   context itself.
   </para><para>
   If the engine's request queue was empty before the request was added, the
   queue is processed immediately. Otherwise the queue will be processed during
   a context switch interrupt. In any case, elements on the queue will get sent
   (in pairs) to the GPU's ExecLists Submit Port (ELSP, for short) with a
   globally unique 20-bits submission ID.
   </para><para>
   When execution of a request completes, the GPU updates the context status
   buffer with a context complete event and generates a context switch interrupt.
   During the interrupt handling, the driver examines the events in the buffer:
   for each context complete event, if the announced ID matches that on the head
   of the request queue, then that request is retired and removed from the queue.
   </para><para>
   After processing, if any requests were retired and the queue is not empty
   then a new execution list can be submitted. The two requests at the front of
   the queue are next to be submitted but since a context may not occur twice in
   an execution list, if subsequent requests have the same ID as the first then
   the two requests must be combined. This is done simply by discarding requests
   at the head of the queue until either only one requests is left (in which case
   we use a NULL second context) or the first two requests have unique IDs.
   </para><para>
   By always executing the first two requests in the queue the driver ensures
   that the GPU is kept as busy as possible. In the case where a single context
   completes but a second context is still executing, the request for this second
   context will be at the head of the queue when we remove the first one. This
   request will then be resubmitted along with a new request for a different context,
   which will cause the hardware to continue executing the second request and queue
   the new request (the GPU detects the condition of a context getting preempted
   with the same context and optimizes the context switch flow by not doing
   preemption, but just sampling the new tail pointer).
   </para><para>
</para>

<!-- drivers/gpu/drm/i915/intel_lrc.c -->
<refentry id="API-intel-sanitize-enable-execlists">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_sanitize_enable_execlists</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_sanitize_enable_execlists</refname>
 <refpurpose>
  sanitize i915.enable_execlists
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_sanitize_enable_execlists </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>int <parameter>enable_execlists</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>enable_execlists</parameter></term>
   <listitem>
    <para>
     value of i915.enable_execlists module parameter.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Only certain platforms support Execlists (the prerequisites being
   support for Logical Ring Contexts and Aliasing PPGTT or better).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   1 if Execlists is supported and has to be enabled.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-execlists-ctx-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_execlists_ctx_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_execlists_ctx_id</refname>
 <refpurpose>
     get the Execlists Context ID
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>u32 <function>intel_execlists_ctx_id </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>ctx_obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx_obj</parameter></term>
   <listitem>
    <para>
     Logical Ring Context backing object.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Do not confuse with ctx-&gt;id! Unfortunately we have a name overload
</para>
</refsect1>
<refsect1>
<title>here</title>
<para>
   the old context ID we pass to userspace as a handler so that
   they can refer to a context, and the new context ID we pass to the
   ELSP so that the GPU can inform us of the context status via
   interrupts.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   20-bits globally unique context ID.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-lrc-irq-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_lrc_irq_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_lrc_irq_handler</refname>
 <refpurpose>
     handle Context Switch interrupts
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_lrc_irq_handler </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     Engine Command Streamer to handle.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Check the unread Context Status Buffers and manage the submission of new
   contexts to the ELSP accordingly.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-logical-ring-begin">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_logical_ring_begin</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_logical_ring_begin</refname>
 <refpurpose>
     prepare the logical ringbuffer to accept some commands
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_logical_ring_begin </function></funcdef>
   <paramdef>struct drm_i915_gem_request * <parameter>req</parameter></paramdef>
   <paramdef>int <parameter>num_dwords</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>req</parameter></term>
   <listitem>
    <para>
     The request to start some new work for
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>num_dwords</parameter></term>
   <listitem>
    <para>
     number of DWORDs that we plan to write to the ringbuffer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The ringbuffer might not be ready to accept the commands right away (maybe it needs to
   be wrapped, or wait a bit for the tail to be updated). This function takes care of that
   and also preallocates a request (every workload submission is still mediated through
   requests, same as it did with legacy ringbuffer submission).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero if the ringbuffer is not ready to be written to.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-execlists-submission">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_execlists_submission</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_execlists_submission</refname>
 <refpurpose>
     submit a batchbuffer for execution, Execlists style
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_execlists_submission </function></funcdef>
   <paramdef>struct i915_execbuffer_params * <parameter>params</parameter></paramdef>
   <paramdef>struct drm_i915_gem_execbuffer2 * <parameter>args</parameter></paramdef>
   <paramdef>struct list_head * <parameter>vmas</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>params</parameter></term>
   <listitem>
    <para>
     -- undescribed --
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>args</parameter></term>
   <listitem>
    <para>
     execbuffer call arguments.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vmas</parameter></term>
   <listitem>
    <para>
     list of vmas.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is the evil twin version of i915_gem_ringbuffer_submission. It abstracts
   away the submission details of the execbuffer ioctl call.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero if the submission fails.
</para>
</refsect1>
</refentry>

<refentry id="API-gen8-init-indirectctx-bb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen8_init_indirectctx_bb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen8_init_indirectctx_bb</refname>
 <refpurpose>
     initialize indirect ctx batch with WA
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen8_init_indirectctx_bb </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
   <paramdef>struct i915_wa_ctx_bb * <parameter>wa_ctx</parameter></paramdef>
   <paramdef>uint32_t *const <parameter>batch</parameter></paramdef>
   <paramdef>uint32_t * <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     only applicable for RCS
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wa_ctx</parameter></term>
   <listitem>
    <para>
     structure representing wa_ctx
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>batch</parameter></term>
   <listitem>
    <para>
     page in which WA are loaded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     This field specifies the start of the batch, it should be
     cache-aligned otherwise it is adjusted accordingly.
     Typically we only have one indirect_ctx and per_ctx batch buffer which are
     initialized at the beginning and shared across all contexts but this field
     helps us to have multiple batches at different offsets and select them based
     on a criteria. At the moment this batch always start at the beginning of the page
     and at this point we don't have multiple wa_ctx batch buffers.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>offset</title>
<para>
   specifies start of the batch, should be cache-aligned. This is updated
   with the offset value received as input.
</para>
</refsect1>
<refsect1>
<title>size</title>
<para>
   size of the batch in DWORDS but HW expects in terms of cachelines
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The number of WA applied are not known at the beginning; we use this field
   to return the no of DWORDS written.
   </para><para>

   It is to be noted that this batch does not contain MI_BATCH_BUFFER_END
   so it adds NOOPs as padding to make it cacheline aligned.
   MI_BATCH_BUFFER_END will be added to perctx batch and both of them together
   makes a complete batch buffer.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero if we exceed the PAGE_SIZE limit.
</para>
</refsect1>
</refentry>

<refentry id="API-gen8-init-perctx-bb">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen8_init_perctx_bb</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen8_init_perctx_bb</refname>
 <refpurpose>
     initialize per ctx batch with WA
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen8_init_perctx_bb </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
   <paramdef>struct i915_wa_ctx_bb * <parameter>wa_ctx</parameter></paramdef>
   <paramdef>uint32_t *const <parameter>batch</parameter></paramdef>
   <paramdef>uint32_t * <parameter>offset</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     only applicable for RCS
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>wa_ctx</parameter></term>
   <listitem>
    <para>
     structure representing wa_ctx
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>batch</parameter></term>
   <listitem>
    <para>
     page in which WA are loaded
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>offset</parameter></term>
   <listitem>
    <para>
     This field specifies the start of this batch.
     This batch is started immediately after indirect_ctx batch. Since we ensure
     that indirect_ctx ends on a cacheline this batch is aligned automatically.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>offset</title>
<para>
   specifies start of the batch, should be cache-aligned.
</para>
</refsect1>
<refsect1>
<title>size</title>
<para>
   size of the batch in DWORDS but HW expects in terms of cachelines
</para>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   The number of DWORDS written are returned using this field.
   </para><para>

   This batch is terminated with MI_BATCH_BUFFER_END and so we need not add padding
   to align it with cacheline as padding after MI_BATCH_BUFFER_END is redundant.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-logical-ring-cleanup">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_logical_ring_cleanup</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_logical_ring_cleanup</refname>
 <refpurpose>
     deallocate the Engine Command Streamer
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_logical_ring_cleanup </function></funcdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     Engine Command Streamer.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-intel-logical-rings-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_logical_rings_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_logical_rings_init</refname>
 <refpurpose>
     allocate, populate and init the Engine Command Streamers
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_logical_rings_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function inits the engines for an Execlists submission style (the equivalent in the
   legacy ringbuffer submission world would be i915_gem_init_rings). It does it only for
   those engines that are present in the hardware.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero if the initialization failed.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-lr-context-free">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_lr_context_free</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_lr_context_free</refname>
 <refpurpose>
     free the LRC specific bits of a context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_lr_context_free </function></funcdef>
   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     the LR context to free.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>The real context freeing is done in i915_gem_context_free</title>
<para>
   this only
</para>
</refsect1>
<refsect1>
<title>takes care of the bits that are LRC related</title>
<para>
   the per-engine backing
   objects and the logical ringbuffer.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-lr-context-deferred-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_lr_context_deferred_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_lr_context_deferred_alloc</refname>
 <refpurpose>
     create the LRC specific bits of a context
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_lr_context_deferred_alloc </function></funcdef>
   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
   <paramdef>struct intel_engine_cs * <parameter>ring</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     LR context to create.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ring</parameter></term>
   <listitem>
    <para>
     engine to be used with the context.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function can be called more than once, with different engines, if we plan
   to use the context with them. The context backing objects and the ringbuffers
   (specially the ringbuffer backing objects) suck a lot of memory up, and that's why
</para>
</refsect1>
<refsect1>
<title>the creation is a deferred call</title>
<para>
   it's better to make sure first that we need to use
   a given ring with the context.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero on error.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Global GTT views</title>
<para>
   </para><para>
   Background and previous state
   </para><para>
   Historically objects could exists (be bound) in global GTT space only as
   singular instances with a view representing all of the object's backing pages
   in a linear fashion. This view will be called a normal view.
   </para><para>
   To support multiple views of the same object, where the number of mapped
   pages is not equal to the backing store, or where the layout of the pages
   is not linear, concept of a GGTT view was added.
   </para><para>
   One example of an alternative view is a stereo display driven by a single
   image. In this case we would have a framebuffer looking like this
   (2x2 pages):
   </para><para>
   12
   34
   </para><para>
   Above would represent a normal GGTT view as normally mapped for GPU or CPU
   rendering. In contrast, fed to the display engine would be an alternative
   view which could look something like this:
   </para><para>
   1212
   3434
   </para><para>
   In this example both the size and layout of pages in the alternative view is
   different from the normal view.
   </para><para>
   Implementation and usage
   </para><para>
   GGTT views are implemented using VMAs and are distinguished via enum
   i915_ggtt_view_type and struct i915_ggtt_view.
   </para><para>
   A new flavour of core GEM functions which work with GGTT bound objects were
   added with the _ggtt_ infix, and sometimes with _view postfix to avoid
   renaming  in large amounts of code. They take the struct i915_ggtt_view
   parameter encapsulating all metadata required to implement a view.
   </para><para>
   As a helper for callers which are only interested in the normal view,
   globally const i915_ggtt_view_normal singleton instance exists. All old core
   GEM API functions, the ones not taking the view parameter, are operating on,
   or with the normal GGTT view.
   </para><para>
   Code wanting to add or use a new GGTT view needs to:
   </para><para>
   1. Add a new enum with a suitable name.
   2. Extend the metadata in the i915_ggtt_view structure if required.
   3. Add support to <function>i915_get_vma_pages</function>.
   </para><para>
   New views are required to build a scatter-gather table from within the
   i915_get_vma_pages function. This table is stored in the vma.ggtt_view and
   exists for the lifetime of an VMA.
   </para><para>
   Core API is designed to have copy semantics which means that passed in
   struct i915_ggtt_view does not need to be persistent (left around after
   calling the core API functions).
   </para><para>
</para>

<!-- drivers/gpu/drm/i915/i915_gem_gtt.c -->
<refentry id="API-gen8-ppgtt-alloc-pagetabs">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen8_ppgtt_alloc_pagetabs</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen8_ppgtt_alloc_pagetabs</refname>
 <refpurpose>
  Allocate page tables for VA range.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen8_ppgtt_alloc_pagetabs </function></funcdef>
   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
   <paramdef>struct i915_page_directory * <parameter>pd</parameter></paramdef>
   <paramdef>uint64_t <parameter>start</parameter></paramdef>
   <paramdef>uint64_t <parameter>length</parameter></paramdef>
   <paramdef>unsigned long * <parameter>new_pts</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     Master vm structure.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pd</parameter></term>
   <listitem>
    <para>
     Page directory for this address range.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Starting virtual address to begin allocations.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     Size of the allocations.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_pts</parameter></term>
   <listitem>
    <para>
     Bitmap set by function with new allocations. Likely used by the
     caller to free on error.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate the required number of page tables. Extremely similar to
   <function>gen8_ppgtt_alloc_page_directories</function>. The main difference is here we are limited by
   the page directory boundary (instead of the page directory pointer). That
   boundary is 1GB virtual. Therefore, unlike <function>gen8_ppgtt_alloc_page_directories</function>, it is
   possible, and likely that the caller will need to use multiple calls of this
   function to achieve the appropriate allocation.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if success; negative error code otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-gen8-ppgtt-alloc-page-directories">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen8_ppgtt_alloc_page_directories</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen8_ppgtt_alloc_page_directories</refname>
 <refpurpose>
     Allocate page directories for VA range.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen8_ppgtt_alloc_page_directories </function></funcdef>
   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
   <paramdef>struct i915_page_directory_pointer * <parameter>pdp</parameter></paramdef>
   <paramdef>uint64_t <parameter>start</parameter></paramdef>
   <paramdef>uint64_t <parameter>length</parameter></paramdef>
   <paramdef>unsigned long * <parameter>new_pds</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     Master vm structure.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pdp</parameter></term>
   <listitem>
    <para>
     Page directory pointer for this address range.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Starting virtual address to begin allocations.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     Size of the allocations.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_pds</parameter></term>
   <listitem>
    <para>
     Bitmap set by function with new allocations. Likely used by the
     caller to free on error.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate the required number of page directories starting at the pde index of
   <parameter>start</parameter>, and ending at the pde index <parameter>start</parameter> + <parameter>length</parameter>. This function will skip
   over already allocated page directories within the range, and only allocate
   new ones, setting the appropriate pointer within the pdp as well as the
   correct position in the bitmap <parameter>new_pds</parameter>.
   </para><para>

   The function will only allocate the pages within the range for a give page
   directory pointer. In other words, if <parameter>start</parameter> + <parameter>length</parameter> straddles a virtually
   addressed PDP boundary (512GB for 4k pages), there will be more allocations
   required by the caller, This is not currently possible, and the BUG in the
   code will prevent it.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if success; negative error code otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-gen8-ppgtt-alloc-page-dirpointers">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gen8_ppgtt_alloc_page_dirpointers</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gen8_ppgtt_alloc_page_dirpointers</refname>
 <refpurpose>
     Allocate pdps for VA range.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>gen8_ppgtt_alloc_page_dirpointers </function></funcdef>
   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
   <paramdef>struct i915_pml4 * <parameter>pml4</parameter></paramdef>
   <paramdef>uint64_t <parameter>start</parameter></paramdef>
   <paramdef>uint64_t <parameter>length</parameter></paramdef>
   <paramdef>unsigned long * <parameter>new_pdps</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     Master vm structure.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>pml4</parameter></term>
   <listitem>
    <para>
     Page map level 4 for this address range.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     Starting virtual address to begin allocations.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>length</parameter></term>
   <listitem>
    <para>
     Size of the allocations.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>new_pdps</parameter></term>
   <listitem>
    <para>
     Bitmap set by function with new allocations. Likely used by the
     caller to free on error.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Allocate the required number of page directory pointers. Extremely similar to
   <function>gen8_ppgtt_alloc_page_directories</function> and <function>gen8_ppgtt_alloc_pagetabs</function>.
   The main difference is here we are limited by the pml4 boundary (instead of
   the page directory pointer).
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if success; negative error code otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-vma-bind">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_vma_bind</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_vma_bind</refname>
 <refpurpose>
     Sets up PTEs for an VMA in it's corresponding address space.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_vma_bind </function></funcdef>
   <paramdef>struct i915_vma * <parameter>vma</parameter></paramdef>
   <paramdef>enum i915_cache_level <parameter>cache_level</parameter></paramdef>
   <paramdef>u32 <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vma</parameter></term>
   <listitem>
    <para>
     VMA to map
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cache_level</parameter></term>
   <listitem>
    <para>
     mapping cache level
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     flags like global or local mapping
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   DMA addresses are taken from the scatter-gather table of this object (or of
   this VMA in case of non-default GGTT views) and PTE entries set up.
   Note that DMA addresses are also the only part of the SG table we care about.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-ggtt-view-size">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_ggtt_view_size</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_ggtt_view_size</refname>
 <refpurpose>
     Get the size of a GGTT view.
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>size_t <function>i915_ggtt_view_size </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
   <paramdef>const struct i915_ggtt_view * <parameter>view</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     Object the view is of.
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>view</parameter></term>
   <listitem>
    <para>
     The view in question.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   <parameter>return</parameter> The size of the GGTT view in bytes.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>GTT Fences and Swizzling</title>
<!-- drivers/gpu/drm/i915/i915_gem_fence.c -->
<refentry id="API-i915-gem-object-put-fence">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_object_put_fence</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_object_put_fence</refname>
 <refpurpose>
  force-remove fence for an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_gem_object_put_fence </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     object to map through a fence reg
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function force-removes any fence from the given object, which is useful
   if the kernel wants to do untiled GTT access.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   </para><para>

   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-object-get-fence">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_object_get_fence</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_object_get_fence</refname>
 <refpurpose>
     set up fencing for an object
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_gem_object_get_fence </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     object to map through a fence reg
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   When mapping objects through the GTT, userspace wants to be able to write
   to them without having to worry about swizzling if the object is tiled.
   This function walks the fence regs looking for a free one for <parameter>obj</parameter>,
   stealing one if it can't find any.
   </para><para>

   It then sets up the reg based on the object's properties: address, pitch
   and tiling format.
   </para><para>

   For an untiled surface, this removes any existing fence.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   </para><para>

   0 on success, negative error code on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-object-pin-fence">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_object_pin_fence</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_object_pin_fence</refname>
 <refpurpose>
     pin fencing state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>bool <function>i915_gem_object_pin_fence </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     object to pin fencing for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This pins the fencing state (whether tiled or untiled) to make sure the
   object is ready to be used as a scanout target. Fencing status must be
   synchronize first by calling <function>i915_gem_object_get_fence</function>:
   </para><para>

   The resulting fence pin reference must be released again with
   <function>i915_gem_object_unpin_fence</function>.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   </para><para>

   True if the object has a fence, false otherwise.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-object-unpin-fence">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_object_unpin_fence</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_object_unpin_fence</refname>
 <refpurpose>
     unpin fencing state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_object_unpin_fence </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     object to unpin fencing for
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This releases the fence pin reference acquired through
   i915_gem_object_pin_fence. It will handle both objects with and without an
   attached fence correctly, callers do not need to distinguish this.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-restore-fences">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_restore_fences</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_restore_fences</refname>
 <refpurpose>
     restore fence state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_restore_fences </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Restore the hw fence state to match the software tracking again, to be called
   after a gpu reset and on resume.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-detect-bit-6-swizzle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_detect_bit_6_swizzle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_detect_bit_6_swizzle</refname>
 <refpurpose>
     detect bit 6 swizzling pattern
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_detect_bit_6_swizzle </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Detects bit 6 swizzling of address lookup between IGD access and CPU
   access through main memory.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-object-do-bit-17-swizzle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_object_do_bit_17_swizzle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_object_do_bit_17_swizzle</refname>
 <refpurpose>
     fixup bit 17 swizzling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_object_do_bit_17_swizzle </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     i915 GEM buffer object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function fixes up the swizzling in case any page frame number for this
   object has changed in bit 17 since that state has been saved with
   <function>i915_gem_object_save_bit_17_swizzle</function>.
   </para><para>

   This is called when pinning backing storage again, since the kernel is free
   to move unpinned backing storage around (either by directly moving pages or
   by swapping them out and back in again).
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-object-save-bit-17-swizzle">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_object_save_bit_17_swizzle</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_object_save_bit_17_swizzle</refname>
 <refpurpose>
     save bit 17 swizzling
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_object_save_bit_17_swizzle </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     i915 GEM buffer object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function saves the bit 17 of each page frame number so that swizzling
   can be fixed up later on with <function>i915_gem_object_do_bit_17_swizzle</function>. This must
   be called before the backing storage can be unpinned.
</para>
</refsect1>
</refentry>

        <sect3>
          <title>Global GTT Fence Handling</title>
<para>
   </para><para>
   Important to avoid confusions: <quote>fences</quote> in the i915 driver are not execution
   fences used to track command completion but hardware detiler objects which
   wrap a given range of the global GTT. Each platform has only a fairly limited
   set of these objects.
   </para><para>
   Fences are used to detile GTT memory mappings. They're also connected to the
   hardware frontbuffer render tracking and hence interract with frontbuffer
   conmpression. Furthermore on older platforms fences are required for tiled
   objects used by the display engine. They can also be used by the render
   engine - they're required for blitter commands and are optional for render
   commands. But on gen4+ both display (with the exception of fbc) and rendering
   have their own tiling state bits and don't need fences.
   </para><para>
   Also note that fences only support X and Y tiling and hence can't be used for
   the fancier new tiling formats like W, Ys and Yf.
   </para><para>
   Finally note that because fences are such a restricted resource they're
   dynamically associated with objects. Furthermore fence state is committed to
   the hardware lazily to avoid unecessary stalls on gen2/3. Therefore code must
   explictly call <function>i915_gem_object_get_fence</function> to synchronize fencing status
   for cpu access. Also note that some code wants an unfenced view, for those
   cases the fence can be removed forcefully with <function>i915_gem_object_put_fence</function>.
   </para><para>
   Internally these functions will synchronize with userspace access by removing
   CPU ptes into GTT mmaps (not the GTT ptes themselves) as needed.
</para>

        </sect3>
        <sect3>
          <title>Hardware Tiling and Swizzling Details</title>
<para>
   </para><para>
   The idea behind tiling is to increase cache hit rates by rearranging
   pixel data so that a group of pixel accesses are in the same cacheline.
   Performance improvement from doing this on the back/depth buffer are on
   the order of 30%.
   </para><para>
   Intel architectures make this somewhat more complicated, though, by
   adjustments made to addressing of data when the memory is in interleaved
   mode (matched pairs of DIMMS) to improve memory bandwidth.
   For interleaved memory, the CPU sends every sequential 64 bytes
   to an alternate memory channel so it can get the bandwidth from both.
   </para><para>
   The GPU also rearranges its accesses for increased bandwidth to interleaved
   memory, and it matches what the CPU does for non-tiled.  However, when tiled
   it does it a little differently, since one walks addresses not just in the
   X direction but also Y.  So, along with alternating channels when bit
   6 of the address flips, it also alternates when other bits flip --  Bits 9
   (every 512 bytes, an X tile scanline) and 10 (every two X tile scanlines)
   are common to both the 915 and 965-class hardware.
   </para><para>
   The CPU also sometimes XORs in higher bits as well, to improve
   bandwidth doing strided access like we do so frequently in graphics.  This
   is called <quote>Channel XOR Randomization</quote> in the MCH documentation.  The result
   is that the CPU is XORing in either bit 11 or bit 17 to bit 6 of its address
   decode.
   </para><para>
   All of this bit 6 XORing has an effect on our memory management,
   as we need to make sure that the 3d driver can correctly address object
   contents.
   </para><para>
   If we don't have interleaved memory, all tiling is safe and no swizzling is
   required.
   </para><para>
   When bit 17 is XORed in, we simply refuse to tile at all.  Bit
   17 is not just a page offset, so as we page an objet out and back in,
   individual pages in it will have different bit 17 addresses, resulting in
   each 64 bytes being swapped with its neighbor!
   </para><para>
   Otherwise, if interleaved, we have to tell the 3d driver what the address
   swizzling it needs to do is, since it's writing with the CPU to the pages
   (bit 6 and potentially bit 11 XORed in), and the GPU is reading from the
   pages (bit 6, 9, and 10 XORed in), resulting in a cumulative bit swizzling
   required by the CPU of XORing in bit 6, 9, 10, and potentially 11, in order
   to match what the GPU expects.
</para>

        </sect3>
      </sect2>
      <sect2>
        <title>Object Tiling IOCTLs</title>
<!-- drivers/gpu/drm/i915/i915_gem_tiling.c -->
<refentry id="API-i915-gem-set-tiling">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_set_tiling</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_set_tiling</refname>
 <refpurpose>
  IOCTL handler to set tiling mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_gem_set_tiling </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>struct drm_file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data pointer for the ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     DRM file for the ioctl call
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Sets the tiling mode of an object, returning the required swizzling of
   bit 6 of addresses in the object.
   </para><para>

   Called by the user via ioctl.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-get-tiling">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_get_tiling</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_get_tiling</refname>
 <refpurpose>
     IOCTL handler to get tiling mode
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_gem_get_tiling </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>void * <parameter>data</parameter></paramdef>
   <paramdef>struct drm_file * <parameter>file</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     DRM device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>data</parameter></term>
   <listitem>
    <para>
     data pointer for the ioctl
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>file</parameter></term>
   <listitem>
    <para>
     DRM file for the ioctl call
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Returns the current tiling mode and required bit 6 swizzling for the object.
   </para><para>

   Called by the user via ioctl.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   Zero on success, negative errno on failure.
</para>
</refsect1>
</refentry>

<para>
   </para><para>
   <function>i915_gem_set_tiling</function> and <function>i915_gem_get_tiling</function> is the userspace interface to
   declare fence register requirements.
   </para><para>
   In principle GEM doesn't care at all about the internal data layout of an
   object, and hence it also doesn't care about tiling or swizzling. There's two
   exceptions:
   </para><para>
   - For X and Y tiling the hardware provides detilers for CPU access, so called
   fences. Since there's only a limited amount of them the kernel must manage
   these, and therefore userspace must tell the kernel the object tiling if it
   wants to use fences for detiling.
   - On gen3 and gen4 platforms have a swizzling pattern for tiled objects which
   depends upon the physical page frame number. When swapping such objects the
   page frame number might change and the kernel must be able to fix this up
   and hence now the tiling. Note that on a subset of platforms with
   asymmetric memory channel population the swizzling pattern changes in an
   unknown way, and for those the kernel simply forbids swapping completely.
   </para><para>
   Since neither of this applies for new tiling layouts on modern platforms like
   W, Ys and Yf tiling GEM only allows object tiling to be set to X or Y tiled.
   Anything else can be handled in userspace entirely without the kernel's
   invovlement.
</para>

      </sect2>
      <sect2>
        <title>Buffer Object Eviction</title>
	<para>
	  This section documents the interface functions for evicting buffer
	  objects to make space available in the virtual gpu address spaces.
	  Note that this is mostly orthogonal to shrinking buffer objects
	  caches, which has the goal to make main memory (shared with the gpu
	  through the unified memory architecture) available.
	</para>
<!-- drivers/gpu/drm/i915/i915_gem_evict.c -->
<refentry id="API-i915-gem-evict-something">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_evict_something</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_evict_something</refname>
 <refpurpose>
  Evict vmas to make room for binding a new one
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_gem_evict_something </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
   <paramdef>int <parameter>min_size</parameter></paramdef>
   <paramdef>unsigned <parameter>alignment</parameter></paramdef>
   <paramdef>unsigned <parameter>cache_level</parameter></paramdef>
   <paramdef>unsigned long <parameter>start</parameter></paramdef>
   <paramdef>unsigned long <parameter>end</parameter></paramdef>
   <paramdef>unsigned <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm_device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     address space to evict from
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>min_size</parameter></term>
   <listitem>
    <para>
     size of the desired free space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>alignment</parameter></term>
   <listitem>
    <para>
     alignment constraint of the desired free space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>cache_level</parameter></term>
   <listitem>
    <para>
     cache_level for the desired space
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>start</parameter></term>
   <listitem>
    <para>
     start (inclusive) of the range from which to evict objects
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>end</parameter></term>
   <listitem>
    <para>
     end (exclusive) of the range from which to evict objects
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     additional flags to control the eviction algorithm
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function will try to evict vmas until a free space satisfying the
   requirements is found. Callers must check first whether any such hole exists
   already before calling this function.
   </para><para>

   This function is used by the object/vma binding code.
   </para><para>

   Since this function is only used to free up virtual address space it only
   ignores pinned vmas, and not object where the backing storage itself is
   pinned. Hence obj-&gt;pages_pin_count does not protect against eviction.
</para>
</refsect1>
<refsect1>
<title>To clarify</title>
<para>
   This is for freeing up virtual address space, not for freeing
   memory in e.g. the shrinker.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-evict-vm">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_evict_vm</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_evict_vm</refname>
 <refpurpose>
     Evict all idle vmas from a vm
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_gem_evict_vm </function></funcdef>
   <paramdef>struct i915_address_space * <parameter>vm</parameter></paramdef>
   <paramdef>bool <parameter>do_idle</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>vm</parameter></term>
   <listitem>
    <para>
     Address space to cleanse
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>do_idle</parameter></term>
   <listitem>
    <para>
     Boolean directing whether to idle first.
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function evicts all idles vmas from a vm. If all unpinned vmas should be
   evicted the <parameter>do_idle</parameter> needs to be set to true.
   </para><para>

   This is used by the execbuf code as a last-ditch effort to defragment the
   address space.
</para>
</refsect1>
<refsect1>
<title>To clarify</title>
<para>
   This is for freeing up virtual address space, not for freeing
   memory in e.g. the shrinker.
</para>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>Buffer Object Memory Shrinking</title>
	<para>
	  This section documents the interface function for shrinking memory
	  usage of buffer object caches. Shrinking is used to make main memory
	  available.  Note that this is mostly orthogonal to evicting buffer
	  objects, which has the goal to make space in gpu virtual address
	  spaces.
	</para>
<!-- drivers/gpu/drm/i915/i915_gem_shrinker.c -->
<refentry id="API-i915-gem-shrink">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_shrink</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_shrink</refname>
 <refpurpose>
  Shrink buffer object caches
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>i915_gem_shrink </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
   <paramdef>unsigned long <parameter>target</parameter></paramdef>
   <paramdef>unsigned <parameter>flags</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>target</parameter></term>
   <listitem>
    <para>
     amount of memory to make available, in pages
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>flags</parameter></term>
   <listitem>
    <para>
     control flags for selecting cache types
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function is the main interface to the shrinker. It will try to release
   up to <parameter>target</parameter> pages of main memory backing storage from buffer objects.
   Selection of the specific caches can be done with <parameter>flags</parameter>. This is e.g. useful
   when purgeable objects should be removed from caches preferentially.
   </para><para>

   Note that it's not guaranteed that released amount is actually available as
   free system memory - the pages might still be in-used to due to other reasons
   (like cpu mmaps) or the mm core has reused them before we could grab them.
   Therefore code that needs to explicitly shrink buffer objects caches (e.g. to
   avoid deadlocks in memory reclaim) must fall back to <function>i915_gem_shrink_all</function>.
   </para><para>

   Also note that any kind of pinning (both per-vma address space pins and
   backing storage pins at the buffer object level) result in the shrinker code
   having to skip the object.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The number of pages of backing storage actually released.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-shrink-all">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_shrink_all</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_shrink_all</refname>
 <refpurpose>
     Shrink buffer object caches completely
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>unsigned long <function>i915_gem_shrink_all </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a simple wraper around <function>i915_gem_shrink</function> to aggressively shrink all
   caches completely. It also first waits for and retires all outstanding
   requests to also be able to release backing storage for active objects.
   </para><para>

   This should only be used in code to intentionally quiescent the gpu or as a
   last-ditch effort when memory seems to have run out.
</para>
</refsect1>
<refsect1>
<title>Returns</title>
<para>
   The number of pages of backing storage actually released.
</para>
</refsect1>
</refentry>

<refentry id="API-i915-gem-shrinker-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_gem_shrinker_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_gem_shrinker_init</refname>
 <refpurpose>
     Initialize i915 shrinker
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>i915_gem_shrinker_init </function></funcdef>
   <paramdef>struct drm_i915_private * <parameter>dev_priv</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev_priv</parameter></term>
   <listitem>
    <para>
     i915 device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This function registers and sets up the i915 shrinker and OOM handler.
</para>
</refsect1>
</refentry>

      </sect2>
    </sect1>
    <sect1>
      <title>GuC-based Command Submission</title>
      <sect2>
        <title>GuC</title>
<refentry>
 <refnamediv>
  <refname>
   drivers/gpu/drm/i915/intel_guc_loader.c
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>drivers/gpu/drm/i915/intel_guc_loader.c</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- drivers/gpu/drm/i915/intel_guc_loader.c -->
<refentry id="API-intel-guc-ucode-load">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_guc_ucode_load</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_guc_ucode_load</refname>
 <refpurpose>
  load GuC uCode into the device
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_guc_ucode_load </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called from <function>gem_init_hw</function> during driver loading and also after a GPU reset.
   </para><para>

   The firmware image should have already been fetched into memory by the
   earlier call to <function>intel_guc_ucode_init</function>, so here we need only check that
   is succeeded, and then transfer the image to the h/w.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   non-zero code on error
</para>
</refsect1>
</refentry>

<refentry id="API-intel-guc-ucode-init">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_guc_ucode_init</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_guc_ucode_init</refname>
 <refpurpose>
     define parameters and fetch firmware
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_guc_ucode_init </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Called early during driver load, but after GEM is initialised.
   </para><para>

   The firmware will be transferred to the GuC's memory later,
   when <function>intel_guc_ucode_load</function> is called.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-guc-ucode-fini">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_guc_ucode_fini</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_guc_ucode_fini</refname>
 <refpurpose>
     clean up all allocated resources
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>intel_guc_ucode_fini </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

      </sect2>
      <sect2>
        <title>GuC Client</title>
<refentry>
 <refnamediv>
  <refname>
   drivers/gpu/drm/i915/i915_guc_submission.c
  </refname>
  <refpurpose>
   Document generation inconsistency
  </refpurpose>
 </refnamediv>
 <refsect1>
  <title>
   Oops
  </title>
  <warning>
   <para>
    The template for this document tried to insert
    the structured comment from the file
    <filename>drivers/gpu/drm/i915/i915_guc_submission.c</filename> at this point,
    but none was found.
    This dummy section is inserted to allow
    generation to continue.
   </para>
  </warning>
 </refsect1>
</refentry>
<!-- drivers/gpu/drm/i915/i915_guc_submission.c -->
<refentry id="API-i915-guc-submit">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>i915_guc_submit</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>i915_guc_submit</refname>
 <refpurpose>
  Submit commands through GuC
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>i915_guc_submit </function></funcdef>
   <paramdef>struct i915_guc_client * <parameter>client</parameter></paramdef>
   <paramdef>struct drm_i915_gem_request * <parameter>rq</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>client</parameter></term>
   <listitem>
    <para>
     the guc client where commands will go through
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>rq</parameter></term>
   <listitem>
    <para>
     -- undescribed --
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 if succeed
</para>
</refsect1>
</refentry>

<refentry id="API-gem-allocate-guc-obj">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gem_allocate_guc_obj</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gem_allocate_guc_obj</refname>
 <refpurpose>
     Allocate gem object for GuC usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct drm_i915_gem_object * <function>gem_allocate_guc_obj </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>u32 <parameter>size</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>size</parameter></term>
   <listitem>
    <para>
     size of object
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   This is a wrapper to create a gem obj. In order to use it inside GuC, the
   object needs to be pinned lifetime. Also we must pin it to gtt space other
   than [0, GUC_WOPCM_TOP) because this range is reserved inside GuC.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   A drm_i915_gem_object if successful, otherwise NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-gem-release-guc-obj">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>gem_release_guc_obj</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>gem_release_guc_obj</refname>
 <refpurpose>
     Release gem object allocated for GuC usage
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>gem_release_guc_obj </function></funcdef>
   <paramdef>struct drm_i915_gem_object * <parameter>obj</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>obj</parameter></term>
   <listitem>
    <para>
     gem obj to be released
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-guc-client-alloc">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>guc_client_alloc</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>guc_client_alloc</refname>
 <refpurpose>
     Allocate an i915_guc_client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>struct i915_guc_client * <function>guc_client_alloc </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
   <paramdef>uint32_t <parameter>priority</parameter></paramdef>
   <paramdef>struct intel_context * <parameter>ctx</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>priority</parameter></term>
   <listitem>
    <para>
     four levels priority _CRITICAL, _HIGH, _NORMAL and _LOW
     The kernel client to replace ExecList submission is created with
     NORMAL priority. Priority of a client for scheduler can be HIGH,
     while a preemption context can use CRITICAL.
     <parameter>ctx</parameter>		the context to own the client (we use the default render context)
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ctx</parameter></term>
   <listitem>
    <para>
     -- undescribed --
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   An i915_guc_client object if success.
</para>
</refsect1>
</refentry>

<refentry id="API-intel-guc-suspend">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_guc_suspend</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_guc_suspend</refname>
 <refpurpose>
     notify GuC entering suspend state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_guc_suspend </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

<refentry id="API-intel-guc-resume">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>intel_guc_resume</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>intel_guc_resume</refname>
 <refpurpose>
     notify GuC resuming from suspend state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>intel_guc_resume </function></funcdef>
   <paramdef>struct drm_device * <parameter>dev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     drm device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
</refentry>

      </sect2>
    </sect1>

    <sect1>
      <title> Tracing </title>
      <para>
    This sections covers all things related to the tracepoints implemented in
    the i915 driver.
      </para>
      <sect2>
        <title> i915_ppgtt_create and i915_ppgtt_release </title>
<para>
   </para><para>
   With full ppgtt enabled each process using drm will allocate at least one
   translation table. With these traces it is possible to keep track of the
   allocation and of the lifetime of the tables; this can be used during
   testing/debug to verify that we are not leaking ppgtts.
   These traces identify the ppgtt through the vm pointer, which is also printed
   by the i915_vma_bind and i915_vma_unbind tracepoints.
</para>

      </sect2>
      <sect2>
        <title> i915_context_create and i915_context_free </title>
<para>
   </para><para>
   These tracepoints are used to track creation and deletion of contexts.
   If full ppgtt is enabled, they also print the address of the vm assigned to
   the context.
</para>

      </sect2>
      <sect2>
        <title> switch_mm </title>
<para>
   </para><para>
   This tracepoint allows tracking of the mm switch, which is an important point
   in the lifetime of the vm in the legacy submission path. This tracepoint is
   called only if full ppgtt is enabled.
</para>

      </sect2>
    </sect1>

  </chapter>
</part>

<part id="vga_switcheroo">
  <title>vga_switcheroo</title>
  <partintro>
<para>
   </para><para>
   vga_switcheroo is the Linux subsystem for laptop hybrid graphics.
   These come in two flavors:
   </para><para>
   * muxed: Dual GPUs with a multiplexer chip to switch outputs between GPUs.
   * muxless: Dual GPUs but only one of them is connected to outputs.
   The other one is merely used to offload rendering, its results
   are copied over PCIe into the framebuffer. On Linux this is
   supported with DRI PRIME.
   </para><para>
   Hybrid graphics started to appear in the late Naughties and were initially
   all muxed. Newer laptops moved to a muxless architecture for cost reasons.
   A notable exception is the MacBook Pro which continues to use a mux.
   Muxes come with varying capabilities: Some switch only the panel, others
   can also switch external displays. Some switch all display pins at once
   while others can switch just the DDC lines. (To allow EDID probing
   for the inactive GPU.) Also, muxes are often used to cut power to the
   discrete GPU while it is not used.
   </para><para>
   DRM drivers register GPUs with vga_switcheroo, these are heretoforth called
   clients. The mux is called the handler. Muxless machines also register a
   handler to control the power state of the discrete GPU, its -&gt;switchto
   callback is a no-op for obvious reasons. The discrete GPU is often equipped
   with an HDA controller for the HDMI/DP audio signal, this will also
   register as a client so that vga_switcheroo can take care of the correct
   suspend/resume order when changing the discrete GPU's power state. In total
   there can thus be up to three clients: Two vga clients (GPUs) and one audio
   client (on the discrete GPU). The code is mostly prepared to support
   machines with more than two GPUs should they become available.
   The GPU to which the outputs are currently switched is called the
   active client in vga_switcheroo parlance. The GPU not in use is the
   inactive client.
</para>

  </partintro>

  <chapter id="modes_of_use">
    <title>Modes of Use</title>
  <sect1>
    <title>Manual switching and manual power control</title>
<para>
   </para><para>
   In this mode of use, the file /sys/kernel/debug/vgaswitcheroo/switch
   can be read to retrieve the current vga_switcheroo state and commands
   can be written to it to change the state. The file appears as soon as
   two GPU drivers and one handler have registered with vga_switcheroo.
   The following commands are understood:
   </para><para>
   * OFF: Power off the device not in use.
   * ON: Power on the device not in use.
   * IGD: Switch to the integrated graphics device.
   Power on the integrated GPU if necessary, power off the discrete GPU.
   Prerequisite is that no user space processes (e.g. Xorg, alsactl)
   have opened device files of the GPUs or the audio client. If the
   switch fails, the user may invoke lsof(8) or fuser(1) on /dev/dri/
   and /dev/snd/controlC1 to identify processes blocking the switch.
   * DIS: Switch to the discrete graphics device.
   * DIGD: Delayed switch to the integrated graphics device.
   This will perform the switch once the last user space process has
   closed the device files of the GPUs and the audio client.
   * DDIS: Delayed switch to the discrete graphics device.
   * MIGD: Mux-only switch to the integrated graphics device.
   Does not remap console or change the power state of either gpu.
   If the integrated GPU is currently off, the screen will turn black.
   If it is on, the screen will show whatever happens to be in VRAM.
   Either way, the user has to blindly enter the command to switch back.
   * MDIS: Mux-only switch to the discrete graphics device.
   </para><para>
   For GPUs whose power state is controlled by the driver's runtime pm,
   the ON and OFF commands are a no-op (see next section).
   </para><para>
   For muxless machines, the IGD/DIS, DIGD/DDIS and MIGD/MDIS commands
   should not be used.
</para>

  </sect1>
  <sect1>
    <title>Driver power control</title>
<para>
   </para><para>
   In this mode of use, the discrete GPU automatically powers up and down at
   the discretion of the driver's runtime pm. On muxed machines, the user may
   still influence the muxer state by way of the debugfs interface, however
   the ON and OFF commands become a no-op for the discrete GPU.
   </para><para>
   This mode is the default on Nvidia HybridPower/Optimus and ATI PowerXpress.
   Specifying nouveau.runpm=0, radeon.runpm=0 or amdgpu.runpm=0 on the kernel
   command line disables it.
   </para><para>
   When the driver decides to power up or down, it notifies vga_switcheroo
   thereof so that it can (a) power the audio device on the GPU up or down,
   and (b) update its internal power state representation for the device.
   This is achieved by <function>vga_switcheroo_set_dynamic_switch</function>.
   </para><para>
   After the GPU has been suspended, the handler needs to be called to cut
   power to the GPU. Likewise it needs to reinstate power before the GPU
   can resume. This is achieved by <function>vga_switcheroo_init_domain_pm_ops</function>,
   which augments the GPU's suspend/resume functions by the requisite
   calls to the handler.
   </para><para>
   When the audio device resumes, the GPU needs to be woken. This is achieved
   by <function>vga_switcheroo_init_domain_pm_optimus_hdmi_audio</function>, which augments the
   audio device's resume function.
   </para><para>
   On muxed machines, if the mux is initially switched to the discrete GPU,
   the user ends up with a black screen when the GPU powers down after boot.
   As a workaround, the mux is forced to the integrated GPU on runtime suspend,
   cf. https://bugs.freedesktop.org/show_bug.cgi?id=75917
</para>

  </sect1>
  </chapter>

  <chapter id="pubfunctions">
    <title>Public functions</title>
<!-- drivers/gpu/vga/vga_switcheroo.c -->
<refentry id="API-vga-switcheroo-register-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_register_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_register_handler</refname>
 <refpurpose>
  register handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vga_switcheroo_register_handler </function></funcdef>
   <paramdef>const struct vga_switcheroo_handler * <parameter>handler</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>handler</parameter></term>
   <listitem>
    <para>
     handler callbacks
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register handler. Enable vga_switcheroo if two vga clients have already
   registered.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success, -EINVAL if a handler was already registered.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-unregister-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_unregister_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_unregister_handler</refname>
 <refpurpose>
     unregister handler
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vga_switcheroo_unregister_handler </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   </para><para>

   Unregister handler. Disable vga_switcheroo.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-register-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_register_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_register_client</refname>
 <refpurpose>
     register vga client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vga_switcheroo_register_client </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct vga_switcheroo_client_ops * <parameter>ops</parameter></paramdef>
   <paramdef>bool <parameter>driver_power_control</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     client pci device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     client callbacks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>driver_power_control</parameter></term>
   <listitem>
    <para>
     whether power state is controlled by the driver's
     runtime pm
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register vga client (GPU). Enable vga_switcheroo if another GPU and a
   handler have already registered. The power state of the client is assumed
   to be ON.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success, -ENOMEM on memory allocation error.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-register-audio-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_register_audio_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_register_audio_client</refname>
 <refpurpose>
     register audio client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vga_switcheroo_register_audio_client </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>const struct vga_switcheroo_client_ops * <parameter>ops</parameter></paramdef>
   <paramdef>enum vga_switcheroo_client_id <parameter>id</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     client pci device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>ops</parameter></term>
   <listitem>
    <para>
     client callbacks
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>id</parameter></term>
   <listitem>
    <para>
     client identifier
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Register audio client (audio device on a GPU). The power state of the
   client is assumed to be ON.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success, -ENOMEM on memory allocation error.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-get-client-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_get_client_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_get_client_state</refname>
 <refpurpose>
     obtain power state of a given client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>enum vga_switcheroo_state <function>vga_switcheroo_get_client_state </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     client pci device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Obtain power state of a given client as seen from vga_switcheroo.
   The function is only called from hda_intel.c.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   Power state.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-unregister-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_unregister_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_unregister_client</refname>
 <refpurpose>
     unregister client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vga_switcheroo_unregister_client </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     client pci device
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Unregister client. Disable vga_switcheroo if this is a vga client (GPU).
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-client-fb-set">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_client_fb_set</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_client_fb_set</refname>
 <refpurpose>
     set framebuffer of a given client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vga_switcheroo_client_fb_set </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>struct fb_info * <parameter>info</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     client pci device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>info</parameter></term>
   <listitem>
    <para>
     framebuffer
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Set framebuffer of a given client. The console will be remapped to this
   on switching.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-process-delayed-switch">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_process_delayed_switch</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_process_delayed_switch</refname>
 <refpurpose>
     helper for delayed switching
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vga_switcheroo_process_delayed_switch </function></funcdef>
   <paramdef> <parameter>void</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>void</parameter></term>
   <listitem>
    <para>
     no arguments
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Manual switching and manual power control</title>
<para>
   </para><para>

   Process a delayed switch if one is pending. DRM drivers should call this
   from their -&gt;lastclose callback.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success. -EINVAL if no delayed switch is pending, if the client
   has unregistered in the meantime or if there are other clients blocking the
   switch. If the actual switch fails, an error is reported and 0 is returned.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-set-dynamic-switch">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_set_dynamic_switch</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_set_dynamic_switch</refname>
 <refpurpose>
     helper for driver power control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>void <function>vga_switcheroo_set_dynamic_switch </function></funcdef>
   <paramdef>struct pci_dev * <parameter>pdev</parameter></paramdef>
   <paramdef>enum vga_switcheroo_state <parameter>dynamic</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>pdev</parameter></term>
   <listitem>
    <para>
     client pci device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>dynamic</parameter></term>
   <listitem>
    <para>
     new power state
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper for GPUs whose power state is controlled by the driver's runtime pm.
   When the driver decides to power up or down, it notifies vga_switcheroo
   thereof using this helper so that it can (a) power the audio device on
   the GPU up or down, and (b) update its internal power state representation
   for the device.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-init-domain-pm-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_init_domain_pm_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_init_domain_pm_ops</refname>
 <refpurpose>
     helper for driver power control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vga_switcheroo_init_domain_pm_ops </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct dev_pm_domain * <parameter>domain</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     vga client device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     power domain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper for GPUs whose power state is controlled by the driver's runtime pm.
   After the GPU has been suspended, the handler needs to be called to cut
   power to the GPU. Likewise it needs to reinstate power before the GPU
   can resume. To this end, this helper augments the suspend/resume functions
   by the requisite calls to the handler. It needs only be called on platforms
   where the power switch is separate to the device being powered down.
</para>
</refsect1>
</refentry>

<refentry id="API-vga-switcheroo-init-domain-pm-optimus-hdmi-audio">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>vga_switcheroo_init_domain_pm_optimus_hdmi_audio</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>vga_switcheroo_init_domain_pm_optimus_hdmi_audio</refname>
 <refpurpose>
     helper for driver power control
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <funcsynopsis><funcprototype>
   <funcdef>int <function>vga_switcheroo_init_domain_pm_optimus_hdmi_audio </function></funcdef>
   <paramdef>struct device * <parameter>dev</parameter></paramdef>
   <paramdef>struct dev_pm_domain * <parameter>domain</parameter></paramdef>
  </funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
 <title>Arguments</title>
 <variablelist>
  <varlistentry>
   <term><parameter>dev</parameter></term>
   <listitem>
    <para>
     audio client device
    </para>
   </listitem>
  </varlistentry>
  <varlistentry>
   <term><parameter>domain</parameter></term>
   <listitem>
    <para>
     power domain
    </para>
   </listitem>
  </varlistentry>
 </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Helper for GPUs whose power state is controlled by the driver's runtime pm.
   When the audio device resumes, the GPU needs to be woken. This helper
   augments the audio device's resume function to do that.
</para>
</refsect1>
<refsect1>
<title>Return</title>
<para>
   0 on success, -EINVAL if no power management operations are
   defined for this device.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="pubstructures">
    <title>Public structures</title>
<refentry id="API-struct-vga-switcheroo-handler">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vga_switcheroo_handler</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vga_switcheroo_handler</refname>
 <refpurpose>
  handler callbacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vga_switcheroo_handler {
  int (* init) (void);
  int (* switchto) (enum vga_switcheroo_client_id id);
  int (* power_state) (enum vga_switcheroo_client_id id,enum vga_switcheroo_state state);
  enum vga_switcheroo_client_id (* get_client_id) (struct pci_dev *pdev);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>init</term>
      <listitem><para>
initialize handler.
Optional. This gets called when vga_switcheroo is enabled, i.e. when
two vga clients have registered. It allows the handler to perform
some delayed initialization that depends on the existence of the
vga clients. Currently only the radeon and amdgpu drivers use this.
The return value is ignored
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>switchto</term>
      <listitem><para>
switch outputs to given client.
Mandatory. For muxless machines this should be a no-op. Returning 0
denotes success, anything else failure (in which case the switch is
aborted)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>power_state</term>
      <listitem><para>
cut or reinstate power of given client.
Optional. The return value is ignored
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>get_client_id</term>
      <listitem><para>
determine if given pci device is integrated or discrete GPU.
Mandatory
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Handler callbacks. The multiplexer itself. The <parameter>switchto</parameter> and <parameter>get_client_id</parameter>
   methods are mandatory, all others may be set to NULL.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-vga-switcheroo-client-ops">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vga_switcheroo_client_ops</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vga_switcheroo_client_ops</refname>
 <refpurpose>
  client callbacks
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vga_switcheroo_client_ops {
  void (* set_gpu_state) (struct pci_dev *dev, enum vga_switcheroo_state);
  void (* reprobe) (struct pci_dev *dev);
  bool (* can_switch) (struct pci_dev *dev);
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>set_gpu_state</term>
      <listitem><para>
do the equivalent of suspend/resume for the card.
Mandatory. This should not cut power to the discrete GPU,
which is the job of the handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>reprobe</term>
      <listitem><para>
poll outputs.
Optional. This gets called after waking the GPU and switching
the outputs to it
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>can_switch</term>
      <listitem><para>
check if the device is in a position to switch now.
Mandatory. The client should return false if a user space process
has one of its device files open
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Client callbacks. A client can be either a GPU or an audio device on a GPU.
   The <parameter>set_gpu_state</parameter> and <parameter>can_switch</parameter> methods are mandatory, <parameter>reprobe</parameter> may be
   set to NULL. For audio clients, the <parameter>reprobe</parameter> member is bogus.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="pubconstants">
    <title>Public constants</title>
<refentry id="API-enum-vga-switcheroo-client-id">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum vga_switcheroo_client_id</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum vga_switcheroo_client_id</refname>
 <refpurpose>
  client identifier
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum vga_switcheroo_client_id {
  VGA_SWITCHEROO_UNKNOWN_ID,
  VGA_SWITCHEROO_IGD,
  VGA_SWITCHEROO_DIS,
  VGA_SWITCHEROO_MAX_CLIENTS
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>VGA_SWITCHEROO_UNKNOWN_ID</term>
      <listitem><para>
initial identifier assigned to vga clients.
Determining the id requires the handler, so GPUs are given their
true id in a delayed fashion in <function>vga_switcheroo_enable</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VGA_SWITCHEROO_IGD</term>
      <listitem><para>
integrated graphics device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VGA_SWITCHEROO_DIS</term>
      <listitem><para>
discrete graphics device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VGA_SWITCHEROO_MAX_CLIENTS</term>
      <listitem><para>
currently no more than two GPUs are supported
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Client identifier. Audio clients use the same identifier &amp; 0x100.
</para>
</refsect1>
</refentry>

<refentry id="API-enum-vga-switcheroo-state">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>enum vga_switcheroo_state</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>enum vga_switcheroo_state</refname>
 <refpurpose>
  client power state
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
enum vga_switcheroo_state {
  VGA_SWITCHEROO_OFF,
  VGA_SWITCHEROO_ON,
  VGA_SWITCHEROO_NOT_FOUND
};  </programlisting>
</refsynopsisdiv>
<refsect1>
 <title>Constants</title>
  <variablelist>
    <varlistentry>      <term>VGA_SWITCHEROO_OFF</term>
      <listitem><para>
off
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VGA_SWITCHEROO_ON</term>
      <listitem><para>
on
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>VGA_SWITCHEROO_NOT_FOUND</term>
      <listitem><para>
client has not registered with vga_switcheroo.
Only used in <function>vga_switcheroo_get_client_state</function> which in turn is only
called from hda_intel.c
      </para></listitem>
    </varlistentry>
  </variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
   Client power state.
</para>
</refsect1>
</refentry>

  </chapter>

  <chapter id="privstructures">
    <title>Private structures</title>
<refentry id="API-struct-vgasr-priv">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vgasr_priv</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vgasr_priv</refname>
 <refpurpose>
  vga_switcheroo private data
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vgasr_priv {
  bool active;
  bool delayed_switch_active;
  enum vga_switcheroo_client_id delayed_client_id;
  struct dentry * debugfs_root;
  struct dentry * switch_file;
  int registered_clients;
  struct list_head clients;
  const struct vga_switcheroo_handler * handler;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>active</term>
      <listitem><para>
whether vga_switcheroo is enabled.
Prerequisite is the registration of two GPUs and a handler
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delayed_switch_active</term>
      <listitem><para>
whether a delayed switch is pending
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>delayed_client_id</term>
      <listitem><para>
client to which a delayed switch is pending
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>debugfs_root</term>
      <listitem><para>
directory for vga_switcheroo debugfs interface
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>switch_file</term>
      <listitem><para>
file for vga_switcheroo debugfs interface
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>registered_clients</term>
      <listitem><para>
number of registered GPUs
(counting only vga clients, not audio clients)
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>clients</term>
      <listitem><para>
list of registered clients
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>handler</term>
      <listitem><para>
registered handler
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   vga_switcheroo private data. Currently only one vga_switcheroo instance
   per system is supported.
</para>
</refsect1>
</refentry>

<refentry id="API-struct-vga-switcheroo-client">
<refentryinfo>
 <title>LINUX</title>
 <productname>Kernel Hackers Manual</productname>
 <date>July 2017</date>
</refentryinfo>
<refmeta>
 <refentrytitle><phrase>struct vga_switcheroo_client</phrase></refentrytitle>
 <manvolnum>9</manvolnum>
 <refmiscinfo class="version">4.4.14</refmiscinfo>
</refmeta>
<refnamediv>
 <refname>struct vga_switcheroo_client</refname>
 <refpurpose>
  registered client
 </refpurpose>
</refnamediv>
<refsynopsisdiv>
 <title>Synopsis</title>
  <programlisting>
struct vga_switcheroo_client {
  struct pci_dev * pdev;
  struct fb_info * fb_info;
  enum vga_switcheroo_state pwr_state;
  const struct vga_switcheroo_client_ops * ops;
  enum vga_switcheroo_client_id id;
  bool active;
  bool driver_power_control;
  struct list_head list;
};  </programlisting>
</refsynopsisdiv>
 <refsect1>
  <title>Members</title>
  <variablelist>
    <varlistentry>      <term>pdev</term>
      <listitem><para>
client pci device
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>fb_info</term>
      <listitem><para>
framebuffer to which console is remapped on switching
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>pwr_state</term>
      <listitem><para>
current power state
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>ops</term>
      <listitem><para>
client callbacks
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>id</term>
      <listitem><para>
client identifier. Determining the id requires the handler,
so gpus are initially assigned VGA_SWITCHEROO_UNKNOWN_ID
and later given their true id in <function>vga_switcheroo_enable</function>
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>active</term>
      <listitem><para>
whether the outputs are currently switched to this client
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>driver_power_control</term>
      <listitem><para>
whether power state is controlled by the driver's
runtime pm. If true, writing ON and OFF to the vga_switcheroo debugfs
interface is a no-op so as not to interfere with runtime pm
      </para></listitem>
    </varlistentry>
    <varlistentry>      <term>list</term>
      <listitem><para>
client list
      </para></listitem>
    </varlistentry>
  </variablelist>
 </refsect1>
<refsect1>
<title>Description</title>
<para>
   Registered client. A client can be either a GPU or an audio device on a GPU.
   For audio clients, the <parameter>fb_info</parameter>, <parameter>active</parameter> and <parameter>driver_power_control</parameter> members
   are bogus.
</para>
</refsect1>
</refentry>

  </chapter>

</part>

</book>