[PATCH net-next 0/2] Fix invalid kernel-doc warnings

[PATCH net-next 0/2] Fix invalid kernel-doc warnings

[Pavan Kumar Linga]

kernel-doc reports invalid warnings on IDPF driver patch series [1]
that is submitted for review. This patch series fixes those warnings.

[1]: https://lore.kernel.org/netdev/20230808003416.3805142-1-anthony.l.nguyen@intel.com/
---
These fixes are needed for the IDPF driver patch series to have
a clean CI. So targeting the series to net-next instead of
linux-docs.
---
Pavan Kumar Linga (2):
  scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]
  scripts: kernel-doc: fix macro handling in enums

 scripts/kernel-doc | 5 +++++
 1 file changed, 5 insertions(+)

-- 
2.38.1

[PATCH net-next 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

[Pavan Kumar Linga]

At present, if the marcos DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN() are used in the structures as shown
below, instead of parsing the parameter in the parenthesis,
kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and
'DEFINE_DMA_UNMAP_LEN(' which results in the following
warnings:

drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in
'idpf_tx_buf'
drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in
'idpf_tx_buf'

struct idpf_tx_buf {
	DEFINE_DMA_UNMAP_ADDR(dma);
	DEFINE_DMA_UNMAP_LEN(len);
};

Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and
DEFINE_DMA_UNMAP_LEN().

Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
---
 scripts/kernel-doc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index d0116c6939dc..cfb1cb223508 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1168,6 +1168,10 @@ sub dump_struct($$) {
 	$members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
 	# replace DECLARE_FLEX_ARRAY
 	$members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
+	#replace DEFINE_DMA_UNMAP_ADDR
+	$members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos;
+	#replace DEFINE_DMA_UNMAP_LEN
+	$members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos;
 	my $declaration = $members;
 
 	# Split nested struct/union elements as newer ones
-- 
2.38.1

Re: [PATCH net-next 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

[Randy Dunlap]

On 8/11/23 17:25, Pavan Kumar Linga wrote:
> At present, if the marcos DEFINE_DMA_UNMAP_ADDR() and

                     macros

> DEFINE_DMA_UNMAP_LEN() are used in the structures as shown
> below, instead of parsing the parameter in the parenthesis,

                                                 parentheses

> kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and
> 'DEFINE_DMA_UNMAP_LEN(' which results in the following
> warnings:
> 
> drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
> parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in
> 'idpf_tx_buf'
> drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
> parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in
> 'idpf_tx_buf'
> 
> struct idpf_tx_buf {
> 	DEFINE_DMA_UNMAP_ADDR(dma);
> 	DEFINE_DMA_UNMAP_LEN(len);
> };
> 
> Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and
> DEFINE_DMA_UNMAP_LEN().
> 
> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>

Looks good. Thanks.
Acked-by: Randy Dunlap <rdunlap@infradead.org>

> ---
>  scripts/kernel-doc | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index d0116c6939dc..cfb1cb223508 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -1168,6 +1168,10 @@ sub dump_struct($$) {
>  	$members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
>  	# replace DECLARE_FLEX_ARRAY
>  	$members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
> +	#replace DEFINE_DMA_UNMAP_ADDR
> +	$members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos;
> +	#replace DEFINE_DMA_UNMAP_LEN
> +	$members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos;
>  	my $declaration = $members;
>  
>  	# Split nested struct/union elements as newer ones

-- 
~Randy

Re: [PATCH net-next 1/2] scripts: kernel-doc: parse DEFINE_DMA_UNMAP_[ADDR|LEN]

[Linga, Pavan Kumar]

On 8/11/2023 9:47 PM, Randy Dunlap wrote:
> 
> 
> On 8/11/23 17:25, Pavan Kumar Linga wrote:
>> At present, if the marcos DEFINE_DMA_UNMAP_ADDR() and
> 
>                       macros
> 
>> DEFINE_DMA_UNMAP_LEN() are used in the structures as shown
>> below, instead of parsing the parameter in the parenthesis,
> 
>                                                   parentheses
> 
>> kernel-doc parses 'DEFINE_DMA_UNMAP_ADDR(' and
>> 'DEFINE_DMA_UNMAP_LEN(' which results in the following
>> warnings:
>>
>> drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
>> parameter or member 'DEFINE_DMA_UNMAP_ADDR(dma' not described in
>> 'idpf_tx_buf'
>> drivers/net/ethernet/intel/idpf/idpf_txrx.h:201: warning: Function
>> parameter or member 'DEFINE_DMA_UNMAP_LEN(len' not described in
>> 'idpf_tx_buf'
>>
>> struct idpf_tx_buf {
>> 	DEFINE_DMA_UNMAP_ADDR(dma);
>> 	DEFINE_DMA_UNMAP_LEN(len);
>> };
>>
>> Fix the warnings by parsing DEFINE_DMA_UNMAP_ADDR() and
>> DEFINE_DMA_UNMAP_LEN().
>>
>> Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
> 
> Looks good. Thanks.
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> 

Thanks for the review. Fixed the typos in the v2 revision.

>> ---
>>   scripts/kernel-doc | 4 ++++
>>   1 file changed, 4 insertions(+)
>>
>> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
>> index d0116c6939dc..cfb1cb223508 100755
>> --- a/scripts/kernel-doc
>> +++ b/scripts/kernel-doc
>> @@ -1168,6 +1168,10 @@ sub dump_struct($$) {
>>   	$members =~ s/DECLARE_KFIFO_PTR\s*\($args,\s*$args\)/$2 \*$1/gos;
>>   	# replace DECLARE_FLEX_ARRAY
>>   	$members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*\($args,\s*$args\)/$1 $2\[\]/gos;
>> +	#replace DEFINE_DMA_UNMAP_ADDR
>> +	$members =~ s/DEFINE_DMA_UNMAP_ADDR\s*\($args\)/dma_addr_t $1/gos;
>> +	#replace DEFINE_DMA_UNMAP_LEN
>> +	$members =~ s/DEFINE_DMA_UNMAP_LEN\s*\($args\)/__u32 $1/gos;
>>   	my $declaration = $members;
>>   
>>   	# Split nested struct/union elements as newer ones
> 

Regards,
Pavan

[PATCH net-next 2/2] scripts: kernel-doc: fix macro handling in enums

[Pavan Kumar Linga]

drivers/net/ethernet/intel/idpf/idpf.h uses offsetof to
initialize the enum enumerators:

enum {
	IDPF_BASE_CAPS = -1,
	IDPF_CSUM_CAPS = offsetof(struct virtchnl2_get_capabilities,
				  csum_caps),
	IDPF_SEG_CAPS = offsetof(struct virtchnl2_get_capabilities,
				 seg_caps),
	IDPF_RSS_CAPS = offsetof(struct virtchnl2_get_capabilities,
				 rss_caps),
	IDPF_HSPLIT_CAPS = offsetof(struct virtchnl2_get_capabilities,
				    hsplit_caps),
	IDPF_RSC_CAPS = offsetof(struct virtchnl2_get_capabilities,
				 rsc_caps),
	IDPF_OTHER_CAPS = offsetof(struct virtchnl2_get_capabilities,
				   other_caps),
};

kernel-doc parses the above enumerator with a ',' inside the
macro and treats 'csum_caps', 'seg_caps' etc. also as enumerators
resulting in the warnings:

drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'csum_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'seg_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'rss_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'hsplit_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'rsc_caps' not described in enum 'idpf_cap_field'
drivers/net/ethernet/intel/idpf/idpf.h:130: warning: Enum value
'other_caps' not described in enum 'idpf_cap_field'

Fix it by removing the macro arguments within the parenthesis.

Signed-off-by: Pavan Kumar Linga <pavan.kumar.linga@intel.com>
---
 scripts/kernel-doc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index cfb1cb223508..bc008f30f3c9 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -1353,6 +1353,7 @@ sub dump_enum($$) {
 	my %_members;
 
 	$members =~ s/\s+$//;
+	$members =~ s/\(.*?[\)]//g;
 
 	foreach my $arg (split ',', $members) {
 	    $arg =~ s/^\s*(\w+).*/$1/;
-- 
2.38.1

Re: [PATCH net-next 0/2] Fix invalid kernel-doc warnings

[Jakub Kicinski]

On Fri, 11 Aug 2023 17:25:47 -0700 Pavan Kumar Linga wrote:
> kernel-doc reports invalid warnings on IDPF driver patch series [1]
> that is submitted for review. This patch series fixes those warnings.
> 
> [1]: https://lore.kernel.org/netdev/20230808003416.3805142-1-anthony.l.nguyen@intel.com/
> ---
> These fixes are needed for the IDPF driver patch series to have
> a clean CI. So targeting the series to net-next instead of
> linux-docs.

Neat, thanks for these.

Jon, no strong preference on the tree here. I'll confirm these resolve
the issues in Pavan's driver when applying it, there's no hard
requirement for the kdoc patches to be in net-next at that point.