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