[PATCH v2] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB

[Pekka Paalanen]

On Mon, 21 Aug 2023 13:15:56 +0000
Simon Ser <contact at emersion.fr> wrote:

> The main motivation is to repeat that dumb buffers should not be
> abused for anything else than basic software rendering with KMS.
> User-space devs are more likely to look at the IOCTL docs than to
> actively search for the driver-oriented "Dumb Buffer Objects"
> section.
> 
> v2: reference DRM_CAP_DUMB_BUFFER, DRM_CAP_DUMB_PREFERRED_DEPTH and
> DRM_CAP_DUMB_PREFER_SHADOW (Pekka)
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> Cc: Pekka Paalanen <pekka.paalanen at collabora.com>
> ---
>  Documentation/gpu/drm-kms.rst |  2 ++
>  include/uapi/drm/drm.h        | 19 +++++++++++++++++++
>  include/uapi/drm/drm_mode.h   | 16 ++++++++++++++--
>  3 files changed, 35 insertions(+), 2 deletions(-)

Acked-by: Pekka Paalanen <pekka.paalanen at collabora.com>


Thanks,
pq

> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index c92d425cb2dd..ca9210e47266 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -360,6 +360,8 @@ Format Functions Reference
>  .. kernel-doc:: drivers/gpu/drm/drm_fourcc.c
>     :export:
>  
> +.. _kms_dumb_buffer_objects:
> +
>  Dumb Buffer Objects
>  ===================
>  
> diff --git a/include/uapi/drm/drm.h b/include/uapi/drm/drm.h
> index 794c1d857677..7683c3f23a9b 100644
> --- a/include/uapi/drm/drm.h
> +++ b/include/uapi/drm/drm.h
> @@ -1134,6 +1134,25 @@ extern "C" {
>  #define DRM_IOCTL_MODE_PAGE_FLIP	DRM_IOWR(0xB0, struct drm_mode_crtc_page_flip)
>  #define DRM_IOCTL_MODE_DIRTYFB		DRM_IOWR(0xB1, struct drm_mode_fb_dirty_cmd)
>  
> +/**
> + * DRM_IOCTL_MODE_CREATE_DUMB - Create a new dumb buffer object.
> + *
> + * KMS dumb buffers provide a very primitive way to allocate a buffer object
> + * suitable for scanout and map it for software rendering. KMS dumb buffers are
> + * not suitable for hardware-accelerated rendering nor video decoding. KMS dumb
> + * buffers are not suitable to be displayed without KMS. Also see
> + * :ref:`kms_dumb_buffer_objects`.
> + *
> + * The IOCTL argument is a struct drm_mode_create_dumb.
> + *
> + * User-space is expected to create a KMS dumb buffer via this IOCTL, then add
> + * it as a KMS framebuffer via &DRM_IOCTL_MODE_ADDFB and map it via
> + * &DRM_IOCTL_MODE_MAP_DUMB.
> + *
> + * &DRM_CAP_DUMB_BUFFER indicates whether this IOCTL is supported.
> + * &DRM_CAP_DUMB_PREFERRED_DEPTH and &DRM_CAP_DUMB_PREFER_SHADOW indicate
> + * driver preferences for dumb buffers.
> + */
>  #define DRM_IOCTL_MODE_CREATE_DUMB DRM_IOWR(0xB2, struct drm_mode_create_dumb)
>  #define DRM_IOCTL_MODE_MAP_DUMB    DRM_IOWR(0xB3, struct drm_mode_map_dumb)
>  #define DRM_IOCTL_MODE_DESTROY_DUMB    DRM_IOWR(0xB4, struct drm_mode_destroy_dumb)
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index ea1b639bcb28..128d09138ceb 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -1032,13 +1032,25 @@ struct drm_mode_crtc_page_flip_target {
>  	__u64 user_data;
>  };
>  
> -/* create a dumb scanout buffer */
> +/**
> + * struct drm_mode_create_dumb - Create a KMS dumb buffer for scanout.
> + * @height: buffer height in pixels
> + * @width: buffer width in pixels
> + * @bpp: bits per pixel
> + * @flags: must be zero
> + * @handle: buffer object handle
> + * @pitch: number of bytes between two consecutive lines
> + * @size: size of the whole buffer in bytes
> + *
> + * User-space fills @height, @width, @bpp and @flags. If the IOCTL succeeds,
> + * the kernel fills @handle, @pitch and @size.
> + */
>  struct drm_mode_create_dumb {
>  	__u32 height;
>  	__u32 width;
>  	__u32 bpp;
>  	__u32 flags;
> -	/* handle, pitch, size will be returned */
> +
>  	__u32 handle;
>  	__u32 pitch;
>  	__u64 size;

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20230821/98b21958/attachment.sig>