Re: [PATCH RFC v2] vfio: Documentation for the migration region

[Cornelia Huck <cohuck@redhat.com>]

On Thu, Dec 02 2021, Jason Gunthorpe <jgg@nvidia.com> wrote:

> On Thu, Dec 02, 2021 at 06:05:36PM +0100, Cornelia Huck wrote:
>> On Wed, Dec 01 2021, Jason Gunthorpe <jgg@nvidia.com> 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.

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