2 # SPDX-License-Identifier: GPL-2.0
4 BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
9 use Pod::Usage qw(pod2usage);
21 my $enable_lineno = 0;
22 my $show_warnings = 1;
23 my $prefix="Documentation/ABI";
24 my $sysfs_prefix="/sys";
28 my $dbg_what_parsing = 1;
29 my $dbg_what_open = 2;
30 my $dbg_dump_abi_structs = 4;
31 my $dbg_undefined = 8;
33 $Data::Dumper::Indent = 1;
34 $Data::Dumper::Terse = 1;
37 # If true, assumes that the description is formatted with ReST
39 my $description_is_rst = 1;
43 "enable-lineno" => \$enable_lineno,
44 "rst-source!" => \$description_is_rst,
47 "show-hints" => \$hint,
48 "search-string=s" => \$search_string,
52 pod2usage(1) if $help;
53 pod2usage(-exitstatus => 0, -noperldoc, -verbose => 2) if $man;
55 pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2);
57 my ($cmd, $arg) = @ARGV;
59 pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate" && $cmd ne "undefined");
60 pod2usage(2) if ($cmd eq "search" && !$arg);
62 require Data::Dumper if ($debug & $dbg_dump_abi_structs);
68 # Displays an error message, printing file name and line
70 sub parse_error($$$$) {
71 my ($file, $ln, $msg, $data) = @_;
73 return if (!$show_warnings);
77 print STDERR "Warning: file $file#$ln:\n\t$msg";
80 print STDERR ". Line\n\t\t$data";
87 # Parse an ABI file, storing its contents at %data
90 my $file = $File::Find::name;
92 my $mode = (stat($file))[2];
93 return if ($mode & S_IFDIR);
94 return if ($file =~ m,/README,);
100 $fn =~ s,Documentation/ABI/,,;
102 my $nametag = "File $fn";
103 $data{$nametag}->{what} = "File $name";
104 $data{$nametag}->{type} = "File";
105 $data{$nametag}->{file} = $name;
106 $data{$nametag}->{filepath} = $file;
107 $data{$nametag}->{is_file} = 1;
108 $data{$nametag}->{line_no} = 1;
111 $type =~ s,.*/(.*)/.*,$1,;
122 print STDERR "Opening $file\n" if ($debug & $dbg_what_open);
126 if (m/^(\S+)(:\s*)(.*)/i) {
127 my $new_tag = lc($1);
131 if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) {
132 if ($tag eq "description") {
133 # New "tag" is actually part of
134 # description. Don't consider it a tag
136 } elsif ($tag ne "") {
137 parse_error($file, $ln, "tag '$tag' is invalid", $_);
141 # Invalid, but it is a common mistake
142 if ($new_tag eq "where") {
143 parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
147 if ($new_tag =~ m/what/) {
149 $content =~ s/[,.;]$//;
151 push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1);
153 if ($tag =~ m/what/) {
154 $what .= "\xac" . $content;
157 parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
159 foreach my $w(split /\xac/, $what) {
160 $symbols{$w}->{xref} = $what;
168 push @labels, [($content, $label)];
171 push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what});
175 if ($tag ne "" && $new_tag) {
179 @{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what});
184 $data{$what}->{type} = $type;
185 if (!defined($data{$what}->{file})) {
186 $data{$what}->{file} = $name;
187 $data{$what}->{filepath} = $file;
189 $data{$what}->{description} .= "\n\n" if (defined($data{$what}->{description}));
190 if ($name ne $data{$what}->{file}) {
191 $data{$what}->{file} .= " " . $name;
192 $data{$what}->{filepath} .= " " . $file;
195 print STDERR "\twhat: $what\n" if ($debug & $dbg_what_parsing);
196 $data{$what}->{line_no} = $ln;
198 $data{$what}->{line_no} = $ln if (!defined($data{$what}->{line_no}));
202 parse_error($file, $ln, "'What:' should come first:", $_);
205 if ($new_tag eq "description") {
207 $content = ' ' x length($new_tag) . $sep . $content;
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
213 $data{$what}->{$tag} .= $content;
219 $data{$what}->{$tag} = $content;
225 # Store any contents before tags at the database
226 if (!$tag && $data{$nametag}->{what}) {
227 $data{$nametag}->{description} .= $_;
231 if ($tag eq "description") {
233 while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
235 $data{$what}->{$tag} .= "\n";
239 if (!defined($space)) {
240 # Preserve initial spaces for the first line
241 if ($content =~ m/^(\s*)(\S.*)$/) {
246 $space = "" if (!($content =~ s/^($space)//));
248 $data{$what}->{$tag} .= $content;
253 $data{$what}->{$tag} .= "\n$1";
254 $data{$what}->{$tag} =~ s/\n+$//;
258 # Everything else is error
259 parse_error($file, $ln, "Unexpected content", $_);
261 $data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
263 parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
265 foreach my $w(split /\xac/,$what) {
266 $symbols{$w}->{xref} = $what;
275 foreach my $what (keys %data) {
276 next if ($data{$what}->{file} eq "File");
278 foreach my $p (@{$data{$what}->{label_list}}) {
279 my ($content, $label) = @{$p};
280 $label = "abi_" . $label . " ";
281 $label =~ tr/A-Z/a-z/;
283 # Convert special chars to "_"
284 $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
288 # Avoid duplicated labels
289 while (defined($labels{$label})) {
290 my @chars = ("A".."Z", "a".."z");
291 $label .= $chars[rand @chars];
295 $data{$what}->{label} = $label;
297 # only one label is enough
304 # Outputs the book on ReST format
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;
311 my $xref_match = qr { $start(\/(sys|config|proc|dev|kvd)\/[^,.:;\)\s]+)$bondary }x;
312 my $symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x2f\x3a-\x40\x7b-\xff]) }x;
319 foreach my $what (sort {
320 ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
323 my $type = $data{$what}->{type};
325 my @file = split / /, $data{$what}->{file};
326 my @filepath = split / /, $data{$what}->{filepath};
328 if ($enable_lineno) {
329 printf "#define LINENO %s%s#%s\n\n",
331 $data{$what}->{line_no};
336 if ($type ne "File") {
337 my $cur_part = $what;
339 if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) {
340 $cur_part = "Symbols under $1";
345 if ($cur_part ne "" && $part ne $cur_part) {
349 print "$part\n$bar\n\n";
352 printf ".. _%s:\n\n", $data{$what}->{label};
354 my @names = split /\xac/,$w;
357 foreach my $name (@names) {
358 $name =~ s/$symbols/\\$1/g;
360 $len = length($name) if (length($name) > $len);
363 print "+-" . "-" x $len . "-+\n";
364 foreach my $name (@names) {
365 printf "| %s", $name . " " x ($len - length($name)) . " |\n";
366 print "+-" . "-" x $len . "-+\n";
372 for (my $i = 0; $i < scalar(@filepath); $i++) {
373 my $path = $filepath[$i];
376 $path =~ s,.*/(.*/.*),$1,;;
377 $path =~ s,[/\-],_,g;;
378 my $fileref = "abi_file_".$path;
380 if ($type eq "File") {
381 print ".. _$fileref:\n\n";
383 print "Defined on file :ref:`$f <$fileref>`\n\n";
387 if ($type eq "File") {
390 print "$w\n$bar\n\n";
394 $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
397 if (!($desc =~ /^\s*$/)) {
398 if ($description_is_rst) {
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;
405 # Enrich text by creating cross-references
408 my $init_indent = -1;
409 my $literal_indent = -1;
411 open(my $fh, "+<", \$desc);
412 while (my $d = <$fh>) {
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) {
421 $literal_indent = -1;
424 if ($d =~ /()::$/ && !($d =~ /^\s*\.\./)) {
425 $literal_indent = $spaces;
429 $d =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
431 my @matches = $d =~ m,Documentation/ABI/([\w\/\-]+),g;
432 foreach my $f (@matches) {
435 $path =~ s,.*/(.*/.*),$1,;;
436 $path =~ s,[/\-],_,g;;
437 $xref .= " <abi_file_" . $path . ">";
438 $d =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g;
441 # Seek for cross reference symbols like /sys/...
442 @matches = $d =~ m/$xref_match/g;
444 foreach my $s (@matches) {
445 next if (!($s =~ m,/,));
446 if (defined($data{$s}) && defined($data{$s}->{label})) {
449 $xref =~ s/$symbols/\\$1/g;
450 $xref = ":ref:`$xref <" . $data{$s}->{label} . ">`";
452 $d =~ s,$start$s$bondary,$1$xref$2,g;
460 print "$new_desc\n\n";
464 # Remove title markups from the description, as they won't work
465 $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
467 if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
468 # put everything inside a code block
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;
480 print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
483 if ($data{$what}->{symbols}) {
484 printf "Has the following ABI:\n\n";
486 foreach my $content(@{$data{$what}->{symbols}}) {
487 my $label = $data{$symbols{$content}->{xref}}->{label};
489 # Escape special chars from content
490 $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
492 print "- :ref:`$content <$label>`\n\n";
496 if (defined($data{$what}->{users})) {
497 my $users = $data{$what}->{users};
499 $users =~ s/\n/\n\t/g;
500 printf "Users:\n\t%s\n\n", $users if ($users ne "");
507 # Searches for ABI symbols
510 foreach my $what (sort keys %data) {
511 next if (!($what =~ m/($arg)/));
513 my $type = $data{$what}->{type};
514 next if ($type eq "File");
516 my $file = $data{$what}->{filepath};
518 $what =~ s/\xac/, /g;
522 print "\n$what\n$bar\n\n";
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}));
530 $kernelversion =~ s/^\s+// if ($kernelversion);
531 $contact =~ s/^\s+// if ($contact);
536 $date =~ s/^\s+// if ($date);
537 $desc =~ s/^\s+// if ($desc);
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);
543 print "Defined on file(s):\t$file\n\n";
544 print "Description:\n\n$desc";
548 # Exclude /sys/kernel/debug and /sys/kernel/tracing from the search path
549 sub dont_parse_special_attributes {
550 if (($File::Find::dir =~ m,^/sys/kernel,)) {
551 return grep {!/(debug|tracing)/ } @_;
554 if (($File::Find::dir =~ m,^/sys/fs,)) {
555 return grep {!/(pstore|bpf|fuse)/ } @_;
571 $dir =~ s,^(.*/).*,$1,;
575 my $file_ref = \%root;
576 foreach my $edge(split "/", $dir) {
578 if (!defined ${$file_ref}{$edge}) {
579 ${$file_ref}{$edge} = { };
581 $file_ref = \%{$$file_ref{$edge}};
582 ${$file_ref}{"__name"} = [ $name ];
585 ${$file_ref}{$file} = {
586 "__name" => [ $name ]
589 return \%{$$file_ref{$file}};
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!";
608 push @queue, $file_ref;
612 my $v = shift @queue;
613 my @child = keys(%{$v});
615 foreach my $c(@child) {
616 next if $seen{$$v{$c}};
617 next if ($c eq "__name");
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});
626 my $name = @{$$v{$c}{"__name"}}[0];
627 if ($name =~ s#^$file/#$link/#) {
628 push @{$$v{$c}{"__name"}}, $name;
630 # Add child to the queue and mark as seen
631 push @queue, $$v{$c};
637 my $escape_symbols = qr { ([\x01-\x08\x0e-\x1f\x21-\x29\x2b-\x2d\x3a-\x40\x7b-\xfe]) }x;
638 sub parse_existing_sysfs {
639 my $file = $File::Find::name;
641 my $mode = (lstat($file))[2];
642 my $abs_file = abs_path($file);
646 push @tmp, $abs_file if ($abs_file ne $file);
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/#);
652 # Ignore firmware as it is documented elsewhere
653 # Either ACPI or under Documentation/devicetree/bindings/
654 return if ($f =~ m#^/sys/firmware/#);
656 # Ignore some sysfs nodes that aren't actually part of ABI
657 return if ($f =~ m#/sections|notes/#);
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/#);
665 if (S_ISLNK($mode)) {
666 $aliases{$file} = $abs_file;
670 return if (S_ISDIR($mode));
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}));
676 push @files, graph_add_file($abs_file, "file");
690 $leave =~ s/[\(\)]//g;
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
699 if ($leave =~ m/\.\*/ || $leave eq "" || $leave =~ /\\d/) {
710 my $file_ref = shift;
711 my $names_ref = shift;
712 my @names = @{$names_ref};
713 my $file = $names[0];
717 my $leave = get_leave($file);
718 if (!defined($leaf{$leave})) {
721 my @expr = @{$leaf{$leave}->{expr}};
722 die ("\rmissing rules for $leave") if (!defined($leaf{$leave}));
725 $path =~ s,(.*/).*,$1,;
727 if ($search_string) {
728 return if (!($file =~ m#$search_string#));
732 for (my $i = 0; $i < @names; $i++) {
733 if ($found_string && $hint) {
735 print STDERR "--> $names[$i]\n";
737 print STDERR " $names[$i]\n";
740 foreach my $re (@expr) {
741 print STDERR "$names[$i] =~ /^$re\$/\n" if ($debug && $dbg_undefined);
742 if ($names[$i] =~ $re) {
748 if ($leave ne "others") {
749 my @expr = @{$leaf{"others"}->{expr}};
750 for (my $i = 0; $i < @names; $i++) {
751 foreach my $re (@expr) {
752 print STDERR "$names[$i] =~ /^$re\$/\n" if ($debug && $dbg_undefined);
753 if ($names[$i] =~ $re) {
760 push @not_found, $file if (!$search_string || $found_string);
762 if ($hint && (!$search_string || $found_string)) {
763 my $what = $leaf{$leave}->{what};
764 $what =~ s/\xac/\n\t/g;
765 if ($leave ne "others") {
766 print STDERR "\r more likely regexes:\n\t$what\n";
768 print STDERR "\r tested regexes:\n\t$what\n";
773 sub check_undefined_symbols {
774 my $num_files = scalar @files;
776 my $start_time = times;
778 @files = sort @files;
780 my $last_time = $start_time;
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;
789 $is_console = 1 if (-t STDERR);
791 for (my $i = 0; $i < $num_files; $i++) {
792 my $file_ref = $files[$i];
793 my @names = @{$$file_ref{"__name"}};
795 check_file($file_ref, \@names);
797 my $cur_time = times;
799 if ($i == $next_i || $cur_time > $last_time + 1) {
800 my $percent = $i * 100 / $num_files;
802 my $tm = $cur_time - $start_time;
803 my $time = sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm));
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);
810 $next_i = int (($percent + 1) * $num_files / 100);
811 $last_time = $cur_time;
815 my $cur_time = times;
816 my $tm = $cur_time - $start_time;
817 my $time = sprintf "%d:%02d", int($tm), 60 * ($tm - int($tm));
819 printf STDERR "\33[2K\r", if ($is_console);
820 printf STDERR "%s: processing sysfs files... done\n", $time;
822 foreach my $file (@not_found) {
823 print "$file not found.\n";
827 sub undefined_symbols {
828 print STDERR "Reading $sysfs_prefix directory contents...";
830 wanted =>\&parse_existing_sysfs,
831 preprocess =>\&dont_parse_special_attributes,
834 print STDERR "done.\n";
836 $leaf{"others"}->{what} = "";
838 print STDERR "Converting ABI What fields into regexes...";
839 foreach my $w (sort keys %data) {
840 foreach my $what (split /\xac/,$w) {
841 next if (!($what =~ m/^$sysfs_prefix/));
843 # Convert what into regular expressions
845 # Escape dot characters
846 $what =~ s/\./\xf6/g;
848 # Temporarily change [0-9]+ type of patterns
849 $what =~ s/\[0\-9\]\+/\xff/g;
851 # Temporarily change [\d+-\d+] type of patterns
852 $what =~ s/\[0\-\d+\]/\xff/g;
853 $what =~ s/\[(\d+)\]/\xf4$1\xf5/g;
855 # Temporarily change [0-9] type of patterns
856 $what =~ s/\[(\d)\-(\d)\]/\xf4$1-$2\xf5/g;
858 # Handle multiple option patterns
859 $what =~ s/[\{\<\[]([\w_]+)(?:[,|]+([\w_]+)){1,}[\}\>\]]/($1|$2)/g;
863 $what =~ s,/\xf6..,/.*,g;
864 $what =~ s/\<[^\>]+\>/.*/g;
865 $what =~ s/\{[^\}]+\}/.*/g;
866 $what =~ s/\[[^\]]+\]/.*/g;
868 $what =~ s/[XYZ]/.*/g;
870 # Recover [0-9] type of patterns
874 # Remove duplicated spaces
877 # Special case: this ABI has a parenthesis on it
878 $what =~ s/sqrt\(x^2\+y^2\+z^2\)/sqrt\(x^2\+y^2\+z^2\)/;
880 # Special case: drop comparition as in:
881 # What: foo = <something>
882 # (this happens on a few IIO definitions)
883 $what =~ s,\s*\=.*$,,;
885 # Escape all other symbols
886 $what =~ s/$escape_symbols/\\$1/g;
887 $what =~ s/\\\\/\\/g;
888 $what =~ s/\\([\[\]\(\)\|])/$1/g;
889 $what =~ s/(\d+)\\(-\d+)/$1$2/g;
891 $what =~ s/\xff/\\d+/g;
893 # Special case: IIO ABI which a parenthesis.
894 $what =~ s/sqrt(.*)/sqrt\(.*\)/;
896 # Simplify regexes with multiple .*
897 $what =~ s#(?:\.\*){2,}##g;
898 # $what =~ s#\.\*/\.\*#.*#g;
900 # Recover dot characters
901 $what =~ s/\xf6/\./g;
903 my $leave = get_leave($what);
906 foreach my $l (split /\|/, $leave) {
907 if (defined($leaf{$l})) {
908 next if ($leaf{$l}->{what} =~ m/\b$what\b/);
909 $leaf{$l}->{what} .= "\xac" . $what;
912 $leaf{$l}->{what} = $what;
916 if ($search_string && $added) {
917 print STDERR "What: $what\n" if ($what =~ m#$search_string#);
923 foreach my $l (sort keys %leaf) {
925 foreach my $w(sort split /\xac/, $leaf{$l}->{what}) {
926 push @expr, qr /^$w$/;
928 $leaf{$l}->{expr} = \@expr;
931 # Take links into account
932 foreach my $link (sort keys %aliases) {
933 my $abs_file = $aliases{$link};
934 graph_add_link($abs_file, $link);
936 print STDERR "done.\n";
938 check_undefined_symbols;
941 # Ensure that the prefix will always end with a slash
942 # While this is not needed for find, it makes the patch nicer
943 # with --enable-lineno
946 if ($cmd eq "undefined" || $cmd eq "search") {
950 # Parses all ABI files located at $prefix dir
952 find({wanted =>\&parse_abi, no_chdir => 1}, $prefix);
954 print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug & $dbg_dump_abi_structs);
957 # Handles the command
959 if ($cmd eq "undefined") {
961 } elsif ($cmd eq "search") {
964 if ($cmd eq "rest") {
968 # Warn about duplicated ABI entries
969 foreach my $what(sort keys %symbols) {
970 my @files = @{$symbols{$what}->{file}};
972 next if (scalar(@files) == 1);
974 printf STDERR "Warning: $what is defined %d times: @files\n",
983 abi_book.pl - parse the Linux ABI files and produce a ReST book.
987 B<abi_book.pl> [--debug <level>] [--enable-lineno] [--man] [--help]
988 [--(no-)rst-source] [--dir=<dir>] [--show-hints]
989 [--search-string <regex>]
990 <COMAND> [<ARGUMENT>]
992 Where B<COMMAND> can be:
996 B<search> I<SEARCH_REGEX> - search for I<SEARCH_REGEX> inside ABI
998 B<rest> - output the ABI in ReST markup language
1000 B<validate> - validate the ABI contents
1002 B<undefined> - existing symbols at the system that aren't
1003 defined at Documentation/ABI
1013 Changes the location of the ABI search. By default, it uses
1014 the Documentation/ABI directory.
1016 =item B<--rst-source> and B<--no-rst-source>
1018 The input file may be using ReST syntax or not. Those two options allow
1019 selecting between a rst-compliant source ABI (B<--rst-source>), or a
1020 plain text that may be violating ReST spec, so it requres some escaping
1021 logic (B<--no-rst-source>).
1023 =item B<--enable-lineno>
1025 Enable output of #define LINENO lines.
1027 =item B<--debug> I<debug level>
1029 Print debug information according with the level, which is given by the
1032 - 1: Debug parsing What entries from ABI files;
1033 - 2: Shows what files are opened from ABI files;
1034 - 4: Dump the structs used to store the contents of the ABI files.
1036 =item B<--show-hints>
1038 Show hints about possible definitions for the missing ABI symbols.
1039 Used only when B<undefined>.
1041 =item B<--search-string> I<regex string>
1043 Show only occurences that match a search string.
1044 Used only when B<undefined>.
1048 Prints a brief help message and exits.
1052 Prints the manual page and exits.
1058 Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI),
1059 allowing to search for ABI symbols or to produce a ReST book containing
1060 the Linux ABI documentation.
1064 Search for all stable symbols with the word "usb":
1068 $ scripts/get_abi.pl search usb --dir Documentation/ABI/stable
1072 Search for all symbols that match the regex expression "usb.*cap":
1076 $ scripts/get_abi.pl search usb.*cap
1080 Output all obsoleted symbols in ReST format
1084 $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete
1090 Report bugs to Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
1094 Copyright (c) 2016-2021 by Mauro Carvalho Chehab <mchehab+huawei@kernel.org>.
1096 License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
1098 This is free software: you are free to change and redistribute it.
1099 There is NO WARRANTY, to the extent permitted by law.