On Thu, Dec 02, 2021 at 06:05:36PM +0100, Cornelia Huck wrote: > On Wed, Dec 01 2021, Jason Gunthorpe <jgg@xxxxxxxxxx> wrote: > > > On Wed, Dec 01, 2021 at 01:03:14PM -0700, Alex Williamson wrote: > >> 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. Maybe Jonathan has an advice? Thanks, Jason
