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

[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@xxxxxxxxxxx>
> > > > > ---
> > > > >     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)