xref: /linux/scripts/kernel-doc (revision f3341dcf3bdcd1209b2911f35e4e970b789c4744)
1#!/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## Copyright (C) 2005-2012  Randy Dunlap                         ##
9## Copyright (C) 2012  Dan Luedtke                               ##
10## 								 ##
11## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
12## Copyright (c) 2000 MontaVista Software, Inc.			 ##
13## 								 ##
14## This software falls under the GNU General Public License.     ##
15## Please read the COPYING file for more information             ##
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# 25/07/2012 - Added support for HTML5
40# -- Dan Luedtke <mail@danrl.de>
41
42sub usage {
43    my $message = <<"EOF";
44Usage: $0 [OPTION ...] FILE ...
45
46Read C language source or header FILEs, extract embedded documentation comments,
47and print formatted documentation to standard output.
48
49The documentation comments are identified by "/**" opening comment mark. See
50Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
51
52Output format selection (mutually exclusive):
53  -docbook		Output DocBook format.
54  -html			Output HTML format.
55  -html5		Output HTML5 format.
56  -list			Output symbol list format. This is for use by docproc.
57  -man			Output troff manual page format. This is the default.
58  -rst			Output reStructuredText format.
59  -text			Output plain text format.
60
61Output selection (mutually exclusive):
62  -export		Only output documentation for symbols that have been
63			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
64			in the same FILE.
65  -internal		Only output documentation for symbols that have NOT been
66			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
67			in the same FILE.
68  -function NAME	Only output documentation for the given function(s)
69			or DOC: section title(s). All other functions and DOC:
70			sections are ignored. May be specified multiple times.
71  -nofunction NAME	Do NOT output documentation for the given function(s);
72			only output documentation for the other functions and
73			DOC: sections. May be specified multiple times.
74
75Output selection modifiers:
76  -no-doc-sections	Do not output DOC: sections.
77
78Other parameters:
79  -v			Verbose output, more warnings and other information.
80  -h			Print this help.
81
82EOF
83    print $message;
84    exit 1;
85}
86
87#
88# format of comments.
89# In the following table, (...)? signifies optional structure.
90#                         (...)* signifies 0 or more structure elements
91# /**
92#  * function_name(:)? (- short description)?
93# (* @parameterx: (description of parameter x)?)*
94# (* a blank line)?
95#  * (Description:)? (Description of function)?
96#  * (section header: (section description)? )*
97#  (*)?*/
98#
99# So .. the trivial example would be:
100#
101# /**
102#  * my_function
103#  */
104#
105# If the Description: header tag is omitted, then there must be a blank line
106# after the last parameter specification.
107# e.g.
108# /**
109#  * my_function - does my stuff
110#  * @my_arg: its mine damnit
111#  *
112#  * Does my stuff explained.
113#  */
114#
115#  or, could also use:
116# /**
117#  * my_function - does my stuff
118#  * @my_arg: its mine damnit
119#  * Description: Does my stuff explained.
120#  */
121# etc.
122#
123# Besides functions you can also write documentation for structs, unions,
124# enums and typedefs. Instead of the function name you must write the name
125# of the declaration;  the struct/union/enum/typedef must always precede
126# the name. Nesting of declarations is not supported.
127# Use the argument mechanism to document members or constants.
128# e.g.
129# /**
130#  * struct my_struct - short description
131#  * @a: first member
132#  * @b: second member
133#  *
134#  * Longer description
135#  */
136# struct my_struct {
137#     int a;
138#     int b;
139# /* private: */
140#     int c;
141# };
142#
143# All descriptions can be multiline, except the short function description.
144#
145# For really longs structs, you can also describe arguments inside the
146# body of the struct.
147# eg.
148# /**
149#  * struct my_struct - short description
150#  * @a: first member
151#  * @b: second member
152#  *
153#  * Longer description
154#  */
155# struct my_struct {
156#     int a;
157#     int b;
158#     /**
159#      * @c: This is longer description of C
160#      *
161#      * You can use paragraphs to describe arguments
162#      * using this method.
163#      */
164#     int c;
165# };
166#
167# This should be use only for struct/enum members.
168#
169# You can also add additional sections. When documenting kernel functions you
170# should document the "Context:" of the function, e.g. whether the functions
171# can be called form interrupts. Unlike other sections you can end it with an
172# empty line.
173# A non-void function should have a "Return:" section describing the return
174# value(s).
175# Example-sections should contain the string EXAMPLE so that they are marked
176# appropriately in DocBook.
177#
178# Example:
179# /**
180#  * user_function - function that can only be called in user context
181#  * @a: some argument
182#  * Context: !in_interrupt()
183#  *
184#  * Some description
185#  * Example:
186#  *    user_function(22);
187#  */
188# ...
189#
190#
191# All descriptive text is further processed, scanning for the following special
192# patterns, which are highlighted appropriately.
193#
194# 'funcname()' - function
195# '$ENVVAR' - environmental variable
196# '&struct_name' - name of a structure (up to two words including 'struct')
197# '@parameter' - name of a parameter
198# '%CONST' - name of a constant.
199
200## init lots of data
201
202my $errors = 0;
203my $warnings = 0;
204my $anon_struct_union = 0;
205
206# match expressions used to find embedded type information
207my $type_constant = '\%([-_\w]+)';
208my $type_func = '(\w+)\(\)';
209my $type_param = '\@(\w+)';
210my $type_struct = '\&((struct\s*)*[_\w]+)';
211my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
212my $type_env = '(\$\w+)';
213my $type_enum_full = '\&(enum)\s*([_\w]+)';
214my $type_struct_full = '\&(struct)\s*([_\w]+)';
215my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
216my $type_union_full = '\&(union)\s*([_\w]+)';
217my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
218my $type_member_func = $type_member . '\(\)';
219
220# Output conversion substitutions.
221#  One for each output format
222
223# these work fairly well
224my @highlights_html = (
225                       [$type_constant, "<i>\$1</i>"],
226                       [$type_func, "<b>\$1</b>"],
227                       [$type_struct_xml, "<i>\$1</i>"],
228                       [$type_env, "<b><i>\$1</i></b>"],
229                       [$type_param, "<tt><b>\$1</b></tt>"]
230                      );
231my $local_lt = "\\\\\\\\lt:";
232my $local_gt = "\\\\\\\\gt:";
233my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
234
235# html version 5
236my @highlights_html5 = (
237                        [$type_constant, "<span class=\"const\">\$1</span>"],
238                        [$type_func, "<span class=\"func\">\$1</span>"],
239                        [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
240                        [$type_env, "<span class=\"env\">\$1</span>"],
241                        [$type_param, "<span class=\"param\">\$1</span>]"]
242		       );
243my $blankline_html5 = $local_lt . "br /" . $local_gt;
244
245# XML, docbook format
246my @highlights_xml = (
247                      ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
248                      [$type_constant, "<constant>\$1</constant>"],
249                      [$type_struct_xml, "<structname>\$1</structname>"],
250                      [$type_param, "<parameter>\$1</parameter>"],
251                      [$type_func, "<function>\$1</function>"],
252                      [$type_env, "<envar>\$1</envar>"]
253		     );
254my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
255
256# gnome, docbook format
257my @highlights_gnome = (
258                        [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
259                        [$type_func, "<function>\$1</function>"],
260                        [$type_struct, "<structname>\$1</structname>"],
261                        [$type_env, "<envar>\$1</envar>"],
262                        [$type_param, "<parameter>\$1</parameter>" ]
263		       );
264my $blankline_gnome = "</para><para>\n";
265
266# these are pretty rough
267my @highlights_man = (
268                      [$type_constant, "\$1"],
269                      [$type_func, "\\\\fB\$1\\\\fP"],
270                      [$type_struct, "\\\\fI\$1\\\\fP"],
271                      [$type_param, "\\\\fI\$1\\\\fP"]
272		     );
273my $blankline_man = "";
274
275# text-mode
276my @highlights_text = (
277                       [$type_constant, "\$1"],
278                       [$type_func, "\$1"],
279                       [$type_struct, "\$1"],
280                       [$type_param, "\$1"]
281		      );
282my $blankline_text = "";
283
284# rst-mode
285my @highlights_rst = (
286                       [$type_constant, "``\$1``"],
287                       # Note: need to escape () to avoid func matching later
288                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
289                       [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
290                       [$type_func, "\\:c\\:func\\:`\$1()`"],
291                       [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
292                       [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
293                       [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
294                       [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
295                       # in rst this can refer to any type
296                       [$type_struct, "\\:c\\:type\\:`\$1`"],
297                       [$type_param, "**\$1**"]
298		      );
299my $blankline_rst = "\n";
300
301# list mode
302my @highlights_list = (
303                       [$type_constant, "\$1"],
304                       [$type_func, "\$1"],
305                       [$type_struct, "\$1"],
306                       [$type_param, "\$1"]
307		      );
308my $blankline_list = "";
309
310# read arguments
311if ($#ARGV == -1) {
312    usage();
313}
314
315my $kernelversion;
316my $dohighlight = "";
317
318my $verbose = 0;
319my $output_mode = "man";
320my $output_preformatted = 0;
321my $no_doc_sections = 0;
322my @highlights = @highlights_man;
323my $blankline = $blankline_man;
324my $modulename = "Kernel API";
325
326use constant {
327    OUTPUT_ALL          => 0, # output all symbols and doc sections
328    OUTPUT_INCLUDE      => 1, # output only specified symbols
329    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
330    OUTPUT_EXPORTED     => 3, # output exported symbols
331    OUTPUT_INTERNAL     => 4, # output non-exported symbols
332};
333my $output_selection = OUTPUT_ALL;
334my $show_not_found = 0;
335
336my @build_time;
337if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
338    (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
339    @build_time = gmtime($seconds);
340} else {
341    @build_time = localtime;
342}
343
344my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
345		'July', 'August', 'September', 'October',
346		'November', 'December')[$build_time[4]] .
347  " " . ($build_time[5]+1900);
348
349# Essentially these are globals.
350# They probably want to be tidied up, made more localised or something.
351# CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
352# could cause "use of undefined value" or other bugs.
353my ($function, %function_table, %parametertypes, $declaration_purpose);
354my ($type, $declaration_name, $return_type);
355my ($newsection, $newcontents, $prototype, $brcount, %source_map);
356
357if (defined($ENV{'KBUILD_VERBOSE'})) {
358	$verbose = "$ENV{'KBUILD_VERBOSE'}";
359}
360
361# Generated docbook code is inserted in a template at a point where
362# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
363# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
364# We keep track of number of generated entries and generate a dummy
365# if needs be to ensure the expanded template can be postprocessed
366# into html.
367my $section_counter = 0;
368
369my $lineprefix="";
370
371# Parser states
372use constant {
373    STATE_NORMAL        => 0, # normal code
374    STATE_NAME          => 1, # looking for function name
375    STATE_FIELD         => 2, # scanning field start
376    STATE_PROTO         => 3, # scanning prototype
377    STATE_DOCBLOCK      => 4, # documentation block
378    STATE_INLINE        => 5, # gathering documentation outside main block
379};
380my $state;
381my $in_doc_sect;
382
383# Inline documentation state
384use constant {
385    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
386    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
387    STATE_INLINE_TEXT   => 2, # looking for member documentation
388    STATE_INLINE_END    => 3, # done
389    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
390                              # Spit a warning as it's not
391                              # proper kernel-doc and ignore the rest.
392};
393my $inline_doc_state;
394
395#declaration types: can be
396# 'function', 'struct', 'union', 'enum', 'typedef'
397my $decl_type;
398
399my $doc_special = "\@\%\$\&";
400
401my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
402my $doc_end = '\*/';
403my $doc_com = '\s*\*\s*';
404my $doc_com_body = '\s*\* ?';
405my $doc_decl = $doc_com . '(\w+)';
406my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
407my $doc_content = $doc_com_body . '(.*)';
408my $doc_block = $doc_com . 'DOC:\s*(.*)?';
409my $doc_inline_start = '^\s*/\*\*\s*$';
410my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
411my $doc_inline_end = '^\s*\*/\s*$';
412my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
413
414my %constants;
415my %parameterdescs;
416my @parameterlist;
417my %sections;
418my @sectionlist;
419my $sectcheck;
420my $struct_actual;
421
422my $contents = "";
423my $section_default = "Description";	# default section
424my $section_intro = "Introduction";
425my $section = $section_default;
426my $section_context = "Context";
427my $section_return = "Return";
428
429my $undescribed = "-- undescribed --";
430
431reset_state();
432
433while ($ARGV[0] =~ m/^-(.*)/) {
434    my $cmd = shift @ARGV;
435    if ($cmd eq "-html") {
436	$output_mode = "html";
437	@highlights = @highlights_html;
438	$blankline = $blankline_html;
439    } elsif ($cmd eq "-html5") {
440	$output_mode = "html5";
441	@highlights = @highlights_html5;
442	$blankline = $blankline_html5;
443    } elsif ($cmd eq "-man") {
444	$output_mode = "man";
445	@highlights = @highlights_man;
446	$blankline = $blankline_man;
447    } elsif ($cmd eq "-text") {
448	$output_mode = "text";
449	@highlights = @highlights_text;
450	$blankline = $blankline_text;
451    } elsif ($cmd eq "-rst") {
452	$output_mode = "rst";
453	@highlights = @highlights_rst;
454	$blankline = $blankline_rst;
455    } elsif ($cmd eq "-docbook") {
456	$output_mode = "xml";
457	@highlights = @highlights_xml;
458	$blankline = $blankline_xml;
459    } elsif ($cmd eq "-list") {
460	$output_mode = "list";
461	@highlights = @highlights_list;
462	$blankline = $blankline_list;
463    } elsif ($cmd eq "-gnome") {
464	$output_mode = "gnome";
465	@highlights = @highlights_gnome;
466	$blankline = $blankline_gnome;
467    } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
468	$modulename = shift @ARGV;
469    } elsif ($cmd eq "-function") { # to only output specific functions
470	$output_selection = OUTPUT_INCLUDE;
471	$function = shift @ARGV;
472	$function_table{$function} = 1;
473    } elsif ($cmd eq "-nofunction") { # output all except specific functions
474	$output_selection = OUTPUT_EXCLUDE;
475	$function = shift @ARGV;
476	$function_table{$function} = 1;
477    } elsif ($cmd eq "-export") { # only exported symbols
478	$output_selection = OUTPUT_EXPORTED;
479	%function_table = ()
480    } elsif ($cmd eq "-internal") { # only non-exported symbols
481	$output_selection = OUTPUT_INTERNAL;
482	%function_table = ()
483    } elsif ($cmd eq "-v") {
484	$verbose = 1;
485    } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
486	usage();
487    } elsif ($cmd eq '-no-doc-sections') {
488	    $no_doc_sections = 1;
489    } elsif ($cmd eq '-show-not-found') {
490	$show_not_found = 1;
491    }
492}
493
494# continue execution near EOF;
495
496# get kernel version from env
497sub get_kernel_version() {
498    my $version = 'unknown kernel version';
499
500    if (defined($ENV{'KERNELVERSION'})) {
501	$version = $ENV{'KERNELVERSION'};
502    }
503    return $version;
504}
505
506##
507# dumps section contents to arrays/hashes intended for that purpose.
508#
509sub dump_section {
510    my $file = shift;
511    my $name = shift;
512    my $contents = join "\n", @_;
513
514    if ($name =~ m/$type_constant/) {
515	$name = $1;
516#	print STDERR "constant section '$1' = '$contents'\n";
517	$constants{$name} = $contents;
518    } elsif ($name =~ m/$type_param/) {
519#	print STDERR "parameter def '$1' = '$contents'\n";
520	$name = $1;
521	$parameterdescs{$name} = $contents;
522	$sectcheck = $sectcheck . $name . " ";
523    } elsif ($name eq "@\.\.\.") {
524#	print STDERR "parameter def '...' = '$contents'\n";
525	$name = "...";
526	$parameterdescs{$name} = $contents;
527	$sectcheck = $sectcheck . $name . " ";
528    } else {
529#	print STDERR "other section '$name' = '$contents'\n";
530	if (defined($sections{$name}) && ($sections{$name} ne "")) {
531		print STDERR "${file}:$.: error: duplicate section name '$name'\n";
532		++$errors;
533	}
534	$sections{$name} = $contents;
535	push @sectionlist, $name;
536    }
537}
538
539##
540# dump DOC: section after checking that it should go out
541#
542sub dump_doc_section {
543    my $file = shift;
544    my $name = shift;
545    my $contents = join "\n", @_;
546
547    if ($no_doc_sections) {
548        return;
549    }
550
551    if (($output_selection == OUTPUT_ALL) ||
552	($output_selection == OUTPUT_INCLUDE &&
553	 defined($function_table{$name})) ||
554	($output_selection == OUTPUT_EXCLUDE &&
555	 !defined($function_table{$name})))
556    {
557	dump_section($file, $name, $contents);
558	output_blockhead({'sectionlist' => \@sectionlist,
559			  'sections' => \%sections,
560			  'module' => $modulename,
561			  'content-only' => ($output_selection != OUTPUT_ALL), });
562    }
563}
564
565##
566# output function
567#
568# parameterdescs, a hash.
569#  function => "function name"
570#  parameterlist => @list of parameters
571#  parameterdescs => %parameter descriptions
572#  sectionlist => @list of sections
573#  sections => %section descriptions
574#
575
576sub output_highlight {
577    my $contents = join "\n",@_;
578    my $line;
579
580#   DEBUG
581#   if (!defined $contents) {
582#	use Carp;
583#	confess "output_highlight got called with no args?\n";
584#   }
585
586    if ($output_mode eq "html" || $output_mode eq "html5" ||
587	$output_mode eq "xml") {
588	$contents = local_unescape($contents);
589	# convert data read & converted thru xml_escape() into &xyz; format:
590	$contents =~ s/\\\\\\/\&/g;
591    }
592#   print STDERR "contents b4:$contents\n";
593    eval $dohighlight;
594    die $@ if $@;
595#   print STDERR "contents af:$contents\n";
596
597#   strip whitespaces when generating html5
598    if ($output_mode eq "html5") {
599	$contents =~ s/^\s+//;
600	$contents =~ s/\s+$//;
601    }
602    foreach $line (split "\n", $contents) {
603	if (! $output_preformatted) {
604	    $line =~ s/^\s*//;
605	}
606	if ($line eq ""){
607	    if (! $output_preformatted) {
608		print $lineprefix, local_unescape($blankline);
609	    }
610	} else {
611	    $line =~ s/\\\\\\/\&/g;
612	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
613		print "\\&$line";
614	    } else {
615		print $lineprefix, $line;
616	    }
617	}
618	print "\n";
619    }
620}
621
622# output sections in html
623sub output_section_html(%) {
624    my %args = %{$_[0]};
625    my $section;
626
627    foreach $section (@{$args{'sectionlist'}}) {
628	print "<h3>$section</h3>\n";
629	print "<blockquote>\n";
630	output_highlight($args{'sections'}{$section});
631	print "</blockquote>\n";
632    }
633}
634
635# output enum in html
636sub output_enum_html(%) {
637    my %args = %{$_[0]};
638    my ($parameter);
639    my $count;
640    print "<h2>enum " . $args{'enum'} . "</h2>\n";
641
642    print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
643    $count = 0;
644    foreach $parameter (@{$args{'parameterlist'}}) {
645	print " <b>" . $parameter . "</b>";
646	if ($count != $#{$args{'parameterlist'}}) {
647	    $count++;
648	    print ",\n";
649	}
650	print "<br>";
651    }
652    print "};<br>\n";
653
654    print "<h3>Constants</h3>\n";
655    print "<dl>\n";
656    foreach $parameter (@{$args{'parameterlist'}}) {
657	print "<dt><b>" . $parameter . "</b>\n";
658	print "<dd>";
659	output_highlight($args{'parameterdescs'}{$parameter});
660    }
661    print "</dl>\n";
662    output_section_html(@_);
663    print "<hr>\n";
664}
665
666# output typedef in html
667sub output_typedef_html(%) {
668    my %args = %{$_[0]};
669    my ($parameter);
670    my $count;
671    print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
672
673    print "<b>typedef " . $args{'typedef'} . "</b>\n";
674    output_section_html(@_);
675    print "<hr>\n";
676}
677
678# output struct in html
679sub output_struct_html(%) {
680    my %args = %{$_[0]};
681    my ($parameter);
682
683    print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
684    print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
685    foreach $parameter (@{$args{'parameterlist'}}) {
686	if ($parameter =~ /^#/) {
687		print "$parameter<br>\n";
688		next;
689	}
690	my $parameter_name = $parameter;
691	$parameter_name =~ s/\[.*//;
692
693	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
694	$type = $args{'parametertypes'}{$parameter};
695	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
696	    # pointer-to-function
697	    print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
698	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
699	    # bitfield
700	    print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
701	} else {
702	    print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
703	}
704    }
705    print "};<br>\n";
706
707    print "<h3>Members</h3>\n";
708    print "<dl>\n";
709    foreach $parameter (@{$args{'parameterlist'}}) {
710	($parameter =~ /^#/) && next;
711
712	my $parameter_name = $parameter;
713	$parameter_name =~ s/\[.*//;
714
715	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
716	print "<dt><b>" . $parameter . "</b>\n";
717	print "<dd>";
718	output_highlight($args{'parameterdescs'}{$parameter_name});
719    }
720    print "</dl>\n";
721    output_section_html(@_);
722    print "<hr>\n";
723}
724
725# output function in html
726sub output_function_html(%) {
727    my %args = %{$_[0]};
728    my ($parameter, $section);
729    my $count;
730
731    print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
732    print "<i>" . $args{'functiontype'} . "</i>\n";
733    print "<b>" . $args{'function'} . "</b>\n";
734    print "(";
735    $count = 0;
736    foreach $parameter (@{$args{'parameterlist'}}) {
737	$type = $args{'parametertypes'}{$parameter};
738	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
739	    # pointer-to-function
740	    print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
741	} else {
742	    print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
743	}
744	if ($count != $#{$args{'parameterlist'}}) {
745	    $count++;
746	    print ",\n";
747	}
748    }
749    print ")\n";
750
751    print "<h3>Arguments</h3>\n";
752    print "<dl>\n";
753    foreach $parameter (@{$args{'parameterlist'}}) {
754	my $parameter_name = $parameter;
755	$parameter_name =~ s/\[.*//;
756
757	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
758	print "<dt><b>" . $parameter . "</b>\n";
759	print "<dd>";
760	output_highlight($args{'parameterdescs'}{$parameter_name});
761    }
762    print "</dl>\n";
763    output_section_html(@_);
764    print "<hr>\n";
765}
766
767# output DOC: block header in html
768sub output_blockhead_html(%) {
769    my %args = %{$_[0]};
770    my ($parameter, $section);
771    my $count;
772
773    foreach $section (@{$args{'sectionlist'}}) {
774	print "<h3>$section</h3>\n";
775	print "<ul>\n";
776	output_highlight($args{'sections'}{$section});
777	print "</ul>\n";
778    }
779    print "<hr>\n";
780}
781
782# output sections in html5
783sub output_section_html5(%) {
784    my %args = %{$_[0]};
785    my $section;
786
787    foreach $section (@{$args{'sectionlist'}}) {
788	print "<section>\n";
789	print "<h1>$section</h1>\n";
790	print "<p>\n";
791	output_highlight($args{'sections'}{$section});
792	print "</p>\n";
793	print "</section>\n";
794    }
795}
796
797# output enum in html5
798sub output_enum_html5(%) {
799    my %args = %{$_[0]};
800    my ($parameter);
801    my $count;
802    my $html5id;
803
804    $html5id = $args{'enum'};
805    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
806    print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
807    print "<h1>enum " . $args{'enum'} . "</h1>\n";
808    print "<ol class=\"code\">\n";
809    print "<li>";
810    print "<span class=\"keyword\">enum</span> ";
811    print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
812    print "</li>\n";
813    $count = 0;
814    foreach $parameter (@{$args{'parameterlist'}}) {
815	print "<li class=\"indent\">";
816	print "<span class=\"param\">" . $parameter . "</span>";
817	if ($count != $#{$args{'parameterlist'}}) {
818	    $count++;
819	    print ",";
820	}
821	print "</li>\n";
822    }
823    print "<li>};</li>\n";
824    print "</ol>\n";
825
826    print "<section>\n";
827    print "<h1>Constants</h1>\n";
828    print "<dl>\n";
829    foreach $parameter (@{$args{'parameterlist'}}) {
830	print "<dt>" . $parameter . "</dt>\n";
831	print "<dd>";
832	output_highlight($args{'parameterdescs'}{$parameter});
833	print "</dd>\n";
834    }
835    print "</dl>\n";
836    print "</section>\n";
837    output_section_html5(@_);
838    print "</article>\n";
839}
840
841# output typedef in html5
842sub output_typedef_html5(%) {
843    my %args = %{$_[0]};
844    my ($parameter);
845    my $count;
846    my $html5id;
847
848    $html5id = $args{'typedef'};
849    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
850    print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
851    print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
852
853    print "<ol class=\"code\">\n";
854    print "<li>";
855    print "<span class=\"keyword\">typedef</span> ";
856    print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
857    print "</li>\n";
858    print "</ol>\n";
859    output_section_html5(@_);
860    print "</article>\n";
861}
862
863# output struct in html5
864sub output_struct_html5(%) {
865    my %args = %{$_[0]};
866    my ($parameter);
867    my $html5id;
868
869    $html5id = $args{'struct'};
870    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
871    print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
872    print "<hgroup>\n";
873    print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
874    print "<h2>". $args{'purpose'} . "</h2>\n";
875    print "</hgroup>\n";
876    print "<ol class=\"code\">\n";
877    print "<li>";
878    print "<span class=\"type\">" . $args{'type'} . "</span> ";
879    print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
880    print "</li>\n";
881    foreach $parameter (@{$args{'parameterlist'}}) {
882	print "<li class=\"indent\">";
883	if ($parameter =~ /^#/) {
884		print "<span class=\"param\">" . $parameter ."</span>\n";
885		print "</li>\n";
886		next;
887	}
888	my $parameter_name = $parameter;
889	$parameter_name =~ s/\[.*//;
890
891	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
892	$type = $args{'parametertypes'}{$parameter};
893	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
894	    # pointer-to-function
895	    print "<span class=\"type\">$1</span> ";
896	    print "<span class=\"param\">$parameter</span>";
897	    print "<span class=\"type\">)</span> ";
898	    print "(<span class=\"args\">$2</span>);";
899	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
900	    # bitfield
901	    print "<span class=\"type\">$1</span> ";
902	    print "<span class=\"param\">$parameter</span>";
903	    print "<span class=\"bits\">$2</span>;";
904	} else {
905	    print "<span class=\"type\">$type</span> ";
906	    print "<span class=\"param\">$parameter</span>;";
907	}
908	print "</li>\n";
909    }
910    print "<li>};</li>\n";
911    print "</ol>\n";
912
913    print "<section>\n";
914    print "<h1>Members</h1>\n";
915    print "<dl>\n";
916    foreach $parameter (@{$args{'parameterlist'}}) {
917	($parameter =~ /^#/) && next;
918
919	my $parameter_name = $parameter;
920	$parameter_name =~ s/\[.*//;
921
922	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
923	print "<dt>" . $parameter . "</dt>\n";
924	print "<dd>";
925	output_highlight($args{'parameterdescs'}{$parameter_name});
926	print "</dd>\n";
927    }
928    print "</dl>\n";
929    print "</section>\n";
930    output_section_html5(@_);
931    print "</article>\n";
932}
933
934# output function in html5
935sub output_function_html5(%) {
936    my %args = %{$_[0]};
937    my ($parameter, $section);
938    my $count;
939    my $html5id;
940
941    $html5id = $args{'function'};
942    $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
943    print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
944    print "<hgroup>\n";
945    print "<h1>" . $args{'function'} . "</h1>";
946    print "<h2>" . $args{'purpose'} . "</h2>\n";
947    print "</hgroup>\n";
948    print "<ol class=\"code\">\n";
949    print "<li>";
950    print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
951    print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
952    print "</li>";
953    $count = 0;
954    foreach $parameter (@{$args{'parameterlist'}}) {
955	print "<li class=\"indent\">";
956	$type = $args{'parametertypes'}{$parameter};
957	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
958	    # pointer-to-function
959	    print "<span class=\"type\">$1</span> ";
960	    print "<span class=\"param\">$parameter</span>";
961	    print "<span class=\"type\">)</span> ";
962	    print "(<span class=\"args\">$2</span>)";
963	} else {
964	    print "<span class=\"type\">$type</span> ";
965	    print "<span class=\"param\">$parameter</span>";
966	}
967	if ($count != $#{$args{'parameterlist'}}) {
968	    $count++;
969	    print ",";
970	}
971	print "</li>\n";
972    }
973    print "<li>)</li>\n";
974    print "</ol>\n";
975
976    print "<section>\n";
977    print "<h1>Arguments</h1>\n";
978    print "<p>\n";
979    print "<dl>\n";
980    foreach $parameter (@{$args{'parameterlist'}}) {
981	my $parameter_name = $parameter;
982	$parameter_name =~ s/\[.*//;
983
984	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
985	print "<dt>" . $parameter . "</dt>\n";
986	print "<dd>";
987	output_highlight($args{'parameterdescs'}{$parameter_name});
988	print "</dd>\n";
989    }
990    print "</dl>\n";
991    print "</section>\n";
992    output_section_html5(@_);
993    print "</article>\n";
994}
995
996# output DOC: block header in html5
997sub output_blockhead_html5(%) {
998    my %args = %{$_[0]};
999    my ($parameter, $section);
1000    my $count;
1001    my $html5id;
1002
1003    foreach $section (@{$args{'sectionlist'}}) {
1004	$html5id = $section;
1005	$html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1006	print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
1007	print "<h1>$section</h1>\n";
1008	print "<p>\n";
1009	output_highlight($args{'sections'}{$section});
1010	print "</p>\n";
1011    }
1012    print "</article>\n";
1013}
1014
1015sub output_section_xml(%) {
1016    my %args = %{$_[0]};
1017    my $section;
1018    # print out each section
1019    $lineprefix="   ";
1020    foreach $section (@{$args{'sectionlist'}}) {
1021	print "<refsect1>\n";
1022	print "<title>$section</title>\n";
1023	if ($section =~ m/EXAMPLE/i) {
1024	    print "<informalexample><programlisting>\n";
1025	    $output_preformatted = 1;
1026	} else {
1027	    print "<para>\n";
1028	}
1029	output_highlight($args{'sections'}{$section});
1030	$output_preformatted = 0;
1031	if ($section =~ m/EXAMPLE/i) {
1032	    print "</programlisting></informalexample>\n";
1033	} else {
1034	    print "</para>\n";
1035	}
1036	print "</refsect1>\n";
1037    }
1038}
1039
1040# output function in XML DocBook
1041sub output_function_xml(%) {
1042    my %args = %{$_[0]};
1043    my ($parameter, $section);
1044    my $count;
1045    my $id;
1046
1047    $id = "API-" . $args{'function'};
1048    $id =~ s/[^A-Za-z0-9]/-/g;
1049
1050    print "<refentry id=\"$id\">\n";
1051    print "<refentryinfo>\n";
1052    print " <title>LINUX</title>\n";
1053    print " <productname>Kernel Hackers Manual</productname>\n";
1054    print " <date>$man_date</date>\n";
1055    print "</refentryinfo>\n";
1056    print "<refmeta>\n";
1057    print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
1058    print " <manvolnum>9</manvolnum>\n";
1059    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1060    print "</refmeta>\n";
1061    print "<refnamediv>\n";
1062    print " <refname>" . $args{'function'} . "</refname>\n";
1063    print " <refpurpose>\n";
1064    print "  ";
1065    output_highlight ($args{'purpose'});
1066    print " </refpurpose>\n";
1067    print "</refnamediv>\n";
1068
1069    print "<refsynopsisdiv>\n";
1070    print " <title>Synopsis</title>\n";
1071    print "  <funcsynopsis><funcprototype>\n";
1072    print "   <funcdef>" . $args{'functiontype'} . " ";
1073    print "<function>" . $args{'function'} . " </function></funcdef>\n";
1074
1075    $count = 0;
1076    if ($#{$args{'parameterlist'}} >= 0) {
1077	foreach $parameter (@{$args{'parameterlist'}}) {
1078	    $type = $args{'parametertypes'}{$parameter};
1079	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1080		# pointer-to-function
1081		print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
1082		print "     <funcparams>$2</funcparams></paramdef>\n";
1083	    } else {
1084		print "   <paramdef>" . $type;
1085		print " <parameter>$parameter</parameter></paramdef>\n";
1086	    }
1087	}
1088    } else {
1089	print "  <void/>\n";
1090    }
1091    print "  </funcprototype></funcsynopsis>\n";
1092    print "</refsynopsisdiv>\n";
1093
1094    # print parameters
1095    print "<refsect1>\n <title>Arguments</title>\n";
1096    if ($#{$args{'parameterlist'}} >= 0) {
1097	print " <variablelist>\n";
1098	foreach $parameter (@{$args{'parameterlist'}}) {
1099	    my $parameter_name = $parameter;
1100	    $parameter_name =~ s/\[.*//;
1101
1102	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
1103	    print "   <listitem>\n    <para>\n";
1104	    $lineprefix="     ";
1105	    output_highlight($args{'parameterdescs'}{$parameter_name});
1106	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
1107	}
1108	print " </variablelist>\n";
1109    } else {
1110	print " <para>\n  None\n </para>\n";
1111    }
1112    print "</refsect1>\n";
1113
1114    output_section_xml(@_);
1115    print "</refentry>\n\n";
1116}
1117
1118# output struct in XML DocBook
1119sub output_struct_xml(%) {
1120    my %args = %{$_[0]};
1121    my ($parameter, $section);
1122    my $id;
1123
1124    $id = "API-struct-" . $args{'struct'};
1125    $id =~ s/[^A-Za-z0-9]/-/g;
1126
1127    print "<refentry id=\"$id\">\n";
1128    print "<refentryinfo>\n";
1129    print " <title>LINUX</title>\n";
1130    print " <productname>Kernel Hackers Manual</productname>\n";
1131    print " <date>$man_date</date>\n";
1132    print "</refentryinfo>\n";
1133    print "<refmeta>\n";
1134    print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1135    print " <manvolnum>9</manvolnum>\n";
1136    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1137    print "</refmeta>\n";
1138    print "<refnamediv>\n";
1139    print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1140    print " <refpurpose>\n";
1141    print "  ";
1142    output_highlight ($args{'purpose'});
1143    print " </refpurpose>\n";
1144    print "</refnamediv>\n";
1145
1146    print "<refsynopsisdiv>\n";
1147    print " <title>Synopsis</title>\n";
1148    print "  <programlisting>\n";
1149    print $args{'type'} . " " . $args{'struct'} . " {\n";
1150    foreach $parameter (@{$args{'parameterlist'}}) {
1151	if ($parameter =~ /^#/) {
1152	    my $prm = $parameter;
1153	    # convert data read & converted thru xml_escape() into &xyz; format:
1154	    # This allows us to have #define macros interspersed in a struct.
1155	    $prm =~ s/\\\\\\/\&/g;
1156	    print "$prm\n";
1157	    next;
1158	}
1159
1160	my $parameter_name = $parameter;
1161	$parameter_name =~ s/\[.*//;
1162
1163	defined($args{'parameterdescs'}{$parameter_name}) || next;
1164	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1165	$type = $args{'parametertypes'}{$parameter};
1166	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1167	    # pointer-to-function
1168	    print "  $1 $parameter) ($2);\n";
1169	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1170	    # bitfield
1171	    print "  $1 $parameter$2;\n";
1172	} else {
1173	    print "  " . $type . " " . $parameter . ";\n";
1174	}
1175    }
1176    print "};";
1177    print "  </programlisting>\n";
1178    print "</refsynopsisdiv>\n";
1179
1180    print " <refsect1>\n";
1181    print "  <title>Members</title>\n";
1182
1183    if ($#{$args{'parameterlist'}} >= 0) {
1184    print "  <variablelist>\n";
1185    foreach $parameter (@{$args{'parameterlist'}}) {
1186      ($parameter =~ /^#/) && next;
1187
1188      my $parameter_name = $parameter;
1189      $parameter_name =~ s/\[.*//;
1190
1191      defined($args{'parameterdescs'}{$parameter_name}) || next;
1192      ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1193      print "    <varlistentry>";
1194      print "      <term>$parameter</term>\n";
1195      print "      <listitem><para>\n";
1196      output_highlight($args{'parameterdescs'}{$parameter_name});
1197      print "      </para></listitem>\n";
1198      print "    </varlistentry>\n";
1199    }
1200    print "  </variablelist>\n";
1201    } else {
1202	print " <para>\n  None\n </para>\n";
1203    }
1204    print " </refsect1>\n";
1205
1206    output_section_xml(@_);
1207
1208    print "</refentry>\n\n";
1209}
1210
1211# output enum in XML DocBook
1212sub output_enum_xml(%) {
1213    my %args = %{$_[0]};
1214    my ($parameter, $section);
1215    my $count;
1216    my $id;
1217
1218    $id = "API-enum-" . $args{'enum'};
1219    $id =~ s/[^A-Za-z0-9]/-/g;
1220
1221    print "<refentry id=\"$id\">\n";
1222    print "<refentryinfo>\n";
1223    print " <title>LINUX</title>\n";
1224    print " <productname>Kernel Hackers Manual</productname>\n";
1225    print " <date>$man_date</date>\n";
1226    print "</refentryinfo>\n";
1227    print "<refmeta>\n";
1228    print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1229    print " <manvolnum>9</manvolnum>\n";
1230    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1231    print "</refmeta>\n";
1232    print "<refnamediv>\n";
1233    print " <refname>enum " . $args{'enum'} . "</refname>\n";
1234    print " <refpurpose>\n";
1235    print "  ";
1236    output_highlight ($args{'purpose'});
1237    print " </refpurpose>\n";
1238    print "</refnamediv>\n";
1239
1240    print "<refsynopsisdiv>\n";
1241    print " <title>Synopsis</title>\n";
1242    print "  <programlisting>\n";
1243    print "enum " . $args{'enum'} . " {\n";
1244    $count = 0;
1245    foreach $parameter (@{$args{'parameterlist'}}) {
1246	print "  $parameter";
1247	if ($count != $#{$args{'parameterlist'}}) {
1248	    $count++;
1249	    print ",";
1250	}
1251	print "\n";
1252    }
1253    print "};";
1254    print "  </programlisting>\n";
1255    print "</refsynopsisdiv>\n";
1256
1257    print "<refsect1>\n";
1258    print " <title>Constants</title>\n";
1259    print "  <variablelist>\n";
1260    foreach $parameter (@{$args{'parameterlist'}}) {
1261      my $parameter_name = $parameter;
1262      $parameter_name =~ s/\[.*//;
1263
1264      print "    <varlistentry>";
1265      print "      <term>$parameter</term>\n";
1266      print "      <listitem><para>\n";
1267      output_highlight($args{'parameterdescs'}{$parameter_name});
1268      print "      </para></listitem>\n";
1269      print "    </varlistentry>\n";
1270    }
1271    print "  </variablelist>\n";
1272    print "</refsect1>\n";
1273
1274    output_section_xml(@_);
1275
1276    print "</refentry>\n\n";
1277}
1278
1279# output typedef in XML DocBook
1280sub output_typedef_xml(%) {
1281    my %args = %{$_[0]};
1282    my ($parameter, $section);
1283    my $id;
1284
1285    $id = "API-typedef-" . $args{'typedef'};
1286    $id =~ s/[^A-Za-z0-9]/-/g;
1287
1288    print "<refentry id=\"$id\">\n";
1289    print "<refentryinfo>\n";
1290    print " <title>LINUX</title>\n";
1291    print " <productname>Kernel Hackers Manual</productname>\n";
1292    print " <date>$man_date</date>\n";
1293    print "</refentryinfo>\n";
1294    print "<refmeta>\n";
1295    print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1296    print " <manvolnum>9</manvolnum>\n";
1297    print "</refmeta>\n";
1298    print "<refnamediv>\n";
1299    print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1300    print " <refpurpose>\n";
1301    print "  ";
1302    output_highlight ($args{'purpose'});
1303    print " </refpurpose>\n";
1304    print "</refnamediv>\n";
1305
1306    print "<refsynopsisdiv>\n";
1307    print " <title>Synopsis</title>\n";
1308    print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1309    print "</refsynopsisdiv>\n";
1310
1311    output_section_xml(@_);
1312
1313    print "</refentry>\n\n";
1314}
1315
1316# output in XML DocBook
1317sub output_blockhead_xml(%) {
1318    my %args = %{$_[0]};
1319    my ($parameter, $section);
1320    my $count;
1321
1322    my $id = $args{'module'};
1323    $id =~ s/[^A-Za-z0-9]/-/g;
1324
1325    # print out each section
1326    $lineprefix="   ";
1327    foreach $section (@{$args{'sectionlist'}}) {
1328	if (!$args{'content-only'}) {
1329		print "<refsect1>\n <title>$section</title>\n";
1330	}
1331	if ($section =~ m/EXAMPLE/i) {
1332	    print "<example><para>\n";
1333	    $output_preformatted = 1;
1334	} else {
1335	    print "<para>\n";
1336	}
1337	output_highlight($args{'sections'}{$section});
1338	$output_preformatted = 0;
1339	if ($section =~ m/EXAMPLE/i) {
1340	    print "</para></example>\n";
1341	} else {
1342	    print "</para>";
1343	}
1344	if (!$args{'content-only'}) {
1345		print "\n</refsect1>\n";
1346	}
1347    }
1348
1349    print "\n\n";
1350}
1351
1352# output in XML DocBook
1353sub output_function_gnome {
1354    my %args = %{$_[0]};
1355    my ($parameter, $section);
1356    my $count;
1357    my $id;
1358
1359    $id = $args{'module'} . "-" . $args{'function'};
1360    $id =~ s/[^A-Za-z0-9]/-/g;
1361
1362    print "<sect2>\n";
1363    print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1364
1365    print "  <funcsynopsis>\n";
1366    print "   <funcdef>" . $args{'functiontype'} . " ";
1367    print "<function>" . $args{'function'} . " ";
1368    print "</function></funcdef>\n";
1369
1370    $count = 0;
1371    if ($#{$args{'parameterlist'}} >= 0) {
1372	foreach $parameter (@{$args{'parameterlist'}}) {
1373	    $type = $args{'parametertypes'}{$parameter};
1374	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1375		# pointer-to-function
1376		print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
1377		print "     <funcparams>$2</funcparams></paramdef>\n";
1378	    } else {
1379		print "   <paramdef>" . $type;
1380		print " <parameter>$parameter</parameter></paramdef>\n";
1381	    }
1382	}
1383    } else {
1384	print "  <void>\n";
1385    }
1386    print "  </funcsynopsis>\n";
1387    if ($#{$args{'parameterlist'}} >= 0) {
1388	print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1389	print "<tgroup cols=\"2\">\n";
1390	print "<colspec colwidth=\"2*\">\n";
1391	print "<colspec colwidth=\"8*\">\n";
1392	print "<tbody>\n";
1393	foreach $parameter (@{$args{'parameterlist'}}) {
1394	    my $parameter_name = $parameter;
1395	    $parameter_name =~ s/\[.*//;
1396
1397	    print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1398	    print "   <entry>\n";
1399	    $lineprefix="     ";
1400	    output_highlight($args{'parameterdescs'}{$parameter_name});
1401	    print "    </entry></row>\n";
1402	}
1403	print " </tbody></tgroup></informaltable>\n";
1404    } else {
1405	print " <para>\n  None\n </para>\n";
1406    }
1407
1408    # print out each section
1409    $lineprefix="   ";
1410    foreach $section (@{$args{'sectionlist'}}) {
1411	print "<simplesect>\n <title>$section</title>\n";
1412	if ($section =~ m/EXAMPLE/i) {
1413	    print "<example><programlisting>\n";
1414	    $output_preformatted = 1;
1415	} else {
1416	}
1417	print "<para>\n";
1418	output_highlight($args{'sections'}{$section});
1419	$output_preformatted = 0;
1420	print "</para>\n";
1421	if ($section =~ m/EXAMPLE/i) {
1422	    print "</programlisting></example>\n";
1423	} else {
1424	}
1425	print " </simplesect>\n";
1426    }
1427
1428    print "</sect2>\n\n";
1429}
1430
1431##
1432# output function in man
1433sub output_function_man(%) {
1434    my %args = %{$_[0]};
1435    my ($parameter, $section);
1436    my $count;
1437
1438    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1439
1440    print ".SH NAME\n";
1441    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1442
1443    print ".SH SYNOPSIS\n";
1444    if ($args{'functiontype'} ne "") {
1445	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1446    } else {
1447	print ".B \"" . $args{'function'} . "\n";
1448    }
1449    $count = 0;
1450    my $parenth = "(";
1451    my $post = ",";
1452    foreach my $parameter (@{$args{'parameterlist'}}) {
1453	if ($count == $#{$args{'parameterlist'}}) {
1454	    $post = ");";
1455	}
1456	$type = $args{'parametertypes'}{$parameter};
1457	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1458	    # pointer-to-function
1459	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1460	} else {
1461	    $type =~ s/([^\*])$/$1 /;
1462	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1463	}
1464	$count++;
1465	$parenth = "";
1466    }
1467
1468    print ".SH ARGUMENTS\n";
1469    foreach $parameter (@{$args{'parameterlist'}}) {
1470	my $parameter_name = $parameter;
1471	$parameter_name =~ s/\[.*//;
1472
1473	print ".IP \"" . $parameter . "\" 12\n";
1474	output_highlight($args{'parameterdescs'}{$parameter_name});
1475    }
1476    foreach $section (@{$args{'sectionlist'}}) {
1477	print ".SH \"", uc $section, "\"\n";
1478	output_highlight($args{'sections'}{$section});
1479    }
1480}
1481
1482##
1483# output enum in man
1484sub output_enum_man(%) {
1485    my %args = %{$_[0]};
1486    my ($parameter, $section);
1487    my $count;
1488
1489    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1490
1491    print ".SH NAME\n";
1492    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1493
1494    print ".SH SYNOPSIS\n";
1495    print "enum " . $args{'enum'} . " {\n";
1496    $count = 0;
1497    foreach my $parameter (@{$args{'parameterlist'}}) {
1498	print ".br\n.BI \"    $parameter\"\n";
1499	if ($count == $#{$args{'parameterlist'}}) {
1500	    print "\n};\n";
1501	    last;
1502	}
1503	else {
1504	    print ", \n.br\n";
1505	}
1506	$count++;
1507    }
1508
1509    print ".SH Constants\n";
1510    foreach $parameter (@{$args{'parameterlist'}}) {
1511	my $parameter_name = $parameter;
1512	$parameter_name =~ s/\[.*//;
1513
1514	print ".IP \"" . $parameter . "\" 12\n";
1515	output_highlight($args{'parameterdescs'}{$parameter_name});
1516    }
1517    foreach $section (@{$args{'sectionlist'}}) {
1518	print ".SH \"$section\"\n";
1519	output_highlight($args{'sections'}{$section});
1520    }
1521}
1522
1523##
1524# output struct in man
1525sub output_struct_man(%) {
1526    my %args = %{$_[0]};
1527    my ($parameter, $section);
1528
1529    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1530
1531    print ".SH NAME\n";
1532    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1533
1534    print ".SH SYNOPSIS\n";
1535    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1536
1537    foreach my $parameter (@{$args{'parameterlist'}}) {
1538	if ($parameter =~ /^#/) {
1539	    print ".BI \"$parameter\"\n.br\n";
1540	    next;
1541	}
1542	my $parameter_name = $parameter;
1543	$parameter_name =~ s/\[.*//;
1544
1545	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1546	$type = $args{'parametertypes'}{$parameter};
1547	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1548	    # pointer-to-function
1549	    print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1550	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1551	    # bitfield
1552	    print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1553	} else {
1554	    $type =~ s/([^\*])$/$1 /;
1555	    print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1556	}
1557	print "\n.br\n";
1558    }
1559    print "};\n.br\n";
1560
1561    print ".SH Members\n";
1562    foreach $parameter (@{$args{'parameterlist'}}) {
1563	($parameter =~ /^#/) && next;
1564
1565	my $parameter_name = $parameter;
1566	$parameter_name =~ s/\[.*//;
1567
1568	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1569	print ".IP \"" . $parameter . "\" 12\n";
1570	output_highlight($args{'parameterdescs'}{$parameter_name});
1571    }
1572    foreach $section (@{$args{'sectionlist'}}) {
1573	print ".SH \"$section\"\n";
1574	output_highlight($args{'sections'}{$section});
1575    }
1576}
1577
1578##
1579# output typedef in man
1580sub output_typedef_man(%) {
1581    my %args = %{$_[0]};
1582    my ($parameter, $section);
1583
1584    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1585
1586    print ".SH NAME\n";
1587    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1588
1589    foreach $section (@{$args{'sectionlist'}}) {
1590	print ".SH \"$section\"\n";
1591	output_highlight($args{'sections'}{$section});
1592    }
1593}
1594
1595sub output_blockhead_man(%) {
1596    my %args = %{$_[0]};
1597    my ($parameter, $section);
1598    my $count;
1599
1600    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1601
1602    foreach $section (@{$args{'sectionlist'}}) {
1603	print ".SH \"$section\"\n";
1604	output_highlight($args{'sections'}{$section});
1605    }
1606}
1607
1608##
1609# output in text
1610sub output_function_text(%) {
1611    my %args = %{$_[0]};
1612    my ($parameter, $section);
1613    my $start;
1614
1615    print "Name:\n\n";
1616    print $args{'function'} . " - " . $args{'purpose'} . "\n";
1617
1618    print "\nSynopsis:\n\n";
1619    if ($args{'functiontype'} ne "") {
1620	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
1621    } else {
1622	$start = $args{'function'} . " (";
1623    }
1624    print $start;
1625
1626    my $count = 0;
1627    foreach my $parameter (@{$args{'parameterlist'}}) {
1628	$type = $args{'parametertypes'}{$parameter};
1629	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1630	    # pointer-to-function
1631	    print $1 . $parameter . ") (" . $2;
1632	} else {
1633	    print $type . " " . $parameter;
1634	}
1635	if ($count != $#{$args{'parameterlist'}}) {
1636	    $count++;
1637	    print ",\n";
1638	    print " " x length($start);
1639	} else {
1640	    print ");\n\n";
1641	}
1642    }
1643
1644    print "Arguments:\n\n";
1645    foreach $parameter (@{$args{'parameterlist'}}) {
1646	my $parameter_name = $parameter;
1647	$parameter_name =~ s/\[.*//;
1648
1649	print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1650    }
1651    output_section_text(@_);
1652}
1653
1654#output sections in text
1655sub output_section_text(%) {
1656    my %args = %{$_[0]};
1657    my $section;
1658
1659    print "\n";
1660    foreach $section (@{$args{'sectionlist'}}) {
1661	print "$section:\n\n";
1662	output_highlight($args{'sections'}{$section});
1663    }
1664    print "\n\n";
1665}
1666
1667# output enum in text
1668sub output_enum_text(%) {
1669    my %args = %{$_[0]};
1670    my ($parameter);
1671    my $count;
1672    print "Enum:\n\n";
1673
1674    print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1675    print "enum " . $args{'enum'} . " {\n";
1676    $count = 0;
1677    foreach $parameter (@{$args{'parameterlist'}}) {
1678	print "\t$parameter";
1679	if ($count != $#{$args{'parameterlist'}}) {
1680	    $count++;
1681	    print ",";
1682	}
1683	print "\n";
1684    }
1685    print "};\n\n";
1686
1687    print "Constants:\n\n";
1688    foreach $parameter (@{$args{'parameterlist'}}) {
1689	print "$parameter\n\t";
1690	print $args{'parameterdescs'}{$parameter} . "\n";
1691    }
1692
1693    output_section_text(@_);
1694}
1695
1696# output typedef in text
1697sub output_typedef_text(%) {
1698    my %args = %{$_[0]};
1699    my ($parameter);
1700    my $count;
1701    print "Typedef:\n\n";
1702
1703    print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1704    output_section_text(@_);
1705}
1706
1707# output struct as text
1708sub output_struct_text(%) {
1709    my %args = %{$_[0]};
1710    my ($parameter);
1711
1712    print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1713    print $args{'type'} . " " . $args{'struct'} . " {\n";
1714    foreach $parameter (@{$args{'parameterlist'}}) {
1715	if ($parameter =~ /^#/) {
1716	    print "$parameter\n";
1717	    next;
1718	}
1719
1720	my $parameter_name = $parameter;
1721	$parameter_name =~ s/\[.*//;
1722
1723	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1724	$type = $args{'parametertypes'}{$parameter};
1725	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1726	    # pointer-to-function
1727	    print "\t$1 $parameter) ($2);\n";
1728	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1729	    # bitfield
1730	    print "\t$1 $parameter$2;\n";
1731	} else {
1732	    print "\t" . $type . " " . $parameter . ";\n";
1733	}
1734    }
1735    print "};\n\n";
1736
1737    print "Members:\n\n";
1738    foreach $parameter (@{$args{'parameterlist'}}) {
1739	($parameter =~ /^#/) && next;
1740
1741	my $parameter_name = $parameter;
1742	$parameter_name =~ s/\[.*//;
1743
1744	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1745	print "$parameter\n\t";
1746	print $args{'parameterdescs'}{$parameter_name} . "\n";
1747    }
1748    print "\n";
1749    output_section_text(@_);
1750}
1751
1752sub output_blockhead_text(%) {
1753    my %args = %{$_[0]};
1754    my ($parameter, $section);
1755
1756    foreach $section (@{$args{'sectionlist'}}) {
1757	print " $section:\n";
1758	print "    -> ";
1759	output_highlight($args{'sections'}{$section});
1760    }
1761}
1762
1763##
1764# output in restructured text
1765#
1766
1767#
1768# This could use some work; it's used to output the DOC: sections, and
1769# starts by putting out the name of the doc section itself, but that tends
1770# to duplicate a header already in the template file.
1771#
1772sub output_blockhead_rst(%) {
1773    my %args = %{$_[0]};
1774    my ($parameter, $section);
1775
1776    foreach $section (@{$args{'sectionlist'}}) {
1777	if ($output_selection != OUTPUT_INCLUDE) {
1778	    print "**$section**\n\n";
1779	}
1780	output_highlight_rst($args{'sections'}{$section});
1781	print "\n";
1782    }
1783}
1784
1785sub output_highlight_rst {
1786    my $contents = join "\n",@_;
1787    my $line;
1788
1789    # undo the evil effects of xml_escape() earlier
1790    $contents = xml_unescape($contents);
1791
1792    eval $dohighlight;
1793    die $@ if $@;
1794
1795    foreach $line (split "\n", $contents) {
1796	if ($line eq "") {
1797	    print $lineprefix, $blankline;
1798	} else {
1799	    $line =~ s/\\\\\\/\&/g;
1800	    print $lineprefix, $line;
1801	}
1802	print "\n";
1803    }
1804}
1805
1806sub output_function_rst(%) {
1807    my %args = %{$_[0]};
1808    my ($parameter, $section);
1809    my $start;
1810
1811    print ".. c:function:: ";
1812    if ($args{'functiontype'} ne "") {
1813	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
1814    } else {
1815	$start = $args{'function'} . " (";
1816    }
1817    print $start;
1818
1819    my $count = 0;
1820    foreach my $parameter (@{$args{'parameterlist'}}) {
1821	if ($count ne 0) {
1822	    print ", ";
1823	}
1824	$count++;
1825	$type = $args{'parametertypes'}{$parameter};
1826	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1827	    # pointer-to-function
1828	    print $1 . $parameter . ") (" . $2;
1829	} else {
1830	    print $type . " " . $parameter;
1831	}
1832    }
1833    print ")\n\n    " . $args{'purpose'} . "\n\n";
1834
1835    print ":Parameters:\n\n";
1836    foreach $parameter (@{$args{'parameterlist'}}) {
1837	my $parameter_name = $parameter;
1838	#$parameter_name =~ s/\[.*//;
1839	$type = $args{'parametertypes'}{$parameter};
1840
1841	if ($type ne "") {
1842	    print "      ``$type $parameter``\n";
1843	} else {
1844	    print "      ``$parameter``\n";
1845	}
1846	if (defined($args{'parameterdescs'}{$parameter_name}) &&
1847	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1848	    my $oldprefix = $lineprefix;
1849	    $lineprefix = "        ";
1850	    output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1851	    $lineprefix = $oldprefix;
1852	} else {
1853	    print "\n        _undescribed_\n";
1854	}
1855	print "\n";
1856    }
1857    output_section_rst(@_);
1858}
1859
1860sub output_section_rst(%) {
1861    my %args = %{$_[0]};
1862    my $section;
1863    my $oldprefix = $lineprefix;
1864    $lineprefix = "        ";
1865
1866    foreach $section (@{$args{'sectionlist'}}) {
1867	print ":$section:\n\n";
1868	output_highlight_rst($args{'sections'}{$section});
1869	print "\n";
1870    }
1871    print "\n";
1872    $lineprefix = $oldprefix;
1873}
1874
1875sub output_enum_rst(%) {
1876    my %args = %{$_[0]};
1877    my ($parameter);
1878    my $count;
1879    my $name = "enum " . $args{'enum'};
1880
1881    print "\n\n.. c:type:: " . $name . "\n\n";
1882    print "    " . $args{'purpose'} . "\n\n";
1883
1884    print "..\n\n:Constants:\n\n";
1885    my $oldprefix = $lineprefix;
1886    $lineprefix = "    ";
1887    foreach $parameter (@{$args{'parameterlist'}}) {
1888	print "  `$parameter`\n";
1889	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1890	    output_highlight_rst($args{'parameterdescs'}{$parameter});
1891	} else {
1892	    print "    undescribed\n";
1893	}
1894	print "\n";
1895    }
1896    $lineprefix = $oldprefix;
1897    output_section_rst(@_);
1898}
1899
1900sub output_typedef_rst(%) {
1901    my %args = %{$_[0]};
1902    my ($parameter);
1903    my $count;
1904    my $name = "typedef " . $args{'typedef'};
1905
1906    ### FIXME: should the name below contain "typedef" or not?
1907    print "\n\n.. c:type:: " . $name . "\n\n";
1908    print "    " . $args{'purpose'} . "\n\n";
1909
1910    output_section_rst(@_);
1911}
1912
1913sub output_struct_rst(%) {
1914    my %args = %{$_[0]};
1915    my ($parameter);
1916    my $name = $args{'type'} . " " . $args{'struct'};
1917
1918    print "\n\n.. c:type:: " . $name . "\n\n";
1919    print "    " . $args{'purpose'} . "\n\n";
1920
1921    print ":Definition:\n\n";
1922    print " ::\n\n";
1923    print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
1924    foreach $parameter (@{$args{'parameterlist'}}) {
1925	if ($parameter =~ /^#/) {
1926	    print "    " . "$parameter\n";
1927	    next;
1928	}
1929
1930	my $parameter_name = $parameter;
1931	$parameter_name =~ s/\[.*//;
1932
1933	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1934	$type = $args{'parametertypes'}{$parameter};
1935	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1936	    # pointer-to-function
1937	    print "    $1 $parameter) ($2);\n";
1938	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1939	    # bitfield
1940	    print "    $1 $parameter$2;\n";
1941	} else {
1942	    print "    " . $type . " " . $parameter . ";\n";
1943	}
1944    }
1945    print "  };\n\n";
1946
1947    print ":Members:\n\n";
1948    foreach $parameter (@{$args{'parameterlist'}}) {
1949	($parameter =~ /^#/) && next;
1950
1951	my $parameter_name = $parameter;
1952	$parameter_name =~ s/\[.*//;
1953
1954	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1955	$type = $args{'parametertypes'}{$parameter};
1956	print "      `$type $parameter`" . "\n";
1957	my $oldprefix = $lineprefix;
1958	$lineprefix = "        ";
1959	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1960	$lineprefix = $oldprefix;
1961	print "\n";
1962    }
1963    print "\n";
1964    output_section_rst(@_);
1965}
1966
1967
1968## list mode output functions
1969
1970sub output_function_list(%) {
1971    my %args = %{$_[0]};
1972
1973    print $args{'function'} . "\n";
1974}
1975
1976# output enum in list
1977sub output_enum_list(%) {
1978    my %args = %{$_[0]};
1979    print $args{'enum'} . "\n";
1980}
1981
1982# output typedef in list
1983sub output_typedef_list(%) {
1984    my %args = %{$_[0]};
1985    print $args{'typedef'} . "\n";
1986}
1987
1988# output struct as list
1989sub output_struct_list(%) {
1990    my %args = %{$_[0]};
1991
1992    print $args{'struct'} . "\n";
1993}
1994
1995sub output_blockhead_list(%) {
1996    my %args = %{$_[0]};
1997    my ($parameter, $section);
1998
1999    foreach $section (@{$args{'sectionlist'}}) {
2000	print "DOC: $section\n";
2001    }
2002}
2003
2004##
2005# generic output function for all types (function, struct/union, typedef, enum);
2006# calls the generated, variable output_ function name based on
2007# functype and output_mode
2008sub output_declaration {
2009    no strict 'refs';
2010    my $name = shift;
2011    my $functype = shift;
2012    my $func = "output_${functype}_$output_mode";
2013    if (($output_selection == OUTPUT_ALL) ||
2014	(($output_selection == OUTPUT_INCLUDE ||
2015	  $output_selection == OUTPUT_EXPORTED) &&
2016	 defined($function_table{$name})) ||
2017	(($output_selection == OUTPUT_EXCLUDE ||
2018	  $output_selection == OUTPUT_INTERNAL) &&
2019	 !($functype eq "function" && defined($function_table{$name}))))
2020    {
2021	&$func(@_);
2022	$section_counter++;
2023    }
2024}
2025
2026##
2027# generic output function - calls the right one based on current output mode.
2028sub output_blockhead {
2029    no strict 'refs';
2030    my $func = "output_blockhead_" . $output_mode;
2031    &$func(@_);
2032    $section_counter++;
2033}
2034
2035##
2036# takes a declaration (struct, union, enum, typedef) and
2037# invokes the right handler. NOT called for functions.
2038sub dump_declaration($$) {
2039    no strict 'refs';
2040    my ($prototype, $file) = @_;
2041    my $func = "dump_" . $decl_type;
2042    &$func(@_);
2043}
2044
2045sub dump_union($$) {
2046    dump_struct(@_);
2047}
2048
2049sub dump_struct($$) {
2050    my $x = shift;
2051    my $file = shift;
2052    my $nested;
2053
2054    if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2055	#my $decl_type = $1;
2056	$declaration_name = $2;
2057	my $members = $3;
2058
2059	# ignore embedded structs or unions
2060	$members =~ s/({.*})//g;
2061	$nested = $1;
2062
2063	# ignore members marked private:
2064	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2065	$members =~ s/\/\*\s*private:.*//gosi;
2066	# strip comments:
2067	$members =~ s/\/\*.*?\*\///gos;
2068	$nested =~ s/\/\*.*?\*\///gos;
2069	# strip kmemcheck_bitfield_{begin,end}.*;
2070	$members =~ s/kmemcheck_bitfield_.*?;//gos;
2071	# strip attributes
2072	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2073	$members =~ s/__aligned\s*\([^;]*\)//gos;
2074	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2075	# replace DECLARE_BITMAP
2076	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2077
2078	create_parameterlist($members, ';', $file);
2079	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
2080
2081	output_declaration($declaration_name,
2082			   'struct',
2083			   {'struct' => $declaration_name,
2084			    'module' => $modulename,
2085			    'parameterlist' => \@parameterlist,
2086			    'parameterdescs' => \%parameterdescs,
2087			    'parametertypes' => \%parametertypes,
2088			    'sectionlist' => \@sectionlist,
2089			    'sections' => \%sections,
2090			    'purpose' => $declaration_purpose,
2091			    'type' => $decl_type
2092			   });
2093    }
2094    else {
2095	print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2096	++$errors;
2097    }
2098}
2099
2100sub dump_enum($$) {
2101    my $x = shift;
2102    my $file = shift;
2103
2104    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
2105    # strip #define macros inside enums
2106    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2107
2108    if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2109	$declaration_name = $1;
2110	my $members = $2;
2111
2112	foreach my $arg (split ',', $members) {
2113	    $arg =~ s/^\s*(\w+).*/$1/;
2114	    push @parameterlist, $arg;
2115	    if (!$parameterdescs{$arg}) {
2116		$parameterdescs{$arg} = $undescribed;
2117		print STDERR "${file}:$.: warning: Enum value '$arg' ".
2118		    "not described in enum '$declaration_name'\n";
2119	    }
2120
2121	}
2122
2123	output_declaration($declaration_name,
2124			   'enum',
2125			   {'enum' => $declaration_name,
2126			    'module' => $modulename,
2127			    'parameterlist' => \@parameterlist,
2128			    'parameterdescs' => \%parameterdescs,
2129			    'sectionlist' => \@sectionlist,
2130			    'sections' => \%sections,
2131			    'purpose' => $declaration_purpose
2132			   });
2133    }
2134    else {
2135	print STDERR "${file}:$.: error: Cannot parse enum!\n";
2136	++$errors;
2137    }
2138}
2139
2140sub dump_typedef($$) {
2141    my $x = shift;
2142    my $file = shift;
2143
2144    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
2145
2146    # Parse function prototypes
2147    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2148	# Function typedefs
2149	$return_type = $1;
2150	$declaration_name = $2;
2151	my $args = $3;
2152
2153	create_parameterlist($args, ',', $file);
2154
2155	output_declaration($declaration_name,
2156			   'function',
2157			   {'function' => $declaration_name,
2158			    'module' => $modulename,
2159			    'functiontype' => $return_type,
2160			    'parameterlist' => \@parameterlist,
2161			    'parameterdescs' => \%parameterdescs,
2162			    'parametertypes' => \%parametertypes,
2163			    'sectionlist' => \@sectionlist,
2164			    'sections' => \%sections,
2165			    'purpose' => $declaration_purpose
2166			   });
2167	return;
2168    }
2169
2170    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2171	$x =~ s/\(*.\)\s*;$/;/;
2172	$x =~ s/\[*.\]\s*;$/;/;
2173    }
2174
2175    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2176	$declaration_name = $1;
2177
2178	output_declaration($declaration_name,
2179			   'typedef',
2180			   {'typedef' => $declaration_name,
2181			    'module' => $modulename,
2182			    'sectionlist' => \@sectionlist,
2183			    'sections' => \%sections,
2184			    'purpose' => $declaration_purpose
2185			   });
2186    }
2187    else {
2188	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2189	++$errors;
2190    }
2191}
2192
2193sub save_struct_actual($) {
2194    my $actual = shift;
2195
2196    # strip all spaces from the actual param so that it looks like one string item
2197    $actual =~ s/\s*//g;
2198    $struct_actual = $struct_actual . $actual . " ";
2199}
2200
2201sub create_parameterlist($$$) {
2202    my $args = shift;
2203    my $splitter = shift;
2204    my $file = shift;
2205    my $type;
2206    my $param;
2207
2208    # temporarily replace commas inside function pointer definition
2209    while ($args =~ /(\([^\),]+),/) {
2210	$args =~ s/(\([^\),]+),/$1#/g;
2211    }
2212
2213    foreach my $arg (split($splitter, $args)) {
2214	# strip comments
2215	$arg =~ s/\/\*.*\*\///;
2216	# strip leading/trailing spaces
2217	$arg =~ s/^\s*//;
2218	$arg =~ s/\s*$//;
2219	$arg =~ s/\s+/ /;
2220
2221	if ($arg =~ /^#/) {
2222	    # Treat preprocessor directive as a typeless variable just to fill
2223	    # corresponding data structures "correctly". Catch it later in
2224	    # output_* subs.
2225	    push_parameter($arg, "", $file);
2226	} elsif ($arg =~ m/\(.+\)\s*\(/) {
2227	    # pointer-to-function
2228	    $arg =~ tr/#/,/;
2229	    $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2230	    $param = $1;
2231	    $type = $arg;
2232	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2233	    save_struct_actual($param);
2234	    push_parameter($param, $type, $file);
2235	} elsif ($arg) {
2236	    $arg =~ s/\s*:\s*/:/g;
2237	    $arg =~ s/\s*\[/\[/g;
2238
2239	    my @args = split('\s*,\s*', $arg);
2240	    if ($args[0] =~ m/\*/) {
2241		$args[0] =~ s/(\*+)\s*/ $1/;
2242	    }
2243
2244	    my @first_arg;
2245	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2246		    shift @args;
2247		    push(@first_arg, split('\s+', $1));
2248		    push(@first_arg, $2);
2249	    } else {
2250		    @first_arg = split('\s+', shift @args);
2251	    }
2252
2253	    unshift(@args, pop @first_arg);
2254	    $type = join " ", @first_arg;
2255
2256	    foreach $param (@args) {
2257		if ($param =~ m/^(\*+)\s*(.*)/) {
2258		    save_struct_actual($2);
2259		    push_parameter($2, "$type $1", $file);
2260		}
2261		elsif ($param =~ m/(.*?):(\d+)/) {
2262		    if ($type ne "") { # skip unnamed bit-fields
2263			save_struct_actual($1);
2264			push_parameter($1, "$type:$2", $file)
2265		    }
2266		}
2267		else {
2268		    save_struct_actual($param);
2269		    push_parameter($param, $type, $file);
2270		}
2271	    }
2272	}
2273    }
2274}
2275
2276sub push_parameter($$$) {
2277	my $param = shift;
2278	my $type = shift;
2279	my $file = shift;
2280
2281	if (($anon_struct_union == 1) && ($type eq "") &&
2282	    ($param eq "}")) {
2283		return;		# ignore the ending }; from anon. struct/union
2284	}
2285
2286	$anon_struct_union = 0;
2287	my $param_name = $param;
2288	$param_name =~ s/\[.*//;
2289
2290	if ($type eq "" && $param =~ /\.\.\.$/)
2291	{
2292	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2293		$parameterdescs{$param} = "variable arguments";
2294	    }
2295	}
2296	elsif ($type eq "" && ($param eq "" or $param eq "void"))
2297	{
2298	    $param="void";
2299	    $parameterdescs{void} = "no arguments";
2300	}
2301	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2302	# handle unnamed (anonymous) union or struct:
2303	{
2304		$type = $param;
2305		$param = "{unnamed_" . $param . "}";
2306		$parameterdescs{$param} = "anonymous\n";
2307		$anon_struct_union = 1;
2308	}
2309
2310	# warn if parameter has no description
2311	# (but ignore ones starting with # as these are not parameters
2312	# but inline preprocessor statements);
2313	# also ignore unnamed structs/unions;
2314	if (!$anon_struct_union) {
2315	if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2316
2317	    $parameterdescs{$param_name} = $undescribed;
2318
2319	    if (($type eq 'function') || ($type eq 'enum')) {
2320		print STDERR "${file}:$.: warning: Function parameter ".
2321		    "or member '$param' not " .
2322		    "described in '$declaration_name'\n";
2323	    }
2324	    print STDERR "${file}:$.: warning:" .
2325			 " No description found for parameter '$param'\n";
2326	    ++$warnings;
2327	}
2328	}
2329
2330	$param = xml_escape($param);
2331
2332	# strip spaces from $param so that it is one continuous string
2333	# on @parameterlist;
2334	# this fixes a problem where check_sections() cannot find
2335	# a parameter like "addr[6 + 2]" because it actually appears
2336	# as "addr[6", "+", "2]" on the parameter list;
2337	# but it's better to maintain the param string unchanged for output,
2338	# so just weaken the string compare in check_sections() to ignore
2339	# "[blah" in a parameter string;
2340	###$param =~ s/\s*//g;
2341	push @parameterlist, $param;
2342	$parametertypes{$param} = $type;
2343}
2344
2345sub check_sections($$$$$$) {
2346	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2347	my @sects = split ' ', $sectcheck;
2348	my @prms = split ' ', $prmscheck;
2349	my $err;
2350	my ($px, $sx);
2351	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"
2352
2353	foreach $sx (0 .. $#sects) {
2354		$err = 1;
2355		foreach $px (0 .. $#prms) {
2356			$prm_clean = $prms[$px];
2357			$prm_clean =~ s/\[.*\]//;
2358			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2359			# ignore array size in a parameter string;
2360			# however, the original param string may contain
2361			# spaces, e.g.:  addr[6 + 2]
2362			# and this appears in @prms as "addr[6" since the
2363			# parameter list is split at spaces;
2364			# hence just ignore "[..." for the sections check;
2365			$prm_clean =~ s/\[.*//;
2366
2367			##$prm_clean =~ s/^\**//;
2368			if ($prm_clean eq $sects[$sx]) {
2369				$err = 0;
2370				last;
2371			}
2372		}
2373		if ($err) {
2374			if ($decl_type eq "function") {
2375				print STDERR "${file}:$.: warning: " .
2376					"Excess function parameter " .
2377					"'$sects[$sx]' " .
2378					"description in '$decl_name'\n";
2379				++$warnings;
2380			} else {
2381				if ($nested !~ m/\Q$sects[$sx]\E/) {
2382				    print STDERR "${file}:$.: warning: " .
2383					"Excess struct/union/enum/typedef member " .
2384					"'$sects[$sx]' " .
2385					"description in '$decl_name'\n";
2386				    ++$warnings;
2387				}
2388			}
2389		}
2390	}
2391}
2392
2393##
2394# Checks the section describing the return value of a function.
2395sub check_return_section {
2396        my $file = shift;
2397        my $declaration_name = shift;
2398        my $return_type = shift;
2399
2400        # Ignore an empty return type (It's a macro)
2401        # Ignore functions with a "void" return type. (But don't ignore "void *")
2402        if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2403                return;
2404        }
2405
2406        if (!defined($sections{$section_return}) ||
2407            $sections{$section_return} eq "") {
2408                print STDERR "${file}:$.: warning: " .
2409                        "No description found for return value of " .
2410                        "'$declaration_name'\n";
2411                ++$warnings;
2412        }
2413}
2414
2415##
2416# takes a function prototype and the name of the current file being
2417# processed and spits out all the details stored in the global
2418# arrays/hashes.
2419sub dump_function($$) {
2420    my $prototype = shift;
2421    my $file = shift;
2422    my $noret = 0;
2423
2424    $prototype =~ s/^static +//;
2425    $prototype =~ s/^extern +//;
2426    $prototype =~ s/^asmlinkage +//;
2427    $prototype =~ s/^inline +//;
2428    $prototype =~ s/^__inline__ +//;
2429    $prototype =~ s/^__inline +//;
2430    $prototype =~ s/^__always_inline +//;
2431    $prototype =~ s/^noinline +//;
2432    $prototype =~ s/__init +//;
2433    $prototype =~ s/__init_or_module +//;
2434    $prototype =~ s/__meminit +//;
2435    $prototype =~ s/__must_check +//;
2436    $prototype =~ s/__weak +//;
2437    my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2438    $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2439
2440    # Yes, this truly is vile.  We are looking for:
2441    # 1. Return type (may be nothing if we're looking at a macro)
2442    # 2. Function name
2443    # 3. Function parameters.
2444    #
2445    # All the while we have to watch out for function pointer parameters
2446    # (which IIRC is what the two sections are for), C types (these
2447    # regexps don't even start to express all the possibilities), and
2448    # so on.
2449    #
2450    # If you mess with these regexps, it's a good idea to check that
2451    # the following functions' documentation still comes out right:
2452    # - parport_register_device (function pointer parameters)
2453    # - atomic_set (macro)
2454    # - pci_match_device, __copy_to_user (long return type)
2455
2456    if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2457        # This is an object-like macro, it has no return type and no parameter
2458        # list.
2459        # Function-like macros are not allowed to have spaces between
2460        # declaration_name and opening parenthesis (notice the \s+).
2461        $return_type = $1;
2462        $declaration_name = $2;
2463        $noret = 1;
2464    } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2465	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2466	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2467	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2468	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2469	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2470	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2471	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2472	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2473	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2474	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2475	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2476	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2477	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2478	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2479	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2480	$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
2481	$return_type = $1;
2482	$declaration_name = $2;
2483	my $args = $3;
2484
2485	create_parameterlist($args, ',', $file);
2486    } else {
2487	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2488	return;
2489    }
2490
2491	my $prms = join " ", @parameterlist;
2492	check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2493
2494        # This check emits a lot of warnings at the moment, because many
2495        # functions don't have a 'Return' doc section. So until the number
2496        # of warnings goes sufficiently down, the check is only performed in
2497        # verbose mode.
2498        # TODO: always perform the check.
2499        if ($verbose && !$noret) {
2500                check_return_section($file, $declaration_name, $return_type);
2501        }
2502
2503    output_declaration($declaration_name,
2504		       'function',
2505		       {'function' => $declaration_name,
2506			'module' => $modulename,
2507			'functiontype' => $return_type,
2508			'parameterlist' => \@parameterlist,
2509			'parameterdescs' => \%parameterdescs,
2510			'parametertypes' => \%parametertypes,
2511			'sectionlist' => \@sectionlist,
2512			'sections' => \%sections,
2513			'purpose' => $declaration_purpose
2514		       });
2515}
2516
2517sub reset_state {
2518    $function = "";
2519    %constants = ();
2520    %parameterdescs = ();
2521    %parametertypes = ();
2522    @parameterlist = ();
2523    %sections = ();
2524    @sectionlist = ();
2525    $sectcheck = "";
2526    $struct_actual = "";
2527    $prototype = "";
2528
2529    $state = STATE_NORMAL;
2530    $inline_doc_state = STATE_INLINE_NA;
2531}
2532
2533sub tracepoint_munge($) {
2534	my $file = shift;
2535	my $tracepointname = 0;
2536	my $tracepointargs = 0;
2537
2538	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2539		$tracepointname = $1;
2540	}
2541	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2542		$tracepointname = $1;
2543	}
2544	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2545		$tracepointname = $2;
2546	}
2547	$tracepointname =~ s/^\s+//; #strip leading whitespace
2548	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2549		$tracepointargs = $1;
2550	}
2551	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2552		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2553			     "$prototype\n";
2554	} else {
2555		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
2556	}
2557}
2558
2559sub syscall_munge() {
2560	my $void = 0;
2561
2562	$prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2563##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2564	if ($prototype =~ m/SYSCALL_DEFINE0/) {
2565		$void = 1;
2566##		$prototype = "long sys_$1(void)";
2567	}
2568
2569	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2570	if ($prototype =~ m/long (sys_.*?),/) {
2571		$prototype =~ s/,/\(/;
2572	} elsif ($void) {
2573		$prototype =~ s/\)/\(void\)/;
2574	}
2575
2576	# now delete all of the odd-number commas in $prototype
2577	# so that arg types & arg names don't have a comma between them
2578	my $count = 0;
2579	my $len = length($prototype);
2580	if ($void) {
2581		$len = 0;	# skip the for-loop
2582	}
2583	for (my $ix = 0; $ix < $len; $ix++) {
2584		if (substr($prototype, $ix, 1) eq ',') {
2585			$count++;
2586			if ($count % 2 == 1) {
2587				substr($prototype, $ix, 1) = ' ';
2588			}
2589		}
2590	}
2591}
2592
2593sub process_state3_function($$) {
2594    my $x = shift;
2595    my $file = shift;
2596
2597    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2598
2599    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2600	# do nothing
2601    }
2602    elsif ($x =~ /([^\{]*)/) {
2603	$prototype .= $1;
2604    }
2605
2606    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2607	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
2608	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2609	$prototype =~ s@^\s+@@gos; # strip leading spaces
2610	if ($prototype =~ /SYSCALL_DEFINE/) {
2611		syscall_munge();
2612	}
2613	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2614	    $prototype =~ /DEFINE_SINGLE_EVENT/)
2615	{
2616		tracepoint_munge($file);
2617	}
2618	dump_function($prototype, $file);
2619	reset_state();
2620    }
2621}
2622
2623sub process_state3_type($$) {
2624    my $x = shift;
2625    my $file = shift;
2626
2627    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2628    $x =~ s@^\s+@@gos; # strip leading spaces
2629    $x =~ s@\s+$@@gos; # strip trailing spaces
2630    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2631
2632    if ($x =~ /^#/) {
2633	# To distinguish preprocessor directive from regular declaration later.
2634	$x .= ";";
2635    }
2636
2637    while (1) {
2638	if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2639	    $prototype .= $1 . $2;
2640	    ($2 eq '{') && $brcount++;
2641	    ($2 eq '}') && $brcount--;
2642	    if (($2 eq ';') && ($brcount == 0)) {
2643		dump_declaration($prototype, $file);
2644		reset_state();
2645		last;
2646	    }
2647	    $x = $3;
2648	} else {
2649	    $prototype .= $x;
2650	    last;
2651	}
2652    }
2653}
2654
2655# xml_escape: replace <, >, and & in the text stream;
2656#
2657# however, formatting controls that are generated internally/locally in the
2658# kernel-doc script are not escaped here; instead, they begin life like
2659# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2660# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2661# just before actual output; (this is done by local_unescape())
2662sub xml_escape($) {
2663	my $text = shift;
2664	if (($output_mode eq "text") || ($output_mode eq "man")) {
2665		return $text;
2666	}
2667	$text =~ s/\&/\\\\\\amp;/g;
2668	$text =~ s/\</\\\\\\lt;/g;
2669	$text =~ s/\>/\\\\\\gt;/g;
2670	return $text;
2671}
2672
2673# xml_unescape: reverse the effects of xml_escape
2674sub xml_unescape($) {
2675	my $text = shift;
2676	if (($output_mode eq "text") || ($output_mode eq "man")) {
2677		return $text;
2678	}
2679	$text =~ s/\\\\\\amp;/\&/g;
2680	$text =~ s/\\\\\\lt;/</g;
2681	$text =~ s/\\\\\\gt;/>/g;
2682	return $text;
2683}
2684
2685# convert local escape strings to html
2686# local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
2687sub local_unescape($) {
2688	my $text = shift;
2689	if (($output_mode eq "text") || ($output_mode eq "man")) {
2690		return $text;
2691	}
2692	$text =~ s/\\\\\\\\lt:/</g;
2693	$text =~ s/\\\\\\\\gt:/>/g;
2694	return $text;
2695}
2696
2697sub process_file($) {
2698    my $file;
2699    my $identifier;
2700    my $func;
2701    my $descr;
2702    my $in_purpose = 0;
2703    my $initial_section_counter = $section_counter;
2704    my ($orig_file) = @_;
2705
2706    if (defined($ENV{'SRCTREE'})) {
2707	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2708    }
2709    else {
2710	$file = $orig_file;
2711    }
2712    if (defined($source_map{$file})) {
2713	$file = $source_map{$file};
2714    }
2715
2716    if (!open(IN,"<$file")) {
2717	print STDERR "Error: Cannot open file $file\n";
2718	++$errors;
2719	return;
2720    }
2721
2722    # two passes for -export and -internal
2723    if ($output_selection == OUTPUT_EXPORTED ||
2724	$output_selection == OUTPUT_INTERNAL) {
2725	while (<IN>) {
2726	    if (/$export_symbol/o) {
2727		$function_table{$2} = 1;
2728	    }
2729	}
2730	seek(IN, 0, 0);
2731    }
2732
2733    $. = 1;
2734
2735    $section_counter = 0;
2736    while (<IN>) {
2737	while (s/\\\s*$//) {
2738	    $_ .= <IN>;
2739	}
2740	if ($state == STATE_NORMAL) {
2741	    if (/$doc_start/o) {
2742		$state = STATE_NAME;	# next line is always the function name
2743		$in_doc_sect = 0;
2744	    }
2745	} elsif ($state == STATE_NAME) {# this line is the function name (always)
2746	    if (/$doc_block/o) {
2747		$state = STATE_DOCBLOCK;
2748		$contents = "";
2749		if ( $1 eq "" ) {
2750			$section = $section_intro;
2751		} else {
2752			$section = $1;
2753		}
2754	    }
2755	    elsif (/$doc_decl/o) {
2756		$identifier = $1;
2757		if (/\s*([\w\s]+?)\s*-/) {
2758		    $identifier = $1;
2759		}
2760
2761		$state = STATE_FIELD;
2762		if (/-(.*)/) {
2763		    # strip leading/trailing/multiple spaces
2764		    $descr= $1;
2765		    $descr =~ s/^\s*//;
2766		    $descr =~ s/\s*$//;
2767		    $descr =~ s/\s+/ /g;
2768		    $declaration_purpose = xml_escape($descr);
2769		    $in_purpose = 1;
2770		} else {
2771		    $declaration_purpose = "";
2772		}
2773
2774		if (($declaration_purpose eq "") && $verbose) {
2775			print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2776			print STDERR $_;
2777			++$warnings;
2778		}
2779
2780		if ($identifier =~ m/^struct/) {
2781		    $decl_type = 'struct';
2782		} elsif ($identifier =~ m/^union/) {
2783		    $decl_type = 'union';
2784		} elsif ($identifier =~ m/^enum/) {
2785		    $decl_type = 'enum';
2786		} elsif ($identifier =~ m/^typedef/) {
2787		    $decl_type = 'typedef';
2788		} else {
2789		    $decl_type = 'function';
2790		}
2791
2792		if ($verbose) {
2793		    print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2794		}
2795	    } else {
2796		print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2797		" - I thought it was a doc line\n";
2798		++$warnings;
2799		$state = STATE_NORMAL;
2800	    }
2801	} elsif ($state == STATE_FIELD) {	# look for head: lines, and include content
2802	    if (/$doc_sect/o) {
2803		$newsection = $1;
2804		$newcontents = $2;
2805
2806		if (($contents ne "") && ($contents ne "\n")) {
2807		    if (!$in_doc_sect && $verbose) {
2808			print STDERR "${file}:$.: warning: contents before sections\n";
2809			++$warnings;
2810		    }
2811		    dump_section($file, $section, xml_escape($contents));
2812		    $section = $section_default;
2813		}
2814
2815		$in_doc_sect = 1;
2816		$in_purpose = 0;
2817		$contents = $newcontents;
2818		if ($contents ne "") {
2819		    while ((substr($contents, 0, 1) eq " ") ||
2820			substr($contents, 0, 1) eq "\t") {
2821			    $contents = substr($contents, 1);
2822		    }
2823		    $contents .= "\n";
2824		}
2825		$section = $newsection;
2826	    } elsif (/$doc_end/) {
2827		if (($contents ne "") && ($contents ne "\n")) {
2828		    dump_section($file, $section, xml_escape($contents));
2829		    $section = $section_default;
2830		    $contents = "";
2831		}
2832		# look for doc_com + <text> + doc_end:
2833		if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2834		    print STDERR "${file}:$.: warning: suspicious ending line: $_";
2835		    ++$warnings;
2836		}
2837
2838		$prototype = "";
2839		$state = STATE_PROTO;
2840		$brcount = 0;
2841#		print STDERR "end of doc comment, looking for prototype\n";
2842	    } elsif (/$doc_content/) {
2843		# miguel-style comment kludge, look for blank lines after
2844		# @parameter line to signify start of description
2845		if ($1 eq "") {
2846		    if ($section =~ m/^@/ || $section eq $section_context) {
2847			dump_section($file, $section, xml_escape($contents));
2848			$section = $section_default;
2849			$contents = "";
2850		    } else {
2851			$contents .= "\n";
2852		    }
2853		    $in_purpose = 0;
2854		} elsif ($in_purpose == 1) {
2855		    # Continued declaration purpose
2856		    chomp($declaration_purpose);
2857		    $declaration_purpose .= " " . xml_escape($1);
2858		    $declaration_purpose =~ s/\s+/ /g;
2859		} else {
2860		    $contents .= $1 . "\n";
2861		}
2862	    } else {
2863		# i dont know - bad line?  ignore.
2864		print STDERR "${file}:$.: warning: bad line: $_";
2865		++$warnings;
2866	    }
2867	} elsif ($state == STATE_INLINE) { # scanning for inline parameters
2868	    # First line (state 1) needs to be a @parameter
2869	    if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2870		$section = $1;
2871		$contents = $2;
2872		if ($contents ne "") {
2873		    while ((substr($contents, 0, 1) eq " ") ||
2874		           substr($contents, 0, 1) eq "\t") {
2875			$contents = substr($contents, 1);
2876		    }
2877		$contents .= "\n";
2878		}
2879		$inline_doc_state = STATE_INLINE_TEXT;
2880	    # Documentation block end */
2881	    } elsif (/$doc_inline_end/) {
2882		if (($contents ne "") && ($contents ne "\n")) {
2883		    dump_section($file, $section, xml_escape($contents));
2884		    $section = $section_default;
2885		    $contents = "";
2886		}
2887		$state = STATE_PROTO;
2888		$inline_doc_state = STATE_INLINE_NA;
2889	    # Regular text
2890	    } elsif (/$doc_content/) {
2891		if ($inline_doc_state == STATE_INLINE_TEXT) {
2892		    $contents .= $1 . "\n";
2893		} elsif ($inline_doc_state == STATE_INLINE_NAME) {
2894		    $inline_doc_state = STATE_INLINE_ERROR;
2895		    print STDERR "Warning(${file}:$.): ";
2896		    print STDERR "Incorrect use of kernel-doc format: $_";
2897		    ++$warnings;
2898		}
2899	    }
2900	} elsif ($state == STATE_PROTO) {	# scanning for function '{' (end of prototype)
2901	    if (/$doc_inline_start/) {
2902		$state = STATE_INLINE;
2903		$inline_doc_state = STATE_INLINE_NAME;
2904	    } elsif ($decl_type eq 'function') {
2905		process_state3_function($_, $file);
2906	    } else {
2907		process_state3_type($_, $file);
2908	    }
2909	} elsif ($state == STATE_DOCBLOCK) {
2910		# Documentation block
2911		if (/$doc_block/) {
2912			dump_doc_section($file, $section, xml_escape($contents));
2913			$contents = "";
2914			$function = "";
2915			%constants = ();
2916			%parameterdescs = ();
2917			%parametertypes = ();
2918			@parameterlist = ();
2919			%sections = ();
2920			@sectionlist = ();
2921			$prototype = "";
2922			if ( $1 eq "" ) {
2923				$section = $section_intro;
2924			} else {
2925				$section = $1;
2926			}
2927		}
2928		elsif (/$doc_end/)
2929		{
2930			dump_doc_section($file, $section, xml_escape($contents));
2931			$contents = "";
2932			$function = "";
2933			%constants = ();
2934			%parameterdescs = ();
2935			%parametertypes = ();
2936			@parameterlist = ();
2937			%sections = ();
2938			@sectionlist = ();
2939			$prototype = "";
2940			$state = STATE_NORMAL;
2941		}
2942		elsif (/$doc_content/)
2943		{
2944			if ( $1 eq "" )
2945			{
2946				$contents .= $blankline;
2947			}
2948			else
2949			{
2950				$contents .= $1 . "\n";
2951			}
2952		}
2953	}
2954    }
2955    if ($initial_section_counter == $section_counter) {
2956	print STDERR "${file}:1: warning: no structured comments found\n";
2957	if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2958	    print STDERR "    Was looking for '$_'.\n" for keys %function_table;
2959	}
2960	if ($output_mode eq "xml") {
2961	    # The template wants at least one RefEntry here; make one.
2962	    print "<refentry>\n";
2963	    print " <refnamediv>\n";
2964	    print "  <refname>\n";
2965	    print "   ${orig_file}\n";
2966	    print "  </refname>\n";
2967	    print "  <refpurpose>\n";
2968	    print "   Document generation inconsistency\n";
2969	    print "  </refpurpose>\n";
2970	    print " </refnamediv>\n";
2971	    print " <refsect1>\n";
2972	    print "  <title>\n";
2973	    print "   Oops\n";
2974	    print "  </title>\n";
2975	    print "  <warning>\n";
2976	    print "   <para>\n";
2977	    print "    The template for this document tried to insert\n";
2978	    print "    the structured comment from the file\n";
2979	    print "    <filename>${orig_file}</filename> at this point,\n";
2980	    print "    but none was found.\n";
2981	    print "    This dummy section is inserted to allow\n";
2982	    print "    generation to continue.\n";
2983	    print "   </para>\n";
2984	    print "  </warning>\n";
2985	    print " </refsect1>\n";
2986	    print "</refentry>\n";
2987	}
2988    }
2989}
2990
2991
2992$kernelversion = get_kernel_version();
2993
2994# generate a sequence of code that will splice in highlighting information
2995# using the s// operator.
2996for (my $k = 0; $k < @highlights; $k++) {
2997    my $pattern = $highlights[$k][0];
2998    my $result = $highlights[$k][1];
2999#   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
3000    $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
3001}
3002
3003# Read the file that maps relative names to absolute names for
3004# separate source and object directories and for shadow trees.
3005if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
3006	my ($relname, $absname);
3007	while(<SOURCE_MAP>) {
3008		chop();
3009		($relname, $absname) = (split())[0..1];
3010		$relname =~ s:^/+::;
3011		$source_map{$relname} = $absname;
3012	}
3013	close(SOURCE_MAP);
3014}
3015
3016foreach (@ARGV) {
3017    chomp;
3018    process_file($_);
3019}
3020if ($verbose && $errors) {
3021  print STDERR "$errors errors\n";
3022}
3023if ($verbose && $warnings) {
3024  print STDERR "$warnings warnings\n";
3025}
3026
3027exit($errors);
3028