scripts/kernel-doc

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