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