blob: de1c0354b50ca48d9e71e5b44e90902a056b6e47 [file] [log] [blame]
Finn Behrensc25ce582020-11-23 15:15:33 +01001#!/usr/bin/env perl
Mauro Carvalho Chehabecb351f2019-06-20 14:23:10 -03002# SPDX-License-Identifier: GPL-2.0
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03003
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02004BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
5
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03006use strict;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +01007use warnings;
Mauro Carvalho Chehab55e54142020-10-30 08:40:29 +01008use utf8;
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02009use Pod::Usage qw(pod2usage);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030010use Getopt::Long;
11use File::Find;
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +020012use IO::Handle;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030013use Fcntl ':mode';
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +020014use Cwd 'abs_path';
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +020015use Data::Dumper;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030016
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +010017my $help = 0;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +020018my $hint = 0;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +010019my $man = 0;
20my $debug = 0;
21my $enable_lineno = 0;
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +020022my $show_warnings = 1;
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -030023my $prefix="Documentation/ABI";
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +020024my $sysfs_prefix="/sys";
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +020025my $search_string;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030026
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +020027# Debug options
28my $dbg_what_parsing = 1;
29my $dbg_what_open = 2;
30my $dbg_dump_abi_structs = 4;
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +020031my $dbg_undefined = 8;
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +020032
Mauro Carvalho Chehab3a1cc062021-09-27 15:49:49 +020033$Data::Dumper::Indent = 1;
34$Data::Dumper::Terse = 1;
35
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +010036#
37# If true, assumes that the description is formatted with ReST
38#
Mauro Carvalho Chehab2fcce372020-10-30 08:40:58 +010039my $description_is_rst = 1;
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +010040
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030041GetOptions(
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +020042 "debug=i" => \$debug,
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +010043 "enable-lineno" => \$enable_lineno,
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +010044 "rst-source!" => \$description_is_rst,
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -030045 "dir=s" => \$prefix,
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030046 'help|?' => \$help,
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +020047 "show-hints" => \$hint,
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +020048 "search-string=s" => \$search_string,
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030049 man => \$man
50) or pod2usage(2);
51
52pod2usage(1) if $help;
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +020053pod2usage(-exitstatus => 0, -noperldoc, -verbose => 2) if $man;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030054
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -030055pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030056
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -030057my ($cmd, $arg) = @ARGV;
58
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +020059pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate" && $cmd ne "undefined");
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -030060pod2usage(2) if ($cmd eq "search" && !$arg);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030061
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +020062require Data::Dumper if ($debug & $dbg_dump_abi_structs);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030063
64my %data;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +010065my %symbols;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030066
67#
68# Displays an error message, printing file name and line
69#
70sub parse_error($$$$) {
71 my ($file, $ln, $msg, $data) = @_;
72
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +020073 return if (!$show_warnings);
74
Mauro Carvalho Chehab75442fb2020-10-30 08:40:45 +010075 $data =~ s/\s+$/\n/;
76
77 print STDERR "Warning: file $file#$ln:\n\t$msg";
78
79 if ($data ne "") {
80 print STDERR ". Line\n\t\t$data";
81 } else {
82 print STDERR "\n";
83 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030084}
85
86#
87# Parse an ABI file, storing its contents at %data
88#
89sub parse_abi {
90 my $file = $File::Find::name;
91
92 my $mode = (stat($file))[2];
93 return if ($mode & S_IFDIR);
94 return if ($file =~ m,/README,);
Jonathan Neuschäferaa21a1b2022-01-29 01:50:18 +010095 return if ($file =~ m,/\.,);
Randy Dunlap75ddc072023-12-28 15:31:13 -080096 return if ($file =~ m,\.(rej|org|orig|bak)$,);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -030097
98 my $name = $file;
99 $name =~ s,.*/,,;
100
Mauro Carvalho Chehaba4ea67b2020-10-30 08:40:27 +0100101 my $fn = $file;
Vegard Nossum5889d6e2024-01-01 00:59:58 +0100102 $fn =~ s,.*Documentation/ABI/,,;
Mauro Carvalho Chehaba4ea67b2020-10-30 08:40:27 +0100103
104 my $nametag = "File $fn";
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300105 $data{$nametag}->{what} = "File $name";
106 $data{$nametag}->{type} = "File";
107 $data{$nametag}->{file} = $name;
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300108 $data{$nametag}->{filepath} = $file;
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300109 $data{$nametag}->{is_file} = 1;
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +0100110 $data{$nametag}->{line_no} = 1;
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300111
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300112 my $type = $file;
113 $type =~ s,.*/(.*)/.*,$1,;
114
115 my $what;
116 my $new_what;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100117 my $tag = "";
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300118 my $ln;
Mauro Carvalho Chehab6619c662019-06-20 14:22:56 -0300119 my $xrefs;
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300120 my $space;
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300121 my @labels;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100122 my $label = "";
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300123
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +0200124 print STDERR "Opening $file\n" if ($debug & $dbg_what_open);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300125 open IN, $file;
126 while(<IN>) {
127 $ln++;
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300128 if (m/^(\S+)(:\s*)(.*)/i) {
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300129 my $new_tag = lc($1);
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300130 my $sep = $2;
131 my $content = $3;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300132
Mauro Carvalho Chehab7ce7b892019-06-20 14:23:04 -0300133 if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) {
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300134 if ($tag eq "description") {
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300135 # New "tag" is actually part of
136 # description. Don't consider it a tag
137 $new_tag = "";
Mauro Carvalho Chehab7d7ea8d2019-06-20 14:23:01 -0300138 } elsif ($tag ne "") {
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300139 parse_error($file, $ln, "tag '$tag' is invalid", $_);
140 }
141 }
142
Mauro Carvalho Chehab2c0700e2019-06-20 14:23:03 -0300143 # Invalid, but it is a common mistake
144 if ($new_tag eq "where") {
Mauro Carvalho Chehab75442fb2020-10-30 08:40:45 +0100145 parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
Mauro Carvalho Chehab2c0700e2019-06-20 14:23:03 -0300146 $new_tag = "what";
147 }
148
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300149 if ($new_tag =~ m/what/) {
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300150 $space = "";
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100151 $content =~ s/[,.;]$//;
152
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100153 push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1);
154
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300155 if ($tag =~ m/what/) {
Mauro Carvalho Chehabab9c1482021-09-18 11:52:11 +0200156 $what .= "\xac" . $content;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300157 } else {
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100158 if ($what) {
159 parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
160
Mauro Carvalho Chehabab9c1482021-09-18 11:52:11 +0200161 foreach my $w(split /\xac/, $what) {
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100162 $symbols{$w}->{xref} = $what;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100163 };
164 }
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300165
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300166 $what = $content;
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300167 $label = $content;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300168 $new_what = 1;
169 }
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300170 push @labels, [($content, $label)];
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300171 $tag = $new_tag;
Mauro Carvalho Chehab6619c662019-06-20 14:22:56 -0300172
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100173 push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what});
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300174 next;
175 }
176
Mauro Carvalho Chehab7d7ea8d2019-06-20 14:23:01 -0300177 if ($tag ne "" && $new_tag) {
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300178 $tag = $new_tag;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300179
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300180 if ($new_what) {
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100181 @{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what});
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300182 @labels = ();
183 $label = "";
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300184 $new_what = 0;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300185
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300186 $data{$what}->{type} = $type;
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100187 if (!defined($data{$what}->{file})) {
188 $data{$what}->{file} = $name;
189 $data{$what}->{filepath} = $file;
190 } else {
Mauro Carvalho Chehabff3777d2021-09-27 13:10:50 +0200191 $data{$what}->{description} .= "\n\n" if (defined($data{$what}->{description}));
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100192 if ($name ne $data{$what}->{file}) {
193 $data{$what}->{file} .= " " . $name;
194 $data{$what}->{filepath} .= " " . $file;
195 }
196 }
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +0200197 print STDERR "\twhat: $what\n" if ($debug & $dbg_what_parsing);
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100198 $data{$what}->{line_no} = $ln;
199 } else {
200 $data{$what}->{line_no} = $ln if (!defined($data{$what}->{line_no}));
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300201 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300202
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300203 if (!$what) {
204 parse_error($file, $ln, "'What:' should come first:", $_);
205 next;
206 }
Mauro Carvalho Chehabf82a8a72020-10-30 08:40:23 +0100207 if ($new_tag eq "description") {
208 $sep =~ s,:, ,;
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +0100209 $content = ' ' x length($new_tag) . $sep . $content;
Mauro Carvalho Chehabf82a8a72020-10-30 08:40:23 +0100210 while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
211 if ($content =~ m/^(\s*)(\S.*)$/) {
212 # Preserve initial spaces for the first line
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +0100213 $space = $1;
Mauro Carvalho Chehabf82a8a72020-10-30 08:40:23 +0100214 $content = "$2\n";
215 $data{$what}->{$tag} .= $content;
216 } else {
217 undef($space);
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300218 }
Mauro Carvalho Chehabe9bca892020-10-30 08:40:21 +0100219
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300220 } else {
221 $data{$what}->{$tag} = $content;
222 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300223 next;
224 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300225 }
226
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300227 # Store any contents before tags at the database
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300228 if (!$tag && $data{$nametag}->{what}) {
229 $data{$nametag}->{description} .= $_;
Mauro Carvalho Chehab6619c662019-06-20 14:22:56 -0300230 next;
231 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300232
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300233 if ($tag eq "description") {
Mauro Carvalho Chehabe9bca892020-10-30 08:40:21 +0100234 my $content = $_;
235 while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
Mauro Carvalho Chehabf82a8a72020-10-30 08:40:23 +0100236 if (m/^\s*\n/) {
237 $data{$what}->{$tag} .= "\n";
238 next;
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300239 }
Mauro Carvalho Chehabf82a8a72020-10-30 08:40:23 +0100240
241 if (!defined($space)) {
242 # Preserve initial spaces for the first line
243 if ($content =~ m/^(\s*)(\S.*)$/) {
244 $space = $1;
245 $content = "$2\n";
246 }
247 } else {
248 $space = "" if (!($content =~ s/^($space)//));
249 }
250 $data{$what}->{$tag} .= $content;
251
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300252 next;
253 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300254 if (m/^\s*(.*)/) {
255 $data{$what}->{$tag} .= "\n$1";
256 $data{$what}->{$tag} =~ s/\n+$//;
257 next;
258 }
259
260 # Everything else is error
Mauro Carvalho Chehab75442fb2020-10-30 08:40:45 +0100261 parse_error($file, $ln, "Unexpected content", $_);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300262 }
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100263 $data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
264 if ($what) {
265 parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
266
Mauro Carvalho Chehabab9c1482021-09-18 11:52:11 +0200267 foreach my $w(split /\xac/,$what) {
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100268 $symbols{$w}->{xref} = $what;
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100269 };
270 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300271 close IN;
272}
273
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100274sub create_labels {
275 my %labels;
276
277 foreach my $what (keys %data) {
278 next if ($data{$what}->{file} eq "File");
279
280 foreach my $p (@{$data{$what}->{label_list}}) {
281 my ($content, $label) = @{$p};
282 $label = "abi_" . $label . " ";
283 $label =~ tr/A-Z/a-z/;
284
285 # Convert special chars to "_"
286 $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
287 $label =~ s,_+,_,g;
288 $label =~ s,_$,,;
289
290 # Avoid duplicated labels
291 while (defined($labels{$label})) {
292 my @chars = ("A".."Z", "a".."z");
293 $label .= $chars[rand @chars];
294 }
295 $labels{$label} = 1;
296
297 $data{$what}->{label} = $label;
298
299 # only one label is enough
300 last;
301 }
302 }
303}
304
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300305#
306# Outputs the book on ReST format
307#
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300308
Mauro Carvalho Chehab50ebf8f2021-03-25 11:38:24 +0100309# \b doesn't work well with paths. So, we need to define something else:
310# Boundaries are punct characters, spaces and end-of-line
311my $start = qr {(^|\s|\() }x;
312my $bondary = qr { ([,.:;\)\s]|\z) }x;
Mauro Carvalho Chehab87ec9ea12021-03-25 11:38:25 +0100313my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x;
Mauro Carvalho Chehabb0f95802021-03-25 11:38:22 +0100314my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x;
Mauro Carvalho Chehab55e54142020-10-30 08:40:29 +0100315
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300316sub output_rest {
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100317 create_labels();
318
Mauro Carvalho Chehab9d4fdda2020-11-02 11:32:16 +0100319 my $part = "";
320
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300321 foreach my $what (sort {
322 ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
323 $a cmp $b
324 } keys %data) {
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300325 my $type = $data{$what}->{type};
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100326
327 my @file = split / /, $data{$what}->{file};
328 my @filepath = split / /, $data{$what}->{filepath};
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300329
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +0100330 if ($enable_lineno) {
Mauro Carvalho Chehab92b6de12022-03-26 11:27:23 +0100331 printf ".. LINENO %s%s#%s\n\n",
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100332 $prefix, $file[0],
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +0100333 $data{$what}->{line_no};
334 }
335
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300336 my $w = $what;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300337
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100338 if ($type ne "File") {
Mauro Carvalho Chehab9d4fdda2020-11-02 11:32:16 +0100339 my $cur_part = $what;
340 if ($what =~ '/') {
341 if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) {
342 $cur_part = "Symbols under $1";
343 $cur_part =~ s,/$,,;
344 }
345 }
346
347 if ($cur_part ne "" && $part ne $cur_part) {
348 $part = $cur_part;
349 my $bar = $part;
350 $bar =~ s/./-/g;
351 print "$part\n$bar\n\n";
352 }
353
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100354 printf ".. _%s:\n\n", $data{$what}->{label};
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300355
Mauro Carvalho Chehabab9c1482021-09-18 11:52:11 +0200356 my @names = split /\xac/,$w;
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300357 my $len = 0;
358
359 foreach my $name (@names) {
Mauro Carvalho Chehabb0f95802021-03-25 11:38:22 +0100360 $name =~ s/$symbols/\\$1/g;
Mauro Carvalho Chehabc01d62d2020-10-30 08:40:28 +0100361 $name = "**$name**";
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300362 $len = length($name) if (length($name) > $len);
363 }
364
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300365 print "+-" . "-" x $len . "-+\n";
366 foreach my $name (@names) {
367 printf "| %s", $name . " " x ($len - length($name)) . " |\n";
368 print "+-" . "-" x $len . "-+\n";
369 }
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100370
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100371 print "\n";
372 }
373
374 for (my $i = 0; $i < scalar(@filepath); $i++) {
375 my $path = $filepath[$i];
376 my $f = $file[$i];
377
378 $path =~ s,.*/(.*/.*),$1,;;
379 $path =~ s,[/\-],_,g;;
380 my $fileref = "abi_file_".$path;
381
382 if ($type eq "File") {
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100383 print ".. _$fileref:\n\n";
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100384 } else {
385 print "Defined on file :ref:`$f <$fileref>`\n\n";
386 }
Mauro Carvalho Chehab45f96512019-06-20 14:23:00 -0300387 }
388
Mauro Carvalho Chehaba4ea67b2020-10-30 08:40:27 +0100389 if ($type eq "File") {
390 my $bar = $w;
391 $bar =~ s/./-/g;
392 print "$w\n$bar\n\n";
393 }
394
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100395 my $desc = "";
396 $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
397 $desc =~ s/\s+$/\n/;
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300398
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300399 if (!($desc =~ /^\s*$/)) {
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +0100400 if ($description_is_rst) {
Mauro Carvalho Chehabdaaaf582020-11-02 11:32:15 +0100401 # Remove title markups from the description
402 # Having titles inside ABI files will only work if extra
403 # care would be taken in order to strictly follow the same
404 # level order for each markup.
405 $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
406
Mauro Carvalho Chehab55e54142020-10-30 08:40:29 +0100407 # Enrich text by creating cross-references
408
Mauro Carvalho Chehabc27c2e32021-03-25 11:38:26 +0100409 my $new_desc = "";
Mauro Carvalho Chehab2ae7bb52021-03-25 11:38:27 +0100410 my $init_indent = -1;
411 my $literal_indent = -1;
412
Mauro Carvalho Chehabc27c2e32021-03-25 11:38:26 +0100413 open(my $fh, "+<", \$desc);
414 while (my $d = <$fh>) {
Mauro Carvalho Chehab2ae7bb52021-03-25 11:38:27 +0100415 my $indent = $d =~ m/^(\s+)/;
416 my $spaces = length($indent);
417 $init_indent = $indent if ($init_indent < 0);
418 if ($literal_indent >= 0) {
419 if ($spaces > $literal_indent) {
420 $new_desc .= $d;
421 next;
422 } else {
423 $literal_indent = -1;
424 }
425 } else {
426 if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) {
427 $literal_indent = $spaces;
428 }
429 }
430
Mauro Carvalho Chehabc27c2e32021-03-25 11:38:26 +0100431 $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
Mauro Carvalho Chehab55e54142020-10-30 08:40:29 +0100432
Mauro Carvalho Chehabc27c2e32021-03-25 11:38:26 +0100433 my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g;
434 foreach my $f (@matches) {
435 my $xref = $f;
436 my $path = $f;
437 $path =~ s,.*/(.*/.*),$1,;;
438 $path =~ s,[/\-],_,g;;
439 $xref .= " <abi_file_" . $path . ">";
440 $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g;
Mauro Carvalho Chehab55e54142020-10-30 08:40:29 +0100441 }
Mauro Carvalho Chehab55e54142020-10-30 08:40:29 +0100442
Mauro Carvalho Chehabc27c2e32021-03-25 11:38:26 +0100443 # Seek for cross reference symbols like /sys/...
444 @matches = $d =~ m/$xref_match/g;
445
446 foreach my $s (@matches) {
447 next if (!($s =~ m,/,));
448 if (defined($data{$s}) && defined($data{$s}->{label})) {
449 my $xref = $s;
450
451 $xref =~ s/$symbols/\\$1/g;
452 $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`";
453
454 $d =~ s,$start$s$bondary,$1$xref$2,g;
455 }
456 }
457 $new_desc .= $d;
458 }
459 close $fh;
460
461
462 print "$new_desc\n\n";
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +0100463 } else {
464 $desc =~ s/^\s+//;
465
466 # Remove title markups from the description, as they won't work
467 $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
468
469 if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
470 # put everything inside a code block
471 $desc =~ s/\n/\n /g;
472
473 print "::\n\n";
474 print " $desc\n\n";
475 } else {
476 # Escape any special chars from description
477 $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
478 print "$desc\n\n";
479 }
Mauro Carvalho Chehab4e6a6232019-06-20 14:22:57 -0300480 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300481 } else {
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300482 print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300483 }
Mauro Carvalho Chehab6619c662019-06-20 14:22:56 -0300484
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100485 if ($data{$what}->{symbols}) {
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300486 printf "Has the following ABI:\n\n";
487
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100488 foreach my $content(@{$data{$what}->{symbols}}) {
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100489 my $label = $data{$symbols{$content}->{xref}}->{label};
Mauro Carvalho Chehabd0ebaf52019-06-20 14:22:58 -0300490
491 # Escape special chars from content
492 $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
493
494 print "- :ref:`$content <$label>`\n\n";
495 }
496 }
Mauro Carvalho Chehaba16ab142020-10-30 08:40:26 +0100497
498 if (defined($data{$what}->{users})) {
499 my $users = $data{$what}->{users};
500
501 $users =~ s/\n/\n\t/g;
502 printf "Users:\n\t%s\n\n", $users if ($users ne "");
503 }
504
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300505 }
506}
507
508#
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300509# Searches for ABI symbols
510#
511sub search_symbols {
512 foreach my $what (sort keys %data) {
513 next if (!($what =~ m/($arg)/));
514
515 my $type = $data{$what}->{type};
516 next if ($type eq "File");
517
518 my $file = $data{$what}->{filepath};
519
Mauro Carvalho Chehabe27c42a2021-09-23 17:41:12 +0200520 $what =~ s/\xac/, /g;
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300521 my $bar = $what;
522 $bar =~ s/./-/g;
523
524 print "\n$what\n$bar\n\n";
525
Mauro Carvalho Chehab234948b2020-10-30 08:40:24 +0100526 my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion}));
527 my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact}));
528 my $users = $data{$what}->{users} if (defined($data{$what}->{users}));
529 my $date = $data{$what}->{date} if (defined($data{$what}->{date}));
530 my $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
531
532 $kernelversion =~ s/^\s+// if ($kernelversion);
533 $contact =~ s/^\s+// if ($contact);
534 if ($users) {
535 $users =~ s/^\s+//;
536 $users =~ s/\n//g;
537 }
538 $date =~ s/^\s+// if ($date);
539 $desc =~ s/^\s+// if ($desc);
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300540
541 printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion);
542 printf "Date:\t\t\t%s\n", $date if ($date);
543 printf "Contact:\t\t%s\n", $contact if ($contact);
544 printf "Users:\t\t\t%s\n", $users if ($users);
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100545 print "Defined on file(s):\t$file\n\n";
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300546 print "Description:\n\n$desc";
547 }
548}
549
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200550# Exclude /sys/kernel/debug and /sys/kernel/tracing from the search path
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200551sub dont_parse_special_attributes {
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200552 if (($File::Find::dir =~ m,^/sys/kernel,)) {
553 return grep {!/(debug|tracing)/ } @_;
554 }
555
556 if (($File::Find::dir =~ m,^/sys/fs,)) {
557 return grep {!/(pstore|bpf|fuse)/ } @_;
558 }
559
560 return @_
561}
562
563my %leaf;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200564my %aliases;
565my @files;
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200566my %root;
567
568sub graph_add_file {
569 my $file = shift;
570 my $type = shift;
571
572 my $dir = $file;
573 $dir =~ s,^(.*/).*,$1,;
574 $file =~ s,.*/,,;
575
576 my $name;
577 my $file_ref = \%root;
578 foreach my $edge(split "/", $dir) {
579 $name .= "$edge/";
580 if (!defined ${$file_ref}{$edge}) {
581 ${$file_ref}{$edge} = { };
582 }
583 $file_ref = \%{$$file_ref{$edge}};
584 ${$file_ref}{"__name"} = [ $name ];
585 }
586 $name .= "$file";
587 ${$file_ref}{$file} = {
588 "__name" => [ $name ]
589 };
590
591 return \%{$$file_ref{$file}};
592}
593
594sub graph_add_link {
595 my $file = shift;
596 my $link = shift;
597
598 # Traverse graph to find the reference
599 my $file_ref = \%root;
600 foreach my $edge(split "/", $file) {
601 $file_ref = \%{$$file_ref{$edge}} || die "Missing node!";
602 }
603
604 # do a BFS
605
606 my @queue;
607 my %seen;
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200608 my $st;
609
610 push @queue, $file_ref;
611 $seen{$start}++;
612
613 while (@queue) {
614 my $v = shift @queue;
615 my @child = keys(%{$v});
616
617 foreach my $c(@child) {
618 next if $seen{$$v{$c}};
619 next if ($c eq "__name");
620
Mauro Carvalho Chehab3a1cc062021-09-27 15:49:49 +0200621 if (!defined($$v{$c}{"__name"})) {
622 printf STDERR "Error: Couldn't find a non-empty name on a children of $file/.*: ";
623 print STDERR Dumper(%{$v});
624 exit;
625 }
626
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200627 # Add new name
628 my $name = @{$$v{$c}{"__name"}}[0];
629 if ($name =~ s#^$file/#$link/#) {
630 push @{$$v{$c}{"__name"}}, $name;
631 }
632 # Add child to the queue and mark as seen
633 push @queue, $$v{$c};
634 $seen{$c}++;
635 }
636 }
637}
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200638
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200639my $escape_symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x29\x2b-\x2d\x3a-\x40\x7b-\xfe]) }x;
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200640sub parse_existing_sysfs {
641 my $file = $File::Find::name;
Mauro Carvalho Chehab0b87a1b2021-09-18 11:52:16 +0200642
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200643 my $mode = (lstat($file))[2];
644 my $abs_file = abs_path($file);
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200645
Mauro Carvalho Chehab87b58c62021-09-27 15:49:50 +0200646 my @tmp;
647 push @tmp, $file;
648 push @tmp, $abs_file if ($abs_file ne $file);
649
650 foreach my $f(@tmp) {
651 # Ignore cgroup, as this is big and has zero docs under ABI
652 return if ($f =~ m#^/sys/fs/cgroup/#);
653
654 # Ignore firmware as it is documented elsewhere
655 # Either ACPI or under Documentation/devicetree/bindings/
656 return if ($f =~ m#^/sys/firmware/#);
657
658 # Ignore some sysfs nodes that aren't actually part of ABI
659 return if ($f =~ m#/sections|notes/#);
660
661 # Would need to check at
662 # Documentation/admin-guide/kernel-parameters.txt, but this
663 # is not easily parseable.
664 return if ($f =~ m#/parameters/#);
665 }
666
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200667 if (S_ISLNK($mode)) {
668 $aliases{$file} = $abs_file;
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200669 return;
670 }
671
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200672 return if (S_ISDIR($mode));
673
674 # Trivial: file is defined exactly the same way at ABI What:
675 return if (defined($data{$file}));
676 return if (defined($data{$abs_file}));
677
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200678 push @files, graph_add_file($abs_file, "file");
679}
680
681sub get_leave($)
682{
683 my $what = shift;
684 my $leave;
685
686 my $l = $what;
687 my $stop = 1;
688
689 $leave = $l;
690 $leave =~ s,/$,,;
691 $leave =~ s,.*/,,;
692 $leave =~ s/[\(\)]//g;
693
694 # $leave is used to improve search performance at
695 # check_undefined_symbols, as the algorithm there can seek
696 # for a small number of "what". It also allows giving a
697 # hint about a leave with the same name somewhere else.
698 # However, there are a few occurences where the leave is
699 # either a wildcard or a number. Just group such cases
700 # altogether.
Mauro Carvalho Chehab926358942021-09-23 17:41:15 +0200701 if ($leave =~ m/\.\*/ || $leave eq "" || $leave =~ /\\d/) {
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200702 $leave = "others";
703 }
704
705 return $leave;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200706}
707
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200708my @not_found;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200709
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200710sub check_file($$)
711{
712 my $file_ref = shift;
713 my $names_ref = shift;
714 my @names = @{$names_ref};
715 my $file = $names[0];
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200716
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200717 my $found_string;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200718
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200719 my $leave = get_leave($file);
720 if (!defined($leaf{$leave})) {
721 $leave = "others";
722 }
723 my @expr = @{$leaf{$leave}->{expr}};
724 die ("\rmissing rules for $leave") if (!defined($leaf{$leave}));
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200725
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200726 my $path = $file;
727 $path =~ s,(.*/).*,$1,;
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200728
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200729 if ($search_string) {
730 return if (!($file =~ m#$search_string#));
731 $found_string = 1;
732 }
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200733
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200734 for (my $i = 0; $i < @names; $i++) {
735 if ($found_string && $hint) {
736 if (!$i) {
737 print STDERR "--> $names[$i]\n";
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200738 } else {
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200739 print STDERR " $names[$i]\n";
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200740 }
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200741 }
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200742 foreach my $re (@expr) {
743 print STDERR "$names[$i] =~ /^$re\$/\n" if ($debug && $dbg_undefined);
744 if ($names[$i] =~ $re) {
745 return;
746 }
747 }
748 }
749
750 if ($leave ne "others") {
Mauro Carvalho Chehab4dcce5b2021-09-30 11:39:59 +0200751 my @expr = @{$leaf{"others"}->{expr}};
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200752 for (my $i = 0; $i < @names; $i++) {
753 foreach my $re (@expr) {
754 print STDERR "$names[$i] =~ /^$re\$/\n" if ($debug && $dbg_undefined);
755 if ($names[$i] =~ $re) {
756 return;
757 }
758 }
759 }
760 }
761
762 push @not_found, $file if (!$search_string || $found_string);
763
764 if ($hint && (!$search_string || $found_string)) {
765 my $what = $leaf{$leave}->{what};
766 $what =~ s/\xac/\n\t/g;
767 if ($leave ne "others") {
768 print STDERR "\r more likely regexes:\n\t$what\n";
769 } else {
770 print STDERR "\r tested regexes:\n\t$what\n";
771 }
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200772 }
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200773}
774
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200775sub check_undefined_symbols {
776 my $num_files = scalar @files;
777 my $next_i = 0;
778 my $start_time = times;
779
Mauro Carvalho Chehabe5c044c2021-09-28 23:51:32 +0200780 @files = sort @files;
781
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200782 my $last_time = $start_time;
783
784 # When either debug or hint is enabled, there's no sense showing
785 # progress, as the progress will be overriden.
786 if ($hint || ($debug && $dbg_undefined)) {
787 $next_i = $num_files;
788 }
789
790 my $is_console;
791 $is_console = 1 if (-t STDERR);
792
793 for (my $i = 0; $i < $num_files; $i++) {
794 my $file_ref = $files[$i];
795 my @names = @{$$file_ref{"__name"}};
796
797 check_file($file_ref, \@names);
798
799 my $cur_time = times;
800
801 if ($i == $next_i || $cur_time > $last_time + 1) {
802 my $percent = $i * 100 / $num_files;
803
804 my $tm = $cur_time - $start_time;
805 my $time = sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm));
806
807 printf STDERR "\33[2K\r", if ($is_console);
808 printf STDERR "%s: processing sysfs files... %i%%: $names[0]", $time, $percent;
809 printf STDERR "\n", if (!$is_console);
810 STDERR->flush();
811
812 $next_i = int (($percent + 1) * $num_files / 100);
813 $last_time = $cur_time;
814 }
815 }
816
817 my $cur_time = times;
818 my $tm = $cur_time - $start_time;
819 my $time = sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm));
820
821 printf STDERR "\33[2K\r", if ($is_console);
822 printf STDERR "%s: processing sysfs files... done\n", $time;
823
824 foreach my $file (@not_found) {
825 print "$file not found.\n";
826 }
827}
828
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200829sub undefined_symbols {
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200830 print STDERR "Reading $sysfs_prefix directory contents...";
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200831 find({
832 wanted =>\&parse_existing_sysfs,
833 preprocess =>\&dont_parse_special_attributes,
834 no_chdir => 1
835 }, $sysfs_prefix);
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200836 print STDERR "done.\n";
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200837
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200838 $leaf{"others"}->{what} = "";
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200839
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200840 print STDERR "Converting ABI What fields into regexes...";
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200841 foreach my $w (sort keys %data) {
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200842 foreach my $what (split /\xac/,$w) {
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200843 next if (!($what =~ m/^$sysfs_prefix/));
844
845 # Convert what into regular expressions
846
Mauro Carvalho Chehabdf2205de2021-09-30 11:40:00 +0200847 # Escape dot characters
848 $what =~ s/\./\xf6/g;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200849
850 # Temporarily change [0-9]+ type of patterns
851 $what =~ s/\[0\-9\]\+/\xff/g;
852
853 # Temporarily change [\d+-\d+] type of patterns
854 $what =~ s/\[0\-\d+\]/\xff/g;
855 $what =~ s/\[(\d+)\]/\xf4$1\xf5/g;
856
857 # Temporarily change [0-9] type of patterns
858 $what =~ s/\[(\d)\-(\d)\]/\xf4$1-$2\xf5/g;
859
860 # Handle multiple option patterns
861 $what =~ s/[\{\<\[]([\w_]+)(?:[,|]+([\w_]+)){1,}[\}\>\]]/($1|$2)/g;
862
863 # Handle wildcards
Mauro Carvalho Chehabdf2205de2021-09-30 11:40:00 +0200864 $what =~ s,\*,.*,g;
865 $what =~ s,/\xf6..,/.*,g;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200866 $what =~ s/\<[^\>]+\>/.*/g;
867 $what =~ s/\{[^\}]+\}/.*/g;
868 $what =~ s/\[[^\]]+\]/.*/g;
869
870 $what =~ s/[XYZ]/.*/g;
871
872 # Recover [0-9] type of patterns
873 $what =~ s/\xf4/[/g;
874 $what =~ s/\xf5/]/g;
875
876 # Remove duplicated spaces
877 $what =~ s/\s+/ /g;
878
879 # Special case: this ABI has a parenthesis on it
880 $what =~ s/sqrt\(x^2\+y^2\+z^2\)/sqrt\(x^2\+y^2\+z^2\)/;
881
882 # Special case: drop comparition as in:
883 # What: foo = <something>
884 # (this happens on a few IIO definitions)
885 $what =~ s,\s*\=.*$,,;
886
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200887 # Escape all other symbols
888 $what =~ s/$escape_symbols/\\$1/g;
889 $what =~ s/\\\\/\\/g;
890 $what =~ s/\\([\[\]\(\)\|])/$1/g;
891 $what =~ s/(\d+)\\(-\d+)/$1$2/g;
892
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200893 $what =~ s/\xff/\\d+/g;
894
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200895 # Special case: IIO ABI which a parenthesis.
896 $what =~ s/sqrt(.*)/sqrt\(.*\)/;
897
Mauro Carvalho Chehabdf2205de2021-09-30 11:40:00 +0200898 # Simplify regexes with multiple .*
899 $what =~ s#(?:\.\*){2,}##g;
900# $what =~ s#\.\*/\.\*#.*#g;
901
902 # Recover dot characters
903 $what =~ s/\xf6/\./g;
904
Mauro Carvalho Chehab45495db2021-09-23 17:41:13 +0200905 my $leave = get_leave($what);
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200906
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200907 my $added = 0;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200908 foreach my $l (split /\|/, $leave) {
909 if (defined($leaf{$l})) {
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200910 next if ($leaf{$l}->{what} =~ m/\b$what\b/);
911 $leaf{$l}->{what} .= "\xac" . $what;
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200912 $added = 1;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200913 } else {
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200914 $leaf{$l}->{what} = $what;
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200915 $added = 1;
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200916 }
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200917 }
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200918 if ($search_string && $added) {
Mauro Carvalho Chehab2833e30a2021-09-28 12:14:02 +0200919 print STDERR "What: $what\n" if ($what =~ m#$search_string#);
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200920 }
921
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200922 }
923 }
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200924 # Compile regexes
Mauro Carvalho Chehabe5c044c2021-09-28 23:51:32 +0200925 foreach my $l (sort keys %leaf) {
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200926 my @expr;
Mauro Carvalho Chehabe5c044c2021-09-28 23:51:32 +0200927 foreach my $w(sort split /\xac/, $leaf{$l}->{what}) {
Mauro Carvalho Chehabf34f6722021-09-23 17:41:18 +0200928 push @expr, qr /^$w$/;
929 }
930 $leaf{$l}->{expr} = \@expr;
931 }
932
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200933 # Take links into account
Mauro Carvalho Chehabe5c044c2021-09-28 23:51:32 +0200934 foreach my $link (sort keys %aliases) {
Mauro Carvalho Chehabca8e0552021-09-18 11:52:17 +0200935 my $abs_file = $aliases{$link};
936 graph_add_link($abs_file, $link);
937 }
Mauro Carvalho Chehab28331a02021-09-28 12:14:03 +0200938 print STDERR "done.\n";
939
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200940 check_undefined_symbols;
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200941}
942
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +0100943# Ensure that the prefix will always end with a slash
944# While this is not needed for find, it makes the patch nicer
945# with --enable-lineno
946$prefix =~ s,/?$,/,;
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300947
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200948if ($cmd eq "undefined" || $cmd eq "search") {
949 $show_warnings = 0;
950}
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300951#
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300952# Parses all ABI files located at $prefix dir
953#
954find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
955
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +0200956print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug & $dbg_dump_abi_structs);
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300957
958#
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300959# Handles the command
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300960#
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +0200961if ($cmd eq "undefined") {
962 undefined_symbols;
963} elsif ($cmd eq "search") {
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300964 search_symbols;
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100965} else {
966 if ($cmd eq "rest") {
967 output_rest;
968 }
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300969
Mauro Carvalho Chehabc7ba3332020-10-30 08:40:25 +0100970 # Warn about duplicated ABI entries
971 foreach my $what(sort keys %symbols) {
972 my @files = @{$symbols{$what}->{file}};
973
974 next if (scalar(@files) == 1);
975
976 printf STDERR "Warning: $what is defined %d times: @files\n",
977 scalar(@files);
978 }
979}
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300980
981__END__
982
983=head1 NAME
984
SeongJae Park5b5bfec2022-04-19 12:16:36 +0000985get_abi.pl - parse the Linux ABI files and produce a ReST book.
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -0300986
987=head1 SYNOPSIS
988
SeongJae Park5b5bfec2022-04-19 12:16:36 +0000989B<get_abi.pl> [--debug <level>] [--enable-lineno] [--man] [--help]
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +0200990 [--(no-)rst-source] [--dir=<dir>] [--show-hints]
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +0200991 [--search-string <regex>]
Michal Simek5bff9632022-02-25 12:40:08 +0100992 <COMMAND> [<ARGUMENT>]
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300993
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +0200994Where B<COMMAND> can be:
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300995
996=over 8
997
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +0200998B<search> I<SEARCH_REGEX> - search for I<SEARCH_REGEX> inside ABI
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -0300999
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001000B<rest> - output the ABI in ReST markup language
Mauro Carvalho Chehab7ce7b892019-06-20 14:23:04 -03001001
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001002B<validate> - validate the ABI contents
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -03001003
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001004B<undefined> - existing symbols at the system that aren't
1005 defined at Documentation/ABI
Mauro Carvalho Chehabf090db42021-09-18 11:52:12 +02001006
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -03001007=back
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001008
1009=head1 OPTIONS
1010
1011=over 8
1012
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -03001013=item B<--dir>
1014
1015Changes the location of the ABI search. By default, it uses
1016the Documentation/ABI directory.
1017
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +01001018=item B<--rst-source> and B<--no-rst-source>
1019
1020The input file may be using ReST syntax or not. Those two options allow
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001021selecting between a rst-compliant source ABI (B<--rst-source>), or a
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +01001022plain text that may be violating ReST spec, so it requres some escaping
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001023logic (B<--no-rst-source>).
Mauro Carvalho Chehab11ce90a2020-10-30 08:40:20 +01001024
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +01001025=item B<--enable-lineno>
1026
Mauro Carvalho Chehab92b6de12022-03-26 11:27:23 +01001027Enable output of .. LINENO lines.
Mauro Carvalho Chehab61439c42020-10-30 08:40:22 +01001028
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +02001029=item B<--debug> I<debug level>
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001030
Mauro Carvalho Chehab46f661f2021-09-23 17:41:14 +02001031Print debug information according with the level, which is given by the
1032following bitmask:
1033
1034 - 1: Debug parsing What entries from ABI files;
1035 - 2: Shows what files are opened from ABI files;
1036 - 4: Dump the structs used to store the contents of the ABI files.
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001037
Mauro Carvalho Chehabab02c512021-09-18 11:52:13 +02001038=item B<--show-hints>
1039
1040Show hints about possible definitions for the missing ABI symbols.
1041Used only when B<undefined>.
1042
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001043=item B<--search-string> I<regex string>
Mauro Carvalho Chehab14c94252021-09-18 11:52:14 +02001044
1045Show only occurences that match a search string.
1046Used only when B<undefined>.
1047
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001048=item B<--help>
1049
1050Prints a brief help message and exits.
1051
1052=item B<--man>
1053
1054Prints the manual page and exits.
1055
1056=back
1057
1058=head1 DESCRIPTION
1059
Mauro Carvalho Chehab33e3e992019-06-20 14:22:59 -03001060Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI),
1061allowing to search for ABI symbols or to produce a ReST book containing
1062the Linux ABI documentation.
1063
1064=head1 EXAMPLES
1065
1066Search for all stable symbols with the word "usb":
1067
1068=over 8
1069
1070$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable
1071
1072=back
1073
1074Search for all symbols that match the regex expression "usb.*cap":
1075
1076=over 8
1077
1078$ scripts/get_abi.pl search usb.*cap
1079
1080=back
1081
1082Output all obsoleted symbols in ReST format
1083
1084=over 8
1085
1086$ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete
1087
1088=back
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001089
1090=head1 BUGS
1091
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001092Report bugs to Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001093
1094=head1 COPYRIGHT
1095
Mauro Carvalho Chehab42f09842021-09-27 15:49:51 +02001096Copyright (c) 2016-2021 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
Mauro Carvalho Chehabbbc249f22019-06-20 14:22:55 -03001097
1098License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
1099
1100This is free software: you are free to change and redistribute it.
1101There is NO WARRANTY, to the extent permitted by law.
1102
1103=cut