[PATCH 2/2] drm/doc: emphasize difference between plane formats and IN_FORMATS blob

[Daniel Vetter]

On Thu, Apr 08, 2021 at 05:39:22PM +0300, Ville Syrjälä wrote:
> On Thu, Apr 08, 2021 at 04:57:51PM +0300, Pekka Paalanen wrote:
> > On Thu, 8 Apr 2021 13:30:16 +0200
> > Daniel Vetter <daniel at ffwll.ch> wrote:
> > 
> > > On Thu, Apr 08, 2021 at 12:59:19PM +0300, Pekka Paalanen wrote:
> > 
> > > > The point of these documentation patches is to establish the convention
> > > > that:
> > > > 
> > > > - drm_mode_get_plane::format_type_ptr is the list of pixel formats that
> > > >   can work via the no-modifiers uAPI, but says nothing about the
> > > >   explicit modifiers uAPI.
> > > > 
> > > > - IN_FORMATS is a list of format-modifier pairs that can work via the
> > > >   explicit modifiers API, but says nothing about the no-modifiers uAPI.
> > > > 
> > > > Is that a reasonable expectation?  
> > > 
> > > I'm not sure. I thought they're the same list underneath in the kernel, at
> > > least for drivers that do support modifiers. The current wording I think
> > > suggests more meaning than is actually there.
> > 
> > They may be the same list in the kernel today, but do you want to force
> > all future drivers and future formats-modifiers to have that too?
> > Or did the boat sail already?
> > 
> > The existing uAPI considers these two to be independent lists, no
> > documentation saying otherwise, is there?
> > 
> > Should a kernel driver not have a way to say "this format won't work
> > via the no-modifiers uAPI"?
> > 
> > The practical consequence in userspace is how should userspace collect
> > the lists of supported format-modifier pairs, when the kernel has two
> > independent format lists, one carries modifiers explicitly and the
> > other does not. The one that carries explicit modifiers cannot denote
> > "no modifier" AFAIU.
> > 
> > So the "obvious" interpretation in userspace is that:
> > - the format list that does not carry any modifier information should
> >   be used with the no-modifiers uAPI, and
> > - the format list that does carry explicit modifiers should be used
> >   with the explicit modifiers uAPI.

Imo the right interpretation is "it's the same list".

> > If you were to say, that if IN_FORMATS exists, use it and ignore the
> > old no-modifiers format list, then the conclusion in userspace when
> > IN_FORMATS exists is that you cannot use the no-modifiers uAPI, because
> > all formats that are listed as supported carry an explicit modifier.

So formats without modifiers are very funny in their semantics. It means
- implied modifier is untiled
- except on i915 and radeon/amdgpu, where there's magic hidden information
  and you might get something else. But it won't work in multi-gpu
  situations
- except bugs (like imo mesa trying to use tiling without modifiers and
  without magic in-kernel tiling information forwarding is just broken,
  and surprise, it's broken). We've had some where parts of mesa where
  assuming modifiers are ok, but that wasn't the case.

Now maybe we can expose to userspace which drivers have magic device-local
tiling information sharing, but I don't expect this list to ever grow.

Anything beyond that sounds like the kernel should maintain a bug list of
things which are broken in userspace.

> > I understand that the format or format-modifier lists are not
> > authoritative. Formats outside of the lists *could* work. But why would
> > anyone bother trying something that is not suggested to work?
> 
> IMO formats not listed by any plane should just be rejected by addfb2.
> I tried to put that check in the drm core actually but there was some
> weird pushback, so for the moment it's handled by each driver. Some
> drivers (like i915) will reject anything not supported by any plane,
> other drivers might not (and probably no one knows how badly they
> might blow up if you pass in some exotic format...).
>
> I also had some igt patches to test that addfb2 behaviour but
> they didn't go in either.
>
> > Or, is the intention such, that all formats in IN_FORMATS list imply
> > some support through the no-modifiers uAPI too, iff buffer
> > allocation does not give you an explicit modifier?
> > 
> > Or, should there be an i-g-t test to ensure that both the old and
> > IN_FORMATS lists have the exact same pixel formats always, carving that
> > fact into stone and resolving all this ambiguity?
> > 
> > > > Is it also so that passing MOD_INVALID to the explicit modifier uAPI
> > > > (ADDFB2) is invalid argument? Do we have that documented?  
> > > 
> > > We'd need to check that, currently it's an out-of-band flag in the struct.
> > > Atm DRM_FORMAT_MOD_INVALID is entirely an internal sentinel value to
> > > denote end-of-array entries.
> > > 
> > > In practice it wont pass because we validate the modifiers against the
> > > advertised list.
> 
> We don't actually. If the driver provides the .format_mod_supported()
> hook then it's up to the driver to validate the modifier in said hook.
> This was done so that people can embed metadata inside the modifier
> while only having the base modifier on the modifier list. How userspace
> is supposed to figure out which values for this extra metadata are valid
> I have no idea.

It took me a while to figure this out again, but now I remember. It's
because of combinatorial explosion of modifiers with stuff like AFBC. So
the modifier list is not necessarily an exhaustive list of all
combinations, some of the modifiers count more like flags. Which is kinda
hilarious since it means userspace can't do anything with modifiers it
gets :-/
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch