drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB
Subsystems (3)
PATCH v2 1/1 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)
--- 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(-)
Documentation/gpu/drm-kms.rst +2 -0
@@ -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 +19 -0
@@ -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)
include/uapi/drm/drm_mode.h +14 -2
@@ -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;
Signature · 1 line
2.41.0
Quoted 9 lines · On Mon, 21 Aug 2023 13:15:56 +0000 Simon Ser <[email protected]> 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_DEPTHandDRM_CAP_DUMB_PREFER_SHADOW(Pekka)
Quoted 8 lines
Signed-off-by Simon Ser <[email protected]>Cc Daniel Vetter <[email protected]>Cc Pekka Paalanen <[email protected]>--- 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(-)
Thanks,
pq
Quoted 76 lines
Documentation/gpu/drm-kms.rst +2
-0@@ -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 +19
-0@@ -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)include/uapi/drm/drm_mode.h +14
-2@@ -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;