blob: a325a0c890dc8e0a49ce4992ca4735ba5b5d1530 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## ##
9## #define enhancements by Armin Kuster <akuster@mvista.com> ##
10## Copyright (c) 2000 MontaVista Software, Inc. ##
11## ##
12## This software falls under the GNU General Public License. ##
13## Please read the COPYING file for more information ##
14
15# w.o. 03-11-2000: added the '-filelist' option.
16
17# 18/01/2001 - Cleanups
18# Functions prototyped as foo(void) same as foo()
19# Stop eval'ing where we don't need to.
20# -- huggie@earth.li
21
22# 27/06/2001 - Allowed whitespace after initial "/**" and
23# allowed comments before function declarations.
24# -- Christian Kreibich <ck@whoop.org>
25
26# Still to do:
27# - add perldoc documentation
28# - Look more closely at some of the scarier bits :)
29
30# 26/05/2001 - Support for separate source and object trees.
31# Return error code.
32# Keith Owens <kaos@ocs.com.au>
33
34# 23/09/2001 - Added support for typedefs, structs, enums and unions
35# Support for Context section; can be terminated using empty line
36# Small fixes (like spaces vs. \s in regex)
37# -- Tim Jansen <tim@tjansen.de>
38
39
40#
41# This will read a 'c' file and scan for embedded comments in the
42# style of gnome comments (+minor extensions - see below).
43#
44
45# Note: This only supports 'c'.
46
47# usage:
Randy Dunlapd28bee02006-02-01 03:06:57 -080048# kernel-doc [ -docbook | -html | -text | -man ]
Linus Torvalds1da177e2005-04-16 15:20:36 -070049# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
50# or
51# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
52#
53# Set output format using one of -docbook -html -text or -man. Default is man.
54#
55# -function funcname
56# If set, then only generate documentation for the given function(s). All
57# other functions are ignored.
58#
59# -nofunction funcname
Rolf Eike Beera073a8b2006-10-03 23:13:02 +020060# If set, then only generate documentation for the other function(s).
61# Cannot be used together with -function
Randy Dunlapd28bee02006-02-01 03:06:57 -080062# (yes, that's a bug -- perl hackers can fix it 8))
Linus Torvalds1da177e2005-04-16 15:20:36 -070063#
64# c files - list of 'c' files to process
65#
66# All output goes to stdout, with errors to stderr.
67
68#
69# format of comments.
70# In the following table, (...)? signifies optional structure.
71# (...)* signifies 0 or more structure elements
72# /**
73# * function_name(:)? (- short description)?
74# (* @parameterx: (description of parameter x)?)*
75# (* a blank line)?
76# * (Description:)? (Description of function)?
77# * (section header: (section description)? )*
78# (*)?*/
79#
80# So .. the trivial example would be:
81#
82# /**
83# * my_function
84# **/
85#
Randy Dunlap891dcd22007-02-10 01:45:53 -080086# If the Description: header tag is omitted, then there must be a blank line
Linus Torvalds1da177e2005-04-16 15:20:36 -070087# after the last parameter specification.
88# e.g.
89# /**
90# * my_function - does my stuff
91# * @my_arg: its mine damnit
92# *
Randy Dunlap3c3b8092006-02-01 03:06:58 -080093# * Does my stuff explained.
Linus Torvalds1da177e2005-04-16 15:20:36 -070094# */
95#
96# or, could also use:
97# /**
98# * my_function - does my stuff
99# * @my_arg: its mine damnit
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800100# * Description: Does my stuff explained.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101# */
102# etc.
103#
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800104# Beside functions you can also write documentation for structs, unions,
105# enums and typedefs. Instead of the function name you must write the name
106# of the declaration; the struct/union/enum/typedef must always precede
107# the name. Nesting of declarations is not supported.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700108# Use the argument mechanism to document members or constants.
109# e.g.
110# /**
111# * struct my_struct - short description
112# * @a: first member
113# * @b: second member
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800114# *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700115# * Longer description
116# */
117# struct my_struct {
118# int a;
119# int b;
Martin Waitzaeec46b2005-11-13 16:08:13 -0800120# /* private: */
121# int c;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700122# };
123#
124# All descriptions can be multiline, except the short function description.
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800125#
126# You can also add additional sections. When documenting kernel functions you
127# should document the "Context:" of the function, e.g. whether the functions
Linus Torvalds1da177e2005-04-16 15:20:36 -0700128# can be called form interrupts. Unlike other sections you can end it with an
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800129# empty line.
130# Example-sections should contain the string EXAMPLE so that they are marked
Linus Torvalds1da177e2005-04-16 15:20:36 -0700131# appropriately in DocBook.
132#
133# Example:
134# /**
135# * user_function - function that can only be called in user context
136# * @a: some argument
137# * Context: !in_interrupt()
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800138# *
Linus Torvalds1da177e2005-04-16 15:20:36 -0700139# * Some description
140# * Example:
141# * user_function(22);
142# */
143# ...
144#
145#
146# All descriptive text is further processed, scanning for the following special
147# patterns, which are highlighted appropriately.
148#
149# 'funcname()' - function
150# '$ENVVAR' - environmental variable
151# '&struct_name' - name of a structure (up to two words including 'struct')
152# '@parameter' - name of a parameter
153# '%CONST' - name of a constant.
154
155my $errors = 0;
156my $warnings = 0;
157
158# match expressions used to find embedded type information
159my $type_constant = '\%([-_\w]+)';
160my $type_func = '(\w+)\(\)';
161my $type_param = '\@(\w+)';
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700162my $type_struct = '\&((struct\s*)*[_\w]+)';
163my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700164my $type_env = '(\$\w+)';
165
166# Output conversion substitutions.
167# One for each output format
168
169# these work fairly well
170my %highlights_html = ( $type_constant, "<i>\$1</i>",
171 $type_func, "<b>\$1</b>",
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700172 $type_struct_xml, "<i>\$1</i>",
173 $type_env, "<b><i>\$1</i></b>",
Linus Torvalds1da177e2005-04-16 15:20:36 -0700174 $type_param, "<tt><b>\$1</b></tt>" );
175my $blankline_html = "<p>";
176
177# XML, docbook format
178my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
179 $type_constant, "<constant>\$1</constant>",
180 $type_func, "<function>\$1</function>",
181 $type_struct, "<structname>\$1</structname>",
182 $type_env, "<envar>\$1</envar>",
183 $type_param, "<parameter>\$1</parameter>" );
184my $blankline_xml = "</para><para>\n";
185
186# gnome, docbook format
187my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
188 $type_func, "<function>\$1</function>",
189 $type_struct, "<structname>\$1</structname>",
190 $type_env, "<envar>\$1</envar>",
191 $type_param, "<parameter>\$1</parameter>" );
192my $blankline_gnome = "</para><para>\n";
193
194# these are pretty rough
195my %highlights_man = ( $type_constant, "\$1",
196 $type_func, "\\\\fB\$1\\\\fP",
197 $type_struct, "\\\\fI\$1\\\\fP",
198 $type_param, "\\\\fI\$1\\\\fP" );
199my $blankline_man = "";
200
201# text-mode
202my %highlights_text = ( $type_constant, "\$1",
203 $type_func, "\$1",
204 $type_struct, "\$1",
205 $type_param, "\$1" );
206my $blankline_text = "";
207
208
209sub usage {
210 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ]\n";
211 print " [ -function funcname [ -function funcname ...] ]\n";
212 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
213 print " c source file(s) > outputfile\n";
214 exit 1;
215}
216
217# read arguments
218if ($#ARGV==-1) {
219 usage();
220}
221
222my $verbose = 0;
223my $output_mode = "man";
224my %highlights = %highlights_man;
225my $blankline = $blankline_man;
226my $modulename = "Kernel API";
227my $function_only = 0;
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800228my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
229 'July', 'August', 'September', 'October',
230 'November', 'December')[(localtime)[4]] .
Linus Torvalds1da177e2005-04-16 15:20:36 -0700231 " " . ((localtime)[5]+1900);
232
233# Essentially these are globals
234# They probably want to be tidied up made more localised or summat.
235# CAVEAT EMPTOR! Some of the others I localised may not want to be which
236# could cause "use of undefined value" or other bugs.
237my ($function, %function_table,%parametertypes,$declaration_purpose);
238my ($type,$declaration_name,$return_type);
239my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
240
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800241# Generated docbook code is inserted in a template at a point where
Linus Torvalds1da177e2005-04-16 15:20:36 -0700242# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
243# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
244# We keep track of number of generated entries and generate a dummy
245# if needs be to ensure the expanded template can be postprocessed
246# into html.
247my $section_counter = 0;
248
249my $lineprefix="";
250
251# states
252# 0 - normal code
253# 1 - looking for function name
254# 2 - scanning field start.
255# 3 - scanning prototype.
256# 4 - documentation block
257my $state;
Randy Dunlap850622d2006-06-25 05:48:55 -0700258my $in_doc_sect;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700259
260#declaration types: can be
261# 'function', 'struct', 'union', 'enum', 'typedef'
262my $decl_type;
263
264my $doc_special = "\@\%\$\&";
265
266my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
267my $doc_end = '\*/';
268my $doc_com = '\s*\*\s*';
269my $doc_decl = $doc_com.'(\w+)';
Randy Dunlap891dcd22007-02-10 01:45:53 -0800270my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
Linus Torvalds1da177e2005-04-16 15:20:36 -0700271my $doc_content = $doc_com.'(.*)';
272my $doc_block = $doc_com.'DOC:\s*(.*)?';
273
274my %constants;
275my %parameterdescs;
276my @parameterlist;
277my %sections;
278my @sectionlist;
279
280my $contents = "";
281my $section_default = "Description"; # default section
282my $section_intro = "Introduction";
283my $section = $section_default;
284my $section_context = "Context";
285
286my $undescribed = "-- undescribed --";
287
288reset_state();
289
290while ($ARGV[0] =~ m/^-(.*)/) {
291 my $cmd = shift @ARGV;
292 if ($cmd eq "-html") {
293 $output_mode = "html";
294 %highlights = %highlights_html;
295 $blankline = $blankline_html;
296 } elsif ($cmd eq "-man") {
297 $output_mode = "man";
298 %highlights = %highlights_man;
299 $blankline = $blankline_man;
300 } elsif ($cmd eq "-text") {
301 $output_mode = "text";
302 %highlights = %highlights_text;
303 $blankline = $blankline_text;
304 } elsif ($cmd eq "-docbook") {
305 $output_mode = "xml";
306 %highlights = %highlights_xml;
307 $blankline = $blankline_xml;
308 } elsif ($cmd eq "-gnome") {
309 $output_mode = "gnome";
310 %highlights = %highlights_gnome;
311 $blankline = $blankline_gnome;
312 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
313 $modulename = shift @ARGV;
314 } elsif ($cmd eq "-function") { # to only output specific functions
315 $function_only = 1;
316 $function = shift @ARGV;
317 $function_table{$function} = 1;
318 } elsif ($cmd eq "-nofunction") { # to only output specific functions
319 $function_only = 2;
320 $function = shift @ARGV;
321 $function_table{$function} = 1;
322 } elsif ($cmd eq "-v") {
323 $verbose = 1;
324 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
325 usage();
326 } elsif ($cmd eq '-filelist') {
327 $filelist = shift @ARGV;
328 }
329}
330
Borislav Petkov53f049f2007-05-08 00:30:54 -0700331# get kernel version from env
332sub get_kernel_version() {
333 my $version;
334
335 if (defined($ENV{'KERNELVERSION'})) {
336 $version = $ENV{'KERNELVERSION'};
337 }
338 return $version;
339}
Linus Torvalds1da177e2005-04-16 15:20:36 -0700340
341# generate a sequence of code that will splice in highlighting information
342# using the s// operator.
343my $dohighlight = "";
344foreach my $pattern (keys %highlights) {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700345# print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700346 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
347}
348
349##
350# dumps section contents to arrays/hashes intended for that purpose.
351#
352sub dump_section {
353 my $name = shift;
354 my $contents = join "\n", @_;
355
356 if ($name =~ m/$type_constant/) {
357 $name = $1;
358# print STDERR "constant section '$1' = '$contents'\n";
359 $constants{$name} = $contents;
360 } elsif ($name =~ m/$type_param/) {
361# print STDERR "parameter def '$1' = '$contents'\n";
362 $name = $1;
363 $parameterdescs{$name} = $contents;
364 } else {
365# print STDERR "other section '$name' = '$contents'\n";
366 $sections{$name} = $contents;
367 push @sectionlist, $name;
368 }
369}
370
371##
372# output function
373#
374# parameterdescs, a hash.
375# function => "function name"
376# parameterlist => @list of parameters
377# parameterdescs => %parameter descriptions
378# sectionlist => @list of sections
Randy Dunlapa21217d2007-02-10 01:46:04 -0800379# sections => %section descriptions
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800380#
Linus Torvalds1da177e2005-04-16 15:20:36 -0700381
382sub output_highlight {
383 my $contents = join "\n",@_;
384 my $line;
385
386# DEBUG
387# if (!defined $contents) {
388# use Carp;
389# confess "output_highlight got called with no args?\n";
390# }
391
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700392# print STDERR "contents b4:$contents\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700393 eval $dohighlight;
394 die $@ if $@;
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700395 if ($output_mode eq "html") {
396 $contents =~ s/\\\\//;
397 }
398# print STDERR "contents af:$contents\n";
399
Linus Torvalds1da177e2005-04-16 15:20:36 -0700400 foreach $line (split "\n", $contents) {
Randy Dunlap3c308792007-05-08 00:24:39 -0700401 if ($line eq ""){
Linus Torvalds1da177e2005-04-16 15:20:36 -0700402 print $lineprefix, $blankline;
403 } else {
Randy Dunlap3c308792007-05-08 00:24:39 -0700404 $line =~ s/\\\\\\/\&/g;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700405 print $lineprefix, $line;
406 }
407 print "\n";
408 }
409}
410
411#output sections in html
412sub output_section_html(%) {
413 my %args = %{$_[0]};
414 my $section;
415
416 foreach $section (@{$args{'sectionlist'}}) {
417 print "<h3>$section</h3>\n";
418 print "<blockquote>\n";
419 output_highlight($args{'sections'}{$section});
420 print "</blockquote>\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800421 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700422}
423
424# output enum in html
425sub output_enum_html(%) {
426 my %args = %{$_[0]};
427 my ($parameter);
428 my $count;
429 print "<h2>enum ".$args{'enum'}."</h2>\n";
430
431 print "<b>enum ".$args{'enum'}."</b> {<br>\n";
432 $count = 0;
433 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -0700434 print " <b>".$parameter."</b>";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700435 if ($count != $#{$args{'parameterlist'}}) {
436 $count++;
437 print ",\n";
438 }
439 print "<br>";
440 }
441 print "};<br>\n";
442
443 print "<h3>Constants</h3>\n";
444 print "<dl>\n";
445 foreach $parameter (@{$args{'parameterlist'}}) {
446 print "<dt><b>".$parameter."</b>\n";
447 print "<dd>";
448 output_highlight($args{'parameterdescs'}{$parameter});
449 }
450 print "</dl>\n";
451 output_section_html(@_);
452 print "<hr>\n";
453}
454
Randy Dunlapd28bee02006-02-01 03:06:57 -0800455# output typedef in html
Linus Torvalds1da177e2005-04-16 15:20:36 -0700456sub output_typedef_html(%) {
457 my %args = %{$_[0]};
458 my ($parameter);
459 my $count;
460 print "<h2>typedef ".$args{'typedef'}."</h2>\n";
461
462 print "<b>typedef ".$args{'typedef'}."</b>\n";
463 output_section_html(@_);
464 print "<hr>\n";
465}
466
467# output struct in html
468sub output_struct_html(%) {
469 my %args = %{$_[0]};
470 my ($parameter);
471
Randy Dunlap262d9b02007-02-20 13:58:04 -0800472 print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700473 print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
474 foreach $parameter (@{$args{'parameterlist'}}) {
475 if ($parameter =~ /^#/) {
476 print "$parameter<br>\n";
477 next;
478 }
479 my $parameter_name = $parameter;
480 $parameter_name =~ s/\[.*//;
481
Randy Dunlap3c308792007-05-08 00:24:39 -0700482 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700483 $type = $args{'parametertypes'}{$parameter};
484 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
485 # pointer-to-function
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700486 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700487 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700488 # bitfield
489 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700490 } else {
Randy Dunlap3eb014a2007-05-08 00:29:51 -0700491 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700492 }
493 }
494 print "};<br>\n";
495
496 print "<h3>Members</h3>\n";
497 print "<dl>\n";
498 foreach $parameter (@{$args{'parameterlist'}}) {
499 ($parameter =~ /^#/) && next;
500
501 my $parameter_name = $parameter;
502 $parameter_name =~ s/\[.*//;
503
Randy Dunlap3c308792007-05-08 00:24:39 -0700504 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700505 print "<dt><b>".$parameter."</b>\n";
506 print "<dd>";
507 output_highlight($args{'parameterdescs'}{$parameter_name});
508 }
509 print "</dl>\n";
510 output_section_html(@_);
511 print "<hr>\n";
512}
513
514# output function in html
515sub output_function_html(%) {
516 my %args = %{$_[0]};
517 my ($parameter, $section);
518 my $count;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700519
Randy Dunlap262d9b02007-02-20 13:58:04 -0800520 print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700521 print "<i>".$args{'functiontype'}."</i>\n";
522 print "<b>".$args{'function'}."</b>\n";
523 print "(";
524 $count = 0;
525 foreach $parameter (@{$args{'parameterlist'}}) {
526 $type = $args{'parametertypes'}{$parameter};
527 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
528 # pointer-to-function
529 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
530 } else {
531 print "<i>".$type."</i> <b>".$parameter."</b>";
532 }
533 if ($count != $#{$args{'parameterlist'}}) {
534 $count++;
535 print ",\n";
536 }
537 }
538 print ")\n";
539
540 print "<h3>Arguments</h3>\n";
541 print "<dl>\n";
542 foreach $parameter (@{$args{'parameterlist'}}) {
543 my $parameter_name = $parameter;
544 $parameter_name =~ s/\[.*//;
545
Randy Dunlap3c308792007-05-08 00:24:39 -0700546 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700547 print "<dt><b>".$parameter."</b>\n";
548 print "<dd>";
549 output_highlight($args{'parameterdescs'}{$parameter_name});
550 }
551 print "</dl>\n";
552 output_section_html(@_);
553 print "<hr>\n";
554}
555
556# output intro in html
557sub output_intro_html(%) {
558 my %args = %{$_[0]};
559 my ($parameter, $section);
560 my $count;
561
562 foreach $section (@{$args{'sectionlist'}}) {
563 print "<h3>$section</h3>\n";
564 print "<ul>\n";
565 output_highlight($args{'sections'}{$section});
566 print "</ul>\n";
567 }
568 print "<hr>\n";
569}
570
571sub output_section_xml(%) {
572 my %args = %{$_[0]};
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800573 my $section;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700574 # print out each section
575 $lineprefix=" ";
576 foreach $section (@{$args{'sectionlist'}}) {
Rich Walkerc73894c2005-05-01 08:59:26 -0700577 print "<refsect1>\n";
578 print "<title>$section</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700579 if ($section =~ m/EXAMPLE/i) {
Rich Walkerc73894c2005-05-01 08:59:26 -0700580 print "<informalexample><programlisting>\n";
581 } else {
582 print "<para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700583 }
584 output_highlight($args{'sections'}{$section});
585 if ($section =~ m/EXAMPLE/i) {
Rich Walkerc73894c2005-05-01 08:59:26 -0700586 print "</programlisting></informalexample>\n";
587 } else {
588 print "</para>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700589 }
Rich Walkerc73894c2005-05-01 08:59:26 -0700590 print "</refsect1>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700591 }
592}
593
594# output function in XML DocBook
595sub output_function_xml(%) {
596 my %args = %{$_[0]};
597 my ($parameter, $section);
598 my $count;
599 my $id;
600
601 $id = "API-".$args{'function'};
602 $id =~ s/[^A-Za-z0-9]/-/g;
603
Pavel Pisa5449bc92007-02-10 01:45:37 -0800604 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700605 print "<refentryinfo>\n";
606 print " <title>LINUX</title>\n";
607 print " <productname>Kernel Hackers Manual</productname>\n";
608 print " <date>$man_date</date>\n";
609 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700610 print "<refmeta>\n";
Pavel Pisa5449bc92007-02-10 01:45:37 -0800611 print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700612 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov53f049f2007-05-08 00:30:54 -0700613 print " <refmiscinfo class=\"version\">" . get_kernel_version() . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700614 print "</refmeta>\n";
615 print "<refnamediv>\n";
616 print " <refname>".$args{'function'}."</refname>\n";
617 print " <refpurpose>\n";
618 print " ";
619 output_highlight ($args{'purpose'});
620 print " </refpurpose>\n";
621 print "</refnamediv>\n";
622
623 print "<refsynopsisdiv>\n";
624 print " <title>Synopsis</title>\n";
625 print " <funcsynopsis><funcprototype>\n";
626 print " <funcdef>".$args{'functiontype'}." ";
627 print "<function>".$args{'function'}." </function></funcdef>\n";
628
629 $count = 0;
630 if ($#{$args{'parameterlist'}} >= 0) {
631 foreach $parameter (@{$args{'parameterlist'}}) {
632 $type = $args{'parametertypes'}{$parameter};
633 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
634 # pointer-to-function
635 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
636 print " <funcparams>$2</funcparams></paramdef>\n";
637 } else {
638 print " <paramdef>".$type;
639 print " <parameter>$parameter</parameter></paramdef>\n";
640 }
641 }
642 } else {
Martin Waitz6013d542005-05-01 08:59:25 -0700643 print " <void/>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700644 }
645 print " </funcprototype></funcsynopsis>\n";
646 print "</refsynopsisdiv>\n";
647
648 # print parameters
649 print "<refsect1>\n <title>Arguments</title>\n";
650 if ($#{$args{'parameterlist'}} >= 0) {
651 print " <variablelist>\n";
652 foreach $parameter (@{$args{'parameterlist'}}) {
653 my $parameter_name = $parameter;
654 $parameter_name =~ s/\[.*//;
655
656 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
657 print " <listitem>\n <para>\n";
658 $lineprefix=" ";
659 output_highlight($args{'parameterdescs'}{$parameter_name});
660 print " </para>\n </listitem>\n </varlistentry>\n";
661 }
662 print " </variablelist>\n";
663 } else {
664 print " <para>\n None\n </para>\n";
665 }
666 print "</refsect1>\n";
667
668 output_section_xml(@_);
669 print "</refentry>\n\n";
670}
671
672# output struct in XML DocBook
673sub output_struct_xml(%) {
674 my %args = %{$_[0]};
675 my ($parameter, $section);
676 my $id;
677
678 $id = "API-struct-".$args{'struct'};
679 $id =~ s/[^A-Za-z0-9]/-/g;
680
Pavel Pisa5449bc92007-02-10 01:45:37 -0800681 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700682 print "<refentryinfo>\n";
683 print " <title>LINUX</title>\n";
684 print " <productname>Kernel Hackers Manual</productname>\n";
685 print " <date>$man_date</date>\n";
686 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700687 print "<refmeta>\n";
Pavel Pisa5449bc92007-02-10 01:45:37 -0800688 print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700689 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov53f049f2007-05-08 00:30:54 -0700690 print " <refmiscinfo class=\"version\">" . get_kernel_version() . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700691 print "</refmeta>\n";
692 print "<refnamediv>\n";
693 print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
694 print " <refpurpose>\n";
695 print " ";
696 output_highlight ($args{'purpose'});
697 print " </refpurpose>\n";
698 print "</refnamediv>\n";
699
700 print "<refsynopsisdiv>\n";
701 print " <title>Synopsis</title>\n";
702 print " <programlisting>\n";
703 print $args{'type'}." ".$args{'struct'}." {\n";
704 foreach $parameter (@{$args{'parameterlist'}}) {
705 if ($parameter =~ /^#/) {
706 print "$parameter\n";
707 next;
708 }
709
710 my $parameter_name = $parameter;
711 $parameter_name =~ s/\[.*//;
712
713 defined($args{'parameterdescs'}{$parameter_name}) || next;
Randy Dunlap3c308792007-05-08 00:24:39 -0700714 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -0700715 $type = $args{'parametertypes'}{$parameter};
716 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
717 # pointer-to-function
718 print " $1 $parameter) ($2);\n";
719 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
720 print " $1 $parameter$2;\n";
721 } else {
722 print " ".$type." ".$parameter.";\n";
723 }
724 }
725 print "};";
726 print " </programlisting>\n";
727 print "</refsynopsisdiv>\n";
728
729 print " <refsect1>\n";
730 print " <title>Members</title>\n";
731
732 print " <variablelist>\n";
733 foreach $parameter (@{$args{'parameterlist'}}) {
734 ($parameter =~ /^#/) && next;
735
736 my $parameter_name = $parameter;
737 $parameter_name =~ s/\[.*//;
738
739 defined($args{'parameterdescs'}{$parameter_name}) || next;
740 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
741 print " <varlistentry>";
742 print " <term>$parameter</term>\n";
743 print " <listitem><para>\n";
744 output_highlight($args{'parameterdescs'}{$parameter_name});
745 print " </para></listitem>\n";
746 print " </varlistentry>\n";
747 }
748 print " </variablelist>\n";
749 print " </refsect1>\n";
750
751 output_section_xml(@_);
752
753 print "</refentry>\n\n";
754}
755
756# output enum in XML DocBook
757sub output_enum_xml(%) {
758 my %args = %{$_[0]};
759 my ($parameter, $section);
760 my $count;
761 my $id;
762
763 $id = "API-enum-".$args{'enum'};
764 $id =~ s/[^A-Za-z0-9]/-/g;
765
Pavel Pisa5449bc92007-02-10 01:45:37 -0800766 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700767 print "<refentryinfo>\n";
768 print " <title>LINUX</title>\n";
769 print " <productname>Kernel Hackers Manual</productname>\n";
770 print " <date>$man_date</date>\n";
771 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700772 print "<refmeta>\n";
Pavel Pisa5449bc92007-02-10 01:45:37 -0800773 print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700774 print " <manvolnum>9</manvolnum>\n";
Borislav Petkov53f049f2007-05-08 00:30:54 -0700775 print " <refmiscinfo class=\"version\">" . get_kernel_version() . "</refmiscinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700776 print "</refmeta>\n";
777 print "<refnamediv>\n";
778 print " <refname>enum ".$args{'enum'}."</refname>\n";
779 print " <refpurpose>\n";
780 print " ";
781 output_highlight ($args{'purpose'});
782 print " </refpurpose>\n";
783 print "</refnamediv>\n";
784
785 print "<refsynopsisdiv>\n";
786 print " <title>Synopsis</title>\n";
787 print " <programlisting>\n";
788 print "enum ".$args{'enum'}." {\n";
789 $count = 0;
790 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -0700791 print " $parameter";
792 if ($count != $#{$args{'parameterlist'}}) {
Linus Torvalds1da177e2005-04-16 15:20:36 -0700793 $count++;
794 print ",";
Randy Dunlap3c308792007-05-08 00:24:39 -0700795 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700796 print "\n";
797 }
798 print "};";
799 print " </programlisting>\n";
800 print "</refsynopsisdiv>\n";
801
802 print "<refsect1>\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -0800803 print " <title>Constants</title>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700804 print " <variablelist>\n";
805 foreach $parameter (@{$args{'parameterlist'}}) {
806 my $parameter_name = $parameter;
807 $parameter_name =~ s/\[.*//;
808
809 print " <varlistentry>";
810 print " <term>$parameter</term>\n";
811 print " <listitem><para>\n";
812 output_highlight($args{'parameterdescs'}{$parameter_name});
813 print " </para></listitem>\n";
814 print " </varlistentry>\n";
815 }
816 print " </variablelist>\n";
817 print "</refsect1>\n";
818
819 output_section_xml(@_);
820
821 print "</refentry>\n\n";
822}
823
824# output typedef in XML DocBook
825sub output_typedef_xml(%) {
826 my %args = %{$_[0]};
827 my ($parameter, $section);
828 my $id;
829
830 $id = "API-typedef-".$args{'typedef'};
831 $id =~ s/[^A-Za-z0-9]/-/g;
832
Pavel Pisa5449bc92007-02-10 01:45:37 -0800833 print "<refentry id=\"$id\">\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700834 print "<refentryinfo>\n";
835 print " <title>LINUX</title>\n";
836 print " <productname>Kernel Hackers Manual</productname>\n";
837 print " <date>$man_date</date>\n";
838 print "</refentryinfo>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700839 print "<refmeta>\n";
Pavel Pisa5449bc92007-02-10 01:45:37 -0800840 print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
Martin Waitz8b0c2d92005-05-01 08:59:27 -0700841 print " <manvolnum>9</manvolnum>\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -0700842 print "</refmeta>\n";
843 print "<refnamediv>\n";
844 print " <refname>typedef ".$args{'typedef'}."</refname>\n";
845 print " <refpurpose>\n";
846 print " ";
847 output_highlight ($args{'purpose'});
848 print " </refpurpose>\n";
849 print "</refnamediv>\n";
850
851 print "<refsynopsisdiv>\n";
852 print " <title>Synopsis</title>\n";
853 print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
854 print "</refsynopsisdiv>\n";
855
856 output_section_xml(@_);
857
858 print "</refentry>\n\n";
859}
860
861# output in XML DocBook
862sub output_intro_xml(%) {
863 my %args = %{$_[0]};
864 my ($parameter, $section);
865 my $count;
866
867 my $id = $args{'module'};
868 $id =~ s/[^A-Za-z0-9]/-/g;
869
870 # print out each section
871 $lineprefix=" ";
872 foreach $section (@{$args{'sectionlist'}}) {
873 print "<refsect1>\n <title>$section</title>\n <para>\n";
874 if ($section =~ m/EXAMPLE/i) {
875 print "<example><para>\n";
876 }
877 output_highlight($args{'sections'}{$section});
878 if ($section =~ m/EXAMPLE/i) {
879 print "</para></example>\n";
880 }
881 print " </para>\n</refsect1>\n";
882 }
883
884 print "\n\n";
885}
886
887# output in XML DocBook
888sub output_function_gnome {
889 my %args = %{$_[0]};
890 my ($parameter, $section);
891 my $count;
892 my $id;
893
894 $id = $args{'module'}."-".$args{'function'};
895 $id =~ s/[^A-Za-z0-9]/-/g;
896
897 print "<sect2>\n";
898 print " <title id=\"$id\">".$args{'function'}."</title>\n";
899
900 print " <funcsynopsis>\n";
901 print " <funcdef>".$args{'functiontype'}." ";
902 print "<function>".$args{'function'}." ";
903 print "</function></funcdef>\n";
904
905 $count = 0;
906 if ($#{$args{'parameterlist'}} >= 0) {
907 foreach $parameter (@{$args{'parameterlist'}}) {
908 $type = $args{'parametertypes'}{$parameter};
909 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
910 # pointer-to-function
911 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
912 print " <funcparams>$2</funcparams></paramdef>\n";
913 } else {
914 print " <paramdef>".$type;
915 print " <parameter>$parameter</parameter></paramdef>\n";
916 }
917 }
918 } else {
919 print " <void>\n";
920 }
921 print " </funcsynopsis>\n";
922 if ($#{$args{'parameterlist'}} >= 0) {
923 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
924 print "<tgroup cols=\"2\">\n";
925 print "<colspec colwidth=\"2*\">\n";
926 print "<colspec colwidth=\"8*\">\n";
927 print "<tbody>\n";
928 foreach $parameter (@{$args{'parameterlist'}}) {
929 my $parameter_name = $parameter;
930 $parameter_name =~ s/\[.*//;
931
932 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
933 print " <entry>\n";
934 $lineprefix=" ";
935 output_highlight($args{'parameterdescs'}{$parameter_name});
936 print " </entry></row>\n";
937 }
938 print " </tbody></tgroup></informaltable>\n";
939 } else {
940 print " <para>\n None\n </para>\n";
941 }
942
943 # print out each section
944 $lineprefix=" ";
945 foreach $section (@{$args{'sectionlist'}}) {
946 print "<simplesect>\n <title>$section</title>\n";
947 if ($section =~ m/EXAMPLE/i) {
948 print "<example><programlisting>\n";
949 } else {
950 }
951 print "<para>\n";
952 output_highlight($args{'sections'}{$section});
953 print "</para>\n";
954 if ($section =~ m/EXAMPLE/i) {
955 print "</programlisting></example>\n";
956 } else {
957 }
958 print " </simplesect>\n";
959 }
960
961 print "</sect2>\n\n";
962}
963
964##
965# output function in man
966sub output_function_man(%) {
967 my %args = %{$_[0]};
968 my ($parameter, $section);
969 my $count;
970
971 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
972
973 print ".SH NAME\n";
974 print $args{'function'}." \\- ".$args{'purpose'}."\n";
975
976 print ".SH SYNOPSIS\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -0800977 if ($args{'functiontype'} ne "") {
978 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
979 } else {
980 print ".B \"".$args{'function'}."\n";
981 }
Linus Torvalds1da177e2005-04-16 15:20:36 -0700982 $count = 0;
983 my $parenth = "(";
984 my $post = ",";
985 foreach my $parameter (@{$args{'parameterlist'}}) {
986 if ($count == $#{$args{'parameterlist'}}) {
987 $post = ");";
988 }
989 $type = $args{'parametertypes'}{$parameter};
990 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
991 # pointer-to-function
992 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
993 } else {
994 $type =~ s/([^\*])$/$1 /;
995 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
996 }
997 $count++;
998 $parenth = "";
999 }
1000
1001 print ".SH ARGUMENTS\n";
1002 foreach $parameter (@{$args{'parameterlist'}}) {
1003 my $parameter_name = $parameter;
1004 $parameter_name =~ s/\[.*//;
1005
1006 print ".IP \"".$parameter."\" 12\n";
1007 output_highlight($args{'parameterdescs'}{$parameter_name});
1008 }
1009 foreach $section (@{$args{'sectionlist'}}) {
1010 print ".SH \"", uc $section, "\"\n";
1011 output_highlight($args{'sections'}{$section});
1012 }
1013}
1014
1015##
1016# output enum in man
1017sub output_enum_man(%) {
1018 my %args = %{$_[0]};
1019 my ($parameter, $section);
1020 my $count;
1021
1022 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1023
1024 print ".SH NAME\n";
1025 print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
1026
1027 print ".SH SYNOPSIS\n";
1028 print "enum ".$args{'enum'}." {\n";
1029 $count = 0;
1030 foreach my $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001031 print ".br\n.BI \" $parameter\"\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001032 if ($count == $#{$args{'parameterlist'}}) {
1033 print "\n};\n";
1034 last;
1035 }
1036 else {
1037 print ", \n.br\n";
1038 }
1039 $count++;
1040 }
1041
1042 print ".SH Constants\n";
1043 foreach $parameter (@{$args{'parameterlist'}}) {
1044 my $parameter_name = $parameter;
1045 $parameter_name =~ s/\[.*//;
1046
1047 print ".IP \"".$parameter."\" 12\n";
1048 output_highlight($args{'parameterdescs'}{$parameter_name});
1049 }
1050 foreach $section (@{$args{'sectionlist'}}) {
1051 print ".SH \"$section\"\n";
1052 output_highlight($args{'sections'}{$section});
1053 }
1054}
1055
1056##
1057# output struct in man
1058sub output_struct_man(%) {
1059 my %args = %{$_[0]};
1060 my ($parameter, $section);
1061
1062 print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
1063
1064 print ".SH NAME\n";
1065 print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
1066
1067 print ".SH SYNOPSIS\n";
1068 print $args{'type'}." ".$args{'struct'}." {\n.br\n";
1069
1070 foreach my $parameter (@{$args{'parameterlist'}}) {
1071 if ($parameter =~ /^#/) {
1072 print ".BI \"$parameter\"\n.br\n";
1073 next;
1074 }
1075 my $parameter_name = $parameter;
1076 $parameter_name =~ s/\[.*//;
1077
Randy Dunlap3c308792007-05-08 00:24:39 -07001078 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001079 $type = $args{'parametertypes'}{$parameter};
1080 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1081 # pointer-to-function
1082 print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
1083 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
Randy.Dunlap1d7e1d42006-07-01 04:36:34 -07001084 # bitfield
1085 print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001086 } else {
1087 $type =~ s/([^\*])$/$1 /;
1088 print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";
1089 }
1090 print "\n.br\n";
1091 }
1092 print "};\n.br\n";
1093
Randy Dunlapc51d3da2006-06-25 05:49:14 -07001094 print ".SH Members\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001095 foreach $parameter (@{$args{'parameterlist'}}) {
1096 ($parameter =~ /^#/) && next;
1097
1098 my $parameter_name = $parameter;
1099 $parameter_name =~ s/\[.*//;
1100
Randy Dunlap3c308792007-05-08 00:24:39 -07001101 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001102 print ".IP \"".$parameter."\" 12\n";
1103 output_highlight($args{'parameterdescs'}{$parameter_name});
1104 }
1105 foreach $section (@{$args{'sectionlist'}}) {
1106 print ".SH \"$section\"\n";
1107 output_highlight($args{'sections'}{$section});
1108 }
1109}
1110
1111##
1112# output typedef in man
1113sub output_typedef_man(%) {
1114 my %args = %{$_[0]};
1115 my ($parameter, $section);
1116
1117 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1118
1119 print ".SH NAME\n";
1120 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1121
1122 foreach $section (@{$args{'sectionlist'}}) {
1123 print ".SH \"$section\"\n";
1124 output_highlight($args{'sections'}{$section});
1125 }
1126}
1127
1128sub output_intro_man(%) {
1129 my %args = %{$_[0]};
1130 my ($parameter, $section);
1131 my $count;
1132
1133 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1134
1135 foreach $section (@{$args{'sectionlist'}}) {
1136 print ".SH \"$section\"\n";
1137 output_highlight($args{'sections'}{$section});
1138 }
1139}
1140
1141##
1142# output in text
1143sub output_function_text(%) {
1144 my %args = %{$_[0]};
1145 my ($parameter, $section);
Randy Dunlapa21217d2007-02-10 01:46:04 -08001146 my $start;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001147
Randy Dunlapf47634b2006-07-01 04:36:36 -07001148 print "Name:\n\n";
1149 print $args{'function'}." - ".$args{'purpose'}."\n";
1150
1151 print "\nSynopsis:\n\n";
Randy Dunlapa21217d2007-02-10 01:46:04 -08001152 if ($args{'functiontype'} ne "") {
1153 $start = $args{'functiontype'}." ".$args{'function'}." (";
1154 } else {
1155 $start = $args{'function'}." (";
1156 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001157 print $start;
Randy Dunlapa21217d2007-02-10 01:46:04 -08001158
Linus Torvalds1da177e2005-04-16 15:20:36 -07001159 my $count = 0;
1160 foreach my $parameter (@{$args{'parameterlist'}}) {
1161 $type = $args{'parametertypes'}{$parameter};
1162 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1163 # pointer-to-function
1164 print $1.$parameter.") (".$2;
1165 } else {
1166 print $type." ".$parameter;
1167 }
1168 if ($count != $#{$args{'parameterlist'}}) {
1169 $count++;
1170 print ",\n";
1171 print " " x length($start);
1172 } else {
1173 print ");\n\n";
1174 }
1175 }
1176
1177 print "Arguments:\n\n";
1178 foreach $parameter (@{$args{'parameterlist'}}) {
1179 my $parameter_name = $parameter;
1180 $parameter_name =~ s/\[.*//;
1181
1182 print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
1183 }
1184 output_section_text(@_);
1185}
1186
1187#output sections in text
1188sub output_section_text(%) {
1189 my %args = %{$_[0]};
1190 my $section;
1191
1192 print "\n";
1193 foreach $section (@{$args{'sectionlist'}}) {
1194 print "$section:\n\n";
1195 output_highlight($args{'sections'}{$section});
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001196 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001197 print "\n\n";
1198}
1199
1200# output enum in text
1201sub output_enum_text(%) {
1202 my %args = %{$_[0]};
1203 my ($parameter);
1204 my $count;
1205 print "Enum:\n\n";
1206
Randy.Dunlap1d7e1d42006-07-01 04:36:34 -07001207 print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001208 print "enum ".$args{'enum'}." {\n";
1209 $count = 0;
1210 foreach $parameter (@{$args{'parameterlist'}}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001211 print "\t$parameter";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001212 if ($count != $#{$args{'parameterlist'}}) {
1213 $count++;
1214 print ",";
1215 }
1216 print "\n";
1217 }
1218 print "};\n\n";
1219
1220 print "Constants:\n\n";
1221 foreach $parameter (@{$args{'parameterlist'}}) {
1222 print "$parameter\n\t";
1223 print $args{'parameterdescs'}{$parameter}."\n";
1224 }
1225
1226 output_section_text(@_);
1227}
1228
1229# output typedef in text
1230sub output_typedef_text(%) {
1231 my %args = %{$_[0]};
1232 my ($parameter);
1233 my $count;
1234 print "Typedef:\n\n";
1235
Randy.Dunlap1d7e1d42006-07-01 04:36:34 -07001236 print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001237 output_section_text(@_);
1238}
1239
1240# output struct as text
1241sub output_struct_text(%) {
1242 my %args = %{$_[0]};
1243 my ($parameter);
1244
Randy.Dunlap1d7e1d42006-07-01 04:36:34 -07001245 print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001246 print $args{'type'}." ".$args{'struct'}." {\n";
1247 foreach $parameter (@{$args{'parameterlist'}}) {
1248 if ($parameter =~ /^#/) {
1249 print "$parameter\n";
1250 next;
1251 }
1252
1253 my $parameter_name = $parameter;
1254 $parameter_name =~ s/\[.*//;
1255
Randy Dunlap3c308792007-05-08 00:24:39 -07001256 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001257 $type = $args{'parametertypes'}{$parameter};
1258 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1259 # pointer-to-function
1260 print "\t$1 $parameter) ($2);\n";
1261 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1262 print "\t$1 $parameter$2;\n";
1263 } else {
1264 print "\t".$type." ".$parameter.";\n";
1265 }
1266 }
1267 print "};\n\n";
1268
1269 print "Members:\n\n";
1270 foreach $parameter (@{$args{'parameterlist'}}) {
1271 ($parameter =~ /^#/) && next;
1272
1273 my $parameter_name = $parameter;
1274 $parameter_name =~ s/\[.*//;
1275
Randy Dunlap3c308792007-05-08 00:24:39 -07001276 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001277 print "$parameter\n\t";
1278 print $args{'parameterdescs'}{$parameter_name}."\n";
1279 }
1280 print "\n";
1281 output_section_text(@_);
1282}
1283
1284sub output_intro_text(%) {
1285 my %args = %{$_[0]};
1286 my ($parameter, $section);
1287
1288 foreach $section (@{$args{'sectionlist'}}) {
1289 print " $section:\n";
1290 print " -> ";
1291 output_highlight($args{'sections'}{$section});
1292 }
1293}
1294
1295##
Randy Dunlap27205742006-10-11 01:22:12 -07001296# generic output function for all types (function, struct/union, typedef, enum);
1297# calls the generated, variable output_ function name based on
1298# functype and output_mode
Linus Torvalds1da177e2005-04-16 15:20:36 -07001299sub output_declaration {
1300 no strict 'refs';
1301 my $name = shift;
1302 my $functype = shift;
1303 my $func = "output_${functype}_$output_mode";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001304 if (($function_only==0) ||
1305 ( $function_only == 1 && defined($function_table{$name})) ||
Linus Torvalds1da177e2005-04-16 15:20:36 -07001306 ( $function_only == 2 && !defined($function_table{$name})))
1307 {
Randy Dunlap3c308792007-05-08 00:24:39 -07001308 &$func(@_);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001309 $section_counter++;
1310 }
1311}
1312
1313##
Randy Dunlap27205742006-10-11 01:22:12 -07001314# generic output function - calls the right one based on current output mode.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001315sub output_intro {
1316 no strict 'refs';
1317 my $func = "output_intro_".$output_mode;
1318 &$func(@_);
1319 $section_counter++;
1320}
1321
1322##
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001323# takes a declaration (struct, union, enum, typedef) and
Linus Torvalds1da177e2005-04-16 15:20:36 -07001324# invokes the right handler. NOT called for functions.
1325sub dump_declaration($$) {
1326 no strict 'refs';
1327 my ($prototype, $file) = @_;
1328 my $func = "dump_".$decl_type;
1329 &$func(@_);
1330}
1331
1332sub dump_union($$) {
1333 dump_struct(@_);
1334}
1335
1336sub dump_struct($$) {
1337 my $x = shift;
1338 my $file = shift;
1339
1340 if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001341 $declaration_name = $2;
1342 my $members = $3;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001343
1344 # ignore embedded structs or unions
1345 $members =~ s/{.*?}//g;
1346
Martin Waitzaeec46b2005-11-13 16:08:13 -08001347 # ignore members marked private:
1348 $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
1349 $members =~ s/\/\*.*?private:.*//gos;
1350 # strip comments:
1351 $members =~ s/\/\*.*?\*\///gos;
1352
Linus Torvalds1da177e2005-04-16 15:20:36 -07001353 create_parameterlist($members, ';', $file);
1354
1355 output_declaration($declaration_name,
1356 'struct',
1357 {'struct' => $declaration_name,
1358 'module' => $modulename,
1359 'parameterlist' => \@parameterlist,
1360 'parameterdescs' => \%parameterdescs,
1361 'parametertypes' => \%parametertypes,
1362 'sectionlist' => \@sectionlist,
1363 'sections' => \%sections,
1364 'purpose' => $declaration_purpose,
1365 'type' => $decl_type
1366 });
1367 }
1368 else {
Randy Dunlap3c308792007-05-08 00:24:39 -07001369 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001370 ++$errors;
1371 }
1372}
1373
1374sub dump_enum($$) {
1375 my $x = shift;
1376 my $file = shift;
1377
Martin Waitzaeec46b2005-11-13 16:08:13 -08001378 $x =~ s@/\*.*?\*/@@gos; # strip comments.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001379 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001380 $declaration_name = $1;
1381 my $members = $2;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001382
1383 foreach my $arg (split ',', $members) {
1384 $arg =~ s/^\s*(\w+).*/$1/;
1385 push @parameterlist, $arg;
1386 if (!$parameterdescs{$arg}) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001387 $parameterdescs{$arg} = $undescribed;
1388 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
Linus Torvalds1da177e2005-04-16 15:20:36 -07001389 "not described in enum '$declaration_name'\n";
1390 }
1391
1392 }
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001393
Linus Torvalds1da177e2005-04-16 15:20:36 -07001394 output_declaration($declaration_name,
1395 'enum',
1396 {'enum' => $declaration_name,
1397 'module' => $modulename,
1398 'parameterlist' => \@parameterlist,
1399 'parameterdescs' => \%parameterdescs,
1400 'sectionlist' => \@sectionlist,
1401 'sections' => \%sections,
1402 'purpose' => $declaration_purpose
1403 });
1404 }
1405 else {
Randy Dunlap3c308792007-05-08 00:24:39 -07001406 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001407 ++$errors;
1408 }
1409}
1410
1411sub dump_typedef($$) {
1412 my $x = shift;
1413 my $file = shift;
1414
Martin Waitzaeec46b2005-11-13 16:08:13 -08001415 $x =~ s@/\*.*?\*/@@gos; # strip comments.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001416 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001417 $x =~ s/\(*.\)\s*;$/;/;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001418 $x =~ s/\[*.\]\s*;$/;/;
1419 }
1420
1421 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001422 $declaration_name = $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001423
1424 output_declaration($declaration_name,
1425 'typedef',
1426 {'typedef' => $declaration_name,
1427 'module' => $modulename,
1428 'sectionlist' => \@sectionlist,
1429 'sections' => \%sections,
1430 'purpose' => $declaration_purpose
1431 });
1432 }
1433 else {
Randy Dunlap3c308792007-05-08 00:24:39 -07001434 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001435 ++$errors;
1436 }
1437}
1438
1439sub create_parameterlist($$$) {
1440 my $args = shift;
1441 my $splitter = shift;
1442 my $file = shift;
1443 my $type;
1444 my $param;
1445
Martin Waitza6d3fe72006-01-09 20:53:55 -08001446 # temporarily replace commas inside function pointer definition
Linus Torvalds1da177e2005-04-16 15:20:36 -07001447 while ($args =~ /(\([^\),]+),/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001448 $args =~ s/(\([^\),]+),/$1#/g;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001449 }
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001450
Linus Torvalds1da177e2005-04-16 15:20:36 -07001451 foreach my $arg (split($splitter, $args)) {
1452 # strip comments
1453 $arg =~ s/\/\*.*\*\///;
Randy Dunlap3c308792007-05-08 00:24:39 -07001454 # strip leading/trailing spaces
1455 $arg =~ s/^\s*//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001456 $arg =~ s/\s*$//;
1457 $arg =~ s/\s+/ /;
1458
1459 if ($arg =~ /^#/) {
1460 # Treat preprocessor directive as a typeless variable just to fill
1461 # corresponding data structures "correctly". Catch it later in
1462 # output_* subs.
1463 push_parameter($arg, "", $file);
Randy Dunlapea82c742006-12-06 20:38:52 -08001464 } elsif ($arg =~ m/\(.*\*/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001465 # pointer-to-function
1466 $arg =~ tr/#/,/;
Randy Dunlap996a07b2007-02-10 01:45:56 -08001467 $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001468 $param = $1;
1469 $type = $arg;
1470 $type =~ s/([^\(]+\(\*)$param/$1/;
1471 push_parameter($param, $type, $file);
Martin Waitzaeec46b2005-11-13 16:08:13 -08001472 } elsif ($arg) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001473 $arg =~ s/\s*:\s*/:/g;
1474 $arg =~ s/\s*\[/\[/g;
1475
1476 my @args = split('\s*,\s*', $arg);
1477 if ($args[0] =~ m/\*/) {
1478 $args[0] =~ s/(\*+)\s*/ $1/;
1479 }
Borislav Petkov884f2812007-05-08 00:29:05 -07001480
1481 my @first_arg;
1482 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1483 shift @args;
1484 push(@first_arg, split('\s+', $1));
1485 push(@first_arg, $2);
1486 } else {
1487 @first_arg = split('\s+', shift @args);
1488 }
1489
Linus Torvalds1da177e2005-04-16 15:20:36 -07001490 unshift(@args, pop @first_arg);
1491 $type = join " ", @first_arg;
1492
1493 foreach $param (@args) {
1494 if ($param =~ m/^(\*+)\s*(.*)/) {
1495 push_parameter($2, "$type $1", $file);
1496 }
1497 elsif ($param =~ m/(.*?):(\d+)/) {
1498 push_parameter($1, "$type:$2", $file)
1499 }
1500 else {
1501 push_parameter($param, $type, $file);
1502 }
1503 }
1504 }
1505 }
1506}
1507
1508sub push_parameter($$$) {
1509 my $param = shift;
1510 my $type = shift;
1511 my $file = shift;
Randy Dunlap134fe012006-12-22 01:10:50 -08001512 my $anon = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001513
1514 my $param_name = $param;
1515 $param_name =~ s/\[.*//;
1516
Martin Waitza6d3fe72006-01-09 20:53:55 -08001517 if ($type eq "" && $param =~ /\.\.\.$/)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001518 {
1519 $type="";
Martin Waitza6d3fe72006-01-09 20:53:55 -08001520 $parameterdescs{$param} = "variable arguments";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001521 }
1522 elsif ($type eq "" && ($param eq "" or $param eq "void"))
1523 {
1524 $type="";
1525 $param="void";
1526 $parameterdescs{void} = "no arguments";
1527 }
Randy Dunlap134fe012006-12-22 01:10:50 -08001528 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1529 # handle unnamed (anonymous) union or struct:
1530 {
1531 $type = $param;
1532 $param = "{unnamed_" . $param. "}";
1533 $parameterdescs{$param} = "anonymous\n";
1534 $anon = 1;
1535 }
1536
Martin Waitza6d3fe72006-01-09 20:53:55 -08001537 # warn if parameter has no description
Randy Dunlap134fe012006-12-22 01:10:50 -08001538 # (but ignore ones starting with # as these are not parameters
1539 # but inline preprocessor statements);
1540 # also ignore unnamed structs/unions;
1541 if (!$anon) {
Martin Waitza6d3fe72006-01-09 20:53:55 -08001542 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1543
Linus Torvalds1da177e2005-04-16 15:20:36 -07001544 $parameterdescs{$param_name} = $undescribed;
1545
1546 if (($type eq 'function') || ($type eq 'enum')) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001547 print STDERR "Warning(${file}:$.): Function parameter ".
Linus Torvalds1da177e2005-04-16 15:20:36 -07001548 "or member '$param' not " .
1549 "described in '$declaration_name'\n";
1550 }
1551 print STDERR "Warning(${file}:$.):".
Randy Dunlap3c308792007-05-08 00:24:39 -07001552 " No description found for parameter '$param'\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001553 ++$warnings;
Randy Dunlap3c308792007-05-08 00:24:39 -07001554 }
1555 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001556
1557 push @parameterlist, $param;
1558 $parametertypes{$param} = $type;
1559}
1560
1561##
1562# takes a function prototype and the name of the current file being
1563# processed and spits out all the details stored in the global
1564# arrays/hashes.
1565sub dump_function($$) {
1566 my $prototype = shift;
1567 my $file = shift;
1568
1569 $prototype =~ s/^static +//;
1570 $prototype =~ s/^extern +//;
Pavel Pisa4dc3b162005-05-01 08:59:25 -07001571 $prototype =~ s/^fastcall +//;
1572 $prototype =~ s/^asmlinkage +//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001573 $prototype =~ s/^inline +//;
1574 $prototype =~ s/^__inline__ +//;
Randy Dunlap32e79402006-10-11 01:22:10 -07001575 $prototype =~ s/^__inline +//;
1576 $prototype =~ s/^__always_inline +//;
1577 $prototype =~ s/^noinline +//;
Randy Dunlap0129a052006-07-30 03:03:41 -07001578 $prototype =~ s/__devinit +//;
Randy Dunlap996a07b2007-02-10 01:45:56 -08001579 $prototype =~ s/^#define\s+//; #ak added
Randy Dunlap328d2442007-02-28 20:12:10 -08001580 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001581
1582 # Yes, this truly is vile. We are looking for:
1583 # 1. Return type (may be nothing if we're looking at a macro)
1584 # 2. Function name
1585 # 3. Function parameters.
1586 #
1587 # All the while we have to watch out for function pointer parameters
1588 # (which IIRC is what the two sections are for), C types (these
1589 # regexps don't even start to express all the possibilities), and
1590 # so on.
1591 #
1592 # If you mess with these regexps, it's a good idea to check that
1593 # the following functions' documentation still comes out right:
1594 # - parport_register_device (function pointer parameters)
1595 # - atomic_set (macro)
Martin Waitz9598f912006-02-01 03:06:55 -08001596 # - pci_match_device, __copy_to_user (long return type)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001597
1598 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1599 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1600 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1601 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1602 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1603 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1604 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1605 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1606 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1607 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1608 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1609 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1610 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
Martin Waitz9598f912006-02-01 03:06:55 -08001611 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1612 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
Randy Dunlap412ecd72007-02-10 22:47:33 -08001613 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1614 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001615 $return_type = $1;
1616 $declaration_name = $2;
1617 my $args = $3;
1618
1619 create_parameterlist($args, ',', $file);
1620 } else {
1621 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1622 ++$errors;
1623 return;
1624 }
1625
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001626 output_declaration($declaration_name,
Linus Torvalds1da177e2005-04-16 15:20:36 -07001627 'function',
1628 {'function' => $declaration_name,
1629 'module' => $modulename,
1630 'functiontype' => $return_type,
1631 'parameterlist' => \@parameterlist,
1632 'parameterdescs' => \%parameterdescs,
1633 'parametertypes' => \%parametertypes,
1634 'sectionlist' => \@sectionlist,
1635 'sections' => \%sections,
1636 'purpose' => $declaration_purpose
1637 });
1638}
1639
1640sub process_file($);
1641
1642# Read the file that maps relative names to absolute names for
1643# separate source and object directories and for shadow trees.
1644if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
1645 my ($relname, $absname);
1646 while(<SOURCE_MAP>) {
1647 chop();
1648 ($relname, $absname) = (split())[0..1];
1649 $relname =~ s:^/+::;
1650 $source_map{$relname} = $absname;
1651 }
1652 close(SOURCE_MAP);
1653}
1654
1655if ($filelist) {
1656 open(FLIST,"<$filelist") or die "Can't open file list $filelist";
1657 while(<FLIST>) {
1658 chop;
1659 process_file($_);
1660 }
1661}
1662
1663foreach (@ARGV) {
1664 chomp;
1665 process_file($_);
1666}
1667if ($verbose && $errors) {
1668 print STDERR "$errors errors\n";
1669}
1670if ($verbose && $warnings) {
1671 print STDERR "$warnings warnings\n";
1672}
1673
1674exit($errors);
1675
1676sub reset_state {
1677 $function = "";
1678 %constants = ();
1679 %parameterdescs = ();
1680 %parametertypes = ();
1681 @parameterlist = ();
1682 %sections = ();
1683 @sectionlist = ();
1684 $prototype = "";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001685
Linus Torvalds1da177e2005-04-16 15:20:36 -07001686 $state = 0;
1687}
1688
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001689sub process_state3_function($$) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001690 my $x = shift;
1691 my $file = shift;
1692
1693 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
1694 # do nothing
1695 }
1696 elsif ($x =~ /([^\{]*)/) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001697 $prototype .= $1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001698 }
1699 if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001700 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
Linus Torvalds1da177e2005-04-16 15:20:36 -07001701 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1702 $prototype =~ s@^\s+@@gos; # strip leading spaces
1703 dump_function($prototype,$file);
1704 reset_state();
1705 }
1706}
1707
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001708sub process_state3_type($$) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001709 my $x = shift;
1710 my $file = shift;
1711
Linus Torvalds1da177e2005-04-16 15:20:36 -07001712 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1713 $x =~ s@^\s+@@gos; # strip leading spaces
1714 $x =~ s@\s+$@@gos; # strip trailing spaces
1715 if ($x =~ /^#/) {
1716 # To distinguish preprocessor directive from regular declaration later.
1717 $x .= ";";
1718 }
1719
1720 while (1) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001721 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001722 $prototype .= $1 . $2;
1723 ($2 eq '{') && $brcount++;
1724 ($2 eq '}') && $brcount--;
1725 if (($2 eq ';') && ($brcount == 0)) {
Randy Dunlap3c308792007-05-08 00:24:39 -07001726 dump_declaration($prototype,$file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001727 reset_state();
Randy Dunlap3c308792007-05-08 00:24:39 -07001728 last;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001729 }
1730 $x = $3;
Randy Dunlap3c308792007-05-08 00:24:39 -07001731 } else {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001732 $prototype .= $x;
1733 last;
1734 }
1735 }
1736}
1737
1738# replace <, >, and &
1739sub xml_escape($) {
1740 my $text = shift;
Randy Dunlapecfb2512006-06-25 05:49:13 -07001741 if (($output_mode eq "text") || ($output_mode eq "man")) {
1742 return $text;
1743 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001744 $text =~ s/\&/\\\\\\amp;/g;
1745 $text =~ s/\</\\\\\\lt;/g;
1746 $text =~ s/\>/\\\\\\gt;/g;
1747 return $text;
1748}
1749
1750sub process_file($) {
Randy Dunlap2283a112005-07-07 15:39:26 -07001751 my $file;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001752 my $identifier;
1753 my $func;
Randy Dunlapa21217d2007-02-10 01:46:04 -08001754 my $descr;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001755 my $initial_section_counter = $section_counter;
1756
Randy Dunlap2283a112005-07-07 15:39:26 -07001757 if (defined($ENV{'SRCTREE'})) {
1758 $file = "$ENV{'SRCTREE'}" . "/" . "@_";
1759 }
1760 else {
1761 $file = "@_";
1762 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001763 if (defined($source_map{$file})) {
1764 $file = $source_map{$file};
1765 }
1766
1767 if (!open(IN,"<$file")) {
1768 print STDERR "Error: Cannot open file $file\n";
1769 ++$errors;
1770 return;
1771 }
1772
1773 $section_counter = 0;
1774 while (<IN>) {
1775 if ($state == 0) {
1776 if (/$doc_start/o) {
1777 $state = 1; # next line is always the function name
Randy Dunlap850622d2006-06-25 05:48:55 -07001778 $in_doc_sect = 0;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001779 }
1780 } elsif ($state == 1) { # this line is the function name (always)
1781 if (/$doc_block/o) {
1782 $state = 4;
1783 $contents = "";
1784 if ( $1 eq "" ) {
1785 $section = $section_intro;
1786 } else {
1787 $section = $1;
1788 }
Randy Dunlap3c308792007-05-08 00:24:39 -07001789 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001790 elsif (/$doc_decl/o) {
1791 $identifier = $1;
1792 if (/\s*([\w\s]+?)\s*-/) {
1793 $identifier = $1;
1794 }
1795
1796 $state = 2;
1797 if (/-(.*)/) {
Randy Dunlapa21217d2007-02-10 01:46:04 -08001798 # strip leading/trailing/multiple spaces #RDD:T:
1799 $descr= $1;
1800 $descr =~ s/^\s*//;
1801 $descr =~ s/\s*$//;
1802 $descr =~ s/\s+/ /;
1803 $declaration_purpose = xml_escape($descr);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001804 } else {
1805 $declaration_purpose = "";
1806 }
1807 if ($identifier =~ m/^struct/) {
1808 $decl_type = 'struct';
1809 } elsif ($identifier =~ m/^union/) {
1810 $decl_type = 'union';
1811 } elsif ($identifier =~ m/^enum/) {
1812 $decl_type = 'enum';
1813 } elsif ($identifier =~ m/^typedef/) {
1814 $decl_type = 'typedef';
1815 } else {
1816 $decl_type = 'function';
1817 }
1818
1819 if ($verbose) {
1820 print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
1821 }
1822 } else {
1823 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
1824 " - I thought it was a doc line\n";
1825 ++$warnings;
1826 $state = 0;
1827 }
1828 } elsif ($state == 2) { # look for head: lines, and include content
1829 if (/$doc_sect/o) {
1830 $newsection = $1;
1831 $newcontents = $2;
1832
1833 if ($contents ne "") {
Randy Dunlap850622d2006-06-25 05:48:55 -07001834 if (!$in_doc_sect && $verbose) {
1835 print STDERR "Warning(${file}:$.): contents before sections\n";
1836 ++$warnings;
1837 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001838 dump_section($section, xml_escape($contents));
1839 $section = $section_default;
1840 }
1841
Randy Dunlap850622d2006-06-25 05:48:55 -07001842 $in_doc_sect = 1;
Linus Torvalds1da177e2005-04-16 15:20:36 -07001843 $contents = $newcontents;
1844 if ($contents ne "") {
Randy Dunlap27205742006-10-11 01:22:12 -07001845 while ((substr($contents, 0, 1) eq " ") ||
1846 substr($contents, 0, 1) eq "\t") {
1847 $contents = substr($contents, 1);
Randy Dunlap05189492006-06-25 05:47:47 -07001848 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001849 $contents .= "\n";
1850 }
1851 $section = $newsection;
1852 } elsif (/$doc_end/) {
1853
1854 if ($contents ne "") {
1855 dump_section($section, xml_escape($contents));
1856 $section = $section_default;
1857 $contents = "";
1858 }
1859
1860 $prototype = "";
1861 $state = 3;
1862 $brcount = 0;
Randy Dunlap232acbc2006-06-25 05:47:48 -07001863# print STDERR "end of doc comment, looking for prototype\n";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001864 } elsif (/$doc_content/) {
1865 # miguel-style comment kludge, look for blank lines after
1866 # @parameter line to signify start of description
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001867 if ($1 eq "" &&
Linus Torvalds1da177e2005-04-16 15:20:36 -07001868 ($section =~ m/^@/ || $section eq $section_context)) {
1869 dump_section($section, xml_escape($contents));
1870 $section = $section_default;
1871 $contents = "";
1872 } else {
1873 $contents .= $1."\n";
1874 }
1875 } else {
1876 # i dont know - bad line? ignore.
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001877 print STDERR "Warning(${file}:$.): bad line: $_";
Linus Torvalds1da177e2005-04-16 15:20:36 -07001878 ++$warnings;
1879 }
Randy Dunlap232acbc2006-06-25 05:47:48 -07001880 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
Linus Torvalds1da177e2005-04-16 15:20:36 -07001881 if ($decl_type eq 'function') {
Randy Dunlap3c308792007-05-08 00:24:39 -07001882 process_state3_function($_, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001883 } else {
Randy Dunlap3c308792007-05-08 00:24:39 -07001884 process_state3_type($_, $file);
Linus Torvalds1da177e2005-04-16 15:20:36 -07001885 }
1886 } elsif ($state == 4) {
1887 # Documentation block
Randy Dunlap3c308792007-05-08 00:24:39 -07001888 if (/$doc_block/) {
Linus Torvalds1da177e2005-04-16 15:20:36 -07001889 dump_section($section, $contents);
1890 output_intro({'sectionlist' => \@sectionlist,
1891 'sections' => \%sections });
1892 $contents = "";
1893 $function = "";
1894 %constants = ();
1895 %parameterdescs = ();
1896 %parametertypes = ();
1897 @parameterlist = ();
1898 %sections = ();
1899 @sectionlist = ();
1900 $prototype = "";
1901 if ( $1 eq "" ) {
1902 $section = $section_intro;
1903 } else {
1904 $section = $1;
1905 }
Randy Dunlap3c308792007-05-08 00:24:39 -07001906 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001907 elsif (/$doc_end/)
1908 {
1909 dump_section($section, $contents);
1910 output_intro({'sectionlist' => \@sectionlist,
1911 'sections' => \%sections });
1912 $contents = "";
1913 $function = "";
1914 %constants = ();
1915 %parameterdescs = ();
1916 %parametertypes = ();
1917 @parameterlist = ();
1918 %sections = ();
1919 @sectionlist = ();
1920 $prototype = "";
1921 $state = 0;
1922 }
1923 elsif (/$doc_content/)
1924 {
1925 if ( $1 eq "" )
1926 {
1927 $contents .= $blankline;
1928 }
1929 else
1930 {
1931 $contents .= $1 . "\n";
Randy Dunlap3c3b8092006-02-01 03:06:58 -08001932 }
Randy Dunlap3c308792007-05-08 00:24:39 -07001933 }
1934 }
Linus Torvalds1da177e2005-04-16 15:20:36 -07001935 }
1936 if ($initial_section_counter == $section_counter) {
1937 print STDERR "Warning(${file}): no structured comments found\n";
1938 if ($output_mode eq "xml") {
1939 # The template wants at least one RefEntry here; make one.
1940 print "<refentry>\n";
1941 print " <refnamediv>\n";
1942 print " <refname>\n";
1943 print " ${file}\n";
1944 print " </refname>\n";
1945 print " <refpurpose>\n";
1946 print " Document generation inconsistency\n";
1947 print " </refpurpose>\n";
1948 print " </refnamediv>\n";
1949 print " <refsect1>\n";
1950 print " <title>\n";
1951 print " Oops\n";
1952 print " </title>\n";
1953 print " <warning>\n";
1954 print " <para>\n";
1955 print " The template for this document tried to insert\n";
1956 print " the structured comment from the file\n";
1957 print " <filename>${file}</filename> at this point,\n";
1958 print " but none was found.\n";
1959 print " This dummy section is inserted to allow\n";
1960 print " generation to continue.\n";
1961 print " </para>\n";
1962 print " </warning>\n";
1963 print " </refsect1>\n";
1964 print "</refentry>\n";
1965 }
1966 }
1967}