* [PATCH 0/6] Add documentation for Documentation/features at the built docs
@ 2020-11-30 15:36 Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 1/6] scripts: get_feat.pl: add a script to handle Documentation/features Mauro Carvalho Chehab
` (6 more replies)
0 siblings, 7 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Daniel W. S. Almeida, H. Peter Anvin, James E.J. Bottomley,
Jonathan Neuschäfer, Albert Ou, Andrew Cooper,
Benjamin Herrenschmidt, Borislav Petkov, Catalin Marinas,
Christian Borntraeger, Fenghua Yu, Greg Kroah-Hartman,
Heiko Carstens, Helge Deller, Ingo Molnar, Jonas Bonn, Kees Cook,
Masami Hiramatsu, Michael Ellerman, Palmer Dabbelt,
Paul Mackerras, Paul Walmsley, Rich Felker, Stafford Horne,
Stefan Kristiansson, Thomas Bogendoerfer, Thomas Gleixner,
Tony Luck, Vasily Gorbik, Will Deacon, Yoshinori Sato,
linux-arm-kernel, linux-ia64, linux-mips, linux-parisc,
linux-riscv, linux-s390, linux-sh, linuxppc-dev, openrisc, x86
Hi Jon,
This series got already submitted last year:
https://lore.kernel.org/lkml/cover.1561222784.git.mchehab+samsung@kernel.org/
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
--
2.28.0
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 1/6] scripts: get_feat.pl: add a script to handle Documentation/features
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
@ 2020-11-30 15:36 ` Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 2/6] scripts: get_feat.pl: improve matrix output Mauro Carvalho Chehab
` (5 subsequent siblings)
6 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 474 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 474 insertions(+)
create mode 100755 scripts/get_feat.pl
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
new file mode 100755
index 000000000000..79d83595addd
--- /dev/null
+++ b/scripts/get_feat.pl
@@ -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 <mchehab+samsung@kernel.org>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2019 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
+
+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
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 2/6] scripts: get_feat.pl: improve matrix output
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 1/6] scripts: get_feat.pl: add a script to handle Documentation/features Mauro Carvalho Chehab
@ 2020-11-30 15:36 ` Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 3/6] scripts: get_feat.pl: use its implementation for list-arch.sh Mauro Carvalho Chehab
` (4 subsequent siblings)
6 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 113 +++++++++++++++++++++++++++-----------------
1 file changed, 70 insertions(+), 43 deletions(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 79d83595addd..7b92ebab7ddd 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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;
}
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 3/6] scripts: get_feat.pl: use its implementation for list-arch.sh
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 1/6] scripts: get_feat.pl: add a script to handle Documentation/features Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 2/6] scripts: get_feat.pl: improve matrix output Mauro Carvalho Chehab
@ 2020-11-30 15:36 ` Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 4/6] sphinx: kernel_feat.py: add a script to parse feature files Mauro Carvalho Chehab
` (3 subsequent siblings)
6 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-kernel
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/features/list-arch.sh | 17 +------
scripts/get_feat.pl | 77 ++++++++++++++++++++++++-----
2 files changed, 66 insertions(+), 28 deletions(-)
diff --git a/Documentation/features/list-arch.sh b/Documentation/features/list-arch.sh
index 1ec47c3bb5fa..e73aa35848f0 100755
--- a/Documentation/features/list-arch.sh
+++ b/Documentation/features/list-arch.sh
@@ -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
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 7b92ebab7ddd..81d1b78d65c9 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -6,13 +6,18 @@ use Pod::Usage;
use Getopt::Long;
use File::Find;
use Fcntl ':mode';
+use Cwd 'abs_path';
my $help;
my $man;
my $debug;
my $arch;
my $feat;
-my $prefix="Documentation/features";
+
+my $basename = abs_path($0);
+$basename =~ s,/[^/]+$,/,;
+
+my $prefix=$basename . "../Documentation/features";
GetOptions(
"debug|d+" => \$debug,
@@ -20,17 +25,19 @@ GetOptions(
'help|?' => \$help,
'arch=s' => \$arch,
'feat=s' => \$feat,
+ 'feature=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);
+pod2usage(1) if (scalar @ARGV < 1 || @ARGV > 2);
my ($cmd, $arg) = @ARGV;
-pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate");
+pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate"
+ && $cmd ne "ls" && $cmd ne "list");
require Data::Dumper if ($debug);
@@ -213,7 +220,7 @@ sub output_arch_table {
foreach my $name (sort {
($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
- ($data{$a}->{name} cmp $data{$b}->{name})
+ ("\L$a" cmp "\L$b")
} keys %data) {
next if ($feat && $name ne $feat);
@@ -222,7 +229,7 @@ sub output_arch_table {
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};
+ printf "%-s\n", $data{$name}->{description};
}
print "=" x $max_size_subsys;
@@ -237,6 +244,31 @@ sub output_arch_table {
print "\n";
}
+#
+# list feature(s) for a given architecture
+#
+sub list_arch_features {
+ print "#\n# Kernel feature support matrix of the '$arch' architecture:\n#\n";
+
+ foreach my $name (sort {
+ ($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
+ ("\L$a" cmp "\L$b")
+ } keys %data) {
+ next if ($feat && $name ne $feat);
+
+ my %arch_table = %{$data{$name}->{table}};
+
+ my $status = $arch_table{$arch};
+ $status = " " x ((4 - length($status)) / 2) . $status;
+
+ printf " %${max_size_subsys}s/ ", $data{$name}->{subsys};
+ printf "%-${max_size_name}s: ", $name;
+ printf "%-5s| ", $status;
+ printf "%${max_size_kconfig}s # ", $data{$name}->{kconfig};
+ printf " %s\n", $data{$name}->{description};
+ }
+}
+
#
# Output a feature on all architectures
#
@@ -337,7 +369,7 @@ sub output_matrix {
my $cur_subsys = "";
foreach my $name (sort {
($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
- ($a cmp $b)
+ ("\L$a" cmp "\L$b")
} keys %data) {
if ($cur_subsys ne $data{$name}->{subsys}) {
@@ -400,6 +432,17 @@ if ($cmd eq "current") {
$arch =~s/\s+$//;
}
+if ($cmd eq "ls" or $cmd eq "list") {
+ if (!$arch) {
+ $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/');
+ $arch =~s/\s+$//;
+ }
+
+ list_arch_features;
+
+ exit;
+}
+
if ($cmd ne "validate") {
if ($arch) {
output_arch_table;
@@ -418,18 +461,26 @@ 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>]
+B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>] [--arch=<arch>]
+ [--feature=<feature>|--feat=<feature>] <COMAND> [<ARGUMENT>]
Where <COMMAND> can be:
=over 8
-B<current> - output features for this machine's architecture
+B<current> - output table in ReST compatible ASCII format
+ with features for this machine's architecture
-B<rest> - output features in ReST markup language
+B<rest> - output table(s) in ReST compatible ASCII format
+ with features in ReST markup language. The output
+ is affected by --arch or --feat/--feature flags.
-B<validate> - validate the feature contents
+B<validate> - validate the contents of the files under
+ Documentation/features.
+
+B<ls> or B<list> - list features for this machine's architecture,
+ using an easier to parse format.
+ The output is affected by --arch flag.
=back
@@ -442,9 +493,9 @@ B<validate> - validate the feature contents
Output features for an specific architecture, optionally filtering for
a single specific feature.
-=item B<--feat>
+=item B<--feat> or B<--feature>
-Output features for a single specific architecture.
+Output features for a single specific feature.
=item B<--dir>
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 4/6] sphinx: kernel_feat.py: add a script to parse feature files
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
` (2 preceding siblings ...)
2020-11-30 15:36 ` [PATCH 3/6] scripts: get_feat.pl: use its implementation for list-arch.sh Mauro Carvalho Chehab
@ 2020-11-30 15:36 ` Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 5/6] docs: admin-guide: add a features list Mauro Carvalho Chehab
` (2 subsequent siblings)
6 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Greg Kroah-Hartman, linux-kernel
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/sphinx/kernel_feat.py | 169 ++++++++++++++++++++++++++++
1 file changed, 169 insertions(+)
create mode 100644 Documentation/sphinx/kernel_feat.py
diff --git a/Documentation/sphinx/kernel_feat.py b/Documentation/sphinx/kernel_feat.py
new file mode 100644
index 000000000000..2fee04f1dedd
--- /dev/null
+++ b/Documentation/sphinx/kernel_feat.py
@@ -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 <mchehab+samsung@kernel.org>
+ :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
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 5/6] docs: admin-guide: add a features list
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
` (3 preceding siblings ...)
2020-11-30 15:36 ` [PATCH 4/6] sphinx: kernel_feat.py: add a script to parse feature files Mauro Carvalho Chehab
@ 2020-11-30 15:36 ` Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 6/6] docs: archis: add a per-architecture " Mauro Carvalho Chehab
2020-12-03 22:36 ` [PATCH 0/6] Add documentation for Documentation/features at the built docs Jonathan Corbet
6 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, Daniel W. S. Almeida, Jonathan Corbet,
Jonathan Neuschäfer, Greg Kroah-Hartman, Kees Cook,
Masami Hiramatsu, linux-kernel
Add a feature list matrix at the admin-guide.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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
diff --git a/Documentation/admin-guide/features.rst b/Documentation/admin-guide/features.rst
new file mode 100644
index 000000000000..8c167082a84f
--- /dev/null
+++ b/Documentation/admin-guide/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 4e0c4ae44acd..0245a8655b22 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -19,6 +19,7 @@ etc.
sysctl/index
abi
+ features
This section describes CPU vulnerabilities and their mitigations.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index ed2b43ec7754..26b54386a477 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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*
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH 6/6] docs: archis: add a per-architecture features list
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
` (4 preceding siblings ...)
2020-11-30 15:36 ` [PATCH 5/6] docs: admin-guide: add a features list Mauro Carvalho Chehab
@ 2020-11-30 15:36 ` Mauro Carvalho Chehab
2020-12-03 22:36 ` [PATCH 0/6] Add documentation for Documentation/features at the built docs Jonathan Corbet
6 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-30 15:36 UTC (permalink / raw)
To: Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, H. Peter Anvin, James E.J. Bottomley,
Jonathan Corbet, Albert Ou, Andrew Cooper,
Benjamin Herrenschmidt, Borislav Petkov, Catalin Marinas,
Christian Borntraeger, Fenghua Yu, Heiko Carstens, Helge Deller,
Ingo Molnar, Jonas Bonn, Michael Ellerman, Palmer Dabbelt,
Paul Mackerras, Paul Walmsley, Rich Felker, Stafford Horne,
Stefan Kristiansson, Thomas Bogendoerfer, Thomas Gleixner,
Tony Luck, Vasily Gorbik, Will Deacon, Yoshinori Sato,
linux-arm-kernel, linux-ia64, linux-kernel, linux-mips,
linux-parisc, linux-riscv, linux-s390, linux-sh, linuxppc-dev,
openrisc, x86
Add a feature list matrix for each architecture to their
respective Kernel books.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
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
diff --git a/Documentation/arm/features.rst b/Documentation/arm/features.rst
new file mode 100644
index 000000000000..7414ec03dd15
--- /dev/null
+++ b/Documentation/arm/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features arm
diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst
index 5fc072dd0c5e..a2e9e1bba7b9 100644
--- a/Documentation/arm/index.rst
+++ b/Documentation/arm/index.rst
@@ -23,6 +23,8 @@ ARM Architecture
vlocks
porting
+ features
+
SoC-specific documents
======================
diff --git a/Documentation/arm64/features.rst b/Documentation/arm64/features.rst
new file mode 100644
index 000000000000..dfa4cb3cd3ef
--- /dev/null
+++ b/Documentation/arm64/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features arm64
diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
index 937634c49979..97d65ba12a35 100644
--- a/Documentation/arm64/index.rst
+++ b/Documentation/arm64/index.rst
@@ -24,6 +24,8 @@ ARM64 Architecture
tagged-address-abi
tagged-pointers
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/ia64/features.rst b/Documentation/ia64/features.rst
new file mode 100644
index 000000000000..d7226fdcf5f8
--- /dev/null
+++ b/Documentation/ia64/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features ia64
diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst
index 4bdfe28067ee..761f2154dfa2 100644
--- a/Documentation/ia64/index.rst
+++ b/Documentation/ia64/index.rst
@@ -15,3 +15,5 @@ IA-64 Architecture
irq-redir
mca
serial
+
+ features
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 57719744774c..5888e8a7272f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -160,7 +160,7 @@ implementation.
ia64/index
m68k/index
mips/index
- nios2/nios2
+ nios2/index
openrisc/index
parisc/index
powerpc/index
diff --git a/Documentation/m68k/features.rst b/Documentation/m68k/features.rst
new file mode 100644
index 000000000000..5107a2119472
--- /dev/null
+++ b/Documentation/m68k/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features m68k
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index b89cb6a86d9b..0f890dbb5fe2 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -10,6 +10,8 @@ m68k Architecture
kernel-options
buddha-driver
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/mips/features.rst b/Documentation/mips/features.rst
new file mode 100644
index 000000000000..1973d729b29a
--- /dev/null
+++ b/Documentation/mips/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features mips
diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst
index 35cceea4e8bc..037f85a08fe3 100644
--- a/Documentation/mips/index.rst
+++ b/Documentation/mips/index.rst
@@ -11,6 +11,8 @@ MIPS-specific Documentation
booting
ingenic-tcu
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/nios2/index.rst b/Documentation/nios2/index.rst
new file mode 100644
index 000000000000..4468fe1a1037
--- /dev/null
+++ b/Documentation/nios2/index.rst
@@ -0,0 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Nios II Specific Documentation
+==============================
+
+.. toctree::
+ :maxdepth: 2
+ :numbered:
+
+ nios2
+ features
diff --git a/Documentation/openrisc/features.rst b/Documentation/openrisc/features.rst
new file mode 100644
index 000000000000..3f7c40d219f2
--- /dev/null
+++ b/Documentation/openrisc/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features openrisc
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
index 748b3eea1707..6879f998b87a 100644
--- a/Documentation/openrisc/index.rst
+++ b/Documentation/openrisc/index.rst
@@ -10,6 +10,8 @@ OpenRISC Architecture
openrisc_port
todo
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/parisc/features.rst b/Documentation/parisc/features.rst
new file mode 100644
index 000000000000..501d7c450037
--- /dev/null
+++ b/Documentation/parisc/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features parisc
diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst
index aa3ee0470425..240685751825 100644
--- a/Documentation/parisc/index.rst
+++ b/Documentation/parisc/index.rst
@@ -10,6 +10,8 @@ PA-RISC Architecture
debugging
registers
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/powerpc/features.rst b/Documentation/powerpc/features.rst
new file mode 100644
index 000000000000..aeae73df86b0
--- /dev/null
+++ b/Documentation/powerpc/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features powerpc
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
index 6ec64b0d5257..bf5f1a2bdbdf 100644
--- a/Documentation/powerpc/index.rst
+++ b/Documentation/powerpc/index.rst
@@ -34,6 +34,8 @@ powerpc
vas-api
vcpudispatch_stats
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/riscv/features.rst b/Documentation/riscv/features.rst
new file mode 100644
index 000000000000..c70ef6ac2368
--- /dev/null
+++ b/Documentation/riscv/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features riscv
diff --git a/Documentation/riscv/index.rst b/Documentation/riscv/index.rst
index fa33bffd8992..6e6e39482502 100644
--- a/Documentation/riscv/index.rst
+++ b/Documentation/riscv/index.rst
@@ -9,6 +9,8 @@ RISC-V architecture
pmu
patch-acceptance
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/s390/features.rst b/Documentation/s390/features.rst
new file mode 100644
index 000000000000..57c296a9d8f3
--- /dev/null
+++ b/Documentation/s390/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features s390
diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst
index cf71df5776b4..b10ca9192557 100644
--- a/Documentation/s390/index.rst
+++ b/Documentation/s390/index.rst
@@ -19,6 +19,8 @@ s390 Architecture
text_files
+ features
+
.. only:: subproject and html
Indices
diff --git a/Documentation/sh/features.rst b/Documentation/sh/features.rst
new file mode 100644
index 000000000000..f722af3b6c99
--- /dev/null
+++ b/Documentation/sh/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features sh
diff --git a/Documentation/sh/index.rst b/Documentation/sh/index.rst
index 7b9a79a28167..c64776738cf6 100644
--- a/Documentation/sh/index.rst
+++ b/Documentation/sh/index.rst
@@ -11,6 +11,8 @@ SuperH Interfaces Guide
new-machine
register-banks
+ features
+
Memory Management
=================
diff --git a/Documentation/sparc/features.rst b/Documentation/sparc/features.rst
new file mode 100644
index 000000000000..c0c92468b0fe
--- /dev/null
+++ b/Documentation/sparc/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features sparc
diff --git a/Documentation/sparc/index.rst b/Documentation/sparc/index.rst
index 71cff621f243..ae884224eec2 100644
--- a/Documentation/sparc/index.rst
+++ b/Documentation/sparc/index.rst
@@ -9,3 +9,5 @@ Sparc Architecture
adi
oradax/oracle-dax
+
+ features
diff --git a/Documentation/x86/features.rst b/Documentation/x86/features.rst
new file mode 100644
index 000000000000..b663f15053ce
--- /dev/null
+++ b/Documentation/x86/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features x86
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index b224d12c880b..b4fcb6f258b2 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -33,3 +33,4 @@ x86-specific Documentation
i386/index
x86_64/index
sva
+ features
diff --git a/Documentation/xtensa/features.rst b/Documentation/xtensa/features.rst
new file mode 100644
index 000000000000..6b92c7bfa19d
--- /dev/null
+++ b/Documentation/xtensa/features.rst
@@ -0,0 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. kernel-feat:: $srctree/Documentation/features xtensa
diff --git a/Documentation/xtensa/index.rst b/Documentation/xtensa/index.rst
index 52fa04eb39a3..69952446a9be 100644
--- a/Documentation/xtensa/index.rst
+++ b/Documentation/xtensa/index.rst
@@ -10,3 +10,5 @@ Xtensa Architecture
atomctl
booting
mmu
+
+ features
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH 0/6] Add documentation for Documentation/features at the built docs
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
` (5 preceding siblings ...)
2020-11-30 15:36 ` [PATCH 6/6] docs: archis: add a per-architecture " Mauro Carvalho Chehab
@ 2020-12-03 22:36 ` Jonathan Corbet
2020-12-04 9:17 ` [PATCH] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
6 siblings, 2 replies; 20+ messages in thread
From: Jonathan Corbet @ 2020-12-03 22:36 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Linux Doc Mailing List, linux-kernel, Daniel W. S. Almeida,
H. Peter Anvin, James E.J. Bottomley, Jonathan Neuschäfer,
Albert Ou, Andrew Cooper, Benjamin Herrenschmidt,
Borislav Petkov, Catalin Marinas, Christian Borntraeger,
Fenghua Yu, Greg Kroah-Hartman, Heiko Carstens, Helge Deller,
Ingo Molnar, Jonas Bonn, Kees Cook, Masami Hiramatsu,
Michael Ellerman, Palmer Dabbelt, Paul Mackerras, Paul Walmsley,
Rich Felker, Stafford Horne, Stefan Kristiansson,
Thomas Bogendoerfer, Thomas Gleixner, Tony Luck, Vasily Gorbik,
Will Deacon, Yoshinori Sato, linux-arm-kernel, linux-ia64,
linux-mips, linux-parisc, linux-riscv, linux-s390, linux-sh,
linuxppc-dev, openrisc, x86
On Mon, 30 Nov 2020 16:36:29 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> This series got already submitted last year:
>
> https://lore.kernel.org/lkml/cover.1561222784.git.mchehab+samsung@kernel.org/
>
> 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
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH] scripts: get_feat.pl: make complete table more coincise
2020-12-03 22:36 ` [PATCH 0/6] Add documentation for Documentation/features at the built docs Jonathan Corbet
@ 2020-12-04 9:17 ` Mauro Carvalho Chehab
2020-12-04 9:26 ` [PATCH v2] " Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
1 sibling, 1 reply; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 9:17 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 107 +++++++++++++++++++++++++++++++++-----------
1 file changed, 81 insertions(+), 26 deletions(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 81d1b78d65c9..f3777f6d32bb 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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);
}
}
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v2] scripts: get_feat.pl: make complete table more coincise
2020-12-04 9:17 ` [PATCH] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
@ 2020-12-04 9:26 ` Mauro Carvalho Chehab
2020-12-04 9:35 ` [PATCH v3] " Mauro Carvalho Chehab
0 siblings, 1 reply; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 9:26 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 119 ++++++++++++++++++++++++++++++--------------
1 file changed, 83 insertions(+), 36 deletions(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 81d1b78d65c9..2860abfdcd91 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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);
}
}
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v3] scripts: get_feat.pl: make complete table more coincise
2020-12-04 9:26 ` [PATCH v2] " Mauro Carvalho Chehab
@ 2020-12-04 9:35 ` Mauro Carvalho Chehab
2020-12-04 9:52 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 9:35 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
- 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(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 81d1b78d65c9..10bf23fbc9c5 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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);
}
}
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH v3] scripts: get_feat.pl: make complete table more coincise
2020-12-04 9:35 ` [PATCH v3] " Mauro Carvalho Chehab
@ 2020-12-04 9:52 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 9:52 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List; +Cc: linux-kernel
Em Fri, 4 Dec 2020 10:35:44 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
> 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.
>
> Suggested-by: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
...
> + 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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 10bf23fbc9c5..3f73c8534059 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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) {
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
2020-12-03 22:36 ` [PATCH 0/6] Add documentation for Documentation/features at the built docs Jonathan Corbet
2020-12-04 9:17 ` [PATCH] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
@ 2020-12-04 15:32 ` Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 1/3] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
` (3 more replies)
1 sibling, 4 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 15:32 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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(-)
--
2.28.0
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH v4 1/3] scripts: get_feat.pl: make complete table more coincise
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
@ 2020-12-04 15:32 ` Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 2/3] scripts: get_feat.pl: change the group by order Mauro Carvalho Chehab
` (2 subsequent siblings)
3 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 15:32 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 105 ++++++++++++++++++++++++++++----------------
1 file changed, 68 insertions(+), 37 deletions(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 81d1b78d65c9..10bf23fbc9c5 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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);
}
}
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 2/3] scripts: get_feat.pl: change the group by order
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 1/3] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
@ 2020-12-04 15:32 ` Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 3/3] scripts: get_feat.pl: reduce table width for all features output Mauro Carvalho Chehab
2020-12-04 21:48 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Jonathan Corbet
3 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 15:32 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 10bf23fbc9c5..3f73c8534059 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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) {
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* [PATCH v4 3/3] scripts: get_feat.pl: reduce table width for all features output
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 1/3] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 2/3] scripts: get_feat.pl: change the group by order Mauro Carvalho Chehab
@ 2020-12-04 15:32 ` Mauro Carvalho Chehab
2020-12-04 21:48 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Jonathan Corbet
3 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-04 15:32 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_feat.pl | 71 +++++++++++++++++++++++++++++++++++++--------
1 file changed, 59 insertions(+), 12 deletions(-)
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 3f73c8534059..457712355676 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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", "";
--
2.28.0
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
` (2 preceding siblings ...)
2020-12-04 15:32 ` [PATCH v4 3/3] scripts: get_feat.pl: reduce table width for all features output Mauro Carvalho Chehab
@ 2020-12-04 21:48 ` Jonathan Corbet
2020-12-05 16:03 ` Mauro Carvalho Chehab
3 siblings, 1 reply; 20+ messages in thread
From: Jonathan Corbet @ 2020-12-04 21:48 UTC (permalink / raw)
To: Mauro Carvalho Chehab; +Cc: Linux Doc Mailing List, linux-kernel
On Fri, 4 Dec 2020 16:32:27 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> 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).
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
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
2020-12-04 21:48 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Jonathan Corbet
@ 2020-12-05 16:03 ` Mauro Carvalho Chehab
2020-12-07 9:33 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-05 16:03 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linux Doc Mailing List, linux-kernel
Em Fri, 4 Dec 2020 14:48:43 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Fri, 4 Dec 2020 16:32:27 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > 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).
>
> OK, this is much improved, thanks; applied.
Anytime.
>
> 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
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
2020-12-05 16:03 ` Mauro Carvalho Chehab
@ 2020-12-07 9:33 ` Mauro Carvalho Chehab
2020-12-07 11:34 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-07 9:33 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linux Doc Mailing List, linux-kernel
Em Sat, 5 Dec 2020 17:03:50 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
> Em Fri, 4 Dec 2020 14:48:43 -0700
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
> > On Fri, 4 Dec 2020 16:32:27 +0100
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> >
> > > 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).
> >
> > OK, this is much improved, thanks; applied.
>
> Anytime.
>
> >
> > 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.
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index 459ec5b29d68..e850859e35a0 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -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
*/
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [PATCH v4 0/3] improve get_feat.pl output when all features are displayed
2020-12-07 9:33 ` Mauro Carvalho Chehab
@ 2020-12-07 11:34 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 20+ messages in thread
From: Mauro Carvalho Chehab @ 2020-12-07 11:34 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Linux Doc Mailing List, linux-kernel
Em Mon, 7 Dec 2020 10:33:40 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
> Em Sat, 5 Dec 2020 17:03:50 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:
>
> > Em Fri, 4 Dec 2020 14:48:43 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >
> > > On Fri, 4 Dec 2020 16:32:27 +0100
> > > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > >
> > > > 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).
> > >
> > > OK, this is much improved, thanks; applied.
> >
> > Anytime.
> >
> > >
> > > 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.
>
> 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.
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index 459ec5b29d68..7ccf69d005fc 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -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
*/
diff --git a/scripts/get_feat.pl b/scripts/get_feat.pl
index 457712355676..f5725803063e 100755
--- a/scripts/get_feat.pl
+++ b/scripts/get_feat.pl
@@ -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);
^ permalink raw reply related [flat|nested] 20+ messages in thread
end of thread, other threads:[~2020-12-07 11:35 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-30 15:36 [PATCH 0/6] Add documentation for Documentation/features at the built docs Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 1/6] scripts: get_feat.pl: add a script to handle Documentation/features Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 2/6] scripts: get_feat.pl: improve matrix output Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 3/6] scripts: get_feat.pl: use its implementation for list-arch.sh Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 4/6] sphinx: kernel_feat.py: add a script to parse feature files Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 5/6] docs: admin-guide: add a features list Mauro Carvalho Chehab
2020-11-30 15:36 ` [PATCH 6/6] docs: archis: add a per-architecture " Mauro Carvalho Chehab
2020-12-03 22:36 ` [PATCH 0/6] Add documentation for Documentation/features at the built docs Jonathan Corbet
2020-12-04 9:17 ` [PATCH] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
2020-12-04 9:26 ` [PATCH v2] " Mauro Carvalho Chehab
2020-12-04 9:35 ` [PATCH v3] " Mauro Carvalho Chehab
2020-12-04 9:52 ` Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 1/3] scripts: get_feat.pl: make complete table more coincise Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 2/3] scripts: get_feat.pl: change the group by order Mauro Carvalho Chehab
2020-12-04 15:32 ` [PATCH v4 3/3] scripts: get_feat.pl: reduce table width for all features output Mauro Carvalho Chehab
2020-12-04 21:48 ` [PATCH v4 0/3] improve get_feat.pl output when all features are displayed Jonathan Corbet
2020-12-05 16:03 ` Mauro Carvalho Chehab
2020-12-07 9:33 ` Mauro Carvalho Chehab
2020-12-07 11:34 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).