On Thu, Dec 02 2021, Jason Gunthorpe [off-list ref] wrote:

On Thu, Dec 02, 2021 at 06:05:36PM +0100, Cornelia Huck wrote:

quoted

On Wed, Dec 01 2021, Jason Gunthorpe [off-list ref] wrote:

quoted

On Wed, Dec 01, 2021 at 01:03:14PM -0700, Alex Williamson wrote:

quoted

But if this document is suggesting the mlx5/QEMU interpretation is the
only valid interpretations for driver authors, those clarifications
should be pushed back into the uAPI header.

Can we go the other way and move more of the uAPI header text here?

Where should a userspace author look when they try to implement support
for vfio migration? I think we need to answer that question first.

Maybe we should separate "these are the rules that an implementation
must obey" from "here's a more verbose description of how things work,
and how you can arrive at a working implementation". The former would go
into the header, while the latter can go into this document. (The
generated documentation can be linked from the header file.)

I think the usual kernel expectation now is to find userspace
information either in man pages or in the Documentation/ html pages?

The uapi header is fine to be a terse summary of what the ioctl does
and some important points, but I wouldn't try to write a spec for
anything complicated in a header file.

I was thinking less of a complete spec, more of "these are the fields
with some basic rules, consult $LINK for more information".