Merge master.kernel.org:/pub/scm/linux/kernel/git/davem/sparc-2.6
[linux-2.6] / scripts / kernel-doc
1 #!/usr/bin/perl -w
2
3 use 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:
48 # kernel-doc [ -docbook | -html | -text | -man ]
49 #           [ -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
60 #       If set, then only generate documentation for the other function(s).
61 #       Cannot be used together with -function
62 #       (yes, that's a bug -- perl hackers can fix it 8))
63 #
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 #
86 # If the Description: header tag is omitted, then there must be a blank line
87 # after the last parameter specification.
88 # e.g.
89 # /**
90 #  * my_function - does my stuff
91 #  * @my_arg: its mine damnit
92 #  *
93 #  * Does my stuff explained.
94 #  */
95 #
96 #  or, could also use:
97 # /**
98 #  * my_function - does my stuff
99 #  * @my_arg: its mine damnit
100 #  * Description: Does my stuff explained.
101 #  */
102 # etc.
103 #
104 # 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.
108 # 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
114 #  *
115 #  * Longer description
116 #  */
117 # struct my_struct {
118 #     int a;
119 #     int b;
120 # /* private: */
121 #     int c;
122 # };
123 #
124 # All descriptions can be multiline, except the short function description.
125 #
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
128 # can be called form interrupts. Unlike other sections you can end it with an
129 # empty line.
130 # Example-sections should contain the string EXAMPLE so that they are marked
131 # 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()
138 #  *
139 #  * 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
155 my $errors = 0;
156 my $warnings = 0;
157
158 # match expressions used to find embedded type information
159 my $type_constant = '\%([-_\w]+)';
160 my $type_func = '(\w+)\(\)';
161 my $type_param = '\@(\w+)';
162 my $type_struct = '\&((struct\s*)*[_\w]+)';
163 my $type_struct_xml = '\\\amp;((struct\s*)*[_\w]+)';
164 my $type_env = '(\$\w+)';
165
166 # Output conversion substitutions.
167 #  One for each output format
168
169 # these work fairly well
170 my %highlights_html = ( $type_constant, "<i>\$1</i>",
171                         $type_func, "<b>\$1</b>",
172                         $type_struct_xml, "<i>\$1</i>",
173                         $type_env, "<b><i>\$1</i></b>",
174                         $type_param, "<tt><b>\$1</b></tt>" );
175 my $blankline_html = "<p>";
176
177 # XML, docbook format
178 my %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>" );
184 my $blankline_xml = "</para><para>\n";
185
186 # gnome, docbook format
187 my %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>" );
192 my $blankline_gnome = "</para><para>\n";
193
194 # these are pretty rough
195 my %highlights_man = ( $type_constant, "\$1",
196                        $type_func, "\\\\fB\$1\\\\fP",
197                        $type_struct, "\\\\fI\$1\\\\fP",
198                        $type_param, "\\\\fI\$1\\\\fP" );
199 my $blankline_man = "";
200
201 # text-mode
202 my %highlights_text = ( $type_constant, "\$1",
203                         $type_func, "\$1",
204                         $type_struct, "\$1",
205                         $type_param, "\$1" );
206 my $blankline_text = "";
207
208
209 sub 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
218 if ($#ARGV==-1) {
219     usage();
220 }
221
222 my $verbose = 0;
223 my $output_mode = "man";
224 my %highlights = %highlights_man;
225 my $blankline = $blankline_man;
226 my $modulename = "Kernel API";
227 my $function_only = 0;
228 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
229                 'July', 'August', 'September', 'October',
230                 'November', 'December')[(localtime)[4]] .
231   " " . ((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.
237 my ($function, %function_table,%parametertypes,$declaration_purpose);
238 my ($type,$declaration_name,$return_type);
239 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
240
241 # Generated docbook code is inserted in a template at a point where
242 # 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.
247 my $section_counter = 0;
248
249 my $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
257 my $state;
258 my $in_doc_sect;
259
260 #declaration types: can be
261 # 'function', 'struct', 'union', 'enum', 'typedef'
262 my $decl_type;
263
264 my $doc_special = "\@\%\$\&";
265
266 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
267 my $doc_end = '\*/';
268 my $doc_com = '\s*\*\s*';
269 my $doc_decl = $doc_com.'(\w+)';
270 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
271 my $doc_content = $doc_com.'(.*)';
272 my $doc_block = $doc_com.'DOC:\s*(.*)?';
273
274 my %constants;
275 my %parameterdescs;
276 my @parameterlist;
277 my %sections;
278 my @sectionlist;
279
280 my $contents = "";
281 my $section_default = "Description";    # default section
282 my $section_intro = "Introduction";
283 my $section = $section_default;
284 my $section_context = "Context";
285
286 my $undescribed = "-- undescribed --";
287
288 reset_state();
289
290 while ($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
331 # get kernel version from env
332 sub get_kernel_version() {
333     my $version;
334
335     if (defined($ENV{'KERNELVERSION'})) {
336         $version = $ENV{'KERNELVERSION'};
337     }
338     return $version;
339 }
340 my $kernelversion = get_kernel_version();
341
342 # generate a sequence of code that will splice in highlighting information
343 # using the s// operator.
344 my $dohighlight = "";
345 foreach my $pattern (keys %highlights) {
346 #   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
347     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
348 }
349
350 ##
351 # dumps section contents to arrays/hashes intended for that purpose.
352 #
353 sub dump_section {
354     my $name = shift;
355     my $contents = join "\n", @_;
356
357     if ($name =~ m/$type_constant/) {
358         $name = $1;
359 #       print STDERR "constant section '$1' = '$contents'\n";
360         $constants{$name} = $contents;
361     } elsif ($name =~ m/$type_param/) {
362 #       print STDERR "parameter def '$1' = '$contents'\n";
363         $name = $1;
364         $parameterdescs{$name} = $contents;
365     } else {
366 #       print STDERR "other section '$name' = '$contents'\n";
367         $sections{$name} = $contents;
368         push @sectionlist, $name;
369     }
370 }
371
372 ##
373 # output function
374 #
375 # parameterdescs, a hash.
376 #  function => "function name"
377 #  parameterlist => @list of parameters
378 #  parameterdescs => %parameter descriptions
379 #  sectionlist => @list of sections
380 #  sections => %section descriptions
381 #
382
383 sub output_highlight {
384     my $contents = join "\n",@_;
385     my $line;
386
387 #   DEBUG
388 #   if (!defined $contents) {
389 #       use Carp;
390 #       confess "output_highlight got called with no args?\n";
391 #   }
392
393 #   print STDERR "contents b4:$contents\n";
394     eval $dohighlight;
395     die $@ if $@;
396     if ($output_mode eq "html") {
397         $contents =~ s/\\\\//;
398     }
399 #   print STDERR "contents af:$contents\n";
400
401     foreach $line (split "\n", $contents) {
402         if ($line eq ""){
403             print $lineprefix, $blankline;
404         } else {
405             $line =~ s/\\\\\\/\&/g;
406             print $lineprefix, $line;
407         }
408         print "\n";
409     }
410 }
411
412 #output sections in html
413 sub output_section_html(%) {
414     my %args = %{$_[0]};
415     my $section;
416
417     foreach $section (@{$args{'sectionlist'}}) {
418         print "<h3>$section</h3>\n";
419         print "<blockquote>\n";
420         output_highlight($args{'sections'}{$section});
421         print "</blockquote>\n";
422     }
423 }
424
425 # output enum in html
426 sub output_enum_html(%) {
427     my %args = %{$_[0]};
428     my ($parameter);
429     my $count;
430     print "<h2>enum ".$args{'enum'}."</h2>\n";
431
432     print "<b>enum ".$args{'enum'}."</b> {<br>\n";
433     $count = 0;
434     foreach $parameter (@{$args{'parameterlist'}}) {
435         print " <b>".$parameter."</b>";
436         if ($count != $#{$args{'parameterlist'}}) {
437             $count++;
438             print ",\n";
439         }
440         print "<br>";
441     }
442     print "};<br>\n";
443
444     print "<h3>Constants</h3>\n";
445     print "<dl>\n";
446     foreach $parameter (@{$args{'parameterlist'}}) {
447         print "<dt><b>".$parameter."</b>\n";
448         print "<dd>";
449         output_highlight($args{'parameterdescs'}{$parameter});
450     }
451     print "</dl>\n";
452     output_section_html(@_);
453     print "<hr>\n";
454 }
455
456 # output typedef in html
457 sub output_typedef_html(%) {
458     my %args = %{$_[0]};
459     my ($parameter);
460     my $count;
461     print "<h2>typedef ".$args{'typedef'}."</h2>\n";
462
463     print "<b>typedef ".$args{'typedef'}."</b>\n";
464     output_section_html(@_);
465     print "<hr>\n";
466 }
467
468 # output struct in html
469 sub output_struct_html(%) {
470     my %args = %{$_[0]};
471     my ($parameter);
472
473     print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
474     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
475     foreach $parameter (@{$args{'parameterlist'}}) {
476         if ($parameter =~ /^#/) {
477                 print "$parameter<br>\n";
478                 next;
479         }
480         my $parameter_name = $parameter;
481         $parameter_name =~ s/\[.*//;
482
483         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
484         $type = $args{'parametertypes'}{$parameter};
485         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
486             # pointer-to-function
487             print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
488         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
489             # bitfield
490             print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
491         } else {
492             print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
493         }
494     }
495     print "};<br>\n";
496
497     print "<h3>Members</h3>\n";
498     print "<dl>\n";
499     foreach $parameter (@{$args{'parameterlist'}}) {
500         ($parameter =~ /^#/) && next;
501
502         my $parameter_name = $parameter;
503         $parameter_name =~ s/\[.*//;
504
505         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
506         print "<dt><b>".$parameter."</b>\n";
507         print "<dd>";
508         output_highlight($args{'parameterdescs'}{$parameter_name});
509     }
510     print "</dl>\n";
511     output_section_html(@_);
512     print "<hr>\n";
513 }
514
515 # output function in html
516 sub output_function_html(%) {
517     my %args = %{$_[0]};
518     my ($parameter, $section);
519     my $count;
520
521     print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
522     print "<i>".$args{'functiontype'}."</i>\n";
523     print "<b>".$args{'function'}."</b>\n";
524     print "(";
525     $count = 0;
526     foreach $parameter (@{$args{'parameterlist'}}) {
527         $type = $args{'parametertypes'}{$parameter};
528         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
529             # pointer-to-function
530             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
531         } else {
532             print "<i>".$type."</i> <b>".$parameter."</b>";
533         }
534         if ($count != $#{$args{'parameterlist'}}) {
535             $count++;
536             print ",\n";
537         }
538     }
539     print ")\n";
540
541     print "<h3>Arguments</h3>\n";
542     print "<dl>\n";
543     foreach $parameter (@{$args{'parameterlist'}}) {
544         my $parameter_name = $parameter;
545         $parameter_name =~ s/\[.*//;
546
547         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
548         print "<dt><b>".$parameter."</b>\n";
549         print "<dd>";
550         output_highlight($args{'parameterdescs'}{$parameter_name});
551     }
552     print "</dl>\n";
553     output_section_html(@_);
554     print "<hr>\n";
555 }
556
557 # output intro in html
558 sub output_intro_html(%) {
559     my %args = %{$_[0]};
560     my ($parameter, $section);
561     my $count;
562
563     foreach $section (@{$args{'sectionlist'}}) {
564         print "<h3>$section</h3>\n";
565         print "<ul>\n";
566         output_highlight($args{'sections'}{$section});
567         print "</ul>\n";
568     }
569     print "<hr>\n";
570 }
571
572 sub output_section_xml(%) {
573     my %args = %{$_[0]};
574     my $section;
575     # print out each section
576     $lineprefix="   ";
577     foreach $section (@{$args{'sectionlist'}}) {
578         print "<refsect1>\n";
579         print "<title>$section</title>\n";
580         if ($section =~ m/EXAMPLE/i) {
581             print "<informalexample><programlisting>\n";
582         } else {
583             print "<para>\n";
584         }
585         output_highlight($args{'sections'}{$section});
586         if ($section =~ m/EXAMPLE/i) {
587             print "</programlisting></informalexample>\n";
588         } else {
589             print "</para>\n";
590         }
591         print "</refsect1>\n";
592     }
593 }
594
595 # output function in XML DocBook
596 sub output_function_xml(%) {
597     my %args = %{$_[0]};
598     my ($parameter, $section);
599     my $count;
600     my $id;
601
602     $id = "API-".$args{'function'};
603     $id =~ s/[^A-Za-z0-9]/-/g;
604
605     print "<refentry id=\"$id\">\n";
606     print "<refentryinfo>\n";
607     print " <title>LINUX</title>\n";
608     print " <productname>Kernel Hackers Manual</productname>\n";
609     print " <date>$man_date</date>\n";
610     print "</refentryinfo>\n";
611     print "<refmeta>\n";
612     print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
613     print " <manvolnum>9</manvolnum>\n";
614     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
615     print "</refmeta>\n";
616     print "<refnamediv>\n";
617     print " <refname>".$args{'function'}."</refname>\n";
618     print " <refpurpose>\n";
619     print "  ";
620     output_highlight ($args{'purpose'});
621     print " </refpurpose>\n";
622     print "</refnamediv>\n";
623
624     print "<refsynopsisdiv>\n";
625     print " <title>Synopsis</title>\n";
626     print "  <funcsynopsis><funcprototype>\n";
627     print "   <funcdef>".$args{'functiontype'}." ";
628     print "<function>".$args{'function'}." </function></funcdef>\n";
629
630     $count = 0;
631     if ($#{$args{'parameterlist'}} >= 0) {
632         foreach $parameter (@{$args{'parameterlist'}}) {
633             $type = $args{'parametertypes'}{$parameter};
634             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
635                 # pointer-to-function
636                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
637                 print "     <funcparams>$2</funcparams></paramdef>\n";
638             } else {
639                 print "   <paramdef>".$type;
640                 print " <parameter>$parameter</parameter></paramdef>\n";
641             }
642         }
643     } else {
644         print "  <void/>\n";
645     }
646     print "  </funcprototype></funcsynopsis>\n";
647     print "</refsynopsisdiv>\n";
648
649     # print parameters
650     print "<refsect1>\n <title>Arguments</title>\n";
651     if ($#{$args{'parameterlist'}} >= 0) {
652         print " <variablelist>\n";
653         foreach $parameter (@{$args{'parameterlist'}}) {
654             my $parameter_name = $parameter;
655             $parameter_name =~ s/\[.*//;
656
657             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
658             print "   <listitem>\n    <para>\n";
659             $lineprefix="     ";
660             output_highlight($args{'parameterdescs'}{$parameter_name});
661             print "    </para>\n   </listitem>\n  </varlistentry>\n";
662         }
663         print " </variablelist>\n";
664     } else {
665         print " <para>\n  None\n </para>\n";
666     }
667     print "</refsect1>\n";
668
669     output_section_xml(@_);
670     print "</refentry>\n\n";
671 }
672
673 # output struct in XML DocBook
674 sub output_struct_xml(%) {
675     my %args = %{$_[0]};
676     my ($parameter, $section);
677     my $id;
678
679     $id = "API-struct-".$args{'struct'};
680     $id =~ s/[^A-Za-z0-9]/-/g;
681
682     print "<refentry id=\"$id\">\n";
683     print "<refentryinfo>\n";
684     print " <title>LINUX</title>\n";
685     print " <productname>Kernel Hackers Manual</productname>\n";
686     print " <date>$man_date</date>\n";
687     print "</refentryinfo>\n";
688     print "<refmeta>\n";
689     print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
690     print " <manvolnum>9</manvolnum>\n";
691     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
692     print "</refmeta>\n";
693     print "<refnamediv>\n";
694     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
695     print " <refpurpose>\n";
696     print "  ";
697     output_highlight ($args{'purpose'});
698     print " </refpurpose>\n";
699     print "</refnamediv>\n";
700
701     print "<refsynopsisdiv>\n";
702     print " <title>Synopsis</title>\n";
703     print "  <programlisting>\n";
704     print $args{'type'}." ".$args{'struct'}." {\n";
705     foreach $parameter (@{$args{'parameterlist'}}) {
706         if ($parameter =~ /^#/) {
707             print "$parameter\n";
708             next;
709         }
710
711         my $parameter_name = $parameter;
712         $parameter_name =~ s/\[.*//;
713
714         defined($args{'parameterdescs'}{$parameter_name}) || next;
715         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
716         $type = $args{'parametertypes'}{$parameter};
717         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
718             # pointer-to-function
719             print "  $1 $parameter) ($2);\n";
720         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
721             print "  $1 $parameter$2;\n";
722         } else {
723             print "  ".$type." ".$parameter.";\n";
724         }
725     }
726     print "};";
727     print "  </programlisting>\n";
728     print "</refsynopsisdiv>\n";
729
730     print " <refsect1>\n";
731     print "  <title>Members</title>\n";
732
733     print "  <variablelist>\n";
734     foreach $parameter (@{$args{'parameterlist'}}) {
735       ($parameter =~ /^#/) && next;
736
737       my $parameter_name = $parameter;
738       $parameter_name =~ s/\[.*//;
739
740       defined($args{'parameterdescs'}{$parameter_name}) || next;
741       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
742       print "    <varlistentry>";
743       print "      <term>$parameter</term>\n";
744       print "      <listitem><para>\n";
745       output_highlight($args{'parameterdescs'}{$parameter_name});
746       print "      </para></listitem>\n";
747       print "    </varlistentry>\n";
748     }
749     print "  </variablelist>\n";
750     print " </refsect1>\n";
751
752     output_section_xml(@_);
753
754     print "</refentry>\n\n";
755 }
756
757 # output enum in XML DocBook
758 sub output_enum_xml(%) {
759     my %args = %{$_[0]};
760     my ($parameter, $section);
761     my $count;
762     my $id;
763
764     $id = "API-enum-".$args{'enum'};
765     $id =~ s/[^A-Za-z0-9]/-/g;
766
767     print "<refentry id=\"$id\">\n";
768     print "<refentryinfo>\n";
769     print " <title>LINUX</title>\n";
770     print " <productname>Kernel Hackers Manual</productname>\n";
771     print " <date>$man_date</date>\n";
772     print "</refentryinfo>\n";
773     print "<refmeta>\n";
774     print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
775     print " <manvolnum>9</manvolnum>\n";
776     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
777     print "</refmeta>\n";
778     print "<refnamediv>\n";
779     print " <refname>enum ".$args{'enum'}."</refname>\n";
780     print " <refpurpose>\n";
781     print "  ";
782     output_highlight ($args{'purpose'});
783     print " </refpurpose>\n";
784     print "</refnamediv>\n";
785
786     print "<refsynopsisdiv>\n";
787     print " <title>Synopsis</title>\n";
788     print "  <programlisting>\n";
789     print "enum ".$args{'enum'}." {\n";
790     $count = 0;
791     foreach $parameter (@{$args{'parameterlist'}}) {
792         print "  $parameter";
793         if ($count != $#{$args{'parameterlist'}}) {
794             $count++;
795             print ",";
796         }
797         print "\n";
798     }
799     print "};";
800     print "  </programlisting>\n";
801     print "</refsynopsisdiv>\n";
802
803     print "<refsect1>\n";
804     print " <title>Constants</title>\n";
805     print "  <variablelist>\n";
806     foreach $parameter (@{$args{'parameterlist'}}) {
807       my $parameter_name = $parameter;
808       $parameter_name =~ s/\[.*//;
809
810       print "    <varlistentry>";
811       print "      <term>$parameter</term>\n";
812       print "      <listitem><para>\n";
813       output_highlight($args{'parameterdescs'}{$parameter_name});
814       print "      </para></listitem>\n";
815       print "    </varlistentry>\n";
816     }
817     print "  </variablelist>\n";
818     print "</refsect1>\n";
819
820     output_section_xml(@_);
821
822     print "</refentry>\n\n";
823 }
824
825 # output typedef in XML DocBook
826 sub output_typedef_xml(%) {
827     my %args = %{$_[0]};
828     my ($parameter, $section);
829     my $id;
830
831     $id = "API-typedef-".$args{'typedef'};
832     $id =~ s/[^A-Za-z0-9]/-/g;
833
834     print "<refentry id=\"$id\">\n";
835     print "<refentryinfo>\n";
836     print " <title>LINUX</title>\n";
837     print " <productname>Kernel Hackers Manual</productname>\n";
838     print " <date>$man_date</date>\n";
839     print "</refentryinfo>\n";
840     print "<refmeta>\n";
841     print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
842     print " <manvolnum>9</manvolnum>\n";
843     print "</refmeta>\n";
844     print "<refnamediv>\n";
845     print " <refname>typedef ".$args{'typedef'}."</refname>\n";
846     print " <refpurpose>\n";
847     print "  ";
848     output_highlight ($args{'purpose'});
849     print " </refpurpose>\n";
850     print "</refnamediv>\n";
851
852     print "<refsynopsisdiv>\n";
853     print " <title>Synopsis</title>\n";
854     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
855     print "</refsynopsisdiv>\n";
856
857     output_section_xml(@_);
858
859     print "</refentry>\n\n";
860 }
861
862 # output in XML DocBook
863 sub output_intro_xml(%) {
864     my %args = %{$_[0]};
865     my ($parameter, $section);
866     my $count;
867
868     my $id = $args{'module'};
869     $id =~ s/[^A-Za-z0-9]/-/g;
870
871     # print out each section
872     $lineprefix="   ";
873     foreach $section (@{$args{'sectionlist'}}) {
874         print "<refsect1>\n <title>$section</title>\n <para>\n";
875         if ($section =~ m/EXAMPLE/i) {
876             print "<example><para>\n";
877         }
878         output_highlight($args{'sections'}{$section});
879         if ($section =~ m/EXAMPLE/i) {
880             print "</para></example>\n";
881         }
882         print " </para>\n</refsect1>\n";
883     }
884
885     print "\n\n";
886 }
887
888 # output in XML DocBook
889 sub output_function_gnome {
890     my %args = %{$_[0]};
891     my ($parameter, $section);
892     my $count;
893     my $id;
894
895     $id = $args{'module'}."-".$args{'function'};
896     $id =~ s/[^A-Za-z0-9]/-/g;
897
898     print "<sect2>\n";
899     print " <title id=\"$id\">".$args{'function'}."</title>\n";
900
901     print "  <funcsynopsis>\n";
902     print "   <funcdef>".$args{'functiontype'}." ";
903     print "<function>".$args{'function'}." ";
904     print "</function></funcdef>\n";
905
906     $count = 0;
907     if ($#{$args{'parameterlist'}} >= 0) {
908         foreach $parameter (@{$args{'parameterlist'}}) {
909             $type = $args{'parametertypes'}{$parameter};
910             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
911                 # pointer-to-function
912                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
913                 print "     <funcparams>$2</funcparams></paramdef>\n";
914             } else {
915                 print "   <paramdef>".$type;
916                 print " <parameter>$parameter</parameter></paramdef>\n";
917             }
918         }
919     } else {
920         print "  <void>\n";
921     }
922     print "  </funcsynopsis>\n";
923     if ($#{$args{'parameterlist'}} >= 0) {
924         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
925         print "<tgroup cols=\"2\">\n";
926         print "<colspec colwidth=\"2*\">\n";
927         print "<colspec colwidth=\"8*\">\n";
928         print "<tbody>\n";
929         foreach $parameter (@{$args{'parameterlist'}}) {
930             my $parameter_name = $parameter;
931             $parameter_name =~ s/\[.*//;
932
933             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
934             print "   <entry>\n";
935             $lineprefix="     ";
936             output_highlight($args{'parameterdescs'}{$parameter_name});
937             print "    </entry></row>\n";
938         }
939         print " </tbody></tgroup></informaltable>\n";
940     } else {
941         print " <para>\n  None\n </para>\n";
942     }
943
944     # print out each section
945     $lineprefix="   ";
946     foreach $section (@{$args{'sectionlist'}}) {
947         print "<simplesect>\n <title>$section</title>\n";
948         if ($section =~ m/EXAMPLE/i) {
949             print "<example><programlisting>\n";
950         } else {
951         }
952         print "<para>\n";
953         output_highlight($args{'sections'}{$section});
954         print "</para>\n";
955         if ($section =~ m/EXAMPLE/i) {
956             print "</programlisting></example>\n";
957         } else {
958         }
959         print " </simplesect>\n";
960     }
961
962     print "</sect2>\n\n";
963 }
964
965 ##
966 # output function in man
967 sub output_function_man(%) {
968     my %args = %{$_[0]};
969     my ($parameter, $section);
970     my $count;
971
972     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
973
974     print ".SH NAME\n";
975     print $args{'function'}." \\- ".$args{'purpose'}."\n";
976
977     print ".SH SYNOPSIS\n";
978     if ($args{'functiontype'} ne "") {
979         print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
980     } else {
981         print ".B \"".$args{'function'}."\n";
982     }
983     $count = 0;
984     my $parenth = "(";
985     my $post = ",";
986     foreach my $parameter (@{$args{'parameterlist'}}) {
987         if ($count == $#{$args{'parameterlist'}}) {
988             $post = ");";
989         }
990         $type = $args{'parametertypes'}{$parameter};
991         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
992             # pointer-to-function
993             print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
994         } else {
995             $type =~ s/([^\*])$/$1 /;
996             print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
997         }
998         $count++;
999         $parenth = "";
1000     }
1001
1002     print ".SH ARGUMENTS\n";
1003     foreach $parameter (@{$args{'parameterlist'}}) {
1004         my $parameter_name = $parameter;
1005         $parameter_name =~ s/\[.*//;
1006
1007         print ".IP \"".$parameter."\" 12\n";
1008         output_highlight($args{'parameterdescs'}{$parameter_name});
1009     }
1010     foreach $section (@{$args{'sectionlist'}}) {
1011         print ".SH \"", uc $section, "\"\n";
1012         output_highlight($args{'sections'}{$section});
1013     }
1014 }
1015
1016 ##
1017 # output enum in man
1018 sub output_enum_man(%) {
1019     my %args = %{$_[0]};
1020     my ($parameter, $section);
1021     my $count;
1022
1023     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1024
1025     print ".SH NAME\n";
1026     print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
1027
1028     print ".SH SYNOPSIS\n";
1029     print "enum ".$args{'enum'}." {\n";
1030     $count = 0;
1031     foreach my $parameter (@{$args{'parameterlist'}}) {
1032         print ".br\n.BI \"    $parameter\"\n";
1033         if ($count == $#{$args{'parameterlist'}}) {
1034             print "\n};\n";
1035             last;
1036         }
1037         else {
1038             print ", \n.br\n";
1039         }
1040         $count++;
1041     }
1042
1043     print ".SH Constants\n";
1044     foreach $parameter (@{$args{'parameterlist'}}) {
1045         my $parameter_name = $parameter;
1046         $parameter_name =~ s/\[.*//;
1047
1048         print ".IP \"".$parameter."\" 12\n";
1049         output_highlight($args{'parameterdescs'}{$parameter_name});
1050     }
1051     foreach $section (@{$args{'sectionlist'}}) {
1052         print ".SH \"$section\"\n";
1053         output_highlight($args{'sections'}{$section});
1054     }
1055 }
1056
1057 ##
1058 # output struct in man
1059 sub output_struct_man(%) {
1060     my %args = %{$_[0]};
1061     my ($parameter, $section);
1062
1063     print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
1064
1065     print ".SH NAME\n";
1066     print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
1067
1068     print ".SH SYNOPSIS\n";
1069     print $args{'type'}." ".$args{'struct'}." {\n.br\n";
1070
1071     foreach my $parameter (@{$args{'parameterlist'}}) {
1072         if ($parameter =~ /^#/) {
1073             print ".BI \"$parameter\"\n.br\n";
1074             next;
1075         }
1076         my $parameter_name = $parameter;
1077         $parameter_name =~ s/\[.*//;
1078
1079         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1080         $type = $args{'parametertypes'}{$parameter};
1081         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1082             # pointer-to-function
1083             print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
1084         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1085             # bitfield
1086             print ".BI \"    ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
1087         } else {
1088             $type =~ s/([^\*])$/$1 /;
1089             print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
1090         }
1091         print "\n.br\n";
1092     }
1093     print "};\n.br\n";
1094
1095     print ".SH Members\n";
1096     foreach $parameter (@{$args{'parameterlist'}}) {
1097         ($parameter =~ /^#/) && next;
1098
1099         my $parameter_name = $parameter;
1100         $parameter_name =~ s/\[.*//;
1101
1102         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1103         print ".IP \"".$parameter."\" 12\n";
1104         output_highlight($args{'parameterdescs'}{$parameter_name});
1105     }
1106     foreach $section (@{$args{'sectionlist'}}) {
1107         print ".SH \"$section\"\n";
1108         output_highlight($args{'sections'}{$section});
1109     }
1110 }
1111
1112 ##
1113 # output typedef in man
1114 sub output_typedef_man(%) {
1115     my %args = %{$_[0]};
1116     my ($parameter, $section);
1117
1118     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1119
1120     print ".SH NAME\n";
1121     print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1122
1123     foreach $section (@{$args{'sectionlist'}}) {
1124         print ".SH \"$section\"\n";
1125         output_highlight($args{'sections'}{$section});
1126     }
1127 }
1128
1129 sub output_intro_man(%) {
1130     my %args = %{$_[0]};
1131     my ($parameter, $section);
1132     my $count;
1133
1134     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1135
1136     foreach $section (@{$args{'sectionlist'}}) {
1137         print ".SH \"$section\"\n";
1138         output_highlight($args{'sections'}{$section});
1139     }
1140 }
1141
1142 ##
1143 # output in text
1144 sub output_function_text(%) {
1145     my %args = %{$_[0]};
1146     my ($parameter, $section);
1147     my $start;
1148
1149     print "Name:\n\n";
1150     print $args{'function'}." - ".$args{'purpose'}."\n";
1151
1152     print "\nSynopsis:\n\n";
1153     if ($args{'functiontype'} ne "") {
1154         $start = $args{'functiontype'}." ".$args{'function'}." (";
1155     } else {
1156         $start = $args{'function'}." (";
1157     }
1158     print $start;
1159
1160     my $count = 0;
1161     foreach my $parameter (@{$args{'parameterlist'}}) {
1162         $type = $args{'parametertypes'}{$parameter};
1163         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1164             # pointer-to-function
1165             print $1.$parameter.") (".$2;
1166         } else {
1167             print $type." ".$parameter;
1168         }
1169         if ($count != $#{$args{'parameterlist'}}) {
1170             $count++;
1171             print ",\n";
1172             print " " x length($start);
1173         } else {
1174             print ");\n\n";
1175         }
1176     }
1177
1178     print "Arguments:\n\n";
1179     foreach $parameter (@{$args{'parameterlist'}}) {
1180         my $parameter_name = $parameter;
1181         $parameter_name =~ s/\[.*//;
1182
1183         print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
1184     }
1185     output_section_text(@_);
1186 }
1187
1188 #output sections in text
1189 sub output_section_text(%) {
1190     my %args = %{$_[0]};
1191     my $section;
1192
1193     print "\n";
1194     foreach $section (@{$args{'sectionlist'}}) {
1195         print "$section:\n\n";
1196         output_highlight($args{'sections'}{$section});
1197     }
1198     print "\n\n";
1199 }
1200
1201 # output enum in text
1202 sub output_enum_text(%) {
1203     my %args = %{$_[0]};
1204     my ($parameter);
1205     my $count;
1206     print "Enum:\n\n";
1207
1208     print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
1209     print "enum ".$args{'enum'}." {\n";
1210     $count = 0;
1211     foreach $parameter (@{$args{'parameterlist'}}) {
1212         print "\t$parameter";
1213         if ($count != $#{$args{'parameterlist'}}) {
1214             $count++;
1215             print ",";
1216         }
1217         print "\n";
1218     }
1219     print "};\n\n";
1220
1221     print "Constants:\n\n";
1222     foreach $parameter (@{$args{'parameterlist'}}) {
1223         print "$parameter\n\t";
1224         print $args{'parameterdescs'}{$parameter}."\n";
1225     }
1226
1227     output_section_text(@_);
1228 }
1229
1230 # output typedef in text
1231 sub output_typedef_text(%) {
1232     my %args = %{$_[0]};
1233     my ($parameter);
1234     my $count;
1235     print "Typedef:\n\n";
1236
1237     print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
1238     output_section_text(@_);
1239 }
1240
1241 # output struct as text
1242 sub output_struct_text(%) {
1243     my %args = %{$_[0]};
1244     my ($parameter);
1245
1246     print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
1247     print $args{'type'}." ".$args{'struct'}." {\n";
1248     foreach $parameter (@{$args{'parameterlist'}}) {
1249         if ($parameter =~ /^#/) {
1250             print "$parameter\n";
1251             next;
1252         }
1253
1254         my $parameter_name = $parameter;
1255         $parameter_name =~ s/\[.*//;
1256
1257         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1258         $type = $args{'parametertypes'}{$parameter};
1259         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1260             # pointer-to-function
1261             print "\t$1 $parameter) ($2);\n";
1262         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1263             print "\t$1 $parameter$2;\n";
1264         } else {
1265             print "\t".$type." ".$parameter.";\n";
1266         }
1267     }
1268     print "};\n\n";
1269
1270     print "Members:\n\n";
1271     foreach $parameter (@{$args{'parameterlist'}}) {
1272         ($parameter =~ /^#/) && next;
1273
1274         my $parameter_name = $parameter;
1275         $parameter_name =~ s/\[.*//;
1276
1277         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1278         print "$parameter\n\t";
1279         print $args{'parameterdescs'}{$parameter_name}."\n";
1280     }
1281     print "\n";
1282     output_section_text(@_);
1283 }
1284
1285 sub output_intro_text(%) {
1286     my %args = %{$_[0]};
1287     my ($parameter, $section);
1288
1289     foreach $section (@{$args{'sectionlist'}}) {
1290         print " $section:\n";
1291         print "    -> ";
1292         output_highlight($args{'sections'}{$section});
1293     }
1294 }
1295
1296 ##
1297 # generic output function for all types (function, struct/union, typedef, enum);
1298 # calls the generated, variable output_ function name based on
1299 # functype and output_mode
1300 sub output_declaration {
1301     no strict 'refs';
1302     my $name = shift;
1303     my $functype = shift;
1304     my $func = "output_${functype}_$output_mode";
1305     if (($function_only==0) ||
1306         ( $function_only == 1 && defined($function_table{$name})) ||
1307         ( $function_only == 2 && !defined($function_table{$name})))
1308     {
1309         &$func(@_);
1310         $section_counter++;
1311     }
1312 }
1313
1314 ##
1315 # generic output function - calls the right one based on current output mode.
1316 sub output_intro {
1317     no strict 'refs';
1318     my $func = "output_intro_".$output_mode;
1319     &$func(@_);
1320     $section_counter++;
1321 }
1322
1323 ##
1324 # takes a declaration (struct, union, enum, typedef) and
1325 # invokes the right handler. NOT called for functions.
1326 sub dump_declaration($$) {
1327     no strict 'refs';
1328     my ($prototype, $file) = @_;
1329     my $func = "dump_".$decl_type;
1330     &$func(@_);
1331 }
1332
1333 sub dump_union($$) {
1334     dump_struct(@_);
1335 }
1336
1337 sub dump_struct($$) {
1338     my $x = shift;
1339     my $file = shift;
1340
1341     if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1342         $declaration_name = $2;
1343         my $members = $3;
1344
1345         # ignore embedded structs or unions
1346         $members =~ s/{.*?}//g;
1347
1348         # ignore members marked private:
1349         $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
1350         $members =~ s/\/\*.*?private:.*//gos;
1351         # strip comments:
1352         $members =~ s/\/\*.*?\*\///gos;
1353
1354         create_parameterlist($members, ';', $file);
1355
1356         output_declaration($declaration_name,
1357                            'struct',
1358                            {'struct' => $declaration_name,
1359                             'module' => $modulename,
1360                             'parameterlist' => \@parameterlist,
1361                             'parameterdescs' => \%parameterdescs,
1362                             'parametertypes' => \%parametertypes,
1363                             'sectionlist' => \@sectionlist,
1364                             'sections' => \%sections,
1365                             'purpose' => $declaration_purpose,
1366                             'type' => $decl_type
1367                            });
1368     }
1369     else {
1370         print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1371         ++$errors;
1372     }
1373 }
1374
1375 sub dump_enum($$) {
1376     my $x = shift;
1377     my $file = shift;
1378
1379     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1380     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1381         $declaration_name = $1;
1382         my $members = $2;
1383
1384         foreach my $arg (split ',', $members) {
1385             $arg =~ s/^\s*(\w+).*/$1/;
1386             push @parameterlist, $arg;
1387             if (!$parameterdescs{$arg}) {
1388                 $parameterdescs{$arg} = $undescribed;
1389                 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1390                     "not described in enum '$declaration_name'\n";
1391             }
1392
1393         }
1394
1395         output_declaration($declaration_name,
1396                            'enum',
1397                            {'enum' => $declaration_name,
1398                             'module' => $modulename,
1399                             'parameterlist' => \@parameterlist,
1400                             'parameterdescs' => \%parameterdescs,
1401                             'sectionlist' => \@sectionlist,
1402                             'sections' => \%sections,
1403                             'purpose' => $declaration_purpose
1404                            });
1405     }
1406     else {
1407         print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1408         ++$errors;
1409     }
1410 }
1411
1412 sub dump_typedef($$) {
1413     my $x = shift;
1414     my $file = shift;
1415
1416     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
1417     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1418         $x =~ s/\(*.\)\s*;$/;/;
1419         $x =~ s/\[*.\]\s*;$/;/;
1420     }
1421
1422     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1423         $declaration_name = $1;
1424
1425         output_declaration($declaration_name,
1426                            'typedef',
1427                            {'typedef' => $declaration_name,
1428                             'module' => $modulename,
1429                             'sectionlist' => \@sectionlist,
1430                             'sections' => \%sections,
1431                             'purpose' => $declaration_purpose
1432                            });
1433     }
1434     else {
1435         print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1436         ++$errors;
1437     }
1438 }
1439
1440 sub create_parameterlist($$$) {
1441     my $args = shift;
1442     my $splitter = shift;
1443     my $file = shift;
1444     my $type;
1445     my $param;
1446
1447     # temporarily replace commas inside function pointer definition
1448     while ($args =~ /(\([^\),]+),/) {
1449         $args =~ s/(\([^\),]+),/$1#/g;
1450     }
1451
1452     foreach my $arg (split($splitter, $args)) {
1453         # strip comments
1454         $arg =~ s/\/\*.*\*\///;
1455         # strip leading/trailing spaces
1456         $arg =~ s/^\s*//;
1457         $arg =~ s/\s*$//;
1458         $arg =~ s/\s+/ /;
1459
1460         if ($arg =~ /^#/) {
1461             # Treat preprocessor directive as a typeless variable just to fill
1462             # corresponding data structures "correctly". Catch it later in
1463             # output_* subs.
1464             push_parameter($arg, "", $file);
1465         } elsif ($arg =~ m/\(.*\*/) {
1466             # pointer-to-function
1467             $arg =~ tr/#/,/;
1468             $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/;
1469             $param = $1;
1470             $type = $arg;
1471             $type =~ s/([^\(]+\(\*)$param/$1/;
1472             push_parameter($param, $type, $file);
1473         } elsif ($arg) {
1474             $arg =~ s/\s*:\s*/:/g;
1475             $arg =~ s/\s*\[/\[/g;
1476
1477             my @args = split('\s*,\s*', $arg);
1478             if ($args[0] =~ m/\*/) {
1479                 $args[0] =~ s/(\*+)\s*/ $1/;
1480             }
1481
1482             my @first_arg;
1483             if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1484                     shift @args;
1485                     push(@first_arg, split('\s+', $1));
1486                     push(@first_arg, $2);
1487             } else {
1488                     @first_arg = split('\s+', shift @args);
1489             }
1490
1491             unshift(@args, pop @first_arg);
1492             $type = join " ", @first_arg;
1493
1494             foreach $param (@args) {
1495                 if ($param =~ m/^(\*+)\s*(.*)/) {
1496                     push_parameter($2, "$type $1", $file);
1497                 }
1498                 elsif ($param =~ m/(.*?):(\d+)/) {
1499                     push_parameter($1, "$type:$2", $file)
1500                 }
1501                 else {
1502                     push_parameter($param, $type, $file);
1503                 }
1504             }
1505         }
1506     }
1507 }
1508
1509 sub push_parameter($$$) {
1510         my $param = shift;
1511         my $type = shift;
1512         my $file = shift;
1513         my $anon = 0;
1514
1515         my $param_name = $param;
1516         $param_name =~ s/\[.*//;
1517
1518         if ($type eq "" && $param =~ /\.\.\.$/)
1519         {
1520             $type="";
1521             $parameterdescs{$param} = "variable arguments";
1522         }
1523         elsif ($type eq "" && ($param eq "" or $param eq "void"))
1524         {
1525             $type="";
1526             $param="void";
1527             $parameterdescs{void} = "no arguments";
1528         }
1529         elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1530         # handle unnamed (anonymous) union or struct:
1531         {
1532                 $type = $param;
1533                 $param = "{unnamed_" . $param. "}";
1534                 $parameterdescs{$param} = "anonymous\n";
1535                 $anon = 1;
1536         }
1537
1538         # warn if parameter has no description
1539         # (but ignore ones starting with # as these are not parameters
1540         # but inline preprocessor statements);
1541         # also ignore unnamed structs/unions;
1542         if (!$anon) {
1543         if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1544
1545             $parameterdescs{$param_name} = $undescribed;
1546
1547             if (($type eq 'function') || ($type eq 'enum')) {
1548                 print STDERR "Warning(${file}:$.): Function parameter ".
1549                     "or member '$param' not " .
1550                     "described in '$declaration_name'\n";
1551             }
1552             print STDERR "Warning(${file}:$.):".
1553                          " No description found for parameter '$param'\n";
1554             ++$warnings;
1555         }
1556         }
1557
1558         push @parameterlist, $param;
1559         $parametertypes{$param} = $type;
1560 }
1561
1562 ##
1563 # takes a function prototype and the name of the current file being
1564 # processed and spits out all the details stored in the global
1565 # arrays/hashes.
1566 sub dump_function($$) {
1567     my $prototype = shift;
1568     my $file = shift;
1569
1570     $prototype =~ s/^static +//;
1571     $prototype =~ s/^extern +//;
1572     $prototype =~ s/^fastcall +//;
1573     $prototype =~ s/^asmlinkage +//;
1574     $prototype =~ s/^inline +//;
1575     $prototype =~ s/^__inline__ +//;
1576     $prototype =~ s/^__inline +//;
1577     $prototype =~ s/^__always_inline +//;
1578     $prototype =~ s/^noinline +//;
1579     $prototype =~ s/__devinit +//;
1580     $prototype =~ s/^#define\s+//; #ak added
1581     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1582
1583     # Yes, this truly is vile.  We are looking for:
1584     # 1. Return type (may be nothing if we're looking at a macro)
1585     # 2. Function name
1586     # 3. Function parameters.
1587     #
1588     # All the while we have to watch out for function pointer parameters
1589     # (which IIRC is what the two sections are for), C types (these
1590     # regexps don't even start to express all the possibilities), and
1591     # so on.
1592     #
1593     # If you mess with these regexps, it's a good idea to check that
1594     # the following functions' documentation still comes out right:
1595     # - parport_register_device (function pointer parameters)
1596     # - atomic_set (macro)
1597     # - pci_match_device, __copy_to_user (long return type)
1598
1599     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1600         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1601         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1602         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1603         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1604         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1605         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1606         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1607         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1608         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1609         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1610         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1611         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1612         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1613         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1614         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1615         $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
1616         $return_type = $1;
1617         $declaration_name = $2;
1618         my $args = $3;
1619
1620         create_parameterlist($args, ',', $file);
1621     } else {
1622         print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
1623         ++$errors;
1624         return;
1625     }
1626
1627     output_declaration($declaration_name,
1628                        'function',
1629                        {'function' => $declaration_name,
1630                         'module' => $modulename,
1631                         'functiontype' => $return_type,
1632                         'parameterlist' => \@parameterlist,
1633                         'parameterdescs' => \%parameterdescs,
1634                         'parametertypes' => \%parametertypes,
1635                         'sectionlist' => \@sectionlist,
1636                         'sections' => \%sections,
1637                         'purpose' => $declaration_purpose
1638                        });
1639 }
1640
1641 sub process_file($);
1642
1643 # Read the file that maps relative names to absolute names for
1644 # separate source and object directories and for shadow trees.
1645 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
1646         my ($relname, $absname);
1647         while(<SOURCE_MAP>) {
1648                 chop();
1649                 ($relname, $absname) = (split())[0..1];
1650                 $relname =~ s:^/+::;
1651                 $source_map{$relname} = $absname;
1652         }
1653         close(SOURCE_MAP);
1654 }
1655
1656 if ($filelist) {
1657         open(FLIST,"<$filelist") or die "Can't open file list $filelist";
1658         while(<FLIST>) {
1659                 chop;
1660                 process_file($_);
1661         }
1662 }
1663
1664 foreach (@ARGV) {
1665     chomp;
1666     process_file($_);
1667 }
1668 if ($verbose && $errors) {
1669   print STDERR "$errors errors\n";
1670 }
1671 if ($verbose && $warnings) {
1672   print STDERR "$warnings warnings\n";
1673 }
1674
1675 exit($errors);
1676
1677 sub reset_state {
1678     $function = "";
1679     %constants = ();
1680     %parameterdescs = ();
1681     %parametertypes = ();
1682     @parameterlist = ();
1683     %sections = ();
1684     @sectionlist = ();
1685     $prototype = "";
1686
1687     $state = 0;
1688 }
1689
1690 sub process_state3_function($$) {
1691     my $x = shift;
1692     my $file = shift;
1693
1694     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#define/)) {
1695         # do nothing
1696     }
1697     elsif ($x =~ /([^\{]*)/) {
1698         $prototype .= $1;
1699     }
1700     if (($x =~ /\{/) || ($x =~ /\#define/) || ($x =~ /;/)) {
1701         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
1702         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1703         $prototype =~ s@^\s+@@gos; # strip leading spaces
1704         dump_function($prototype,$file);
1705         reset_state();
1706     }
1707 }
1708
1709 sub process_state3_type($$) {
1710     my $x = shift;
1711     my $file = shift;
1712
1713     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1714     $x =~ s@^\s+@@gos; # strip leading spaces
1715     $x =~ s@\s+$@@gos; # strip trailing spaces
1716     if ($x =~ /^#/) {
1717         # To distinguish preprocessor directive from regular declaration later.
1718         $x .= ";";
1719     }
1720
1721     while (1) {
1722         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1723             $prototype .= $1 . $2;
1724             ($2 eq '{') && $brcount++;
1725             ($2 eq '}') && $brcount--;
1726             if (($2 eq ';') && ($brcount == 0)) {
1727                 dump_declaration($prototype,$file);
1728                 reset_state();
1729                 last;
1730             }
1731             $x = $3;
1732         } else {
1733             $prototype .= $x;
1734             last;
1735         }
1736     }
1737 }
1738
1739 # replace <, >, and &
1740 sub xml_escape($) {
1741         my $text = shift;
1742         if (($output_mode eq "text") || ($output_mode eq "man")) {
1743                 return $text;
1744         }
1745         $text =~ s/\&/\\\\\\amp;/g;
1746         $text =~ s/\</\\\\\\lt;/g;
1747         $text =~ s/\>/\\\\\\gt;/g;
1748         return $text;
1749 }
1750
1751 sub process_file($) {
1752     my $file;
1753     my $identifier;
1754     my $func;
1755     my $descr;
1756     my $initial_section_counter = $section_counter;
1757
1758     if (defined($ENV{'SRCTREE'})) {
1759         $file = "$ENV{'SRCTREE'}" . "/" . "@_";
1760     }
1761     else {
1762         $file = "@_";
1763     }
1764     if (defined($source_map{$file})) {
1765         $file = $source_map{$file};
1766     }
1767
1768     if (!open(IN,"<$file")) {
1769         print STDERR "Error: Cannot open file $file\n";
1770         ++$errors;
1771         return;
1772     }
1773
1774     $section_counter = 0;
1775     while (<IN>) {
1776         if ($state == 0) {
1777             if (/$doc_start/o) {
1778                 $state = 1;             # next line is always the function name
1779                 $in_doc_sect = 0;
1780             }
1781         } elsif ($state == 1) { # this line is the function name (always)
1782             if (/$doc_block/o) {
1783                 $state = 4;
1784                 $contents = "";
1785                 if ( $1 eq "" ) {
1786                         $section = $section_intro;
1787                 } else {
1788                         $section = $1;
1789                 }
1790             }
1791             elsif (/$doc_decl/o) {
1792                 $identifier = $1;
1793                 if (/\s*([\w\s]+?)\s*-/) {
1794                     $identifier = $1;
1795                 }
1796
1797                 $state = 2;
1798                 if (/-(.*)/) {
1799                     # strip leading/trailing/multiple spaces #RDD:T:
1800                     $descr= $1;
1801                     $descr =~ s/^\s*//;
1802                     $descr =~ s/\s*$//;
1803                     $descr =~ s/\s+/ /;
1804                     $declaration_purpose = xml_escape($descr);
1805                 } else {
1806                     $declaration_purpose = "";
1807                 }
1808                 if ($identifier =~ m/^struct/) {
1809                     $decl_type = 'struct';
1810                 } elsif ($identifier =~ m/^union/) {
1811                     $decl_type = 'union';
1812                 } elsif ($identifier =~ m/^enum/) {
1813                     $decl_type = 'enum';
1814                 } elsif ($identifier =~ m/^typedef/) {
1815                     $decl_type = 'typedef';
1816                 } else {
1817                     $decl_type = 'function';
1818                 }
1819
1820                 if ($verbose) {
1821                     print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
1822                 }
1823             } else {
1824                 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
1825                 " - I thought it was a doc line\n";
1826                 ++$warnings;
1827                 $state = 0;
1828             }
1829         } elsif ($state == 2) { # look for head: lines, and include content
1830             if (/$doc_sect/o) {
1831                 $newsection = $1;
1832                 $newcontents = $2;
1833
1834                 if ($contents ne "") {
1835                     if (!$in_doc_sect && $verbose) {
1836                         print STDERR "Warning(${file}:$.): contents before sections\n";
1837                         ++$warnings;
1838                     }
1839                     dump_section($section, xml_escape($contents));
1840                     $section = $section_default;
1841                 }
1842
1843                 $in_doc_sect = 1;
1844                 $contents = $newcontents;
1845                 if ($contents ne "") {
1846                     while ((substr($contents, 0, 1) eq " ") ||
1847                         substr($contents, 0, 1) eq "\t") {
1848                             $contents = substr($contents, 1);
1849                     }
1850                     $contents .= "\n";
1851                 }
1852                 $section = $newsection;
1853             } elsif (/$doc_end/) {
1854
1855                 if ($contents ne "") {
1856                     dump_section($section, xml_escape($contents));
1857                     $section = $section_default;
1858                     $contents = "";
1859                 }
1860
1861                 $prototype = "";
1862                 $state = 3;
1863                 $brcount = 0;
1864 #               print STDERR "end of doc comment, looking for prototype\n";
1865             } elsif (/$doc_content/) {
1866                 # miguel-style comment kludge, look for blank lines after
1867                 # @parameter line to signify start of description
1868                 if ($1 eq "" &&
1869                         ($section =~ m/^@/ || $section eq $section_context)) {
1870                     dump_section($section, xml_escape($contents));
1871                     $section = $section_default;
1872                     $contents = "";
1873                 } else {
1874                     $contents .= $1."\n";
1875                 }
1876             } else {
1877                 # i dont know - bad line?  ignore.
1878                 print STDERR "Warning(${file}:$.): bad line: $_";
1879                 ++$warnings;
1880             }
1881         } elsif ($state == 3) { # scanning for function '{' (end of prototype)
1882             if ($decl_type eq 'function') {
1883                 process_state3_function($_, $file);
1884             } else {
1885                 process_state3_type($_, $file);
1886             }
1887         } elsif ($state == 4) {
1888                 # Documentation block
1889                 if (/$doc_block/) {
1890                         dump_section($section, $contents);
1891                         output_intro({'sectionlist' => \@sectionlist,
1892                                       'sections' => \%sections });
1893                         $contents = "";
1894                         $function = "";
1895                         %constants = ();
1896                         %parameterdescs = ();
1897                         %parametertypes = ();
1898                         @parameterlist = ();
1899                         %sections = ();
1900                         @sectionlist = ();
1901                         $prototype = "";
1902                         if ( $1 eq "" ) {
1903                                 $section = $section_intro;
1904                         } else {
1905                                 $section = $1;
1906                         }
1907                 }
1908                 elsif (/$doc_end/)
1909                 {
1910                         dump_section($section, $contents);
1911                         output_intro({'sectionlist' => \@sectionlist,
1912                                       'sections' => \%sections });
1913                         $contents = "";
1914                         $function = "";
1915                         %constants = ();
1916                         %parameterdescs = ();
1917                         %parametertypes = ();
1918                         @parameterlist = ();
1919                         %sections = ();
1920                         @sectionlist = ();
1921                         $prototype = "";
1922                         $state = 0;
1923                 }
1924                 elsif (/$doc_content/)
1925                 {
1926                         if ( $1 eq "" )
1927                         {
1928                                 $contents .= $blankline;
1929                         }
1930                         else
1931                         {
1932                                 $contents .= $1 . "\n";
1933                         }
1934                 }
1935         }
1936     }
1937     if ($initial_section_counter == $section_counter) {
1938         print STDERR "Warning(${file}): no structured comments found\n";
1939         if ($output_mode eq "xml") {
1940             # The template wants at least one RefEntry here; make one.
1941             print "<refentry>\n";
1942             print " <refnamediv>\n";
1943             print "  <refname>\n";
1944             print "   ${file}\n";
1945             print "  </refname>\n";
1946             print "  <refpurpose>\n";
1947             print "   Document generation inconsistency\n";
1948             print "  </refpurpose>\n";
1949             print " </refnamediv>\n";
1950             print " <refsect1>\n";
1951             print "  <title>\n";
1952             print "   Oops\n";
1953             print "  </title>\n";
1954             print "  <warning>\n";
1955             print "   <para>\n";
1956             print "    The template for this document tried to insert\n";
1957             print "    the structured comment from the file\n";
1958             print "    <filename>${file}</filename> at this point,\n";
1959             print "    but none was found.\n";
1960             print "    This dummy section is inserted to allow\n";
1961             print "    generation to continue.\n";
1962             print "   </para>\n";
1963             print "  </warning>\n";
1964             print " </refsect1>\n";
1965             print "</refentry>\n";
1966         }
1967     }
1968 }