| Message ID | 20230821131548.269204-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB | expand |
On Mon, 21 Aug 2023 13:15:56 +0000 Simon Ser <contact@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@emersion.fr> > Cc: Daniel Vetter <daniel.vetter@ffwll.ch> > Cc: Pekka Paalanen <pekka.paalanen@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@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;
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;
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@emersion.fr> Cc: Daniel Vetter <daniel.vetter@ffwll.ch> Cc: Pekka Paalanen <pekka.paalanen@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(-)