402 lines · plain
1#!/usr/bin/env perl2use strict;3use Text::Tabs;4use Getopt::Long;5use Pod::Usage;6 7my $debug;8my $help;9my $man;10 11GetOptions(12 "debug" => \$debug,13 'usage|?' => \$help,14 'help' => \$man15) or pod2usage(2);16 17pod2usage(1) if $help;18pod2usage(-exitstatus => 0, -verbose => 2) if $man;19pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3);20 21my ($file_in, $file_out, $file_exceptions) = @ARGV;22 23my $data;24my %ioctls;25my %defines;26my %typedefs;27my %enums;28my %enum_symbols;29my %structs;30 31require Data::Dumper if ($debug);32 33#34# read the file and get identifiers35#36 37my $is_enum = 0;38my $is_comment = 0;39open IN, $file_in or die "Can't open $file_in";40while (<IN>) {41 $data .= $_;42 43 my $ln = $_;44 if (!$is_comment) {45 $ln =~ s,/\*.*(\*/),,g;46 47 $is_comment = 1 if ($ln =~ s,/\*.*,,);48 } else {49 if ($ln =~ s,^(.*\*/),,) {50 $is_comment = 0;51 } else {52 next;53 }54 }55 56 if ($is_enum && $ln =~ m/^\s*([_\w][\w\d_]+)\s*[\,=]?/) {57 my $s = $1;58 my $n = $1;59 $n =~ tr/A-Z/a-z/;60 $n =~ tr/_/-/;61 62 $enum_symbols{$s} = "\\ :ref:`$s <$n>`\\ ";63 64 $is_enum = 0 if ($is_enum && m/\}/);65 next;66 }67 $is_enum = 0 if ($is_enum && m/\}/);68 69 if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+_IO/) {70 my $s = $1;71 my $n = $1;72 $n =~ tr/A-Z/a-z/;73 74 $ioctls{$s} = "\\ :ref:`$s <$n>`\\ ";75 next;76 }77 78 if ($ln =~ m/^\s*#\s*define\s+([_\w][\w\d_]+)\s+/) {79 my $s = $1;80 my $n = $1;81 $n =~ tr/A-Z/a-z/;82 $n =~ tr/_/-/;83 84 $defines{$s} = "\\ :ref:`$s <$n>`\\ ";85 next;86 }87 88 if ($ln =~ m/^\s*typedef\s+([_\w][\w\d_]+)\s+(.*)\s+([_\w][\w\d_]+);/) {89 my $s = $2;90 my $n = $3;91 92 $typedefs{$n} = "\\ :c:type:`$n <$s>`\\ ";93 next;94 }95 if ($ln =~ m/^\s*enum\s+([_\w][\w\d_]+)\s+\{/96 || $ln =~ m/^\s*enum\s+([_\w][\w\d_]+)$/97 || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)\s+\{/98 || $ln =~ m/^\s*typedef\s*enum\s+([_\w][\w\d_]+)$/) {99 my $s = $1;100 101 $enums{$s} = "enum :c:type:`$s`\\ ";102 103 $is_enum = $1;104 next;105 }106 if ($ln =~ m/^\s*struct\s+([_\w][\w\d_]+)\s+\{/107 || $ln =~ m/^\s*struct\s+([[_\w][\w\d_]+)$/108 || $ln =~ m/^\s*typedef\s*struct\s+([_\w][\w\d_]+)\s+\{/109 || $ln =~ m/^\s*typedef\s*struct\s+([[_\w][\w\d_]+)$/110 ) {111 my $s = $1;112 113 $structs{$s} = "struct $s\\ ";114 next;115 }116}117close IN;118 119#120# Handle multi-line typedefs121#122 123my @matches = ($data =~ m/typedef\s+struct\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,124 $data =~ m/typedef\s+enum\s+\S+?\s*\{[^\}]+\}\s*(\S+)\s*\;/g,);125foreach my $m (@matches) {126 my $s = $m;127 128 $typedefs{$s} = "\\ :c:type:`$s`\\ ";129 next;130}131 132#133# Handle exceptions, if any134#135 136my %def_reftype = (137 "ioctl" => ":ref",138 "define" => ":ref",139 "symbol" => ":ref",140 "typedef" => ":c:type",141 "enum" => ":c:type",142 "struct" => ":c:type",143);144 145if ($file_exceptions) {146 open IN, $file_exceptions or die "Can't read $file_exceptions";147 while (<IN>) {148 next if (m/^\s*$/ || m/^\s*#/);149 150 # Parsers to ignore a symbol151 152 if (m/^ignore\s+ioctl\s+(\S+)/) {153 delete $ioctls{$1} if (exists($ioctls{$1}));154 next;155 }156 if (m/^ignore\s+define\s+(\S+)/) {157 delete $defines{$1} if (exists($defines{$1}));158 next;159 }160 if (m/^ignore\s+typedef\s+(\S+)/) {161 delete $typedefs{$1} if (exists($typedefs{$1}));162 next;163 }164 if (m/^ignore\s+enum\s+(\S+)/) {165 delete $enums{$1} if (exists($enums{$1}));166 next;167 }168 if (m/^ignore\s+struct\s+(\S+)/) {169 delete $structs{$1} if (exists($structs{$1}));170 next;171 }172 if (m/^ignore\s+symbol\s+(\S+)/) {173 delete $enum_symbols{$1} if (exists($enum_symbols{$1}));174 next;175 }176 177 # Parsers to replace a symbol178 my ($type, $old, $new, $reftype);179 180 if (m/^replace\s+(\S+)\s+(\S+)\s+(\S+)/) {181 $type = $1;182 $old = $2;183 $new = $3;184 } else {185 die "Can't parse $file_exceptions: $_";186 }187 188 if ($new =~ m/^\:c\:(data|func|macro|type)\:\`(.+)\`/) {189 $reftype = ":c:$1";190 $new = $2;191 } elsif ($new =~ m/\:ref\:\`(.+)\`/) {192 $reftype = ":ref";193 $new = $1;194 } else {195 $reftype = $def_reftype{$type};196 }197 $new = "$reftype:`$old <$new>`";198 199 if ($type eq "ioctl") {200 $ioctls{$old} = $new if (exists($ioctls{$old}));201 next;202 }203 if ($type eq "define") {204 $defines{$old} = $new if (exists($defines{$old}));205 next;206 }207 if ($type eq "symbol") {208 $enum_symbols{$old} = $new if (exists($enum_symbols{$old}));209 next;210 }211 if ($type eq "typedef") {212 $typedefs{$old} = $new if (exists($typedefs{$old}));213 next;214 }215 if ($type eq "enum") {216 $enums{$old} = $new if (exists($enums{$old}));217 next;218 }219 if ($type eq "struct") {220 $structs{$old} = $new if (exists($structs{$old}));221 next;222 }223 224 die "Can't parse $file_exceptions: $_";225 }226}227 228if ($debug) {229 print Data::Dumper->Dump([\%ioctls], [qw(*ioctls)]) if (%ioctls);230 print Data::Dumper->Dump([\%typedefs], [qw(*typedefs)]) if (%typedefs);231 print Data::Dumper->Dump([\%enums], [qw(*enums)]) if (%enums);232 print Data::Dumper->Dump([\%structs], [qw(*structs)]) if (%structs);233 print Data::Dumper->Dump([\%defines], [qw(*defines)]) if (%defines);234 print Data::Dumper->Dump([\%enum_symbols], [qw(*enum_symbols)]) if (%enum_symbols);235}236 237#238# Align block239#240$data = expand($data);241$data = " " . $data;242$data =~ s/\n/\n /g;243$data =~ s/\n\s+$/\n/g;244$data =~ s/\n\s+\n/\n\n/g;245 246#247# Add escape codes for special characters248#249$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g;250 251$data =~ s,DEPRECATED,**DEPRECATED**,g;252 253#254# Add references255#256 257my $start_delim = "[ \n\t\(\=\*\@]";258my $end_delim = "(\\s|,|\\\\=|\\\\:|\\;|\\\)|\\}|\\{)";259 260foreach my $r (keys %ioctls) {261 my $s = $ioctls{$r};262 263 $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;264 265 print "$r -> $s\n" if ($debug);266 267 $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;268}269 270foreach my $r (keys %defines) {271 my $s = $defines{$r};272 273 $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;274 275 print "$r -> $s\n" if ($debug);276 277 $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;278}279 280foreach my $r (keys %enum_symbols) {281 my $s = $enum_symbols{$r};282 283 $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;284 285 print "$r -> $s\n" if ($debug);286 287 $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;288}289 290foreach my $r (keys %enums) {291 my $s = $enums{$r};292 293 $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;294 295 print "$r -> $s\n" if ($debug);296 297 $data =~ s/enum\s+($r)$end_delim/$s$2/g;298}299 300foreach my $r (keys %structs) {301 my $s = $structs{$r};302 303 $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;304 305 print "$r -> $s\n" if ($debug);306 307 $data =~ s/struct\s+($r)$end_delim/$s$2/g;308}309 310foreach my $r (keys %typedefs) {311 my $s = $typedefs{$r};312 313 $r =~ s,([\_\`\*\<\>\&\\\\:\/]),\\\\$1,g;314 315 print "$r -> $s\n" if ($debug);316 $data =~ s/($start_delim)($r)$end_delim/$1$s$3/g;317}318 319$data =~ s/\\ ([\n\s])/\1/g;320 321#322# Generate output file323#324 325my $title = $file_in;326$title =~ s,.*/,,;327 328open OUT, "> $file_out" or die "Can't open $file_out";329print OUT ".. -*- coding: utf-8; mode: rst -*-\n\n";330print OUT "$title\n";331print OUT "=" x length($title);332print OUT "\n\n.. parsed-literal::\n\n";333print OUT $data;334close OUT;335 336__END__337 338=head1 NAME339 340parse_headers.pl - parse a C file, in order to identify functions, structs,341enums and defines and create cross-references to a Sphinx book.342 343=head1 SYNOPSIS344 345B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]346 347Where <options> can be: --debug, --help or --usage.348 349=head1 OPTIONS350 351=over 8352 353=item B<--debug>354 355Put the script in verbose mode, useful for debugging.356 357=item B<--usage>358 359Prints a brief help message and exits.360 361=item B<--help>362 363Prints a more detailed help message and exits.364 365=back366 367=head1 DESCRIPTION368 369Convert a C header or source file (C_FILE), into a ReStructured Text370included via ..parsed-literal block with cross-references for the371documentation files that describe the API. It accepts an optional372EXCEPTIONS_FILE with describes what elements will be either ignored or373be pointed to a non-default reference.374 375The output is written at the (OUT_FILE).376 377It is capable of identifying defines, functions, structs, typedefs,378enums and enum symbols and create cross-references for all of them.379It is also capable of distinguish #define used for specifying a Linux380ioctl.381 382The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or383to replace the default references by a custom one.384 385Please read Documentation/doc-guide/parse-headers.rst at the Kernel's386tree for more details.387 388=head1 BUGS389 390Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org>391 392=head1 COPYRIGHT393 394Copyright (c) 2016 by Mauro Carvalho Chehab <mchehab+samsung@kernel.org>.395 396License GPLv2: GNU GPL version 2 <https://gnu.org/licenses/gpl.html>.397 398This is free software: you are free to change and redistribute it.399There is NO WARRANTY, to the extent permitted by law.400 401=cut402