Commit | Line | Data |
---|---|---|
c25ce589 | 1 | #!/usr/bin/env perl |
ecb351f1 | 2 | # SPDX-License-Identifier: GPL-2.0 |
bbc249f2 | 3 | |
42f09848 MCC |
4 | BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; } |
5 | ||
bbc249f2 | 6 | use strict; |
234948bf | 7 | use warnings; |
55e5414f | 8 | use utf8; |
42f09848 | 9 | use Pod::Usage qw(pod2usage); |
bbc249f2 MCC |
10 | use Getopt::Long; |
11 | use File::Find; | |
28331a01 | 12 | use IO::Handle; |
bbc249f2 | 13 | use Fcntl ':mode'; |
ab02c515 | 14 | use Cwd 'abs_path'; |
46f661fd | 15 | use Data::Dumper; |
bbc249f2 | 16 | |
234948bf | 17 | my $help = 0; |
ab02c515 | 18 | my $hint = 0; |
234948bf MCC |
19 | my $man = 0; |
20 | my $debug = 0; | |
21 | my $enable_lineno = 0; | |
f090db43 | 22 | my $show_warnings = 1; |
33e3e991 | 23 | my $prefix="Documentation/ABI"; |
f090db43 | 24 | my $sysfs_prefix="/sys"; |
14c94257 | 25 | my $search_string; |
bbc249f2 | 26 | |
46f661fd MCC |
27 | # Debug options |
28 | my $dbg_what_parsing = 1; | |
29 | my $dbg_what_open = 2; | |
30 | my $dbg_dump_abi_structs = 4; | |
f34f6729 | 31 | my $dbg_undefined = 8; |
46f661fd | 32 | |
3a1cc06c MCC |
33 | $Data::Dumper::Indent = 1; |
34 | $Data::Dumper::Terse = 1; | |
35 | ||
11ce90a4 MCC |
36 | # |
37 | # If true, assumes that the description is formatted with ReST | |
38 | # | |
2fcce37a | 39 | my $description_is_rst = 1; |
11ce90a4 | 40 | |
bbc249f2 | 41 | GetOptions( |
46f661fd | 42 | "debug=i" => \$debug, |
61439c4a | 43 | "enable-lineno" => \$enable_lineno, |
11ce90a4 | 44 | "rst-source!" => \$description_is_rst, |
33e3e991 | 45 | "dir=s" => \$prefix, |
bbc249f2 | 46 | 'help|?' => \$help, |
ab02c515 | 47 | "show-hints" => \$hint, |
14c94257 | 48 | "search-string=s" => \$search_string, |
bbc249f2 MCC |
49 | man => \$man |
50 | ) or pod2usage(2); | |
51 | ||
52 | pod2usage(1) if $help; | |
42f09848 | 53 | pod2usage(-exitstatus => 0, -noperldoc, -verbose => 2) if $man; |
bbc249f2 | 54 | |
33e3e991 | 55 | pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); |
bbc249f2 | 56 | |
33e3e991 MCC |
57 | my ($cmd, $arg) = @ARGV; |
58 | ||
f090db43 | 59 | pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate" && $cmd ne "undefined"); |
33e3e991 | 60 | pod2usage(2) if ($cmd eq "search" && !$arg); |
bbc249f2 | 61 | |
46f661fd | 62 | require Data::Dumper if ($debug & $dbg_dump_abi_structs); |
bbc249f2 MCC |
63 | |
64 | my %data; | |
234948bf | 65 | my %symbols; |
bbc249f2 MCC |
66 | |
67 | # | |
68 | # Displays an error message, printing file name and line | |
69 | # | |
70 | sub parse_error($$$$) { | |
71 | my ($file, $ln, $msg, $data) = @_; | |
72 | ||
f090db43 MCC |
73 | return if (!$show_warnings); |
74 | ||
75442fb0 MCC |
75 | $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 | } | |
bbc249f2 MCC |
84 | } |
85 | ||
86 | # | |
87 | # Parse an ABI file, storing its contents at %data | |
88 | # | |
89 | sub 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,); | |
95 | ||
96 | my $name = $file; | |
97 | $name =~ s,.*/,,; | |
98 | ||
a4ea67bc MCC |
99 | my $fn = $file; |
100 | $fn =~ s,Documentation/ABI/,,; | |
101 | ||
102 | my $nametag = "File $fn"; | |
d0ebaf51 MCC |
103 | $data{$nametag}->{what} = "File $name"; |
104 | $data{$nametag}->{type} = "File"; | |
105 | $data{$nametag}->{file} = $name; | |
33e3e991 | 106 | $data{$nametag}->{filepath} = $file; |
d0ebaf51 | 107 | $data{$nametag}->{is_file} = 1; |
61439c4a | 108 | $data{$nametag}->{line_no} = 1; |
d0ebaf51 | 109 | |
bbc249f2 MCC |
110 | my $type = $file; |
111 | $type =~ s,.*/(.*)/.*,$1,; | |
112 | ||
113 | my $what; | |
114 | my $new_what; | |
234948bf | 115 | my $tag = ""; |
bbc249f2 | 116 | my $ln; |
6619c661 | 117 | my $xrefs; |
4e6a6234 | 118 | my $space; |
d0ebaf51 | 119 | my @labels; |
234948bf | 120 | my $label = ""; |
bbc249f2 | 121 | |
46f661fd | 122 | print STDERR "Opening $file\n" if ($debug & $dbg_what_open); |
bbc249f2 MCC |
123 | open IN, $file; |
124 | while(<IN>) { | |
125 | $ln++; | |
4e6a6234 | 126 | if (m/^(\S+)(:\s*)(.*)/i) { |
bbc249f2 | 127 | my $new_tag = lc($1); |
4e6a6234 MCC |
128 | my $sep = $2; |
129 | my $content = $3; | |
bbc249f2 | 130 | |
7ce7b89b | 131 | if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) { |
bbc249f2 | 132 | if ($tag eq "description") { |
4e6a6234 MCC |
133 | # New "tag" is actually part of |
134 | # description. Don't consider it a tag | |
135 | $new_tag = ""; | |
7d7ea8d2 | 136 | } elsif ($tag ne "") { |
bbc249f2 MCC |
137 | parse_error($file, $ln, "tag '$tag' is invalid", $_); |
138 | } | |
139 | } | |
140 | ||
2c0700e7 MCC |
141 | # Invalid, but it is a common mistake |
142 | if ($new_tag eq "where") { | |
75442fb0 | 143 | parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", ""); |
2c0700e7 MCC |
144 | $new_tag = "what"; |
145 | } | |
146 | ||
bbc249f2 | 147 | if ($new_tag =~ m/what/) { |
4e6a6234 | 148 | $space = ""; |
234948bf MCC |
149 | $content =~ s/[,.;]$//; |
150 | ||
c7ba3334 MCC |
151 | push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1); |
152 | ||
bbc249f2 | 153 | if ($tag =~ m/what/) { |
ab9c1480 | 154 | $what .= "\xac" . $content; |
bbc249f2 | 155 | } else { |
234948bf MCC |
156 | if ($what) { |
157 | parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description}); | |
158 | ||
ab9c1480 | 159 | foreach my $w(split /\xac/, $what) { |
c7ba3334 | 160 | $symbols{$w}->{xref} = $what; |
234948bf MCC |
161 | }; |
162 | } | |
4e6a6234 | 163 | |
bbc249f2 | 164 | $what = $content; |
d0ebaf51 | 165 | $label = $content; |
bbc249f2 MCC |
166 | $new_what = 1; |
167 | } | |
d0ebaf51 | 168 | push @labels, [($content, $label)]; |
bbc249f2 | 169 | $tag = $new_tag; |
6619c661 | 170 | |
234948bf | 171 | push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what}); |
bbc249f2 MCC |
172 | next; |
173 | } | |
174 | ||
7d7ea8d2 | 175 | if ($tag ne "" && $new_tag) { |
4e6a6234 | 176 | $tag = $new_tag; |
bbc249f2 | 177 | |
4e6a6234 | 178 | if ($new_what) { |
234948bf | 179 | @{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what}); |
d0ebaf51 MCC |
180 | @labels = (); |
181 | $label = ""; | |
4e6a6234 | 182 | $new_what = 0; |
bbc249f2 | 183 | |
4e6a6234 | 184 | $data{$what}->{type} = $type; |
c7ba3334 MCC |
185 | if (!defined($data{$what}->{file})) { |
186 | $data{$what}->{file} = $name; | |
187 | $data{$what}->{filepath} = $file; | |
188 | } else { | |
ff3777d0 | 189 | $data{$what}->{description} .= "\n\n" if (defined($data{$what}->{description})); |
c7ba3334 MCC |
190 | if ($name ne $data{$what}->{file}) { |
191 | $data{$what}->{file} .= " " . $name; | |
192 | $data{$what}->{filepath} .= " " . $file; | |
193 | } | |
194 | } | |
46f661fd | 195 | print STDERR "\twhat: $what\n" if ($debug & $dbg_what_parsing); |
c7ba3334 MCC |
196 | $data{$what}->{line_no} = $ln; |
197 | } else { | |
198 | $data{$what}->{line_no} = $ln if (!defined($data{$what}->{line_no})); | |
4e6a6234 | 199 | } |
bbc249f2 | 200 | |
4e6a6234 MCC |
201 | if (!$what) { |
202 | parse_error($file, $ln, "'What:' should come first:", $_); | |
203 | next; | |
204 | } | |
f82a8a74 MCC |
205 | if ($new_tag eq "description") { |
206 | $sep =~ s,:, ,; | |
11ce90a4 | 207 | $content = ' ' x length($new_tag) . $sep . $content; |
f82a8a74 MCC |
208 | while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} |
209 | if ($content =~ m/^(\s*)(\S.*)$/) { | |
210 | # Preserve initial spaces for the first line | |
11ce90a4 | 211 | $space = $1; |
f82a8a74 MCC |
212 | $content = "$2\n"; |
213 | $data{$what}->{$tag} .= $content; | |
214 | } else { | |
215 | undef($space); | |
4e6a6234 | 216 | } |
e9bca891 | 217 | |
4e6a6234 MCC |
218 | } else { |
219 | $data{$what}->{$tag} = $content; | |
220 | } | |
bbc249f2 MCC |
221 | next; |
222 | } | |
bbc249f2 MCC |
223 | } |
224 | ||
4e6a6234 | 225 | # Store any contents before tags at the database |
d0ebaf51 MCC |
226 | if (!$tag && $data{$nametag}->{what}) { |
227 | $data{$nametag}->{description} .= $_; | |
6619c661 MCC |
228 | next; |
229 | } | |
bbc249f2 | 230 | |
4e6a6234 | 231 | if ($tag eq "description") { |
e9bca891 MCC |
232 | my $content = $_; |
233 | while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} | |
f82a8a74 MCC |
234 | if (m/^\s*\n/) { |
235 | $data{$what}->{$tag} .= "\n"; | |
236 | next; | |
237 | } | |
238 | ||
239 | if (!defined($space)) { | |
e9bca891 | 240 | # Preserve initial spaces for the first line |
f82a8a74 | 241 | if ($content =~ m/^(\s*)(\S.*)$/) { |
e9bca891 | 242 | $space = $1; |
f82a8a74 | 243 | $content = "$2\n"; |
4e6a6234 MCC |
244 | } |
245 | } else { | |
4e6a6234 | 246 | $space = "" if (!($content =~ s/^($space)//)); |
4e6a6234 | 247 | } |
f82a8a74 MCC |
248 | $data{$what}->{$tag} .= $content; |
249 | ||
4e6a6234 MCC |
250 | next; |
251 | } | |
bbc249f2 MCC |
252 | if (m/^\s*(.*)/) { |
253 | $data{$what}->{$tag} .= "\n$1"; | |
254 | $data{$what}->{$tag} =~ s/\n+$//; | |
255 | next; | |
256 | } | |
257 | ||
258 | # Everything else is error | |
75442fb0 | 259 | parse_error($file, $ln, "Unexpected content", $_); |
bbc249f2 | 260 | } |
234948bf MCC |
261 | $data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description}); |
262 | if ($what) { | |
263 | parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description}); | |
264 | ||
ab9c1480 | 265 | foreach my $w(split /\xac/,$what) { |
c7ba3334 | 266 | $symbols{$w}->{xref} = $what; |
234948bf MCC |
267 | }; |
268 | } | |
bbc249f2 MCC |
269 | close IN; |
270 | } | |
271 | ||
234948bf MCC |
272 | sub create_labels { |
273 | my %labels; | |
bbc249f2 | 274 | |
234948bf MCC |
275 | foreach my $what (keys %data) { |
276 | next if ($data{$what}->{file} eq "File"); | |
4e6a6234 | 277 | |
234948bf | 278 | foreach my $p (@{$data{$what}->{label_list}}) { |
d0ebaf51 MCC |
279 | my ($content, $label) = @{$p}; |
280 | $label = "abi_" . $label . " "; | |
281 | $label =~ tr/A-Z/a-z/; | |
282 | ||
283 | # Convert special chars to "_" | |
284 | $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; | |
285 | $label =~ s,_+,_,g; | |
286 | $label =~ s,_$,,; | |
287 | ||
2e7ce055 MCC |
288 | # Avoid duplicated labels |
289 | while (defined($labels{$label})) { | |
290 | my @chars = ("A".."Z", "a".."z"); | |
291 | $label .= $chars[rand @chars]; | |
292 | } | |
293 | $labels{$label} = 1; | |
294 | ||
234948bf | 295 | $data{$what}->{label} = $label; |
d0ebaf51 MCC |
296 | |
297 | # only one label is enough | |
298 | last; | |
6619c661 | 299 | } |
234948bf MCC |
300 | } |
301 | } | |
302 | ||
303 | # | |
304 | # Outputs the book on ReST format | |
305 | # | |
306 | ||
50ebf8f4 MCC |
307 | # \b doesn't work well with paths. So, we need to define something else: |
308 | # Boundaries are punct characters, spaces and end-of-line | |
309 | my $start = qr {(^|\s|\() }x; | |
310 | my $bondary = qr { ([,.:;\)\s]|\z) }x; | |
87ec9ea1 | 311 | my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x; |
b0f9580a | 312 | my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x; |
55e5414f | 313 | |
234948bf MCC |
314 | sub output_rest { |
315 | create_labels(); | |
316 | ||
9d4fdda3 MCC |
317 | my $part = ""; |
318 | ||
234948bf MCC |
319 | foreach my $what (sort { |
320 | ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || | |
321 | $a cmp $b | |
322 | } keys %data) { | |
323 | my $type = $data{$what}->{type}; | |
c7ba3334 MCC |
324 | |
325 | my @file = split / /, $data{$what}->{file}; | |
326 | my @filepath = split / /, $data{$what}->{filepath}; | |
234948bf MCC |
327 | |
328 | if ($enable_lineno) { | |
329 | printf "#define LINENO %s%s#%s\n\n", | |
c7ba3334 | 330 | $prefix, $file[0], |
234948bf MCC |
331 | $data{$what}->{line_no}; |
332 | } | |
6619c661 | 333 | |
234948bf | 334 | my $w = $what; |
6619c661 | 335 | |
c7ba3334 | 336 | if ($type ne "File") { |
9d4fdda3 MCC |
337 | my $cur_part = $what; |
338 | if ($what =~ '/') { | |
339 | if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) { | |
340 | $cur_part = "Symbols under $1"; | |
341 | $cur_part =~ s,/$,,; | |
342 | } | |
343 | } | |
344 | ||
345 | if ($cur_part ne "" && $part ne $cur_part) { | |
346 | $part = $cur_part; | |
347 | my $bar = $part; | |
348 | $bar =~ s/./-/g; | |
349 | print "$part\n$bar\n\n"; | |
350 | } | |
351 | ||
234948bf | 352 | printf ".. _%s:\n\n", $data{$what}->{label}; |
45f96517 | 353 | |
ab9c1480 | 354 | my @names = split /\xac/,$w; |
45f96517 MCC |
355 | my $len = 0; |
356 | ||
357 | foreach my $name (@names) { | |
b0f9580a | 358 | $name =~ s/$symbols/\\$1/g; |
c01d62d3 | 359 | $name = "**$name**"; |
45f96517 MCC |
360 | $len = length($name) if (length($name) > $len); |
361 | } | |
362 | ||
45f96517 MCC |
363 | print "+-" . "-" x $len . "-+\n"; |
364 | foreach my $name (@names) { | |
365 | printf "| %s", $name . " " x ($len - length($name)) . " |\n"; | |
366 | print "+-" . "-" x $len . "-+\n"; | |
367 | } | |
45f96517 | 368 | |
c7ba3334 MCC |
369 | print "\n"; |
370 | } | |
371 | ||
372 | for (my $i = 0; $i < scalar(@filepath); $i++) { | |
373 | my $path = $filepath[$i]; | |
374 | my $f = $file[$i]; | |
375 | ||
376 | $path =~ s,.*/(.*/.*),$1,;; | |
377 | $path =~ s,[/\-],_,g;; | |
378 | my $fileref = "abi_file_".$path; | |
379 | ||
380 | if ($type eq "File") { | |
c7ba3334 | 381 | print ".. _$fileref:\n\n"; |
c7ba3334 MCC |
382 | } else { |
383 | print "Defined on file :ref:`$f <$fileref>`\n\n"; | |
384 | } | |
234948bf | 385 | } |
bbc249f2 | 386 | |
a4ea67bc MCC |
387 | if ($type eq "File") { |
388 | my $bar = $w; | |
389 | $bar =~ s/./-/g; | |
390 | print "$w\n$bar\n\n"; | |
391 | } | |
392 | ||
234948bf MCC |
393 | my $desc = ""; |
394 | $desc = $data{$what}->{description} if (defined($data{$what}->{description})); | |
395 | $desc =~ s/\s+$/\n/; | |
bbc249f2 | 396 | |
4e6a6234 | 397 | if (!($desc =~ /^\s*$/)) { |
11ce90a4 | 398 | if ($description_is_rst) { |
daaaf58a MCC |
399 | # Remove title markups from the description |
400 | # Having titles inside ABI files will only work if extra | |
401 | # care would be taken in order to strictly follow the same | |
402 | # level order for each markup. | |
403 | $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g; | |
404 | ||
55e5414f MCC |
405 | # Enrich text by creating cross-references |
406 | ||
c27c2e34 | 407 | my $new_desc = ""; |
2ae7bb57 MCC |
408 | my $init_indent = -1; |
409 | my $literal_indent = -1; | |
410 | ||
c27c2e34 MCC |
411 | open(my $fh, "+<", \$desc); |
412 | while (my $d = <$fh>) { | |
2ae7bb57 MCC |
413 | my $indent = $d =~ m/^(\s+)/; |
414 | my $spaces = length($indent); | |
415 | $init_indent = $indent if ($init_indent < 0); | |
416 | if ($literal_indent >= 0) { | |
417 | if ($spaces > $literal_indent) { | |
418 | $new_desc .= $d; | |
419 | next; | |
420 | } else { | |
421 | $literal_indent = -1; | |
422 | } | |
423 | } else { | |
424 | if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) { | |
425 | $literal_indent = $spaces; | |
426 | } | |
427 | } | |
428 | ||
c27c2e34 MCC |
429 | $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g; |
430 | ||
431 | my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g; | |
432 | foreach my $f (@matches) { | |
433 | my $xref = $f; | |
434 | my $path = $f; | |
435 | $path =~ s,.*/(.*/.*),$1,;; | |
436 | $path =~ s,[/\-],_,g;; | |
437 | $xref .= " <abi_file_" . $path . ">"; | |
438 | $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g; | |
439 | } | |
55e5414f | 440 | |
c27c2e34 MCC |
441 | # Seek for cross reference symbols like /sys/... |
442 | @matches = $d =~ m/$xref_match/g; | |
55e5414f | 443 | |
c27c2e34 MCC |
444 | foreach my $s (@matches) { |
445 | next if (!($s =~ m,/,)); | |
446 | if (defined($data{$s}) && defined($data{$s}->{label})) { | |
447 | my $xref = $s; | |
55e5414f | 448 | |
c27c2e34 MCC |
449 | $xref =~ s/$symbols/\\$1/g; |
450 | $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`"; | |
55e5414f | 451 | |
c27c2e34 MCC |
452 | $d =~ s,$start$s$bondary,$1$xref$2,g; |
453 | } | |
55e5414f | 454 | } |
c27c2e34 | 455 | $new_desc .= $d; |
55e5414f | 456 | } |
c27c2e34 MCC |
457 | close $fh; |
458 | ||
55e5414f | 459 | |
c27c2e34 | 460 | print "$new_desc\n\n"; |
4e6a6234 | 461 | } else { |
11ce90a4 | 462 | $desc =~ s/^\s+//; |
bbc249f2 | 463 | |
11ce90a4 MCC |
464 | # Remove title markups from the description, as they won't work |
465 | $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g; | |
466 | ||
467 | if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { | |
468 | # put everything inside a code block | |
469 | $desc =~ s/\n/\n /g; | |
470 | ||
471 | print "::\n\n"; | |
472 | print " $desc\n\n"; | |
473 | } else { | |
474 | # Escape any special chars from description | |
475 | $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; | |
476 | print "$desc\n\n"; | |
477 | } | |
4e6a6234 | 478 | } |
bbc249f2 | 479 | } else { |
d0ebaf51 | 480 | print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); |
bbc249f2 | 481 | } |
6619c661 | 482 | |
234948bf | 483 | if ($data{$what}->{symbols}) { |
d0ebaf51 MCC |
484 | printf "Has the following ABI:\n\n"; |
485 | ||
234948bf | 486 | foreach my $content(@{$data{$what}->{symbols}}) { |
c7ba3334 | 487 | my $label = $data{$symbols{$content}->{xref}}->{label}; |
d0ebaf51 MCC |
488 | |
489 | # Escape special chars from content | |
490 | $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; | |
491 | ||
492 | print "- :ref:`$content <$label>`\n\n"; | |
493 | } | |
494 | } | |
a16ab14e MCC |
495 | |
496 | if (defined($data{$what}->{users})) { | |
497 | my $users = $data{$what}->{users}; | |
498 | ||
499 | $users =~ s/\n/\n\t/g; | |
500 | printf "Users:\n\t%s\n\n", $users if ($users ne ""); | |
501 | } | |
502 | ||
bbc249f2 MCC |
503 | } |
504 | } | |
505 | ||
33e3e991 MCC |
506 | # |
507 | # Searches for ABI symbols | |
508 | # | |
509 | sub search_symbols { | |
510 | foreach my $what (sort keys %data) { | |
511 | next if (!($what =~ m/($arg)/)); | |
512 | ||
513 | my $type = $data{$what}->{type}; | |
514 | next if ($type eq "File"); | |
515 | ||
516 | my $file = $data{$what}->{filepath}; | |
517 | ||
e27c42a5 | 518 | $what =~ s/\xac/, /g; |
33e3e991 MCC |
519 | my $bar = $what; |
520 | $bar =~ s/./-/g; | |
521 | ||
522 | print "\n$what\n$bar\n\n"; | |
523 | ||
234948bf MCC |
524 | my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion})); |
525 | my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact})); | |
526 | my $users = $data{$what}->{users} if (defined($data{$what}->{users})); | |
527 | my $date = $data{$what}->{date} if (defined($data{$what}->{date})); | |
528 | my $desc = $data{$what}->{description} if (defined($data{$what}->{description})); | |
529 | ||
530 | $kernelversion =~ s/^\s+// if ($kernelversion); | |
531 | $contact =~ s/^\s+// if ($contact); | |
532 | if ($users) { | |
533 | $users =~ s/^\s+//; | |
534 | $users =~ s/\n//g; | |
535 | } | |
536 | $date =~ s/^\s+// if ($date); | |
537 | $desc =~ s/^\s+// if ($desc); | |
33e3e991 MCC |
538 | |
539 | printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion); | |
540 | printf "Date:\t\t\t%s\n", $date if ($date); | |
541 | printf "Contact:\t\t%s\n", $contact if ($contact); | |
542 | printf "Users:\t\t\t%s\n", $users if ($users); | |
c7ba3334 | 543 | print "Defined on file(s):\t$file\n\n"; |
33e3e991 MCC |
544 | print "Description:\n\n$desc"; |
545 | } | |
546 | } | |
547 | ||
f090db43 | 548 | # Exclude /sys/kernel/debug and /sys/kernel/tracing from the search path |
ab02c515 | 549 | sub dont_parse_special_attributes { |
f090db43 MCC |
550 | if (($File::Find::dir =~ m,^/sys/kernel,)) { |
551 | return grep {!/(debug|tracing)/ } @_; | |
552 | } | |
553 | ||
554 | if (($File::Find::dir =~ m,^/sys/fs,)) { | |
555 | return grep {!/(pstore|bpf|fuse)/ } @_; | |
556 | } | |
557 | ||
558 | return @_ | |
559 | } | |
560 | ||
561 | my %leaf; | |
ab02c515 MCC |
562 | my %aliases; |
563 | my @files; | |
ca8e055c MCC |
564 | my %root; |
565 | ||
566 | sub graph_add_file { | |
567 | my $file = shift; | |
568 | my $type = shift; | |
569 | ||
570 | my $dir = $file; | |
571 | $dir =~ s,^(.*/).*,$1,; | |
572 | $file =~ s,.*/,,; | |
573 | ||
574 | my $name; | |
575 | my $file_ref = \%root; | |
576 | foreach my $edge(split "/", $dir) { | |
577 | $name .= "$edge/"; | |
578 | if (!defined ${$file_ref}{$edge}) { | |
579 | ${$file_ref}{$edge} = { }; | |
580 | } | |
581 | $file_ref = \%{$$file_ref{$edge}}; | |
582 | ${$file_ref}{"__name"} = [ $name ]; | |
583 | } | |
584 | $name .= "$file"; | |
585 | ${$file_ref}{$file} = { | |
586 | "__name" => [ $name ] | |
587 | }; | |
588 | ||
589 | return \%{$$file_ref{$file}}; | |
590 | } | |
591 | ||
592 | sub graph_add_link { | |
593 | my $file = shift; | |
594 | my $link = shift; | |
595 | ||
596 | # Traverse graph to find the reference | |
597 | my $file_ref = \%root; | |
598 | foreach my $edge(split "/", $file) { | |
599 | $file_ref = \%{$$file_ref{$edge}} || die "Missing node!"; | |
600 | } | |
601 | ||
602 | # do a BFS | |
603 | ||
604 | my @queue; | |
605 | my %seen; | |
ca8e055c MCC |
606 | my $st; |
607 | ||
608 | push @queue, $file_ref; | |
609 | $seen{$start}++; | |
610 | ||
611 | while (@queue) { | |
612 | my $v = shift @queue; | |
613 | my @child = keys(%{$v}); | |
614 | ||
615 | foreach my $c(@child) { | |
616 | next if $seen{$$v{$c}}; | |
617 | next if ($c eq "__name"); | |
618 | ||
3a1cc06c MCC |
619 | if (!defined($$v{$c}{"__name"})) { |
620 | printf STDERR "Error: Couldn't find a non-empty name on a children of $file/.*: "; | |
621 | print STDERR Dumper(%{$v}); | |
622 | exit; | |
623 | } | |
624 | ||
ca8e055c MCC |
625 | # Add new name |
626 | my $name = @{$$v{$c}{"__name"}}[0]; | |
627 | if ($name =~ s#^$file/#$link/#) { | |
628 | push @{$$v{$c}{"__name"}}, $name; | |
629 | } | |
630 | # Add child to the queue and mark as seen | |
631 | push @queue, $$v{$c}; | |
632 | $seen{$c}++; | |
633 | } | |
634 | } | |
635 | } | |
f090db43 | 636 | |
ab02c515 | 637 | my $escape_symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x29\x2b-\x2d\x3a-\x40\x7b-\xfe]) }x; |
f090db43 MCC |
638 | sub parse_existing_sysfs { |
639 | my $file = $File::Find::name; | |
0b87a1b8 | 640 | |
87b58c6f MCC |
641 | my $mode = (lstat($file))[2]; |
642 | my $abs_file = abs_path($file); | |
0b87a1b8 | 643 | |
87b58c6f MCC |
644 | my @tmp; |
645 | push @tmp, $file; | |
646 | push @tmp, $abs_file if ($abs_file ne $file); | |
0cd9e25b | 647 | |
87b58c6f MCC |
648 | foreach my $f(@tmp) { |
649 | # Ignore cgroup, as this is big and has zero docs under ABI | |
650 | return if ($f =~ m#^/sys/fs/cgroup/#); | |
0cd9e25b | 651 | |
87b58c6f MCC |
652 | # Ignore firmware as it is documented elsewhere |
653 | # Either ACPI or under Documentation/devicetree/bindings/ | |
654 | return if ($f =~ m#^/sys/firmware/#); | |
655 | ||
656 | # Ignore some sysfs nodes that aren't actually part of ABI | |
657 | return if ($f =~ m#/sections|notes/#); | |
658 | ||
659 | # Would need to check at | |
660 | # Documentation/admin-guide/kernel-parameters.txt, but this | |
661 | # is not easily parseable. | |
662 | return if ($f =~ m#/parameters/#); | |
663 | } | |
f090db43 | 664 | |
ab02c515 MCC |
665 | if (S_ISLNK($mode)) { |
666 | $aliases{$file} = $abs_file; | |
667 | return; | |
668 | } | |
669 | ||
670 | return if (S_ISDIR($mode)); | |
f090db43 | 671 | |
ab02c515 MCC |
672 | # Trivial: file is defined exactly the same way at ABI What: |
673 | return if (defined($data{$file})); | |
674 | return if (defined($data{$abs_file})); | |
f090db43 | 675 | |
ca8e055c MCC |
676 | push @files, graph_add_file($abs_file, "file"); |
677 | } | |
678 | ||
679 | sub get_leave($) | |
680 | { | |
681 | my $what = shift; | |
682 | my $leave; | |
683 | ||
684 | my $l = $what; | |
685 | my $stop = 1; | |
686 | ||
687 | $leave = $l; | |
688 | $leave =~ s,/$,,; | |
689 | $leave =~ s,.*/,,; | |
690 | $leave =~ s/[\(\)]//g; | |
691 | ||
692 | # $leave is used to improve search performance at | |
693 | # check_undefined_symbols, as the algorithm there can seek | |
694 | # for a small number of "what". It also allows giving a | |
695 | # hint about a leave with the same name somewhere else. | |
696 | # However, there are a few occurences where the leave is | |
697 | # either a wildcard or a number. Just group such cases | |
698 | # altogether. | |
92635894 | 699 | if ($leave =~ m/\.\*/ || $leave eq "" || $leave =~ /\\d/) { |
ca8e055c MCC |
700 | $leave = "others"; |
701 | } | |
702 | ||
703 | return $leave; | |
ab02c515 | 704 | } |
f090db43 | 705 | |
28331a01 MCC |
706 | my @not_found; |
707 | ||
708 | sub check_file($$) | |
709 | { | |
710 | my $file_ref = shift; | |
711 | my $names_ref = shift; | |
712 | my @names = @{$names_ref}; | |
713 | my $file = $names[0]; | |
f090db43 | 714 | |
28331a01 | 715 | my $found_string; |
f090db43 | 716 | |
28331a01 MCC |
717 | my $leave = get_leave($file); |
718 | if (!defined($leaf{$leave})) { | |
719 | $leave = "others"; | |
720 | } | |
721 | my @expr = @{$leaf{$leave}->{expr}}; | |
722 | die ("\rmissing rules for $leave") if (!defined($leaf{$leave})); | |
723 | ||
724 | my $path = $file; | |
725 | $path =~ s,(.*/).*,$1,; | |
ab02c515 | 726 | |
28331a01 MCC |
727 | if ($search_string) { |
728 | return if (!($file =~ m#$search_string#)); | |
729 | $found_string = 1; | |
730 | } | |
ab02c515 | 731 | |
28331a01 MCC |
732 | for (my $i = 0; $i < @names; $i++) { |
733 | if ($found_string && $hint) { | |
734 | if (!$i) { | |
735 | print STDERR "--> $names[$i]\n"; | |
736 | } else { | |
737 | print STDERR " $names[$i]\n"; | |
738 | } | |
14c94257 | 739 | } |
28331a01 MCC |
740 | foreach my $re (@expr) { |
741 | print STDERR "$names[$i] =~ /^$re\$/\n" if ($debug && $dbg_undefined); | |
742 | if ($names[$i] =~ $re) { | |
743 | return; | |
744 | } | |
745 | } | |
746 | } | |
14c94257 | 747 | |
28331a01 MCC |
748 | if ($leave ne "others") { |
749 | my @expr = @{$leaf{$leave}->{expr}}; | |
f34f6729 | 750 | for (my $i = 0; $i < @names; $i++) { |
f34f6729 | 751 | foreach my $re (@expr) { |
28331a01 | 752 | print STDERR "$names[$i] =~ /^$re\$/\n" if ($debug && $dbg_undefined); |
f34f6729 | 753 | if ($names[$i] =~ $re) { |
28331a01 | 754 | return; |
ab02c515 | 755 | } |
f090db43 MCC |
756 | } |
757 | } | |
28331a01 MCC |
758 | } |
759 | ||
760 | push @not_found, $file if (!$search_string || $found_string); | |
f090db43 | 761 | |
28331a01 MCC |
762 | if ($hint && (!$search_string || $found_string)) { |
763 | my $what = $leaf{$leave}->{what}; | |
764 | $what =~ s/\xac/\n\t/g; | |
d4771993 | 765 | if ($leave ne "others") { |
28331a01 MCC |
766 | print STDERR "\r more likely regexes:\n\t$what\n"; |
767 | } else { | |
768 | print STDERR "\r tested regexes:\n\t$what\n"; | |
d4771993 | 769 | } |
28331a01 MCC |
770 | } |
771 | } | |
d4771993 | 772 | |
28331a01 MCC |
773 | sub check_undefined_symbols { |
774 | my $num_files = scalar @files; | |
775 | my $next_i = 0; | |
776 | my $start_time = times; | |
2833e30a | 777 | |
e5c044c8 MCC |
778 | @files = sort @files; |
779 | ||
28331a01 MCC |
780 | my $last_time = $start_time; |
781 | ||
782 | # When either debug or hint is enabled, there's no sense showing | |
783 | # progress, as the progress will be overriden. | |
784 | if ($hint || ($debug && $dbg_undefined)) { | |
785 | $next_i = $num_files; | |
786 | } | |
787 | ||
788 | my $is_console; | |
789 | $is_console = 1 if (-t STDERR); | |
790 | ||
791 | for (my $i = 0; $i < $num_files; $i++) { | |
792 | my $file_ref = $files[$i]; | |
793 | my @names = @{$$file_ref{"__name"}}; | |
794 | ||
795 | check_file($file_ref, \@names); | |
796 | ||
797 | my $cur_time = times; | |
798 | ||
799 | if ($i == $next_i || $cur_time > $last_time + 1) { | |
800 | my $percent = $i * 100 / $num_files; | |
801 | ||
802 | my $tm = $cur_time - $start_time; | |
803 | my $time = sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm)); | |
804 | ||
805 | printf STDERR "\33[2K\r", if ($is_console); | |
806 | printf STDERR "%s: processing sysfs files... %i%%: $names[0]", $time, $percent; | |
807 | printf STDERR "\n", if (!$is_console); | |
808 | STDERR->flush(); | |
809 | ||
810 | $next_i = int (($percent + 1) * $num_files / 100); | |
811 | $last_time = $cur_time; | |
ab02c515 | 812 | } |
ab02c515 | 813 | } |
28331a01 MCC |
814 | |
815 | my $cur_time = times; | |
816 | my $tm = $cur_time - $start_time; | |
817 | my $time = sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm)); | |
818 | ||
819 | printf STDERR "\33[2K\r", if ($is_console); | |
820 | printf STDERR "%s: processing sysfs files... done\n", $time; | |
821 | ||
822 | foreach my $file (@not_found) { | |
823 | print "$file not found.\n"; | |
824 | } | |
f090db43 MCC |
825 | } |
826 | ||
827 | sub undefined_symbols { | |
28331a01 | 828 | print STDERR "Reading $sysfs_prefix directory contents..."; |
ab02c515 MCC |
829 | find({ |
830 | wanted =>\&parse_existing_sysfs, | |
831 | preprocess =>\&dont_parse_special_attributes, | |
832 | no_chdir => 1 | |
833 | }, $sysfs_prefix); | |
28331a01 | 834 | print STDERR "done.\n"; |
ab02c515 | 835 | |
f34f6729 | 836 | $leaf{"others"}->{what} = ""; |
ca8e055c | 837 | |
28331a01 | 838 | print STDERR "Converting ABI What fields into regexes..."; |
f090db43 | 839 | foreach my $w (sort keys %data) { |
ca8e055c | 840 | foreach my $what (split /\xac/,$w) { |
ab02c515 MCC |
841 | next if (!($what =~ m/^$sysfs_prefix/)); |
842 | ||
843 | # Convert what into regular expressions | |
844 | ||
845 | $what =~ s,/\.\.\./,/*/,g; | |
846 | $what =~ s,\*,.*,g; | |
847 | ||
848 | # Temporarily change [0-9]+ type of patterns | |
849 | $what =~ s/\[0\-9\]\+/\xff/g; | |
850 | ||
851 | # Temporarily change [\d+-\d+] type of patterns | |
852 | $what =~ s/\[0\-\d+\]/\xff/g; | |
853 | $what =~ s/\[(\d+)\]/\xf4$1\xf5/g; | |
854 | ||
855 | # Temporarily change [0-9] type of patterns | |
856 | $what =~ s/\[(\d)\-(\d)\]/\xf4$1-$2\xf5/g; | |
857 | ||
858 | # Handle multiple option patterns | |
859 | $what =~ s/[\{\<\[]([\w_]+)(?:[,|]+([\w_]+)){1,}[\}\>\]]/($1|$2)/g; | |
860 | ||
861 | # Handle wildcards | |
862 | $what =~ s/\<[^\>]+\>/.*/g; | |
863 | $what =~ s/\{[^\}]+\}/.*/g; | |
864 | $what =~ s/\[[^\]]+\]/.*/g; | |
865 | ||
866 | $what =~ s/[XYZ]/.*/g; | |
867 | ||
868 | # Recover [0-9] type of patterns | |
869 | $what =~ s/\xf4/[/g; | |
870 | $what =~ s/\xf5/]/g; | |
871 | ||
872 | # Remove duplicated spaces | |
873 | $what =~ s/\s+/ /g; | |
874 | ||
875 | # Special case: this ABI has a parenthesis on it | |
876 | $what =~ s/sqrt\(x^2\+y^2\+z^2\)/sqrt\(x^2\+y^2\+z^2\)/; | |
877 | ||
878 | # Special case: drop comparition as in: | |
879 | # What: foo = <something> | |
880 | # (this happens on a few IIO definitions) | |
881 | $what =~ s,\s*\=.*$,,; | |
882 | ||
ab02c515 MCC |
883 | # Escape all other symbols |
884 | $what =~ s/$escape_symbols/\\$1/g; | |
885 | $what =~ s/\\\\/\\/g; | |
886 | $what =~ s/\\([\[\]\(\)\|])/$1/g; | |
887 | $what =~ s/(\d+)\\(-\d+)/$1$2/g; | |
888 | ||
14c94257 MCC |
889 | $what =~ s/\xff/\\d+/g; |
890 | ||
14c94257 MCC |
891 | # Special case: IIO ABI which a parenthesis. |
892 | $what =~ s/sqrt(.*)/sqrt\(.*\)/; | |
893 | ||
45495db9 | 894 | my $leave = get_leave($what); |
f34f6729 | 895 | |
14c94257 | 896 | my $added = 0; |
ab02c515 MCC |
897 | foreach my $l (split /\|/, $leave) { |
898 | if (defined($leaf{$l})) { | |
f34f6729 MCC |
899 | next if ($leaf{$l}->{what} =~ m/\b$what\b/); |
900 | $leaf{$l}->{what} .= "\xac" . $what; | |
14c94257 | 901 | $added = 1; |
ab02c515 | 902 | } else { |
f34f6729 | 903 | $leaf{$l}->{what} = $what; |
14c94257 | 904 | $added = 1; |
ab02c515 | 905 | } |
f090db43 | 906 | } |
14c94257 | 907 | if ($search_string && $added) { |
2833e30a | 908 | print STDERR "What: $what\n" if ($what =~ m#$search_string#); |
14c94257 MCC |
909 | } |
910 | ||
f090db43 MCC |
911 | } |
912 | } | |
f34f6729 | 913 | # Compile regexes |
e5c044c8 | 914 | foreach my $l (sort keys %leaf) { |
f34f6729 | 915 | my @expr; |
e5c044c8 | 916 | foreach my $w(sort split /\xac/, $leaf{$l}->{what}) { |
f34f6729 MCC |
917 | push @expr, qr /^$w$/; |
918 | } | |
919 | $leaf{$l}->{expr} = \@expr; | |
920 | } | |
921 | ||
ca8e055c | 922 | # Take links into account |
e5c044c8 | 923 | foreach my $link (sort keys %aliases) { |
ca8e055c MCC |
924 | my $abs_file = $aliases{$link}; |
925 | graph_add_link($abs_file, $link); | |
926 | } | |
28331a01 MCC |
927 | print STDERR "done.\n"; |
928 | ||
ab02c515 | 929 | check_undefined_symbols; |
f090db43 MCC |
930 | } |
931 | ||
61439c4a MCC |
932 | # Ensure that the prefix will always end with a slash |
933 | # While this is not needed for find, it makes the patch nicer | |
934 | # with --enable-lineno | |
935 | $prefix =~ s,/?$,/,; | |
33e3e991 | 936 | |
f090db43 MCC |
937 | if ($cmd eq "undefined" || $cmd eq "search") { |
938 | $show_warnings = 0; | |
939 | } | |
bbc249f2 MCC |
940 | # |
941 | # Parses all ABI files located at $prefix dir | |
942 | # | |
943 | find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); | |
944 | ||
46f661fd | 945 | print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug & $dbg_dump_abi_structs); |
bbc249f2 MCC |
946 | |
947 | # | |
33e3e991 | 948 | # Handles the command |
bbc249f2 | 949 | # |
f090db43 MCC |
950 | if ($cmd eq "undefined") { |
951 | undefined_symbols; | |
952 | } elsif ($cmd eq "search") { | |
33e3e991 | 953 | search_symbols; |
c7ba3334 MCC |
954 | } else { |
955 | if ($cmd eq "rest") { | |
956 | output_rest; | |
957 | } | |
958 | ||
959 | # Warn about duplicated ABI entries | |
960 | foreach my $what(sort keys %symbols) { | |
961 | my @files = @{$symbols{$what}->{file}}; | |
962 | ||
963 | next if (scalar(@files) == 1); | |
bbc249f2 | 964 | |
c7ba3334 MCC |
965 | printf STDERR "Warning: $what is defined %d times: @files\n", |
966 | scalar(@files); | |
967 | } | |
968 | } | |
bbc249f2 MCC |
969 | |
970 | __END__ | |
971 | ||
972 | =head1 NAME | |
973 | ||
974 | abi_book.pl - parse the Linux ABI files and produce a ReST book. | |
975 | ||
976 | =head1 SYNOPSIS | |
977 | ||
46f661fd | 978 | B<abi_book.pl> [--debug <level>] [--enable-lineno] [--man] [--help] |
ab02c515 | 979 | [--(no-)rst-source] [--dir=<dir>] [--show-hints] |
14c94257 | 980 | [--search-string <regex>] |
ab02c515 | 981 | <COMAND> [<ARGUMENT>] |
33e3e991 | 982 | |
42f09848 | 983 | Where B<COMMAND> can be: |
33e3e991 MCC |
984 | |
985 | =over 8 | |
986 | ||
42f09848 | 987 | B<search> I<SEARCH_REGEX> - search for I<SEARCH_REGEX> inside ABI |
33e3e991 | 988 | |
42f09848 | 989 | B<rest> - output the ABI in ReST markup language |
7ce7b89b | 990 | |
42f09848 | 991 | B<validate> - validate the ABI contents |
33e3e991 | 992 | |
42f09848 MCC |
993 | B<undefined> - existing symbols at the system that aren't |
994 | defined at Documentation/ABI | |
f090db43 | 995 | |
33e3e991 | 996 | =back |
bbc249f2 MCC |
997 | |
998 | =head1 OPTIONS | |
999 | ||
1000 | =over 8 | |
1001 | ||
33e3e991 MCC |
1002 | =item B<--dir> |
1003 | ||
1004 | Changes the location of the ABI search. By default, it uses | |
1005 | the Documentation/ABI directory. | |
1006 | ||
11ce90a4 MCC |
1007 | =item B<--rst-source> and B<--no-rst-source> |
1008 | ||
1009 | The input file may be using ReST syntax or not. Those two options allow | |
42f09848 | 1010 | selecting between a rst-compliant source ABI (B<--rst-source>), or a |
11ce90a4 | 1011 | plain text that may be violating ReST spec, so it requres some escaping |
42f09848 | 1012 | logic (B<--no-rst-source>). |
11ce90a4 | 1013 | |
61439c4a MCC |
1014 | =item B<--enable-lineno> |
1015 | ||
1016 | Enable output of #define LINENO lines. | |
1017 | ||
46f661fd MCC |
1018 | =item B<--debug> I<debug level> |
1019 | ||
1020 | Print debug information according with the level, which is given by the | |
1021 | following bitmask: | |
bbc249f2 | 1022 | |
46f661fd MCC |
1023 | - 1: Debug parsing What entries from ABI files; |
1024 | - 2: Shows what files are opened from ABI files; | |
1025 | - 4: Dump the structs used to store the contents of the ABI files. | |
bbc249f2 | 1026 | |
ab02c515 MCC |
1027 | =item B<--show-hints> |
1028 | ||
1029 | Show hints about possible definitions for the missing ABI symbols. | |
1030 | Used only when B<undefined>. | |
1031 | ||
42f09848 | 1032 | =item B<--search-string> I<regex string> |
14c94257 MCC |
1033 | |
1034 | Show only occurences that match a search string. | |
1035 | Used only when B<undefined>. | |
1036 | ||
bbc249f2 MCC |
1037 | =item B<--help> |
1038 | ||
1039 | Prints a brief help message and exits. | |
1040 | ||
1041 | =item B<--man> | |
1042 | ||
1043 | Prints the manual page and exits. | |
1044 | ||
1045 | =back | |
1046 | ||
1047 | =head1 DESCRIPTION | |
1048 | ||
33e3e991 MCC |
1049 | Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI), |
1050 | allowing to search for ABI symbols or to produce a ReST book containing | |
1051 | the Linux ABI documentation. | |
1052 | ||
1053 | =head1 EXAMPLES | |
1054 | ||
1055 | Search for all stable symbols with the word "usb": | |
1056 | ||
1057 | =over 8 | |
1058 | ||
1059 | $ scripts/get_abi.pl search usb --dir Documentation/ABI/stable | |
1060 | ||
1061 | =back | |
1062 | ||
1063 | Search for all symbols that match the regex expression "usb.*cap": | |
1064 | ||
1065 | =over 8 | |
1066 | ||
1067 | $ scripts/get_abi.pl search usb.*cap | |
1068 | ||
1069 | =back | |
1070 | ||
1071 | Output all obsoleted symbols in ReST format | |
1072 | ||
1073 | =over 8 | |
1074 | ||
1075 | $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete | |
1076 | ||
1077 | =back | |
bbc249f2 MCC |
1078 | |
1079 | =head1 BUGS | |
1080 | ||
42f09848 | 1081 | Report bugs to Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
bbc249f2 MCC |
1082 | |
1083 | =head1 COPYRIGHT | |
1084 | ||
42f09848 | 1085 | Copyright (c) 2016-2021 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>. |
bbc249f2 MCC |
1086 | |
1087 | License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. | |
1088 | ||
1089 | This is free software: you are free to change and redistribute it. | |
1090 | There is NO WARRANTY, to the extent permitted by law. | |
1091 | ||
1092 | =cut |