drm: Consolidate dumb buffer docs

Put the callback docs into struct drm_driver, and the small overview
into a DOC comment.

Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20161114115825.22050-7-daniel.vetter@ffwll.ch

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index cb0d3537b70592ec0a9de6445e4d98f85303af32..4edfb6d912501d9e4019d2edb11c6cefafabc2ef 100644 (file)
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -72,46 +72,8 @@ DRM Format Handling
 Dumb Buffer Objects
 ===================
 
-The KMS API doesn't standardize backing storage object creation and
-leaves it to driver-specific ioctls. Furthermore actually creating a
-buffer object even for GEM-based drivers is done through a
-driver-specific ioctl - GEM only has a common userspace interface for
-sharing and destroying objects. While not an issue for full-fledged
-graphics stacks that include device-specific userspace components (in
-libdrm for instance), this limit makes DRM-based early boot graphics
-unnecessarily complex.
-
-Dumb objects partly alleviate the problem by providing a standard API to
-create dumb buffers suitable for scanout, which can then be used to
-create KMS frame buffers.
-
-To support dumb objects drivers must implement the dumb_create,
-dumb_destroy and dumb_map_offset operations.
-
--  int (\*dumb_create)(struct drm_file \*file_priv, struct
-   drm_device \*dev, struct drm_mode_create_dumb \*args);
-   The dumb_create operation creates a driver object (GEM or TTM
-   handle) suitable for scanout based on the width, height and depth
-   from the struct :c:type:`struct drm_mode_create_dumb
-   <drm_mode_create_dumb>` argument. It fills the argument's
-   handle, pitch and size fields with a handle for the newly created
-   object and its line pitch and size in bytes.
-
--  int (\*dumb_destroy)(struct drm_file \*file_priv, struct
-   drm_device \*dev, uint32_t handle);
-   The dumb_destroy operation destroys a dumb object created by
-   dumb_create.
-
--  int (\*dumb_map_offset)(struct drm_file \*file_priv, struct
-   drm_device \*dev, uint32_t handle, uint64_t \*offset);
-   The dumb_map_offset operation associates an mmap fake offset with
-   the object given by the handle and returns it. Drivers must use the
-   :c:func:`drm_gem_create_mmap_offset()` function to associate
-   the fake offset as described in ?.
-
-Note that dumb objects may not be used for gpu acceleration, as has been
-attempted on some ARM embedded platforms. Such drivers really must have
-a hardware-specific ioctl to allocate suitable buffer objects.
+.. kernel-doc:: drivers/gpu/drm/drm_dumb_buffers.c
+   :doc: overview
 
 Plane Abstraction
 =================

diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
index cd291b538f5aaebe1606d3849b9b89817666ff2b..8ac5a1c1d8111716e9871e8a5313f649cc0e370b 100644 (file)
--- a/drivers/gpu/drm/drm_dumb_buffers.c
+++ b/drivers/gpu/drm/drm_dumb_buffers.c
@@ -28,24 +28,29 @@
 #include "drm_crtc_internal.h"
 
 /**
- * drm_mode_create_dumb_ioctl - create a dumb backing storage buffer
- * @dev: DRM device
- * @data: ioctl data
- * @file_priv: DRM file info
+ * DOC: overview
  *
- * This creates a new dumb buffer in the driver's backing storage manager (GEM,
- * TTM or something else entirely) and returns the resulting buffer handle. This
- * handle can then be wrapped up into a framebuffer modeset object.
+ * The KMS API doesn't standardize backing storage object creation and leaves it
+ * to driver-specific ioctls. Furthermore actually creating a buffer object even
+ * for GEM-based drivers is done through a driver-specific ioctl - GEM only has
+ * a common userspace interface for sharing and destroying objects. While not an
+ * issue for full-fledged graphics stacks that include device-specific userspace
+ * components (in libdrm for instance), this limit makes DRM-based early boot
+ * graphics unnecessarily complex.
  *
- * Note that userspace is not allowed to use such objects for render
- * acceleration - drivers must create their own private ioctls for such a use
- * case.
+ * Dumb objects partly alleviate the problem by providing a standard API to
+ * create dumb buffers suitable for scanout, which can then be used to create
+ * KMS frame buffers.
  *
- * Called by the user via ioctl.
+ * To support dumb objects drivers must implement the dumb_create,
+ * dumb_destroy and dumb_map_offset operations from struct &drm_driver. See
+ * there for further details.
  *
- * Returns:
- * Zero on success, negative errno on failure.
+ * Note that dumb objects may not be used for gpu acceleration, as has been
+ * attempted on some ARM embedded platforms. Such drivers really must have
+ * a hardware-specific ioctl to allocate suitable buffer objects.
  */
+
 int drm_mode_create_dumb_ioctl(struct drm_device *dev,
                               void *data, struct drm_file *file_priv)
 {
@@ -110,21 +115,6 @@ int drm_mode_mmap_dumb_ioctl(struct drm_device *dev,
        return dev->driver->dumb_map_offset(file_priv, dev, args->handle, &args->offset);
 }
 
-/**
- * drm_mode_destroy_dumb_ioctl - destroy a dumb backing strage buffer
- * @dev: DRM device
- * @data: ioctl data
- * @file_priv: DRM file info
- *
- * This destroys the userspace handle for the given dumb backing storage buffer.
- * Since buffer objects must be reference counted in the kernel a buffer object
- * won't be immediately freed if a framebuffer modeset object still uses it.
- *
- * Called by the user via ioctl.
- *
- * Returns:
- * Zero on success, negative errno on failure.
- */
 int drm_mode_destroy_dumb_ioctl(struct drm_device *dev,
                                void *data, struct drm_file *file_priv)
 {

diff --git a/include/drm/drm_drv.h b/include/drm/drm_drv.h
index 048086e38ef68c46ba6ed0b7df47b36afcc73d77..aad8bbacd1f0ff100f6a8c61a49b762ab4cdd41d 100644 (file)
--- a/include/drm/drm_drv.h
+++ b/include/drm/drm_drv.h
@@ -328,13 +328,59 @@ struct drm_driver {
        /* vga arb irq handler */
        void (*vgaarb_irq)(struct drm_device *dev, bool state);
 
-       /* dumb alloc support */
+       /**
+        * @dumb_create:
+        *
+        * This creates a new dumb buffer in the driver's backing storage manager (GEM,
+        * TTM or something else entirely) and returns the resulting buffer handle. This
+        * handle can then be wrapped up into a framebuffer modeset object.
+        *
+        * Note that userspace is not allowed to use such objects for render
+        * acceleration - drivers must create their own private ioctls for such a use
+        * case.
+        *
+        * Width, height and depth are specified in the &drm_mode_create_dumb
+        * argument. The callback needs to fill the handle, pitch and size for
+        * the created buffer.
+        *
+        * Called by the user via ioctl.
+        *
+        * Returns:
+        *
+        * Zero on success, negative errno on failure.
+        */
        int (*dumb_create)(struct drm_file *file_priv,
                           struct drm_device *dev,
                           struct drm_mode_create_dumb *args);
+       /**
+        * @dumb_map_offset:
+        *
+        * Allocate an offset in the drm device node's address space to be able to
+        * memory map a dumb buffer. GEM-based drivers must use
+        * drm_gem_create_mmap_offset() to implement this.
+        *
+        * Called by the user via ioctl.
+        *
+        * Returns:
+        *
+        * Zero on success, negative errno on failure.
+        */
        int (*dumb_map_offset)(struct drm_file *file_priv,
                               struct drm_device *dev, uint32_t handle,
                               uint64_t *offset);
+       /**
+        * @dumb_destroy:
+        *
+        * This destroys the userspace handle for the given dumb backing storage buffer.
+        * Since buffer objects must be reference counted in the kernel a buffer object
+        * won't be immediately freed if a framebuffer modeset object still uses it.
+        *
+        * Called by the user via ioctl.
+        *
+        * Returns:
+        *
+        * Zero on success, negative errno on failure.
+        */
        int (*dumb_destroy)(struct drm_file *file_priv,
                            struct drm_device *dev,
                            uint32_t handle);