[RFC] drm: Start documenting userspace ABI
Daniel Vetter
daniel at ffwll.ch
Tue Nov 18 06:27:27 PST 2014
On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding at nvidia.com>
>
> 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 at nvidia.com>
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 at valinux.com>
> @@ -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
More information about the dri-devel
mailing list