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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <SJ1PR11MB6153A77684F68B592851A32EBFFCA@SJ1PR11MB6153.namprd11.prod.outlook.com>
Date: Mon, 27 Oct 2025 05:54:59 +0000
From: "Li, Fei1" <fei1.li@...el.com>
To: Randy Dunlap <rdunlap@...radead.org>, "linux-kernel@...r.kernel.org"
	<linux-kernel@...r.kernel.org>
CC: "acrn-dev@...ts.projectacrn.org" <acrn-dev@...ts.projectacrn.org>, "Greg
 Kroah-Hartman" <gregkh@...uxfoundation.org>
Subject: RE: [PATCH] virt: acrn: fix kernel-doc in <uapi/linux/acrn.h>

> From: Randy Dunlap <rdunlap@...radead.org>
> Sent: Saturday, October 25, 2025 3:44 AM
> To: Li, Fei1 <fei1.li@...el.com>; linux-kernel@...r.kernel.org
> Cc: acrn-dev@...ts.projectacrn.org; Greg Kroah-Hartman
> <gregkh@...uxfoundation.org>
> Subject: Re: [PATCH] virt: acrn: fix kernel-doc in <uapi/linux/acrn.h>
> 
> Hi,
> 
> On 10/23/25 11:22 PM, Li, Fei1 wrote:
> >>
> >> Hi,
> >>
> >> On 10/23/25 11:00 PM, Li, Fei1 wrote:
> >>>> From: Randy Dunlap <rdunlap@...radead.org>
> >>>> Sent: Friday, October 24, 2025 12:42 PM
> >>>> To: linux-kernel@...r.kernel.org
> >>>> Cc: Randy Dunlap <rdunlap@...radead.org>; Li, Fei1
> >>>> <fei1.li@...el.com>; acrn-dev@...ts.projectacrn.org; Greg
> >>>> Kroah-Hartman <gregkh@...uxfoundation.org>
> >>>> 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@...radead.org>
> >>>> ---
> >>>> Cc: Fei Li <fei1.li@...el.com>
> >>>> Cc: acrn-dev@...ts.projectacrn.org
> >>>> Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
> >>>> ---
> >>>>  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
> 
> There is not anything in kernel-doc that indicates arrays so I can't post a quote
> that shows that.
> The patch shows the preferred kernel-doc here.

Hi Randy

IMHO,  the patch shows here is an example of `Nested structs/unions`, not an example of
`Nested structs/unions array`. 
For the ` Nested structs/unions array `, the `In-line member documentation comments`
style is more suitable, or could we just keep what it is for: (1) there're many kernels' codes
still use this comment style for theirs function comments, I.E., in kernel/rcu/srcutree.c
(2) the kernel-doc doesn't complain about this warning.
What do you think ?

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
> >
> 
> --
> ~Randy