From 4489f161b739f01ab60a58784f6ef7de9d7a1352 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Jun 2019 17:53:27 -0300 Subject: docs: driver-model: convert docs to ReST and rename to *.rst Convert the various documents at the driver-model, preparing them to be part of the driver-api book. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Jeff Kirsher # ice Signed-off-by: Greg Kroah-Hartman --- scripts/coccinelle/free/devm_free.cocci | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci index b2a2cf8bf81f..e32236a979a8 100644 --- a/scripts/coccinelle/free/devm_free.cocci +++ b/scripts/coccinelle/free/devm_free.cocci @@ -2,7 +2,7 @@ /// functions. Values allocated using the devm_functions are freed when /// the device is detached, and thus the use of the standard freeing /// function would cause a double free. -/// See Documentation/driver-model/devres.txt for more information. +/// See Documentation/driver-model/devres.rst for more information. /// /// A difficulty of detecting this problem is that the standard freeing /// function might be called from a different function than the one -- cgit v1.2.3 From bbc249f2b85916da489111f6d33bf1da2be444bb Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:55 -0300 Subject: scripts: add an script to parse the ABI files Add a script to parse the Documentation/ABI files and produce an output with all entries inside an ABI (sub)directory. Right now, it outputs its contents on ReST format. It shouldn't be hard to make it produce other kind of outputs, since the ABI file parser is implemented in separate than the output generator. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 212 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100755 scripts/get_abi.pl (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl new file mode 100755 index 000000000000..f7c9944a833c --- /dev/null +++ b/scripts/get_abi.pl @@ -0,0 +1,212 @@ +#!/usr/bin/perl + +use strict; +use Pod::Usage; +use Getopt::Long; +use File::Find; +use Fcntl ':mode'; + +my $help; +my $man; +my $debug; + +GetOptions( + "debug|d+" => \$debug, + 'help|?' => \$help, + man => \$man +) or pod2usage(2); + +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; + +pod2usage(2) if (scalar @ARGV != 1); + +my ($prefix) = @ARGV; + +require Data::Dumper if ($debug); + +my %data; + +# +# Displays an error message, printing file name and line +# +sub parse_error($$$$) { + my ($file, $ln, $msg, $data) = @_; + + print STDERR "file $file#$ln: $msg at\n\t$data"; +} + +# +# Parse an ABI file, storing its contents at %data +# +sub parse_abi { + my $file = $File::Find::name; + + my $mode = (stat($file))[2]; + return if ($mode & S_IFDIR); + return if ($file =~ m,/README,); + + my $name = $file; + $name =~ s,.*/,,; + + my $type = $file; + $type =~ s,.*/(.*)/.*,$1,; + + my $what; + my $new_what; + my $tag; + my $ln; + + print STDERR "Opening $file\n" if ($debug > 1); + open IN, $file; + while() { + $ln++; + if (m/^(\S+):\s*(.*)/i) { + my $new_tag = lc($1); + my $content = $2; + + if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { + if ($tag eq "description") { + $data{$what}->{$tag} .= "\n$content";; + $data{$what}->{$tag} =~ s/\n+$//; + next; + } else { + parse_error($file, $ln, "tag '$tag' is invalid", $_); + } + } + + if ($new_tag =~ m/what/) { + if ($tag =~ m/what/) { + $what .= ", " . $content; + } else { + $what = $content; + $new_what = 1; + } + $tag = $new_tag; + next; + } + + $tag = $new_tag; + + if ($new_what) { + $new_what = 0; + + $data{$what}->{type} = $type; + $data{$what}->{file} = $name; + print STDERR "\twhat: $what\n" if ($debug > 1); + } + + if (!$what) { + parse_error($file, $ln, "'What:' should come first:", $_); + next; + } + $data{$what}->{$tag} = $content; + next; + } + + # Silently ignore any headers before the database + next if (!$tag); + + if (m/^\s*(.*)/) { + $data{$what}->{$tag} .= "\n$1"; + $data{$what}->{$tag} =~ s/\n+$//; + next; + } + + # Everything else is error + parse_error($file, $ln, "Unexpected line:", $_); + } + close IN; +} + +# Outputs the output on ReST format +sub output_rest { + foreach my $what (sort keys %data) { + my $type = $data{$what}->{type}; + my $file = $data{$what}->{file}; + + my $w = $what; + $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + + print "$w\n\n"; + print "- defined on file $file (type: $type)\n\n::\n\n"; + + 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; + + # put everything inside a code block + $desc =~ s/\n/\n /g; + + + if (!($desc =~ /^\s*$/)) { + print " $desc\n\n"; + } else { + print " DESCRIPTION MISSING\n\n"; + } + } +} + +# +# Parses all ABI files located at $prefix dir +# +find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); + +print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); + +# +# Outputs an ReST file with the ABI contents +# +output_rest + + +__END__ + +=head1 NAME + +abi_book.pl - parse the Linux ABI files and produce a ReST book. + +=head1 SYNOPSIS + +B [--debug] ] + +=head1 OPTIONS + +=over 8 + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. Can be called multiple +times, to increase verbosity. + +=item B<--help> + +Prints a brief help message and exits. + +=item B<--man> + +Prints the manual page and exits. + +=back + +=head1 DESCRIPTION + +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI) +and produce a ReST book containing the Linux ABI. + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab + +=head1 COPYRIGHT + +Copyright (c) 2016 by Mauro Carvalho Chehab . + +License GPLv2: GNU GPL version 2 . + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut -- cgit v1.2.3 From 6619c6617a88e3b5e35b12aed069aabe35c370e0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:56 -0300 Subject: scripts/get_abi.pl: parse files with text at beginning It sounds usefult o parse files with has some text at the beginning. Add support for it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 59 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 54 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index f7c9944a833c..ef9b6e108973 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -55,7 +55,10 @@ sub parse_abi { my $what; my $new_what; my $tag; + my $label; my $ln; + my $has_file; + my $xrefs; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; @@ -67,7 +70,7 @@ sub parse_abi { if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { - $data{$what}->{$tag} .= "\n$content";; + $data{$what}->{$tag} .= "\n$content"; $data{$what}->{$tag} =~ s/\n+$//; next; } else { @@ -83,6 +86,25 @@ sub parse_abi { $new_what = 1; } $tag = $new_tag; + + if ($has_file) { + $label = "abi_" . $content . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/[\x00-\x2f]+/_/g; + $label =~s/[\x3a-\x40]+/_/g; + $label =~s/[\x7b-\xff]+/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + $data{$what}->{label} .= $label; + + # Escape special chars from content + $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + + $xrefs .= "- :ref:`$content <$label>`\n\n"; + } next; } @@ -104,8 +126,18 @@ sub parse_abi { next; } - # Silently ignore any headers before the database - next if (!$tag); + # Store any contents before the database + if (!$tag) { + next if (/^\n/); + + my $my_what = "File $name"; + $data{$my_what}->{what} = "File $name"; + $data{$my_what}->{type} = "File"; + $data{$my_what}->{file} = $name; + $data{$my_what}->{description} .= $_; + $has_file = 1; + next; + } if (m/^\s*(.*)/) { $data{$what}->{$tag} .= "\n$1"; @@ -117,6 +149,11 @@ sub parse_abi { parse_error($file, $ln, "Unexpected line:", $_); } close IN; + + if ($has_file) { + my $my_what = "File $name"; + $data{$my_what}->{xrefs} = $xrefs; + } } # Outputs the output on ReST format @@ -128,8 +165,17 @@ sub output_rest { my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + if ($data{$what}->{label}) { + my @labels = split(/\s/, $data{$what}->{label}); + foreach my $label (@labels) { + printf ".. _%s:\n\n", $label; + } + } + print "$w\n\n"; - print "- defined on file $file (type: $type)\n\n::\n\n"; + + print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); + print "::\n\n"; my $desc = $data{$what}->{description}; $desc =~ s/^\s+//; @@ -144,8 +190,11 @@ sub output_rest { if (!($desc =~ /^\s*$/)) { print " $desc\n\n"; } else { - print " DESCRIPTION MISSING\n\n"; + print " DESCRIPTION MISSING for $what\n\n"; } + + printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); + } } -- cgit v1.2.3 From 4e6a6234da84496c6173ebe991060fe382ec4f15 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:57 -0300 Subject: scripts/get_abi.pl: avoid use literal blocks when not needed The usage of literal blocks make the document very complex, causing the browser to take a long time to load. On most ABI descriptions, they're a plain text, and don't require a literal block. So, add a logic there with identifies when a literal block is needed. As, on literal blocks, we need to respect the original document space, the most complex part of this patch is to preserve the original spacing where needed. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 102 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 25 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index ef9b6e108973..0ede9593c639 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -59,29 +59,34 @@ sub parse_abi { my $ln; my $has_file; my $xrefs; + my $space; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; while() { $ln++; - if (m/^(\S+):\s*(.*)/i) { + if (m/^(\S+)(:\s*)(.*)/i) { my $new_tag = lc($1); - my $content = $2; + my $sep = $2; + my $content = $3; if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { - $data{$what}->{$tag} .= "\n$content"; - $data{$what}->{$tag} =~ s/\n+$//; - next; + # New "tag" is actually part of + # description. Don't consider it a tag + $new_tag = ""; } else { parse_error($file, $ln, "tag '$tag' is invalid", $_); } } if ($new_tag =~ m/what/) { + $space = ""; if ($tag =~ m/what/) { $what .= ", " . $content; } else { + parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); + $what = $content; $new_what = 1; } @@ -108,25 +113,38 @@ sub parse_abi { next; } - $tag = $new_tag; + if ($new_tag) { + $tag = $new_tag; - if ($new_what) { - $new_what = 0; + if ($new_what) { + $new_what = 0; - $data{$what}->{type} = $type; - $data{$what}->{file} = $name; - print STDERR "\twhat: $what\n" if ($debug > 1); - } + $data{$what}->{type} = $type; + $data{$what}->{file} = $name; + print STDERR "\twhat: $what\n" if ($debug > 1); + } - if (!$what) { - parse_error($file, $ln, "'What:' should come first:", $_); + if (!$what) { + parse_error($file, $ln, "'What:' should come first:", $_); + 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"; + } + } else { + $data{$what}->{$tag} = $content; + } next; } - $data{$what}->{$tag} = $content; - next; } - # Store any contents before the database + # Store any contents before tags at the database if (!$tag) { next if (/^\n/); @@ -139,6 +157,32 @@ sub parse_abi { next; } + if ($tag eq "description") { + if (!$data{$what}->{description}) { + next if (m/^\s*\n/); + if (m/^(\s*)(.*)/) { + $space = $1; + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $data{$what}->{$tag} .= "$2\n"; + } + } 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>; + $data{$what}->{$tag} .= $content; + } + next; + } if (m/^\s*(.*)/) { $data{$what}->{$tag} .= "\n$1"; $data{$what}->{$tag} =~ s/\n+$//; @@ -165,6 +209,9 @@ sub output_rest { my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + my $bar = $w; + $bar =~ s/./-/g; + if ($data{$what}->{label}) { my @labels = split(/\s/, $data{$what}->{label}); foreach my $label (@labels) { @@ -172,10 +219,9 @@ sub output_rest { } } - print "$w\n\n"; + print "$w\n$bar\n\n"; print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); - print "::\n\n"; my $desc = $data{$what}->{description}; $desc =~ s/^\s+//; @@ -183,18 +229,24 @@ sub output_rest { # Remove title markups from the description, as they won't work $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; - # put everything inside a code block - $desc =~ s/\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"; + } 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; - if (!($desc =~ /^\s*$/)) { - print " $desc\n\n"; + print "$desc\n\n"; + } } else { - print " DESCRIPTION MISSING for $what\n\n"; + print "DESCRIPTION MISSING for $what\n\n"; } printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); - } } -- cgit v1.2.3 From d0ebaf51d219b63f87f3dc1da4c9da501d0519a4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:58 -0300 Subject: scripts/get_abi.pl: split label naming from xref logic Instead of using a ReST compilant label while parsing, move the label to ReST output. That makes the parsing logic more generic, allowing it to provide other types of output. As a side effect, now all files used to generate the output will be output. We can later add command line arguments to filter. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 94 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 53 insertions(+), 41 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 0ede9593c639..f84d321a72bb 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -49,17 +49,23 @@ sub parse_abi { my $name = $file; $name =~ s,.*/,,; + my $nametag = "File $name"; + $data{$nametag}->{what} = "File $name"; + $data{$nametag}->{type} = "File"; + $data{$nametag}->{file} = $name; + $data{$nametag}->{is_file} = 1; + my $type = $file; $type =~ s,.*/(.*)/.*,$1,; my $what; my $new_what; my $tag; - my $label; my $ln; - my $has_file; my $xrefs; my $space; + my @labels; + my $label; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; @@ -88,28 +94,13 @@ sub parse_abi { parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); $what = $content; + $label = $content; $new_what = 1; } + push @labels, [($content, $label)]; $tag = $new_tag; - if ($has_file) { - $label = "abi_" . $content . " "; - $label =~ tr/A-Z/a-z/; - - # Convert special chars to "_" - $label =~s/[\x00-\x2f]+/_/g; - $label =~s/[\x3a-\x40]+/_/g; - $label =~s/[\x7b-\xff]+/_/g; - $label =~ s,_+,_,g; - $label =~ s,_$,,; - - $data{$what}->{label} .= $label; - - # Escape special chars from content - $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; - - $xrefs .= "- :ref:`$content <$label>`\n\n"; - } + push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what}); next; } @@ -117,6 +108,9 @@ sub parse_abi { $tag = $new_tag; if ($new_what) { + @{$data{$what}->{label}} = @labels if ($data{$nametag}->{what}); + @labels = (); + $label = ""; $new_what = 0; $data{$what}->{type} = $type; @@ -145,15 +139,8 @@ sub parse_abi { } # Store any contents before tags at the database - if (!$tag) { - next if (/^\n/); - - my $my_what = "File $name"; - $data{$my_what}->{what} = "File $name"; - $data{$my_what}->{type} = "File"; - $data{$my_what}->{file} = $name; - $data{$my_what}->{description} .= $_; - $has_file = 1; + if (!$tag && $data{$nametag}->{what}) { + $data{$nametag}->{description} .= $_; next; } @@ -192,12 +179,8 @@ sub parse_abi { # Everything else is error parse_error($file, $ln, "Unexpected line:", $_); } + $data{$nametag}->{description} =~ s/^\n+//; close IN; - - if ($has_file) { - my $my_what = "File $name"; - $data{$my_what}->{xrefs} = $xrefs; - } } # Outputs the output on ReST format @@ -212,11 +195,22 @@ sub output_rest { my $bar = $w; $bar =~ s/./-/g; - if ($data{$what}->{label}) { - my @labels = split(/\s/, $data{$what}->{label}); - foreach my $label (@labels) { - printf ".. _%s:\n\n", $label; - } + foreach my $p (@{$data{$what}->{label}}) { + 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,_$,,; + + $data{$what}->{label} .= $label; + + printf ".. _%s:\n\n", $label; + + # only one label is enough + last; } print "$w\n$bar\n\n"; @@ -243,10 +237,28 @@ sub output_rest { print "$desc\n\n"; } } else { - print "DESCRIPTION MISSING for $what\n\n"; + print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); } - printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); + if ($data{$what}->{xrefs}) { + 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,_$,,; + + # Escape special chars from content + $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + + print "- :ref:`$content <$label>`\n\n"; + } + } } } -- cgit v1.2.3 From 33e3e9913e22481fd90fa0c50d4a04dded0ee1e1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:22:59 -0300 Subject: scripts/get_abi.pl: add support for searching for ABI symbols Change its syntax to allow switching between ReST output mode and a new search mode, with allows to seek for ABI symbols using regex. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 112 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 103 insertions(+), 9 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index f84d321a72bb..ecf6b91df7c4 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -9,9 +9,11 @@ use Fcntl ':mode'; my $help; my $man; my $debug; +my $prefix="Documentation/ABI"; GetOptions( "debug|d+" => \$debug, + "dir=s" => \$prefix, 'help|?' => \$help, man => \$man ) or pod2usage(2); @@ -19,9 +21,12 @@ GetOptions( pod2usage(1) if $help; pod2usage(-exitstatus => 0, -verbose => 2) if $man; -pod2usage(2) if (scalar @ARGV != 1); +pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); -my ($prefix) = @ARGV; +my ($cmd, $arg) = @ARGV; + +pod2usage(2) if ($cmd ne "search" && $cmd ne "rest"); +pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug); @@ -53,6 +58,7 @@ sub parse_abi { $data{$nametag}->{what} = "File $name"; $data{$nametag}->{type} = "File"; $data{$nametag}->{file} = $name; + $data{$nametag}->{filepath} = $file; $data{$nametag}->{is_file} = 1; my $type = $file; @@ -115,6 +121,7 @@ sub parse_abi { $data{$what}->{type} = $type; $data{$what}->{file} = $name; + $data{$what}->{filepath} = $file; print STDERR "\twhat: $what\n" if ($debug > 1); } @@ -183,7 +190,9 @@ sub parse_abi { close IN; } -# Outputs the output on ReST format +# +# Outputs the book on ReST format +# sub output_rest { foreach my $what (sort keys %data) { my $type = $data{$what}->{type}; @@ -262,6 +271,45 @@ sub output_rest { } } +# +# Searches for ABI symbols +# +sub search_symbols { + foreach my $what (sort keys %data) { + next if (!($what =~ m/($arg)/)); + + my $type = $data{$what}->{type}; + next if ($type eq "File"); + + my $file = $data{$what}->{filepath}; + + my $bar = $what; + $bar =~ s/./-/g; + + 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+//; + + printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion); + 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 "Description:\n\n$desc"; + } +} + + # # Parses all ABI files located at $prefix dir # @@ -270,9 +318,13 @@ find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # -# Outputs an ReST file with the ABI contents +# Handles the command # -output_rest +if ($cmd eq "rest") { + output_rest; +} else { + search_symbols; +} __END__ @@ -283,12 +335,27 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B [--debug] ] +B [--debug] [] + +Where can be: + +=over 8 + +B [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI + +B - output the ABI in ReST markup language + +=back =head1 OPTIONS =over 8 +=item B<--dir> + +Changes the location of the ABI search. By default, it uses +the Documentation/ABI directory. + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple @@ -306,8 +373,35 @@ Prints the manual page and exits. =head1 DESCRIPTION -Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI) -and produce a ReST book containing the Linux ABI. +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI), +allowing to search for ABI symbols or to produce a ReST book containing +the Linux ABI documentation. + +=head1 EXAMPLES + +Search for all stable symbols with the word "usb": + +=over 8 + +$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable + +=back + +Search for all symbols that match the regex expression "usb.*cap": + +=over 8 + +$ scripts/get_abi.pl search usb.*cap + +=back + +Output all obsoleted symbols in ReST format + +=over 8 + +$ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete + +=back =head1 BUGS @@ -315,7 +409,7 @@ Report bugs to Mauro Carvalho Chehab =head1 COPYRIGHT -Copyright (c) 2016 by Mauro Carvalho Chehab . +Copyright (c) 2016-2017 by Mauro Carvalho Chehab . License GPLv2: GNU GPL version 2 . -- cgit v1.2.3 From 45f965179560f26227d87641da0d055d5751f49f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:00 -0300 Subject: scripts/get_abi.pl: represent what in tables Several entries at the ABI have multiple What: with the same description. Instead of showing those symbols as sections, let's show them as tables. That makes easier to read on the final output, and avoid too much recursion at Sphinx parsing. We need to put file references at the end, as we don't want non-file tables to be mangled with other entries. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index ecf6b91df7c4..7d454e359d25 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -193,16 +193,19 @@ sub parse_abi { # # Outputs the book on ReST format # + sub output_rest { - foreach my $what (sort keys %data) { + 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}; my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; - my $bar = $w; - $bar =~ s/./-/g; foreach my $p (@{$data{$what}->{label}}) { my ($content, $label) = @{$p}; @@ -222,9 +225,37 @@ sub output_rest { last; } - print "$w\n$bar\n\n"; - print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); + $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 { + my @names = split /\s*,\s*/,$w; + + my $len = 0; + + foreach my $name (@names) { + $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"; + print "+-" . "-" x $len . "-+\n"; + } + print "\n"; + } + + print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File"); my $desc = $data{$what}->{description}; $desc =~ s/^\s+//; -- cgit v1.2.3 From 7d7ea8d2409fca0796f87676e489ed4ac0690a1b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:01 -0300 Subject: scripts/get_abi.pl: fix parse issues with some files A few files are failing to parse: Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats Documentation/ABI/testing/sysfs-class-pktcdvd Documentation/ABI/testing/sysfs-bus-nfit On all three files, the problem is that there is a ":" character at the initial file description. Improve the parse in order to handle those special cases. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 7d454e359d25..116f0c33c16d 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -87,7 +87,7 @@ sub parse_abi { # New "tag" is actually part of # description. Don't consider it a tag $new_tag = ""; - } else { + } elsif ($tag ne "") { parse_error($file, $ln, "tag '$tag' is invalid", $_); } } @@ -110,7 +110,7 @@ sub parse_abi { next; } - if ($new_tag) { + if ($tag ne "" && $new_tag) { $tag = $new_tag; if ($new_what) { -- cgit v1.2.3 From 2e7ce05593b39f0a947819ca8b73f2185f372f12 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:02 -0300 Subject: scripts/get_abi.pl: avoid creating duplicate names The file the Documentation/ABI/testing/sysfs-class-power has voltage_min, voltage_max and voltage_now symbols duplicated. They are defined first for "General Properties" and then for "USB Properties". This cause those warnings: get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26933: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_max". get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26968: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_min". get_abi.pl rest --dir $srctree/Documentation/ABI/testing:27008: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_now". And, as the references are not valid, it will also generate warnings about links to undefined references. Fix it by storing labels into a hash table and, when a duplicated one is found, appending random characters at the end. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index 116f0c33c16d..329ace635ac2 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -194,6 +194,8 @@ sub parse_abi { # 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") || @@ -217,6 +219,13 @@ sub output_rest { $label =~ s,_+,_,g; $label =~ s,_$,,; + # Avoid duplicated labels + while (defined($labels{$label})) { + my @chars = ("A".."Z", "a".."z"); + $label .= $chars[rand @chars]; + } + $labels{$label} = 1; + $data{$what}->{label} .= $label; printf ".. _%s:\n\n", $label; -- cgit v1.2.3 From 2c0700e7afa40330f2d21defe2a7bffcb0eecb1e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:03 -0300 Subject: scripts/get_abi.pl: add a handler for invalid "where" tag The ABI README file doesn't provide any meaning for a Where: tag. Yet, a few ABI symbols use it. So, make the parser handle it, emitting a warning. Signed-off-by: Mauro Carvalho Chehab 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 329ace635ac2..c5038a0a7313 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -92,6 +92,12 @@ 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", $_); + $new_tag = "what"; + } + if ($new_tag =~ m/what/) { $space = ""; if ($tag =~ m/what/) { -- cgit v1.2.3 From 7ce7b89bf565b4e86d37fd32577272e98d3359cd Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:04 -0300 Subject: scripts/get_abi.pl: add a validate command Sometimes, we just want the parser to retrieve all symbols from ABI, in order to check for parsing errors. So, add a new "validate" command. While here, update the man/help pages. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Greg Kroah-Hartman --- scripts/get_abi.pl | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'scripts') diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl index c5038a0a7313..774e9b809ead 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -25,7 +25,7 @@ pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); my ($cmd, $arg) = @ARGV; -pod2usage(2) if ($cmd ne "search" && $cmd ne "rest"); +pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate"); pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug); @@ -82,7 +82,7 @@ sub parse_abi { my $sep = $2; my $content = $3; - if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { + if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { # New "tag" is actually part of # description. Don't consider it a tag @@ -368,7 +368,7 @@ print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # if ($cmd eq "rest") { output_rest; -} else { +} elsif ($cmd eq "search") { search_symbols; } @@ -381,7 +381,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B [--debug] [] +B [--debug] [--man] [--help] [--dir=] [] Where can be: @@ -389,7 +389,9 @@ Where can be: B [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI -B - output the ABI in ReST markup language +B - output the ABI in ReST markup language + +B - validate the ABI contents =back @@ -451,11 +453,11 @@ $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete =head1 BUGS -Report bugs to Mauro Carvalho Chehab +Report bugs to Mauro Carvalho Chehab =head1 COPYRIGHT -Copyright (c) 2016-2017 by Mauro Carvalho Chehab . +Copyright (c) 2016-2019 by Mauro Carvalho Chehab . License GPLv2: GNU GPL version 2 . -- cgit v1.2.3 From ecb351f1c4475d11ce6b4fa443fe71764027d409 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 20 Jun 2019 14:23:10 -0300 Subject: doc: ABI scripts: add a SPDX header file released under GPL v2. Signed-off-by: Mauro Carvalho Chehab 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 774e9b809ead..c738cb795514 100755 --- a/scripts/get_abi.pl +++ b/scripts/get_abi.pl @@ -1,4 +1,5 @@ #!/usr/bin/perl +# SPDX-License-Identifier: GPL-2.0 use strict; use Pod::Usage; -- cgit v1.2.3