From a746fe32cd362c8bba523a97123129ede4f5b75a Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Thu, 25 Feb 2021 20:20:33 +0530 Subject: scripts: kernel-doc: fix typedef support for struct/union parsing Currently, there are ~1290 occurrences in 447 files in the kernel tree 'typedef struct/union' syntax for defining some struct/union. However, kernel-doc currently does not support that syntax. Of the ~1290 occurrences, there are four occurrences in ./include/linux/zstd.h with typedef struct/union syntax and a preceding kernel-doc; all other occurrences have no preceding kernel-doc. Add support for parsing struct/union following this syntax. Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210225145033.11431-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8b5bc7bf4bb8..68df17877384 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1201,12 +1201,23 @@ sub dump_union($$) { sub dump_struct($$) { my $x = shift; my $file = shift; + my $decl_type; + my $members; + my $type = qr{struct|union}; + # For capturing struct/union definition body, i.e. "{members*}qualifiers*" + my $definition_body = qr{\{(.*)\}(?:\s*(?:__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*}; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { - my $decl_type = $1; + if ($x =~ /($type)\s+(\w+)\s*$definition_body/) { + $decl_type = $1; $declaration_name = $2; - my $members = $3; + $members = $3; + } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) { + $decl_type = $1; + $declaration_name = $3; + $members = $2; + } + if ($members) { if ($identifier ne $declaration_name) { print STDERR "${file}:$.: warning: expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n"; return; -- cgit v1.2.3 From 52178ce01335d9d76611c3a5198b8778cb9b03f5 Mon Sep 17 00:00:00 2001 From: Dwaipayan Ray Date: Fri, 26 Feb 2021 15:08:26 +0530 Subject: checkpatch: add verbose mode Add a new verbose mode to checkpatch.pl to emit additional verbose test descriptions. The verbose mode is optional and can be enabled by the flag -v or --verbose. The test descriptions are parsed from the checkpatch documentation file at `Documentation/dev-tools/checkpatch.rst`. The test descriptions in the docs are kept in a fixed format grouped by usage. Some examples of this format are: **LINE_SPACING** Vertical space is wasted given the limited number of lines an editor window can display when multiple blank lines are used. **MISSING_SIGN_OFF** The patch is missing a Signed-off-by line. A signed-off-by line should be added according to Developer's certificate of Origin. To avoid lengthy output, the verbose description is printed only for the first instance of a particular message type. The --verbose option cannot be used along with the --terse option. Verbose mode can be used with the --list-types option. The --list-types output also supports color coding now. Signed-off-by: Dwaipayan Ray Link: https://lore.kernel.org/r/20210226093827.12700-3-dwaipayanray1@gmail.com Signed-off-by: Jonathan Corbet --- scripts/checkpatch.pl | 133 ++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 113 insertions(+), 20 deletions(-) (limited to 'scripts') diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index df8b23dc1eb0..f42e5ba16d9b 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -23,6 +23,9 @@ my $V = '0.32'; use Getopt::Long qw(:config no_auto_abbrev); my $quiet = 0; +my $verbose = 0; +my %verbose_messages = (); +my %verbose_emitted = (); my $tree = 1; my $chk_signoff = 1; my $chk_patch = 1; @@ -61,6 +64,7 @@ my $spelling_file = "$D/spelling.txt"; my $codespell = 0; my $codespellfile = "/usr/share/codespell/dictionary.txt"; my $conststructsfile = "$D/const_structs.checkpatch"; +my $docsfile = "$D/../Documentation/dev-tools/checkpatch.rst"; my $typedefsfile; my $color = "auto"; my $allow_c99_comments = 1; # Can be overridden by --ignore C99_COMMENT_TOLERANCE @@ -78,6 +82,7 @@ Version: $V Options: -q, --quiet quiet + -v, --verbose verbose mode --no-tree run without a kernel tree --no-signoff do not check for 'Signed-off-by' line --patch treat FILE as patchfile (default) @@ -158,15 +163,51 @@ sub list_types { my $text = <$script>; close($script); - my @types = (); + my %types = (); # Also catch when type or level is passed through a variable - for ($text =~ /(?:(?:\bCHK|\bWARN|\bERROR|&\{\$msg_level})\s*\(|\$msg_type\s*=)\s*"([^"]+)"/g) { - push (@types, $_); + while ($text =~ /(?:(\bCHK|\bWARN|\bERROR|&\{\$msg_level})\s*\(|\$msg_type\s*=)\s*"([^"]+)"/g) { + if (defined($1)) { + if (exists($types{$2})) { + $types{$2} .= ",$1" if ($types{$2} ne $1); + } else { + $types{$2} = $1; + } + } else { + $types{$2} = "UNDETERMINED"; + } } - @types = sort(uniq(@types)); + print("#\tMessage type\n\n"); - foreach my $type (@types) { + if ($color) { + print(" ( Color coding: "); + print(RED . "ERROR" . RESET); + print(" | "); + print(YELLOW . "WARNING" . RESET); + print(" | "); + print(GREEN . "CHECK" . RESET); + print(" | "); + print("Multiple levels / Undetermined"); + print(" )\n\n"); + } + + foreach my $type (sort keys %types) { + my $orig_type = $type; + if ($color) { + my $level = $types{$type}; + if ($level eq "ERROR") { + $type = RED . $type . RESET; + } elsif ($level eq "WARN") { + $type = YELLOW . $type . RESET; + } elsif ($level eq "CHK") { + $type = GREEN . $type . RESET; + } + } print(++$count . "\t" . $type . "\n"); + if ($verbose && exists($verbose_messages{$orig_type})) { + my $message = $verbose_messages{$orig_type}; + $message =~ s/\n/\n\t/g; + print("\t" . $message . "\n\n"); + } } exit($exitcode); @@ -198,6 +239,46 @@ if (-f $conf) { unshift(@ARGV, @conf_args) if @conf_args; } +sub load_docs { + open(my $docs, '<', "$docsfile") + or warn "$P: Can't read the documentation file $docsfile $!\n"; + + my $type = ''; + my $desc = ''; + my $in_desc = 0; + + while (<$docs>) { + chomp; + my $line = $_; + $line =~ s/\s+$//; + + if ($line =~ /^\s*\*\*(.+)\*\*$/) { + if ($desc ne '') { + $verbose_messages{$type} = trim($desc); + } + $type = $1; + $desc = ''; + $in_desc = 1; + } elsif ($in_desc) { + if ($line =~ /^(?:\s{4,}|$)/) { + $line =~ s/^\s{4}//; + $desc .= $line; + $desc .= "\n"; + } else { + $verbose_messages{$type} = trim($desc); + $type = ''; + $desc = ''; + $in_desc = 0; + } + } + } + + if ($desc ne '') { + $verbose_messages{$type} = trim($desc); + } + close($docs); +} + # Perl's Getopt::Long allows options to take optional arguments after a space. # Prevent --color by itself from consuming other arguments foreach (@ARGV) { @@ -208,6 +289,7 @@ foreach (@ARGV) { GetOptions( 'q|quiet+' => \$quiet, + 'v|verbose!' => \$verbose, 'tree!' => \$tree, 'signoff!' => \$chk_signoff, 'patch!' => \$chk_patch, @@ -247,13 +329,27 @@ GetOptions( help(0) if ($help); +die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix)); +die "$P: --verbose cannot be used with --terse\n" if ($verbose && $terse); + +if ($color =~ /^[01]$/) { + $color = !$color; +} elsif ($color =~ /^always$/i) { + $color = 1; +} elsif ($color =~ /^never$/i) { + $color = 0; +} elsif ($color =~ /^auto$/i) { + $color = (-t STDOUT); +} else { + die "$P: Invalid color mode: $color\n"; +} + +load_docs() if ($verbose); list_types(0) if ($list_types); $fix = 1 if ($fix_inplace); $check_orig = $check; -die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix)); - my $exit = 0; my $perl_version_ok = 1; @@ -268,18 +364,6 @@ if ($#ARGV < 0) { push(@ARGV, '-'); } -if ($color =~ /^[01]$/) { - $color = !$color; -} elsif ($color =~ /^always$/i) { - $color = 1; -} elsif ($color =~ /^never$/i) { - $color = 0; -} elsif ($color =~ /^auto$/i) { - $color = (-t STDOUT); -} else { - die "$P: Invalid color mode: $color\n"; -} - # skip TAB size 1 to avoid additional checks on $tabsize - 1 die "$P: Invalid TAB size: $tabsize\n" if ($tabsize < 2); @@ -2209,7 +2293,16 @@ sub report { splice(@lines, 1, 1); $output = join("\n", @lines); } - $output = (split('\n', $output))[0] . "\n" if ($terse); + + if ($terse) { + $output = (split('\n', $output))[0] . "\n"; + } + + if ($verbose && exists($verbose_messages{$type}) && + !exists($verbose_emitted{$type})) { + $output .= $verbose_messages{$type} . "\n\n"; + $verbose_emitted{$type} = 1; + } push(our @report, $output); -- cgit v1.2.3 From 084aa00162bda02bcab501c2b0a0ea9252d291b2 Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Sat, 6 Mar 2021 17:05:10 +0530 Subject: scripts: kernel-doc: fix attribute capture in function parsing Currently, kernel-doc warns for function prototype parsing on the presence of attributes "__attribute_const__" and "__flatten" in the definition. There are 166 occurrences in ~70 files in the kernel tree for "__attribute_const__" and 5 occurrences in 4 files for "__flatten". Out of 166, there are 3 occurrences in three different files with "__attribute_const__" and a preceding kernel-doc; and, 1 occurrence in ./mm/percpu.c for "__flatten" with a preceding kernel-doc. All other occurrences have no preceding kernel-doc. Add support for "__attribute_const__" and "__flatten" attributes. A quick evaluation by running 'kernel-doc -none' on kernel-tree reveals that no additional warning or error has been added or removed by the fix. Suggested-by: Lukas Bulwahn Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210306113510.31023-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 68df17877384..e1e562b2e2e7 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1766,12 +1766,14 @@ sub dump_function($$) { $prototype =~ s/^noinline +//; $prototype =~ s/__init +//; $prototype =~ s/__init_or_module +//; + $prototype =~ s/__flatten +//; $prototype =~ s/__meminit +//; $prototype =~ s/__must_check +//; $prototype =~ s/__weak +//; $prototype =~ s/__sched +//; $prototype =~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; my $define = $prototype =~ s/^#\s*define\s+//; #ak added + $prototype =~ s/__attribute_const__ +//; $prototype =~ s/__attribute__\s*\(\( (?: [\w\s]++ # attribute name -- cgit v1.2.3 From 0b54c2e34be7987b5e0ffc0aa0e7dced7301cc1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 3 Mar 2021 09:42:14 +0100 Subject: scripts/kernel-doc: ignore identifier on anonymous enums When anonymous enums are used, the identifier is empty. While, IMO, it should be avoided the usage of such enums, adding support for it is not hard. So, postpone the check for empty identifiers to happen only at the dump phase. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/055ad57879f1b9381b90879e00f72fde1c3a5647.1614760910.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e1e562b2e2e7..cb92d0e1e932 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1412,9 +1412,14 @@ sub dump_enum($$) { if ($members) { if ($identifier ne $declaration_name) { - print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; + if ($identifier eq "") { + print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; + } else { + print STDERR "${file}:$.: warning: expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n"; + } return; } + $declaration_name = "(anonymous)" if ($declaration_name eq ""); my %_members; @@ -2134,7 +2139,7 @@ sub process_name($$) { ++$warnings; } - if ($identifier eq "") { + if ($identifier eq "" && $decl_type ne "enum") { print STDERR "${file}:$.: warning: wrong kernel-doc identifier on line:\n"; print STDERR $_; ++$warnings; -- cgit v1.2.3 From 8d295fbad687a61eaa0cf14958c284a3ddbf2173 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 19:14:25 +0100 Subject: kernel-doc: better handle '::' sequences Right now, if one of the following headers end with a '::', the kernel-doc script will do the wrong thing: description|context|returns?|notes?|examples? The real issue is with examples, as people could try to write something like: example:: /* Some C code */ and this won't be properly evaluated. So, improve the regex to not catch '\w+::' regex for the above identifiers. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/2cf44cf1fa42588632735d4fbc8e84304bdc235f.1616696051.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cb92d0e1e932..0ecd71477a16 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -392,7 +392,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; -- cgit v1.2.3 From 212209cff89fe497bc47abcd017aa95e4e8a5196 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 26 Mar 2021 13:16:35 -0600 Subject: docs: kernel-doc: properly recognize parameter lines with colons The previous attempt to properly handle literal blocks broke parsing of parameter lines containing colons; fix it by tweaking the regex to specifically exclude the "::" pattern while accepting lines containing colons in general. Add a little documentation to the regex while in the neighborhood. Reported-by: Stephen Rothwell Fixes: 8d295fbad687 ("kernel-doc: better handle '::' sequences") Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 0ecd71477a16..d6d2b6e0b4eb 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -391,8 +391,14 @@ my $doc_com = '\s*\*\s*'; my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names +# Specifically: +# Match @word: +# @...: +# @{section-name}: +# while trying to not match literal block starts like "example::" +# my $doc_sect = $doc_com . - '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:]*)$'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; -- cgit v1.2.3 From 3e58e839150db0857dfcb3a0bb3d4af4c6ac1abf Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Mon, 29 Mar 2021 14:59:45 +0530 Subject: scripts: kernel-doc: add warning for comment not following kernel-doc syntax Currently, kernel-doc start parsing the comment as a kernel-doc comment if it starts with '/**', but does not take into account if the content inside the comment too, adheres with the expected format. This results in unexpected and unclear warnings for the user. E.g., running scripts/kernel-doc -none mm/memcontrol.c emits: "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead" Here kernel-doc parses the corresponding comment as a kernel-doc comment and expects prototype for it in the next lines, and as a result causing this warning. Provide a clearer warning message to the users regarding the same, if the content inside the comment does not follow the kernel-doc expected format. Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210329092945.13152-1-yashsri421@gmail.com Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index d6d2b6e0b4eb..888913528185 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2109,15 +2109,17 @@ sub process_name($$) { } } elsif (/$doc_decl/o) { $identifier = $1; - if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { + my $is_kernel_comment = 0; + if (/^\s*\*\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { $identifier = $1; + $decl_type = 'function'; + $identifier =~ s/^define\s+//; + $is_kernel_comment = 1; } if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { $decl_type = $1; $identifier = $2; - } else { - $decl_type = 'function'; - $identifier =~ s/^define\s+//; + $is_kernel_comment = 1; } $identifier =~ s/\s+$//; @@ -2139,6 +2141,13 @@ sub process_name($$) { $declaration_purpose = ""; } + if (!$is_kernel_comment) { + print STDERR "${file}:$.: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n"; + print STDERR $_; + ++$warnings; + $state = STATE_NORMAL; + } + if (($declaration_purpose eq "") && $verbose) { print STDERR "${file}:$.: warning: missing initial short description on line:\n"; print STDERR $_; -- cgit v1.2.3 From b0f9580a88803472d7c05d89365902a64f076df4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 11:38:22 +0100 Subject: scripts: get_abi.pl: better handle escape chars on what: The parser for the symbols defined on What: doesn't cover all chars that need to be scaped, like '{' and '}'. Change the logic to be more generic, and ensure that the same regex will be used on both What: and when parsing the cross-references. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/29cb56def89b508fe605bcd2ba74a4376cc08e35.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_abi.pl | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 92d9aa6cc4f5..a9348b9bdaa4 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -283,6 +283,7 @@ sub create_labels { # \b doesn't work well with paths. So, we need to define something else my $bondary = qr { (? $len); } @@ -395,7 +396,7 @@ sub output_rest { if (defined($data{$s}) && defined($data{$s}->{label})) { my $xref = $s; - $xref =~ s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + $xref =~ s/$symbols/\\$1/g; $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; $desc =~ s,$bondary$s$bondary,$xref,g; -- cgit v1.2.3 From d3e6b2235e46a34f3d6b08283d1a817aeff0c757 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 11:38:23 +0100 Subject: get_abi.pl: seek for all occurrences for Documentation/ABI Instead of retrieving just one match at most, ensure that the entire description will be parsed. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/17019b73e106d1b1b353b8880ed189bad3604c13.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_abi.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index a9348b9bdaa4..3c82cd188368 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -380,7 +380,7 @@ sub output_rest { $desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; - my @matches = $desc =~ m,Documentation/ABI/([\w\/\-]+),; + my @matches = $desc =~ m,Documentation/ABI/([\w\/\-]+),g; foreach my $f (@matches) { my $xref = $f; my $path = $f; -- cgit v1.2.3 From 50ebf8f4933ec27f0dc8c3b46c72894b14de0018 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 11:38:24 +0100 Subject: get_abi.pl: fix xref boundaries There are some issues with the regex that seeks for What: cross references: basically, it is mis-identifying the start and the end boundaries of the regex, which causes :ref: to be inseerted for the wrong symbols at the wrong places. Fix it. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/79a14d2518499b76931b5f29c50979987108152d.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_abi.pl | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 3c82cd188368..e87028257d1c 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -281,8 +281,11 @@ sub create_labels { # Outputs the book on ReST format # -# \b doesn't work well with paths. So, we need to define something else -my $bondary = qr { (?{label})) { my $xref = $s; $xref =~ s/$symbols/\\$1/g; $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; - $desc =~ s,$bondary$s$bondary,$xref,g; + $desc =~ s,$start$s$bondary,$1$xref$2,g; } } -- cgit v1.2.3 From 87ec9ea1fc27a6475ef09cf221c42943fa418f47 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 11:38:25 +0100 Subject: scripts: get_abi.pl: extend xref match to other types Currently, there are "What:" symbols for more than just /sys. Extend the regex to also cover configfs, /proc /dev and /kvd symbols. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/a1c7e2b2c37ed6e111dfc8641deb37ed96375a63.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_abi.pl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index e87028257d1c..eb1a23103afa 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -285,7 +285,7 @@ sub create_labels { # Boundaries are punct characters, spaces and end-of-line my $start = qr {(^|\s|\() }x; my $bondary = qr { ([,.:;\)\s]|\z) }x; -my $xref_match = qr { $start(\/sys\/[^,.:;\)\s]+)$bondary }x; +my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x; my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x; sub output_rest { -- cgit v1.2.3 From c27c2e34412f8ca36ed1d8beb248d132aaf0016a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 11:38:26 +0100 Subject: scripts: get_abi.pl: parse description line per line Change the description parsing logic in rst mode in order to parse it line per line. The end result is the same, but doing line per line allows to add some code to escape literal blocks when seeking for cross-references. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/d33cfa2e59ecf8f28d4ed7de7402468cf2168921.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_abi.pl | 49 ++++++++++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 21 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index eb1a23103afa..e5d1da492c1e 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -381,34 +381,41 @@ sub output_rest { # Enrich text by creating cross-references - $desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; - - my @matches = $desc =~ m,Documentation/ABI/([\w\/\-]+),g; - foreach my $f (@matches) { - my $xref = $f; - my $path = $f; - $path =~ s,.*/(.*/.*),$1,;; - $path =~ s,[/\-],_,g;; - $xref .= " "; - $desc =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; - } + my $new_desc = ""; + open(my $fh, "+<", \$desc); + while (my $d = <$fh>) { + $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; + + my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g; + foreach my $f (@matches) { + my $xref = $f; + my $path = $f; + $path =~ s,.*/(.*/.*),$1,;; + $path =~ s,[/\-],_,g;; + $xref .= " "; + $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; + } - # Seek for cross reference symbols like /sys/... - @matches = $desc =~ m/$xref_match/g; + # Seek for cross reference symbols like /sys/... + @matches = $d =~ m/$xref_match/g; - foreach my $s (@matches) { - next if (!($s =~ m,/,)); - if (defined($data{$s}) && defined($data{$s}->{label})) { - my $xref = $s; + foreach my $s (@matches) { + next if (!($s =~ m,/,)); + if (defined($data{$s}) && defined($data{$s}->{label})) { + my $xref = $s; - $xref =~ s/$symbols/\\$1/g; - $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; + $xref =~ s/$symbols/\\$1/g; + $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; - $desc =~ s,$start$s$bondary,$1$xref$2,g; + $d =~ s,$start$s$bondary,$1$xref$2,g; + } } + $new_desc .= $d; } + close $fh; + - print "$desc\n\n"; + print "$new_desc\n\n"; } else { $desc =~ s/^\s+//; -- cgit v1.2.3 From 2ae7bb570e5d8b2da4b281fe7fae5c3de411f287 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 25 Mar 2021 11:38:27 +0100 Subject: scripts: get_abi: ignore code blocks for cross-references The script should not generate cross-references inside literal blocks. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/a590f994f8a5742db333bde69e88241a080e4fe0.1616668017.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/get_abi.pl | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index e5d1da492c1e..d7aa82094296 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -382,8 +382,27 @@ sub output_rest { # Enrich text by creating cross-references my $new_desc = ""; + my $init_indent = -1; + my $literal_indent = -1; + open(my $fh, "+<", \$desc); while (my $d = <$fh>) { + my $indent = $d =~ m/^(\s+)/; + my $spaces = length($indent); + $init_indent = $indent if ($init_indent < 0); + if ($literal_indent >= 0) { + if ($spaces > $literal_indent) { + $new_desc .= $d; + next; + } else { + $literal_indent = -1; + } + } else { + if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) { + $literal_indent = $spaces; + } + } + $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g; -- cgit v1.2.3 From f9bbc12ccb35ac8b3fa01cec1a19cb523a7707c7 Mon Sep 17 00:00:00 2001 From: Aditya Srivastava Date: Thu, 15 Apr 2021 00:55:29 +0530 Subject: scripts: kernel-doc: improve parsing for kernel-doc comments syntax Currently kernel-doc does not identify some cases of probable kernel doc comments, for e.g. pointer used as declaration type for identifier, space separated identifier, etc. Some example of these cases in files can be: i)" * journal_t * jbd2_journal_init_dev() - creates and initialises a journal structure" in fs/jbd2/journal.c ii) "* dget, dget_dlock - get a reference to a dentry" in include/linux/dcache.h iii) " * DEFINE_SEQLOCK(sl) - Define a statically allocated seqlock_t" in include/linux/seqlock.h Also improve identification for non-kerneldoc comments. For e.g., i) " * The following functions allow us to read data using a swap map" in kernel/power/swap.c does follow the kernel-doc like syntax, but the content inside does not adheres to the expected format. Improve parsing by adding support for these probable attempts to write kernel-doc comment. Suggested-by: Jonathan Corbet Link: https://lore.kernel.org/lkml/87mtujktl2.fsf@meer.lwn.net Signed-off-by: Aditya Srivastava Link: https://lore.kernel.org/r/20210414192529.9080-1-yashsri421@gmail.com [ jc: fixed some line-length issues ] Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 888913528185..2a85d34fdcd0 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2110,17 +2110,28 @@ sub process_name($$) { } elsif (/$doc_decl/o) { $identifier = $1; my $is_kernel_comment = 0; - if (/^\s*\*\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) { + my $decl_start = qr{\s*\*}; + # test for pointer declaration type, foo * bar() - desc + my $fn_type = qr{\w+\s*\*\s*}; + my $parenthesis = qr{\(\w*\)}; + my $decl_end = qr{[-:].*}; + if (/^$decl_start\s*([\w\s]+?)$parenthesis?\s*$decl_end?$/) { $identifier = $1; - $decl_type = 'function'; - $identifier =~ s/^define\s+//; - $is_kernel_comment = 1; } if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) { $decl_type = $1; $identifier = $2; $is_kernel_comment = 1; } + # Look for foo() or static void foo() - description; or misspelt + # identifier + elsif (/^$decl_start\s*$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ || + /^$decl_start\s*$fn_type?(\w+.*)$parenthesis?\s*$decl_end$/) { + $identifier = $1; + $decl_type = 'function'; + $identifier =~ s/^define\s+//; + $is_kernel_comment = 1; + } $identifier =~ s/\s+$//; $state = STATE_BODY; -- cgit v1.2.3 From e9dfeed2518671e94779a6103301cded67fae0e2 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 15 Apr 2021 16:01:50 -0600 Subject: docs: sphinx-pre-install: don't barf on beta Sphinx releases sphinx-pre-install is picky when it comes to parsing sphinx versions; it failed when run with sphinx 4.0.0b1. Tweak the regex to tolerate a trailing "bN" on the version number. Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index b5f9fd5b2880..fe92020d67e3 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -259,7 +259,7 @@ sub get_sphinx_version($) open IN, "$cmd --version 2>&1 |"; while () { - if (m/^\s*sphinx-build\s+([\d\.]+)(\+\/[\da-f]+)?$/) { + if (m/^\s*sphinx-build\s+([\d\.]+)((\+\/[\da-f]+)|(b\d+))?$/) { $ver=$1; last; } -- cgit v1.2.3