Commit b8644c4a authored by Simon Ser's avatar Simon Ser
Browse files

drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB 



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: default avatarSimon Ser <contact@emersion.fr>
Acked-by: default avatarDaniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: default avatarPekka Paalanen <pekka.paalanen@collabora.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230821131548.269204-1-contact@emersion.fr
parent d4b38422

Documentation/gpu/drm-kms.rst

+2 −0
Original line number Diff line number Diff line
@@ -360,6 +360,8 @@ Format Functions Reference 
.. kernel-doc:: drivers/gpu/drm/drm_fourcc.c

   :export:



.. _kms_dumb_buffer_objects:



Dumb Buffer Objects

===================

include/uapi/drm/drm.h

+20 −0
Original line number Diff line number Diff line
@@ -1134,6 +1134,26 @@ 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 on any other device than the KMS

 * device where they were allocated from. 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)

include/uapi/drm/drm_mode.h

+14 −2
Original line number Diff line number Diff line
@@ -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;