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