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