[PATCH 0/3] scripts: get_abi.pl: some additional fixes and doc update

[PATCH 0/3] scripts: get_abi.pl: some additional fixes and doc update

[Mauro Carvalho Chehab]

Hi Greg,

This small series address a couple of issues I noticed while testing it
on an arm64 board (HiKey970). Those are addressed on patches 1
and 2.

Patch 2 is the real fix: it prevents creating aliases for nodes that
are ignored (specially for /sys/firmware, where there's no documentation
for the files created there under Documentation/ABI - nor it makes
sense to have it).

Patch 1 prevents similar cases, as it will produce an error if a
symlink is pointing to an entry that was not added at the internal
representation of the sysfs.

Patch 3 just update a few things at the documentation inside the
script.

Mauro Carvalho Chehab (3):
  scripts: get_abi.pl: produce an error if the ref tree is broken
  scripts: get_abi.pl: fix parse logic for DT firmware
  scripts: get_abi.pl: update its documentation

 scripts/get_abi.pl | 70 +++++++++++++++++++++++++++++-----------------
 1 file changed, 45 insertions(+), 25 deletions(-)

-- 
2.31.1

[PATCH 1/3] scripts: get_abi.pl: produce an error if the ref tree is broken

[Mauro Carvalho Chehab]

The logic under graph_add_file should create, for every entry, a
__name name array for all entries of the tree. If this fails, the
symlink parsing will break.

Add an error if this ever happens.

While here, improve the output of data dumper to be more
compact and to avoid displaying things like $VAR1=.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

See [PATCH 0/3] at: https://lore.kernel.org/all/cover.1632750315.git.mchehab+huawei@kernel.org/

 scripts/get_abi.pl | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index c191c024f052..26a3f8ff566a 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -27,6 +27,9 @@ my $dbg_what_open = 2;
 my $dbg_dump_abi_structs = 4;
 my $dbg_undefined = 8;
 
+$Data::Dumper::Indent = 1;
+$Data::Dumper::Terse = 1;
+
 #
 # If true, assumes that the description is formatted with ReST
 #
@@ -597,7 +600,6 @@ sub graph_add_link {
 
 	my @queue;
 	my %seen;
-	my $base_name;
 	my $st;
 
 	push @queue, $file_ref;
@@ -611,6 +613,12 @@ sub graph_add_link {
 			next if $seen{$$v{$c}};
 			next if ($c eq "__name");
 
+			if (!defined($$v{$c}{"__name"})) {
+				printf STDERR "Error: Couldn't find a non-empty name on a children of $file/.*: ";
+				print STDERR Dumper(%{$v});
+				exit;
+			}
+
 			# Add new name
 			my $name = @{$$v{$c}{"__name"}}[0];
 			if ($name =~ s#^$file/#$link/#) {
-- 
2.31.1

[PATCH 2/3] scripts: get_abi.pl: fix parse logic for DT firmware

[Mauro Carvalho Chehab]

It doesn't make any sense to parse ABI entries under
/sys/firmware, as those are either specified by ACPI specs
or by Documentation/devicetree.

The current logic to ignore firmware entries is incomplete,
as it ignores just the relative name of the file, and not
its absolute name. This cause errors while parsing the
symlinks.

So, rewrite the logic for it to do a better job.

Tested with both x86 and arm64 (HiKey970) systems.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

See [PATCH 0/3] at: https://lore.kernel.org/all/cover.1632750315.git.mchehab+huawei@kernel.org/

 scripts/get_abi.pl | 32 +++++++++++++++++++++-----------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 26a3f8ff566a..d14f5cfc3138 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -635,20 +635,30 @@ my $escape_symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x29\x2b-\x2d\x3a-\x40\x7b-\x
 sub parse_existing_sysfs {
 	my $file = $File::Find::name;
 
-	# Ignore cgroup and firmware
-	return if ($file =~ m#^/sys/(fs/cgroup|firmware)/#);
-
-	# Ignore some sysfs nodes
-	return if ($file =~ m#/(sections|notes)/#);
-
-	# Would need to check at
-	# Documentation/admin-guide/kernel-parameters.txt, but this
-	# is not easily parseable.
-	return if ($file =~ m#/parameters/#);
-
 	my $mode = (lstat($file))[2];
 	my $abs_file = abs_path($file);
 
+	my @tmp;
+	push @tmp, $file;
+	push @tmp, $abs_file if ($abs_file ne $file);
+
+	foreach my $f(@tmp) {
+		# Ignore cgroup, as this is big and has zero docs under ABI
+		return if ($f =~ m#^/sys/fs/cgroup/#);
+
+		# Ignore firmware as it is documented elsewhere
+		# Either ACPI or under Documentation/devicetree/bindings/
+		return if ($f =~ m#^/sys/firmware/#);
+
+		# Ignore some sysfs nodes that aren't actually part of ABI
+		return if ($f =~ m#/sections|notes/#);
+
+		# Would need to check at
+		# Documentation/admin-guide/kernel-parameters.txt, but this
+		# is not easily parseable.
+		return if ($f =~ m#/parameters/#);
+	}
+
 	if (S_ISLNK($mode)) {
 		$aliases{$file} = $abs_file;
 		return;
-- 
2.31.1

[PATCH 3/3] scripts: get_abi.pl: update its documentation

[Mauro Carvalho Chehab]

The current highlight schema is not working properly. So, use,
instead, Pod::Text.

While here, also update the copyright in order to reflect the latest
changes and the e-mail I'm currently using.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

See [PATCH 0/3] at: https://lore.kernel.org/all/cover.1632750315.git.mchehab+huawei@kernel.org/

 scripts/get_abi.pl | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index d14f5cfc3138..4978163f5b16 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -1,10 +1,12 @@
 #!/usr/bin/env perl
 # SPDX-License-Identifier: GPL-2.0
 
+BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
+
 use strict;
 use warnings;
 use utf8;
-use Pod::Usage;
+use Pod::Usage qw(pod2usage);
 use Getopt::Long;
 use File::Find;
 use Fcntl ':mode';
@@ -47,7 +49,7 @@ GetOptions(
 ) or pod2usage(2);
 
 pod2usage(1) if $help;
-pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+pod2usage(-exitstatus => 0, -noperldoc, -verbose => 2) if $man;
 
 pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
 
@@ -923,18 +925,18 @@ B<abi_book.pl> [--debug <level>] [--enable-lineno] [--man] [--help]
 	       [--search-string <regex>]
 	       <COMAND> [<ARGUMENT>]
 
-Where <COMMAND> can be:
+Where B<COMMAND> can be:
 
 =over 8
 
-B<search> [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI
+B<search> I<SEARCH_REGEX> - search for I<SEARCH_REGEX> inside ABI
 
-B<rest>                  - output the ABI in ReST markup language
+B<rest>                   - output the ABI in ReST markup language
 
-B<validate>              - validate the ABI contents
+B<validate>               - validate the ABI contents
 
-B<undefined>             - existing symbols at the system that aren't
-                           defined at Documentation/ABI
+B<undefined>              - existing symbols at the system that aren't
+                            defined at Documentation/ABI
 
 =back
 
@@ -950,9 +952,9 @@ 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
+selecting between a rst-compliant source ABI (B<--rst-source>), or a
 plain text that may be violating ReST spec, so it requres some escaping
-logic (--no-rst-source).
+logic (B<--no-rst-source>).
 
 =item B<--enable-lineno>
 
@@ -972,7 +974,7 @@ following bitmask:
 Show hints about possible definitions for the missing ABI symbols.
 Used only when B<undefined>.
 
-=item B<--search-string> [regex string]
+=item B<--search-string> I<regex string>
 
 Show only occurences that match a search string.
 Used only when B<undefined>.
@@ -1021,11 +1023,11 @@ $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete
 
 =head1 BUGS
 
-Report bugs to Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
+Report bugs to Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
 
 =head1 COPYRIGHT
 
-Copyright (c) 2016-2019 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
+Copyright (c) 2016-2021 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
 
 License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
 
-- 
2.31.1