* [PATCH] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB
@ 2023-08-03 10:00 Simon Ser
2023-08-21 8:49 ` Pekka Paalanen
0 siblings, 1 reply; 2+ messages in thread
From: Simon Ser @ 2023-08-03 10:00 UTC (permalink / raw)
To: dri-devel; +Cc: Daniel Vetter, Pekka Paalanen
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;
--
2.41.0
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [PATCH] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB
2023-08-03 10:00 [PATCH] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB Simon Ser
@ 2023-08-21 8:49 ` Pekka Paalanen
0 siblings, 0 replies; 2+ messages in thread
From: Pekka Paalanen @ 2023-08-21 8:49 UTC (permalink / raw)
To: Simon Ser; +Cc: Daniel Vetter, dri-devel
[-- Attachment #1: Type: text/plain, Size: 3750 bytes --]
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
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2023-08-21 8:49 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-08-03 10:00 [PATCH] drm/doc: document DRM_IOCTL_MODE_CREATE_DUMB Simon Ser
2023-08-21 8:49 ` Pekka Paalanen
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.