Skip to contentSkip to conversation

Add documentation for Documentation/features at the built docs

PATCH In review Mauro Carvalho Chehab 2 participants 20 messages Nov 30, 2020 – Dec 7, 2020

Subsystems (6)
Documentation MIPS RISC-V s390 +2 more subsystems
lore
Share & tools
lore
#0 lore raw

cover Add documentation for Documentation/features at the built docs

Hi Jon,

This series got already submitted last year:

https://lore.kernel.org/lkml/[email protected]/

Yet, on that time, there were too many other patches related to ReST conversion floating around. So, at the end, I guess this one got missed.

So, I did a rebase on the top of upstream, and added a few new changes.

Patch 1 contains the original implementation back then. It adds a get_feat.pl script that parses the contents of Documentation/features.

Patch 2 is new: it re-implements the output of the full contents of the features table as a set of per-subsystem tables.

Patch 3 replaces the existing Documentation/features/list-arch.sh by a call to the new script, in order to avoid having two scripts doing the same thing.

Patch 4 is a sphinx extension to allow generating features output via a meta-tag.

Patch 5 adds a complete feature list covering all archs at the admin guide.

Patch 6 adds a per-arch feature list on each architecture book.

-

The scripts/get_feat.pl supports several types of output:

- $ scripts/get_feat.pl current

Outputs the supported feadures by the architecture of the running Kernel, as an ASCII table;

- $ scripts/get_feat.pl list

Outputs the supported features on an easy to be parsed format. By default, it uses the current architecture as well;

- $ scripts/get_feat.pl rest --feature jump-labels

Output what architecture supports a given feature (on the above example, "jump-labels" feature)

- $ scripts/get_feat.pl rest --arch um

Outputs the features support for an specific architecture (on the above example, for "um" architecture.

- $ scripts/get_feat.pl rest

Outputs a text file with ASCII tables (ReST compatible) with all features, grouped per subsystem.

E. g. something like:

================= Feature status on all architectures
=================
Subsystem: core
=======
+---------------------+---------------------------------+-------------------------------------------------------------------------+------------+------+
|Feature |Kconfig |Description |Architecture|Status|
+===========+=================+=====================================+======+===+
|cBPF-JIT |HAVE_CBPF_JIT |arch supports cBPF JIT optimizations |alpha |TODO |
| | | +------------+------+
| | | |arc |TODO |
| | | +------------+------+
| | | |arm |TODO |
| | | +------------+------+
| | | |arm64 |TODO |
| | | +------------+------+
| | | |c6x |TODO |
| | | +------------+------+
| | | |csky |TODO |
| | | +------------+------+
| | | |h8300 |TODO |
| | | +------------+------+
| | | |hexagon |TODO |
...

Adding those patchsets will basically place the contents of all files under Documentation/features (currently, 45 files) at the Kernel documentation, which is, IMO, a good thing to do.

Regards,
Mauro

Mauro Carvalho Chehab (6):
scripts: get_feat.pl: add a script to handle Documentation/features
scripts: get_feat.pl: improve matrix output
scripts: get_feat.pl: use its implementation for list-arch.sh
sphinx: kernel_feat.py: add a script to parse feature files
docs: admin-guide: add a features list
docs: archis: add a per-architecture features list

 Documentation/admin-guide/features.rst |   3 +
 Documentation/admin-guide/index.rst    |   1 +
 Documentation/arm/features.rst         |   3 +
 Documentation/arm/index.rst            |   2 +
 Documentation/arm64/features.rst       |   3 +
 Documentation/arm64/index.rst          |   2 +
 Documentation/conf.py                  |   2 +-
 Documentation/features/list-arch.sh    |  17 +-
 Documentation/ia64/features.rst        |   3 +
 Documentation/ia64/index.rst           |   2 +
 Documentation/index.rst                |   2 +-
 Documentation/m68k/features.rst        |   3 +
 Documentation/m68k/index.rst           |   2 +
 Documentation/mips/features.rst        |   3 +
 Documentation/mips/index.rst           |   2 +
 Documentation/nios2/index.rst          |  12 +
 Documentation/openrisc/features.rst    |   3 +
 Documentation/openrisc/index.rst       |   2 +
 Documentation/parisc/features.rst      |   3 +
 Documentation/parisc/index.rst         |   2 +
 Documentation/powerpc/features.rst     |   3 +
 Documentation/powerpc/index.rst        |   2 +
 Documentation/riscv/features.rst       |   3 +
 Documentation/riscv/index.rst          |   2 +
 Documentation/s390/features.rst        |   3 +
 Documentation/s390/index.rst           |   2 +
 Documentation/sh/features.rst          |   3 +
 Documentation/sh/index.rst             |   2 +
 Documentation/sparc/features.rst       |   3 +
 Documentation/sparc/index.rst          |   2 +
 Documentation/sphinx/kernel_feat.py    | 169 ++++++++
 Documentation/x86/features.rst         |   3 +
 Documentation/x86/index.rst            |   1 +
 Documentation/xtensa/features.rst      |   3 +
 Documentation/xtensa/index.rst         |   2 +
 scripts/get_feat.pl                    | 552 +++++++++++++++++++++++++
 36 files changed, 810 insertions(+), 17 deletions(-)
 create mode 100644 Documentation/admin-guide/features.rst
 create mode 100644 Documentation/arm/features.rst
 create mode 100644 Documentation/arm64/features.rst
 create mode 100644 Documentation/ia64/features.rst
 create mode 100644 Documentation/m68k/features.rst
 create mode 100644 Documentation/mips/features.rst
 create mode 100644 Documentation/nios2/index.rst
 create mode 100644 Documentation/openrisc/features.rst
 create mode 100644 Documentation/parisc/features.rst
 create mode 100644 Documentation/powerpc/features.rst
 create mode 100644 Documentation/riscv/features.rst
 create mode 100644 Documentation/s390/features.rst
 create mode 100644 Documentation/sh/features.rst
 create mode 100644 Documentation/sparc/features.rst
 create mode 100644 Documentation/sphinx/kernel_feat.py
 create mode 100644 Documentation/x86/features.rst
 create mode 100644 Documentation/xtensa/features.rst
 create mode 100755 scripts/get_feat.pl
Signature · 1 line
2.28.0
#1 lore raw

PATCH 1/6 scripts: get_feat.pl: add a script to handle Documentation/features

The Documentation/features contains a set of parseable files. It is not worth converting them to ReST format, as they're useful the way it is. It is, however, interesting to parse them and produce output on different formats:

1) Output the contents of a feature in ReST format;

2) Output what features a given architecture supports;

3) Output a matrix with features x architectures.

---
 scripts/get_feat.pl | 474 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 474 insertions(+)
 create mode 100755 scripts/get_feat.pl
scripts/get_feat.pl new file +474 -0
new file mode 100755
index 000000000000..79d83595addd
@@ -0,0 +1,474 @@
+#!/usr/bin/perl
+# SPDX-License-Identifier: GPL-2.0
+
+use strict;
+use Pod::Usage;
+use Getopt::Long;
+use File::Find;
+use Fcntl ':mode';
+
+my $help;
+my $man;
+my $debug;
+my $arch;
+my $feat;
+my $prefix="Documentation/features";
+
+GetOptions(
+	"debug|d+" => \$debug,
+	"dir=s" => \$prefix,
+	'help|?' => \$help,
+	'arch=s' => \$arch,
+	'feat=s' => \$feat,
+	man => \$man
+) or pod2usage(2);
+
+pod2usage(1) if $help;
+pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
+
+my ($cmd, $arg) = @ARGV;
+
+pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate");
+
+require Data::Dumper if ($debug);
+
+my %data;
+my %archs;
+
+#
+# Displays an error message, printing file name and line
+#
+sub parse_error($$$$) {
+	my ($file, $ln, $msg, $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";
+	}
+}
+
+#
+# Parse a features file, storing its contents at %data
+#
+
+my $h_name = "Feature";
+my $h_kconfig = "Kconfig";
+my $h_description = "Description";
+my $h_subsys = "Subsystem";
+my $h_status = "Status";
+my $h_arch = "Architecture";
+
+my $max_size_name = length($h_name);
+my $max_size_kconfig = length($h_kconfig);
+my $max_size_description = length($h_description);
+my $max_size_subsys = length($h_subsys);
+my $max_size_status = length($h_status);
+my $max_size_arch = length($h_arch);
+
+sub parse_feat {
+	my $file = $File::Find::name;
+
+	my $mode = (stat($file))[2];
+	return if ($mode & S_IFDIR);
+	return if ($file =~ m,($prefix)/arch-support.txt,);
+	return if (!($file =~ m,arch-support.txt$,));
+
+	my $subsys = "";
+	$subsys = $2 if ( m,.*($prefix)/([^/]+).*,);
+
+	if (length($subsys) > $max_size_subsys) {
+		$max_size_subsys = length($subsys);
+	}
+
+	my $name;
+	my $kconfig;
+	my $description;
+	my $comments = "";
+	my $last_status;
+	my $ln;
+	my %arch_table;
+
+	print STDERR "Opening $file\n" if ($debug > 1);
+	open IN, $file;
+
+	while(<IN>) {
+		$ln++;
+
+		if (m/^\#\s+Feature\s+name:\s*(.*\S)/) {
+			$name = $1;
+			if (length($name) > $max_size_name) {
+				$max_size_name = length($name);
+			}
+			next;
+		}
+		if (m/^\#\s+Kconfig:\s*(.*\S)/) {
+			$kconfig = $1;
+			if (length($kconfig) > $max_size_kconfig) {
+				$max_size_kconfig = length($kconfig);
+			}
+			next;
+		}
+		if (m/^\#\s+description:\s*(.*\S)/) {
+			$description = $1;
+			if (length($description) > $max_size_description) {
+				$max_size_description = length($description);
+			}
+			next;
+		}
+		next if (m/^\\s*$/);
+		next if (m/^\s*\-+\s*$/);
+		next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/);
+
+		if (m/^\#\s*(.*)/) {
+			$comments .= "$1\n";
+			next;
+		}
+		if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) {
+			my $a = $1;
+			my $status = $2;
+
+			if (length($status) > $max_size_status) {
+				$max_size_status = length($status);
+			}
+			if (length($a) > $max_size_arch) {
+				$max_size_arch = length($a);
+			}
+
+			$status = "---" if ($status =~ m/^\.\.$/);
+
+			$archs{$a} = 1;
+			$arch_table{$a} = $status;
+			next;
+		}
+
+		#Everything else is an error
+		parse_error($file, $ln, "line is invalid", $_);
+	}
+	close IN;
+
+	if (!$name) {
+		parse_error($file, $ln, "Feature name not found", "");
+		return;
+	}
+
+	parse_error($file, $ln, "Subsystem not found", "") if (!$subsys);
+	parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig);
+	parse_error($file, $ln, "Description not found", "") if (!$description);
+
+	if (!%arch_table) {
+		parse_error($file, $ln, "Architecture table not found", "");
+		return;
+	}
+
+	$data{$name}->{where} = $file;
+	$data{$name}->{subsys} = $subsys;
+	$data{$name}->{kconfig} = $kconfig;
+	$data{$name}->{description} = $description;
+	$data{$name}->{comments} = $comments;
+	$data{$name}->{table} = \%arch_table;
+}
+
+#
+# Output feature(s) for a given architecture
+#
+sub output_arch_table {
+	my $title = "Feature status on $arch architecture";
+
+	print "=" x length($title) . "\n";
+	print "$title\n";
+	print "=" x length($title) . "\n\n";
+
+	print "=" x $max_size_subsys;
+	print "  ";
+	print "=" x $max_size_name;
+	print "  ";
+	print "=" x $max_size_kconfig;
+	print "  ";
+	print "=" x $max_size_status;
+	print "  ";
+	print "=" x $max_size_description;
+	print "\n";
+	printf "%-${max_size_subsys}s  ", $h_subsys;
+	printf "%-${max_size_name}s  ", $h_name;
+	printf "%-${max_size_kconfig}s  ", $h_kconfig;
+	printf "%-${max_size_status}s  ", $h_status;
+	printf "%-${max_size_description}s\n", $h_description;
+	print "=" x $max_size_subsys;
+	print "  ";
+	print "=" x $max_size_name;
+	print "  ";
+	print "=" x $max_size_kconfig;
+	print "  ";
+	print "=" x $max_size_status;
+	print "  ";
+	print "=" x $max_size_description;
+	print "\n";
+
+	foreach my $name (sort {
+				($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
+				($data{$a}->{name} cmp $data{$b}->{name})
+			       } keys %data) {
+		next if ($feat && $name ne $feat);
+
+		my %arch_table = %{$data{$name}->{table}};
+		printf "%-${max_size_subsys}s  ", $data{$name}->{subsys};
+		printf "%-${max_size_name}s  ", $name;
+		printf "%-${max_size_kconfig}s  ", $data{$name}->{kconfig};
+		printf "%-${max_size_status}s  ", $arch_table{$arch};
+		printf "%-${max_size_description}s\n", $data{$name}->{description};
+	}
+
+	print "=" x $max_size_subsys;
+	print "  ";
+	print "=" x $max_size_name;
+	print "  ";
+	print "=" x $max_size_kconfig;
+	print "  ";
+	print "=" x $max_size_status;
+	print "  ";
+	print "=" x $max_size_description;
+	print "\n";
+}
+
+#
+# Output a feature on all architectures
+#
+sub output_feature {
+	my $title = "Feature $feat";
+
+	print "=" x length($title) . "\n";
+	print "$title\n";
+	print "=" x length($title) . "\n\n";
+
+	print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys});
+	print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig});
+
+	my $desc = $data{$feat}->{description};
+	$desc =~ s/^([a-z])/\U$1/;
+	$desc =~ s/\.?\s*//;
+	print "\n$desc.\n\n";
+
+	my $com = $data{$feat}->{comments};
+	$com =~ s/^\s+//;
+	$com =~ s/\s+$//;
+	if ($com) {
+		print "Comments\n";
+		print "--------\n\n";
+		print "$com\n\n";
+	}
+
+	print "=" x $max_size_arch;
+	print "  ";
+	print "=" x $max_size_status;
+	print "\n";
+
+	printf "%-${max_size_arch}s  ", $h_arch;
+	printf "%-${max_size_status}s", $h_status . "\n";
+
+	print "=" x $max_size_arch;
+	print "  ";
+	print "=" x $max_size_status;
+	print "\n";
+
+	my %arch_table = %{$data{$feat}->{table}};
+	foreach my $arch (sort keys %arch_table) {
+		printf "%-${max_size_arch}s  ", $arch;
+		printf "%-${max_size_status}s\n", $arch_table{$arch};
+	}
+
+	print "=" x $max_size_arch;
+	print "  ";
+	print "=" x $max_size_status;
+	print "\n";
+}
+
+#
+# Output all features for all architectures
+#
+
+sub matrix_lines {
+	print "=" x $max_size_subsys;
+	print "  ";
+	print "=" x $max_size_name;
+	print "  ";
+
+	foreach my $arch (sort keys %archs) {
+		my $len = $max_size_status;
+
+		$len = length($arch) if ($len < length($arch));
+
+		print "=" x $len;
+		print "  ";
+	}
+	print "=" x $max_size_kconfig;
+	print "  ";
+	print "=" x $max_size_description;
+	print "\n";
+}
+
+sub output_matrix {
+
+	my $title = "Feature List (feature x architecture)";
+
+	print "=" x length($title) . "\n";
+	print "$title\n";
+	print "=" x length($title) . "\n\n";
+
+	matrix_lines;
+
+	printf "%-${max_size_subsys}s  ", $h_subsys;
+	printf "%-${max_size_name}s  ", $h_name;
+
+	foreach my $arch (sort keys %archs) {
+		printf "%-${max_size_status}s  ", $arch;
+	}
+	printf "%-${max_size_kconfig}s  ", $h_kconfig;
+	printf "%-${max_size_description}s\n", $h_description;
+
+	matrix_lines;
+
+	foreach my $name (sort {
+				($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
+				($data{$a}->{name} cmp $data{$b}->{name})
+			       } keys %data) {
+		printf "%-${max_size_subsys}s  ", $data{$name}->{subsys};
+		printf "%-${max_size_name}s  ", $name;
+
+		my %arch_table = %{$data{$name}->{table}};
+
+		foreach my $arch (sort keys %arch_table) {
+			my $len = $max_size_status;
+
+			$len = length($arch) if ($len < length($arch));
+
+			printf "%-${len}s  ", $arch_table{$arch};
+		}
+		printf "%-${max_size_kconfig}s  ", $data{$name}->{kconfig};
+		printf "%-${max_size_description}s\n", $data{$name}->{description};
+	}
+
+	matrix_lines;
+}
+
+
+#
+# Parses all feature files located at $prefix dir
+#
+find({wanted =>\&parse_feat, no_chdir => 1}, $prefix);
+
+print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
+
+#
+# Handles the command
+#
+if ($cmd eq "current") {
+	$arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/');
+	$arch =~s/\s+$//;
+}
+
+if ($cmd ne "validate") {
+	if ($arch) {
+		output_arch_table;
+	} elsif ($feat) {
+		output_feature;
+	} else {
+		output_matrix;
+	}
+}
+
+__END__
+
+=head1 NAME
+
+get_feat.pl - parse the Linux Feature files and produce a ReST book.
+
+=head1 SYNOPSIS
+
+B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>]
+	       [--arch=<arch>] [--feat=<feature>] <COMAND> [<ARGUMENT>]
+
+Where <COMMAND> can be:
+
+=over 8
+
+B<current>               - output features for this machine's architecture
+
+B<rest>                  - output features in ReST markup language
+
+B<validate>              - validate the feature contents
+
+=back
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<--arch>
+
+Output features for an specific architecture, optionally filtering for
+a single specific feature.
+
+=item B<--feat>
+
+Output features for a single specific architecture.
+
+=item B<--dir>
+
+Changes the location of the Feature files. By default, it uses
+the Documentation/features directory.
+
+=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 feature files from Documentation/features (by default),
+optionally producing results at ReST format.
+
+It supports output data per architecture, per feature or a
+feature x arch matrix.
+
+When used with B<rest> command, it will use either one of the tree formats:
+
+If neither B<--arch> or B<--feature> arguments are used, it will output a
+matrix with features per architecture.
+
+If B<--arch> argument is used, it will output the features availability for
+a given architecture.
+
+If B<--feat> argument is used, it will output the content of the feature
+file using ReStructured Text markup.
+
+=head1 BUGS
+
+Report bugs to Mauro Carvalho Chehab <[email protected]>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2019 by Mauro Carvalho Chehab <[email protected]>.
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+=cut
Signature · 1 line
2.28.0
#2 lore raw

PATCH 2/6 scripts: get_feat.pl: improve matrix output

In reply to Mauro Carvalho Chehab

Instead of producing a too wide table, let's split it per subsystem, and use a better notation in order to make easier for the reader to identify how a feature is supported on multiple architectures.

---
 scripts/get_feat.pl | 113 +++++++++++++++++++++++++++-----------------
 1 file changed, 70 insertions(+), 43 deletions(-)
scripts/get_feat.pl +70 -43
index 79d83595addd..7b92ebab7ddd 100755
@@ -293,68 +293,95 @@ sub output_feature {
 # Output all features for all architectures
 #
 
-sub matrix_lines {
-	print "=" x $max_size_subsys;
-	print "  ";
-	print "=" x $max_size_name;
-	print "  ";
+sub matrix_lines($$) {
+	my $partial = shift;
+	my $header = shift;
+	my $split;
+	my $fill;
+	my $ln_marker;
 
-	foreach my $arch (sort keys %archs) {
-		my $len = $max_size_status;
-
-		$len = length($arch) if ($len < length($arch));
+	if ($header) {
+		$ln_marker = "=";
+	} else {
+		$ln_marker = "-";
+	}
 
-		print "=" x $len;
-		print "  ";
+	if ($partial) {
+		$split = "|";
+		$fill = " ";
+	} else {
+		$split = "+";
+		$fill = $ln_marker;
 	}
-	print "=" x $max_size_kconfig;
-	print "  ";
-	print "=" x $max_size_description;
-	print "\n";
+
+	print $split;
+	print $fill x $max_size_name;
+	print $split;
+	print $fill x $max_size_kconfig;
+	print $split;
+	print $fill x $max_size_description;
+	print "+";
+	print $ln_marker x $max_size_arch;
+	print "+";
+	print $ln_marker x $max_size_status;
+	print "+\n";
 }
 
 sub output_matrix {
-
-	my $title = "Feature List (feature x architecture)";
+	my $title = "Feature status on all architectures";
 
 	print "=" x length($title) . "\n";
 	print "$title\n";
 	print "=" x length($title) . "\n\n";
 
-	matrix_lines;
-
-	printf "%-${max_size_subsys}s  ", $h_subsys;
-	printf "%-${max_size_name}s  ", $h_name;
-
-	foreach my $arch (sort keys %archs) {
-		printf "%-${max_size_status}s  ", $arch;
-	}
-	printf "%-${max_size_kconfig}s  ", $h_kconfig;
-	printf "%-${max_size_description}s\n", $h_description;
-
-	matrix_lines;
-
+	my $cur_subsys = "";
 	foreach my $name (sort {
-				($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
-				($data{$a}->{name} cmp $data{$b}->{name})
+				($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
+				($a cmp $b)
 			       } keys %data) {
-		printf "%-${max_size_subsys}s  ", $data{$name}->{subsys};
-		printf "%-${max_size_name}s  ", $name;
+
+		if ($cur_subsys ne $data{$name}->{subsys}) {
+			if ($cur_subsys ne "") {
+				printf "\n";
+			}
+
+			$cur_subsys = $data{$name}->{subsys};
+
+			my $title = "Subsystem: $cur_subsys";
+			print "$title\n";
+			print "=" x length($title) . "\n\n";
+
+			matrix_lines(0, 0);
+			printf "|%-${max_size_name}s", $h_name;
+			printf "|%-${max_size_kconfig}s", $h_kconfig;
+			printf "|%-${max_size_description}s", $h_description;
+
+			printf "|%-${max_size_arch}s", $h_arch;
+			printf "|%-${max_size_status}s|\n", $h_status;
+
+			matrix_lines(0, 1);
+		}
 
 		my %arch_table = %{$data{$name}->{table}};
-
+		my $first = 1;
 		foreach my $arch (sort keys %arch_table) {
-			my $len = $max_size_status;
+			if ($first) {
+				printf "|%-${max_size_name}s", $name;
+				printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig};
+				printf "|%-${max_size_description}s", $data{$name}->{description};
+				$first = 0;
+			} else {
+				matrix_lines(1, 0);
 
-			$len = length($arch) if ($len < length($arch));
-
-			printf "%-${len}s  ", $arch_table{$arch};
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${max_size_kconfig}s", "";
+				printf "|%-${max_size_description}s", "";
+			}
+			printf "|%-${max_size_arch}s", $arch;
+			printf "|%-${max_size_status}s|\n", $arch_table{$arch};
 		}
-		printf "%-${max_size_kconfig}s  ", $data{$name}->{kconfig};
-		printf "%-${max_size_description}s\n", $data{$name}->{description};
+		matrix_lines(0, 0);
 	}
-
-	matrix_lines;
 }
 
 
Signature · 1 line
2.28.0
#3 lore raw

PATCH 3/6 scripts: get_feat.pl: use its implementation for list-arch.sh

In reply to Mauro Carvalho Chehab

Add support for the same output format as the bash script, and use its implementation instead of the previous one.

I opted to do such patch in order to have a single script responsible for parsing Documentation/features and produce different outputs.

As someone may rely on the past format, which is easy to parse it, get_feat.pl now gains a new command with the same output format as the previous script.

As a side effect, the perl script is a lot faster, as it reads each file only once, instead of parsing files several times via a for command and grep commands inside it.

This patch also changes the features list order to be case-insensitive, in order to better match the output of the existing script.

---
 Documentation/features/list-arch.sh | 17 +------
 scripts/get_feat.pl                 | 77 ++++++++++++++++++++++++-----
 2 files changed, 66 insertions(+), 28 deletions(-)
Documentation/features/list-arch.sh +2 -15
index 1ec47c3bb5fa..e73aa35848f0 100755
@@ -1,3 +1,4 @@
+# SPDX-License-Identifier: GPL-2.0
 #
 # Small script that visualizes the kernel feature support status
 # of an architecture.
@@ -7,18 +8,4 @@
 
 ARCH=${1:-$(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/')}
 
-cd $(dirname $0)
-echo "#"
-echo "# Kernel feature support matrix of the '$ARCH' architecture:"
-echo "#"
-
-for F in */*/arch-support.txt; do
-  SUBSYS=$(echo $F | cut -d/ -f1)
-  N=$(grep -h "^# Feature name:"        $F | cut -c25-)
-  C=$(grep -h "^#         Kconfig:"     $F | cut -c25-)
-  D=$(grep -h "^#         description:" $F | cut -c25-)
-  S=$(grep -hv "^#" $F | grep -w $ARCH | cut -d\| -f3)
-
-  printf "%10s/%-22s:%s| %35s # %s\n" "$SUBSYS" "$N" "$S" "$C" "$D"
-done
-
+$(dirname $0)/../../scripts/get_feat.pl list --arch $ARCH
scripts/get_feat.pl +64 -13

154 lines not on this page · raw message

Signature · 1 line
2.28.0
#4 lore raw

PATCH 4/6 sphinx: kernel_feat.py: add a script to parse feature files

In reply to Mauro Carvalho Chehab

The feature files have a special well-defined format. Add a script that parses them, allowing to search for a feature and/or by an architecture and to produce ReST-compatible outputs.

---
 Documentation/sphinx/kernel_feat.py | 169 ++++++++++++++++++++++++++++
 1 file changed, 169 insertions(+)
 create mode 100644 Documentation/sphinx/kernel_feat.py
Documentation/sphinx/kernel_feat.py new file +169 -0
new file mode 100644
index 000000000000..2fee04f1dedd
@@ -0,0 +1,169 @@
+# coding=utf-8
+# SPDX-License-Identifier: GPL-2.0
+#
+u"""
+    kernel-feat
+    ~~~~~~~~~~~
+
+    Implementation of the ``kernel-feat`` reST-directive.
+
+    :copyright:  Copyright (C) 2016  Markus Heiser
+    :copyright:  Copyright (C) 2016-2019  Mauro Carvalho Chehab
+    :maintained-by: Mauro Carvalho Chehab <[email protected]>
+    :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
+
+    The ``kernel-feat`` (:py:class:`KernelFeat`) directive calls the
+    scripts/get_feat.pl script to parse the Kernel ABI files.
+
+    Overview of directive's argument and options.
+
+    .. code-block:: rst
+
+        .. kernel-feat:: <ABI directory location>
+            :debug:
+
+    The argument ``<ABI directory location>`` is required. It contains the
+    location of the ABI files to be parsed.
+
+    ``debug``
+      Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+      what reST is generated.
+
+"""
+
+import codecs
+import os
+import subprocess
+import sys
+
+from os import path
+
+from docutils import nodes, statemachine
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import directives, Directive
+from docutils.utils.error_reporting import ErrorString
+
+#
+# AutodocReporter is only good up to Sphinx 1.7
+#
+import sphinx
+
+Use_SSI = sphinx.__version__[:3] >= '1.7'
+if Use_SSI:
+    from sphinx.util.docutils import switch_source_input
+else:
+    from sphinx.ext.autodoc import AutodocReporter
+
+__version__  = '1.0'
+
+def setup(app):
+
+    app.add_directive("kernel-feat", KernelFeat)
+    return dict(
+        version = __version__
+        , parallel_read_safe = True
+        , parallel_write_safe = True
+    )
+
+class KernelFeat(Directive):
+
+    u"""KernelFeat (``kernel-feat``) directive"""
+
+    required_arguments = 1
+    optional_arguments = 2
+    has_content = False
+    final_argument_whitespace = True
+
+    option_spec = {
+        "debug"     : directives.flag
+    }
+
+    def warn(self, message, **replace):
+        replace["fname"]   = self.state.document.current_source
+        replace["line_no"] = replace.get("line_no", self.lineno)
+        message = ("%(fname)s:%(line_no)s: [kernel-feat WARN] : " + message) % replace
+        self.state.document.settings.env.app.warn(message, prefix="")
+
+    def run(self):
+
+        doc = self.state.document
+        if not doc.settings.file_insertion_enabled:
+            raise self.warning("docutils: file insertion disabled")
+
+        env = doc.settings.env
+        cwd = path.dirname(doc.current_source)
+        cmd = "get_feat.pl rest --dir "
+        cmd += self.arguments[0]
+
+        if len(self.arguments) > 1:
+            cmd += " --arch " + self.arguments[1]
+
+        srctree = path.abspath(os.environ["srctree"])
+
+        fname = cmd
+
+        # extend PATH with $(srctree)/scripts
+        path_env = os.pathsep.join([
+            srctree + os.sep + "scripts",
+            os.environ["PATH"]
+        ])
+        shell_env = os.environ.copy()
+        shell_env["PATH"]    = path_env
+        shell_env["srctree"] = srctree
+
+        lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+        nodeList = self.nestedParse(lines, fname)
+        return nodeList
+
+    def runCmd(self, cmd, **kwargs):
+        u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+        try:
+            proc = subprocess.Popen(
+                cmd
+                , stdout = subprocess.PIPE
+                , stderr = subprocess.PIPE
+                , **kwargs
+            )
+            out, err = proc.communicate()
+
+            out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
+
+            if proc.returncode != 0:
+                raise self.severe(
+                    u"command '%s' failed with return code %d"
+                    % (cmd, proc.returncode)
+                )
+        except OSError as exc:
+            raise self.severe(u"problems with '%s' directive: %s."
+                              % (self.name, ErrorString(exc)))
+        return out
+
+    def nestedParse(self, lines, fname):
+        content = ViewList()
+        node    = nodes.section()
+
+        if "debug" in self.options:
+            code_block = "\n\n.. code-block:: rst\n    :linenos:\n"
+            for l in lines.split("\n"):
+                code_block += "\n    " + l
+            lines = code_block + "\n\n"
+
+        for c, l in enumerate(lines.split("\n")):
+            content.append(l, fname, c)
+
+        buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+
+        if Use_SSI:
+            with switch_source_input(self.state, content):
+                self.state.nested_parse(content, 0, node, match_titles=1)
+        else:
+            self.state.memo.title_styles  = []
+            self.state.memo.section_level = 0
+            self.state.memo.reporter      = AutodocReporter(content, self.state.memo.reporter)
+            try:
+                self.state.nested_parse(content, 0, node, match_titles=1)
+            finally:
+                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
+        return node.children
Signature · 1 line
2.28.0
#5 lore raw

PATCH 5/6 docs: admin-guide: add a features list

In reply to Mauro Carvalho Chehab

Add a feature list matrix at the admin-guide.

---
 Documentation/admin-guide/features.rst | 3 +++
 Documentation/admin-guide/index.rst    | 1 +
 Documentation/conf.py                  | 2 +-
 3 files changed, 5 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/features.rst
Documentation/admin-guide/features.rst new file +3 -0
new file mode 100644
index 000000000000..8c167082a84f
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features
Documentation/admin-guide/index.rst +1 -0
index 4e0c4ae44acd..0245a8655b22 100644
@@ -19,6 +19,7 @@ etc.
    sysctl/index
 
    abi
+   features
 
 This section describes CPU vulnerabilities and their mitigations.
 
Documentation/conf.py +1 -1
index ed2b43ec7754..26b54386a477 100644
@@ -39,7 +39,7 @@ needs_sphinx = '1.3'
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
               'maintainers_include', 'sphinx.ext.autosectionlabel',
-              'kernel_abi']
+              'kernel_abi', 'kernel_feat']
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
Signature · 1 line
2.28.0
#6 lore raw

PATCH 6/6 docs: archis: add a per-architecture features list

In reply to Mauro Carvalho Chehab

Add a feature list matrix for each architecture to their respective Kernel books.

---
 Documentation/arm/features.rst      |  3 +++
 Documentation/arm/index.rst         |  2 ++
 Documentation/arm64/features.rst    |  3 +++
 Documentation/arm64/index.rst       |  2 ++
 Documentation/ia64/features.rst     |  3 +++
 Documentation/ia64/index.rst        |  2 ++
 Documentation/index.rst             |  2 +-
 Documentation/m68k/features.rst     |  3 +++
 Documentation/m68k/index.rst        |  2 ++
 Documentation/mips/features.rst     |  3 +++
 Documentation/mips/index.rst        |  2 ++
 Documentation/nios2/index.rst       | 12 ++++++++++++
 Documentation/openrisc/features.rst |  3 +++
 Documentation/openrisc/index.rst    |  2 ++
 Documentation/parisc/features.rst   |  3 +++
 Documentation/parisc/index.rst      |  2 ++
 Documentation/powerpc/features.rst  |  3 +++
 Documentation/powerpc/index.rst     |  2 ++
 Documentation/riscv/features.rst    |  3 +++
 Documentation/riscv/index.rst       |  2 ++
 Documentation/s390/features.rst     |  3 +++
 Documentation/s390/index.rst        |  2 ++
 Documentation/sh/features.rst       |  3 +++
 Documentation/sh/index.rst          |  2 ++
 Documentation/sparc/features.rst    |  3 +++
 Documentation/sparc/index.rst       |  2 ++
 Documentation/x86/features.rst      |  3 +++
 Documentation/x86/index.rst         |  1 +
 Documentation/xtensa/features.rst   |  3 +++
 Documentation/xtensa/index.rst      |  2 ++
 30 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/arm/features.rst
 create mode 100644 Documentation/arm64/features.rst
 create mode 100644 Documentation/ia64/features.rst
 create mode 100644 Documentation/m68k/features.rst
 create mode 100644 Documentation/mips/features.rst
 create mode 100644 Documentation/nios2/index.rst
 create mode 100644 Documentation/openrisc/features.rst
 create mode 100644 Documentation/parisc/features.rst
 create mode 100644 Documentation/powerpc/features.rst
 create mode 100644 Documentation/riscv/features.rst
 create mode 100644 Documentation/s390/features.rst
 create mode 100644 Documentation/sh/features.rst
 create mode 100644 Documentation/sparc/features.rst
 create mode 100644 Documentation/x86/features.rst
 create mode 100644 Documentation/xtensa/features.rst
Documentation/arm/features.rst new file +3 -0
new file mode 100644
index 000000000000..7414ec03dd15
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features arm
Documentation/arm/index.rst +2 -0
index 5fc072dd0c5e..a2e9e1bba7b9 100644
@@ -23,6 +23,8 @@ ARM Architecture
    vlocks
    porting
 
+   features
+
 SoC-specific documents
 ===========
 
Documentation/arm64/features.rst new file +3 -0
new file mode 100644
index 000000000000..dfa4cb3cd3ef
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features arm64
Documentation/arm64/index.rst +2 -0
index 937634c49979..97d65ba12a35 100644
@@ -24,6 +24,8 @@ ARM64 Architecture
     tagged-address-abi
     tagged-pointers
 
+    features
+
 .. only::  subproject and html
 
    Indices
Documentation/ia64/features.rst new file +3 -0
new file mode 100644
index 000000000000..d7226fdcf5f8
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features ia64
Documentation/ia64/index.rst +2 -0
index 4bdfe28067ee..761f2154dfa2 100644
@@ -15,3 +15,5 @@ IA-64 Architecture
    irq-redir
    mca
    serial
+
+   features
Documentation/index.rst +1 -1
index 57719744774c..5888e8a7272f 100644
@@ -160,7 +160,7 @@ implementation.
    ia64/index
    m68k/index
    mips/index
-   nios2/nios2
+   nios2/index
    openrisc/index
    parisc/index
    powerpc/index
Documentation/m68k/features.rst new file +3 -0
new file mode 100644
index 000000000000..5107a2119472
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features m68k
Documentation/m68k/index.rst +2 -0
index b89cb6a86d9b..0f890dbb5fe2 100644
@@ -10,6 +10,8 @@ m68k Architecture
    kernel-options
    buddha-driver
 
+   features
+
 .. only::  subproject and html
 
    Indices
Documentation/mips/features.rst new file +3 -0
new file mode 100644
index 000000000000..1973d729b29a
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features mips
Documentation/mips/index.rst +2 -0
index 35cceea4e8bc..037f85a08fe3 100644
@@ -11,6 +11,8 @@ MIPS-specific Documentation
    booting
    ingenic-tcu
 
+   features
+
 .. only::  subproject and html
 
    Indices
Documentation/nios2/index.rst new file +12 -0
new file mode 100644
index 000000000000..4468fe1a1037
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Nios II Specific Documentation
+===============
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   nios2
+   features
Documentation/openrisc/features.rst new file +3 -0
new file mode 100644
index 000000000000..3f7c40d219f2
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features openrisc
Documentation/openrisc/index.rst +2 -0
index 748b3eea1707..6879f998b87a 100644
@@ -10,6 +10,8 @@ OpenRISC Architecture
    openrisc_port
    todo
 
+   features
+
 .. only::  subproject and html
 
    Indices
Documentation/parisc/features.rst new file +3 -0
new file mode 100644
index 000000000000..501d7c450037
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features parisc
Documentation/parisc/index.rst +2 -0
index aa3ee0470425..240685751825 100644
@@ -10,6 +10,8 @@ PA-RISC Architecture
    debugging
    registers
 
+   features
+
 .. only::  subproject and html
 
    Indices
Documentation/powerpc/features.rst new file +3 -0
new file mode 100644
index 000000000000..aeae73df86b0
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features powerpc
Documentation/powerpc/index.rst +2 -0
index 6ec64b0d5257..bf5f1a2bdbdf 100644
@@ -34,6 +34,8 @@ powerpc
     vas-api
     vcpudispatch_stats
 
+    features
+
 .. only::  subproject and html
 
    Indices
Documentation/riscv/features.rst new file +3 -0
new file mode 100644
index 000000000000..c70ef6ac2368
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features riscv
Documentation/riscv/index.rst +2 -0
index fa33bffd8992..6e6e39482502 100644
@@ -9,6 +9,8 @@ RISC-V architecture
     pmu
     patch-acceptance
 
+    features
+
 .. only::  subproject and html
 
    Indices
Documentation/s390/features.rst new file +3 -0
new file mode 100644
index 000000000000..57c296a9d8f3
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features s390
Documentation/s390/index.rst +2 -0
index cf71df5776b4..b10ca9192557 100644
@@ -19,6 +19,8 @@ s390 Architecture
 
     text_files
 
+    features
+
 .. only::  subproject and html
 
    Indices
Documentation/sh/features.rst new file +3 -0
new file mode 100644
index 000000000000..f722af3b6c99
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features sh
Documentation/sh/index.rst +2 -0
index 7b9a79a28167..c64776738cf6 100644
@@ -11,6 +11,8 @@ SuperH Interfaces Guide
     new-machine
     register-banks
 
+    features
+
 Memory Management
 ======== 
Documentation/sparc/features.rst new file +3 -0
new file mode 100644
index 000000000000..c0c92468b0fe
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features sparc
Documentation/sparc/index.rst +2 -0
index 71cff621f243..ae884224eec2 100644
@@ -9,3 +9,5 @@ Sparc Architecture
    adi
 
    oradax/oracle-dax
+
+   features
Documentation/x86/features.rst new file +3 -0
new file mode 100644
index 000000000000..b663f15053ce
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features x86
Documentation/x86/index.rst +1 -0
index b224d12c880b..b4fcb6f258b2 100644
@@ -33,3 +33,4 @@ x86-specific Documentation
    i386/index
    x86_64/index
    sva
+   features
Documentation/xtensa/features.rst new file +3 -0
new file mode 100644
index 000000000000..6b92c7bfa19d
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features xtensa
Documentation/xtensa/index.rst +2 -0
index 52fa04eb39a3..69952446a9be 100644
@@ -10,3 +10,5 @@ Xtensa Architecture
    atomctl
    booting
    mmu
+
+   features
Signature · 1 line
2.28.0
maintainer
#7 lore raw
In reply to Mauro Carvalho Chehab
Quoted 8 lines · On Mon, 30 Nov 2020 16:36:29 +0100 Mauro Carvalho Chehab…

This series got already submitted last year:

   https://lore.kernel.org/lkml/[email protected]/

Yet, on that time, there were too many other patches related to ReST conversion floating around. So, at the end, I guess this one got missed.

So, I did a rebase on the top of upstream, and added a few new changes.

OK, I've gone ahead and applied these; it gains me a new trivial conflict with x86, but so be it...

That said, I think that the RST table formatting could be *way* improved. The current tables are all white space and hard to make sense of. What if we condensed the information? Just looking at the first entry in Documentation/admin-guide/features.html, perhaps it could look like:

FEATURE KCONFIG/DESCRIPTION STATUS

cBPF-JIT HAVE_CBPF_JIT TODO: alpha, arc, arm...
ok: mips, powerpc, ...
arch supports cBPF JIT
optimizations

The result would be far more compact and easy to read, IMO. I may get around to giving this a try if (hint :) nobody else gets there first.

Thanks,

jon

#8 lore raw

PATCH 1/1 scripts: get_feat.pl: make complete table more coincise

Currently, there are too many white spaces at the tables, and the information is very sparsed on it.

Make the format a lot more compact.

---
 scripts/get_feat.pl | 107 +++++++++++++++++++++++++++++++++-----------
 1 file changed, 81 insertions(+), 26 deletions(-)
scripts/get_feat.pl +81 -26
index 81d1b78d65c9..f3777f6d32bb 100755
@@ -325,7 +325,9 @@ sub output_feature {
 # Output all features for all architectures
 #
 
-sub matrix_lines($$) {
+sub matrix_lines($$$$) {
+	my $desc_size = shift;
+	my $status_size = shift;
 	my $partial = shift;
 	my $header = shift;
 	my $split;
@@ -349,13 +351,9 @@ sub matrix_lines($$) {
 	print $split;
 	print $fill x $max_size_name;
 	print $split;
-	print $fill x $max_size_kconfig;
-	print $split;
-	print $fill x $max_size_description;
+	print $fill x $desc_size;
 	print "+";
-	print $ln_marker x $max_size_arch;
-	print "+";
-	print $ln_marker x $max_size_status;
+	print $ln_marker x $status_size;
 	print "+\n";
 }
 
@@ -366,6 +364,14 @@ sub output_matrix {
 	print "$title\n";
 	print "=" x length($title) . "\n\n";
 
+	my $desc_title = "$h_kconfig / $h_description";
+
+	my $desc_size = $max_size_kconfig + 4;
+	$desc_size = $max_size_description if ($max_size_description > $desc_size);
+	$desc_size = length($desc_title) if (length($desc_title) > $desc_size);
+
+	my $status_size = 60;
+
 	my $cur_subsys = "";
 	foreach my $name (sort {
 				($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +389,85 @@ sub output_matrix {
 			print "$title\n";
 			print "=" x length($title) . "\n\n";
 
-			matrix_lines(0, 0);
+
+			matrix_lines($desc_size, $status_size, 0, 0);
+
 			printf "|%-${max_size_name}s", $h_name;
-			printf "|%-${max_size_kconfig}s", $h_kconfig;
-			printf "|%-${max_size_description}s", $h_description;
+			printf "|%-${desc_size}s", $desc_title;
 
-			printf "|%-${max_size_arch}s", $h_arch;
-			printf "|%-${max_size_status}s|\n", $h_status;
-
-			matrix_lines(0, 1);
+			printf "|%-${status_size}s|\n", "Status per architecture";
+			matrix_lines($desc_size, $status_size, 0, 1);
 		}
 
 		my %arch_table = %{$data{$name}->{table}};
-		my $first = 1;
-		foreach my $arch (sort keys %arch_table) {
-			if ($first) {
+		my $cur_status = "";
+
+		my @lines;
+		my $line = "";
+		foreach my $arch (sort {
+					($arch_table{$a} cmp $arch_table{$b}) or
+					("\L$a" cmp "\L$b")
+				       } keys %arch_table) {
+
+			my $status = $arch_table{$arch};
+
+			if ($status eq "---") {
+				$status = "Not compatible";
+			}
+
+			if ($status ne $cur_status) {
+				if ($line ne "") {
+					push @lines, $line;
+					$line = "";
+				}
+				$line = "- **" . $status . "**: " . $arch;
+			} elsif (length($line) + length ($arch) + 2 < $status_size) {
+				$line .= ", " . $arch;
+			} else {
+				push @lines, $line;
+				$line = "  " . $arch;
+			}
+			$cur_status = $status;
+		}
+		push @lines, $line if ($line ne "");
+
+		my $ln = 0;
+		for my $line(@lines) {
+			if (!$ln) {
 				printf "|%-${max_size_name}s", $name;
-				printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig};
-				printf "|%-${max_size_description}s", $data{$name}->{description};
-				$first = 0;
+				printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``";
+			} elsif ($ln == 2) {
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", $data{$name}->{description};
 			} else {
-				matrix_lines(1, 0);
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", "";
+			}
+
+			printf "|%-${status_size}s|\n", $line;
 
+			$ln++;
+		}
+
+		# Ensure that Kconfig and description will be printed
+		while ($ln < 2) {
+			if (!$ln) {
+				printf "|%-${max_size_name}s", $name;
+				printf "|%-${desc_size}s``", $data{$name}->{kconfig} . "``";
+			} elsif ($ln == 2) {
 				printf "|%-${max_size_name}s", "";
-				printf "|%-${max_size_kconfig}s", "";
-				printf "|%-${max_size_description}s", "";
+				printf "|%-${desc_size}s", $data{$name}->{description};
+			} else {
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", "";
 			}
-			printf "|%-${max_size_arch}s", $arch;
-			printf "|%-${max_size_status}s|\n", $arch_table{$arch};
+
+			printf "|%-${status_size}s|\n", "";
+
+			$ln++;
 		}
-		matrix_lines(0, 0);
+
+		matrix_lines($desc_size, $status_size, 0, 0);
 	}
 }
 
Signature · 1 line
2.28.0
#9 lore raw

PATCH v2 1/1 scripts: get_feat.pl: make complete table more coincise

Currently, there are too many white spaces at the tables, and the information is very sparsed on it.

Make the format a lot more compact.

---
 scripts/get_feat.pl | 119 ++++++++++++++++++++++++++++++--------------
 1 file changed, 83 insertions(+), 36 deletions(-)
scripts/get_feat.pl +83 -36
index 81d1b78d65c9..2860abfdcd91 100755
@@ -325,10 +325,10 @@ sub output_feature {
 # Output all features for all architectures
 #
 
-sub matrix_lines($$) {
-	my $partial = shift;
+sub matrix_lines($$$) {
+	my $desc_size = shift;
+	my $status_size = shift;
 	my $header = shift;
-	my $split;
 	my $fill;
 	my $ln_marker;
 
@@ -338,24 +338,14 @@ sub matrix_lines($$) {
 		$ln_marker = "-";
 	}
 
-	if ($partial) {
-		$split = "|";
-		$fill = " ";
-	} else {
-		$split = "+";
-		$fill = $ln_marker;
-	}
+	$fill = $ln_marker;
 
-	print $split;
+	print "+";
 	print $fill x $max_size_name;
-	print $split;
-	print $fill x $max_size_kconfig;
-	print $split;
-	print $fill x $max_size_description;
 	print "+";
-	print $ln_marker x $max_size_arch;
+	print $fill x $desc_size;
 	print "+";
-	print $ln_marker x $max_size_status;
+	print $ln_marker x $status_size;
 	print "+\n";
 }
 
@@ -366,6 +356,14 @@ sub output_matrix {
 	print "$title\n";
 	print "=" x length($title) . "\n\n";
 
+	my $desc_title = "$h_kconfig / $h_description";
+
+	my $desc_size = $max_size_kconfig + 4;
+	$desc_size = $max_size_description if ($max_size_description > $desc_size);
+	$desc_size = length($desc_title) if (length($desc_title) > $desc_size);
+
+	my $status_size = 60;
+
 	my $cur_subsys = "";
 	foreach my $name (sort {
 				($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +381,85 @@ sub output_matrix {
 			print "$title\n";
 			print "=" x length($title) . "\n\n";
 
-			matrix_lines(0, 0);
+
+			matrix_lines($desc_size, $status_size, 0);
+
 			printf "|%-${max_size_name}s", $h_name;
-			printf "|%-${max_size_kconfig}s", $h_kconfig;
-			printf "|%-${max_size_description}s", $h_description;
+			printf "|%-${desc_size}s", $desc_title;
 
-			printf "|%-${max_size_arch}s", $h_arch;
-			printf "|%-${max_size_status}s|\n", $h_status;
-
-			matrix_lines(0, 1);
+			printf "|%-${status_size}s|\n", "Status per architecture";
+			matrix_lines($desc_size, $status_size, 1);
 		}
 
 		my %arch_table = %{$data{$name}->{table}};
-		my $first = 1;
-		foreach my $arch (sort keys %arch_table) {
-			if ($first) {
+		my $cur_status = "";
+
+		my @lines;
+		my $line = "";
+		foreach my $arch (sort {
+					($arch_table{$a} cmp $arch_table{$b}) or
+					("\L$a" cmp "\L$b")
+				       } keys %arch_table) {
+
+			my $status = $arch_table{$arch};
+
+			if ($status eq "---") {
+				$status = "Not compatible";
+			}
+
+			if ($status ne $cur_status) {
+				if ($line ne "") {
+					push @lines, $line;
+					$line = "";
+				}
+				$line = "- **" . $status . "**: " . $arch;
+			} elsif (length($line) + length ($arch) + 2 < $status_size) {
+				$line .= ", " . $arch;
+			} else {
+				push @lines, $line;
+				$line = "  " . $arch;
+			}
+			$cur_status = $status;
+		}
+		push @lines, $line if ($line ne "");
+
+		my $ln = 0;
+		for my $line(@lines) {
+			if (!$ln) {
 				printf "|%-${max_size_name}s", $name;
-				printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig};
-				printf "|%-${max_size_description}s", $data{$name}->{description};
-				$first = 0;
+				printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``";
+			} elsif ($ln == 2) {
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", $data{$name}->{description};
 			} else {
-				matrix_lines(1, 0);
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", "";
+			}
+
+			printf "|%-${status_size}s|\n", $line;
 
+			$ln++;
+		}
+
+		# Ensure that Kconfig and description will be printed
+		while ($ln < 2) {
+			if (!$ln) {
+				printf "|%-${max_size_name}s", $name;
+				printf "|%-${desc_size}s``", $data{$name}->{kconfig} . "``";
+			} elsif ($ln == 2) {
 				printf "|%-${max_size_name}s", "";
-				printf "|%-${max_size_kconfig}s", "";
-				printf "|%-${max_size_description}s", "";
+				printf "|%-${desc_size}s", $data{$name}->{description};
+			} else {
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", "";
 			}
-			printf "|%-${max_size_arch}s", $arch;
-			printf "|%-${max_size_status}s|\n", $arch_table{$arch};
+
+			printf "|%-${status_size}s|\n", "";
+
+			$ln++;
 		}
-		matrix_lines(0, 0);
+
+		matrix_lines($desc_size, $status_size, 0);
 	}
 }
 
Signature · 1 line
2.28.0
#10 lore raw

PATCH v3 1/1 scripts: get_feat.pl: make complete table more coincise

Currently, there are too many white spaces at the tables, and the information is very sparsed on it.

Make the format a lot more compact.

---

- v3: cleanup the logic that ensures a minimal number of lines;
- v2: cleanup the matrix_lines function to remove a now unused parameter.

 scripts/get_feat.pl | 105 ++++++++++++++++++++++++++++----------------
 1 file changed, 68 insertions(+), 37 deletions(-)
scripts/get_feat.pl +68 -37
index 81d1b78d65c9..10bf23fbc9c5 100755
@@ -325,10 +325,10 @@ sub output_feature {
 # Output all features for all architectures
 #
 
-sub matrix_lines($$) {
-	my $partial = shift;
+sub matrix_lines($$$) {
+	my $desc_size = shift;
+	my $status_size = shift;
 	my $header = shift;
-	my $split;
 	my $fill;
 	my $ln_marker;
 
@@ -338,24 +338,14 @@ sub matrix_lines($$) {
 		$ln_marker = "-";
 	}
 
-	if ($partial) {
-		$split = "|";
-		$fill = " ";
-	} else {
-		$split = "+";
-		$fill = $ln_marker;
-	}
+	$fill = $ln_marker;
 
-	print $split;
+	print "+";
 	print $fill x $max_size_name;
-	print $split;
-	print $fill x $max_size_kconfig;
-	print $split;
-	print $fill x $max_size_description;
 	print "+";
-	print $ln_marker x $max_size_arch;
+	print $fill x $desc_size;
 	print "+";
-	print $ln_marker x $max_size_status;
+	print $ln_marker x $status_size;
 	print "+\n";
 }
 
@@ -366,6 +356,14 @@ sub output_matrix {
 	print "$title\n";
 	print "=" x length($title) . "\n\n";
 
+	my $desc_title = "$h_kconfig / $h_description";
+
+	my $desc_size = $max_size_kconfig + 4;
+	$desc_size = $max_size_description if ($max_size_description > $desc_size);
+	$desc_size = length($desc_title) if (length($desc_title) > $desc_size);
+
+	my $status_size = 60;
+
 	my $cur_subsys = "";
 	foreach my $name (sort {
 				($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +381,69 @@ sub output_matrix {
 			print "$title\n";
 			print "=" x length($title) . "\n\n";
 
-			matrix_lines(0, 0);
+
+			matrix_lines($desc_size, $status_size, 0);
+
 			printf "|%-${max_size_name}s", $h_name;
-			printf "|%-${max_size_kconfig}s", $h_kconfig;
-			printf "|%-${max_size_description}s", $h_description;
+			printf "|%-${desc_size}s", $desc_title;
 
-			printf "|%-${max_size_arch}s", $h_arch;
-			printf "|%-${max_size_status}s|\n", $h_status;
-
-			matrix_lines(0, 1);
+			printf "|%-${status_size}s|\n", "Status per architecture";
+			matrix_lines($desc_size, $status_size, 1);
 		}
 
 		my %arch_table = %{$data{$name}->{table}};
-		my $first = 1;
-		foreach my $arch (sort keys %arch_table) {
-			if ($first) {
+		my $cur_status = "";
+
+		my @lines;
+		my $line = "";
+		foreach my $arch (sort {
+					($arch_table{$a} cmp $arch_table{$b}) or
+					("\L$a" cmp "\L$b")
+				       } keys %arch_table) {
+
+			my $status = $arch_table{$arch};
+
+			if ($status eq "---") {
+				$status = "Not compatible";
+			}
+
+			if ($status ne $cur_status) {
+				if ($line ne "") {
+					push @lines, $line;
+					$line = "";
+				}
+				$line = "- **" . $status . "**: " . $arch;
+			} elsif (length($line) + length ($arch) + 2 < $status_size) {
+				$line .= ", " . $arch;
+			} else {
+				push @lines, $line;
+				$line = "  " . $arch;
+			}
+			$cur_status = $status;
+		}
+		push @lines, $line if ($line ne "");
+
+		# Ensure that description will be printed
+		push @lines, "" while (scalar(@lines) < 2);
+
+		my $ln = 0;
+		for my $line(@lines) {
+			if (!$ln) {
 				printf "|%-${max_size_name}s", $name;
-				printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig};
-				printf "|%-${max_size_description}s", $data{$name}->{description};
-				$first = 0;
+				printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``";
+			} elsif ($ln == 2) {
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", $data{$name}->{description};
 			} else {
-				matrix_lines(1, 0);
-
 				printf "|%-${max_size_name}s", "";
-				printf "|%-${max_size_kconfig}s", "";
-				printf "|%-${max_size_description}s", "";
+				printf "|%-${desc_size}s", "";
 			}
-			printf "|%-${max_size_arch}s", $arch;
-			printf "|%-${max_size_status}s|\n", $arch_table{$arch};
+
+			printf "|%-${status_size}s|\n", $line;
+
+			$ln++;
 		}
-		matrix_lines(0, 0);
+		matrix_lines($desc_size, $status_size, 0);
 	}
 }
 
Signature · 1 line
2.28.0
#11 lore raw

Re: [PATCH v3] scripts: get_feat.pl: make complete table more coincise

Em Fri, 4 Dec 2020 10:35:44 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:

Quoted 7 lines

Currently, there are too many white spaces at the tables, and the information is very sparsed on it.

Make the format a lot more compact.

...

Review

Quoted 6 lines
(quoted diff) +6 -0
+		my @lines;
+		my $line = "";
+		foreach my $arch (sort {
+					($arch_table{$a} cmp $arch_table{$b}) or
+					("\L$a" cmp "\L$b")
+				       } keys %arch_table) {

Actually, I have one doubt myself with the above sort.

Right now, it places things on this order:

	Not Compatible: ...
	TODO: ...
	ok: ...

I'm wondering if it would it be better to place them at the reverse order, e. g.:

	ok: ...
	TODO: ...
	Not Compatible: ...

In other words, to output it like:

+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|Feature              |Kconfig / Description                                                    |Status per architecture                                     |
+=====================+=========================================================================+============================================================+
|batch-unmap-tlb-flush|``ARCH_WANT_BATCHED_UNMAP_TLB_FLUSH``                                    |- **ok**: x86                                               |
|                     |                                                                         |- **TODO**: alpha, arc, arm, arm64, csky, hexagon, ia64     |
|                     |arch supports deferral of TLB flush until multiple pages are unmapped    |  mips, nds32, parisc, powerpc, riscv, s390, sh, sparc      |
|                     |                                                                         |  xtensa                                                    |
|                     |                                                                         |- **Not compatible**: c6x, h8300, m68k, microblaze, nios2   |
|                     |                                                                         |  openrisc, um                                              |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|ELF-ASLR             |``ARCH_HAS_ELF_RANDOMIZE``                                               |- **ok**: arm, arm64, mips, parisc, powerpc, s390, x86      |
|                     |                                                                         |- **TODO**: alpha, arc, c6x, csky, h8300, hexagon, ia64     |
|                     |arch randomizes the stack, heap and binary images of ELF binaries        |  m68k, microblaze, nds32, nios2, openrisc, riscv, sh       |
|                     |                                                                         |  sparc, um, xtensa                                         |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|huge-vmap            |``HAVE_ARCH_HUGE_VMAP``                                                  |- **ok**: arm64, powerpc, x86                               |
|                     |                                                                         |- **TODO**: alpha, arc, arm, c6x, csky, h8300, hexagon      |
|                     |arch supports the ioremap_pud_enabled() and ioremap_pmd_enabled() VM APIs|  ia64, m68k, microblaze, mips, nds32, nios2, openrisc      |
|                     |                                                                         |  parisc, riscv, s390, sh, sparc, um, xtensa                |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|ioremap_prot         |``HAVE_IOREMAP_PROT``                                                    |- **ok**: arc, mips, powerpc, s390, sh, x86                 |
|                     |                                                                         |- **TODO**: alpha, arm, arm64, c6x, csky, h8300, hexagon    |
|                     |arch has ioremap_prot()                                                  |  ia64, m68k, microblaze, nds32, nios2, openrisc, parisc    |
|                     |                                                                         |  riscv, sparc, um, xtensa                                  |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|PG_uncached          |``ARCH_USES_PG_UNCACHED``                                                |- **ok**: ia64, x86                                         |
|                     |                                                                         |- **TODO**: alpha, arc, arm, arm64, c6x, csky, h8300        |
|                     |arch supports the PG_uncached page flag                                  |  hexagon, m68k, microblaze, mips, nds32, nios2, openrisc   |
|                     |                                                                         |  parisc, powerpc, riscv, s390, sh, sparc, um, xtensa       |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|pte_special          |``ARCH_HAS_PTE_SPECIAL``                                                 |- **ok**: arc, arm, arm64, mips, powerpc, riscv, s390, sh   |
|                     |                                                                         |  sparc, x86                                                |
|                     |arch supports the pte_special()/pte_mkspecial() VM APIs                  |- **TODO**: alpha, c6x, csky, h8300, hexagon, ia64, m68k    |
|                     |                                                                         |  microblaze, nds32, nios2, openrisc, parisc, um, xtensa    |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+
|THP                  |``HAVE_ARCH_TRANSPARENT_HUGEPAGE``                                       |- **ok**: arc, arm, arm64, mips, powerpc, s390, sparc, x86  |
|                     |                                                                         |- **TODO**: alpha, ia64, nds32, parisc, riscv               |
|                     |arch supports transparent hugepages                                      |- **Not compatible**: c6x, csky, h8300, hexagon, m68k       |
|                     |                                                                         |  microblaze, nios2, openrisc, sh, um, xtensa               |
+---------------------+-------------------------------------------------------------------------+------------------------------------------------------------+

Changing the order is one line patch (see enclosed).

If you think that reverting the order looks better, feel free to apply the enclosed patch, or fold it with the previous one.

Thanks,
Mauro

[PATCH] script: get_feat: change the group by order

Right now, arch compatibility is grouped by status at the alphabetical order from A to Z, and then from a to z, e. g:.

	---
	TODO
	ok

Revert the order, in order to print first the OK results, then TODO, and, finally, the not compatible ones.

scripts/get_feat.pl +1 -1
index 10bf23fbc9c5..3f73c8534059 100755
@@ -397,7 +397,7 @@ sub output_matrix {
 		my @lines;
 		my $line = "";
 		foreach my $arch (sort {
-					($arch_table{$a} cmp $arch_table{$b}) or
+					($arch_table{$b} cmp $arch_table{$a}) or
 					("\L$a" cmp "\L$b")
 				       } keys %arch_table) {
 
#12 lore raw

v4 cover improve get_feat.pl output when all features are displayed

In reply to Jonathan Corbet

Jon,

As requested, those patches improve the output of the script, when all features are displayed.

The first patch was already posted as-is at v3.

Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.

Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).

While not implemented, it shold be trivial to allow controlling the number of columns via command line (with a 2 line patch).

I ended dropping such control basically because I was too lazy to add the helper for the two new command line parameters ;-) (and because it probably doesn't matter much sense for the user to control it - I guess).

Mauro Carvalho Chehab (3):
scripts: get_feat.pl: make complete table more coincise
scripts: get_feat.pl: change the group by order
scripts: get_feat.pl: reduce table width for all features output

 scripts/get_feat.pl | 160 ++++++++++++++++++++++++++++++++------------
 1 file changed, 119 insertions(+), 41 deletions(-)
Signature · 1 line
2.28.0
#13 lore raw

PATCH v4 1/3 scripts: get_feat.pl: make complete table more coincise

Currently, there are too many white spaces at the tables, and the information is very sparsed on it.

Make the format a lot more compact.

---
 scripts/get_feat.pl | 105 ++++++++++++++++++++++++++++----------------
 1 file changed, 68 insertions(+), 37 deletions(-)
scripts/get_feat.pl +68 -37
index 81d1b78d65c9..10bf23fbc9c5 100755
@@ -325,10 +325,10 @@ sub output_feature {
 # Output all features for all architectures
 #
 
-sub matrix_lines($$) {
-	my $partial = shift;
+sub matrix_lines($$$) {
+	my $desc_size = shift;
+	my $status_size = shift;
 	my $header = shift;
-	my $split;
 	my $fill;
 	my $ln_marker;
 
@@ -338,24 +338,14 @@ sub matrix_lines($$) {
 		$ln_marker = "-";
 	}
 
-	if ($partial) {
-		$split = "|";
-		$fill = " ";
-	} else {
-		$split = "+";
-		$fill = $ln_marker;
-	}
+	$fill = $ln_marker;
 
-	print $split;
+	print "+";
 	print $fill x $max_size_name;
-	print $split;
-	print $fill x $max_size_kconfig;
-	print $split;
-	print $fill x $max_size_description;
 	print "+";
-	print $ln_marker x $max_size_arch;
+	print $fill x $desc_size;
 	print "+";
-	print $ln_marker x $max_size_status;
+	print $ln_marker x $status_size;
 	print "+\n";
 }
 
@@ -366,6 +356,14 @@ sub output_matrix {
 	print "$title\n";
 	print "=" x length($title) . "\n\n";
 
+	my $desc_title = "$h_kconfig / $h_description";
+
+	my $desc_size = $max_size_kconfig + 4;
+	$desc_size = $max_size_description if ($max_size_description > $desc_size);
+	$desc_size = length($desc_title) if (length($desc_title) > $desc_size);
+
+	my $status_size = 60;
+
 	my $cur_subsys = "";
 	foreach my $name (sort {
 				($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
@@ -383,36 +381,69 @@ sub output_matrix {
 			print "$title\n";
 			print "=" x length($title) . "\n\n";
 
-			matrix_lines(0, 0);
+
+			matrix_lines($desc_size, $status_size, 0);
+
 			printf "|%-${max_size_name}s", $h_name;
-			printf "|%-${max_size_kconfig}s", $h_kconfig;
-			printf "|%-${max_size_description}s", $h_description;
+			printf "|%-${desc_size}s", $desc_title;
 
-			printf "|%-${max_size_arch}s", $h_arch;
-			printf "|%-${max_size_status}s|\n", $h_status;
-
-			matrix_lines(0, 1);
+			printf "|%-${status_size}s|\n", "Status per architecture";
+			matrix_lines($desc_size, $status_size, 1);
 		}
 
 		my %arch_table = %{$data{$name}->{table}};
-		my $first = 1;
-		foreach my $arch (sort keys %arch_table) {
-			if ($first) {
+		my $cur_status = "";
+
+		my @lines;
+		my $line = "";
+		foreach my $arch (sort {
+					($arch_table{$a} cmp $arch_table{$b}) or
+					("\L$a" cmp "\L$b")
+				       } keys %arch_table) {
+
+			my $status = $arch_table{$arch};
+
+			if ($status eq "---") {
+				$status = "Not compatible";
+			}
+
+			if ($status ne $cur_status) {
+				if ($line ne "") {
+					push @lines, $line;
+					$line = "";
+				}
+				$line = "- **" . $status . "**: " . $arch;
+			} elsif (length($line) + length ($arch) + 2 < $status_size) {
+				$line .= ", " . $arch;
+			} else {
+				push @lines, $line;
+				$line = "  " . $arch;
+			}
+			$cur_status = $status;
+		}
+		push @lines, $line if ($line ne "");
+
+		# Ensure that description will be printed
+		push @lines, "" while (scalar(@lines) < 2);
+
+		my $ln = 0;
+		for my $line(@lines) {
+			if (!$ln) {
 				printf "|%-${max_size_name}s", $name;
-				printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig};
-				printf "|%-${max_size_description}s", $data{$name}->{description};
-				$first = 0;
+				printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``";
+			} elsif ($ln == 2) {
+				printf "|%-${max_size_name}s", "";
+				printf "|%-${desc_size}s", $data{$name}->{description};
 			} else {
-				matrix_lines(1, 0);
-
 				printf "|%-${max_size_name}s", "";
-				printf "|%-${max_size_kconfig}s", "";
-				printf "|%-${max_size_description}s", "";
+				printf "|%-${desc_size}s", "";
 			}
-			printf "|%-${max_size_arch}s", $arch;
-			printf "|%-${max_size_status}s|\n", $arch_table{$arch};
+
+			printf "|%-${status_size}s|\n", $line;
+
+			$ln++;
 		}
-		matrix_lines(0, 0);
+		matrix_lines($desc_size, $status_size, 0);
 	}
 }
 
Signature · 1 line
2.28.0
#14 lore raw

PATCH v4 2/3 scripts: get_feat.pl: change the group by order

In reply to Mauro Carvalho Chehab

Right now, arch compatibility is grouped by status at the alphabetical order from A to Z, and then from a to z, e. g:.

	---
	TODO
	ok

Revert the order, in order to print first the OK results, then TODO, and, finally, the not compatible ones.

---
 scripts/get_feat.pl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/get_feat.pl +1 -1
index 10bf23fbc9c5..3f73c8534059 100755
@@ -397,7 +397,7 @@ sub output_matrix {
 		my @lines;
 		my $line = "";
 		foreach my $arch (sort {
-					($arch_table{$a} cmp $arch_table{$b}) or
+					($arch_table{$b} cmp $arch_table{$a}) or
 					("\L$a" cmp "\L$b")
 				       } keys %arch_table) {
 
Signature · 1 line
2.28.0
#15 lore raw

PATCH v4 3/3 scripts: get_feat.pl: reduce table width for all features output

In reply to Mauro Carvalho Chehab

Auto-adjust the table columns width to better fit under terminals, by breaking the description on multiple lines and auto-estimating the minimal size for the per-architecture status.

---
 scripts/get_feat.pl | 71 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 59 insertions(+), 12 deletions(-)
scripts/get_feat.pl +59 -12
index 3f73c8534059..457712355676 100755
@@ -19,6 +19,11 @@ $basename =~ s,/[^/]+$,/,;
 
 my $prefix=$basename . "../Documentation/features";
 
+# Used only at for full features output. The script will auto-adjust
+# such values for the minimal possible values
+my $status_size = 1;
+my $description_size = 1;
+
 GetOptions(
 	"debug|d+" => \$debug,
 	"dir=s" => \$prefix,
@@ -77,7 +82,10 @@ my $max_size_kconfig = length($h_kconfig);
 my $max_size_description = length($h_description);
 my $max_size_subsys = length($h_subsys);
 my $max_size_status = length($h_status);
-my $max_size_arch = length($h_arch);
+
+my $max_size_arch = 0;
+my $max_size_arch_with_header;
+my $max_description_word = 0;
 
 sub parse_feat {
 	my $file = $File::Find::name;
@@ -127,6 +135,13 @@ sub parse_feat {
 			if (length($description) > $max_size_description) {
 				$max_size_description = length($description);
 			}
+
+			foreach my $word (split /\s+/, $description) {
+				if (length($word) > $max_description_word) {
+					$max_description_word = length($word);
+				}
+			}
+
 			next;
 		}
 		next if (m/^\\s*$/);
@@ -180,6 +195,8 @@ sub parse_feat {
 	$data{$name}->{description} = $description;
 	$data{$name}->{comments} = $comments;
 	$data{$name}->{table} = \%arch_table;
+
+	$max_size_arch_with_header = $max_size_arch + length($h_arch);
 }
 
 #
@@ -296,7 +313,7 @@ sub output_feature {
 		print "$com\n\n";
 	}
 
-	print "=" x $max_size_arch;
+	print "=" x $max_size_arch_with_header;
 	print "  ";
 	print "=" x $max_size_status;
 	print "\n";
@@ -304,7 +321,7 @@ sub output_feature {
 	printf "%-${max_size_arch}s  ", $h_arch;
 	printf "%-${max_size_status}s", $h_status . "\n";
 
-	print "=" x $max_size_arch;
+	print "=" x $max_size_arch_with_header;
 	print "  ";
 	print "=" x $max_size_status;
 	print "\n";
@@ -315,7 +332,7 @@ sub output_feature {
 		printf "%-${max_size_status}s\n", $arch_table{$arch};
 	}
 
-	print "=" x $max_size_arch;
+	print "=" x $max_size_arch_with_header;
 	print "  ";
 	print "=" x $max_size_status;
 	print "\n";
@@ -351,6 +368,7 @@ sub matrix_lines($$$) {
 
 sub output_matrix {
 	my $title = "Feature status on all architectures";
+	my $notcompat = "Not compatible";
 
 	print "=" x length($title) . "\n";
 	print "$title\n";
@@ -359,10 +377,21 @@ sub output_matrix {
 	my $desc_title = "$h_kconfig / $h_description";
 
 	my $desc_size = $max_size_kconfig + 4;
-	$desc_size = $max_size_description if ($max_size_description > $desc_size);
+	if (!$description_size) {
+		$desc_size = $max_size_description if ($max_size_description > $desc_size);
+	} else {
+		$desc_size = $description_size if ($description_size > $desc_size);
+	}
+	$desc_size = $max_description_word if ($max_description_word > $desc_size);
+
 	$desc_size = length($desc_title) if (length($desc_title) > $desc_size);
 
-	my $status_size = 60;
+	$max_size_status = length($notcompat) if (length($notcompat) > $max_size_status);
+
+	# Ensure that the status will fit
+	my $min_status_size = $max_size_status + $max_size_arch + 6;
+	$status_size = $min_status_size if ($status_size < $min_status_size);
+
 
 	my $cur_subsys = "";
 	foreach my $name (sort {
@@ -394,7 +423,7 @@ sub output_matrix {
 		my %arch_table = %{$data{$name}->{table}};
 		my $cur_status = "";
 
-		my @lines;
+		my (@lines, @descs);
 		my $line = "";
 		foreach my $arch (sort {
 					($arch_table{$b} cmp $arch_table{$a}) or
@@ -404,7 +433,7 @@ sub output_matrix {
 			my $status = $arch_table{$arch};
 
 			if ($status eq "---") {
-				$status = "Not compatible";
+				$status = $notcompat;
 			}
 
 			if ($status ne $cur_status) {
@@ -423,17 +452,35 @@ sub output_matrix {
 		}
 		push @lines, $line if ($line ne "");
 
-		# Ensure that description will be printed
-		push @lines, "" while (scalar(@lines) < 2);
+		my $description = $data{$name}->{description};
+		while (length($description) > $desc_size) {
+			my $d = substr $description, 0, $desc_size;
+
+			# Ensure that it will end on a space
+			# if it can't, it means that the size is too small
+			# Instead of aborting it, let's print what we have
+			if (!($d =~ s/^(.*)\s+.*/$1/)) {
+				$d = substr $d, 0, -1;
+				push @descs, "$d\\";
+				$description =~ s/^\Q$d\E//;
+			} else {
+				push @descs, $d;
+				$description =~ s/^\Q$d\E\s+//;
+			}
+		}
+		push @descs, $description;
+
+		# Ensure that the full description will be printed
+		push @lines, "" while (scalar(@lines) < 2 + scalar(@descs));
 
 		my $ln = 0;
 		for my $line(@lines) {
 			if (!$ln) {
 				printf "|%-${max_size_name}s", $name;
 				printf "|%-${desc_size}s", "``" . $data{$name}->{kconfig} . "``";
-			} elsif ($ln == 2) {
+			} elsif ($ln >= 2 && scalar(@descs)) {
 				printf "|%-${max_size_name}s", "";
-				printf "|%-${desc_size}s", $data{$name}->{description};
+				printf "|%-${desc_size}s", shift @descs;
 			} else {
 				printf "|%-${max_size_name}s", "";
 				printf "|%-${desc_size}s", "";
Signature · 1 line
2.28.0
maintainer
#16 lore raw

Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed

In reply to Mauro Carvalho Chehab
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…

As requested, those patches improve the output of the script, when all features are displayed.

The first patch was already posted as-is at v3.

Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.

Quoted 6 lines

Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).

OK, this is much improved, thanks; applied.

The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)

Thanks,

jon

#17 lore raw

Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed

Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 13 lines
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…

As requested, those patches improve the output of the script, when all features are displayed.

The first patch was already posted as-is at v3.

Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.

Quoted 8 lines
Quoted 6 lines

Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).

OK, this is much improved, thanks; applied.

Anytime.

Quoted 3 lines

The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)

I actually prefer myself valign=center on tables ;-)

In any case, a change like that should be simple to do.

either adjust:

Documentation/sphinx-static/theme_overrides.css

to change it globally for all tables or create a "table_valign_top" CSS class on it, changing the script to add:

.. cssclass:: table_valign_top

Before each table.

Thanks,
Mauro

#18 lore raw

Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed

Em Sat, 5 Dec 2020 17:03:50 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:

Quoted 37 lines

Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 13 lines
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…

As requested, those patches improve the output of the script, when all features are displayed.

The first patch was already posted as-is at v3.

Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.

Quoted 8 lines
Quoted 6 lines

Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).

OK, this is much improved, thanks; applied.

Anytime.

Quoted 3 lines

The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)

I actually prefer myself valign=center on tables ;-)

In any case, a change like that should be simple to do.

either adjust:

Quoted 8 lines

Documentation/sphinx-static/theme_overrides.css

to change it globally for all tables or create a "table_valign_top" CSS class on it, changing the script to add:

.. cssclass:: table_valign_top

Before each table.

Btw, if you want to play with changing the table alignment, the enclosed patch changes the alignment to use valign=top for all tables (and not only for the feature ones).

Don't forget to remove the old theme before testing the patch with:

	$ rm $(find Documentation/output/ -name theme_overrides.css)

As sphinx (at least version 2.4.4) only writes it if the file doesn't exist.

Thanks,
Mauro

[PATCH] docs: use top-alignment for table cells

Change the table's default in order to align cells on the top, overriding the defaults found on Read the Docs Sphinx Theme.

Documentation/sphinx-static/theme_overrides.css +5 -0
index 459ec5b29d68..e850859e35a0 100644
@@ -42,6 +42,11 @@ p {
 	font-size: 100%;
 }
 
+/* use vertical alignment on tables */
+.rst-content table.docutils td, .rst-content table.field-list td, .wy-table td {
+    vertical-align: top;
+}
+
 /* Interim: Code-blocks with line nos - lines and line numbers don't line up.
  * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
  */
#19 lore raw

Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed

Em Mon, 7 Dec 2020 10:33:40 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:

Quoted 53 lines

Em Sat, 5 Dec 2020 17:03:50 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:

Quoted 37 lines

Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <[email protected]> escreveu:

Quoted 13 lines
Quoted 10 lines · On Fri, 4 Dec 2020 16:32:27 +0100 Mauro Carvalho Chehab…

As requested, those patches improve the output of the script, when all features are displayed.

The first patch was already posted as-is at v3.

Patch 2 is optional. IMO, it makes more sense for the admin guide to show the architectures where the features are OK, then TODO, and finally the ones that are incompatible with the features. I already sent it together with a comment.

Quoted 8 lines
Quoted 6 lines

Patch 3 is new: it tries to reduce the width of the table, in order for it to better fit on a terminal. With the patch, the number of columns were reduced, in order to better fit at console output. Before the patch, the output takes 281 lines with 158 columns (total size: 38.9 kB). After the patch, displaying all features require 439 lines and 92 columns (total size: 37.6 kB).

OK, this is much improved, thanks; applied.

Anytime.

Quoted 3 lines

The one last thing I would do is stick "valign=top" on all the table entries, but we can leave the shed a different color for now :)

I actually prefer myself valign=center on tables ;-)

In any case, a change like that should be simple to do.

either adjust:

Quoted 8 lines

Documentation/sphinx-static/theme_overrides.css

to change it globally for all tables or create a "table_valign_top" CSS class on it, changing the script to add:

.. cssclass:: table_valign_top

Before each table.

Btw, if you want to play with changing the table alignment, the enclosed patch changes the alignment to use valign=top for all tables (and not only for the feature ones).

Quoted 7 lines

Don't forget to remove the old theme before testing the patch with:

	$ rm $(find Documentation/output/ -name theme_overrides.css)

As sphinx (at least version 2.4.4) only writes it if the file doesn't exist.

Btw, if you want to vertically align just some tables - like the ones produced by get_feat.pl, the enclosed patch should do the job.

-

PS.: It seems worth mentioning here, as others may find issues when trying to customize the Kernel-specific CSS styles.

It took me a while to find a way for the style to be properly applied, due to CSS Specificity[1].

[1] I don't usually deal with CSS style sheets :-) So, had to do some research and lots of tests.

Those are two useful references about that:
https://stackoverflow.com/questions/12258596/class-overrule-when-two-classes-assigned-to-one-div
https://www.smashingmagazine.com/2007/07/css-specificity-things-you-should-know/

The thing is that the tables (tested with Sphinx 2.4.4) are created with multiple classes:

<table class="top-aligned docutils align-default">

As the user-specified class (top-aligned) is the first one (instead of the last one), it has less precedence than "docutils" or "align-default" classes.

So, if one specifies at the CSS file just:

	.top-aligned {
		vertical-align: top;
		color: red;
	}

The table color will change to red as expected, but the vertical-align will be overridden by the other classes.

So, we need to place all classes there, in order to increase the CSS Specificity:

	table.top-aligned.docutils.align-default td {
		vertical-align: top;
	}

Thanks,
Mauro

[PATCH] scripts: get_feat.pl: align tables vertically on top

In order to make the full features tables, align
them on the top.

Documentation/sphinx-static/theme_overrides.css +5 -0
index 459ec5b29d68..7ccf69d005fc 100644
@@ -42,6 +42,11 @@ p {
 	font-size: 100%;
 }
 
+/* use vertical alignment on tables */
+table.top-aligned.docutils.align-default td {
+	vertical-align: top;
+}
+
 /* Interim: Code-blocks with line nos - lines and line numbers don't line up.
  * see: https://github.com/rtfd/sphinx_rtd_theme/issues/419
  */
scripts/get_feat.pl +1 -0
index 457712355676..f5725803063e 100755
@@ -410,6 +410,7 @@ sub output_matrix {
 			print "$title\n";
 			print "=" x length($title) . "\n\n";
 
+			print ".. cssclass:: top-aligned\n\n";
 
 			matrix_lines($desc_size, $status_size, 0);