Re: [PATCH v3] vfio: Introduce helper vfio_pci_from_vfio_device()

["Cédric Le Goater" <clg@redhat.com>]

On 8/1/25 17:56, Peter Maydell wrote:
> On Fri, 1 Aug 2025 at 16:47, Cédric Le Goater <clg@redhat.com> wrote:
>> I have modified your patch with :
>>
>> +/**
>> +  * vfio_pci_from_vfio_device: Transform from VFIODevice to
>> +  * VFIOPCIDevice
>> +  *
>> +  * This function checks if the given @vbasedev is a VFIO PCI device.
>> +  * If it is, it returns the containing VFIOPCIDevice.
>> +  *
>> +  * @vbasedev: The VFIODevice to transform
>> +  *
>> +  * Return: The VFIOPCIDevice on success, NULL on failure.
>> +  */
>>
>> See https://github.com/legoater/qemu/tree/vfio-10.2.
>>
>> I don't think it's really necessary, as these are internal APIs and
>> none are documented, but Philippe seems keen on it. I guess he plans
>> to volunteer to document the rest ;)
> 
> This is one of those cases where we have a rule in place
> that we apply on code review for newly added prototypes
> in header files, as an exercise in trying to at least not
> make an existing problem worse :-)

Sure. May be, this is something we could add to checkpatch.pl
then ? This would reduce the resends for simple things.

> I think Philippe's intent was just to say "put that one
> line comment by the prototype in the .h file rather than
> by the implementation in the .c file", rather than to
> require a full-on doc-comment format comment, though
> I do appreciate having one.
I've tried to reorganize the VFIO code to define some software
subcomponents and layers in previous versions. This to handle
recent (rather significant) changes and also because vfio-pci
was initially a device and is gradually evolving into a kind
of library.

I'd also like to address documentation, so my comment was
self-interested :) as it's a pretty broad topic; any help is
welcome !

I should find a way to generate some of it to start with. At least.

Thanks,

C.