| Message ID | 20230803100041.387404-1-contact@emersion.fr (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB | expand |
On Thu, 03 Aug 2023 10:00:44 +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. > > 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 | 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@collabora.com> 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
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;
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@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 | 15 +++++++++++++++ include/uapi/drm/drm_mode.h | 16 ++++++++++++++-- 3 files changed, 31 insertions(+), 2 deletions(-)