On Thu, 03 Aug 2023 10:00:44 +0000 Simon Ser <contact@xxxxxxxxxxx> 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 <contact@xxxxxxxxxxx> > Cc: Daniel Vetter <daniel.vetter@xxxxxxxx> > Cc: Pekka Paalanen <pekka.paalanen@xxxxxxxxxxxxx> > --- > 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(-) > > 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 863e47200911..625dba7ddbfe 100644 > --- a/include/uapi/drm/drm.h > +++ b/include/uapi/drm/drm.h > @@ -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) > diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h > index 92d96a2b6763..8a7e747f0564 100644 > --- a/include/uapi/drm/drm_mode.h > +++ b/include/uapi/drm/drm_mode.h > @@ -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; Acked-by: Pekka Paalanen <pekka.paalanen@xxxxxxxxxxxxx> 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
Attachment:
pgpZb1htzWCRm.pgp
Description: OpenPGP digital signature