* [RFC] drm: Start documenting userspace ABI
@ 2014-11-18 14:19 Thierry Reding
2014-11-18 14:27 ` Daniel Vetter
0 siblings, 1 reply; 7+ messages in thread
From: Thierry Reding @ 2014-11-18 14:19 UTC (permalink / raw)
To: dri-devel; +Cc: Daniel Vetter, Laurent Pinchart
From: Thierry Reding <treding@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@nvidia.com>
---
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@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
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [RFC] drm: Start documenting userspace ABI
2014-11-18 14:19 [RFC] drm: Start documenting userspace ABI Thierry Reding
@ 2014-11-18 14:27 ` Daniel Vetter
2014-11-18 14:43 ` Thierry Reding
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Vetter @ 2014-11-18 14:27 UTC (permalink / raw)
To: Thierry Reding; +Cc: Daniel Vetter, Laurent Pinchart, dri-devel
On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@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@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@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
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [RFC] drm: Start documenting userspace ABI
2014-11-18 14:27 ` Daniel Vetter
@ 2014-11-18 14:43 ` Thierry Reding
2014-11-18 15:05 ` David Herrmann
0 siblings, 1 reply; 7+ messages in thread
From: Thierry Reding @ 2014-11-18 14:43 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Laurent Pinchart, dri-devel
[-- Attachment #1.1: Type: text/plain, Size: 2121 bytes --]
On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote:
> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> > From: Thierry Reding <treding@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@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.
I don't think I've ever seen manpages document IOCTLs at this level of
detail. The intention of this is to add documentation about the IOCTLs
at the kernel/userspace transition. Keeping this in the kernel has the
advantage that it's a whole lot easier to keep updated, much like what
we do with the other kerneldoc.
That doesn't mean we shouldn't have manpages, but I think both are for
the most part orthogonal, even though they may describe various facets
of the same interfaces.
> Also, we already have some skeleton of that in libdrm, so I think
> extending that would be best.
One other reason why I don't think libdrm is the best fit for this is
that libdrm is just one userspace implementation abstracting away the
interfaces that this describes. Not everyone will use libdrm. So in my
opinion its great if libdrm documents the API that it exposes, but I
don't think it should document the kernel interfaces that it uses. The
kernel exposes them, so it should provide the documentation for it as
well.
Thierry
[-- Attachment #1.2: Type: application/pgp-signature, Size: 819 bytes --]
[-- Attachment #2: Type: text/plain, Size: 159 bytes --]
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [RFC] drm: Start documenting userspace ABI
2014-11-18 14:43 ` Thierry Reding
@ 2014-11-18 15:05 ` David Herrmann
2014-11-18 15:24 ` Thierry Reding
0 siblings, 1 reply; 7+ messages in thread
From: David Herrmann @ 2014-11-18 15:05 UTC (permalink / raw)
To: Thierry Reding; +Cc: Daniel Vetter, Laurent Pinchart, dri-devel
Hi
On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding
<thierry.reding@gmail.com> wrote:
> On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote:
>> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
>> > From: Thierry Reding <treding@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@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.
>
> I don't think I've ever seen manpages document IOCTLs at this level of
> detail. The intention of this is to add documentation about the IOCTLs
> at the kernel/userspace transition. Keeping this in the kernel has the
> advantage that it's a whole lot easier to keep updated, much like what
> we do with the other kerneldoc.
>
> That doesn't mean we shouldn't have manpages, but I think both are for
> the most part orthogonal, even though they may describe various facets
> of the same interfaces.
tty_ioctl(4)
console_ioctl(4)
I think a similar man-page ala drm_ioctl(4) makes a lot of sense.
>> Also, we already have some skeleton of that in libdrm, so I think
>> extending that would be best.
>
> One other reason why I don't think libdrm is the best fit for this is
> that libdrm is just one userspace implementation abstracting away the
> interfaces that this describes. Not everyone will use libdrm. So in my
> opinion its great if libdrm documents the API that it exposes, but I
> don't think it should document the kernel interfaces that it uses. The
> kernel exposes them, so it should provide the documentation for it as
> well.
I don't mind documenting this in the kernel-doc. But if we start
something like drm_ioctl(4) (I pushed some more generic man-pages to
libdrm a few years ago), we have this documented in 2 places, which is
always annoying for updates.
And even if people don't use libdrm, I think it's totally acceptable
to ship man-pages with libdrm. Distributions are free to provide
drm-man-pages as stand-alone package (which is _really_ easy to
generate from libdrm).
Thanks
David
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [RFC] drm: Start documenting userspace ABI
2014-11-18 15:05 ` David Herrmann
@ 2014-11-18 15:24 ` Thierry Reding
2014-11-19 13:23 ` Daniel Vetter
0 siblings, 1 reply; 7+ messages in thread
From: Thierry Reding @ 2014-11-18 15:24 UTC (permalink / raw)
To: David Herrmann; +Cc: Daniel Vetter, Laurent Pinchart, dri-devel
[-- Attachment #1.1: Type: text/plain, Size: 4059 bytes --]
On Tue, Nov 18, 2014 at 04:05:08PM +0100, David Herrmann wrote:
> Hi
>
> On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding
> <thierry.reding@gmail.com> wrote:
> > On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote:
> >> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> >> > From: Thierry Reding <treding@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@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.
> >
> > I don't think I've ever seen manpages document IOCTLs at this level of
> > detail. The intention of this is to add documentation about the IOCTLs
> > at the kernel/userspace transition. Keeping this in the kernel has the
> > advantage that it's a whole lot easier to keep updated, much like what
> > we do with the other kerneldoc.
> >
> > That doesn't mean we shouldn't have manpages, but I think both are for
> > the most part orthogonal, even though they may describe various facets
> > of the same interfaces.
>
> tty_ioctl(4)
> console_ioctl(4)
>
> I think a similar man-page ala drm_ioctl(4) makes a lot of sense.
>
> >> Also, we already have some skeleton of that in libdrm, so I think
> >> extending that would be best.
> >
> > One other reason why I don't think libdrm is the best fit for this is
> > that libdrm is just one userspace implementation abstracting away the
> > interfaces that this describes. Not everyone will use libdrm. So in my
> > opinion its great if libdrm documents the API that it exposes, but I
> > don't think it should document the kernel interfaces that it uses. The
> > kernel exposes them, so it should provide the documentation for it as
> > well.
>
> I don't mind documenting this in the kernel-doc. But if we start
> something like drm_ioctl(4) (I pushed some more generic man-pages to
> libdrm a few years ago), we have this documented in 2 places, which is
> always annoying for updates.
I wonder if it would somehow be possible to generate manpages from the
DocBook to avoid this duplication. One of the things that
DRM_IOCTL_MODE_CREATE_DUMB showed is that both drivers and userspace can
interpret things wrongly, and I fear that if all we have is a manpage to
document the IOCTLs, people writing the drivers may not be tempted
enough to read that manpage. So I think we want documentation for both
driver and userspace developers.
Documenting this within the kernel is also pretty easy. I know that I'll
be much more tempted to do it within the kernel than if I have to switch
to some other repository, build system and whatnot.
Perhaps in this case having two places where it's documented isn't all
that bad. It's ABI after all, so the documentation never needs to
change. Theoretically.
> And even if people don't use libdrm, I think it's totally acceptable
> to ship man-pages with libdrm. Distributions are free to provide
> drm-man-pages as stand-alone package (which is _really_ easy to
> generate from libdrm).
I guess one other home for these could be the man-pages project on
kernel.org. It's what carries most (all?) of the Linux kernel-specific
man-pages (like the tty_ioctl and console_ioctl ones that you referred
to).
Thierry
[-- Attachment #1.2: Type: application/pgp-signature, Size: 819 bytes --]
[-- Attachment #2: Type: text/plain, Size: 159 bytes --]
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [RFC] drm: Start documenting userspace ABI
2014-11-18 15:24 ` Thierry Reding
@ 2014-11-19 13:23 ` Daniel Vetter
2014-12-01 1:32 ` Laurent Pinchart
0 siblings, 1 reply; 7+ messages in thread
From: Daniel Vetter @ 2014-11-19 13:23 UTC (permalink / raw)
To: Thierry Reding; +Cc: Daniel Vetter, Laurent Pinchart, dri-devel
On Tue, Nov 18, 2014 at 04:24:39PM +0100, Thierry Reding wrote:
> On Tue, Nov 18, 2014 at 04:05:08PM +0100, David Herrmann wrote:
> > Hi
> >
> > On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding
> > <thierry.reding@gmail.com> wrote:
> > > On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote:
> > >> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> > >> > From: Thierry Reding <treding@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@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.
> > >
> > > I don't think I've ever seen manpages document IOCTLs at this level of
> > > detail. The intention of this is to add documentation about the IOCTLs
> > > at the kernel/userspace transition. Keeping this in the kernel has the
> > > advantage that it's a whole lot easier to keep updated, much like what
> > > we do with the other kerneldoc.
> > >
> > > That doesn't mean we shouldn't have manpages, but I think both are for
> > > the most part orthogonal, even though they may describe various facets
> > > of the same interfaces.
> >
> > tty_ioctl(4)
> > console_ioctl(4)
> >
> > I think a similar man-page ala drm_ioctl(4) makes a lot of sense.
> >
> > >> Also, we already have some skeleton of that in libdrm, so I think
> > >> extending that would be best.
> > >
> > > One other reason why I don't think libdrm is the best fit for this is
> > > that libdrm is just one userspace implementation abstracting away the
> > > interfaces that this describes. Not everyone will use libdrm. So in my
> > > opinion its great if libdrm documents the API that it exposes, but I
> > > don't think it should document the kernel interfaces that it uses. The
> > > kernel exposes them, so it should provide the documentation for it as
> > > well.
> >
> > I don't mind documenting this in the kernel-doc. But if we start
> > something like drm_ioctl(4) (I pushed some more generic man-pages to
> > libdrm a few years ago), we have this documented in 2 places, which is
> > always annoying for updates.
>
> I wonder if it would somehow be possible to generate manpages from the
> DocBook to avoid this duplication. One of the things that
> DRM_IOCTL_MODE_CREATE_DUMB showed is that both drivers and userspace can
> interpret things wrongly, and I fear that if all we have is a manpage to
> document the IOCTLs, people writing the drivers may not be tempted
> enough to read that manpage. So I think we want documentation for both
> driver and userspace developers.
Imo docs don't help with that kind of fumble, only nasty testcases will.
People only read docs when they don't understand stuff (i.e. trying to
write drivers). Imo manpages an ioctl docs are only really good for
designing the interface (since it forces you to really think through the
semantics to be able to describe them concisely and precisely). But even
there I think having solid testcases is better invested time.
Documentation for developers is imo an entirely different matter, I think
that gets used a lot more. Or at least I find them fairly useful.
> Documenting this within the kernel is also pretty easy. I know that I'll
> be much more tempted to do it within the kernel than if I have to switch
> to some other repository, build system and whatnot.
>
> Perhaps in this case having two places where it's documented isn't all
> that bad. It's ABI after all, so the documentation never needs to
> change. Theoretically.
>
> > And even if people don't use libdrm, I think it's totally acceptable
> > to ship man-pages with libdrm. Distributions are free to provide
> > drm-man-pages as stand-alone package (which is _really_ easy to
> > generate from libdrm).
>
> I guess one other home for these could be the man-pages project on
> kernel.org. It's what carries most (all?) of the Linux kernel-specific
> man-pages (like the tty_ioctl and console_ioctl ones that you referred
> to).
There has been talks about merging the linux manpages back into the kernel
actually. But yeah that seems like a good home, especially since Micheal
Kerrisk seems pretty sharp with reviewing manpages.
-Daniel
--
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [RFC] drm: Start documenting userspace ABI
2014-11-19 13:23 ` Daniel Vetter
@ 2014-12-01 1:32 ` Laurent Pinchart
0 siblings, 0 replies; 7+ messages in thread
From: Laurent Pinchart @ 2014-12-01 1:32 UTC (permalink / raw)
To: Daniel Vetter; +Cc: Daniel Vetter, Laurent Pinchart, dri-devel
On Wednesday 19 November 2014 14:23:47 Daniel Vetter wrote:
> On Tue, Nov 18, 2014 at 04:24:39PM +0100, Thierry Reding wrote:
> > On Tue, Nov 18, 2014 at 04:05:08PM +0100, David Herrmann wrote:
> > > On Tue, Nov 18, 2014 at 3:43 PM, Thierry Reding wrote:
> > > > On Tue, Nov 18, 2014 at 03:27:27PM +0100, Daniel Vetter wrote:
> > > >> On Tue, Nov 18, 2014 at 03:19:33PM +0100, Thierry Reding wrote:
> > > >> > From: Thierry Reding <treding@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@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.
> > > >
> > > > I don't think I've ever seen manpages document IOCTLs at this level of
> > > > detail. The intention of this is to add documentation about the IOCTLs
> > > > at the kernel/userspace transition. Keeping this in the kernel has the
> > > > advantage that it's a whole lot easier to keep updated, much like what
> > > > we do with the other kerneldoc.
> > > >
> > > > That doesn't mean we shouldn't have manpages, but I think both are for
> > > > the most part orthogonal, even though they may describe various facets
> > > > of the same interfaces.
> > >
> > > tty_ioctl(4)
> > > console_ioctl(4)
> > >
> > > I think a similar man-page ala drm_ioctl(4) makes a lot of sense.
The DRM API is much more complex, I think it deserves one page per ioctl.
> > > >> Also, we already have some skeleton of that in libdrm, so I think
> > > >> extending that would be best.
> > > >
> > > > One other reason why I don't think libdrm is the best fit for this is
> > > > that libdrm is just one userspace implementation abstracting away the
> > > > interfaces that this describes. Not everyone will use libdrm. So in my
> > > > opinion its great if libdrm documents the API that it exposes, but I
> > > > don't think it should document the kernel interfaces that it uses. The
> > > > kernel exposes them, so it should provide the documentation for it as
> > > > well.
> > >
> > > I don't mind documenting this in the kernel-doc. But if we start
> > > something like drm_ioctl(4) (I pushed some more generic man-pages to
> > > libdrm a few years ago), we have this documented in 2 places, which is
> > > always annoying for updates.
> >
> > I wonder if it would somehow be possible to generate manpages from the
> > DocBook to avoid this duplication.
I'm pretty sure that should be possible. DocBook has appropriate markup to
document functions in a manpage-like manner, see
http://linuxtv.org/downloads/v4l-dvb-apis/vidioc-reqbufs.html for instance.
> > One of the things that DRM_IOCTL_MODE_CREATE_DUMB showed is that both
> > drivers and userspace can interpret things wrongly, and I fear that if all
> > we have is a manpage to document the IOCTLs, people writing the drivers
> > may not be tempted enough to read that manpage. So I think we want
> > documentation for both driver and userspace developers.
>
> Imo docs don't help with that kind of fumble, only nasty testcases will.
> People only read docs when they don't understand stuff (i.e. trying to
> write drivers). Imo manpages an ioctl docs are only really good for
> designing the interface (since it forces you to really think through the
> semantics to be able to describe them concisely and precisely). But even
> there I think having solid testcases is better invested time.
>
> Documentation for developers is imo an entirely different matter, I think
> that gets used a lot more. Or at least I find them fairly useful.
I think both are useful. From my personal experience proper detailed ioctl
documentation helps a lots when writing kernel drivers. Even in the case of
the DRM subsystem where various helper functions push the driver away from the
ioctl API, proper documentation of the structures passed by userspace is very
helpful for driver developers. Not to mention of course that the
documentation helps getting the helpers right.
Test cases are also invaluable. I've seen both test cases being used to fix
drivers and documentation, clarifying the API as they get developed.
Implementing a test case is a very good way to test the maturity of an API.
> > Documenting this within the kernel is also pretty easy. I know that I'll
> > be much more tempted to do it within the kernel than if I have to switch
> > to some other repository, build system and whatnot.
I agree. Having code and documentation close to each other will benefit both.
> > Perhaps in this case having two places where it's documented isn't all
> > that bad. It's ABI after all, so the documentation never needs to
> > change. Theoretically.
> >
> > > And even if people don't use libdrm, I think it's totally acceptable
> > > to ship man-pages with libdrm. Distributions are free to provide
> > > drm-man-pages as stand-alone package (which is _really_ easy to
> > > generate from libdrm).
> >
> > I guess one other home for these could be the man-pages project on
> > kernel.org. It's what carries most (all?) of the Linux kernel-specific
> > man-pages (like the tty_ioctl and console_ioctl ones that you referred
> > to).
>
> There has been talks about merging the linux manpages back into the kernel
> actually. But yeah that seems like a good home, especially since Micheal
> Kerrisk seems pretty sharp with reviewing manpages.
--
Regards,
Laurent Pinchart
_______________________________________________
dri-devel mailing list
dri-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/dri-devel
^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2014-12-01 1:31 UTC | newest]
Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2014-11-18 14:19 [RFC] drm: Start documenting userspace ABI Thierry Reding
2014-11-18 14:27 ` Daniel Vetter
2014-11-18 14:43 ` Thierry Reding
2014-11-18 15:05 ` David Herrmann
2014-11-18 15:24 ` Thierry Reding
2014-11-19 13:23 ` Daniel Vetter
2014-12-01 1:32 ` Laurent Pinchart
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.