c25ce589dca10 (Finn Behrens 2020-11-23 15:15:33 +0100 1) #!/usr/bin/env perl
ecb351f1c4475 (Mauro Carvalho Chehab 2019-06-20 14:23:10 -0300 2) # SPDX-License-Identifier: GPL-2.0
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 3)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 4) use strict;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 5) use warnings;
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 6) use utf8;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 7) use Pod::Usage;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 8) use Getopt::Long;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 9) use File::Find;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 10) use Fcntl ':mode';
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 11)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 12) my $help = 0;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 13) my $man = 0;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 14) my $debug = 0;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 15) my $enable_lineno = 0;
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 16) my $prefix="Documentation/ABI";
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 17)
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 18) #
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 19) # If true, assumes that the description is formatted with ReST
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 20) #
2fcce37a3d2f2 (Mauro Carvalho Chehab 2020-10-30 08:40:58 +0100 21) my $description_is_rst = 1;
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 22)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 23) GetOptions(
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 24) "debug|d+" => \$debug,
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 25) "enable-lineno" => \$enable_lineno,
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 26) "rst-source!" => \$description_is_rst,
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 27) "dir=s" => \$prefix,
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 28) 'help|?' => \$help,
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 29) man => \$man
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 30) ) or pod2usage(2);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 31)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 32) pod2usage(1) if $help;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 33) pod2usage(-exitstatus => 0, -verbose => 2) if $man;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 34)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 35) pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 36)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 37) my ($cmd, $arg) = @ARGV;
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 38)
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 39) pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate");
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 40) pod2usage(2) if ($cmd eq "search" && !$arg);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 41)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 42) require Data::Dumper if ($debug);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 43)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 44) my %data;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 45) my %symbols;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 46)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 47) #
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 48) # Displays an error message, printing file name and line
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 49) #
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 50) sub parse_error($$$$) {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 51) my ($file, $ln, $msg, $data) = @_;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 52)
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 53) $data =~ s/\s+$/\n/;
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 54)
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 55) print STDERR "Warning: file $file#$ln:\n\t$msg";
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 56)
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 57) if ($data ne "") {
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 58) print STDERR ". Line\n\t\t$data";
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 59) } else {
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 60) print STDERR "\n";
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 61) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 62) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 63)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 64) #
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 65) # Parse an ABI file, storing its contents at %data
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 66) #
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 67) sub parse_abi {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 68) my $file = $File::Find::name;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 69)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 70) my $mode = (stat($file))[2];
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 71) return if ($mode & S_IFDIR);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 72) return if ($file =~ m,/README,);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 73)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 74) my $name = $file;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 75) $name =~ s,.*/,,;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 76)
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 77) my $fn = $file;
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 78) $fn =~ s,Documentation/ABI/,,;
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 79)
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 80) my $nametag = "File $fn";
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 81) $data{$nametag}->{what} = "File $name";
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 82) $data{$nametag}->{type} = "File";
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 83) $data{$nametag}->{file} = $name;
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 84) $data{$nametag}->{filepath} = $file;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 85) $data{$nametag}->{is_file} = 1;
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 86) $data{$nametag}->{line_no} = 1;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 87)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 88) my $type = $file;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 89) $type =~ s,.*/(.*)/.*,$1,;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 90)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 91) my $what;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 92) my $new_what;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 93) my $tag = "";
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 94) my $ln;
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 95) my $xrefs;
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 96) my $space;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 97) my @labels;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 98) my $label = "";
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 99)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 100) print STDERR "Opening $file\n" if ($debug > 1);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 101) open IN, $file;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 102) while(<IN>) {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 103) $ln++;
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 104) if (m/^(\S+)(:\s*)(.*)/i) {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 105) my $new_tag = lc($1);
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 106) my $sep = $2;
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 107) my $content = $3;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 108)
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 109) if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 110) if ($tag eq "description") {
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 111) # New "tag" is actually part of
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 112) # description. Don't consider it a tag
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 113) $new_tag = "";
7d7ea8d2409fc (Mauro Carvalho Chehab 2019-06-20 14:23:01 -0300 114) } elsif ($tag ne "") {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 115) parse_error($file, $ln, "tag '$tag' is invalid", $_);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 116) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 117) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 118)
2c0700e7afa40 (Mauro Carvalho Chehab 2019-06-20 14:23:03 -0300 119) # Invalid, but it is a common mistake
2c0700e7afa40 (Mauro Carvalho Chehab 2019-06-20 14:23:03 -0300 120) if ($new_tag eq "where") {
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 121) parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
2c0700e7afa40 (Mauro Carvalho Chehab 2019-06-20 14:23:03 -0300 122) $new_tag = "what";
2c0700e7afa40 (Mauro Carvalho Chehab 2019-06-20 14:23:03 -0300 123) }
2c0700e7afa40 (Mauro Carvalho Chehab 2019-06-20 14:23:03 -0300 124)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 125) if ($new_tag =~ m/what/) {
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 126) $space = "";
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 127) $content =~ s/[,.;]$//;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 128)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 129) push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1);
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 130)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 131) if ($tag =~ m/what/) {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 132) $what .= ", " . $content;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 133) } else {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 134) if ($what) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 135) parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 136)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 137) foreach my $w(split /, /, $what) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 138) $symbols{$w}->{xref} = $what;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 139) };
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 140) }
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 141)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 142) $what = $content;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 143) $label = $content;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 144) $new_what = 1;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 145) }
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 146) push @labels, [($content, $label)];
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 147) $tag = $new_tag;
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 148)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 149) push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what});
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 150) next;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 151) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 152)
7d7ea8d2409fc (Mauro Carvalho Chehab 2019-06-20 14:23:01 -0300 153) if ($tag ne "" && $new_tag) {
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 154) $tag = $new_tag;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 155)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 156) if ($new_what) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 157) @{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what});
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 158) @labels = ();
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 159) $label = "";
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 160) $new_what = 0;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 161)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 162) $data{$what}->{type} = $type;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 163) if (!defined($data{$what}->{file})) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 164) $data{$what}->{file} = $name;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 165) $data{$what}->{filepath} = $file;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 166) } else {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 167) if ($name ne $data{$what}->{file}) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 168) $data{$what}->{file} .= " " . $name;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 169) $data{$what}->{filepath} .= " " . $file;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 170) }
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 171) }
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 172) print STDERR "\twhat: $what\n" if ($debug > 1);
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 173) $data{$what}->{line_no} = $ln;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 174) } else {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 175) $data{$what}->{line_no} = $ln if (!defined($data{$what}->{line_no}));
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 176) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 177)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 178) if (!$what) {
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 179) parse_error($file, $ln, "'What:' should come first:", $_);
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 180) next;
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 181) }
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 182) if ($new_tag eq "description") {
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 183) $sep =~ s,:, ,;
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 184) $content = ' ' x length($new_tag) . $sep . $content;
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 185) while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 186) if ($content =~ m/^(\s*)(\S.*)$/) {
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 187) # Preserve initial spaces for the first line
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 188) $space = $1;
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 189) $content = "$2\n";
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 190) $data{$what}->{$tag} .= $content;
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 191) } else {
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 192) undef($space);
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 193) }
e9bca8918e3d4 (Mauro Carvalho Chehab 2020-10-30 08:40:21 +0100 194)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 195) } else {
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 196) $data{$what}->{$tag} = $content;
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 197) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 198) next;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 199) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 200) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 201)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 202) # Store any contents before tags at the database
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 203) if (!$tag && $data{$nametag}->{what}) {
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 204) $data{$nametag}->{description} .= $_;
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 205) next;
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 206) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 207)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 208) if ($tag eq "description") {
e9bca8918e3d4 (Mauro Carvalho Chehab 2020-10-30 08:40:21 +0100 209) my $content = $_;
e9bca8918e3d4 (Mauro Carvalho Chehab 2020-10-30 08:40:21 +0100 210) while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 211) if (m/^\s*\n/) {
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 212) $data{$what}->{$tag} .= "\n";
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 213) next;
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 214) }
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 215)
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 216) if (!defined($space)) {
e9bca8918e3d4 (Mauro Carvalho Chehab 2020-10-30 08:40:21 +0100 217) # Preserve initial spaces for the first line
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 218) if ($content =~ m/^(\s*)(\S.*)$/) {
e9bca8918e3d4 (Mauro Carvalho Chehab 2020-10-30 08:40:21 +0100 219) $space = $1;
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 220) $content = "$2\n";
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 221) }
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 222) } else {
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 223) $space = "" if (!($content =~ s/^($space)//));
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 224) }
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 225) $data{$what}->{$tag} .= $content;
f82a8a74ea81d (Mauro Carvalho Chehab 2020-10-30 08:40:23 +0100 226)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 227) next;
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 228) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 229) if (m/^\s*(.*)/) {
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 230) $data{$what}->{$tag} .= "\n$1";
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 231) $data{$what}->{$tag} =~ s/\n+$//;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 232) next;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 233) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 234)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 235) # Everything else is error
75442fb0ccaac (Mauro Carvalho Chehab 2020-10-30 08:40:45 +0100 236) parse_error($file, $ln, "Unexpected content", $_);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 237) }
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 238) $data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 239) if ($what) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 240) parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 241)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 242) foreach my $w(split /, /,$what) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 243) $symbols{$w}->{xref} = $what;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 244) };
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 245) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 246) close IN;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 247) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 248)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 249) sub create_labels {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 250) my %labels;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 251)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 252) foreach my $what (keys %data) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 253) next if ($data{$what}->{file} eq "File");
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 254)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 255) foreach my $p (@{$data{$what}->{label_list}}) {
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 256) my ($content, $label) = @{$p};
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 257) $label = "abi_" . $label . " ";
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 258) $label =~ tr/A-Z/a-z/;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 259)
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 260) # Convert special chars to "_"
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 261) $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 262) $label =~ s,_+,_,g;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 263) $label =~ s,_$,,;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 264)
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 265) # Avoid duplicated labels
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 266) while (defined($labels{$label})) {
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 267) my @chars = ("A".."Z", "a".."z");
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 268) $label .= $chars[rand @chars];
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 269) }
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 270) $labels{$label} = 1;
2e7ce05593b39 (Mauro Carvalho Chehab 2019-06-20 14:23:02 -0300 271)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 272) $data{$what}->{label} = $label;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 273)
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 274) # only one label is enough
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 275) last;
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 276) }
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 277) }
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 278) }
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 279)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 280) #
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 281) # Outputs the book on ReST format
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 282) #
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 283)
50ebf8f4933ec (Mauro Carvalho Chehab 2021-03-25 11:38:24 +0100 284) # \b doesn't work well with paths. So, we need to define something else:
50ebf8f4933ec (Mauro Carvalho Chehab 2021-03-25 11:38:24 +0100 285) # Boundaries are punct characters, spaces and end-of-line
50ebf8f4933ec (Mauro Carvalho Chehab 2021-03-25 11:38:24 +0100 286) my $start = qr {(^|\s|\() }x;
50ebf8f4933ec (Mauro Carvalho Chehab 2021-03-25 11:38:24 +0100 287) my $bondary = qr { ([,.:;\)\s]|\z) }x;
87ec9ea1fc27a (Mauro Carvalho Chehab 2021-03-25 11:38:25 +0100 288) my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x;
b0f9580a88803 (Mauro Carvalho Chehab 2021-03-25 11:38:22 +0100 289) my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x;
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 290)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 291) sub output_rest {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 292) create_labels();
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 293)
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 294) my $part = "";
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 295)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 296) foreach my $what (sort {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 297) ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 298) $a cmp $b
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 299) } keys %data) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 300) my $type = $data{$what}->{type};
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 301)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 302) my @file = split / /, $data{$what}->{file};
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 303) my @filepath = split / /, $data{$what}->{filepath};
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 304)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 305) if ($enable_lineno) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 306) printf "#define LINENO %s%s#%s\n\n",
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 307) $prefix, $file[0],
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 308) $data{$what}->{line_no};
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 309) }
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 310)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 311) my $w = $what;
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 312)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 313) if ($type ne "File") {
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 314) my $cur_part = $what;
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 315) if ($what =~ '/') {
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 316) if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) {
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 317) $cur_part = "Symbols under $1";
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 318) $cur_part =~ s,/$,,;
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 319) }
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 320) }
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 321)
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 322) if ($cur_part ne "" && $part ne $cur_part) {
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 323) $part = $cur_part;
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 324) my $bar = $part;
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 325) $bar =~ s/./-/g;
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 326) print "$part\n$bar\n\n";
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 327) }
9d4fdda334461 (Mauro Carvalho Chehab 2020-11-02 11:32:16 +0100 328)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 329) printf ".. _%s:\n\n", $data{$what}->{label};
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 330)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 331) my @names = split /, /,$w;
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 332) my $len = 0;
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 333)
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 334) foreach my $name (@names) {
b0f9580a88803 (Mauro Carvalho Chehab 2021-03-25 11:38:22 +0100 335) $name =~ s/$symbols/\\$1/g;
c01d62d3fecb2 (Mauro Carvalho Chehab 2020-10-30 08:40:28 +0100 336) $name = "**$name**";
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 337) $len = length($name) if (length($name) > $len);
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 338) }
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 339)
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 340) print "+-" . "-" x $len . "-+\n";
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 341) foreach my $name (@names) {
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 342) printf "| %s", $name . " " x ($len - length($name)) . " |\n";
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 343) print "+-" . "-" x $len . "-+\n";
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 344) }
45f965179560f (Mauro Carvalho Chehab 2019-06-20 14:23:00 -0300 345)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 346) print "\n";
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 347) }
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 348)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 349) for (my $i = 0; $i < scalar(@filepath); $i++) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 350) my $path = $filepath[$i];
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 351) my $f = $file[$i];
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 352)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 353) $path =~ s,.*/(.*/.*),$1,;;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 354) $path =~ s,[/\-],_,g;;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 355) my $fileref = "abi_file_".$path;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 356)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 357) if ($type eq "File") {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 358) print ".. _$fileref:\n\n";
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 359) } else {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 360) print "Defined on file :ref:`$f <$fileref>`\n\n";
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 361) }
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 362) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 363)
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 364) if ($type eq "File") {
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 365) my $bar = $w;
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 366) $bar =~ s/./-/g;
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 367) print "$w\n$bar\n\n";
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 368) }
a4ea67bc65a15 (Mauro Carvalho Chehab 2020-10-30 08:40:27 +0100 369)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 370) my $desc = "";
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 371) $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 372) $desc =~ s/\s+$/\n/;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 373)
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 374) if (!($desc =~ /^\s*$/)) {
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 375) if ($description_is_rst) {
daaaf58a2b7fd (Mauro Carvalho Chehab 2020-11-02 11:32:15 +0100 376) # Remove title markups from the description
daaaf58a2b7fd (Mauro Carvalho Chehab 2020-11-02 11:32:15 +0100 377) # Having titles inside ABI files will only work if extra
daaaf58a2b7fd (Mauro Carvalho Chehab 2020-11-02 11:32:15 +0100 378) # care would be taken in order to strictly follow the same
daaaf58a2b7fd (Mauro Carvalho Chehab 2020-11-02 11:32:15 +0100 379) # level order for each markup.
daaaf58a2b7fd (Mauro Carvalho Chehab 2020-11-02 11:32:15 +0100 380) $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
daaaf58a2b7fd (Mauro Carvalho Chehab 2020-11-02 11:32:15 +0100 381)
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 382) # Enrich text by creating cross-references
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 383)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 384) my $new_desc = "";
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 385) my $init_indent = -1;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 386) my $literal_indent = -1;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 387)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 388) open(my $fh, "+<", \$desc);
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 389) while (my $d = <$fh>) {
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 390) my $indent = $d =~ m/^(\s+)/;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 391) my $spaces = length($indent);
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 392) $init_indent = $indent if ($init_indent < 0);
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 393) if ($literal_indent >= 0) {
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 394) if ($spaces > $literal_indent) {
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 395) $new_desc .= $d;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 396) next;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 397) } else {
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 398) $literal_indent = -1;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 399) }
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 400) } else {
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 401) if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) {
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 402) $literal_indent = $spaces;
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 403) }
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 404) }
2ae7bb570e5d8 (Mauro Carvalho Chehab 2021-03-25 11:38:27 +0100 405)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 406) $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 407)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 408) my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 409) foreach my $f (@matches) {
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 410) my $xref = $f;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 411) my $path = $f;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 412) $path =~ s,.*/(.*/.*),$1,;;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 413) $path =~ s,[/\-],_,g;;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 414) $xref .= " <abi_file_" . $path . ">";
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 415) $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 416) }
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 417)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 418) # Seek for cross reference symbols like /sys/...
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 419) @matches = $d =~ m/$xref_match/g;
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 420)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 421) foreach my $s (@matches) {
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 422) next if (!($s =~ m,/,));
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 423) if (defined($data{$s}) && defined($data{$s}->{label})) {
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 424) my $xref = $s;
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 425)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 426) $xref =~ s/$symbols/\\$1/g;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 427) $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`";
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 428)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 429) $d =~ s,$start$s$bondary,$1$xref$2,g;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 430) }
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 431) }
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 432) $new_desc .= $d;
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 433) }
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 434) close $fh;
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 435)
55e5414f2f8e3 (Mauro Carvalho Chehab 2020-10-30 08:40:29 +0100 436)
c27c2e34412f8 (Mauro Carvalho Chehab 2021-03-25 11:38:26 +0100 437) print "$new_desc\n\n";
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 438) } else {
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 439) $desc =~ s/^\s+//;
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 440)
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 441) # Remove title markups from the description, as they won't work
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 442) $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 443)
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 444) if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 445) # put everything inside a code block
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 446) $desc =~ s/\n/\n /g;
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 447)
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 448) print "::\n\n";
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 449) print " $desc\n\n";
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 450) } else {
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 451) # Escape any special chars from description
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 452) $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 453) print "$desc\n\n";
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 454) }
4e6a6234da844 (Mauro Carvalho Chehab 2019-06-20 14:22:57 -0300 455) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 456) } else {
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 457) print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 458) }
6619c6617a88e (Mauro Carvalho Chehab 2019-06-20 14:22:56 -0300 459)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 460) if ($data{$what}->{symbols}) {
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 461) printf "Has the following ABI:\n\n";
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 462)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 463) foreach my $content(@{$data{$what}->{symbols}}) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 464) my $label = $data{$symbols{$content}->{xref}}->{label};
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 465)
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 466) # Escape special chars from content
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 467) $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 468)
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 469) print "- :ref:`$content <$label>`\n\n";
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 470) }
d0ebaf51d219b (Mauro Carvalho Chehab 2019-06-20 14:22:58 -0300 471) }
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 472)
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 473) if (defined($data{$what}->{users})) {
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 474) my $users = $data{$what}->{users};
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 475)
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 476) $users =~ s/\n/\n\t/g;
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 477) printf "Users:\n\t%s\n\n", $users if ($users ne "");
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 478) }
a16ab14eb7a92 (Mauro Carvalho Chehab 2020-10-30 08:40:26 +0100 479)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 480) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 481) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 482)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 483) #
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 484) # Searches for ABI symbols
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 485) #
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 486) sub search_symbols {
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 487) foreach my $what (sort keys %data) {
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 488) next if (!($what =~ m/($arg)/));
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 489)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 490) my $type = $data{$what}->{type};
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 491) next if ($type eq "File");
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 492)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 493) my $file = $data{$what}->{filepath};
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 494)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 495) my $bar = $what;
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 496) $bar =~ s/./-/g;
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 497)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 498) print "\n$what\n$bar\n\n";
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 499)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 500) my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion}));
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 501) my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact}));
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 502) my $users = $data{$what}->{users} if (defined($data{$what}->{users}));
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 503) my $date = $data{$what}->{date} if (defined($data{$what}->{date}));
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 504) my $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 505)
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 506) $kernelversion =~ s/^\s+// if ($kernelversion);
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 507) $contact =~ s/^\s+// if ($contact);
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 508) if ($users) {
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 509) $users =~ s/^\s+//;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 510) $users =~ s/\n//g;
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 511) }
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 512) $date =~ s/^\s+// if ($date);
234948bf3d27e (Mauro Carvalho Chehab 2020-10-30 08:40:24 +0100 513) $desc =~ s/^\s+// if ($desc);
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 514)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 515) printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion);
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 516) printf "Date:\t\t\t%s\n", $date if ($date);
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 517) printf "Contact:\t\t%s\n", $contact if ($contact);
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 518) printf "Users:\t\t\t%s\n", $users if ($users);
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 519) print "Defined on file(s):\t$file\n\n";
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 520) print "Description:\n\n$desc";
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 521) }
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 522) }
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 523)
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 524) # Ensure that the prefix will always end with a slash
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 525) # While this is not needed for find, it makes the patch nicer
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 526) # with --enable-lineno
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 527) $prefix =~ s,/?$,/,;
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 528)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 529) #
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 530) # Parses all ABI files located at $prefix dir
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 531) #
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 532) find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 533)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 534) print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 535)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 536) #
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 537) # Handles the command
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 538) #
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 539) if ($cmd eq "search") {
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 540) search_symbols;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 541) } else {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 542) if ($cmd eq "rest") {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 543) output_rest;
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 544) }
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 545)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 546) # Warn about duplicated ABI entries
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 547) foreach my $what(sort keys %symbols) {
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 548) my @files = @{$symbols{$what}->{file}};
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 549)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 550) next if (scalar(@files) == 1);
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 551)
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 552) printf STDERR "Warning: $what is defined %d times: @files\n",
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 553) scalar(@files);
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 554) }
c7ba333426bcf (Mauro Carvalho Chehab 2020-10-30 08:40:25 +0100 555) }
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 556)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 557) __END__
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 558)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 559) =head1 NAME
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 560)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 561) abi_book.pl - parse the Linux ABI files and produce a ReST book.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 562)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 563) =head1 SYNOPSIS
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 564)
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 565) B<abi_book.pl> [--debug] [--enable-lineno] [--man] [--help]
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 566) [--(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 567)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 568) Where <COMMAND> can be:
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 569)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 570) =over 8
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 571)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 572) B<search> [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 573)
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 574) B<rest> - output the ABI in ReST markup language
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 575)
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 576) B<validate> - validate the ABI contents
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 577)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 578) =back
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 579)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 580) =head1 OPTIONS
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 581)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 582) =over 8
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 583)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 584) =item B<--dir>
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 585)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 586) Changes the location of the ABI search. By default, it uses
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 587) the Documentation/ABI directory.
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 588)
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 589) =item B<--rst-source> and B<--no-rst-source>
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 590)
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 591) The input file may be using ReST syntax or not. Those two options allow
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 592) selecting between a rst-compliant source ABI (--rst-source), or a
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 593) plain text that may be violating ReST spec, so it requres some escaping
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 594) logic (--no-rst-source).
11ce90a45d380 (Mauro Carvalho Chehab 2020-10-30 08:40:20 +0100 595)
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 596) =item B<--enable-lineno>
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 597)
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 598) Enable output of #define LINENO lines.
61439c4ada9fd (Mauro Carvalho Chehab 2020-10-30 08:40:22 +0100 599)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 600) =item B<--debug>
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 601)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 602) Put the script in verbose mode, useful for debugging. Can be called multiple
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 603) times, to increase verbosity.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 604)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 605) =item B<--help>
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 606)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 607) Prints a brief help message and exits.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 608)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 609) =item B<--man>
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 610)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 611) Prints the manual page and exits.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 612)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 613) =back
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 614)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 615) =head1 DESCRIPTION
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 616)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 617) Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI),
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 618) allowing to search for ABI symbols or to produce a ReST book containing
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 619) the Linux ABI documentation.
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 620)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 621) =head1 EXAMPLES
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 622)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 623) Search for all stable symbols with the word "usb":
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 624)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 625) =over 8
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 626)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 627) $ scripts/get_abi.pl search usb --dir Documentation/ABI/stable
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 628)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 629) =back
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 630)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 631) Search for all symbols that match the regex expression "usb.*cap":
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 632)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 633) =over 8
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 634)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 635) $ scripts/get_abi.pl search usb.*cap
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 636)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 637) =back
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 638)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 639) Output all obsoleted symbols in ReST format
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 640)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 641) =over 8
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 642)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 643) $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 644)
33e3e9913e224 (Mauro Carvalho Chehab 2019-06-20 14:22:59 -0300 645) =back
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 646)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 647) =head1 BUGS
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 648)
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 649) Report bugs to Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 650)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 651) =head1 COPYRIGHT
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 652)
7ce7b89bf565b (Mauro Carvalho Chehab 2019-06-20 14:23:04 -0300 653) Copyright (c) 2016-2019 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 654)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 655) License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 656)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 657) This is free software: you are free to change and redistribute it.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 658) There is NO WARRANTY, to the extent permitted by law.
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 659)
bbc249f2b8591 (Mauro Carvalho Chehab 2019-06-20 14:22:55 -0300 660) =cut
VisionFive2 Linux kernel
StarFive Tech Linux Kernel for VisionFive (JH7110) boards (mirror)
More than 9999 Commits
33 Branches
55 Tags