RE: [PATCH] virt: acrn: fix kernel-doc in <uapi/linux/acrn.h>

[Li, Fei1]

> 
> Hi,
> 
> On 10/23/25 11:00 PM, Li, Fei1 wrote:
> >> From: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> >> Sent: Friday, October 24, 2025 12:42 PM
> >> To: linux-kernel@xxxxxxxxxxxxxxx
> >> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>; Li, Fei1
> >> <fei1.li@xxxxxxxxx>; acrn-dev@xxxxxxxxxxxxxxxxxxxxx; Greg
> >> Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> >> Subject: [PATCH] virt: acrn: fix kernel-doc in <uapi/linux/acrn.h>
> >>
> >> Fix the kernel-doc comments for struct acrn_mmiodev so that all
> >> struct members are rendered correctly.
> >> Correct io_base to io_addr in struct acrn_vdev.
> >>
> >> acrn.h:441: warning: Function parameter or struct member 'res'
> >>  not described in 'acrn_mmiodev'
> >> acrn.h:479: warning: Function parameter or struct member 'io_addr'
> >>  not described in 'acrn_vdev'
> >> acrn.h:479: warning: Excess struct member 'io_base' description  in
> >> 'acrn_vdev'
> >>
> >> Signed-off-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> >> ---
> >> Cc: Fei Li <fei1.li@xxxxxxxxx>
> >> Cc: acrn-dev@xxxxxxxxxxxxxxxxxxxxx
> >> Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> >> ---
> >>  include/uapi/linux/acrn.h |   11 ++++++-----
> >>  1 file changed, 6 insertions(+), 5 deletions(-)
> >>
> >> --- linux-next-20251022.orig/include/uapi/linux/acrn.h
> >> +++ linux-next-20251022/include/uapi/linux/acrn.h
> >> @@ -420,12 +420,13 @@ struct acrn_pcidev {
> >>  /**
> >>   * struct acrn_mmiodev - Info for assigning or de-assigning a MMIO device
> >>   * @name:			Name of the MMIO device.
> >> - * @res[].user_vm_pa:		Physical address of User VM of the
> MMIO
> >> region
> >> + * @res:			MMIO resource descriptor info.
> >
> > Hi Randy
> >
> > Thanks for cooking this patch to help fix these warning.
> > Could you just add the comment for `res` and keep the other comments for
> the fields of ` struct acrn_mmiodev ` ?
> >
> 
> Do you mean leave the [] square brackets in the field name?
yes
> If that's what you mean, that's not valid kernel-doc notation.
Would you please post the quote how kernel-doc prefer to add this comments ? I didn't see
an example in the kernel-doc.rst

Thanks.

> 
> >
> >> + * @res.user_vm_pa:		Physical address of User VM of the
> MMIO
> >> region
> >>   *				for the MMIO device.
> >> - * @res[].service_vm_pa:	Physical address of Service VM of the MMIO
> >> + * @res.service_vm_pa:		Physical address of Service VM of the
> >> MMIO
> >>   *				region for the MMIO device.
> >> - * @res[].size:			Size of the MMIO region for the
> MMIO
> >> device.
> >> - * @res[].mem_type:		Memory type of the MMIO region for
> the
> >> MMIO
> >> + * @res.size:			Size of the MMIO region for the
> MMIO
> >> device.
> >> + * @res.mem_type:		Memory type of the MMIO region for
> the
> >> MMIO
> >>   *				device.
> >>   *
> >>   * This structure will be passed to hypervisor directly.
> >> @@ -449,7 +450,7 @@ struct acrn_mmiodev {
> >>   * @id.fields.legacy_id:	ID of the virtual device if not a PCI device
> >>   * @slot:			Virtual Bus/Device/Function of the virtual
> >>   *				device
> >> - * @io_base:			IO resource base address of the
> virtual device
> >> + * @io_addr:			IO resource base address of the
> virtual device
> >>   * @io_size:			IO resource size of the virtual device
> >>   * @args:			Arguments for the virtual device creation
> >>   *
> 
> --
> ~Randy