[PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Jason Gunthorpe]

Parse EXPORT_SYMBOL_NS_GPL() in addition to EXPORT_SYMBOL_GPL() for use
with the -export flag.

Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
---
 scripts/kernel-doc | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

The new iommufd kdocs need this because they are using:

.. kernel-doc:: drivers/iommu/iommufd/device.c
   :export:

And also symbol namespaces for those functions.

I'd like to send it through the iommufd tree with an ack, thanks

(I don't know perl at all so happy to replace this with something more elegant)

Thanks,
Jason

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index aea04365bc69d3..48e3feca31701a 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -256,6 +256,7 @@ my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
+my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*\w+\)\s*;';
 my $function_pointer = qr{([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)};
 my $attribute = qr{__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)}i;
 
@@ -1948,6 +1949,10 @@ sub process_export_file($) {
 	    next if (defined($nosymbol_table{$2}));
 	    $function_table{$2} = 1;
 	}
+	if (/$export_symbol_ns/) {
+	    next if (defined($nosymbol_table{$2}));
+	    $function_table{$2} = 1;
+	}
     }
 
     close(IN);
@@ -2419,12 +2424,12 @@ found on PATH.
 =item -export
 
 Only output documentation for the symbols that have been exported using
-EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
 
 =item -internal
 
 Only output documentation for the symbols that have NOT been exported using
-EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
+EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
 
 =item -function NAME
 
@@ -2451,8 +2456,7 @@ Do not output DOC: sections.
 
 =item -export-file FILE
 
-Specify an additional FILE in which to look for EXPORT_SYMBOL() and
-EXPORT_SYMBOL_GPL().
+Specify an additional FILE in which to look for EXPORT_SYMBOL information.
 
 To be used with -export or -internal.
 

base-commit: a21945d88e38b5772958161b3a5ee4e2adaa1f61
-- 
2.38.1

Re: [PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Matthew Wilcox]

On Tue, Nov 08, 2022 at 11:02:35AM -0400, Jason Gunthorpe wrote:
> (I don't know perl at all so happy to replace this with something more elegant)
>  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> +my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*\w+\)\s*;';

How about:

-my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
+my $export_symbol = '^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';

Not them i'm a perlite either, but this is just a regexp.

Re: [PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Jason Gunthorpe]

On Tue, Nov 08, 2022 at 03:25:10PM +0000, Matthew Wilcox wrote:
> On Tue, Nov 08, 2022 at 11:02:35AM -0400, Jason Gunthorpe wrote:
> > (I don't know perl at all so happy to replace this with something more elegant)
> >  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > +my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*\w+\)\s*;';
> 
> How about:
> 
> -my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> +my $export_symbol = '^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> 
> Not them i'm a perlite either, but this is just a regexp.

I started like that, but the target text looks like this:

EXPORT_SYMBOL_NS_GPL(iommufd_access_destroy, IOMMUFD);

And the (\w+) capture should only pick "iommufd_access_destroy", so
the ideal regex does the ",\s*\w+)" part only if _NS was matched
earlier.

Jason

Re: [PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Matthew Wilcox]

On Tue, Nov 08, 2022 at 12:21:17PM -0400, Jason Gunthorpe wrote:
> On Tue, Nov 08, 2022 at 03:25:10PM +0000, Matthew Wilcox wrote:
> > On Tue, Nov 08, 2022 at 11:02:35AM -0400, Jason Gunthorpe wrote:
> > > (I don't know perl at all so happy to replace this with something more elegant)
> > >  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > > +my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*\w+\)\s*;';
> > 
> > How about:
> > 
> > -my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > +my $export_symbol = '^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > 
> > Not them i'm a perlite either, but this is just a regexp.
> 
> I started like that, but the target text looks like this:
> 
> EXPORT_SYMBOL_NS_GPL(iommufd_access_destroy, IOMMUFD);
> 
> And the (\w+) capture should only pick "iommufd_access_destroy", so
> the ideal regex does the ",\s*\w+)" part only if _NS was matched
> earlier.

Oh, right, I missed that part of the regex difference.  How about
terminating the match with [,)]?  ie:

+my $export_symbol = '^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+[,)]\s*\)\s*;';

Re: [PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Jason Gunthorpe]

On Tue, Nov 08, 2022 at 05:13:28PM +0000, Matthew Wilcox wrote:
> On Tue, Nov 08, 2022 at 12:21:17PM -0400, Jason Gunthorpe wrote:
> > On Tue, Nov 08, 2022 at 03:25:10PM +0000, Matthew Wilcox wrote:
> > > On Tue, Nov 08, 2022 at 11:02:35AM -0400, Jason Gunthorpe wrote:
> > > > (I don't know perl at all so happy to replace this with something more elegant)
> > > >  my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > > > +my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*\(\s*(\w+)\s*,\s*\w+\)\s*;';
> > > 
> > > How about:
> > > 
> > > -my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > > +my $export_symbol = '^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
> > > 
> > > Not them i'm a perlite either, but this is just a regexp.
> > 
> > I started like that, but the target text looks like this:
> > 
> > EXPORT_SYMBOL_NS_GPL(iommufd_access_destroy, IOMMUFD);
> > 
> > And the (\w+) capture should only pick "iommufd_access_destroy", so
> > the ideal regex does the ",\s*\w+)" part only if _NS was matched
> > earlier.
> 
> Oh, right, I missed that part of the regex difference.  How about
> terminating the match with [,)]?  ie:
> 
> +my $export_symbol = '^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+[,)]\s*\)\s*;';

Ah, I came up with this ugly thing:

^\s*EXPORT_SYMBOL(_NS)?(_GPL)?\s*\(\s*(\w+?)(\s*,\s*\w+)?\s*\)\s*;

As there is still some trailing \w that the \s won't match.

Jason

Re: [PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Bagas Sanjaya]

On 11/8/22 22:02, Jason Gunthorpe wrote:
>  Only output documentation for the symbols that have been exported using
> -EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
> +EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
>  
>  =item -internal
>  
>  Only output documentation for the symbols that have NOT been exported using
> -EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() in any input FILE or -export-file FILE.
> +EXPORT_SYMBOL() and related macros in any input FILE or -export-file FILE.
>  
>  =item -function NAME
>  
> @@ -2451,8 +2456,7 @@ Do not output DOC: sections.
>  
>  =item -export-file FILE
>  
> -Specify an additional FILE in which to look for EXPORT_SYMBOL() and
> -EXPORT_SYMBOL_GPL().
> +Specify an additional FILE in which to look for EXPORT_SYMBOL information.
> 

For consistency, what about "Specify an additional FILE in which to look for
EXPORT_SYMBOL() and related macros."
 
Anyway, what are EXPORT_SYMBOL_NS{,_GPL}() macros?

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH] scripts/kernel-doc: support EXPORT_SYMBOL_NS_GPL() with -export

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

>> -Specify an additional FILE in which to look for EXPORT_SYMBOL() and
>> -EXPORT_SYMBOL_GPL().
>> +Specify an additional FILE in which to look for EXPORT_SYMBOL information.
>> 
>
> For consistency, what about "Specify an additional FILE in which to look for
> EXPORT_SYMBOL() and related macros."

Nobody runs kernel-doc by hand except for a few of us trying to figure
out some weirdness.  We really don't need nit-picking here.  Please (for
the Nth time) stop adding unnecessary friction for our contributors.

> Anyway, what are EXPORT_SYMBOL_NS{,_GPL}() macros?

Somebody who tries to come across as the authoritative master of patch
style should know that.  Maybe try reading the docs? :)

jon