scripts/get_feat.pl

   1 #!/usr/bin/perl
   2 # SPDX-License-Identifier: GPL-2.0
   3
   4 use strict;
   5 use Pod::Usage;
   6 use Getopt::Long;
   7 use File::Find;
   8 use Fcntl ':mode';
   9
  10 my $help;
  11 my $man;
  12 my $debug;
  13 my $arch;
  14 my $feat;
  15 my $prefix="Documentation/features";
  16
  17 GetOptions(
  18         "debug|d+" => \$debug,
  19         "dir=s" => \$prefix,
  20         'help|?' => \$help,
  21         'arch=s' => \$arch,
  22         'feat=s' => \$feat,
  23         man => \$man
  24 ) or pod2usage(2);
  25
  26 pod2usage(1) if $help;
  27 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
  28
  29 pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
  30
  31 my ($cmd, $arg) = @ARGV;
  32
  33 pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate");
  34
  35 require Data::Dumper if ($debug);
  36
  37 my %data;
  38 my %archs;
  39
  40 #
  41 # Displays an error message, printing file name and line
  42 #
  43 sub parse_error($$$$) {
  44         my ($file, $ln, $msg, $data) = @_;
  45
  46         $data =~ s/\s+$/\n/;
  47
  48         print STDERR "Warning: file $file#$ln:\n\t$msg";
  49
  50         if ($data ne "") {
  51                 print STDERR ". Line\n\t\t$data";
  52         } else {
  53             print STDERR "\n";
  54         }
  55 }
  56
  57 #
  58 # Parse a features file, storing its contents at %data
  59 #
  60
  61 my $h_name = "Feature";
  62 my $h_kconfig = "Kconfig";
  63 my $h_description = "Description";
  64 my $h_subsys = "Subsystem";
  65 my $h_status = "Status";
  66 my $h_arch = "Architecture";
  67
  68 my $max_size_name = length($h_name);
  69 my $max_size_kconfig = length($h_kconfig);
  70 my $max_size_description = length($h_description);
  71 my $max_size_subsys = length($h_subsys);
  72 my $max_size_status = length($h_status);
  73 my $max_size_arch = length($h_arch);
  74
  75 sub parse_feat {
  76         my $file = $File::Find::name;
  77
  78         my $mode = (stat($file))[2];
  79         return if ($mode & S_IFDIR);
  80         return if ($file =~ m,($prefix)/arch-support.txt,);
  81         return if (!($file =~ m,arch-support.txt$,));
  82
  83         my $subsys = "";
  84         $subsys = $2 if ( m,.*($prefix)/([^/]+).*,);
  85
  86         if (length($subsys) > $max_size_subsys) {
  87                 $max_size_subsys = length($subsys);
  88         }
  89
  90         my $name;
  91         my $kconfig;
  92         my $description;
  93         my $comments = "";
  94         my $last_status;
  95         my $ln;
  96         my %arch_table;
  97
  98         print STDERR "Opening $file\n" if ($debug > 1);
  99         open IN, $file;
 100
 101         while(<IN>) {
 102                 $ln++;
 103
 104                 if (m/^\#\s+Feature\s+name:\s*(.*\S)/) {
 105                         $name = $1;
 106                         if (length($name) > $max_size_name) {
 107                                 $max_size_name = length($name);
 108                         }
 109                         next;
 110                 }
 111                 if (m/^\#\s+Kconfig:\s*(.*\S)/) {
 112                         $kconfig = $1;
 113                         if (length($kconfig) > $max_size_kconfig) {
 114                                 $max_size_kconfig = length($kconfig);
 115                         }
 116                         next;
 117                 }
 118                 if (m/^\#\s+description:\s*(.*\S)/) {
 119                         $description = $1;
 120                         if (length($description) > $max_size_description) {
 121                                 $max_size_description = length($description);
 122                         }
 123                         next;
 124                 }
 125                 next if (m/^\\s*$/);
 126                 next if (m/^\s*\-+\s*$/);
 127                 next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/);
 128
 129                 if (m/^\#\s*(.*)/) {
 130                         $comments .= "$1\n";
 131                         next;
 132                 }
 133                 if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) {
 134                         my $a = $1;
 135                         my $status = $2;
 136
 137                         if (length($status) > $max_size_status) {
 138                                 $max_size_status = length($status);
 139                         }
 140                         if (length($a) > $max_size_arch) {
 141                                 $max_size_arch = length($a);
 142                         }
 143
 144                         $status = "---" if ($status =~ m/^\.\.$/);
 145
 146                         $archs{$a} = 1;
 147                         $arch_table{$a} = $status;
 148                         next;
 149                 }
 150
 151                 #Everything else is an error
 152                 parse_error($file, $ln, "line is invalid", $_);
 153         }
 154         close IN;
 155
 156         if (!$name) {
 157                 parse_error($file, $ln, "Feature name not found", "");
 158                 return;
 159         }
 160
 161         parse_error($file, $ln, "Subsystem not found", "") if (!$subsys);
 162         parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig);
 163         parse_error($file, $ln, "Description not found", "") if (!$description);
 164
 165         if (!%arch_table) {
 166                 parse_error($file, $ln, "Architecture table not found", "");
 167                 return;
 168         }
 169
 170         $data{$name}->{where} = $file;
 171         $data{$name}->{subsys} = $subsys;
 172         $data{$name}->{kconfig} = $kconfig;
 173         $data{$name}->{description} = $description;
 174         $data{$name}->{comments} = $comments;
 175         $data{$name}->{table} = \%arch_table;
 176 }
 177
 178 #
 179 # Output feature(s) for a given architecture
 180 #
 181 sub output_arch_table {
 182         my $title = "Feature status on $arch architecture";
 183
 184         print "=" x length($title) . "\n";
 185         print "$title\n";
 186         print "=" x length($title) . "\n\n";
 187
 188         print "=" x $max_size_subsys;
 189         print "  ";
 190         print "=" x $max_size_name;
 191         print "  ";
 192         print "=" x $max_size_kconfig;
 193         print "  ";
 194         print "=" x $max_size_status;
 195         print "  ";
 196         print "=" x $max_size_description;
 197         print "\n";
 198         printf "%-${max_size_subsys}s  ", $h_subsys;
 199         printf "%-${max_size_name}s  ", $h_name;
 200         printf "%-${max_size_kconfig}s  ", $h_kconfig;
 201         printf "%-${max_size_status}s  ", $h_status;
 202         printf "%-${max_size_description}s\n", $h_description;
 203         print "=" x $max_size_subsys;
 204         print "  ";
 205         print "=" x $max_size_name;
 206         print "  ";
 207         print "=" x $max_size_kconfig;
 208         print "  ";
 209         print "=" x $max_size_status;
 210         print "  ";
 211         print "=" x $max_size_description;
 212         print "\n";
 213
 214         foreach my $name (sort {
 215                                 ($data{$a}->{subsys} cmp $data{$b}->{subsys}) ||
 216                                 ($data{$a}->{name} cmp $data{$b}->{name})
 217                                } keys %data) {
 218                 next if ($feat && $name ne $feat);
 219
 220                 my %arch_table = %{$data{$name}->{table}};
 221                 printf "%-${max_size_subsys}s  ", $data{$name}->{subsys};
 222                 printf "%-${max_size_name}s  ", $name;
 223                 printf "%-${max_size_kconfig}s  ", $data{$name}->{kconfig};
 224                 printf "%-${max_size_status}s  ", $arch_table{$arch};
 225                 printf "%-${max_size_description}s\n", $data{$name}->{description};
 226         }
 227
 228         print "=" x $max_size_subsys;
 229         print "  ";
 230         print "=" x $max_size_name;
 231         print "  ";
 232         print "=" x $max_size_kconfig;
 233         print "  ";
 234         print "=" x $max_size_status;
 235         print "  ";
 236         print "=" x $max_size_description;
 237         print "\n";
 238 }
 239
 240 #
 241 # Output a feature on all architectures
 242 #
 243 sub output_feature {
 244         my $title = "Feature $feat";
 245
 246         print "=" x length($title) . "\n";
 247         print "$title\n";
 248         print "=" x length($title) . "\n\n";
 249
 250         print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys});
 251         print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig});
 252
 253         my $desc = $data{$feat}->{description};
 254         $desc =~ s/^([a-z])/\U$1/;
 255         $desc =~ s/\.?\s*//;
 256         print "\n$desc.\n\n";
 257
 258         my $com = $data{$feat}->{comments};
 259         $com =~ s/^\s+//;
 260         $com =~ s/\s+$//;
 261         if ($com) {
 262                 print "Comments\n";
 263                 print "--------\n\n";
 264                 print "$com\n\n";
 265         }
 266
 267         print "=" x $max_size_arch;
 268         print "  ";
 269         print "=" x $max_size_status;
 270         print "\n";
 271
 272         printf "%-${max_size_arch}s  ", $h_arch;
 273         printf "%-${max_size_status}s", $h_status . "\n";
 274
 275         print "=" x $max_size_arch;
 276         print "  ";
 277         print "=" x $max_size_status;
 278         print "\n";
 279
 280         my %arch_table = %{$data{$feat}->{table}};
 281         foreach my $arch (sort keys %arch_table) {
 282                 printf "%-${max_size_arch}s  ", $arch;
 283                 printf "%-${max_size_status}s\n", $arch_table{$arch};
 284         }
 285
 286         print "=" x $max_size_arch;
 287         print "  ";
 288         print "=" x $max_size_status;
 289         print "\n";
 290 }
 291
 292 #
 293 # Output all features for all architectures
 294 #
 295
 296 sub matrix_lines($$) {
 297         my $partial = shift;
 298         my $header = shift;
 299         my $split;
 300         my $fill;
 301         my $ln_marker;
 302
 303         if ($header) {
 304                 $ln_marker = "=";
 305         } else {
 306                 $ln_marker = "-";
 307         }
 308
 309         if ($partial) {
 310                 $split = "|";
 311                 $fill = " ";
 312         } else {
 313                 $split = "+";
 314                 $fill = $ln_marker;
 315         }
 316
 317         print $split;
 318         print $fill x $max_size_name;
 319         print $split;
 320         print $fill x $max_size_kconfig;
 321         print $split;
 322         print $fill x $max_size_description;
 323         print "+";
 324         print $ln_marker x $max_size_arch;
 325         print "+";
 326         print $ln_marker x $max_size_status;
 327         print "+\n";
 328 }
 329
 330 sub output_matrix {
 331         my $title = "Feature status on all architectures";
 332
 333         print "=" x length($title) . "\n";
 334         print "$title\n";
 335         print "=" x length($title) . "\n\n";
 336
 337         my $cur_subsys = "";
 338         foreach my $name (sort {
 339                                 ($data{$a}->{subsys} cmp $data{$b}->{subsys}) or
 340                                 ($a cmp $b)
 341                                } keys %data) {
 342
 343                 if ($cur_subsys ne $data{$name}->{subsys}) {
 344                         if ($cur_subsys ne "") {
 345                                 printf "\n";
 346                         }
 347
 348                         $cur_subsys = $data{$name}->{subsys};
 349
 350                         my $title = "Subsystem: $cur_subsys";
 351                         print "$title\n";
 352                         print "=" x length($title) . "\n\n";
 353
 354                         matrix_lines(0, 0);
 355                         printf "|%-${max_size_name}s", $h_name;
 356                         printf "|%-${max_size_kconfig}s", $h_kconfig;
 357                         printf "|%-${max_size_description}s", $h_description;
 358
 359                         printf "|%-${max_size_arch}s", $h_arch;
 360                         printf "|%-${max_size_status}s|\n", $h_status;
 361
 362                         matrix_lines(0, 1);
 363                 }
 364
 365                 my %arch_table = %{$data{$name}->{table}};
 366                 my $first = 1;
 367                 foreach my $arch (sort keys %arch_table) {
 368                         if ($first) {
 369                                 printf "|%-${max_size_name}s", $name;
 370                                 printf "|%-${max_size_kconfig}s", $data{$name}->{kconfig};
 371                                 printf "|%-${max_size_description}s", $data{$name}->{description};
 372                                 $first = 0;
 373                         } else {
 374                                 matrix_lines(1, 0);
 375
 376                                 printf "|%-${max_size_name}s", "";
 377                                 printf "|%-${max_size_kconfig}s", "";
 378                                 printf "|%-${max_size_description}s", "";
 379                         }
 380                         printf "|%-${max_size_arch}s", $arch;
 381                         printf "|%-${max_size_status}s|\n", $arch_table{$arch};
 382                 }
 383                 matrix_lines(0, 0);
 384         }
 385 }
 386
 387
 388 #
 389 # Parses all feature files located at $prefix dir
 390 #
 391 find({wanted =>\&parse_feat, no_chdir => 1}, $prefix);
 392
 393 print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
 394
 395 #
 396 # Handles the command
 397 #
 398 if ($cmd eq "current") {
 399         $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/');
 400         $arch =~s/\s+$//;
 401 }
 402
 403 if ($cmd ne "validate") {
 404         if ($arch) {
 405                 output_arch_table;
 406         } elsif ($feat) {
 407                 output_feature;
 408         } else {
 409                 output_matrix;
 410         }
 411 }
 412
 413 __END__
 414
 415 =head1 NAME
 416
 417 get_feat.pl - parse the Linux Feature files and produce a ReST book.
 418
 419 =head1 SYNOPSIS
 420
 421 B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>]
 422                [--arch=<arch>] [--feat=<feature>] <COMAND> [<ARGUMENT>]
 423
 424 Where <COMMAND> can be:
 425
 426 =over 8
 427
 428 B<current>               - output features for this machine's architecture
 429
 430 B<rest>                  - output features in ReST markup language
 431
 432 B<validate>              - validate the feature contents
 433
 434 =back
 435
 436 =head1 OPTIONS
 437
 438 =over 8
 439
 440 =item B<--arch>
 441
 442 Output features for an specific architecture, optionally filtering for
 443 a single specific feature.
 444
 445 =item B<--feat>
 446
 447 Output features for a single specific architecture.
 448
 449 =item B<--dir>
 450
 451 Changes the location of the Feature files. By default, it uses
 452 the Documentation/features directory.
 453
 454 =item B<--debug>
 455
 456 Put the script in verbose mode, useful for debugging. Can be called multiple
 457 times, to increase verbosity.
 458
 459 =item B<--help>
 460
 461 Prints a brief help message and exits.
 462
 463 =item B<--man>
 464
 465 Prints the manual page and exits.
 466
 467 =back
 468
 469 =head1 DESCRIPTION
 470
 471 Parse the Linux feature files from Documentation/features (by default),
 472 optionally producing results at ReST format.
 473
 474 It supports output data per architecture, per feature or a
 475 feature x arch matrix.
 476
 477 When used with B<rest> command, it will use either one of the tree formats:
 478
 479 If neither B<--arch> or B<--feature> arguments are used, it will output a
 480 matrix with features per architecture.
 481
 482 If B<--arch> argument is used, it will output the features availability for
 483 a given architecture.
 484
 485 If B<--feat> argument is used, it will output the content of the feature
 486 file using ReStructured Text markup.
 487
 488 =head1 BUGS
 489
 490 Report bugs to Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
 491
 492 =head1 COPYRIGHT
 493
 494 Copyright (c) 2019 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
 495
 496 License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
 497
 498 This is free software: you are free to change and redistribute it.
 499 There is NO WARRANTY, to the extent permitted by law.
 500
 501 =cut