drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB
Subsystems (3)
PATCH 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.
--- Documentation/gpu/drm-kms.rst | 2 ++ include/uapi/drm/drm.h | 15 +++++++++++++++ include/uapi/drm/drm_mode.h | 16 ++++++++++++++-- 3 files changed, 31 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 +15 -0
@@ -1128,6 +1128,21 @@ 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. +*/ #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
@@ -1029,13 +1029,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 76 lines · On Thu, 03 Aug 2023 10:00:44 +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.
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 | 15 +++++++++++++++ include/uapi/drm/drm_mode.h | 16 ++++++++++++++-- 3 files changed, 31 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 +15
-0@@ -1128,6 +1128,21 @@ 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. +*/ #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 +13
-1@@ -1029,13 +1029,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. +*/
include/uapi/drm/drm_mode.h struct drm_mode_crtc_page_flip_target { · line 1053
Quoted 10 lines
include/uapi/drm/drm_mode.h +1
-1struct drm_mode_create_dumb {__u32 height;__u32 width;__u32 bpp;__u32 flags; -/* handle, pitch, size will be returned */ +__u32 handle;__u32 pitch;__u64 size;
Should there be a mention of DRM_CAP_DUMB_PREFER_SHADOW at the ioctl doc too?
DRM_CAP_DUMB_BUFFER?DRM_CAP_DUMB_PREFERRED_DEPTH?
Thanks,
pq