drm/dumb-buffers: document that it's only for linear FB

[PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Icenowy Zheng 1 month, 2 weeks ago

The ioctl interfaces for dumb buffers currently only properly support
linear buffers.

Mention this in the documentation snippet of dumb-buffers source code,
which is referenced by drm-kms.rst and will end up in the built kernel
documentation.

Also mention the existence of current drivers abusing dumb buffers for
AFBC to reduce confusion about this.

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

diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
index e2b62e5fb891b..06f74460adf62 100644
--- a/drivers/gpu/drm/drm_dumb_buffers.c
+++ b/drivers/gpu/drm/drm_dumb_buffers.c
@@ -57,7 +57,12 @@
  *
  * 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. They are
+ * also currently meant for only linear buffers, and using them with any
+ * modifier other than DRM_FORMAT_MOD_LINEAR is undefined behavior. There
+ * exist some KMS drivers abusing dumb objects for AFBC framebuffers, but this
+ * behavior is discouraged, only exists as a hack now and shouldn't be
+ * replicated.
  */
 
 static int drm_mode_align_dumb(struct drm_mode_create_dumb *args,
-- 
2.52.0

Re: [PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Thomas Zimmermann 1 month, 2 weeks ago

Hi,

Am 25.02.26 um 07:13 schrieb Icenowy Zheng:
> The ioctl interfaces for dumb buffers currently only properly support
> linear buffers.
>
> Mention this in the documentation snippet of dumb-buffers source code,
> which is referenced by drm-kms.rst and will end up in the built kernel
> documentation.
>
> Also mention the existence of current drivers abusing dumb buffers for
> AFBC to reduce confusion about this.
>
> Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
> ---
>   drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-

We documented the meaning of the color bits and the behavior of the 
dumb-buffer interface at [1]. If anything is missing, it should be added 
there.

Best regards
Thomas

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

>   1 file changed, 6 insertions(+), 1 deletion(-)
>
> diff --git a/drivers/gpu/drm/drm_dumb_buffers.c b/drivers/gpu/drm/drm_dumb_buffers.c
> index e2b62e5fb891b..06f74460adf62 100644
> --- a/drivers/gpu/drm/drm_dumb_buffers.c
> +++ b/drivers/gpu/drm/drm_dumb_buffers.c
> @@ -57,7 +57,12 @@
>    *
>    * 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. They are
> + * also currently meant for only linear buffers, and using them with any
> + * modifier other than DRM_FORMAT_MOD_LINEAR is undefined behavior. There
> + * exist some KMS drivers abusing dumb objects for AFBC framebuffers, but this
> + * behavior is discouraged, only exists as a hack now and shouldn't be
> + * replicated.
>    */
>   
>   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)

Re: [PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Icenowy Zheng 1 month, 2 weeks ago

在 2026-02-25三的 08:26 +0100，Thomas Zimmermann写道：
> Hi,
> 
> Am 25.02.26 um 07:13 schrieb Icenowy Zheng:
> > The ioctl interfaces for dumb buffers currently only properly
> > support
> > linear buffers.
> > 
> > Mention this in the documentation snippet of dumb-buffers source
> > code,
> > which is referenced by drm-kms.rst and will end up in the built
> > kernel
> > documentation.
> > 
> > Also mention the existence of current drivers abusing dumb buffers
> > for
> > AFBC to reduce confusion about this.
> > 
> > Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
> > ---
> >   drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-
> 
> We documented the meaning of the color bits and the behavior of the 
> dumb-buffer interface at [1]. If anything is missing, it should be
> added 
> there.

Yes, I saw this piece of document; however it's part of the interface
document instead of a concept document, and the whole existence of the
document snippet I am changing can be considered a duplicate of the
interface document.

Thanks
Icenowy

> 
> Best regards
> Thomas
> 
> [1] 
> https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1200
> 
> >   1 file changed, 6 insertions(+), 1 deletion(-)
> > 
> > diff --git a/drivers/gpu/drm/drm_dumb_buffers.c
> > b/drivers/gpu/drm/drm_dumb_buffers.c
> > index e2b62e5fb891b..06f74460adf62 100644
> > --- a/drivers/gpu/drm/drm_dumb_buffers.c
> > +++ b/drivers/gpu/drm/drm_dumb_buffers.c
> > @@ -57,7 +57,12 @@
> >    *
> >    * 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.
> > They are
> > + * also currently meant for only linear buffers, and using them
> > with any
> > + * modifier other than DRM_FORMAT_MOD_LINEAR is undefined
> > behavior. There
> > + * exist some KMS drivers abusing dumb objects for AFBC
> > framebuffers, but this
> > + * behavior is discouraged, only exists as a hack now and
> > shouldn't be
> > + * replicated.
> >    */
> >   
> >   static int drm_mode_align_dumb(struct drm_mode_create_dumb *args,

Re: [PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Thomas Zimmermann 1 month, 2 weeks ago


Am 25.02.26 um 08:38 schrieb Icenowy Zheng:
> 在 2026-02-25三的 08:26 +0100，Thomas Zimmermann写道：
>> Hi,
>>
>> Am 25.02.26 um 07:13 schrieb Icenowy Zheng:
>>> The ioctl interfaces for dumb buffers currently only properly
>>> support
>>> linear buffers.
>>>
>>> Mention this in the documentation snippet of dumb-buffers source
>>> code,
>>> which is referenced by drm-kms.rst and will end up in the built
>>> kernel
>>> documentation.
>>>
>>> Also mention the existence of current drivers abusing dumb buffers
>>> for
>>> AFBC to reduce confusion about this.
>>>
>>> Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
>>> ---
>>>    drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-
>> We documented the meaning of the color bits and the behavior of the
>> dumb-buffer interface at [1]. If anything is missing, it should be
>> added
>> there.
> Yes, I saw this piece of document; however it's part of the interface
> document instead of a concept document, and the whole existence of the

What is a concept document?

> document snippet I am changing can be considered a duplicate of the
> interface document.
>
> Thanks
> Icenowy
>
>> Best regards
>> Thomas
>>
>> [1]
>> https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1200
>>
>>>    1 file changed, 6 insertions(+), 1 deletion(-)
>>>
>>> diff --git a/drivers/gpu/drm/drm_dumb_buffers.c
>>> b/drivers/gpu/drm/drm_dumb_buffers.c
>>> index e2b62e5fb891b..06f74460adf62 100644
>>> --- a/drivers/gpu/drm/drm_dumb_buffers.c
>>> +++ b/drivers/gpu/drm/drm_dumb_buffers.c
>>> @@ -57,7 +57,12 @@
>>>     *
>>>     * 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.
>>> They are
>>> + * also currently meant for only linear buffers, and using them
>>> with any
>>> + * modifier other than DRM_FORMAT_MOD_LINEAR is undefined
>>> behavior. There
>>> + * exist some KMS drivers abusing dumb objects for AFBC
>>> framebuffers, but this
>>> + * behavior is discouraged, only exists as a hack now and
>>> shouldn't be
>>> + * replicated.
>>>     */
>>>    
>>>    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)

Re: [PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Icenowy Zheng 1 month, 2 weeks ago

在 2026-02-25三的 08:47 +0100，Thomas Zimmermann写道：
> 
> 
> Am 25.02.26 um 08:38 schrieb Icenowy Zheng:
> > 在 2026-02-25三的 08:26 +0100，Thomas Zimmermann写道：
> > > Hi,
> > > 
> > > Am 25.02.26 um 07:13 schrieb Icenowy Zheng:
> > > > The ioctl interfaces for dumb buffers currently only properly
> > > > support
> > > > linear buffers.
> > > > 
> > > > Mention this in the documentation snippet of dumb-buffers
> > > > source
> > > > code,
> > > > which is referenced by drm-kms.rst and will end up in the built
> > > > kernel
> > > > documentation.
> > > > 
> > > > Also mention the existence of current drivers abusing dumb
> > > > buffers
> > > > for
> > > > AFBC to reduce confusion about this.
> > > > 
> > > > Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
> > > > ---
> > > >    drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-
> > > We documented the meaning of the color bits and the behavior of
> > > the
> > > dumb-buffer interface at [1]. If anything is missing, it should
> > > be
> > > added
> > > there.
> > Yes, I saw this piece of document; however it's part of the
> > interface
> > document instead of a concept document, and the whole existence of
> > the
> 
> What is a concept document?

Well I am patching this document snippet because it becomes part of the
document at [1] (by being referenced in the .rst file).

[1] https://docs.kernel.org/gpu/drm-kms.html#dumb-buffer-objects

> 
> > document snippet I am changing can be considered a duplicate of the
> > interface document.
> > 
> > Thanks
> > Icenowy
> > 
> > > Best regards
> > > Thomas
> > > 
> > > [1]
> > > https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1200
> > > 
> > > >    1 file changed, 6 insertions(+), 1 deletion(-)
> > > > 
> > > > diff --git a/drivers/gpu/drm/drm_dumb_buffers.c
> > > > b/drivers/gpu/drm/drm_dumb_buffers.c
> > > > index e2b62e5fb891b..06f74460adf62 100644
> > > > --- a/drivers/gpu/drm/drm_dumb_buffers.c
> > > > +++ b/drivers/gpu/drm/drm_dumb_buffers.c
> > > > @@ -57,7 +57,12 @@
> > > >     *
> > > >     * 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.
> > > > They are
> > > > + * also currently meant for only linear buffers, and using
> > > > them
> > > > with any
> > > > + * modifier other than DRM_FORMAT_MOD_LINEAR is undefined
> > > > behavior. There
> > > > + * exist some KMS drivers abusing dumb objects for AFBC
> > > > framebuffers, but this
> > > > + * behavior is discouraged, only exists as a hack now and
> > > > shouldn't be
> > > > + * replicated.
> > > >     */
> > > >    
> > > >    static int drm_mode_align_dumb(struct drm_mode_create_dumb
> > > > *args,

Re: [PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Thomas Zimmermann 1 month, 2 weeks ago

Hi

Am 25.02.26 um 09:10 schrieb Icenowy Zheng:
> 在 2026-02-25三的 08:47 +0100，Thomas Zimmermann写道：
>>
>> Am 25.02.26 um 08:38 schrieb Icenowy Zheng:
>>> 在 2026-02-25三的 08:26 +0100，Thomas Zimmermann写道：
>>>> Hi,
>>>>
>>>> Am 25.02.26 um 07:13 schrieb Icenowy Zheng:
>>>>> The ioctl interfaces for dumb buffers currently only properly
>>>>> support
>>>>> linear buffers.
>>>>>
>>>>> Mention this in the documentation snippet of dumb-buffers
>>>>> source
>>>>> code,
>>>>> which is referenced by drm-kms.rst and will end up in the built
>>>>> kernel
>>>>> documentation.
>>>>>
>>>>> Also mention the existence of current drivers abusing dumb
>>>>> buffers
>>>>> for
>>>>> AFBC to reduce confusion about this.
>>>>>
>>>>> Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
>>>>> ---
>>>>>     drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-
>>>> We documented the meaning of the color bits and the behavior of
>>>> the
>>>> dumb-buffer interface at [1]. If anything is missing, it should
>>>> be
>>>> added
>>>> there.
>>> Yes, I saw this piece of document; however it's part of the
>>> interface
>>> document instead of a concept document, and the whole existence of
>>> the
>> What is a concept document?
> Well I am patching this document snippet because it becomes part of the
> document at [1] (by being referenced in the .rst file).

That question was a joke, but also not entirely untrue.

These overview sections usually introduce the purpose of a module and 
give readers a sense of how to use the code; like a tutorial. We don't 
have concept documents. As the concepts keep changing, they'd bitrot 
quickly.

For example, not too long ago we discussed the possibility of a 
CREATE_DUMB2 ioctl that would allow for specifying the DRM format 
directly. It would also allow formats with multiple planes and 
non-linear layouts. My point is that whatever we write here today could 
be obsolete tomorrow. The only stable thing is the user-space interfaces.

IMHO if you think the overview should mention the supported formats, you 
should link to the UAPI documentation of the ioctl. If we ever get that 
CREATE2 ioctl, we can refer to this as well.

Best regards
Thomas

>
> [1] https://docs.kernel.org/gpu/drm-kms.html#dumb-buffer-objects
>
>>> document snippet I am changing can be considered a duplicate of the
>>> interface document.
>>>
>>> Thanks
>>> Icenowy
>>>
>>>> Best regards
>>>> Thomas
>>>>
>>>> [1]
>>>> https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1200
>>>>
>>>>>     1 file changed, 6 insertions(+), 1 deletion(-)
>>>>>
>>>>> diff --git a/drivers/gpu/drm/drm_dumb_buffers.c
>>>>> b/drivers/gpu/drm/drm_dumb_buffers.c
>>>>> index e2b62e5fb891b..06f74460adf62 100644
>>>>> --- a/drivers/gpu/drm/drm_dumb_buffers.c
>>>>> +++ b/drivers/gpu/drm/drm_dumb_buffers.c
>>>>> @@ -57,7 +57,12 @@
>>>>>      *
>>>>>      * 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.
>>>>> They are
>>>>> + * also currently meant for only linear buffers, and using
>>>>> them
>>>>> with any
>>>>> + * modifier other than DRM_FORMAT_MOD_LINEAR is undefined
>>>>> behavior. There
>>>>> + * exist some KMS drivers abusing dumb objects for AFBC
>>>>> framebuffers, but this
>>>>> + * behavior is discouraged, only exists as a hack now and
>>>>> shouldn't be
>>>>> + * replicated.
>>>>>      */
>>>>>     
>>>>>     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)

Re: [PATCH] drm/dumb-buffers: document that it's only for linear FB

Posted by Icenowy Zheng 1 month, 2 weeks ago

在 2026-02-25三的 09:34 +0100，Thomas Zimmermann写道：
> Hi
> 
> Am 25.02.26 um 09:10 schrieb Icenowy Zheng:
> > 在 2026-02-25三的 08:47 +0100，Thomas Zimmermann写道：
> > > 
> > > Am 25.02.26 um 08:38 schrieb Icenowy Zheng:
> > > > 在 2026-02-25三的 08:26 +0100，Thomas Zimmermann写道：
> > > > > Hi,
> > > > > 
> > > > > Am 25.02.26 um 07:13 schrieb Icenowy Zheng:
> > > > > > The ioctl interfaces for dumb buffers currently only
> > > > > > properly
> > > > > > support
> > > > > > linear buffers.
> > > > > > 
> > > > > > Mention this in the documentation snippet of dumb-buffers
> > > > > > source
> > > > > > code,
> > > > > > which is referenced by drm-kms.rst and will end up in the
> > > > > > built
> > > > > > kernel
> > > > > > documentation.
> > > > > > 
> > > > > > Also mention the existence of current drivers abusing dumb
> > > > > > buffers
> > > > > > for
> > > > > > AFBC to reduce confusion about this.
> > > > > > 
> > > > > > Signed-off-by: Icenowy Zheng <zhengxingda@iscas.ac.cn>
> > > > > > ---
> > > > > >     drivers/gpu/drm/drm_dumb_buffers.c | 7 ++++++-
> > > > > We documented the meaning of the color bits and the behavior
> > > > > of
> > > > > the
> > > > > dumb-buffer interface at [1]. If anything is missing, it
> > > > > should
> > > > > be
> > > > > added
> > > > > there.
> > > > Yes, I saw this piece of document; however it's part of the
> > > > interface
> > > > document instead of a concept document, and the whole existence
> > > > of
> > > > the
> > > What is a concept document?
> > Well I am patching this document snippet because it becomes part of
> > the
> > document at [1] (by being referenced in the .rst file).
> 
> That question was a joke, but also not entirely untrue.
> 
> These overview sections usually introduce the purpose of a module and
> give readers a sense of how to use the code; like a tutorial. We
> don't 
> have concept documents. As the concepts keep changing, they'd bitrot 
> quickly.
> 
> For example, not too long ago we discussed the possibility of a 
> CREATE_DUMB2 ioctl that would allow for specifying the DRM format 
> directly. It would also allow formats with multiple planes and 
> non-linear layouts. My point is that whatever we write here today
> could 
> be obsolete tomorrow. The only stable thing is the user-space
> interfaces.
> 
> IMHO if you think the overview should mention the supported formats,
> you 
> should link to the UAPI documentation of the ioctl. If we ever get
> that 
> CREATE2 ioctl, we can refer to this as well.

This sounds reasonable. I will reword this to a reference to the UAPI
documentation to raise attraction (because otherwise it's not very
natrual to consult the UAPI doc, at least for me).

Thanks,
Icenowy

> 
> Best regards
> Thomas
> 
> > 
> > [1] https://docs.kernel.org/gpu/drm-kms.html#dumb-buffer-objects
> > 
> > > > document snippet I am changing can be considered a duplicate of
> > > > the
> > > > interface document.
> > > > 
> > > > Thanks
> > > > Icenowy
> > > > 
> > > > > Best regards
> > > > > Thomas
> > > > > 
> > > > > [1]
> > > > > https://elixir.bootlin.com/linux/v6.19/source/include/uapi/drm/drm_mode.h#L1200
> > > > > 
> > > > > >     1 file changed, 6 insertions(+), 1 deletion(-)
> > > > > > 
> > > > > > diff --git a/drivers/gpu/drm/drm_dumb_buffers.c
> > > > > > b/drivers/gpu/drm/drm_dumb_buffers.c
> > > > > > index e2b62e5fb891b..06f74460adf62 100644
> > > > > > --- a/drivers/gpu/drm/drm_dumb_buffers.c
> > > > > > +++ b/drivers/gpu/drm/drm_dumb_buffers.c
> > > > > > @@ -57,7 +57,12 @@
> > > > > >      *
> > > > > >      * 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.
> > > > > > They are
> > > > > > + * also currently meant for only linear buffers, and using
> > > > > > them
> > > > > > with any
> > > > > > + * modifier other than DRM_FORMAT_MOD_LINEAR is undefined
> > > > > > behavior. There
> > > > > > + * exist some KMS drivers abusing dumb objects for AFBC
> > > > > > framebuffers, but this
> > > > > > + * behavior is discouraged, only exists as a hack now and
> > > > > > shouldn't be
> > > > > > + * replicated.
> > > > > >      */
> > > > > >     
> > > > > >     static int drm_mode_align_dumb(struct
> > > > > > drm_mode_create_dumb
> > > > > > *args,