From 6b80975c6308b5dc93b270a2903a314d896974c4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Oct 2020 11:20:36 +0100 Subject: scripts: kernel-doc: fix typedef parsing The include/linux/genalloc.h file defined this typedef: typedef unsigned long (*genpool_algo_t)(unsigned long *map,unsigned long size,unsigned long start,unsigned int nr,void *data, struct gen_pool *pool, unsigned long start_addr); Because it has a type composite of two words (unsigned long), the parser gets the typedef name wrong: .. c:macro:: long **Typedef**: Allocation callback function type definition Fix the regex in order to accept composite types when defining a typedef for a function pointer. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/328e8018041cc44f7a1684e57f8d111230761c4f.1603792384.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c8f6b11d5da1..c7c9f1e8428d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1434,13 +1434,14 @@ sub dump_typedef($$) { $x =~ s@/\*.*?\*/@@gos; # strip comments. # Parse function prototypes - if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ || - $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) { + if ($x =~ /typedef((?:\s+[\w\*]+){1,8})\s*\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ || + $x =~ /typedef((?:\s+[\w\*]+\s+){1,8})\s*\*?(\w\S+)\s*\s*\((.*)\);/) { # Function typedefs $return_type = $1; $declaration_name = $2; my $args = $3; + $return_type =~ s/^\s+//; create_parameterlist($args, ',', $file, $declaration_name); -- cgit v1.2.3 From 7efc6c4295f5489e25eaef6d6fb6ceb6a6e238d0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Oct 2020 11:20:37 +0100 Subject: scripts: kernel-doc: split typedef complex regex The typedef regex for function prototypes are very complex. Split them into 3 separate regex and then join them using qr. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/3a4af999a0d62d4ab9dfae1cdefdfcad93383356.1603792384.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c7c9f1e8428d..cf71897df36d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1427,17 +1427,21 @@ sub dump_enum($$) { } } +my $typedef_type = qr { ((?:\s+[\w\*]+){1,8})\s* }x; +my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x; +my $typedef_args = qr { \s*\((.*)\); }x; + +my $typedef1 = qr { typedef$typedef_type\($typedef_ident\)$typedef_args }x; +my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x; + sub dump_typedef($$) { my $x = shift; my $file = shift; $x =~ s@/\*.*?\*/@@gos; # strip comments. - # Parse function prototypes - if ($x =~ /typedef((?:\s+[\w\*]+){1,8})\s*\(\*?\s*(\w\S+)\s*\)\s*\((.*)\);/ || - $x =~ /typedef((?:\s+[\w\*]+\s+){1,8})\s*\*?(\w\S+)\s*\s*\((.*)\);/) { - - # Function typedefs + # Parse function typedef prototypes + if ($x =~ $typedef1 || $x =~ $typedef2) { $return_type = $1; $declaration_name = $2; my $args = $3; -- cgit v1.2.3 From 72b97d0b911872ba36a5742b7d790b6b165e11d8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Oct 2020 10:51:05 +0100 Subject: scripts: kernel-doc: use :c:union when needed Sphinx C domain code after 3.2.1 will start complaning if :c:struct would be used for an union type: .../Documentation/gpu/drm-kms-helpers:352: ../drivers/video/hdmi.c:851: WARNING: C 'identifier' cross-reference uses wrong tag: reference name is 'union hdmi_infoframe' but found name is 'struct hdmi_infoframe'. Full reference name is 'union hdmi_infoframe'. Full found name is 'struct hdmi_infoframe'. So, let's address this issue too in advance, in order to avoid future issues. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/6e4ec3eec914df62389a299797a3880ae4490f35.1603791716.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cf71897df36d..f699cf05d409 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1092,7 +1092,11 @@ sub output_struct_rst(%) { print "\n\n.. c:type:: " . $name . "\n\n"; } else { my $name = $args{'struct'}; - print "\n\n.. c:struct:: " . $name . "\n\n"; + if ($args{'type'} eq 'union') { + print "\n\n.. c:union:: " . $name . "\n\n"; + } else { + print "\n\n.. c:struct:: " . $name . "\n\n"; + } } print_lineno($declaration_start_line); $lineprefix = " "; -- cgit v1.2.3 From 821f5c90130d15f8f725412d714d05df3b9e0fac Mon Sep 17 00:00:00 2001 From: Andrii Nakryiko Date: Wed, 28 Oct 2020 11:12:04 -0700 Subject: bpf: Add struct bpf_redir_neigh forward declaration to BPF helper defs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forward-declare struct bpf_redir_neigh in bpf_helper_defs.h to avoid compiler warning about unknown structs. Fixes: ba452c9e996d ("bpf: Fix bpf_redirect_neigh helper api to support supplying nexthop") Signed-off-by: Andrii Nakryiko Signed-off-by: Daniel Borkmann Acked-by: Toke Høiland-Jørgensen Link: https://lore.kernel.org/bpf/20201028181204.111241-1-andrii@kernel.org --- scripts/bpf_helpers_doc.py | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/bpf_helpers_doc.py b/scripts/bpf_helpers_doc.py index 6769caae142f..31484377b8b1 100755 --- a/scripts/bpf_helpers_doc.py +++ b/scripts/bpf_helpers_doc.py @@ -408,6 +408,7 @@ class PrinterHelpers(Printer): 'struct bpf_perf_event_data', 'struct bpf_perf_event_value', 'struct bpf_pidns_info', + 'struct bpf_redir_neigh', 'struct bpf_sock', 'struct bpf_sock_addr', 'struct bpf_sock_ops', -- cgit v1.2.3 From 11ce90a45d380f09213f128b76d68bb525186ad8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:20 +0100 Subject: scripts: get_abi.pl: change script to allow parsing in ReST mode Right now, several ABI files won't parse as ReST, as they contain severe violations to the spec, with makes the script to crash. So, the code has a sanity logic with escapes bad code and cleans tags that can cause Sphinx to crash. Add support for disabling this mode. Right now, as enabling rst-mode causes crash, it is disabled by default. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/34b691e3002e8987c24d851fe37640f95e506a92.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 72 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 47 insertions(+), 25 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index c738cb795514..107672cdacb3 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -12,8 +12,14 @@ my $man; my $debug; my $prefix="Documentation/ABI"; +# +# If true, assumes that the description is formatted with ReST +# +my $description_is_rst = 0; + GetOptions( "debug|d+" => \$debug, + "rst-source!" => \$description_is_rst, "dir=s" => \$prefix, 'help|?' => \$help, man => \$man @@ -137,14 +143,15 @@ sub parse_abi { next; } if ($tag eq "description") { - next if ($content =~ m/^\s*$/); - if ($content =~ m/^(\s*)(.*)/) { - my $new_content = $2; - $space = $new_tag . $sep . $1; - while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - $space =~ s/./ /g; - $data{$what}->{$tag} .= "$new_content\n"; + # Preserve initial spaces for the first line + $content = ' ' x length($new_tag) . $sep . $content; + $content =~ s,^(\s*):,$1 ,; + if ($content =~ m/^(\s*)(.*)$/) { + $space = $1; + $content = $2; } + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $data{$what}->{$tag} .= $content; } else { $data{$what}->{$tag} = $content; } @@ -160,11 +167,15 @@ sub parse_abi { if ($tag eq "description") { if (!$data{$what}->{description}) { - next if (m/^\s*\n/); + s/^($space)//; if (m/^(\s*)(.*)/) { - $space = $1; - while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - $data{$what}->{$tag} .= "$2\n"; + my $sp = $1; + while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + my $content = "$sp$2"; + + $content =~ s/^($space)//; + + $data{$what}->{$tag} .= "$content"; } } else { my $content = $_; @@ -274,23 +285,27 @@ sub output_rest { print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File"); my $desc = $data{$what}->{description}; - $desc =~ s/^\s+//; - - # Remove title markups from the description, as they won't work - $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; if (!($desc =~ /^\s*$/)) { - if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { - # put everything inside a code block - $desc =~ s/\n/\n /g; - - print "::\n\n"; - print " $desc\n\n"; + if ($description_is_rst) { + print "$desc\n\n"; } else { - # Escape any special chars from description - $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; + $desc =~ s/^\s+//; - print "$desc\n\n"; + # Remove title markups from the description, as they won't work + $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g; + + if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { + # put everything inside a code block + $desc =~ s/\n/\n /g; + + print "::\n\n"; + print " $desc\n\n"; + } else { + # Escape any special chars from description + $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; + print "$desc\n\n"; + } } } else { print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); @@ -382,7 +397,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B [--debug] [--man] [--help] [--dir=] [] +B [--debug] [--man] [--help] --[(no-)rst-source] [--dir=] [] Where can be: @@ -405,6 +420,13 @@ B - validate the ABI contents Changes the location of the ABI search. By default, it uses the Documentation/ABI directory. +=item B<--rst-source> and B<--no-rst-source> + +The input file may be using ReST syntax or not. Those two options allow +selecting between a rst-compliant source ABI (--rst-source), or a +plain text that may be violating ReST spec, so it requres some escaping +logic (--no-rst-source). + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple -- cgit v1.2.3 From e9bca8918e3d409f3b575d8db5591e422506c1ea Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:21 +0100 Subject: scripts: get_abi.pl: fix parsing on ReST mode When the source ABI file is using ReST notation, the script should handle whitespaces and lines with care, as otherwise the file won't be properly recognized. Address the bugs that are on such part of the script. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/5c22c54fbd0cda797b691d52c568be6d0d1079d8.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 107672cdacb3..0c403af86fd5 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -151,7 +151,8 @@ sub parse_abi { $content = $2; } while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - $data{$what}->{$tag} .= $content; + + $data{$what}->{$tag} .= "$content\n" if ($content); } else { $data{$what}->{$tag} = $content; } @@ -166,31 +167,28 @@ sub parse_abi { } if ($tag eq "description") { + my $content = $_; + while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} if (!$data{$what}->{description}) { - s/^($space)//; - if (m/^(\s*)(.*)/) { - my $sp = $1; - while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - my $content = "$sp$2"; - - $content =~ s/^($space)//; - - $data{$what}->{$tag} .= "$content"; + # Preserve initial spaces for the first line + if ($content =~ m/^(\s*)(.*)$/) { + $space = $1; + $content = $2; } + + $data{$what}->{$tag} .= "$content\n" if ($content); } else { - my $content = $_; if (m/^\s*\n/) { $data{$what}->{$tag} .= $content; next; } - while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} $space = "" if (!($content =~ s/^($space)//)); - # Compress spaces with tabs - $content =~ s<^ {8}> <\t>; - $content =~ s<^ {1,7}\t> <\t>; - $content =~ s< {1,7}\t> <\t>; +# # Compress spaces with tabs +# $content =~ s<^ {8}> <\t>; +# $content =~ s<^ {1,7}\t> <\t>; +# $content =~ s< {1,7}\t> <\t>; $data{$what}->{$tag} .= $content; } next; -- cgit v1.2.3 From 61439c4ada9fd0e4ce73aca81a71344380a3053b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:22 +0100 Subject: scripts: get_abi.pl: Allow optionally record from where a line came from The get_abi.pl reads a lot of files and can join them on a single output file. Store where each "What:" output came from, in order to be able to optionally display it. This is useful for the Sphinx extension, with can now be able to blame what ABI file has issues, and on what line the What: description with problems begin. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/befc387011c5e3c6febd285b7f27610e41c90260.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 0c403af86fd5..6a4d387ebf3b 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -10,6 +10,7 @@ use Fcntl ':mode'; my $help; my $man; my $debug; +my $enable_lineno; my $prefix="Documentation/ABI"; # @@ -19,6 +20,7 @@ my $description_is_rst = 0; GetOptions( "debug|d+" => \$debug, + "enable-lineno" => \$enable_lineno, "rst-source!" => \$description_is_rst, "dir=s" => \$prefix, 'help|?' => \$help, @@ -67,6 +69,7 @@ sub parse_abi { $data{$nametag}->{file} = $name; $data{$nametag}->{filepath} = $file; $data{$nametag}->{is_file} = 1; + $data{$nametag}->{line_no} = 1; my $type = $file; $type =~ s,.*/(.*)/.*,$1,; @@ -126,6 +129,8 @@ sub parse_abi { if ($tag ne "" && $new_tag) { $tag = $new_tag; + $data{$what}->{line_no} = $ln; + if ($new_what) { @{$data{$what}->{label}} = @labels if ($data{$nametag}->{what}); @labels = (); @@ -221,6 +226,12 @@ sub output_rest { my $file = $data{$what}->{file}; my $filepath = $data{$what}->{filepath}; + if ($enable_lineno) { + printf "#define LINENO %s%s#%s\n\n", + $prefix, $data{$what}->{file}, + $data{$what}->{line_no}; + } + my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; @@ -369,6 +380,10 @@ sub search_symbols { } } +# Ensure that the prefix will always end with a slash +# While this is not needed for find, it makes the patch nicer +# with --enable-lineno +$prefix =~ s,/?$,/,; # # Parses all ABI files located at $prefix dir @@ -395,7 +410,8 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B [--debug] [--man] [--help] --[(no-)rst-source] [--dir=] [] +B [--debug] [--enable-lineno] [--man] [--help] + [--(no-)rst-source] [--dir=] [] Where can be: @@ -425,6 +441,10 @@ selecting between a rst-compliant source ABI (--rst-source), or a plain text that may be violating ReST spec, so it requres some escaping logic (--no-rst-source). +=item B<--enable-lineno> + +Enable output of #define LINENO lines. + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple -- cgit v1.2.3 From f82a8a74ea81df22b1641ee56cf7195cc2a1bd0b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:23 +0100 Subject: scripts: get_abi.pl: improve its parser to better catch up indentation The original parser for indentation were relying on having just one description for each "what". However, that's not the case: there are a number of ABI symbols that got defined multiple times. Improve the parser for it to better handle descriptions if entries are duplicated. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/eb458bb30be0e5a89192d6057b2e8a7e910dbcb8.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 42 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 23 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 6a4d387ebf3b..bd018eb3815b 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -147,17 +147,19 @@ sub parse_abi { parse_error($file, $ln, "'What:' should come first:", $_); next; } - if ($tag eq "description") { - # Preserve initial spaces for the first line + if ($new_tag eq "description") { + $sep =~ s,:, ,; $content = ' ' x length($new_tag) . $sep . $content; - $content =~ s,^(\s*):,$1 ,; - if ($content =~ m/^(\s*)(.*)$/) { + while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + if ($content =~ m/^(\s*)(\S.*)$/) { + # Preserve initial spaces for the first line $space = $1; - $content = $2; + $content = "$2\n"; + $data{$what}->{$tag} .= $content; + } else { + undef($space); } - while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - $data{$what}->{$tag} .= "$content\n" if ($content); } else { $data{$what}->{$tag} = $content; } @@ -174,28 +176,22 @@ sub parse_abi { if ($tag eq "description") { my $content = $_; while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - if (!$data{$what}->{description}) { + if (m/^\s*\n/) { + $data{$what}->{$tag} .= "\n"; + next; + } + + if (!defined($space)) { # Preserve initial spaces for the first line - if ($content =~ m/^(\s*)(.*)$/) { + if ($content =~ m/^(\s*)(\S.*)$/) { $space = $1; - $content = $2; + $content = "$2\n"; } - - $data{$what}->{$tag} .= "$content\n" if ($content); } else { - if (m/^\s*\n/) { - $data{$what}->{$tag} .= $content; - next; - } - $space = "" if (!($content =~ s/^($space)//)); - -# # Compress spaces with tabs -# $content =~ s<^ {8}> <\t>; -# $content =~ s<^ {1,7}\t> <\t>; -# $content =~ s< {1,7}\t> <\t>; - $data{$what}->{$tag} .= $content; } + $data{$what}->{$tag} .= $content; + next; } if (m/^\s*(.*)/) { -- cgit v1.2.3 From 234948bf3d27e473ac8043d20dacda146beeb0cb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:24 +0100 Subject: scripts: get_abi.pl: cleanup ABI cross-reference logic Right now, the cross-references are generated on a single step, when doing ReST output. While this is nice optimization, it prevents auto-creating cross-references for ABI symbols. So, split it into a separate logic. While here, turn on Perl warnings, as it helps to debug problems inside the script. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/dbc97c8c2dfd877921f058134c35b2a8b1f8414b.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 147 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 64 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index bd018eb3815b..d134cc1692ee 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -2,15 +2,16 @@ # SPDX-License-Identifier: GPL-2.0 use strict; +use warnings; use Pod::Usage; use Getopt::Long; use File::Find; use Fcntl ':mode'; -my $help; -my $man; -my $debug; -my $enable_lineno; +my $help = 0; +my $man = 0; +my $debug = 0; +my $enable_lineno = 0; my $prefix="Documentation/ABI"; # @@ -40,6 +41,7 @@ pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug); my %data; +my %symbols; # # Displays an error message, printing file name and line @@ -76,12 +78,12 @@ sub parse_abi { my $what; my $new_what; - my $tag; + my $tag = ""; my $ln; my $xrefs; my $space; my @labels; - my $label; + my $label = ""; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; @@ -110,10 +112,18 @@ sub parse_abi { if ($new_tag =~ m/what/) { $space = ""; + $content =~ s/[,.;]$//; + if ($tag =~ m/what/) { $what .= ", " . $content; } else { - parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); + if ($what) { + parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description}); + + foreach my $w(split /, /, $what) { + $symbols{$w} = $what; + }; + } $what = $content; $label = $content; @@ -122,7 +132,7 @@ sub parse_abi { push @labels, [($content, $label)]; $tag = $new_tag; - push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what}); + push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what}); next; } @@ -132,7 +142,7 @@ sub parse_abi { $data{$what}->{line_no} = $ln; if ($new_what) { - @{$data{$what}->{label}} = @labels if ($data{$nametag}->{what}); + @{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what}); @labels = (); $label = ""; $new_what = 0; @@ -203,36 +213,24 @@ sub parse_abi { # Everything else is error parse_error($file, $ln, "Unexpected line:", $_); } - $data{$nametag}->{description} =~ s/^\n+//; + $data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description}); + if ($what) { + parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description}); + + foreach my $w(split /, /,$what) { + $symbols{$w} = $what; + }; + } close IN; } -# -# Outputs the book on ReST format -# - -my %labels; - -sub output_rest { - foreach my $what (sort { - ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || - $a cmp $b - } keys %data) { - my $type = $data{$what}->{type}; - my $file = $data{$what}->{file}; - my $filepath = $data{$what}->{filepath}; - - if ($enable_lineno) { - printf "#define LINENO %s%s#%s\n\n", - $prefix, $data{$what}->{file}, - $data{$what}->{line_no}; - } - - my $w = $what; - $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; +sub create_labels { + my %labels; + foreach my $what (keys %data) { + next if ($data{$what}->{file} eq "File"); - foreach my $p (@{$data{$what}->{label}}) { + foreach my $p (@{$data{$what}->{label_list}}) { my ($content, $label) = @{$p}; $label = "abi_" . $label . " "; $label =~ tr/A-Z/a-z/; @@ -249,16 +247,39 @@ sub output_rest { } $labels{$label} = 1; - $data{$what}->{label} .= $label; - - printf ".. _%s:\n\n", $label; + $data{$what}->{label} = $label; # only one label is enough last; } + } +} + +# +# Outputs the book on ReST format +# + +sub output_rest { + create_labels(); + + foreach my $what (sort { + ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || + $a cmp $b + } keys %data) { + my $type = $data{$what}->{type}; + my $file = $data{$what}->{file}; + my $filepath = $data{$what}->{filepath}; + + if ($enable_lineno) { + printf "#define LINENO %s%s#%s\n\n", + $prefix, $data{$what}->{file}, + $data{$what}->{line_no}; + } + my $w = $what; + $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; - $filepath =~ s,.*/(.*/.*),\1,;; + $filepath =~ s,.*/(.*/.*),$1,;; $filepath =~ s,[/\-],_,g;; my $fileref = "abi_file_".$filepath; @@ -269,8 +290,9 @@ sub output_rest { print ".. _$fileref:\n\n"; print "$w\n$bar\n\n"; } else { - my @names = split /\s*,\s*/,$w; + printf ".. _%s:\n\n", $data{$what}->{label}; + my @names = split /, /,$w; my $len = 0; foreach my $name (@names) { @@ -284,12 +306,13 @@ sub output_rest { printf "| %s", $name . " " x ($len - length($name)) . " |\n"; print "+-" . "-" x $len . "-+\n"; } - print "\n"; - } - print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File"); + print "\nDefined on file :ref:`$file <$fileref>`\n\n"; + } - my $desc = $data{$what}->{description}; + my $desc = ""; + $desc = $data{$what}->{description} if (defined($data{$what}->{description})); + $desc =~ s/\s+$/\n/; if (!($desc =~ /^\s*$/)) { if ($description_is_rst) { @@ -316,18 +339,11 @@ sub output_rest { print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); } - if ($data{$what}->{xrefs}) { + if ($data{$what}->{symbols}) { printf "Has the following ABI:\n\n"; - foreach my $p(@{$data{$what}->{xrefs}}) { - my ($content, $label) = @{$p}; - $label = "abi_" . $label . " "; - $label =~ tr/A-Z/a-z/; - - # Convert special chars to "_" - $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; - $label =~ s,_+,_,g; - $label =~ s,_$,,; + foreach my $content(@{$data{$what}->{symbols}}) { + my $label = $data{$symbols{$content}}->{label}; # Escape special chars from content $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; @@ -355,17 +371,20 @@ sub search_symbols { print "\n$what\n$bar\n\n"; - my $kernelversion = $data{$what}->{kernelversion}; - my $contact = $data{$what}->{contact}; - my $users = $data{$what}->{users}; - my $date = $data{$what}->{date}; - my $desc = $data{$what}->{description}; - $kernelversion =~ s/^\s+//; - $contact =~ s/^\s+//; - $users =~ s/^\s+//; - $users =~ s/\n//g; - $date =~ s/^\s+//; - $desc =~ s/^\s+//; + my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion})); + my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact})); + my $users = $data{$what}->{users} if (defined($data{$what}->{users})); + my $date = $data{$what}->{date} if (defined($data{$what}->{date})); + my $desc = $data{$what}->{description} if (defined($data{$what}->{description})); + + $kernelversion =~ s/^\s+// if ($kernelversion); + $contact =~ s/^\s+// if ($contact); + if ($users) { + $users =~ s/^\s+//; + $users =~ s/\n//g; + } + $date =~ s/^\s+// if ($date); + $desc =~ s/^\s+// if ($desc); printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion); printf "Date:\t\t\t%s\n", $date if ($date); -- cgit v1.2.3 From c7ba333426bcf4d7330d3a0a768e8048a82e4cc7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:25 +0100 Subject: scripts: get_abi.pl: detect duplicated ABI definitions The ABI should define only once each What. The current script logic assumes that. However, that's not the case, currently: there are several symbols with a generic definition, and per-driver ones. Better handle such cases, by preserving the cross-references with the files that define them, but also track such cases, producing warnings, as they should be fixed. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/d7a73b8b3aae5b2bff9279996ff9ca4cdfc89196.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 85 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 27 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index d134cc1692ee..1d1408fad130 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -114,6 +114,8 @@ sub parse_abi { $space = ""; $content =~ s/[,.;]$//; + push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1); + if ($tag =~ m/what/) { $what .= ", " . $content; } else { @@ -121,7 +123,7 @@ sub parse_abi { parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description}); foreach my $w(split /, /, $what) { - $symbols{$w} = $what; + $symbols{$w}->{xref} = $what; }; } @@ -139,8 +141,6 @@ sub parse_abi { if ($tag ne "" && $new_tag) { $tag = $new_tag; - $data{$what}->{line_no} = $ln; - if ($new_what) { @{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what}); @labels = (); @@ -148,9 +148,19 @@ sub parse_abi { $new_what = 0; $data{$what}->{type} = $type; - $data{$what}->{file} = $name; - $data{$what}->{filepath} = $file; + if (!defined($data{$what}->{file})) { + $data{$what}->{file} = $name; + $data{$what}->{filepath} = $file; + } else { + if ($name ne $data{$what}->{file}) { + $data{$what}->{file} .= " " . $name; + $data{$what}->{filepath} .= " " . $file; + } + } print STDERR "\twhat: $what\n" if ($debug > 1); + $data{$what}->{line_no} = $ln; + } else { + $data{$what}->{line_no} = $ln if (!defined($data{$what}->{line_no})); } if (!$what) { @@ -218,7 +228,7 @@ sub parse_abi { parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description}); foreach my $w(split /, /,$what) { - $symbols{$w} = $what; + $symbols{$w}->{xref} = $what; }; } close IN; @@ -267,29 +277,20 @@ sub output_rest { $a cmp $b } keys %data) { my $type = $data{$what}->{type}; - my $file = $data{$what}->{file}; - my $filepath = $data{$what}->{filepath}; + + my @file = split / /, $data{$what}->{file}; + my @filepath = split / /, $data{$what}->{filepath}; if ($enable_lineno) { printf "#define LINENO %s%s#%s\n\n", - $prefix, $data{$what}->{file}, + $prefix, $file[0], $data{$what}->{line_no}; } my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; - $filepath =~ s,.*/(.*/.*),$1,;; - $filepath =~ s,[/\-],_,g;; - my $fileref = "abi_file_".$filepath; - - if ($type eq "File") { - my $bar = $w; - $bar =~ s/./-/g; - - print ".. _$fileref:\n\n"; - print "$w\n$bar\n\n"; - } else { + if ($type ne "File") { printf ".. _%s:\n\n", $data{$what}->{label}; my @names = split /, /,$w; @@ -307,7 +308,26 @@ sub output_rest { print "+-" . "-" x $len . "-+\n"; } - print "\nDefined on file :ref:`$file <$fileref>`\n\n"; + print "\n"; + } + + for (my $i = 0; $i < scalar(@filepath); $i++) { + my $path = $filepath[$i]; + my $f = $file[$i]; + + $path =~ s,.*/(.*/.*),$1,;; + $path =~ s,[/\-],_,g;; + my $fileref = "abi_file_".$path; + + if ($type eq "File") { + my $bar = $w; + $bar =~ s/./-/g; + + print ".. _$fileref:\n\n"; + print "$w\n$bar\n\n"; + } else { + print "Defined on file :ref:`$f <$fileref>`\n\n"; + } } my $desc = ""; @@ -343,7 +363,7 @@ sub output_rest { printf "Has the following ABI:\n\n"; foreach my $content(@{$data{$what}->{symbols}}) { - my $label = $data{$symbols{$content}}->{label}; + my $label = $data{$symbols{$content}->{xref}}->{label}; # Escape special chars from content $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; @@ -390,7 +410,7 @@ sub search_symbols { printf "Date:\t\t\t%s\n", $date if ($date); printf "Contact:\t\t%s\n", $contact if ($contact); printf "Users:\t\t\t%s\n", $users if ($users); - print "Defined on file:\t$file\n\n"; + print "Defined on file(s):\t$file\n\n"; print "Description:\n\n$desc"; } } @@ -410,12 +430,23 @@ print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # # Handles the command # -if ($cmd eq "rest") { - output_rest; -} elsif ($cmd eq "search") { +if ($cmd eq "search") { search_symbols; -} +} else { + if ($cmd eq "rest") { + output_rest; + } + + # Warn about duplicated ABI entries + foreach my $what(sort keys %symbols) { + my @files = @{$symbols{$what}->{file}}; + + next if (scalar(@files) == 1); + printf STDERR "Warning: $what is defined %d times: @files\n", + scalar(@files); + } +} __END__ -- cgit v1.2.3 From a16ab14eb7a92bfebf71a8a9185c749de86851f4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:26 +0100 Subject: scripts: get_abi.pl: output users in ReST format Right now, the script only outputs Users on search. Print it also in ReST format. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/83def2a692c4c678f21ee6e76b66a54d2be1e796.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 1d1408fad130..e5a5588a8639 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -371,6 +371,14 @@ sub output_rest { print "- :ref:`$content <$label>`\n\n"; } } + + if (defined($data{$what}->{users})) { + my $users = $data{$what}->{users}; + + $users =~ s/\n/\n\t/g; + printf "Users:\n\t%s\n\n", $users if ($users ne ""); + } + } } -- cgit v1.2.3 From a4ea67bc65a15dadcda747c7f9d7b0e76e7c842a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:27 +0100 Subject: scripts: get_abi.pl: prevent duplicated file names The same filename may exist on multiple directories within ABI. Create separate entries at the internal database for each of them. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/ef760f68f54e132c4be52f0027189b4ba31554ec.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index e5a5588a8639..5612f019fae0 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -65,7 +65,10 @@ sub parse_abi { my $name = $file; $name =~ s,.*/,,; - my $nametag = "File $name"; + my $fn = $file; + $fn =~ s,Documentation/ABI/,,; + + my $nametag = "File $fn"; $data{$nametag}->{what} = "File $name"; $data{$nametag}->{type} = "File"; $data{$nametag}->{file} = $name; @@ -320,16 +323,18 @@ sub output_rest { my $fileref = "abi_file_".$path; if ($type eq "File") { - my $bar = $w; - $bar =~ s/./-/g; - print ".. _$fileref:\n\n"; - print "$w\n$bar\n\n"; } else { print "Defined on file :ref:`$f <$fileref>`\n\n"; } } + if ($type eq "File") { + my $bar = $w; + $bar =~ s/./-/g; + print "$w\n$bar\n\n"; + } + my $desc = ""; $desc = $data{$what}->{description} if (defined($data{$what}->{description})); $desc =~ s/\s+$/\n/; -- cgit v1.2.3 From c01d62d3fecb27f4c76a0e14b7e5afc15497a74b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:28 +0100 Subject: scripts: get_abi.pl: use bold font for ABI definitions As we're using tables, let's distinguish the ones used by ABI by using a bold font. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/9ed645c2519169817379c1df5b8cf03828e92520.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 5612f019fae0..12a23f9a2f86 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -300,6 +300,7 @@ sub output_rest { my $len = 0; foreach my $name (@names) { + $name = "**$name**"; $len = length($name) if (length($name) > $len); } -- cgit v1.2.3 From 55e5414f2f8e31a8abbd95c43c24b69e83560a20 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:29 +0100 Subject: scripts: get_abi.pl: auto-generate cross references There are several cross-references that can be automatically generated: - References to .rst files inside Documentation/ - References to other ABI files; - References to ABI symbols at /sys/*. Add a logic to automatically parse them and convert into cross references. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/abe756d4f94fb6ffcc3dd3902a766c7c3990ea89.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 12a23f9a2f86..ff4f9f82ecad 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -3,6 +3,7 @@ use strict; use warnings; +use utf8; use Pod::Usage; use Getopt::Long; use File::Find; @@ -272,6 +273,9 @@ 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 { (?"; + $desc =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; + } + + @matches = $desc =~ m,$bondary(/sys/[^\s\.\,\;\:\*\s\`\'\(\)]+)$bondary,; + + foreach my $s (@matches) { + if (defined($data{$s}) && defined($data{$s}->{label})) { + my $xref = $s; + + $xref =~ s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; + + $desc =~ s,$bondary$s$bondary,$xref,g; + } + } + print "$desc\n\n"; } else { $desc =~ s/^\s+//; -- cgit v1.2.3 From 75442fb0ccaacddf1654a5304401a9f556c61004 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:45 +0100 Subject: docs: Kconfig/Makefile: add a check for broken ABI files The files under Documentation/ABI should follow the syntax as defined at Documentation/ABI/README. Allow checking if they're following the syntax by running the ABI parser script on COMPILE_TEST. With that, when there's a problem with a file under Documentation/ABI, it would produce a warning like: Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14: What '/sys/bus/pci/devices//aer_stats/aer_rootport_total_err_cor' doesn't have a description Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21: What '/sys/bus/pci/devices//aer_stats/aer_rootport_total_err_fatal' doesn't have a description Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/57a38de85cb4b548857207cf1fc1bf1ee08613c9.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index ff4f9f82ecad..f6adf4b38a2b 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -50,7 +50,15 @@ my %symbols; sub parse_error($$$$) { my ($file, $ln, $msg, $data) = @_; - print STDERR "file $file#$ln: $msg at\n\t$data"; + $data =~ s/\s+$/\n/; + + print STDERR "Warning: file $file#$ln:\n\t$msg"; + + if ($data ne "") { + print STDERR ". Line\n\t\t$data"; + } else { + print STDERR "\n"; + } } # @@ -110,7 +118,7 @@ sub parse_abi { # Invalid, but it is a common mistake if ($new_tag eq "where") { - parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_); + parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", ""); $new_tag = "what"; } @@ -225,7 +233,7 @@ sub parse_abi { } # Everything else is error - parse_error($file, $ln, "Unexpected line:", $_); + parse_error($file, $ln, "Unexpected content", $_); } $data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description}); if ($what) { -- cgit v1.2.3 From 54a19b4d3fe0fa0a31b46cd60951e8177cac25fa Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:50 +0100 Subject: docs: ABI: cleanup several ABI documents There are some ABI documents that, while they don't generate any warnings, they have issues when parsed by get_abi.pl script on its output result. Address them, in order to provide a clean output. Reviewed-by: Tom Rix # for fpga-manager Reviewed-By: Kajol Jain # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7 Acked-by: Jonathan Cameron #for IIO Acked-by: Oded Gabbay # for Habanalabs Acked-by: Vaibhav Jain # for sysfs-bus-papr-pmem Acked-by: Cezary Rojewski # for catpt Acked-by: Suzuki K Poulose Acked-by: Ilya Dryomov # for rbd Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/5bc78e5b68ed1e9e39135173857cb2e753be868f.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 2 -- 1 file changed, 2 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index f6adf4b38a2b..d09bb37dd236 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -316,8 +316,6 @@ sub output_rest { $len = length($name) if (length($name) > $len); } - print "What:\n\n"; - print "+-" . "-" x $len . "-+\n"; foreach my $name (@names) { printf "| %s", $name . " " x ($len - length($name)) . " |\n"; -- cgit v1.2.3 From 2fcce37a3d2f2f3d7fa36aad2b71cbaca135ffd4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 30 Oct 2020 08:40:58 +0100 Subject: scripts: get_abi.pl: assume ReST format by default All ABI files are now compatible with ReST format. So, change the script default to assume that the ABI source files are compatible with ReST. Acked-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/4b0af257010570e0e917d82498e42992bec5e173.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- 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 d09bb37dd236..2cb592f8eba4 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -18,7 +18,7 @@ my $prefix="Documentation/ABI"; # # If true, assumes that the description is formatted with ReST # -my $description_is_rst = 0; +my $description_is_rst = 1; GetOptions( "debug|d+" => \$debug, -- cgit v1.2.3 From d1889589a4f54b2d1d7075d608b596d6fcfd3d96 Mon Sep 17 00:00:00 2001 From: Sven Joachim Date: Mon, 26 Oct 2020 20:32:16 +0100 Subject: builddeb: Fix rootless build in setuid/setgid directory Building 5.10-rc1 in a setgid directory failed with the following error: dpkg-deb: error: control directory has bad permissions 2755 (must be >=0755 and <=0775) When building with fakeroot, the earlier chown call would have removed the setgid bits, but in a rootless build they remain. Fixes: 3e8541803624 ("builddeb: Enable rootless builds") Cc: Guillem Jover Signed-off-by: Sven Joachim Signed-off-by: Masahiro Yamada --- scripts/package/builddeb | 2 ++ 1 file changed, 2 insertions(+) (limited to 'scripts') diff --git a/scripts/package/builddeb b/scripts/package/builddeb index 1b11f8993629..91a502bb97e8 100755 --- a/scripts/package/builddeb +++ b/scripts/package/builddeb @@ -45,6 +45,8 @@ create_package() { chmod -R go-w "$pdir" # in case we are in a restrictive umask environment like 0077 chmod -R a+rX "$pdir" + # in case we build in a setuid/setgid directory + chmod -R ug-s "$pdir" # Create the package dpkg-gencontrol -p$pname -P"$pdir" -- cgit v1.2.3 From daaaf58a2b7fd59951bd090eddee131f26422e20 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:15 +0100 Subject: scripts: get_abi.pl: Don't let ABI files to create subtitles The ReST output should only contain documentation titles automatically created by the script. There are two reasons for that: 1) Consistency. just a handful ABI docs define titles 2) To avoid critical errors. Docutils (which is the basis for Sphinx) allows a free assign of documentation title markups. So, one document could be doing things like: Level 1 ======= Level 2 ------- While another one could do the reverse: Level 1 ------- Level 2 ======= But the same document can't mix. As the output of get_abi.pl will join contents from multiple files, if they don't define the levels on a consistent errors, errors like this can happen: Sphinx parallel build error: docutils.utils.SystemMessage: /home/rdunlap/lnx/lnx-510-rc2/Documentation/ABI/testing/sysfs-bus-rapidio:2: (SEVERE/4) Title level inconsistent: Attributes Common for All RapidIO Devices ----------------------------------------- Which cause some versions of Sphinx to go into an endless loop. It should be noticed that an alternative to that would be to replace all title occurrences by a single markup, but that will make the parser more complex, and, due to (1) it would generate an inconsistent output. So, better to just remove the titles defined at the ABI files from the output. Reported-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/6c62ef5c01d39dee8d891f8390c816d2a889670a.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 2cb592f8eba4..459f169f834c 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -352,6 +352,12 @@ sub output_rest { if (!($desc =~ /^\s*$/)) { if ($description_is_rst) { + # Remove title markups from the description + # Having titles inside ABI files will only work if extra + # care would be taken in order to strictly follow the same + # level order for each markup. + $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g; + # Enrich text by creating cross-references $desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; -- cgit v1.2.3 From 9d4fdda3344611ec53ededccc0c13cb149ba4375 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Nov 2020 11:32:16 +0100 Subject: scripts: get_api.pl: Add sub-titles to ABI output Instead of adding titles just for the files, add titles for each part of the ABI output, in order to make easier to search for a symbol there. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/64752a5de06ab8263c296e3ed01414b25861e1eb.1604312590.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 459f169f834c..68dab828a722 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -287,6 +287,8 @@ my $bondary = qr { (?{type} eq "File") cmp ($data{$b}->{type} eq "File") || $a cmp $b @@ -306,6 +308,21 @@ sub output_rest { $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; if ($type ne "File") { + my $cur_part = $what; + if ($what =~ '/') { + if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) { + $cur_part = "Symbols under $1"; + $cur_part =~ s,/$,,; + } + } + + if ($cur_part ne "" && $part ne $cur_part) { + $part = $cur_part; + my $bar = $part; + $bar =~ s/./-/g; + print "$part\n$bar\n\n"; + } + printf ".. _%s:\n\n", $data{$what}->{label}; my @names = split /, /,$w; -- cgit v1.2.3