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: <213c918b-b4aa-4174-af89-a4d17e8c30dc@infradead.org>
Date: Thu, 23 Oct 2025 23:06:00 -0700
From: Randy Dunlap <rdunlap@...radead.org>
To: "Li, Fei1" <fei1.li@...el.com>,
 "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>

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?
If that's what you mean, that's not valid kernel-doc notation.

> 
>> + * @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