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

[Icenowy Zheng <zhengxingda@iscas.ac.cn>]

在 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,