Skip to contentSkip to conversation

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

PATCH In review Jason Gunthorpe 4 participants 7 messages Nov 8, 2022 – Nov 9, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

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

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

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

scripts/kernel-doc +8 -4
index aea04365bc69d3..48e3feca31701a 100755
@@ -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

Signature · 1 line
2.38.1
#1 lore raw
Quoted 3 lines · Jason Gunthorpe

(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.

#2 lore raw
Quoted 11 lines · Matthew Wilcox
Quoted 3 lines · Jason Gunthorpe

(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:

(quoted diff) +1 -1
-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

#3 lore raw
Quoted 15 lines · Jason Gunthorpe
Quoted 11 lines · Matthew Wilcox
Quoted 3 lines · Jason Gunthorpe

(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:

(quoted diff) +1 -1
-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:

Quoted 5 lines

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*;';

#4 lore raw
Quoted 18 lines · Matthew Wilcox
Quoted 17 lines · Jason Gunthorpe
Quoted 11 lines · Matthew Wilcox
Quoted 3 lines · Jason Gunthorpe

(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:

(quoted diff) +1 -1
-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);

Quoted 8 lines
Quoted 3 lines

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

#5 lore raw
In reply to Jason Gunthorpe
Quoted 13 lines · Jason Gunthorpe

Only output documentation for the symbols that have been exported using

scripts/kernel-doc +2 -2
-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

scripts/kernel-doc Do not output DOC: sections. · line 2460

Quoted 7 lines
scripts/kernel-doc +1 -2
@@ -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?

Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#6 lore raw
Quoted 7 lines · Bagas Sanjaya

scripts/kernel-doc Do not output DOC: sections. · line 2459

Quoted 4 lines
scripts/kernel-doc +1 -2
-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.

Quoted 1 line

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