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