scripts/kernel-doc

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