1#!/usr/bin/env perl 2use 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' => \$man 15) 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 identifiers 35# 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 typedefs 121# 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 any 134# 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 symbol 151 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 symbol 178 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 block 239# 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 characters 248# 249$data =~ s,([\_\`\*\<\>\&\\\\:\/\|\%\$\#\{\}\~\^]),\\$1,g; 250 251$data =~ s,DEPRECATED,**DEPRECATED**,g; 252 253# 254# Add references 255# 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 file 323# 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 NAME 339 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 SYNOPSIS 344 345B<parse_headers.pl> [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>] 346 347Where <options> can be: --debug, --help or --usage. 348 349=head1 OPTIONS 350 351=over 8 352 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=back 366 367=head1 DESCRIPTION 368 369Convert a C header or source file (C_FILE), into a ReStructured Text 370included via ..parsed-literal block with cross-references for the 371documentation files that describe the API. It accepts an optional 372EXCEPTIONS_FILE with describes what elements will be either ignored or 373be 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 Linux 380ioctl. 381 382The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or 383to replace the default references by a custom one. 384 385Please read Documentation/doc-guide/parse-headers.rst at the Kernel's 386tree for more details. 387 388=head1 BUGS 389 390Report bugs to Mauro Carvalho Chehab <mchehab@kernel.org> 391 392=head1 COPYRIGHT 393 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=cut 402