xref: /openbmc/linux/scripts/kernel-doc (revision 6a767685)
1#!/usr/bin/env perl
2
3use warnings;
4use strict;
5
6## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
7## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
8## Copyright (C) 2001  Simon Huggins                             ##
9## Copyright (C) 2005-2012  Randy Dunlap                         ##
10## Copyright (C) 2012  Dan Luedtke                               ##
11## 								 ##
12## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
13## Copyright (c) 2000 MontaVista Software, Inc.			 ##
14## 								 ##
15## This software falls under the GNU General Public License.     ##
16## Please read the COPYING file for more information             ##
17
18# 18/01/2001 - 	Cleanups
19# 		Functions prototyped as foo(void) same as foo()
20# 		Stop eval'ing where we don't need to.
21# -- huggie@earth.li
22
23# 27/06/2001 -  Allowed whitespace after initial "/**" and
24#               allowed comments before function declarations.
25# -- Christian Kreibich <ck@whoop.org>
26
27# Still to do:
28# 	- add perldoc documentation
29# 	- Look more closely at some of the scarier bits :)
30
31# 26/05/2001 - 	Support for separate source and object trees.
32#		Return error code.
33# 		Keith Owens <kaos@ocs.com.au>
34
35# 23/09/2001 - Added support for typedefs, structs, enums and unions
36#              Support for Context section; can be terminated using empty line
37#              Small fixes (like spaces vs. \s in regex)
38# -- Tim Jansen <tim@tjansen.de>
39
40# 25/07/2012 - Added support for HTML5
41# -- Dan Luedtke <mail@danrl.de>
42
43sub usage {
44    my $message = <<"EOF";
45Usage: $0 [OPTION ...] FILE ...
46
47Read C language source or header FILEs, extract embedded documentation comments,
48and print formatted documentation to standard output.
49
50The documentation comments are identified by "/**" opening comment mark. See
51Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
52
53Output format selection (mutually exclusive):
54  -man			Output troff manual page format. This is the default.
55  -rst			Output reStructuredText format.
56  -none			Do not output documentation, only warnings.
57
58Output selection (mutually exclusive):
59  -export		Only output documentation for symbols that have been
60			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
61                        in any input FILE or -export-file FILE.
62  -internal		Only output documentation for symbols that have NOT been
63			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
64                        in any input FILE or -export-file FILE.
65  -function NAME	Only output documentation for the given function(s)
66			or DOC: section title(s). All other functions and DOC:
67			sections are ignored. May be specified multiple times.
68  -nofunction NAME	Do NOT output documentation for the given function(s);
69			only output documentation for the other functions and
70			DOC: sections. May be specified multiple times.
71
72Output selection modifiers:
73  -no-doc-sections	Do not output DOC: sections.
74  -enable-lineno        Enable output of #define LINENO lines. Only works with
75                        reStructuredText format.
76  -export-file FILE     Specify an additional FILE in which to look for
77                        EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
78                        -export or -internal. May be specified multiple times.
79
80Other parameters:
81  -v			Verbose output, more warnings and other information.
82  -h			Print this help.
83
84EOF
85    print $message;
86    exit 1;
87}
88
89#
90# format of comments.
91# In the following table, (...)? signifies optional structure.
92#                         (...)* signifies 0 or more structure elements
93# /**
94#  * function_name(:)? (- short description)?
95# (* @parameterx: (description of parameter x)?)*
96# (* a blank line)?
97#  * (Description:)? (Description of function)?
98#  * (section header: (section description)? )*
99#  (*)?*/
100#
101# So .. the trivial example would be:
102#
103# /**
104#  * my_function
105#  */
106#
107# If the Description: header tag is omitted, then there must be a blank line
108# after the last parameter specification.
109# e.g.
110# /**
111#  * my_function - does my stuff
112#  * @my_arg: its mine damnit
113#  *
114#  * Does my stuff explained.
115#  */
116#
117#  or, could also use:
118# /**
119#  * my_function - does my stuff
120#  * @my_arg: its mine damnit
121#  * Description: Does my stuff explained.
122#  */
123# etc.
124#
125# Besides functions you can also write documentation for structs, unions,
126# enums and typedefs. Instead of the function name you must write the name
127# of the declaration;  the struct/union/enum/typedef must always precede
128# the name. Nesting of declarations is not supported.
129# Use the argument mechanism to document members or constants.
130# e.g.
131# /**
132#  * struct my_struct - short description
133#  * @a: first member
134#  * @b: second member
135#  *
136#  * Longer description
137#  */
138# struct my_struct {
139#     int a;
140#     int b;
141# /* private: */
142#     int c;
143# };
144#
145# All descriptions can be multiline, except the short function description.
146#
147# For really longs structs, you can also describe arguments inside the
148# body of the struct.
149# eg.
150# /**
151#  * struct my_struct - short description
152#  * @a: first member
153#  * @b: second member
154#  *
155#  * Longer description
156#  */
157# struct my_struct {
158#     int a;
159#     int b;
160#     /**
161#      * @c: This is longer description of C
162#      *
163#      * You can use paragraphs to describe arguments
164#      * using this method.
165#      */
166#     int c;
167# };
168#
169# This should be use only for struct/enum members.
170#
171# You can also add additional sections. When documenting kernel functions you
172# should document the "Context:" of the function, e.g. whether the functions
173# can be called form interrupts. Unlike other sections you can end it with an
174# empty line.
175# A non-void function should have a "Return:" section describing the return
176# value(s).
177# Example-sections should contain the string EXAMPLE so that they are marked
178# appropriately in DocBook.
179#
180# Example:
181# /**
182#  * user_function - function that can only be called in user context
183#  * @a: some argument
184#  * Context: !in_interrupt()
185#  *
186#  * Some description
187#  * Example:
188#  *    user_function(22);
189#  */
190# ...
191#
192#
193# All descriptive text is further processed, scanning for the following special
194# patterns, which are highlighted appropriately.
195#
196# 'funcname()' - function
197# '$ENVVAR' - environmental variable
198# '&struct_name' - name of a structure (up to two words including 'struct')
199# '&struct_name.member' - name of a structure member
200# '@parameter' - name of a parameter
201# '%CONST' - name of a constant.
202# '``LITERAL``' - literal string without any spaces on it.
203
204## init lots of data
205
206my $errors = 0;
207my $warnings = 0;
208my $anon_struct_union = 0;
209
210# match expressions used to find embedded type information
211my $type_constant = '\b``([^\`]+)``\b';
212my $type_constant2 = '\%([-_\w]+)';
213my $type_func = '(\w+)\(\)';
214my $type_param = '\@(\w*(\.\w+)*(\.\.\.)?)';
215my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
216my $type_env = '(\$\w+)';
217my $type_enum = '\&(enum\s*([_\w]+))';
218my $type_struct = '\&(struct\s*([_\w]+))';
219my $type_typedef = '\&(typedef\s*([_\w]+))';
220my $type_union = '\&(union\s*([_\w]+))';
221my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
222my $type_fallback = '\&([_\w]+)';
223my $type_member_func = $type_member . '\(\)';
224
225# Output conversion substitutions.
226#  One for each output format
227
228# these are pretty rough
229my @highlights_man = (
230                      [$type_constant, "\$1"],
231                      [$type_constant2, "\$1"],
232                      [$type_func, "\\\\fB\$1\\\\fP"],
233                      [$type_enum, "\\\\fI\$1\\\\fP"],
234                      [$type_struct, "\\\\fI\$1\\\\fP"],
235                      [$type_typedef, "\\\\fI\$1\\\\fP"],
236                      [$type_union, "\\\\fI\$1\\\\fP"],
237                      [$type_param, "\\\\fI\$1\\\\fP"],
238                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
239                      [$type_fallback, "\\\\fI\$1\\\\fP"]
240		     );
241my $blankline_man = "";
242
243# rst-mode
244my @highlights_rst = (
245                       [$type_constant, "``\$1``"],
246                       [$type_constant2, "``\$1``"],
247                       # Note: need to escape () to avoid func matching later
248                       [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
249                       [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
250		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
251                       [$type_func, "\\:c\\:func\\:`\$1()`"],
252                       [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
253                       [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
254                       [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
255                       [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
256                       # in rst this can refer to any type
257                       [$type_fallback, "\\:c\\:type\\:`\$1`"],
258                       [$type_param, "**\$1**"]
259		      );
260my $blankline_rst = "\n";
261
262# read arguments
263if ($#ARGV == -1) {
264    usage();
265}
266
267my $kernelversion;
268my $dohighlight = "";
269
270my $verbose = 0;
271my $output_mode = "rst";
272my $output_preformatted = 0;
273my $no_doc_sections = 0;
274my $enable_lineno = 0;
275my @highlights = @highlights_rst;
276my $blankline = $blankline_rst;
277my $modulename = "Kernel API";
278
279use constant {
280    OUTPUT_ALL          => 0, # output all symbols and doc sections
281    OUTPUT_INCLUDE      => 1, # output only specified symbols
282    OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
283    OUTPUT_EXPORTED     => 3, # output exported symbols
284    OUTPUT_INTERNAL     => 4, # output non-exported symbols
285};
286my $output_selection = OUTPUT_ALL;
287my $show_not_found = 0;
288
289my @export_file_list;
290
291my @build_time;
292if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
293    (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
294    @build_time = gmtime($seconds);
295} else {
296    @build_time = localtime;
297}
298
299my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
300		'July', 'August', 'September', 'October',
301		'November', 'December')[$build_time[4]] .
302  " " . ($build_time[5]+1900);
303
304# Essentially these are globals.
305# They probably want to be tidied up, made more localised or something.
306# CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
307# could cause "use of undefined value" or other bugs.
308my ($function, %function_table, %parametertypes, $declaration_purpose);
309my $declaration_start_line;
310my ($type, $declaration_name, $return_type);
311my ($newsection, $newcontents, $prototype, $brcount, %source_map);
312
313if (defined($ENV{'KBUILD_VERBOSE'})) {
314	$verbose = "$ENV{'KBUILD_VERBOSE'}";
315}
316
317# Generated docbook code is inserted in a template at a point where
318# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
319# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
320# We keep track of number of generated entries and generate a dummy
321# if needs be to ensure the expanded template can be postprocessed
322# into html.
323my $section_counter = 0;
324
325my $lineprefix="";
326
327# Parser states
328use constant {
329    STATE_NORMAL        => 0, # normal code
330    STATE_NAME          => 1, # looking for function name
331    STATE_FIELD         => 2, # scanning field start
332    STATE_PROTO         => 3, # scanning prototype
333    STATE_DOCBLOCK      => 4, # documentation block
334    STATE_INLINE        => 5, # gathering documentation outside main block
335};
336my $state;
337my $in_doc_sect;
338
339# Inline documentation state
340use constant {
341    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
342    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
343    STATE_INLINE_TEXT   => 2, # looking for member documentation
344    STATE_INLINE_END    => 3, # done
345    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
346                              # Spit a warning as it's not
347                              # proper kernel-doc and ignore the rest.
348};
349my $inline_doc_state;
350
351#declaration types: can be
352# 'function', 'struct', 'union', 'enum', 'typedef'
353my $decl_type;
354
355my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
356my $doc_end = '\*/';
357my $doc_com = '\s*\*\s*';
358my $doc_com_body = '\s*\* ?';
359my $doc_decl = $doc_com . '(\w+)';
360# @params and a strictly limited set of supported section names
361my $doc_sect = $doc_com .
362    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
363my $doc_content = $doc_com_body . '(.*)';
364my $doc_block = $doc_com . 'DOC:\s*(.*)?';
365my $doc_inline_start = '^\s*/\*\*\s*$';
366my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
367my $doc_inline_end = '^\s*\*/\s*$';
368my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
369my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
370
371my %parameterdescs;
372my %parameterdesc_start_lines;
373my @parameterlist;
374my %sections;
375my @sectionlist;
376my %section_start_lines;
377my $sectcheck;
378my $struct_actual;
379
380my $contents = "";
381my $new_start_line = 0;
382
383# the canonical section names. see also $doc_sect above.
384my $section_default = "Description";	# default section
385my $section_intro = "Introduction";
386my $section = $section_default;
387my $section_context = "Context";
388my $section_return = "Return";
389
390my $undescribed = "-- undescribed --";
391
392reset_state();
393
394while ($ARGV[0] =~ m/^--?(.*)/) {
395    my $cmd = $1;
396    shift @ARGV;
397    if ($cmd eq "man") {
398	$output_mode = "man";
399	@highlights = @highlights_man;
400	$blankline = $blankline_man;
401    } elsif ($cmd eq "rst") {
402	$output_mode = "rst";
403	@highlights = @highlights_rst;
404	$blankline = $blankline_rst;
405    } elsif ($cmd eq "none") {
406	$output_mode = "none";
407    } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
408	$modulename = shift @ARGV;
409    } elsif ($cmd eq "function") { # to only output specific functions
410	$output_selection = OUTPUT_INCLUDE;
411	$function = shift @ARGV;
412	$function_table{$function} = 1;
413    } elsif ($cmd eq "nofunction") { # output all except specific functions
414	$output_selection = OUTPUT_EXCLUDE;
415	$function = shift @ARGV;
416	$function_table{$function} = 1;
417    } elsif ($cmd eq "export") { # only exported symbols
418	$output_selection = OUTPUT_EXPORTED;
419	%function_table = ();
420    } elsif ($cmd eq "internal") { # only non-exported symbols
421	$output_selection = OUTPUT_INTERNAL;
422	%function_table = ();
423    } elsif ($cmd eq "export-file") {
424	my $file = shift @ARGV;
425	push(@export_file_list, $file);
426    } elsif ($cmd eq "v") {
427	$verbose = 1;
428    } elsif (($cmd eq "h") || ($cmd eq "help")) {
429	usage();
430    } elsif ($cmd eq 'no-doc-sections') {
431	    $no_doc_sections = 1;
432    } elsif ($cmd eq 'enable-lineno') {
433	    $enable_lineno = 1;
434    } elsif ($cmd eq 'show-not-found') {
435	$show_not_found = 1;
436    } else {
437	# Unknown argument
438        usage();
439    }
440}
441
442# continue execution near EOF;
443
444# get kernel version from env
445sub get_kernel_version() {
446    my $version = 'unknown kernel version';
447
448    if (defined($ENV{'KERNELVERSION'})) {
449	$version = $ENV{'KERNELVERSION'};
450    }
451    return $version;
452}
453
454#
455sub print_lineno {
456    my $lineno = shift;
457    if ($enable_lineno && defined($lineno)) {
458        print "#define LINENO " . $lineno . "\n";
459    }
460}
461##
462# dumps section contents to arrays/hashes intended for that purpose.
463#
464sub dump_section {
465    my $file = shift;
466    my $name = shift;
467    my $contents = join "\n", @_;
468
469    if ($name =~ m/$type_param/) {
470	$name = $1;
471	$parameterdescs{$name} = $contents;
472	$sectcheck = $sectcheck . $name . " ";
473        $parameterdesc_start_lines{$name} = $new_start_line;
474        $new_start_line = 0;
475    } elsif ($name eq "@\.\.\.") {
476	$name = "...";
477	$parameterdescs{$name} = $contents;
478	$sectcheck = $sectcheck . $name . " ";
479        $parameterdesc_start_lines{$name} = $new_start_line;
480        $new_start_line = 0;
481    } else {
482	if (defined($sections{$name}) && ($sections{$name} ne "")) {
483	    # Only warn on user specified duplicate section names.
484	    if ($name ne $section_default) {
485		print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
486		++$warnings;
487	    }
488	    $sections{$name} .= $contents;
489	} else {
490	    $sections{$name} = $contents;
491	    push @sectionlist, $name;
492            $section_start_lines{$name} = $new_start_line;
493            $new_start_line = 0;
494	}
495    }
496}
497
498##
499# dump DOC: section after checking that it should go out
500#
501sub dump_doc_section {
502    my $file = shift;
503    my $name = shift;
504    my $contents = join "\n", @_;
505
506    if ($no_doc_sections) {
507        return;
508    }
509
510    if (($output_selection == OUTPUT_ALL) ||
511	($output_selection == OUTPUT_INCLUDE &&
512	 defined($function_table{$name})) ||
513	($output_selection == OUTPUT_EXCLUDE &&
514	 !defined($function_table{$name})))
515    {
516	dump_section($file, $name, $contents);
517	output_blockhead({'sectionlist' => \@sectionlist,
518			  'sections' => \%sections,
519			  'module' => $modulename,
520			  'content-only' => ($output_selection != OUTPUT_ALL), });
521    }
522}
523
524##
525# output function
526#
527# parameterdescs, a hash.
528#  function => "function name"
529#  parameterlist => @list of parameters
530#  parameterdescs => %parameter descriptions
531#  sectionlist => @list of sections
532#  sections => %section descriptions
533#
534
535sub output_highlight {
536    my $contents = join "\n",@_;
537    my $line;
538
539#   DEBUG
540#   if (!defined $contents) {
541#	use Carp;
542#	confess "output_highlight got called with no args?\n";
543#   }
544
545#   print STDERR "contents b4:$contents\n";
546    eval $dohighlight;
547    die $@ if $@;
548#   print STDERR "contents af:$contents\n";
549
550    foreach $line (split "\n", $contents) {
551	if (! $output_preformatted) {
552	    $line =~ s/^\s*//;
553	}
554	if ($line eq ""){
555	    if (! $output_preformatted) {
556		print $lineprefix, local_unescape($blankline);
557	    }
558	} else {
559	    $line =~ s/\\\\\\/\&/g;
560	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
561		print "\\&$line";
562	    } else {
563		print $lineprefix, $line;
564	    }
565	}
566	print "\n";
567    }
568}
569
570##
571# output function in man
572sub output_function_man(%) {
573    my %args = %{$_[0]};
574    my ($parameter, $section);
575    my $count;
576
577    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
578
579    print ".SH NAME\n";
580    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
581
582    print ".SH SYNOPSIS\n";
583    if ($args{'functiontype'} ne "") {
584	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
585    } else {
586	print ".B \"" . $args{'function'} . "\n";
587    }
588    $count = 0;
589    my $parenth = "(";
590    my $post = ",";
591    foreach my $parameter (@{$args{'parameterlist'}}) {
592	if ($count == $#{$args{'parameterlist'}}) {
593	    $post = ");";
594	}
595	$type = $args{'parametertypes'}{$parameter};
596	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
597	    # pointer-to-function
598	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
599	} else {
600	    $type =~ s/([^\*])$/$1 /;
601	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
602	}
603	$count++;
604	$parenth = "";
605    }
606
607    print ".SH ARGUMENTS\n";
608    foreach $parameter (@{$args{'parameterlist'}}) {
609	my $parameter_name = $parameter;
610	$parameter_name =~ s/\[.*//;
611
612	print ".IP \"" . $parameter . "\" 12\n";
613	output_highlight($args{'parameterdescs'}{$parameter_name});
614    }
615    foreach $section (@{$args{'sectionlist'}}) {
616	print ".SH \"", uc $section, "\"\n";
617	output_highlight($args{'sections'}{$section});
618    }
619}
620
621##
622# output enum in man
623sub output_enum_man(%) {
624    my %args = %{$_[0]};
625    my ($parameter, $section);
626    my $count;
627
628    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
629
630    print ".SH NAME\n";
631    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
632
633    print ".SH SYNOPSIS\n";
634    print "enum " . $args{'enum'} . " {\n";
635    $count = 0;
636    foreach my $parameter (@{$args{'parameterlist'}}) {
637	print ".br\n.BI \"    $parameter\"\n";
638	if ($count == $#{$args{'parameterlist'}}) {
639	    print "\n};\n";
640	    last;
641	}
642	else {
643	    print ", \n.br\n";
644	}
645	$count++;
646    }
647
648    print ".SH Constants\n";
649    foreach $parameter (@{$args{'parameterlist'}}) {
650	my $parameter_name = $parameter;
651	$parameter_name =~ s/\[.*//;
652
653	print ".IP \"" . $parameter . "\" 12\n";
654	output_highlight($args{'parameterdescs'}{$parameter_name});
655    }
656    foreach $section (@{$args{'sectionlist'}}) {
657	print ".SH \"$section\"\n";
658	output_highlight($args{'sections'}{$section});
659    }
660}
661
662##
663# output struct in man
664sub output_struct_man(%) {
665    my %args = %{$_[0]};
666    my ($parameter, $section);
667
668    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
669
670    print ".SH NAME\n";
671    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
672
673    my $declaration = $args{'definition'};
674    $declaration =~ s/\t/  /g;
675    $declaration =~ s/\n/"\n.br\n.BI \"/g;
676    print ".SH SYNOPSIS\n";
677    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
678    print ".BI \"$declaration\n};\n.br\n\n";
679
680    print ".SH Members\n";
681    foreach $parameter (@{$args{'parameterlist'}}) {
682	($parameter =~ /^#/) && next;
683
684	my $parameter_name = $parameter;
685	$parameter_name =~ s/\[.*//;
686
687	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
688	print ".IP \"" . $parameter . "\" 12\n";
689	output_highlight($args{'parameterdescs'}{$parameter_name});
690    }
691    foreach $section (@{$args{'sectionlist'}}) {
692	print ".SH \"$section\"\n";
693	output_highlight($args{'sections'}{$section});
694    }
695}
696
697##
698# output typedef in man
699sub output_typedef_man(%) {
700    my %args = %{$_[0]};
701    my ($parameter, $section);
702
703    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
704
705    print ".SH NAME\n";
706    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
707
708    foreach $section (@{$args{'sectionlist'}}) {
709	print ".SH \"$section\"\n";
710	output_highlight($args{'sections'}{$section});
711    }
712}
713
714sub output_blockhead_man(%) {
715    my %args = %{$_[0]};
716    my ($parameter, $section);
717    my $count;
718
719    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
720
721    foreach $section (@{$args{'sectionlist'}}) {
722	print ".SH \"$section\"\n";
723	output_highlight($args{'sections'}{$section});
724    }
725}
726
727##
728# output in restructured text
729#
730
731#
732# This could use some work; it's used to output the DOC: sections, and
733# starts by putting out the name of the doc section itself, but that tends
734# to duplicate a header already in the template file.
735#
736sub output_blockhead_rst(%) {
737    my %args = %{$_[0]};
738    my ($parameter, $section);
739
740    foreach $section (@{$args{'sectionlist'}}) {
741	if ($output_selection != OUTPUT_INCLUDE) {
742	    print "**$section**\n\n";
743	}
744        print_lineno($section_start_lines{$section});
745	output_highlight_rst($args{'sections'}{$section});
746	print "\n";
747    }
748}
749
750sub output_highlight_rst {
751    my $contents = join "\n",@_;
752    my $line;
753
754    # undo the evil effects of xml_escape() earlier
755    $contents = xml_unescape($contents);
756
757    eval $dohighlight;
758    die $@ if $@;
759
760    foreach $line (split "\n", $contents) {
761	print $lineprefix . $line . "\n";
762    }
763}
764
765sub output_function_rst(%) {
766    my %args = %{$_[0]};
767    my ($parameter, $section);
768    my $oldprefix = $lineprefix;
769    my $start = "";
770
771    if ($args{'typedef'}) {
772	print ".. c:type:: ". $args{'function'} . "\n\n";
773	print_lineno($declaration_start_line);
774	print "   **Typedef**: ";
775	$lineprefix = "";
776	output_highlight_rst($args{'purpose'});
777	$start = "\n\n**Syntax**\n\n  ``";
778    } else {
779	print ".. c:function:: ";
780    }
781    if ($args{'functiontype'} ne "") {
782	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
783    } else {
784	$start .= $args{'function'} . " (";
785    }
786    print $start;
787
788    my $count = 0;
789    foreach my $parameter (@{$args{'parameterlist'}}) {
790	if ($count ne 0) {
791	    print ", ";
792	}
793	$count++;
794	$type = $args{'parametertypes'}{$parameter};
795
796	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
797	    # pointer-to-function
798	    print $1 . $parameter . ") (" . $2;
799	} else {
800	    print $type . " " . $parameter;
801	}
802    }
803    if ($args{'typedef'}) {
804	print ");``\n\n";
805    } else {
806	print ")\n\n";
807	print_lineno($declaration_start_line);
808	$lineprefix = "   ";
809	output_highlight_rst($args{'purpose'});
810	print "\n";
811    }
812
813    print "**Parameters**\n\n";
814    $lineprefix = "  ";
815    foreach $parameter (@{$args{'parameterlist'}}) {
816	my $parameter_name = $parameter;
817	$parameter_name =~ s/\[.*//;
818	$type = $args{'parametertypes'}{$parameter};
819
820	if ($type ne "") {
821	    print "``$type $parameter``\n";
822	} else {
823	    print "``$parameter``\n";
824	}
825
826        print_lineno($parameterdesc_start_lines{$parameter_name});
827
828	if (defined($args{'parameterdescs'}{$parameter_name}) &&
829	    $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
830	    output_highlight_rst($args{'parameterdescs'}{$parameter_name});
831	} else {
832	    print "  *undescribed*\n";
833	}
834	print "\n";
835    }
836
837    $lineprefix = $oldprefix;
838    output_section_rst(@_);
839}
840
841sub output_section_rst(%) {
842    my %args = %{$_[0]};
843    my $section;
844    my $oldprefix = $lineprefix;
845    $lineprefix = "";
846
847    foreach $section (@{$args{'sectionlist'}}) {
848	print "**$section**\n\n";
849        print_lineno($section_start_lines{$section});
850	output_highlight_rst($args{'sections'}{$section});
851	print "\n";
852    }
853    print "\n";
854    $lineprefix = $oldprefix;
855}
856
857sub output_enum_rst(%) {
858    my %args = %{$_[0]};
859    my ($parameter);
860    my $oldprefix = $lineprefix;
861    my $count;
862    my $name = "enum " . $args{'enum'};
863
864    print "\n\n.. c:type:: " . $name . "\n\n";
865    print_lineno($declaration_start_line);
866    $lineprefix = "   ";
867    output_highlight_rst($args{'purpose'});
868    print "\n";
869
870    print "**Constants**\n\n";
871    $lineprefix = "  ";
872    foreach $parameter (@{$args{'parameterlist'}}) {
873	print "``$parameter``\n";
874	if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
875	    output_highlight_rst($args{'parameterdescs'}{$parameter});
876	} else {
877	    print "  *undescribed*\n";
878	}
879	print "\n";
880    }
881
882    $lineprefix = $oldprefix;
883    output_section_rst(@_);
884}
885
886sub output_typedef_rst(%) {
887    my %args = %{$_[0]};
888    my ($parameter);
889    my $oldprefix = $lineprefix;
890    my $name = "typedef " . $args{'typedef'};
891
892    print "\n\n.. c:type:: " . $name . "\n\n";
893    print_lineno($declaration_start_line);
894    $lineprefix = "   ";
895    output_highlight_rst($args{'purpose'});
896    print "\n";
897
898    $lineprefix = $oldprefix;
899    output_section_rst(@_);
900}
901
902sub output_struct_rst(%) {
903    my %args = %{$_[0]};
904    my ($parameter);
905    my $oldprefix = $lineprefix;
906    my $name = $args{'type'} . " " . $args{'struct'};
907
908    print "\n\n.. c:type:: " . $name . "\n\n";
909    print_lineno($declaration_start_line);
910    $lineprefix = "   ";
911    output_highlight_rst($args{'purpose'});
912    print "\n";
913
914    print "**Definition**\n\n";
915    print "::\n\n";
916    my $declaration = $args{'definition'};
917    $declaration =~ s/\t/  /g;
918    print "  " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration  };\n\n";
919
920    print "**Members**\n\n";
921    $lineprefix = "  ";
922    foreach $parameter (@{$args{'parameterlist'}}) {
923	($parameter =~ /^#/) && next;
924
925	my $parameter_name = $parameter;
926	$parameter_name =~ s/\[.*//;
927
928	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
929	$type = $args{'parametertypes'}{$parameter};
930        print_lineno($parameterdesc_start_lines{$parameter_name});
931	print "``" . $parameter . "``\n";
932	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
933	print "\n";
934    }
935    print "\n";
936
937    $lineprefix = $oldprefix;
938    output_section_rst(@_);
939}
940
941## none mode output functions
942
943sub output_function_none(%) {
944}
945
946sub output_enum_none(%) {
947}
948
949sub output_typedef_none(%) {
950}
951
952sub output_struct_none(%) {
953}
954
955sub output_blockhead_none(%) {
956}
957
958##
959# generic output function for all types (function, struct/union, typedef, enum);
960# calls the generated, variable output_ function name based on
961# functype and output_mode
962sub output_declaration {
963    no strict 'refs';
964    my $name = shift;
965    my $functype = shift;
966    my $func = "output_${functype}_$output_mode";
967    if (($output_selection == OUTPUT_ALL) ||
968	(($output_selection == OUTPUT_INCLUDE ||
969	  $output_selection == OUTPUT_EXPORTED) &&
970	 defined($function_table{$name})) ||
971	(($output_selection == OUTPUT_EXCLUDE ||
972	  $output_selection == OUTPUT_INTERNAL) &&
973	 !($functype eq "function" && defined($function_table{$name}))))
974    {
975	&$func(@_);
976	$section_counter++;
977    }
978}
979
980##
981# generic output function - calls the right one based on current output mode.
982sub output_blockhead {
983    no strict 'refs';
984    my $func = "output_blockhead_" . $output_mode;
985    &$func(@_);
986    $section_counter++;
987}
988
989##
990# takes a declaration (struct, union, enum, typedef) and
991# invokes the right handler. NOT called for functions.
992sub dump_declaration($$) {
993    no strict 'refs';
994    my ($prototype, $file) = @_;
995    my $func = "dump_" . $decl_type;
996    &$func(@_);
997}
998
999sub dump_union($$) {
1000    dump_struct(@_);
1001}
1002
1003sub dump_struct($$) {
1004    my $x = shift;
1005    my $file = shift;
1006
1007    if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
1008	my $decl_type = $1;
1009	$declaration_name = $2;
1010	my $members = $3;
1011
1012	# ignore members marked private:
1013	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
1014	$members =~ s/\/\*\s*private:.*//gosi;
1015	# strip comments:
1016	$members =~ s/\/\*.*?\*\///gos;
1017	# strip attributes
1018	$members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1019	$members =~ s/__aligned\s*\([^;]*\)//gos;
1020	$members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
1021	# replace DECLARE_BITMAP
1022	$members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
1023	# replace DECLARE_HASHTABLE
1024	$members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
1025	# replace DECLARE_KFIFO
1026	$members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1027	# replace DECLARE_KFIFO_PTR
1028	$members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
1029
1030	my $declaration = $members;
1031
1032	# Split nested struct/union elements as newer ones
1033	while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
1034		my $newmember;
1035		my $maintype = $1;
1036		my $ids = $4;
1037		my $content = $3;
1038		foreach my $id(split /,/, $ids) {
1039			$newmember .= "$maintype $id; ";
1040
1041			$id =~ s/[:\[].*//;
1042			$id =~ s/^\s*\**(\S+)\s*/$1/;
1043			foreach my $arg (split /;/, $content) {
1044				next if ($arg =~ m/^\s*$/);
1045				if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) {
1046					# pointer-to-function
1047					my $type = $1;
1048					my $name = $2;
1049					my $extra = $3;
1050					next if (!$name);
1051					if ($id =~ m/^\s*$/) {
1052						# anonymous struct/union
1053						$newmember .= "$type$name$extra; ";
1054					} else {
1055						$newmember .= "$type$id.$name$extra; ";
1056					}
1057				} else {
1058					my $type;
1059					my $names;
1060					$arg =~ s/^\s+//;
1061					$arg =~ s/\s+$//;
1062					# Handle bitmaps
1063					$arg =~ s/:\s*\d+\s*//g;
1064					# Handle arrays
1065					$arg =~ s/\[\S+\]//g;
1066					# The type may have multiple words,
1067					# and multiple IDs can be defined, like:
1068					#	const struct foo, *bar, foobar
1069					# So, we remove spaces when parsing the
1070					# names, in order to match just names
1071					# and commas for the names
1072					$arg =~ s/\s*,\s*/,/g;
1073					if ($arg =~ m/(.*)\s+([\S+,]+)/) {
1074						$type = $1;
1075						$names = $2;
1076					} else {
1077						$newmember .= "$arg; ";
1078						next;
1079					}
1080					foreach my $name (split /,/, $names) {
1081						$name =~ s/^\s*\**(\S+)\s*/$1/;
1082						next if (($name =~ m/^\s*$/));
1083						if ($id =~ m/^\s*$/) {
1084							# anonymous struct/union
1085							$newmember .= "$type $name; ";
1086						} else {
1087							$newmember .= "$type $id.$name; ";
1088						}
1089					}
1090				}
1091			}
1092		}
1093		$members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)}([^\{\}\;]*)\;/$newmember/;
1094	}
1095
1096	# Ignore other nested elements, like enums
1097	$members =~ s/({[^\{\}]*})//g;
1098
1099	create_parameterlist($members, ';', $file, $declaration_name);
1100	check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);
1101
1102	# Adjust declaration for better display
1103	$declaration =~ s/([{;])/$1\n/g;
1104	$declaration =~ s/}\s+;/};/g;
1105	# Better handle inlined enums
1106	do {} while ($declaration =~ s/(enum\s+{[^}]+),([^\n])/$1,\n$2/);
1107
1108	my @def_args = split /\n/, $declaration;
1109	my $level = 1;
1110	$declaration = "";
1111	foreach my $clause (@def_args) {
1112		$clause =~ s/^\s+//;
1113		$clause =~ s/\s+$//;
1114		$clause =~ s/\s+/ /;
1115		next if (!$clause);
1116		$level-- if ($clause =~ m/(})/ && $level > 1);
1117		if (!($clause =~ m/^\s*#/)) {
1118			$declaration .= "\t" x $level;
1119		}
1120		$declaration .= "\t" . $clause . "\n";
1121		$level++ if ($clause =~ m/({)/ && !($clause =~m/}/));
1122	}
1123	output_declaration($declaration_name,
1124			   'struct',
1125			   {'struct' => $declaration_name,
1126			    'module' => $modulename,
1127			    'definition' => $declaration,
1128			    'parameterlist' => \@parameterlist,
1129			    'parameterdescs' => \%parameterdescs,
1130			    'parametertypes' => \%parametertypes,
1131			    'sectionlist' => \@sectionlist,
1132			    'sections' => \%sections,
1133			    'purpose' => $declaration_purpose,
1134			    'type' => $decl_type
1135			   });
1136    }
1137    else {
1138	print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
1139	++$errors;
1140    }
1141}
1142
1143
1144sub show_warnings($$) {
1145	my $functype = shift;
1146	my $name = shift;
1147
1148	return 1 if ($output_selection == OUTPUT_ALL);
1149
1150	if ($output_selection == OUTPUT_EXPORTED) {
1151		if (defined($function_table{$name})) {
1152			return 1;
1153		} else {
1154			return 0;
1155		}
1156	}
1157        if ($output_selection == OUTPUT_INTERNAL) {
1158		if (!($functype eq "function" && defined($function_table{$name}))) {
1159			return 1;
1160		} else {
1161			return 0;
1162		}
1163	}
1164	if ($output_selection == OUTPUT_INCLUDE) {
1165		if (defined($function_table{$name})) {
1166			return 1;
1167		} else {
1168			return 0;
1169		}
1170	}
1171	if ($output_selection == OUTPUT_EXCLUDE) {
1172		if (!defined($function_table{$name})) {
1173			return 1;
1174		} else {
1175			return 0;
1176		}
1177	}
1178	die("Please add the new output type at show_warnings()");
1179}
1180
1181sub dump_enum($$) {
1182    my $x = shift;
1183    my $file = shift;
1184
1185    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
1186    # strip #define macros inside enums
1187    $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
1188
1189    if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1190	$declaration_name = $1;
1191	my $members = $2;
1192	my %_members;
1193
1194	$members =~ s/\s+$//;
1195
1196	foreach my $arg (split ',', $members) {
1197	    $arg =~ s/^\s*(\w+).*/$1/;
1198	    push @parameterlist, $arg;
1199	    if (!$parameterdescs{$arg}) {
1200		$parameterdescs{$arg} = $undescribed;
1201	        if (show_warnings("enum", $declaration_name)) {
1202			print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n";
1203		}
1204	    }
1205	    $_members{$arg} = 1;
1206	}
1207
1208	while (my ($k, $v) = each %parameterdescs) {
1209	    if (!exists($_members{$k})) {
1210	        if (show_warnings("enum", $declaration_name)) {
1211		     print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n";
1212		}
1213	    }
1214        }
1215
1216	output_declaration($declaration_name,
1217			   'enum',
1218			   {'enum' => $declaration_name,
1219			    'module' => $modulename,
1220			    'parameterlist' => \@parameterlist,
1221			    'parameterdescs' => \%parameterdescs,
1222			    'sectionlist' => \@sectionlist,
1223			    'sections' => \%sections,
1224			    'purpose' => $declaration_purpose
1225			   });
1226    }
1227    else {
1228	print STDERR "${file}:$.: error: Cannot parse enum!\n";
1229	++$errors;
1230    }
1231}
1232
1233sub dump_typedef($$) {
1234    my $x = shift;
1235    my $file = shift;
1236
1237    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
1238
1239    # Parse function prototypes
1240    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
1241	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
1242
1243	# Function typedefs
1244	$return_type = $1;
1245	$declaration_name = $2;
1246	my $args = $3;
1247
1248	create_parameterlist($args, ',', $file, $declaration_name);
1249
1250	output_declaration($declaration_name,
1251			   'function',
1252			   {'function' => $declaration_name,
1253			    'typedef' => 1,
1254			    'module' => $modulename,
1255			    'functiontype' => $return_type,
1256			    'parameterlist' => \@parameterlist,
1257			    'parameterdescs' => \%parameterdescs,
1258			    'parametertypes' => \%parametertypes,
1259			    'sectionlist' => \@sectionlist,
1260			    'sections' => \%sections,
1261			    'purpose' => $declaration_purpose
1262			   });
1263	return;
1264    }
1265
1266    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1267	$x =~ s/\(*.\)\s*;$/;/;
1268	$x =~ s/\[*.\]\s*;$/;/;
1269    }
1270
1271    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1272	$declaration_name = $1;
1273
1274	output_declaration($declaration_name,
1275			   'typedef',
1276			   {'typedef' => $declaration_name,
1277			    'module' => $modulename,
1278			    'sectionlist' => \@sectionlist,
1279			    'sections' => \%sections,
1280			    'purpose' => $declaration_purpose
1281			   });
1282    }
1283    else {
1284	print STDERR "${file}:$.: error: Cannot parse typedef!\n";
1285	++$errors;
1286    }
1287}
1288
1289sub save_struct_actual($) {
1290    my $actual = shift;
1291
1292    # strip all spaces from the actual param so that it looks like one string item
1293    $actual =~ s/\s*//g;
1294    $struct_actual = $struct_actual . $actual . " ";
1295}
1296
1297sub create_parameterlist($$$$) {
1298    my $args = shift;
1299    my $splitter = shift;
1300    my $file = shift;
1301    my $declaration_name = shift;
1302    my $type;
1303    my $param;
1304
1305    # temporarily replace commas inside function pointer definition
1306    while ($args =~ /(\([^\),]+),/) {
1307	$args =~ s/(\([^\),]+),/$1#/g;
1308    }
1309
1310    foreach my $arg (split($splitter, $args)) {
1311	# strip comments
1312	$arg =~ s/\/\*.*\*\///;
1313	# strip leading/trailing spaces
1314	$arg =~ s/^\s*//;
1315	$arg =~ s/\s*$//;
1316	$arg =~ s/\s+/ /;
1317
1318	if ($arg =~ /^#/) {
1319	    # Treat preprocessor directive as a typeless variable just to fill
1320	    # corresponding data structures "correctly". Catch it later in
1321	    # output_* subs.
1322	    push_parameter($arg, "", $file);
1323	} elsif ($arg =~ m/\(.+\)\s*\(/) {
1324	    # pointer-to-function
1325	    $arg =~ tr/#/,/;
1326	    $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/;
1327	    $param = $1;
1328	    $type = $arg;
1329	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1330	    save_struct_actual($param);
1331	    push_parameter($param, $type, $file, $declaration_name);
1332	} elsif ($arg) {
1333	    $arg =~ s/\s*:\s*/:/g;
1334	    $arg =~ s/\s*\[/\[/g;
1335
1336	    my @args = split('\s*,\s*', $arg);
1337	    if ($args[0] =~ m/\*/) {
1338		$args[0] =~ s/(\*+)\s*/ $1/;
1339	    }
1340
1341	    my @first_arg;
1342	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1343		    shift @args;
1344		    push(@first_arg, split('\s+', $1));
1345		    push(@first_arg, $2);
1346	    } else {
1347		    @first_arg = split('\s+', shift @args);
1348	    }
1349
1350	    unshift(@args, pop @first_arg);
1351	    $type = join " ", @first_arg;
1352
1353	    foreach $param (@args) {
1354		if ($param =~ m/^(\*+)\s*(.*)/) {
1355		    save_struct_actual($2);
1356		    push_parameter($2, "$type $1", $file, $declaration_name);
1357		}
1358		elsif ($param =~ m/(.*?):(\d+)/) {
1359		    if ($type ne "") { # skip unnamed bit-fields
1360			save_struct_actual($1);
1361			push_parameter($1, "$type:$2", $file, $declaration_name)
1362		    }
1363		}
1364		else {
1365		    save_struct_actual($param);
1366		    push_parameter($param, $type, $file, $declaration_name);
1367		}
1368	    }
1369	}
1370    }
1371}
1372
1373sub push_parameter($$$$) {
1374	my $param = shift;
1375	my $type = shift;
1376	my $file = shift;
1377	my $declaration_name = shift;
1378
1379	if (($anon_struct_union == 1) && ($type eq "") &&
1380	    ($param eq "}")) {
1381		return;		# ignore the ending }; from anon. struct/union
1382	}
1383
1384	$anon_struct_union = 0;
1385	$param =~ s/[\[\)].*//;
1386
1387	if ($type eq "" && $param =~ /\.\.\.$/)
1388	{
1389	    if (!$param =~ /\w\.\.\.$/) {
1390	      # handles unnamed variable parameters
1391	      $param = "...";
1392	    }
1393	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
1394		$parameterdescs{$param} = "variable arguments";
1395	    }
1396	}
1397	elsif ($type eq "" && ($param eq "" or $param eq "void"))
1398	{
1399	    $param="void";
1400	    $parameterdescs{void} = "no arguments";
1401	}
1402	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1403	# handle unnamed (anonymous) union or struct:
1404	{
1405		$type = $param;
1406		$param = "{unnamed_" . $param . "}";
1407		$parameterdescs{$param} = "anonymous\n";
1408		$anon_struct_union = 1;
1409	}
1410
1411	# warn if parameter has no description
1412	# (but ignore ones starting with # as these are not parameters
1413	# but inline preprocessor statements);
1414	# Note: It will also ignore void params and unnamed structs/unions
1415	if (!defined $parameterdescs{$param} && $param !~ /^#/) {
1416		$parameterdescs{$param} = $undescribed;
1417
1418	        if (show_warnings($type, $declaration_name)) {
1419			print STDERR
1420			      "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
1421			++$warnings;
1422		}
1423	}
1424
1425	$param = xml_escape($param);
1426
1427	# strip spaces from $param so that it is one continuous string
1428	# on @parameterlist;
1429	# this fixes a problem where check_sections() cannot find
1430	# a parameter like "addr[6 + 2]" because it actually appears
1431	# as "addr[6", "+", "2]" on the parameter list;
1432	# but it's better to maintain the param string unchanged for output,
1433	# so just weaken the string compare in check_sections() to ignore
1434	# "[blah" in a parameter string;
1435	###$param =~ s/\s*//g;
1436	push @parameterlist, $param;
1437	$type =~ s/\s\s+/ /g;
1438	$parametertypes{$param} = $type;
1439}
1440
1441sub check_sections($$$$$) {
1442	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
1443	my @sects = split ' ', $sectcheck;
1444	my @prms = split ' ', $prmscheck;
1445	my $err;
1446	my ($px, $sx);
1447	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"
1448
1449	foreach $sx (0 .. $#sects) {
1450		$err = 1;
1451		foreach $px (0 .. $#prms) {
1452			$prm_clean = $prms[$px];
1453			$prm_clean =~ s/\[.*\]//;
1454			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1455			# ignore array size in a parameter string;
1456			# however, the original param string may contain
1457			# spaces, e.g.:  addr[6 + 2]
1458			# and this appears in @prms as "addr[6" since the
1459			# parameter list is split at spaces;
1460			# hence just ignore "[..." for the sections check;
1461			$prm_clean =~ s/\[.*//;
1462
1463			##$prm_clean =~ s/^\**//;
1464			if ($prm_clean eq $sects[$sx]) {
1465				$err = 0;
1466				last;
1467			}
1468		}
1469		if ($err) {
1470			if ($decl_type eq "function") {
1471				print STDERR "${file}:$.: warning: " .
1472					"Excess function parameter " .
1473					"'$sects[$sx]' " .
1474					"description in '$decl_name'\n";
1475				++$warnings;
1476			}
1477		}
1478	}
1479}
1480
1481##
1482# Checks the section describing the return value of a function.
1483sub check_return_section {
1484        my $file = shift;
1485        my $declaration_name = shift;
1486        my $return_type = shift;
1487
1488        # Ignore an empty return type (It's a macro)
1489        # Ignore functions with a "void" return type. (But don't ignore "void *")
1490        if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
1491                return;
1492        }
1493
1494        if (!defined($sections{$section_return}) ||
1495            $sections{$section_return} eq "") {
1496                print STDERR "${file}:$.: warning: " .
1497                        "No description found for return value of " .
1498                        "'$declaration_name'\n";
1499                ++$warnings;
1500        }
1501}
1502
1503##
1504# takes a function prototype and the name of the current file being
1505# processed and spits out all the details stored in the global
1506# arrays/hashes.
1507sub dump_function($$) {
1508    my $prototype = shift;
1509    my $file = shift;
1510    my $noret = 0;
1511
1512    $prototype =~ s/^static +//;
1513    $prototype =~ s/^extern +//;
1514    $prototype =~ s/^asmlinkage +//;
1515    $prototype =~ s/^inline +//;
1516    $prototype =~ s/^__inline__ +//;
1517    $prototype =~ s/^__inline +//;
1518    $prototype =~ s/^__always_inline +//;
1519    $prototype =~ s/^noinline +//;
1520    $prototype =~ s/__init +//;
1521    $prototype =~ s/__init_or_module +//;
1522    $prototype =~ s/__meminit +//;
1523    $prototype =~ s/__must_check +//;
1524    $prototype =~ s/__weak +//;
1525    my $define = $prototype =~ s/^#\s*define\s+//; #ak added
1526    $prototype =~ s/__attribute__\s*\(\(
1527            (?:
1528                 [\w\s]++          # attribute name
1529                 (?:\([^)]*+\))?   # attribute arguments
1530                 \s*+,?            # optional comma at the end
1531            )+
1532          \)\)\s+//x;
1533
1534    # Yes, this truly is vile.  We are looking for:
1535    # 1. Return type (may be nothing if we're looking at a macro)
1536    # 2. Function name
1537    # 3. Function parameters.
1538    #
1539    # All the while we have to watch out for function pointer parameters
1540    # (which IIRC is what the two sections are for), C types (these
1541    # regexps don't even start to express all the possibilities), and
1542    # so on.
1543    #
1544    # If you mess with these regexps, it's a good idea to check that
1545    # the following functions' documentation still comes out right:
1546    # - parport_register_device (function pointer parameters)
1547    # - atomic_set (macro)
1548    # - pci_match_device, __copy_to_user (long return type)
1549
1550    if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
1551        # This is an object-like macro, it has no return type and no parameter
1552        # list.
1553        # Function-like macros are not allowed to have spaces between
1554        # declaration_name and opening parenthesis (notice the \s+).
1555        $return_type = $1;
1556        $declaration_name = $2;
1557        $noret = 1;
1558    } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1559	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1560	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1561	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1562	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1563	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1564	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1565	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1566	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1567	$prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1568	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1569	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1570	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1571	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1572	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1573	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1574	$prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
1575	$return_type = $1;
1576	$declaration_name = $2;
1577	my $args = $3;
1578
1579	create_parameterlist($args, ',', $file, $declaration_name);
1580    } else {
1581	print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
1582	return;
1583    }
1584
1585	my $prms = join " ", @parameterlist;
1586	check_sections($file, $declaration_name, "function", $sectcheck, $prms);
1587
1588        # This check emits a lot of warnings at the moment, because many
1589        # functions don't have a 'Return' doc section. So until the number
1590        # of warnings goes sufficiently down, the check is only performed in
1591        # verbose mode.
1592        # TODO: always perform the check.
1593        if ($verbose && !$noret) {
1594                check_return_section($file, $declaration_name, $return_type);
1595        }
1596
1597    output_declaration($declaration_name,
1598		       'function',
1599		       {'function' => $declaration_name,
1600			'module' => $modulename,
1601			'functiontype' => $return_type,
1602			'parameterlist' => \@parameterlist,
1603			'parameterdescs' => \%parameterdescs,
1604			'parametertypes' => \%parametertypes,
1605			'sectionlist' => \@sectionlist,
1606			'sections' => \%sections,
1607			'purpose' => $declaration_purpose
1608		       });
1609}
1610
1611sub reset_state {
1612    $function = "";
1613    %parameterdescs = ();
1614    %parametertypes = ();
1615    @parameterlist = ();
1616    %sections = ();
1617    @sectionlist = ();
1618    $sectcheck = "";
1619    $struct_actual = "";
1620    $prototype = "";
1621
1622    $state = STATE_NORMAL;
1623    $inline_doc_state = STATE_INLINE_NA;
1624}
1625
1626sub tracepoint_munge($) {
1627	my $file = shift;
1628	my $tracepointname = 0;
1629	my $tracepointargs = 0;
1630
1631	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
1632		$tracepointname = $1;
1633	}
1634	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
1635		$tracepointname = $1;
1636	}
1637	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
1638		$tracepointname = $2;
1639	}
1640	$tracepointname =~ s/^\s+//; #strip leading whitespace
1641	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1642		$tracepointargs = $1;
1643	}
1644	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
1645		print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
1646			     "$prototype\n";
1647	} else {
1648		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
1649	}
1650}
1651
1652sub syscall_munge() {
1653	my $void = 0;
1654
1655	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
1656##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
1657	if ($prototype =~ m/SYSCALL_DEFINE0/) {
1658		$void = 1;
1659##		$prototype = "long sys_$1(void)";
1660	}
1661
1662	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
1663	if ($prototype =~ m/long (sys_.*?),/) {
1664		$prototype =~ s/,/\(/;
1665	} elsif ($void) {
1666		$prototype =~ s/\)/\(void\)/;
1667	}
1668
1669	# now delete all of the odd-number commas in $prototype
1670	# so that arg types & arg names don't have a comma between them
1671	my $count = 0;
1672	my $len = length($prototype);
1673	if ($void) {
1674		$len = 0;	# skip the for-loop
1675	}
1676	for (my $ix = 0; $ix < $len; $ix++) {
1677		if (substr($prototype, $ix, 1) eq ',') {
1678			$count++;
1679			if ($count % 2 == 1) {
1680				substr($prototype, $ix, 1) = ' ';
1681			}
1682		}
1683	}
1684}
1685
1686sub process_proto_function($$) {
1687    my $x = shift;
1688    my $file = shift;
1689
1690    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1691
1692    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
1693	# do nothing
1694    }
1695    elsif ($x =~ /([^\{]*)/) {
1696	$prototype .= $1;
1697    }
1698
1699    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1700	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
1701	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1702	$prototype =~ s@^\s+@@gos; # strip leading spaces
1703	if ($prototype =~ /SYSCALL_DEFINE/) {
1704		syscall_munge();
1705	}
1706	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
1707	    $prototype =~ /DEFINE_SINGLE_EVENT/)
1708	{
1709		tracepoint_munge($file);
1710	}
1711	dump_function($prototype, $file);
1712	reset_state();
1713    }
1714}
1715
1716sub process_proto_type($$) {
1717    my $x = shift;
1718    my $file = shift;
1719
1720    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
1721    $x =~ s@^\s+@@gos; # strip leading spaces
1722    $x =~ s@\s+$@@gos; # strip trailing spaces
1723    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
1724
1725    if ($x =~ /^#/) {
1726	# To distinguish preprocessor directive from regular declaration later.
1727	$x .= ";";
1728    }
1729
1730    while (1) {
1731	if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
1732            if( length $prototype ) {
1733                $prototype .= " "
1734            }
1735	    $prototype .= $1 . $2;
1736	    ($2 eq '{') && $brcount++;
1737	    ($2 eq '}') && $brcount--;
1738	    if (($2 eq ';') && ($brcount == 0)) {
1739		dump_declaration($prototype, $file);
1740		reset_state();
1741		last;
1742	    }
1743	    $x = $3;
1744	} else {
1745	    $prototype .= $x;
1746	    last;
1747	}
1748    }
1749}
1750
1751# xml_escape: replace <, >, and & in the text stream;
1752#
1753# however, formatting controls that are generated internally/locally in the
1754# kernel-doc script are not escaped here; instead, they begin life like
1755# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
1756# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
1757# just before actual output; (this is done by local_unescape())
1758sub xml_escape($) {
1759	my $text = shift;
1760	if ($output_mode eq "man") {
1761		return $text;
1762	}
1763	$text =~ s/\&/\\\\\\amp;/g;
1764	$text =~ s/\</\\\\\\lt;/g;
1765	$text =~ s/\>/\\\\\\gt;/g;
1766	return $text;
1767}
1768
1769# xml_unescape: reverse the effects of xml_escape
1770sub xml_unescape($) {
1771	my $text = shift;
1772	if ($output_mode eq "man") {
1773		return $text;
1774	}
1775	$text =~ s/\\\\\\amp;/\&/g;
1776	$text =~ s/\\\\\\lt;/</g;
1777	$text =~ s/\\\\\\gt;/>/g;
1778	return $text;
1779}
1780
1781# convert local escape strings to html
1782# local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
1783sub local_unescape($) {
1784	my $text = shift;
1785	if ($output_mode eq "man") {
1786		return $text;
1787	}
1788	$text =~ s/\\\\\\\\lt:/</g;
1789	$text =~ s/\\\\\\\\gt:/>/g;
1790	return $text;
1791}
1792
1793sub map_filename($) {
1794    my $file;
1795    my ($orig_file) = @_;
1796
1797    if (defined($ENV{'SRCTREE'})) {
1798	$file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
1799    } else {
1800	$file = $orig_file;
1801    }
1802
1803    if (defined($source_map{$file})) {
1804	$file = $source_map{$file};
1805    }
1806
1807    return $file;
1808}
1809
1810sub process_export_file($) {
1811    my ($orig_file) = @_;
1812    my $file = map_filename($orig_file);
1813
1814    if (!open(IN,"<$file")) {
1815	print STDERR "Error: Cannot open file $file\n";
1816	++$errors;
1817	return;
1818    }
1819
1820    while (<IN>) {
1821	if (/$export_symbol/) {
1822	    $function_table{$2} = 1;
1823	}
1824    }
1825
1826    close(IN);
1827}
1828
1829sub process_file($) {
1830    my $file;
1831    my $identifier;
1832    my $func;
1833    my $descr;
1834    my $in_purpose = 0;
1835    my $initial_section_counter = $section_counter;
1836    my ($orig_file) = @_;
1837    my $leading_space;
1838
1839    $file = map_filename($orig_file);
1840
1841    if (!open(IN,"<$file")) {
1842	print STDERR "Error: Cannot open file $file\n";
1843	++$errors;
1844	return;
1845    }
1846
1847    $. = 1;
1848
1849    $section_counter = 0;
1850    while (<IN>) {
1851	while (s/\\\s*$//) {
1852	    $_ .= <IN>;
1853	}
1854	# Replace tabs by spaces
1855        while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
1856	if ($state == STATE_NORMAL) {
1857	    if (/$doc_start/o) {
1858		$state = STATE_NAME;	# next line is always the function name
1859		$in_doc_sect = 0;
1860		$declaration_start_line = $. + 1;
1861	    }
1862	} elsif ($state == STATE_NAME) {# this line is the function name (always)
1863	    if (/$doc_block/o) {
1864		$state = STATE_DOCBLOCK;
1865		$contents = "";
1866                $new_start_line = $. + 1;
1867
1868		if ( $1 eq "" ) {
1869			$section = $section_intro;
1870		} else {
1871			$section = $1;
1872		}
1873	    }
1874	    elsif (/$doc_decl/o) {
1875		$identifier = $1;
1876		if (/\s*([\w\s]+?)\s*-/) {
1877		    $identifier = $1;
1878		}
1879
1880		$state = STATE_FIELD;
1881		# if there's no @param blocks need to set up default section
1882		# here
1883		$contents = "";
1884		$section = $section_default;
1885		$new_start_line = $. + 1;
1886		if (/-(.*)/) {
1887		    # strip leading/trailing/multiple spaces
1888		    $descr= $1;
1889		    $descr =~ s/^\s*//;
1890		    $descr =~ s/\s*$//;
1891		    $descr =~ s/\s+/ /g;
1892		    $declaration_purpose = xml_escape($descr);
1893		    $in_purpose = 1;
1894		} else {
1895		    $declaration_purpose = "";
1896		}
1897
1898		if (($declaration_purpose eq "") && $verbose) {
1899			print STDERR "${file}:$.: warning: missing initial short description on line:\n";
1900			print STDERR $_;
1901			++$warnings;
1902		}
1903
1904		if ($identifier =~ m/^struct/) {
1905		    $decl_type = 'struct';
1906		} elsif ($identifier =~ m/^union/) {
1907		    $decl_type = 'union';
1908		} elsif ($identifier =~ m/^enum/) {
1909		    $decl_type = 'enum';
1910		} elsif ($identifier =~ m/^typedef/) {
1911		    $decl_type = 'typedef';
1912		} else {
1913		    $decl_type = 'function';
1914		}
1915
1916		if ($verbose) {
1917		    print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
1918		}
1919	    } else {
1920		print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
1921		" - I thought it was a doc line\n";
1922		++$warnings;
1923		$state = STATE_NORMAL;
1924	    }
1925	} elsif ($state == STATE_FIELD) {	# look for head: lines, and include content
1926	    if (/$doc_sect/i) { # case insensitive for supported section names
1927		$newsection = $1;
1928		$newcontents = $2;
1929
1930		# map the supported section names to the canonical names
1931		if ($newsection =~ m/^description$/i) {
1932		    $newsection = $section_default;
1933		} elsif ($newsection =~ m/^context$/i) {
1934		    $newsection = $section_context;
1935		} elsif ($newsection =~ m/^returns?$/i) {
1936		    $newsection = $section_return;
1937		} elsif ($newsection =~ m/^\@return$/) {
1938		    # special: @return is a section, not a param description
1939		    $newsection = $section_return;
1940		}
1941
1942		if (($contents ne "") && ($contents ne "\n")) {
1943		    if (!$in_doc_sect && $verbose) {
1944			print STDERR "${file}:$.: warning: contents before sections\n";
1945			++$warnings;
1946		    }
1947		    dump_section($file, $section, xml_escape($contents));
1948		    $section = $section_default;
1949		}
1950
1951		$in_doc_sect = 1;
1952		$in_purpose = 0;
1953		$contents = $newcontents;
1954                $new_start_line = $.;
1955		while (substr($contents, 0, 1) eq " ") {
1956		    $contents = substr($contents, 1);
1957		}
1958		if ($contents ne "") {
1959		    $contents .= "\n";
1960		}
1961		$section = $newsection;
1962		$leading_space = undef;
1963	    } elsif (/$doc_end/) {
1964		if (($contents ne "") && ($contents ne "\n")) {
1965		    dump_section($file, $section, xml_escape($contents));
1966		    $section = $section_default;
1967		    $contents = "";
1968		}
1969		# look for doc_com + <text> + doc_end:
1970		if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
1971		    print STDERR "${file}:$.: warning: suspicious ending line: $_";
1972		    ++$warnings;
1973		}
1974
1975		$prototype = "";
1976		$state = STATE_PROTO;
1977		$brcount = 0;
1978#		print STDERR "end of doc comment, looking for prototype\n";
1979	    } elsif (/$doc_content/) {
1980		# miguel-style comment kludge, look for blank lines after
1981		# @parameter line to signify start of description
1982		if ($1 eq "") {
1983		    if ($section =~ m/^@/ || $section eq $section_context) {
1984			dump_section($file, $section, xml_escape($contents));
1985			$section = $section_default;
1986			$contents = "";
1987                        $new_start_line = $.;
1988		    } else {
1989			$contents .= "\n";
1990		    }
1991		    $in_purpose = 0;
1992		} elsif ($in_purpose == 1) {
1993		    # Continued declaration purpose
1994		    chomp($declaration_purpose);
1995		    $declaration_purpose .= " " . xml_escape($1);
1996		    $declaration_purpose =~ s/\s+/ /g;
1997		} else {
1998		    my $cont = $1;
1999		    if ($section =~ m/^@/ || $section eq $section_context) {
2000			if (!defined $leading_space) {
2001			    if ($cont =~ m/^(\s+)/) {
2002				$leading_space = $1;
2003			    } else {
2004				$leading_space = "";
2005			    }
2006			}
2007
2008			$cont =~ s/^$leading_space//;
2009		    }
2010		    $contents .= $cont . "\n";
2011		}
2012	    } else {
2013		# i dont know - bad line?  ignore.
2014		print STDERR "${file}:$.: warning: bad line: $_";
2015		++$warnings;
2016	    }
2017	} elsif ($state == STATE_INLINE) { # scanning for inline parameters
2018	    # First line (state 1) needs to be a @parameter
2019	    if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2020		$section = $1;
2021		$contents = $2;
2022                $new_start_line = $.;
2023		if ($contents ne "") {
2024		    while (substr($contents, 0, 1) eq " ") {
2025			$contents = substr($contents, 1);
2026		    }
2027		    $contents .= "\n";
2028		}
2029		$inline_doc_state = STATE_INLINE_TEXT;
2030	    # Documentation block end */
2031	    } elsif (/$doc_inline_end/) {
2032		if (($contents ne "") && ($contents ne "\n")) {
2033		    dump_section($file, $section, xml_escape($contents));
2034		    $section = $section_default;
2035		    $contents = "";
2036		}
2037		$state = STATE_PROTO;
2038		$inline_doc_state = STATE_INLINE_NA;
2039	    # Regular text
2040	    } elsif (/$doc_content/) {
2041		if ($inline_doc_state == STATE_INLINE_TEXT) {
2042		    $contents .= $1 . "\n";
2043		    # nuke leading blank lines
2044		    if ($contents =~ /^\s*$/) {
2045			$contents = "";
2046		    }
2047		} elsif ($inline_doc_state == STATE_INLINE_NAME) {
2048		    $inline_doc_state = STATE_INLINE_ERROR;
2049		    print STDERR "${file}:$.: warning: ";
2050		    print STDERR "Incorrect use of kernel-doc format: $_";
2051		    ++$warnings;
2052		}
2053	    }
2054	} elsif ($state == STATE_PROTO) {	# scanning for function '{' (end of prototype)
2055	    if (/$doc_inline_oneline/) {
2056		$section = $1;
2057		$contents = $2;
2058		if ($contents ne "") {
2059		    $contents .= "\n";
2060		    dump_section($file, $section, xml_escape($contents));
2061		    $section = $section_default;
2062		    $contents = "";
2063		}
2064	    } elsif (/$doc_inline_start/) {
2065		$state = STATE_INLINE;
2066		$inline_doc_state = STATE_INLINE_NAME;
2067	    } elsif ($decl_type eq 'function') {
2068		process_proto_function($_, $file);
2069	    } else {
2070		process_proto_type($_, $file);
2071	    }
2072	} elsif ($state == STATE_DOCBLOCK) {
2073		if (/$doc_end/)
2074		{
2075			dump_doc_section($file, $section, xml_escape($contents));
2076			$section = $section_default;
2077			$contents = "";
2078			$function = "";
2079			%parameterdescs = ();
2080			%parametertypes = ();
2081			@parameterlist = ();
2082			%sections = ();
2083			@sectionlist = ();
2084			$prototype = "";
2085			$state = STATE_NORMAL;
2086		}
2087		elsif (/$doc_content/)
2088		{
2089			if ( $1 eq "" )
2090			{
2091				$contents .= $blankline;
2092			}
2093			else
2094			{
2095				$contents .= $1 . "\n";
2096			}
2097		}
2098	}
2099    }
2100    if ($initial_section_counter == $section_counter) {
2101	if ($output_mode ne "none") {
2102	    print STDERR "${file}:1: warning: no structured comments found\n";
2103	}
2104	if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2105	    print STDERR "    Was looking for '$_'.\n" for keys %function_table;
2106	}
2107    }
2108}
2109
2110
2111$kernelversion = get_kernel_version();
2112
2113# generate a sequence of code that will splice in highlighting information
2114# using the s// operator.
2115for (my $k = 0; $k < @highlights; $k++) {
2116    my $pattern = $highlights[$k][0];
2117    my $result = $highlights[$k][1];
2118#   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2119    $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
2120}
2121
2122# Read the file that maps relative names to absolute names for
2123# separate source and object directories and for shadow trees.
2124if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2125	my ($relname, $absname);
2126	while(<SOURCE_MAP>) {
2127		chop();
2128		($relname, $absname) = (split())[0..1];
2129		$relname =~ s:^/+::;
2130		$source_map{$relname} = $absname;
2131	}
2132	close(SOURCE_MAP);
2133}
2134
2135if ($output_selection == OUTPUT_EXPORTED ||
2136    $output_selection == OUTPUT_INTERNAL) {
2137
2138    push(@export_file_list, @ARGV);
2139
2140    foreach (@export_file_list) {
2141	chomp;
2142	process_export_file($_);
2143    }
2144}
2145
2146foreach (@ARGV) {
2147    chomp;
2148    process_file($_);
2149}
2150if ($verbose && $errors) {
2151  print STDERR "$errors errors\n";
2152}
2153if ($verbose && $warnings) {
2154  print STDERR "$warnings warnings\n";
2155}
2156
2157exit($output_mode eq "none" ? 0 : $errors);
2158