Re: [RFC] drm: Start documenting userspace ABI

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@xxxxxxxxxx>
> 
> After seeing how the DRM_IOCTL_MODE_CREATE_DUMB was implemented with
> different semantics on different drivers it seems like a good idea to
> start to more rigorously document userspace ABI to avoid these things
> in the future.
> 
> This is a first draft of what such documentation could look like. Not
> all IOCTLs are documented and some explanation about the other system
> calls (mmap(), poll(), read(), ...) would be good too. But I wanted to
> send this out for early review to see if the direction is reasonable.
> If so my plan is to continue to chip away at this as I find time.
> 
> Signed-off-by: Thierry Reding <treding@xxxxxxxxxx>

Imo for ioctls the right thing to do is having proper manpages, not
kerneldoc or DocBook sections. manpages really lend themselves well to
specify all the different facets of a single interface.

Also, we already have some skeleton of that in libdrm, so I think
extending that would be best.
-Daniel

> ---
>  Documentation/DocBook/drm.tmpl | 700 ++++++++++++++++++++++++++++++++++++++++-
>  include/uapi/drm/drm.h         |  95 ++++--
>  2 files changed, 773 insertions(+), 22 deletions(-)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index ffe0d9b41826..bc125c043032 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -3831,8 +3831,706 @@ int num_ioctls;</synopsis>
>  
>    </chapter>
>  </part>
> +<part id="drmABI">
> +  <title>DRM Userspace ABI</title>
> +  <partintro>
> +    <para>
> +      This third part of the DRM Developer's Guide documents userspace
> +      interfaces. DRM devices can be accessed using standard file operations
> +      such as open(), close(), ioctl() or mmap(). How these translate to the
> +      DRM drivers is explained in the following chapters.
> +    </para>
> +    <para>
> +      For driver-specific userspace interfaces (buffer allocation and
> +      management, command stream submission, ...) refer to the driver-specific
> +      sections in <link linkend="drmDrivers" endterm="drmDrivers.title"/>.
> +    </para>
> +  </partintro>
> +  <chapter id="drmIoctl">
> +    <title>DRM IOCTLs</title>
> +    <para>
> +      A number of IOCTLs can be performed on a DRM device node. Many of them
> +      are generic and apply to all devices, others are considered legacy and
> +      should no longer be used in new userspace applications.
> +    </para>
> +    <sect1>
> +      <title>Identification</title>
> +      <sect2>
> +        <title>DRM_IOCTL_VERSION - query driver name and version</title>
> +        <para>
> +          After opening a DRM device, userspace applications will typically
> +          want to identify the driver bound to the device. They can use this
> +          IOCTL to obtain information about the driver in the form of a
> +          <structname>drm_version</structname> structure.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_version
> +        <para>
> +          Returns 0 on success or one of the following error codes on
> +          failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EFAULT</constant></term>
> +            <listitem>
> +              <para>
> +                If data cannot be copied to any of the
> +                <structfield>name</structfield>,
> +                <structfield>date</structfield> or
> +                <structfield>desc</structfield> fields.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_UNIQUE - get unique device name</title>
> +        <para>
> +          Each device has a unique name associated with it. This is useful to
> +          differentiate between two devices driven by the same driver. Unique
> +          names of devices can be obtained with this IOCTL and the result is
> +          returned in a <structname>drm_unique</structname> structure.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_unique
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EFAULT</constant></term>
> +            <listitem>
> +              <para>
> +                If the device's unique name cannot be copied to the
> +                <structfield>unique</structfield> field.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SET_VERSION - request interface version</title>
> +        <para>
> +          Request a specific interface or driver version. The values passed in
> +          the <structname>drm_set_version</structname> structure are matched
> +          against the DRM interface and driver versions.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_set_version
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EINVAL</constant></term>
> +            <listitem>
> +              <para>
> +                If the interface version in the kernel is incompatible with
> +                that requested by the userspace application or if the driver
> +                is not compatible with the version requested by the userspace
> +                application.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_CAP - query device capabilities</title>
> +        <para>
> +          DRM drivers vary in terms of which functionality that they support.
> +          Even within one driver, certain devices may not support the same
> +          functionality as others. The <constant>DRM_IOCTL_GET_CAP</constant>
> +          IOCTL can be used to query such capabilities at runtime.
> +        </para>
> +        <para>
> +          The following is a list of available capabilities. Userspace
> +          applications set the <structfield>capability</structfield> to one of
> +          these before performing the IOCTL. The kernel returns the capability
> +          value in the <structfield>value</structfield> field. Typically this
> +          will be a boolean (0 or 1) value that denotes whether or not the
> +          device supports the given capability. In other cases the returned
> +          value is numerical and the meaning is specified below.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_get_cap
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_DUMB_BUFFER</constant></term>
> +            <listitem>
> +              <para>
> +                The device supports the creation of dumb buffers. Dumb buffers
> +                are typically used for unaccelerated operations. These buffers
> +                can be mapped to userspace so that software can draw into them
> +                and attach them to a CRTC for scanout.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_VBLANK_HIGH_CRTC</constant></term>
> +            <listitem>
> +              <para>
> +                The device is capable of waiting for VBLANK events on all
> +                CRTCs.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_DUMB_PREFERRED_DEPTH</constant></term>
> +            <listitem>
> +              <para>
> +                The preferred pixel bit depth of dumb buffers.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_DUMB_PREFER_SHADOW</constant></term>
> +            <listitem>
> +              <para>
> +                Whether userspace should prefer shadow mode on dumb buffers.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_PRIME</constant></term>
> +            <listitem>
> +              <para>
> +                The device supports DMA-BUF sharing using PRIME. The value
> +                returned is a mask of the following bits:
> +              </para>
> +              <variablelist>
> +                <varlistentry>
> +                  <term><constant>DRM_PRIME_CAP_IMPORT</constant></term>
> +                  <listitem>
> +                    <para>
> +                      The device supports importing DMA-BUF buffers using
> +                      PRIME.
> +                    </para>
> +                  </listitem>
> +                </varlistentry>
> +                <varlistentry>
> +                  <term><constant>DRM_PRIME_CAP_EXPORT</constant></term>
> +                  <listitem>
> +                    <para>
> +                      The device supports exporting DMA-BUF buffers using
> +                      PRIME.
> +                    </para>
> +                  </listitem>
> +                </varlistentry>
> +              </variablelist>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_TIMESTAMP_MONOTONIC</constant></term>
> +            <listitem>
> +              <para>
> +                The timestamp associated with VBLANK events is monotonically
> +                increasing (not influenced by synchronization to external
> +                clocks, such as NTP or RTC, nor leap seconds).
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_ASYNC_PAGE_FLIP</constant></term>
> +            <listitem>
> +              <para>
> +                The device supports asynchronous (i.e. immediate, non-VBLANK
> +                synchronized) page flips.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_CURSOR_WIDTH</constant></term>
> +            <listitem>
> +              <para>
> +                The value returned is a valid width for the hardware cursor.
> +                Hardware-agnostic userspace applications can use this to help
> +                determine the proper size for the hardware cursor.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CAP_CURSOR_HEIGHT</constant></term>
> +            <listitem>
> +              <para>
> +                The value returned is a valid height for the hardware cursor.
> +                Hardware-agnostic userspace applications can use this to help
> +                determine the proper size for the hardware cursor.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EINVAL</constant></term>
> +            <listitem>
> +              <para>
> +                If the value in the <structfield>capability</structfield>
> +                field is not supported.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SET_CLIENT_CAP - advertise client capabilities</title>
> +        <para>
> +          Semantics sometimes change as an interfaces evolves. To preserve
> +          backwards compatibility and still take advantage of new features
> +          userspace can use this IOCTL to advertise its own capabilities.
> +        </para>
> +        <para>
> +          Userspace applications set <structfield>capability</structfield>
> +          and <structfield>value</structfield> appropriately and pass the
> +          <structname>drm_set_client_cap</structname> structure to this
> +          IOCTL. Below is a list of valid capabilities.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_set_client_cap
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>DRM_CLIENT_CAP_STEREO_3D</constant></term>
> +            <listitem>
> +              <para>
> +                The device will expose stereo 3D capabilities of monitors by
> +                advertising the supported 3D layouts in the flags of the
> +                <structname>drm_mode_modeinfo</structname> structure.
> +              </para>
> +              <para>
> +                Valid values are 0 (disable) or 1 (enable).
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>DRM_CLIENT_CAP_UNIVERSAL_PLANES</constant></term>
> +            <listitem>
> +              <para>
> +                The device will expose planes of all types (primary, overlay
> +                and cursor) to userspace, in contrast with the default mode
> +                where only overlay planes are exposed.
> +              </para>
> +              <para>
> +                Valid values are 0 (disable) or 1 (enable).
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EINVAL</constant></term>
> +            <listitem>
> +              <para>
> +                If the value of the <structfield>capability</structfield>
> +                field is not supported or the value in the <structfield>
> +                value</structfield> field is not valid for the capability.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +    </sect1>
> +    <sect1>
> +      <title>Authentication</title>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_MAGIC</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AUTH_MAGIC</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SET_MASTER</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_DROP_MASTER</title>
> +      </sect2>
> +    </sect1>
> +    <sect1>
> +      <title>Buffer Management</title>
> +      <sect2>
> +        <title>DRM_IOCTL_GEM_CLOSE - remove a GEM object</title>
> +        <para>
> +          Removes the handle of a GEM object and drops the handle's reference
> +          to the object. If the handle was holding the last reference, the
> +          GEM object is destroyed.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_gem_close
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>ENODEV</constant></term>
> +            <listitem>
> +              <para>
> +                If the device doesn't support GEM objects.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>EINVAL</constant></term>
> +            <listitem>
> +              <para>
> +                If no GEM object with the specified handle exists.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GEM_FLINK - export a GEM object by name</title>
> +        <para>
> +          Creates a global name for a GEM object.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_gem_flink
> +        <para>
> +          The name does not hold a reference to the object. If a reference is
> +          needed, open the GEM object using the <constant>DRM_IOCTL_GEM_OPEN
> +          </constant> IOCTL.
> +        </para>
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>ENODEV</constant></term>
> +            <listitem>
> +              <para>
> +                If the device doesn't support GEM objects.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>ENOENT</constant></term>
> +            <listitem>
> +              <para>
> +                If no GEM object with the specified handle exists or if it is
> +                in the process of being removed.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GEM_OPEN - open a GEM object by name</title>
> +        <para>
> +          Opens a GEM object by name.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_gem_open
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>ENODEV</constant></term>
> +            <listitem>
> +              <para>
> +                If the device doesn't support GEM objects.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>ENOENT</constant></term>
> +            <listitem>
> +              <para>
> +                If no GEM object with the specified handle exists.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +    </sect1>
> +    <sect1>
> +      <title>DMA-BUF Sharing (PRIME)</title>
> +      <sect2>
> +        <title>DRM_IOCTL_PRIME_HANDLE_TO_FD - export a DMA-BUF buffer</title>
> +        <para>
> +          Exports a buffer object identified by its handle using DMA-BUF. The
> +          file descriptor obtained during this process can be imported into a
> +          different driver supporting DMA-BUF for zero-copy sharing of buffer
> +          content.
> +        </para>
> +        <para>
> +          The only supported flag in the <structfield>flags</structfield>
> +          field is <constant>DMA_CLOEXEC</constant>.
> +        </para>
> +!Finclude/uapi/drm/drm.h drm_prime_handle
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EINVAL</constant></term>
> +            <listitem>
> +              <para>
> +                If the driver does not support buffer sharing using PRIME or
> +                if the flags specified in <structfield>flags</structfield> are
> +                invalid.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>ENOSYS</constant></term>
> +            <listitem>
> +              <para>
> +                If the driver does not support exporting buffers using PRIME.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_PRIME_FD_TO_HANDLE - import a DMA-BUF buffer</title>
> +        <para>
> +          Imports a DMA-BUF buffer identified by its file descriptor. Buffers
> +          imported using this IOCTL are assigned a new handle relative to the
> +          device and can be used like any natively-allocated buffer.
> +        </para>
> +        <para>
> +          Returns 0 on success or one of the following error codes on failure:
> +        </para>
> +        <variablelist>
> +          <varlistentry>
> +            <term><constant>EINVAL</constant></term>
> +            <listitem>
> +              <para>
> +                If the driver does not support buffer sharing using PRIME.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +          <varlistentry>
> +            <term><constant>ENOSYS</constant></term>
> +            <listitem>
> +              <para>
> +                If the driver does not support importing buffers using PRIME.
> +              </para>
> +            </listitem>
> +          </varlistentry>
> +        </variablelist>
> +      </sect2>
> +    </sect1>
> +    <sect1>
> +      <title>Modesetting</title>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETRESOURCES</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETCRTC</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_SETCRTC</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_CURSOR</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETGAMMA</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_SETGAMMA</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETENCODER</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETCONNECTOR</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_ATTACHMODE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_DETACHMODE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETPROPERTY</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_SETPROPERTY</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETPROPBLOB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETFB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_ADDFB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_RMFB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_PAGE_FLIP</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_DIRTYFB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_CREATE_DUMB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_MAP_DUMB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_DESTROY_DUMB</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETPLANERESOURCES</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_GETPLANE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_SETPLANE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_ADDFB2</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_OBJ_GETPROPERTIES</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_OBJ_SETPROPERTY</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODE_CURSOR2</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_WAIT_VBLANK</title>
> +      </sect2>
> +    </sect1>
> +    <sect1>
> +      <title>Legacy IOCTLs</title>
> +      <sect2>
> +        <title>DRM_IOCTL_SET_UNIQUE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_IRQ_BUSID</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_MAP</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_CLIENT</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_STATS</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MODESET_CTL</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_BLOCK</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_UNBLOCK</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_CONTROL</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_ADD_MAP</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_ADD_BUFS</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MARK_BUFS</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_INFO_BUFS</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MAP_BUFS</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_FREE_BUFS</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_RM_MAP</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SET_SAREA_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_SAREA_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_ADD_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_RM_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_MOD_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_GET_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SWITCH_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_NEW_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_RES_CTX</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_ADD_DRAW</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_RM_DRAW</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_DMA</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_LOCK</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_UNLOCK</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_FINISH</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_ACQUIRE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_RELEASE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_ENABLE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_INFO</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_ALLOC</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_FREE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_BIND</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_AGP_UNBIND</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SG_ALLOC</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_SG_FREE</title>
> +      </sect2>
> +      <sect2>
> +        <title>DRM_IOCTL_UPDATE_DRAW</title>
> +      </sect2>
> +    </sect1>
> +  </chapter>
> +</part>
>  <part id="drmDrivers">
> -  <title>DRM Drivers</title>
> +  <title id="drmDrivers.title">DRM Drivers</title>
>  
>    <partintro>
>      <para>
> diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
> index b0b855613641..ec533ea74324 100644
> --- a/include/uapi/drm/drm.h
> +++ b/include/uapi/drm/drm.h
> @@ -1,5 +1,4 @@
>  /**
> - * \file drm.h
>   * Header for the Direct Rendering Manager
>   *
>   * \author Rickard E. (Rik) Faith <faith@xxxxxxxxxxx>
> @@ -121,9 +120,24 @@ struct drm_hw_lock {
>  };
>  
>  /**
> - * DRM_IOCTL_VERSION ioctl argument type.
> + * struct drm_version - DRM_IOCTL_VERSION IOCTL argument type
> + * @version_major: major version
> + * @version_minor: minor version
> + * @version_patchlevel: patch level
> + * @name_len: length of name buffer
> + * @name: driver name
> + * @date_len: length of date buffer
> + * @date: driver date
> + * @desc_len: length of description buffer
> + * @desc: driver description
>   *
> - * \sa drmGetVersion().
> + * The @name, @date and @desc fields must point to buffers allocated by the
> + * userspace application. Only @name_len, @date_len or @desc_len characters
> + * will be written into these buffers, so the strings may be truncated. The
> + * kernel sets the @name_len, @date_len and @desc_len fields to the actual
> + * lengths of the strings upon return (not inccluding the terminating NUL
> + * character). Userspace can call this IOCTL with all lengths set to 0 (and
> + * buffers to NULL) to determine the exact size of the buffers to allocate.
>   */
>  struct drm_version {
>  	int version_major;	  /**< Major version */
> @@ -138,9 +152,17 @@ struct drm_version {
>  };
>  
>  /**
> - * DRM_IOCTL_GET_UNIQUE ioctl argument type.
> + * struct drm_unique - DRM_IOCTL_GET_UNIQUE IOCTL argument type
> + * @unique_len: length of unique name for driver instantiation
> + * @unique: unique name for driver instantiation
>   *
> - * \sa drmGetBusid() and drmSetBusId().
> + * The @unique field must point to a buffer allocated by the userspace
> + * application. If the @unique_len field is less than the actual size of the
> + * unique name of the device, the kernel will not fill the @unique field but
> + * return the actual size in @unique_len instead. Userspace applications
> + * will typically perform the IOCTL once with @unique_len and @unique set to
> + * 0 and NULL, respectively, allocate a buffer using the returned length and
> + * perform the IOCTL again with the properly sized buffer.
>   */
>  struct drm_unique {
>  	size_t unique_len;	  /**< Length of unique */
> @@ -573,7 +595,11 @@ struct drm_scatter_gather {
>  };
>  
>  /**
> - * DRM_IOCTL_SET_VERSION ioctl argument type.
> + * struct drm_set_version - DRM_IOCTL_SET_VERSION IOCTL argument type
> + * @drm_di_major: DRM interface major version
> + * @drm_di_minor: DRM interface minor version
> + * @drm_dd_major: DRM driver major version
> + * @drm_dd_minor: DRM driver minor version
>   */
>  struct drm_set_version {
>  	int drm_di_major;
> @@ -582,14 +608,21 @@ struct drm_set_version {
>  	int drm_dd_minor;
>  };
>  
> -/** DRM_IOCTL_GEM_CLOSE ioctl argument type */
> +/**
> + * struct drm_gem_close - DRM_IOCTL_GEM_CLOSE IOCTL argument type
> + * @handle: handle of object to close
> + * @pad: padding for 64-bit alignment
> + */
>  struct drm_gem_close {
> -	/** Handle of the object to be closed. */
>  	__u32 handle;
>  	__u32 pad;
>  };
>  
> -/** DRM_IOCTL_GEM_FLINK ioctl argument type */
> +/**
> + * struct drm_gem_flink - DRM_IOCTL_GEM_FLINK IOCTL argument type
> + * @handle: handle of object to export
> + * @name: returned object name
> + */
>  struct drm_gem_flink {
>  	/** Handle for the object being named */
>  	__u32 handle;
> @@ -598,15 +631,15 @@ struct drm_gem_flink {
>  	__u32 name;
>  };
>  
> -/** DRM_IOCTL_GEM_OPEN ioctl argument type */
> +/**
> + * struct drm_gem_open - DRM_IOCTL_GEM_OPEN IOCTL argument type
> + * @name: name of the object being opened
> + * @handle: returned object handle
> + * @size: returned object size
> + */
>  struct drm_gem_open {
> -	/** Name of object being opened */
>  	__u32 name;
> -
> -	/** Returned handle for the object */
>  	__u32 handle;
> -
> -	/** Returned size of the object */
>  	__u64 size;
>  };
>  
> @@ -631,7 +664,11 @@ struct drm_gem_open {
>  #define DRM_CAP_CURSOR_WIDTH		0x8
>  #define DRM_CAP_CURSOR_HEIGHT		0x9
>  
> -/** DRM_IOCTL_GET_CAP ioctl argument type */
> +/**
> + * struct drm_get_cap - DRM_IOCTL_GET_CAP IOCTL argument type
> + * @capability: device/driver capability to query
> + * @value: return location for the value
> + */
>  struct drm_get_cap {
>  	__u64 capability;
>  	__u64 value;
> @@ -654,20 +691,36 @@ struct drm_get_cap {
>   */
>  #define DRM_CLIENT_CAP_UNIVERSAL_PLANES  2
>  
> -/** DRM_IOCTL_SET_CLIENT_CAP ioctl argument type */
> +/**
> + * struct drm_set_client_cap - DRM_IOCTL_SET_CLIENT_CAP IOCTL argument type
> + * @capability: client capability
> + * @value: capability value
> + */
>  struct drm_set_client_cap {
>  	__u64 capability;
>  	__u64 value;
>  };
>  
>  #define DRM_CLOEXEC O_CLOEXEC
> +
> +/**
> + * struct drm_prime_handle - DRM_IOCTL_PRIME_* IOCTL argument type
> + * @handle: buffer object handle
> + * @flags: export flags (only applicable for DRM_IOCTL_PRIME_HANDLE_TO_FD)
> + * @fd: DMA-BUF file descriptor
> + *
> + * For DRM_IOCTL_PRIME_HANDLE_TO_FD (export) the @handle is passed in along
> + * with a set of @flags (only DRM_CLOEXEC is currently valid). Upon return the
> + * @fd field contains a file descriptor that can be used to import the buffer
> + * into another driver.
> + *
> + * For DRM_IOCTL_PRIME_FD_TO_HANDLE (import) the file descriptor corresponding
> + * to the buffer that is to be imported is specified in @fd. Upon return the
> + * @handle field contains a device-local handle to the imported buffer object.
> + */
>  struct drm_prime_handle {
>  	__u32 handle;
> -
> -	/** Flags.. only applicable for handle->fd */
>  	__u32 flags;
> -
> -	/** Returned dmabuf file descriptor */
>  	__s32 fd;
>  };
>  
> -- 
> 2.1.3
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@xxxxxxxxxxxxxxxxxxxxx
http://lists.freedesktop.org/mailman/listinfo/dri-devel





[Index of Archives]     [Linux DRI Users]     [Linux Intel Graphics]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]
  Powered by Linux