[PATCH 1/2] drm/dumb-buffers: reference the ioctl interface for its constraints

[PATCH 1/2] drm/dumb-buffers: reference the ioctl interface for its constraints

[Icenowy Zheng]

The current design of the DRM_IOCTL_MODE_CREATE_DUMB interface can only
promise linear RGB buffers to be properly working.

Add a reference to the interface from the document snippet for dumb
objects (which is included by drm-kms.rst document and will end up in
the built kernel documentation).

Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
---
 drivers/gpu/drm/drm_dumb_buffers.c | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
index e2b62e5fb891b..5d535b230aad3 100644
--- a/drivers/gpu/drm/drm_dumb_buffers.c
+++ b/drivers/gpu/drm/drm_dumb_buffers.c
@@ -57,7 +57,10 @@
  *
  * Note that dumb objects may not be used for gpu acceleration, as has been
  * attempted on some ARM embedded platforms. Such drivers really must have
- * a hardware-specific ioctl to allocate suitable buffer objects.
+ * a hardware-specific ioctl to allocate suitable buffer objects. The current
+ * userspace API also includes some constraints on the format and modifier to
+ * be used with buffers backed by dumb objects, see &struct
+ * drm_mode_create_dumb for more details.
  */
 
 static int drm_mode_align_dumb(struct drm_mode_create_dumb *args,
-- 
2.52.0

[PATCH 2/2] drm/dumb-buffers: document abuses in the UAPI document

[Icenowy Zheng]

Although the current DRM_IOCTL_MODE_CREATE_DUMB interface design only
suits linear buffers, some KMS drivers abuse it for AFBC framebuffers.

Mention it in the interface document, and clarifying that it's not
recommended.

Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
---
 include/uapi/drm/drm_mode.h | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
index cbbbfc1dfe2b8..02b6fa7ade355 100644
--- a/include/uapi/drm/drm_mode.h
+++ b/include/uapi/drm/drm_mode.h
@@ -1256,6 +1256,10 @@ struct drm_mode_crtc_page_flip_target {
  * Do not attempt to allocate anything but linear framebuffer memory
  * with single-plane RGB data. Allocation of other framebuffer
  * layouts requires dedicated ioctls in the respective DRM driver.
+ * There exists drivers exploiting this interface for framebuffers
+ * with modifiers other than DRM_FORMAT_MOD_LINEAR, but this is
+ * incorrect usage with undefined behavior, and should not be
+ * replicated.
  */
 struct drm_mode_create_dumb {
 	__u32 height;
-- 
2.52.0

Re: [PATCH 2/2] drm/dumb-buffers: document abuses in the UAPI document

[Thomas Zimmermann]

Hi

Am 26.02.26 um 07:37 schrieb Icenowy Zheng:
> Although the current DRM_IOCTL_MODE_CREATE_DUMB interface design only
> suits linear buffers, some KMS drivers abuse it for AFBC framebuffers.
>
> Mention it in the interface document, and clarifying that it's not
> recommended.
>
> Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
> ---
>   include/uapi/drm/drm_mode.h | 4 ++++
>   1 file changed, 4 insertions(+)
>
> diff --git a/include/uapi/drm/drm_mode.h b/include/uapi/drm/drm_mode.h
> index cbbbfc1dfe2b8..02b6fa7ade355 100644
> --- a/include/uapi/drm/drm_mode.h
> +++ b/include/uapi/drm/drm_mode.h
> @@ -1256,6 +1256,10 @@ struct drm_mode_crtc_page_flip_target {

Since you're at it, you should move the line at [1] right here as the 
first sentence of this paragraph. Then continue with 'Do not attempt'.

With that change, the previous paragraphs refer to pixel formats and the 
final one refers to framebuffer layout.


>    * Do not attempt to allocate anything but linear framebuffer memory
>    * with single-plane RGB data. Allocation of other framebuffer
>    * layouts requires dedicated ioctls in the respective DRM driver.
> + * There exists drivers exploiting this interface for framebuffers

'exists user-space software'

> + * with modifiers other than DRM_FORMAT_MOD_LINEAR, but this is

Rather 'with non-linear layout'.  The reference to MOD_LINEAR seems out 
of place here.

> + * incorrect usage with undefined behavior, and should not be
> + * replicated.

Best regards
Thomas

[1] 
https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1216

>    */
>   struct drm_mode_create_dumb {
>   	__u32 height;

-- 
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com
GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)

Re: [PATCH 2/2] drm/dumb-buffers: document abuses in the UAPI document

[Icenowy Zheng]

在 2026-02-26四的 17:01 +0100，Thomas Zimmermann写道：
> Hi
> 
> Am 26.02.26 um 07:37 schrieb Icenowy Zheng:
> > Although the current DRM_IOCTL_MODE_CREATE_DUMB interface design
> > only
> > suits linear buffers, some KMS drivers abuse it for AFBC
> > framebuffers.
> > 
> > Mention it in the interface document, and clarifying that it's not
> > recommended.
> > 
> > Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
> > ---
> >   include/uapi/drm/drm_mode.h | 4 ++++
> >   1 file changed, 4 insertions(+)
> > 
> > diff --git a/include/uapi/drm/drm_mode.h
> > b/include/uapi/drm/drm_mode.h
> > index cbbbfc1dfe2b8..02b6fa7ade355 100644
> > --- a/include/uapi/drm/drm_mode.h
> > +++ b/include/uapi/drm/drm_mode.h
> > @@ -1256,6 +1256,10 @@ struct drm_mode_crtc_page_flip_target {
> 
> Since you're at it, you should move the line at [1] right here as the
> first sentence of this paragraph. Then continue with 'Do not
> attempt'.
> 
> With that change, the previous paragraphs refer to pixel formats and
> the 
> final one refers to framebuffer layout.
> 
> 
> >    * Do not attempt to allocate anything but linear framebuffer
> > memory
> >    * with single-plane RGB data. Allocation of other framebuffer
> >    * layouts requires dedicated ioctls in the respective DRM
> > driver.
> > + * There exists drivers exploiting this interface for framebuffers
> 
> 'exists user-space software'

Ah the drivers seem to be also criminal to accept this kind of usage,
it's why I thought about writing "drivers" here.

Thanks
Icenowy

> 
> > + * with modifiers other than DRM_FORMAT_MOD_LINEAR, but this is
> 
> Rather 'with non-linear layout'.  The reference to MOD_LINEAR seems
> out 
> of place here.
> 
> > + * incorrect usage with undefined behavior, and should not be
> > + * replicated.
> 
> Best regards
> Thomas
> 
> [1] 
> https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1216
> 
> >    */
> >   struct drm_mode_create_dumb {
> >   	__u32 height;

Re: [PATCH 2/2] drm/dumb-buffers: document abuses in the UAPI document

[Thomas Zimmermann]

Hi

Am 26.02.26 um 17:06 schrieb Icenowy Zheng:
> 在 2026-02-26四的 17:01 +0100，Thomas Zimmermann写道：
>> Hi
>>
>> Am 26.02.26 um 07:37 schrieb Icenowy Zheng:
>>> Although the current DRM_IOCTL_MODE_CREATE_DUMB interface design
>>> only
>>> suits linear buffers, some KMS drivers abuse it for AFBC
>>> framebuffers.
>>>
>>> Mention it in the interface document, and clarifying that it's not
>>> recommended.
>>>
>>> Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
>>> ---
>>>    include/uapi/drm/drm_mode.h | 4 ++++
>>>    1 file changed, 4 insertions(+)
>>>
>>> diff --git a/include/uapi/drm/drm_mode.h
>>> b/include/uapi/drm/drm_mode.h
>>> index cbbbfc1dfe2b8..02b6fa7ade355 100644
>>> --- a/include/uapi/drm/drm_mode.h
>>> +++ b/include/uapi/drm/drm_mode.h
>>> @@ -1256,6 +1256,10 @@ struct drm_mode_crtc_page_flip_target {
>> Since you're at it, you should move the line at [1] right here as the
>> first sentence of this paragraph. Then continue with 'Do not
>> attempt'.
>>
>> With that change, the previous paragraphs refer to pixel formats and
>> the
>> final one refers to framebuffer layout.
>>
>>
>>>     * Do not attempt to allocate anything but linear framebuffer
>>> memory
>>>     * with single-plane RGB data. Allocation of other framebuffer
>>>     * layouts requires dedicated ioctls in the respective DRM
>>> driver.
>>> + * There exists drivers exploiting this interface for framebuffers
>> 'exists user-space software'
> Ah the drivers seem to be also criminal to accept this kind of usage,
> it's why I thought about writing "drivers" here.

Each driver implements dumb buffers on top of its own memory manager. 
They are complicit in the sense that they often never tested against the 
limitations of the dumb-buffer ioctl. But OTOH the limitations where 
never written down clearly. Only very recently did we add the code and 
documentation to clarify dumb-buffer semantics. [1] And not all drivers 
have been updated yet.

Therefore several user-space programs used dumb-buffers in an 
"out-of-scope fashion" and got away with it. The comments in 
drm_mode_size_dumb() list the known exceptions.

Best regards
Thomas

[1] https://lore.kernel.org/all/20250821081918.79786-3-tzimmermann@suse.de/

>
> Thanks
> Icenowy
>
>>> + * with modifiers other than DRM_FORMAT_MOD_LINEAR, but this is
>> Rather 'with non-linear layout'.  The reference to MOD_LINEAR seems
>> out
>> of place here.
>>
>>> + * incorrect usage with undefined behavior, and should not be
>>> + * replicated.
>> Best regards
>> Thomas
>>
>> [1]
>> https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1216
>>
>>>     */
>>>    struct drm_mode_create_dumb {
>>>    	__u32 height;

-- 
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com
GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)

Re: [PATCH 1/2] drm/dumb-buffers: reference the ioctl interface for its constraints

[Thomas Zimmermann]

Hi

Am 26.02.26 um 07:37 schrieb Icenowy Zheng:
> The current design of the DRM_IOCTL_MODE_CREATE_DUMB interface can only
> promise linear RGB buffers to be properly working.
>
> Add a reference to the interface from the document snippet for dumb
> objects (which is included by drm-kms.rst document and will end up in
> the built kernel documentation).
>
> Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>

Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>

with a comment on wording below

> ---
>   drivers/gpu/drm/drm_dumb_buffers.c | 5 ++++-
>   1 file changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
> index e2b62e5fb891b..5d535b230aad3 100644
> --- a/drivers/gpu/drm/drm_dumb_buffers.c
> +++ b/drivers/gpu/drm/drm_dumb_buffers.c
> @@ -57,7 +57,10 @@
>    *
>    * Note that dumb objects may not be used for gpu acceleration, as has been
>    * attempted on some ARM embedded platforms. Such drivers really must have
> - * a hardware-specific ioctl to allocate suitable buffer objects.
> + * a hardware-specific ioctl to allocate suitable buffer objects. The current
> + * userspace API also includes some constraints on the format and modifier to

Rather 'on the pixel format and framebuffer layout'.  The term modifier 
seems out of place here.

Best regards
Thomas

> + * be used with buffers backed by dumb objects, see &struct
> + * drm_mode_create_dumb for more details.
>    */
>   
>   static int drm_mode_align_dumb(struct drm_mode_create_dumb *args,

-- 
--
Thomas Zimmermann
Graphics Driver Developer
SUSE Software Solutions Germany GmbH
Frankenstr. 146, 90461 Nürnberg, Germany, www.suse.com
GF: Jochen Jaser, Andrew McDonald, Werner Knoblich, (HRB 36809, AG Nürnberg)