scripts/kernel-doc

   1 #!/usr/bin/perl -w
   2
   3 use strict;
   4
   5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
   6 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
   7 ## Copyright (C) 2001  Simon Huggins                             ##
   8 ## Copyright (C) 2005-2012  Randy Dunlap                         ##
   9 ## Copyright (C) 2012  Dan Luedtke                               ##
  10 ##                                                               ##
  11 ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
  12 ## Copyright (c) 2000 MontaVista Software, Inc.                  ##
  13 ##                                                               ##
  14 ## This software falls under the GNU General Public License.     ##
  15 ## Please read the COPYING file for more information             ##
  16
  17 # 18/01/2001 -  Cleanups
  18 #               Functions prototyped as foo(void) same as foo()
  19 #               Stop eval'ing where we don't need to.
  20 # -- huggie@earth.li
  21
  22 # 27/06/2001 -  Allowed whitespace after initial "/**" and
  23 #               allowed comments before function declarations.
  24 # -- Christian Kreibich <ck@whoop.org>
  25
  26 # Still to do:
  27 #       - add perldoc documentation
  28 #       - Look more closely at some of the scarier bits :)
  29
  30 # 26/05/2001 -  Support for separate source and object trees.
  31 #               Return error code.
  32 #               Keith Owens <kaos@ocs.com.au>
  33
  34 # 23/09/2001 - Added support for typedefs, structs, enums and unions
  35 #              Support for Context section; can be terminated using empty line
  36 #              Small fixes (like spaces vs. \s in regex)
  37 # -- Tim Jansen <tim@tjansen.de>
  38
  39 # 25/07/2012 - Added support for HTML5
  40 # -- Dan Luedtke <mail@danrl.de>
  41
  42 sub usage {
  43     my $message = <<"EOF";
  44 Usage: $0 [OPTION ...] FILE ...
  45
  46 Read C language source or header FILEs, extract embedded documentation comments,
  47 and print formatted documentation to standard output.
  48
  49 The documentation comments are identified by "/**" opening comment mark. See
  50 Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
  51
  52 Output format selection (mutually exclusive):
  53   -docbook              Output DocBook format.
  54   -html                 Output HTML format.
  55   -html5                Output HTML5 format.
  56   -list                 Output symbol list format. This is for use by docproc.
  57   -man                  Output troff manual page format. This is the default.
  58   -rst                  Output reStructuredText format.
  59   -text                 Output plain text format.
  60
  61 Output selection (mutually exclusive):
  62   -export               Only output documentation for symbols that have been
  63                         exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
  64                         in the same FILE.
  65   -internal             Only output documentation for symbols that have NOT been
  66                         exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
  67                         in the same FILE.
  68   -function NAME        Only output documentation for the given function(s)
  69                         or DOC: section title(s). All other functions and DOC:
  70                         sections are ignored. May be specified multiple times.
  71   -nofunction NAME      Do NOT output documentation for the given function(s);
  72                         only output documentation for the other functions and
  73                         DOC: sections. May be specified multiple times.
  74
  75 Output selection modifiers:
  76   -no-doc-sections      Do not output DOC: sections.
  77   -enable-lineno        Enable output of #define LINENO lines. Only works with
  78                         reStructuredText format.
  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 # '@parameter' - name of a parameter
 200 # '%CONST' - name of a constant.
 201
 202 ## init lots of data
 203
 204 my $errors = 0;
 205 my $warnings = 0;
 206 my $anon_struct_union = 0;
 207
 208 # match expressions used to find embedded type information
 209 my $type_constant = '\%([-_\w]+)';
 210 my $type_func = '(\w+)\(\)';
 211 my $type_param = '\@(\w+)';
 212 my $type_struct = '\&((struct\s*)*[_\w]+)';
 213 my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
 214 my $type_env = '(\$\w+)';
 215 my $type_enum_full = '\&(enum)\s*([_\w]+)';
 216 my $type_struct_full = '\&(struct)\s*([_\w]+)';
 217 my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
 218 my $type_union_full = '\&(union)\s*([_\w]+)';
 219 my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
 220 my $type_member_func = $type_member . '\(\)';
 221
 222 # Output conversion substitutions.
 223 #  One for each output format
 224
 225 # these work fairly well
 226 my @highlights_html = (
 227                        [$type_constant, "<i>\$1</i>"],
 228                        [$type_func, "<b>\$1</b>"],
 229                        [$type_struct_xml, "<i>\$1</i>"],
 230                        [$type_env, "<b><i>\$1</i></b>"],
 231                        [$type_param, "<tt><b>\$1</b></tt>"]
 232                       );
 233 my $local_lt = "\\\\\\\\lt:";
 234 my $local_gt = "\\\\\\\\gt:";
 235 my $blankline_html = $local_lt . "p" . $local_gt;       # was "<p>"
 236
 237 # html version 5
 238 my @highlights_html5 = (
 239                         [$type_constant, "<span class=\"const\">\$1</span>"],
 240                         [$type_func, "<span class=\"func\">\$1</span>"],
 241                         [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
 242                         [$type_env, "<span class=\"env\">\$1</span>"],
 243                         [$type_param, "<span class=\"param\">\$1</span>]"]
 244                        );
 245 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 246
 247 # XML, docbook format
 248 my @highlights_xml = (
 249                       ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
 250                       [$type_constant, "<constant>\$1</constant>"],
 251                       [$type_struct_xml, "<structname>\$1</structname>"],
 252                       [$type_param, "<parameter>\$1</parameter>"],
 253                       [$type_func, "<function>\$1</function>"],
 254                       [$type_env, "<envar>\$1</envar>"]
 255                      );
 256 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
 257
 258 # gnome, docbook format
 259 my @highlights_gnome = (
 260                         [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
 261                         [$type_func, "<function>\$1</function>"],
 262                         [$type_struct, "<structname>\$1</structname>"],
 263                         [$type_env, "<envar>\$1</envar>"],
 264                         [$type_param, "<parameter>\$1</parameter>" ]
 265                        );
 266 my $blankline_gnome = "</para><para>\n";
 267
 268 # these are pretty rough
 269 my @highlights_man = (
 270                       [$type_constant, "\$1"],
 271                       [$type_func, "\\\\fB\$1\\\\fP"],
 272                       [$type_struct, "\\\\fI\$1\\\\fP"],
 273                       [$type_param, "\\\\fI\$1\\\\fP"]
 274                      );
 275 my $blankline_man = "";
 276
 277 # text-mode
 278 my @highlights_text = (
 279                        [$type_constant, "\$1"],
 280                        [$type_func, "\$1"],
 281                        [$type_struct, "\$1"],
 282                        [$type_param, "\$1"]
 283                       );
 284 my $blankline_text = "";
 285
 286 # rst-mode
 287 my @highlights_rst = (
 288                        [$type_constant, "``\$1``"],
 289                        # Note: need to escape () to avoid func matching later
 290                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
 291                        [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
 292                        [$type_func, "\\:c\\:func\\:`\$1()`"],
 293                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
 294                        [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
 295                        [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
 296                        [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
 297                        # in rst this can refer to any type
 298                        [$type_struct, "\\:c\\:type\\:`\$1`"],
 299                        [$type_param, "**\$1**"]
 300                       );
 301 my $blankline_rst = "\n";
 302
 303 # list mode
 304 my @highlights_list = (
 305                        [$type_constant, "\$1"],
 306                        [$type_func, "\$1"],
 307                        [$type_struct, "\$1"],
 308                        [$type_param, "\$1"]
 309                       );
 310 my $blankline_list = "";
 311
 312 # read arguments
 313 if ($#ARGV == -1) {
 314     usage();
 315 }
 316
 317 my $kernelversion;
 318 my $dohighlight = "";
 319
 320 my $verbose = 0;
 321 my $output_mode = "man";
 322 my $output_preformatted = 0;
 323 my $no_doc_sections = 0;
 324 my $enable_lineno = 0;
 325 my @highlights = @highlights_man;
 326 my $blankline = $blankline_man;
 327 my $modulename = "Kernel API";
 328
 329 use constant {
 330     OUTPUT_ALL          => 0, # output all symbols and doc sections
 331     OUTPUT_INCLUDE      => 1, # output only specified symbols
 332     OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
 333     OUTPUT_EXPORTED     => 3, # output exported symbols
 334     OUTPUT_INTERNAL     => 4, # output non-exported symbols
 335 };
 336 my $output_selection = OUTPUT_ALL;
 337 my $show_not_found = 0;
 338
 339 my @build_time;
 340 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
 341     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
 342     @build_time = gmtime($seconds);
 343 } else {
 344     @build_time = localtime;
 345 }
 346
 347 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
 348                 'July', 'August', 'September', 'October',
 349                 'November', 'December')[$build_time[4]] .
 350   " " . ($build_time[5]+1900);
 351
 352 # Essentially these are globals.
 353 # They probably want to be tidied up, made more localised or something.
 354 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
 355 # could cause "use of undefined value" or other bugs.
 356 my ($function, %function_table, %parametertypes, $declaration_purpose);
 357 my $declaration_start_line;
 358 my ($type, $declaration_name, $return_type);
 359 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
 360
 361 if (defined($ENV{'KBUILD_VERBOSE'})) {
 362         $verbose = "$ENV{'KBUILD_VERBOSE'}";
 363 }
 364
 365 # Generated docbook code is inserted in a template at a point where
 366 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
 367 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
 368 # We keep track of number of generated entries and generate a dummy
 369 # if needs be to ensure the expanded template can be postprocessed
 370 # into html.
 371 my $section_counter = 0;
 372
 373 my $lineprefix="";
 374
 375 # Parser states
 376 use constant {
 377     STATE_NORMAL        => 0, # normal code
 378     STATE_NAME          => 1, # looking for function name
 379     STATE_FIELD         => 2, # scanning field start
 380     STATE_PROTO         => 3, # scanning prototype
 381     STATE_DOCBLOCK      => 4, # documentation block
 382     STATE_INLINE        => 5, # gathering documentation outside main block
 383 };
 384 my $state;
 385 my $in_doc_sect;
 386
 387 # Inline documentation state
 388 use constant {
 389     STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
 390     STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
 391     STATE_INLINE_TEXT   => 2, # looking for member documentation
 392     STATE_INLINE_END    => 3, # done
 393     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
 394                               # Spit a warning as it's not
 395                               # proper kernel-doc and ignore the rest.
 396 };
 397 my $inline_doc_state;
 398
 399 #declaration types: can be
 400 # 'function', 'struct', 'union', 'enum', 'typedef'
 401 my $decl_type;
 402
 403 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
 404 my $doc_end = '\*/';
 405 my $doc_com = '\s*\*\s*';
 406 my $doc_com_body = '\s*\* ?';
 407 my $doc_decl = $doc_com . '(\w+)';
 408 # @params and a strictly limited set of supported section names
 409 my $doc_sect = $doc_com .
 410     '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)';
 411 my $doc_content = $doc_com_body . '(.*)';
 412 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 413 my $doc_inline_start = '^\s*/\*\*\s*$';
 414 my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
 415 my $doc_inline_end = '^\s*\*/\s*$';
 416 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
 417
 418 my %parameterdescs;
 419 my %parameterdesc_start_lines;
 420 my @parameterlist;
 421 my %sections;
 422 my @sectionlist;
 423 my %section_start_lines;
 424 my $sectcheck;
 425 my $struct_actual;
 426
 427 my $contents = "";
 428 my $new_start_line = 0;
 429
 430 # the canonical section names. see also $doc_sect above.
 431 my $section_default = "Description";    # default section
 432 my $section_intro = "Introduction";
 433 my $section = $section_default;
 434 my $section_context = "Context";
 435 my $section_return = "Return";
 436
 437 my $undescribed = "-- undescribed --";
 438
 439 reset_state();
 440
 441 while ($ARGV[0] =~ m/^-(.*)/) {
 442     my $cmd = shift @ARGV;
 443     if ($cmd eq "-html") {
 444         $output_mode = "html";
 445         @highlights = @highlights_html;
 446         $blankline = $blankline_html;
 447     } elsif ($cmd eq "-html5") {
 448         $output_mode = "html5";
 449         @highlights = @highlights_html5;
 450         $blankline = $blankline_html5;
 451     } elsif ($cmd eq "-man") {
 452         $output_mode = "man";
 453         @highlights = @highlights_man;
 454         $blankline = $blankline_man;
 455     } elsif ($cmd eq "-text") {
 456         $output_mode = "text";
 457         @highlights = @highlights_text;
 458         $blankline = $blankline_text;
 459     } elsif ($cmd eq "-rst") {
 460         $output_mode = "rst";
 461         @highlights = @highlights_rst;
 462         $blankline = $blankline_rst;
 463     } elsif ($cmd eq "-docbook") {
 464         $output_mode = "xml";
 465         @highlights = @highlights_xml;
 466         $blankline = $blankline_xml;
 467     } elsif ($cmd eq "-list") {
 468         $output_mode = "list";
 469         @highlights = @highlights_list;
 470         $blankline = $blankline_list;
 471     } elsif ($cmd eq "-gnome") {
 472         $output_mode = "gnome";
 473         @highlights = @highlights_gnome;
 474         $blankline = $blankline_gnome;
 475     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
 476         $modulename = shift @ARGV;
 477     } elsif ($cmd eq "-function") { # to only output specific functions
 478         $output_selection = OUTPUT_INCLUDE;
 479         $function = shift @ARGV;
 480         $function_table{$function} = 1;
 481     } elsif ($cmd eq "-nofunction") { # output all except specific functions
 482         $output_selection = OUTPUT_EXCLUDE;
 483         $function = shift @ARGV;
 484         $function_table{$function} = 1;
 485     } elsif ($cmd eq "-export") { # only exported symbols
 486         $output_selection = OUTPUT_EXPORTED;
 487         %function_table = ()
 488     } elsif ($cmd eq "-internal") { # only non-exported symbols
 489         $output_selection = OUTPUT_INTERNAL;
 490         %function_table = ()
 491     } elsif ($cmd eq "-v") {
 492         $verbose = 1;
 493     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
 494         usage();
 495     } elsif ($cmd eq '-no-doc-sections') {
 496             $no_doc_sections = 1;
 497     } elsif ($cmd eq '-enable-lineno') {
 498             $enable_lineno = 1;
 499     } elsif ($cmd eq '-show-not-found') {
 500         $show_not_found = 1;
 501     }
 502 }
 503
 504 # continue execution near EOF;
 505
 506 # get kernel version from env
 507 sub get_kernel_version() {
 508     my $version = 'unknown kernel version';
 509
 510     if (defined($ENV{'KERNELVERSION'})) {
 511         $version = $ENV{'KERNELVERSION'};
 512     }
 513     return $version;
 514 }
 515
 516 #
 517 sub print_lineno {
 518     my $lineno = shift;
 519     if ($enable_lineno && defined($lineno)) {
 520         print "#define LINENO " . $lineno . "\n";
 521     }
 522 }
 523 ##
 524 # dumps section contents to arrays/hashes intended for that purpose.
 525 #
 526 sub dump_section {
 527     my $file = shift;
 528     my $name = shift;
 529     my $contents = join "\n", @_;
 530
 531     if ($name =~ m/$type_param/) {
 532 #       print STDERR "parameter def '$1' = '$contents'\n";
 533         $name = $1;
 534         $parameterdescs{$name} = $contents;
 535         $sectcheck = $sectcheck . $name . " ";
 536         $parameterdesc_start_lines{$name} = $new_start_line;
 537         $new_start_line = 0;
 538     } elsif ($name eq "@\.\.\.") {
 539 #       print STDERR "parameter def '...' = '$contents'\n";
 540         $name = "...";
 541         $parameterdescs{$name} = $contents;
 542         $sectcheck = $sectcheck . $name . " ";
 543         $parameterdesc_start_lines{$name} = $new_start_line;
 544         $new_start_line = 0;
 545     } else {
 546 #       print STDERR "other section '$name' = '$contents'\n";
 547         if (defined($sections{$name}) && ($sections{$name} ne "")) {
 548             print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
 549             ++$warnings;
 550             $sections{$name} .= $contents;
 551         } else {
 552             $sections{$name} = $contents;
 553             push @sectionlist, $name;
 554             $section_start_lines{$name} = $new_start_line;
 555             $new_start_line = 0;
 556         }
 557     }
 558 }
 559
 560 ##
 561 # dump DOC: section after checking that it should go out
 562 #
 563 sub dump_doc_section {
 564     my $file = shift;
 565     my $name = shift;
 566     my $contents = join "\n", @_;
 567
 568     if ($no_doc_sections) {
 569         return;
 570     }
 571
 572     if (($output_selection == OUTPUT_ALL) ||
 573         ($output_selection == OUTPUT_INCLUDE &&
 574          defined($function_table{$name})) ||
 575         ($output_selection == OUTPUT_EXCLUDE &&
 576          !defined($function_table{$name})))
 577     {
 578         dump_section($file, $name, $contents);
 579         output_blockhead({'sectionlist' => \@sectionlist,
 580                           'sections' => \%sections,
 581                           'module' => $modulename,
 582                           'content-only' => ($output_selection != OUTPUT_ALL), });
 583     }
 584 }
 585
 586 ##
 587 # output function
 588 #
 589 # parameterdescs, a hash.
 590 #  function => "function name"
 591 #  parameterlist => @list of parameters
 592 #  parameterdescs => %parameter descriptions
 593 #  sectionlist => @list of sections
 594 #  sections => %section descriptions
 595 #
 596
 597 sub output_highlight {
 598     my $contents = join "\n",@_;
 599     my $line;
 600
 601 #   DEBUG
 602 #   if (!defined $contents) {
 603 #       use Carp;
 604 #       confess "output_highlight got called with no args?\n";
 605 #   }
 606
 607     if ($output_mode eq "html" || $output_mode eq "html5" ||
 608         $output_mode eq "xml") {
 609         $contents = local_unescape($contents);
 610         # convert data read & converted thru xml_escape() into &xyz; format:
 611         $contents =~ s/\\\\\\/\&/g;
 612     }
 613 #   print STDERR "contents b4:$contents\n";
 614     eval $dohighlight;
 615     die $@ if $@;
 616 #   print STDERR "contents af:$contents\n";
 617
 618 #   strip whitespaces when generating html5
 619     if ($output_mode eq "html5") {
 620         $contents =~ s/^\s+//;
 621         $contents =~ s/\s+$//;
 622     }
 623     foreach $line (split "\n", $contents) {
 624         if (! $output_preformatted) {
 625             $line =~ s/^\s*//;
 626         }
 627         if ($line eq ""){
 628             if (! $output_preformatted) {
 629                 print $lineprefix, local_unescape($blankline);
 630             }
 631         } else {
 632             $line =~ s/\\\\\\/\&/g;
 633             if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
 634                 print "\\&$line";
 635             } else {
 636                 print $lineprefix, $line;
 637             }
 638         }
 639         print "\n";
 640     }
 641 }
 642
 643 # output sections in html
 644 sub output_section_html(%) {
 645     my %args = %{$_[0]};
 646     my $section;
 647
 648     foreach $section (@{$args{'sectionlist'}}) {
 649         print "<h3>$section</h3>\n";
 650         print "<blockquote>\n";
 651         output_highlight($args{'sections'}{$section});
 652         print "</blockquote>\n";
 653     }
 654 }
 655
 656 # output enum in html
 657 sub output_enum_html(%) {
 658     my %args = %{$_[0]};
 659     my ($parameter);
 660     my $count;
 661     print "<h2>enum " . $args{'enum'} . "</h2>\n";
 662
 663     print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
 664     $count = 0;
 665     foreach $parameter (@{$args{'parameterlist'}}) {
 666         print " <b>" . $parameter . "</b>";
 667         if ($count != $#{$args{'parameterlist'}}) {
 668             $count++;
 669             print ",\n";
 670         }
 671         print "<br>";
 672     }
 673     print "};<br>\n";
 674
 675     print "<h3>Constants</h3>\n";
 676     print "<dl>\n";
 677     foreach $parameter (@{$args{'parameterlist'}}) {
 678         print "<dt><b>" . $parameter . "</b>\n";
 679         print "<dd>";
 680         output_highlight($args{'parameterdescs'}{$parameter});
 681     }
 682     print "</dl>\n";
 683     output_section_html(@_);
 684     print "<hr>\n";
 685 }
 686
 687 # output typedef in html
 688 sub output_typedef_html(%) {
 689     my %args = %{$_[0]};
 690     my ($parameter);
 691     my $count;
 692     print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
 693
 694     print "<b>typedef " . $args{'typedef'} . "</b>\n";
 695     output_section_html(@_);
 696     print "<hr>\n";
 697 }
 698
 699 # output struct in html
 700 sub output_struct_html(%) {
 701     my %args = %{$_[0]};
 702     my ($parameter);
 703
 704     print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
 705     print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
 706     foreach $parameter (@{$args{'parameterlist'}}) {
 707         if ($parameter =~ /^#/) {
 708                 print "$parameter<br>\n";
 709                 next;
 710         }
 711         my $parameter_name = $parameter;
 712         $parameter_name =~ s/\[.*//;
 713
 714         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 715         $type = $args{'parametertypes'}{$parameter};
 716         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 717             # pointer-to-function
 718             print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
 719         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 720             # bitfield
 721             print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
 722         } else {
 723             print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
 724         }
 725     }
 726     print "};<br>\n";
 727
 728     print "<h3>Members</h3>\n";
 729     print "<dl>\n";
 730     foreach $parameter (@{$args{'parameterlist'}}) {
 731         ($parameter =~ /^#/) && next;
 732
 733         my $parameter_name = $parameter;
 734         $parameter_name =~ s/\[.*//;
 735
 736         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 737         print "<dt><b>" . $parameter . "</b>\n";
 738         print "<dd>";
 739         output_highlight($args{'parameterdescs'}{$parameter_name});
 740     }
 741     print "</dl>\n";
 742     output_section_html(@_);
 743     print "<hr>\n";
 744 }
 745
 746 # output function in html
 747 sub output_function_html(%) {
 748     my %args = %{$_[0]};
 749     my ($parameter, $section);
 750     my $count;
 751
 752     print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
 753     print "<i>" . $args{'functiontype'} . "</i>\n";
 754     print "<b>" . $args{'function'} . "</b>\n";
 755     print "(";
 756     $count = 0;
 757     foreach $parameter (@{$args{'parameterlist'}}) {
 758         $type = $args{'parametertypes'}{$parameter};
 759         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 760             # pointer-to-function
 761             print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
 762         } else {
 763             print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
 764         }
 765         if ($count != $#{$args{'parameterlist'}}) {
 766             $count++;
 767             print ",\n";
 768         }
 769     }
 770     print ")\n";
 771
 772     print "<h3>Arguments</h3>\n";
 773     print "<dl>\n";
 774     foreach $parameter (@{$args{'parameterlist'}}) {
 775         my $parameter_name = $parameter;
 776         $parameter_name =~ s/\[.*//;
 777
 778         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 779         print "<dt><b>" . $parameter . "</b>\n";
 780         print "<dd>";
 781         output_highlight($args{'parameterdescs'}{$parameter_name});
 782     }
 783     print "</dl>\n";
 784     output_section_html(@_);
 785     print "<hr>\n";
 786 }
 787
 788 # output DOC: block header in html
 789 sub output_blockhead_html(%) {
 790     my %args = %{$_[0]};
 791     my ($parameter, $section);
 792     my $count;
 793
 794     foreach $section (@{$args{'sectionlist'}}) {
 795         print "<h3>$section</h3>\n";
 796         print "<ul>\n";
 797         output_highlight($args{'sections'}{$section});
 798         print "</ul>\n";
 799     }
 800     print "<hr>\n";
 801 }
 802
 803 # output sections in html5
 804 sub output_section_html5(%) {
 805     my %args = %{$_[0]};
 806     my $section;
 807
 808     foreach $section (@{$args{'sectionlist'}}) {
 809         print "<section>\n";
 810         print "<h1>$section</h1>\n";
 811         print "<p>\n";
 812         output_highlight($args{'sections'}{$section});
 813         print "</p>\n";
 814         print "</section>\n";
 815     }
 816 }
 817
 818 # output enum in html5
 819 sub output_enum_html5(%) {
 820     my %args = %{$_[0]};
 821     my ($parameter);
 822     my $count;
 823     my $html5id;
 824
 825     $html5id = $args{'enum'};
 826     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 827     print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
 828     print "<h1>enum " . $args{'enum'} . "</h1>\n";
 829     print "<ol class=\"code\">\n";
 830     print "<li>";
 831     print "<span class=\"keyword\">enum</span> ";
 832     print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
 833     print "</li>\n";
 834     $count = 0;
 835     foreach $parameter (@{$args{'parameterlist'}}) {
 836         print "<li class=\"indent\">";
 837         print "<span class=\"param\">" . $parameter . "</span>";
 838         if ($count != $#{$args{'parameterlist'}}) {
 839             $count++;
 840             print ",";
 841         }
 842         print "</li>\n";
 843     }
 844     print "<li>};</li>\n";
 845     print "</ol>\n";
 846
 847     print "<section>\n";
 848     print "<h1>Constants</h1>\n";
 849     print "<dl>\n";
 850     foreach $parameter (@{$args{'parameterlist'}}) {
 851         print "<dt>" . $parameter . "</dt>\n";
 852         print "<dd>";
 853         output_highlight($args{'parameterdescs'}{$parameter});
 854         print "</dd>\n";
 855     }
 856     print "</dl>\n";
 857     print "</section>\n";
 858     output_section_html5(@_);
 859     print "</article>\n";
 860 }
 861
 862 # output typedef in html5
 863 sub output_typedef_html5(%) {
 864     my %args = %{$_[0]};
 865     my ($parameter);
 866     my $count;
 867     my $html5id;
 868
 869     $html5id = $args{'typedef'};
 870     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 871     print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
 872     print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
 873
 874     print "<ol class=\"code\">\n";
 875     print "<li>";
 876     print "<span class=\"keyword\">typedef</span> ";
 877     print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
 878     print "</li>\n";
 879     print "</ol>\n";
 880     output_section_html5(@_);
 881     print "</article>\n";
 882 }
 883
 884 # output struct in html5
 885 sub output_struct_html5(%) {
 886     my %args = %{$_[0]};
 887     my ($parameter);
 888     my $html5id;
 889
 890     $html5id = $args{'struct'};
 891     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 892     print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
 893     print "<hgroup>\n";
 894     print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
 895     print "<h2>". $args{'purpose'} . "</h2>\n";
 896     print "</hgroup>\n";
 897     print "<ol class=\"code\">\n";
 898     print "<li>";
 899     print "<span class=\"type\">" . $args{'type'} . "</span> ";
 900     print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
 901     print "</li>\n";
 902     foreach $parameter (@{$args{'parameterlist'}}) {
 903         print "<li class=\"indent\">";
 904         if ($parameter =~ /^#/) {
 905                 print "<span class=\"param\">" . $parameter ."</span>\n";
 906                 print "</li>\n";
 907                 next;
 908         }
 909         my $parameter_name = $parameter;
 910         $parameter_name =~ s/\[.*//;
 911
 912         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 913         $type = $args{'parametertypes'}{$parameter};
 914         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 915             # pointer-to-function
 916             print "<span class=\"type\">$1</span> ";
 917             print "<span class=\"param\">$parameter</span>";
 918             print "<span class=\"type\">)</span> ";
 919             print "(<span class=\"args\">$2</span>);";
 920         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
 921             # bitfield
 922             print "<span class=\"type\">$1</span> ";
 923             print "<span class=\"param\">$parameter</span>";
 924             print "<span class=\"bits\">$2</span>;";
 925         } else {
 926             print "<span class=\"type\">$type</span> ";
 927             print "<span class=\"param\">$parameter</span>;";
 928         }
 929         print "</li>\n";
 930     }
 931     print "<li>};</li>\n";
 932     print "</ol>\n";
 933
 934     print "<section>\n";
 935     print "<h1>Members</h1>\n";
 936     print "<dl>\n";
 937     foreach $parameter (@{$args{'parameterlist'}}) {
 938         ($parameter =~ /^#/) && next;
 939
 940         my $parameter_name = $parameter;
 941         $parameter_name =~ s/\[.*//;
 942
 943         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 944         print "<dt>" . $parameter . "</dt>\n";
 945         print "<dd>";
 946         output_highlight($args{'parameterdescs'}{$parameter_name});
 947         print "</dd>\n";
 948     }
 949     print "</dl>\n";
 950     print "</section>\n";
 951     output_section_html5(@_);
 952     print "</article>\n";
 953 }
 954
 955 # output function in html5
 956 sub output_function_html5(%) {
 957     my %args = %{$_[0]};
 958     my ($parameter, $section);
 959     my $count;
 960     my $html5id;
 961
 962     $html5id = $args{'function'};
 963     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
 964     print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
 965     print "<hgroup>\n";
 966     print "<h1>" . $args{'function'} . "</h1>";
 967     print "<h2>" . $args{'purpose'} . "</h2>\n";
 968     print "</hgroup>\n";
 969     print "<ol class=\"code\">\n";
 970     print "<li>";
 971     print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
 972     print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
 973     print "</li>";
 974     $count = 0;
 975     foreach $parameter (@{$args{'parameterlist'}}) {
 976         print "<li class=\"indent\">";
 977         $type = $args{'parametertypes'}{$parameter};
 978         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 979             # pointer-to-function
 980             print "<span class=\"type\">$1</span> ";
 981             print "<span class=\"param\">$parameter</span>";
 982             print "<span class=\"type\">)</span> ";
 983             print "(<span class=\"args\">$2</span>)";
 984         } else {
 985             print "<span class=\"type\">$type</span> ";
 986             print "<span class=\"param\">$parameter</span>";
 987         }
 988         if ($count != $#{$args{'parameterlist'}}) {
 989             $count++;
 990             print ",";
 991         }
 992         print "</li>\n";
 993     }
 994     print "<li>)</li>\n";
 995     print "</ol>\n";
 996
 997     print "<section>\n";
 998     print "<h1>Arguments</h1>\n";
 999     print "<p>\n";
1000     print "<dl>\n";
1001     foreach $parameter (@{$args{'parameterlist'}}) {
1002         my $parameter_name = $parameter;
1003         $parameter_name =~ s/\[.*//;
1004
1005         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1006         print "<dt>" . $parameter . "</dt>\n";
1007         print "<dd>";
1008         output_highlight($args{'parameterdescs'}{$parameter_name});
1009         print "</dd>\n";
1010     }
1011     print "</dl>\n";
1012     print "</section>\n";
1013     output_section_html5(@_);
1014     print "</article>\n";
1015 }
1016
1017 # output DOC: block header in html5
1018 sub output_blockhead_html5(%) {
1019     my %args = %{$_[0]};
1020     my ($parameter, $section);
1021     my $count;
1022     my $html5id;
1023
1024     foreach $section (@{$args{'sectionlist'}}) {
1025         $html5id = $section;
1026         $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1027         print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
1028         print "<h1>$section</h1>\n";
1029         print "<p>\n";
1030         output_highlight($args{'sections'}{$section});
1031         print "</p>\n";
1032     }
1033     print "</article>\n";
1034 }
1035
1036 sub output_section_xml(%) {
1037     my %args = %{$_[0]};
1038     my $section;
1039     # print out each section
1040     $lineprefix="   ";
1041     foreach $section (@{$args{'sectionlist'}}) {
1042         print "<refsect1>\n";
1043         print "<title>$section</title>\n";
1044         if ($section =~ m/EXAMPLE/i) {
1045             print "<informalexample><programlisting>\n";
1046             $output_preformatted = 1;
1047         } else {
1048             print "<para>\n";
1049         }
1050         output_highlight($args{'sections'}{$section});
1051         $output_preformatted = 0;
1052         if ($section =~ m/EXAMPLE/i) {
1053             print "</programlisting></informalexample>\n";
1054         } else {
1055             print "</para>\n";
1056         }
1057         print "</refsect1>\n";
1058     }
1059 }
1060
1061 # output function in XML DocBook
1062 sub output_function_xml(%) {
1063     my %args = %{$_[0]};
1064     my ($parameter, $section);
1065     my $count;
1066     my $id;
1067
1068     $id = "API-" . $args{'function'};
1069     $id =~ s/[^A-Za-z0-9]/-/g;
1070
1071     print "<refentry id=\"$id\">\n";
1072     print "<refentryinfo>\n";
1073     print " <title>LINUX</title>\n";
1074     print " <productname>Kernel Hackers Manual</productname>\n";
1075     print " <date>$man_date</date>\n";
1076     print "</refentryinfo>\n";
1077     print "<refmeta>\n";
1078     print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
1079     print " <manvolnum>9</manvolnum>\n";
1080     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1081     print "</refmeta>\n";
1082     print "<refnamediv>\n";
1083     print " <refname>" . $args{'function'} . "</refname>\n";
1084     print " <refpurpose>\n";
1085     print "  ";
1086     output_highlight ($args{'purpose'});
1087     print " </refpurpose>\n";
1088     print "</refnamediv>\n";
1089
1090     print "<refsynopsisdiv>\n";
1091     print " <title>Synopsis</title>\n";
1092     print "  <funcsynopsis><funcprototype>\n";
1093     print "   <funcdef>" . $args{'functiontype'} . " ";
1094     print "<function>" . $args{'function'} . " </function></funcdef>\n";
1095
1096     $count = 0;
1097     if ($#{$args{'parameterlist'}} >= 0) {
1098         foreach $parameter (@{$args{'parameterlist'}}) {
1099             $type = $args{'parametertypes'}{$parameter};
1100             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1101                 # pointer-to-function
1102                 print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
1103                 print "     <funcparams>$2</funcparams></paramdef>\n";
1104             } else {
1105                 print "   <paramdef>" . $type;
1106                 print " <parameter>$parameter</parameter></paramdef>\n";
1107             }
1108         }
1109     } else {
1110         print "  <void/>\n";
1111     }
1112     print "  </funcprototype></funcsynopsis>\n";
1113     print "</refsynopsisdiv>\n";
1114
1115     # print parameters
1116     print "<refsect1>\n <title>Arguments</title>\n";
1117     if ($#{$args{'parameterlist'}} >= 0) {
1118         print " <variablelist>\n";
1119         foreach $parameter (@{$args{'parameterlist'}}) {
1120             my $parameter_name = $parameter;
1121             $parameter_name =~ s/\[.*//;
1122
1123             print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
1124             print "   <listitem>\n    <para>\n";
1125             $lineprefix="     ";
1126             output_highlight($args{'parameterdescs'}{$parameter_name});
1127             print "    </para>\n   </listitem>\n  </varlistentry>\n";
1128         }
1129         print " </variablelist>\n";
1130     } else {
1131         print " <para>\n  None\n </para>\n";
1132     }
1133     print "</refsect1>\n";
1134
1135     output_section_xml(@_);
1136     print "</refentry>\n\n";
1137 }
1138
1139 # output struct in XML DocBook
1140 sub output_struct_xml(%) {
1141     my %args = %{$_[0]};
1142     my ($parameter, $section);
1143     my $id;
1144
1145     $id = "API-struct-" . $args{'struct'};
1146     $id =~ s/[^A-Za-z0-9]/-/g;
1147
1148     print "<refentry id=\"$id\">\n";
1149     print "<refentryinfo>\n";
1150     print " <title>LINUX</title>\n";
1151     print " <productname>Kernel Hackers Manual</productname>\n";
1152     print " <date>$man_date</date>\n";
1153     print "</refentryinfo>\n";
1154     print "<refmeta>\n";
1155     print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1156     print " <manvolnum>9</manvolnum>\n";
1157     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1158     print "</refmeta>\n";
1159     print "<refnamediv>\n";
1160     print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1161     print " <refpurpose>\n";
1162     print "  ";
1163     output_highlight ($args{'purpose'});
1164     print " </refpurpose>\n";
1165     print "</refnamediv>\n";
1166
1167     print "<refsynopsisdiv>\n";
1168     print " <title>Synopsis</title>\n";
1169     print "  <programlisting>\n";
1170     print $args{'type'} . " " . $args{'struct'} . " {\n";
1171     foreach $parameter (@{$args{'parameterlist'}}) {
1172         if ($parameter =~ /^#/) {
1173             my $prm = $parameter;
1174             # convert data read & converted thru xml_escape() into &xyz; format:
1175             # This allows us to have #define macros interspersed in a struct.
1176             $prm =~ s/\\\\\\/\&/g;
1177             print "$prm\n";
1178             next;
1179         }
1180
1181         my $parameter_name = $parameter;
1182         $parameter_name =~ s/\[.*//;
1183
1184         defined($args{'parameterdescs'}{$parameter_name}) || next;
1185         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1186         $type = $args{'parametertypes'}{$parameter};
1187         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1188             # pointer-to-function
1189             print "  $1 $parameter) ($2);\n";
1190         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1191             # bitfield
1192             print "  $1 $parameter$2;\n";
1193         } else {
1194             print "  " . $type . " " . $parameter . ";\n";
1195         }
1196     }
1197     print "};";
1198     print "  </programlisting>\n";
1199     print "</refsynopsisdiv>\n";
1200
1201     print " <refsect1>\n";
1202     print "  <title>Members</title>\n";
1203
1204     if ($#{$args{'parameterlist'}} >= 0) {
1205     print "  <variablelist>\n";
1206     foreach $parameter (@{$args{'parameterlist'}}) {
1207       ($parameter =~ /^#/) && next;
1208
1209       my $parameter_name = $parameter;
1210       $parameter_name =~ s/\[.*//;
1211
1212       defined($args{'parameterdescs'}{$parameter_name}) || next;
1213       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1214       print "    <varlistentry>";
1215       print "      <term>$parameter</term>\n";
1216       print "      <listitem><para>\n";
1217       output_highlight($args{'parameterdescs'}{$parameter_name});
1218       print "      </para></listitem>\n";
1219       print "    </varlistentry>\n";
1220     }
1221     print "  </variablelist>\n";
1222     } else {
1223         print " <para>\n  None\n </para>\n";
1224     }
1225     print " </refsect1>\n";
1226
1227     output_section_xml(@_);
1228
1229     print "</refentry>\n\n";
1230 }
1231
1232 # output enum in XML DocBook
1233 sub output_enum_xml(%) {
1234     my %args = %{$_[0]};
1235     my ($parameter, $section);
1236     my $count;
1237     my $id;
1238
1239     $id = "API-enum-" . $args{'enum'};
1240     $id =~ s/[^A-Za-z0-9]/-/g;
1241
1242     print "<refentry id=\"$id\">\n";
1243     print "<refentryinfo>\n";
1244     print " <title>LINUX</title>\n";
1245     print " <productname>Kernel Hackers Manual</productname>\n";
1246     print " <date>$man_date</date>\n";
1247     print "</refentryinfo>\n";
1248     print "<refmeta>\n";
1249     print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1250     print " <manvolnum>9</manvolnum>\n";
1251     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1252     print "</refmeta>\n";
1253     print "<refnamediv>\n";
1254     print " <refname>enum " . $args{'enum'} . "</refname>\n";
1255     print " <refpurpose>\n";
1256     print "  ";
1257     output_highlight ($args{'purpose'});
1258     print " </refpurpose>\n";
1259     print "</refnamediv>\n";
1260
1261     print "<refsynopsisdiv>\n";
1262     print " <title>Synopsis</title>\n";
1263     print "  <programlisting>\n";
1264     print "enum " . $args{'enum'} . " {\n";
1265     $count = 0;
1266     foreach $parameter (@{$args{'parameterlist'}}) {
1267         print "  $parameter";
1268         if ($count != $#{$args{'parameterlist'}}) {
1269             $count++;
1270             print ",";
1271         }
1272         print "\n";
1273     }
1274     print "};";
1275     print "  </programlisting>\n";
1276     print "</refsynopsisdiv>\n";
1277
1278     print "<refsect1>\n";
1279     print " <title>Constants</title>\n";
1280     print "  <variablelist>\n";
1281     foreach $parameter (@{$args{'parameterlist'}}) {
1282       my $parameter_name = $parameter;
1283       $parameter_name =~ s/\[.*//;
1284
1285       print "    <varlistentry>";
1286       print "      <term>$parameter</term>\n";
1287       print "      <listitem><para>\n";
1288       output_highlight($args{'parameterdescs'}{$parameter_name});
1289       print "      </para></listitem>\n";
1290       print "    </varlistentry>\n";
1291     }
1292     print "  </variablelist>\n";
1293     print "</refsect1>\n";
1294
1295     output_section_xml(@_);
1296
1297     print "</refentry>\n\n";
1298 }
1299
1300 # output typedef in XML DocBook
1301 sub output_typedef_xml(%) {
1302     my %args = %{$_[0]};
1303     my ($parameter, $section);
1304     my $id;
1305
1306     $id = "API-typedef-" . $args{'typedef'};
1307     $id =~ s/[^A-Za-z0-9]/-/g;
1308
1309     print "<refentry id=\"$id\">\n";
1310     print "<refentryinfo>\n";
1311     print " <title>LINUX</title>\n";
1312     print " <productname>Kernel Hackers Manual</productname>\n";
1313     print " <date>$man_date</date>\n";
1314     print "</refentryinfo>\n";
1315     print "<refmeta>\n";
1316     print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1317     print " <manvolnum>9</manvolnum>\n";
1318     print "</refmeta>\n";
1319     print "<refnamediv>\n";
1320     print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1321     print " <refpurpose>\n";
1322     print "  ";
1323     output_highlight ($args{'purpose'});
1324     print " </refpurpose>\n";
1325     print "</refnamediv>\n";
1326
1327     print "<refsynopsisdiv>\n";
1328     print " <title>Synopsis</title>\n";
1329     print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1330     print "</refsynopsisdiv>\n";
1331
1332     output_section_xml(@_);
1333
1334     print "</refentry>\n\n";
1335 }
1336
1337 # output in XML DocBook
1338 sub output_blockhead_xml(%) {
1339     my %args = %{$_[0]};
1340     my ($parameter, $section);
1341     my $count;
1342
1343     my $id = $args{'module'};
1344     $id =~ s/[^A-Za-z0-9]/-/g;
1345
1346     # print out each section
1347     $lineprefix="   ";
1348     foreach $section (@{$args{'sectionlist'}}) {
1349         if (!$args{'content-only'}) {
1350                 print "<refsect1>\n <title>$section</title>\n";
1351         }
1352         if ($section =~ m/EXAMPLE/i) {
1353             print "<example><para>\n";
1354             $output_preformatted = 1;
1355         } else {
1356             print "<para>\n";
1357         }
1358         output_highlight($args{'sections'}{$section});
1359         $output_preformatted = 0;
1360         if ($section =~ m/EXAMPLE/i) {
1361             print "</para></example>\n";
1362         } else {
1363             print "</para>";
1364         }
1365         if (!$args{'content-only'}) {
1366                 print "\n</refsect1>\n";
1367         }
1368     }
1369
1370     print "\n\n";
1371 }
1372
1373 # output in XML DocBook
1374 sub output_function_gnome {
1375     my %args = %{$_[0]};
1376     my ($parameter, $section);
1377     my $count;
1378     my $id;
1379
1380     $id = $args{'module'} . "-" . $args{'function'};
1381     $id =~ s/[^A-Za-z0-9]/-/g;
1382
1383     print "<sect2>\n";
1384     print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1385
1386     print "  <funcsynopsis>\n";
1387     print "   <funcdef>" . $args{'functiontype'} . " ";
1388     print "<function>" . $args{'function'} . " ";
1389     print "</function></funcdef>\n";
1390
1391     $count = 0;
1392     if ($#{$args{'parameterlist'}} >= 0) {
1393         foreach $parameter (@{$args{'parameterlist'}}) {
1394             $type = $args{'parametertypes'}{$parameter};
1395             if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1396                 # pointer-to-function
1397                 print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
1398                 print "     <funcparams>$2</funcparams></paramdef>\n";
1399             } else {
1400                 print "   <paramdef>" . $type;
1401                 print " <parameter>$parameter</parameter></paramdef>\n";
1402             }
1403         }
1404     } else {
1405         print "  <void>\n";
1406     }
1407     print "  </funcsynopsis>\n";
1408     if ($#{$args{'parameterlist'}} >= 0) {
1409         print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1410         print "<tgroup cols=\"2\">\n";
1411         print "<colspec colwidth=\"2*\">\n";
1412         print "<colspec colwidth=\"8*\">\n";
1413         print "<tbody>\n";
1414         foreach $parameter (@{$args{'parameterlist'}}) {
1415             my $parameter_name = $parameter;
1416             $parameter_name =~ s/\[.*//;
1417
1418             print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1419             print "   <entry>\n";
1420             $lineprefix="     ";
1421             output_highlight($args{'parameterdescs'}{$parameter_name});
1422             print "    </entry></row>\n";
1423         }
1424         print " </tbody></tgroup></informaltable>\n";
1425     } else {
1426         print " <para>\n  None\n </para>\n";
1427     }
1428
1429     # print out each section
1430     $lineprefix="   ";
1431     foreach $section (@{$args{'sectionlist'}}) {
1432         print "<simplesect>\n <title>$section</title>\n";
1433         if ($section =~ m/EXAMPLE/i) {
1434             print "<example><programlisting>\n";
1435             $output_preformatted = 1;
1436         } else {
1437         }
1438         print "<para>\n";
1439         output_highlight($args{'sections'}{$section});
1440         $output_preformatted = 0;
1441         print "</para>\n";
1442         if ($section =~ m/EXAMPLE/i) {
1443             print "</programlisting></example>\n";
1444         } else {
1445         }
1446         print " </simplesect>\n";
1447     }
1448
1449     print "</sect2>\n\n";
1450 }
1451
1452 ##
1453 # output function in man
1454 sub output_function_man(%) {
1455     my %args = %{$_[0]};
1456     my ($parameter, $section);
1457     my $count;
1458
1459     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1460
1461     print ".SH NAME\n";
1462     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1463
1464     print ".SH SYNOPSIS\n";
1465     if ($args{'functiontype'} ne "") {
1466         print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1467     } else {
1468         print ".B \"" . $args{'function'} . "\n";
1469     }
1470     $count = 0;
1471     my $parenth = "(";
1472     my $post = ",";
1473     foreach my $parameter (@{$args{'parameterlist'}}) {
1474         if ($count == $#{$args{'parameterlist'}}) {
1475             $post = ");";
1476         }
1477         $type = $args{'parametertypes'}{$parameter};
1478         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1479             # pointer-to-function
1480             print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1481         } else {
1482             $type =~ s/([^\*])$/$1 /;
1483             print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1484         }
1485         $count++;
1486         $parenth = "";
1487     }
1488
1489     print ".SH ARGUMENTS\n";
1490     foreach $parameter (@{$args{'parameterlist'}}) {
1491         my $parameter_name = $parameter;
1492         $parameter_name =~ s/\[.*//;
1493
1494         print ".IP \"" . $parameter . "\" 12\n";
1495         output_highlight($args{'parameterdescs'}{$parameter_name});
1496     }
1497     foreach $section (@{$args{'sectionlist'}}) {
1498         print ".SH \"", uc $section, "\"\n";
1499         output_highlight($args{'sections'}{$section});
1500     }
1501 }
1502
1503 ##
1504 # output enum in man
1505 sub output_enum_man(%) {
1506     my %args = %{$_[0]};
1507     my ($parameter, $section);
1508     my $count;
1509
1510     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1511
1512     print ".SH NAME\n";
1513     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1514
1515     print ".SH SYNOPSIS\n";
1516     print "enum " . $args{'enum'} . " {\n";
1517     $count = 0;
1518     foreach my $parameter (@{$args{'parameterlist'}}) {
1519         print ".br\n.BI \"    $parameter\"\n";
1520         if ($count == $#{$args{'parameterlist'}}) {
1521             print "\n};\n";
1522             last;
1523         }
1524         else {
1525             print ", \n.br\n";
1526         }
1527         $count++;
1528     }
1529
1530     print ".SH Constants\n";
1531     foreach $parameter (@{$args{'parameterlist'}}) {
1532         my $parameter_name = $parameter;
1533         $parameter_name =~ s/\[.*//;
1534
1535         print ".IP \"" . $parameter . "\" 12\n";
1536         output_highlight($args{'parameterdescs'}{$parameter_name});
1537     }
1538     foreach $section (@{$args{'sectionlist'}}) {
1539         print ".SH \"$section\"\n";
1540         output_highlight($args{'sections'}{$section});
1541     }
1542 }
1543
1544 ##
1545 # output struct in man
1546 sub output_struct_man(%) {
1547     my %args = %{$_[0]};
1548     my ($parameter, $section);
1549
1550     print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1551
1552     print ".SH NAME\n";
1553     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1554
1555     print ".SH SYNOPSIS\n";
1556     print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1557
1558     foreach my $parameter (@{$args{'parameterlist'}}) {
1559         if ($parameter =~ /^#/) {
1560             print ".BI \"$parameter\"\n.br\n";
1561             next;
1562         }
1563         my $parameter_name = $parameter;
1564         $parameter_name =~ s/\[.*//;
1565
1566         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1567         $type = $args{'parametertypes'}{$parameter};
1568         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1569             # pointer-to-function
1570             print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1571         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1572             # bitfield
1573             print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1574         } else {
1575             $type =~ s/([^\*])$/$1 /;
1576             print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1577         }
1578         print "\n.br\n";
1579     }
1580     print "};\n.br\n";
1581
1582     print ".SH Members\n";
1583     foreach $parameter (@{$args{'parameterlist'}}) {
1584         ($parameter =~ /^#/) && next;
1585
1586         my $parameter_name = $parameter;
1587         $parameter_name =~ s/\[.*//;
1588
1589         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1590         print ".IP \"" . $parameter . "\" 12\n";
1591         output_highlight($args{'parameterdescs'}{$parameter_name});
1592     }
1593     foreach $section (@{$args{'sectionlist'}}) {
1594         print ".SH \"$section\"\n";
1595         output_highlight($args{'sections'}{$section});
1596     }
1597 }
1598
1599 ##
1600 # output typedef in man
1601 sub output_typedef_man(%) {
1602     my %args = %{$_[0]};
1603     my ($parameter, $section);
1604
1605     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1606
1607     print ".SH NAME\n";
1608     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1609
1610     foreach $section (@{$args{'sectionlist'}}) {
1611         print ".SH \"$section\"\n";
1612         output_highlight($args{'sections'}{$section});
1613     }
1614 }
1615
1616 sub output_blockhead_man(%) {
1617     my %args = %{$_[0]};
1618     my ($parameter, $section);
1619     my $count;
1620
1621     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1622
1623     foreach $section (@{$args{'sectionlist'}}) {
1624         print ".SH \"$section\"\n";
1625         output_highlight($args{'sections'}{$section});
1626     }
1627 }
1628
1629 ##
1630 # output in text
1631 sub output_function_text(%) {
1632     my %args = %{$_[0]};
1633     my ($parameter, $section);
1634     my $start;
1635
1636     print "Name:\n\n";
1637     print $args{'function'} . " - " . $args{'purpose'} . "\n";
1638
1639     print "\nSynopsis:\n\n";
1640     if ($args{'functiontype'} ne "") {
1641         $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1642     } else {
1643         $start = $args{'function'} . " (";
1644     }
1645     print $start;
1646
1647     my $count = 0;
1648     foreach my $parameter (@{$args{'parameterlist'}}) {
1649         $type = $args{'parametertypes'}{$parameter};
1650         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1651             # pointer-to-function
1652             print $1 . $parameter . ") (" . $2;
1653         } else {
1654             print $type . " " . $parameter;
1655         }
1656         if ($count != $#{$args{'parameterlist'}}) {
1657             $count++;
1658             print ",\n";
1659             print " " x length($start);
1660         } else {
1661             print ");\n\n";
1662         }
1663     }
1664
1665     print "Arguments:\n\n";
1666     foreach $parameter (@{$args{'parameterlist'}}) {
1667         my $parameter_name = $parameter;
1668         $parameter_name =~ s/\[.*//;
1669
1670         print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1671     }
1672     output_section_text(@_);
1673 }
1674
1675 #output sections in text
1676 sub output_section_text(%) {
1677     my %args = %{$_[0]};
1678     my $section;
1679
1680     print "\n";
1681     foreach $section (@{$args{'sectionlist'}}) {
1682         print "$section:\n\n";
1683         output_highlight($args{'sections'}{$section});
1684     }
1685     print "\n\n";
1686 }
1687
1688 # output enum in text
1689 sub output_enum_text(%) {
1690     my %args = %{$_[0]};
1691     my ($parameter);
1692     my $count;
1693     print "Enum:\n\n";
1694
1695     print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1696     print "enum " . $args{'enum'} . " {\n";
1697     $count = 0;
1698     foreach $parameter (@{$args{'parameterlist'}}) {
1699         print "\t$parameter";
1700         if ($count != $#{$args{'parameterlist'}}) {
1701             $count++;
1702             print ",";
1703         }
1704         print "\n";
1705     }
1706     print "};\n\n";
1707
1708     print "Constants:\n\n";
1709     foreach $parameter (@{$args{'parameterlist'}}) {
1710         print "$parameter\n\t";
1711         print $args{'parameterdescs'}{$parameter} . "\n";
1712     }
1713
1714     output_section_text(@_);
1715 }
1716
1717 # output typedef in text
1718 sub output_typedef_text(%) {
1719     my %args = %{$_[0]};
1720     my ($parameter);
1721     my $count;
1722     print "Typedef:\n\n";
1723
1724     print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1725     output_section_text(@_);
1726 }
1727
1728 # output struct as text
1729 sub output_struct_text(%) {
1730     my %args = %{$_[0]};
1731     my ($parameter);
1732
1733     print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1734     print $args{'type'} . " " . $args{'struct'} . " {\n";
1735     foreach $parameter (@{$args{'parameterlist'}}) {
1736         if ($parameter =~ /^#/) {
1737             print "$parameter\n";
1738             next;
1739         }
1740
1741         my $parameter_name = $parameter;
1742         $parameter_name =~ s/\[.*//;
1743
1744         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1745         $type = $args{'parametertypes'}{$parameter};
1746         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1747             # pointer-to-function
1748             print "\t$1 $parameter) ($2);\n";
1749         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1750             # bitfield
1751             print "\t$1 $parameter$2;\n";
1752         } else {
1753             print "\t" . $type . " " . $parameter . ";\n";
1754         }
1755     }
1756     print "};\n\n";
1757
1758     print "Members:\n\n";
1759     foreach $parameter (@{$args{'parameterlist'}}) {
1760         ($parameter =~ /^#/) && next;
1761
1762         my $parameter_name = $parameter;
1763         $parameter_name =~ s/\[.*//;
1764
1765         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1766         print "$parameter\n\t";
1767         print $args{'parameterdescs'}{$parameter_name} . "\n";
1768     }
1769     print "\n";
1770     output_section_text(@_);
1771 }
1772
1773 sub output_blockhead_text(%) {
1774     my %args = %{$_[0]};
1775     my ($parameter, $section);
1776
1777     foreach $section (@{$args{'sectionlist'}}) {
1778         print " $section:\n";
1779         print "    -> ";
1780         output_highlight($args{'sections'}{$section});
1781     }
1782 }
1783
1784 ##
1785 # output in restructured text
1786 #
1787
1788 #
1789 # This could use some work; it's used to output the DOC: sections, and
1790 # starts by putting out the name of the doc section itself, but that tends
1791 # to duplicate a header already in the template file.
1792 #
1793 sub output_blockhead_rst(%) {
1794     my %args = %{$_[0]};
1795     my ($parameter, $section);
1796
1797     foreach $section (@{$args{'sectionlist'}}) {
1798         if ($output_selection != OUTPUT_INCLUDE) {
1799             print "**$section**\n\n";
1800         }
1801         print_lineno($section_start_lines{$section});
1802         output_highlight_rst($args{'sections'}{$section});
1803         print "\n";
1804     }
1805 }
1806
1807 sub output_highlight_rst {
1808     my $contents = join "\n",@_;
1809     my $line;
1810
1811     # undo the evil effects of xml_escape() earlier
1812     $contents = xml_unescape($contents);
1813
1814     eval $dohighlight;
1815     die $@ if $@;
1816
1817     foreach $line (split "\n", $contents) {
1818         print $lineprefix . $line . "\n";
1819     }
1820 }
1821
1822 sub output_function_rst(%) {
1823     my %args = %{$_[0]};
1824     my ($parameter, $section);
1825     my $oldprefix = $lineprefix;
1826     my $start;
1827
1828     print ".. c:function:: ";
1829     if ($args{'functiontype'} ne "") {
1830         $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1831     } else {
1832         $start = $args{'function'} . " (";
1833     }
1834     print $start;
1835
1836     my $count = 0;
1837     foreach my $parameter (@{$args{'parameterlist'}}) {
1838         if ($count ne 0) {
1839             print ", ";
1840         }
1841         $count++;
1842         $type = $args{'parametertypes'}{$parameter};
1843         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1844             # pointer-to-function
1845             print $1 . $parameter . ") (" . $2;
1846         } else {
1847             print $type . " " . $parameter;
1848         }
1849     }
1850     print ")\n\n";
1851     print_lineno($declaration_start_line);
1852     $lineprefix = "   ";
1853     output_highlight_rst($args{'purpose'});
1854     print "\n";
1855
1856     print "**Parameters**\n\n";
1857     $lineprefix = "  ";
1858     foreach $parameter (@{$args{'parameterlist'}}) {
1859         my $parameter_name = $parameter;
1860         #$parameter_name =~ s/\[.*//;
1861         $type = $args{'parametertypes'}{$parameter};
1862
1863         if ($type ne "") {
1864             print "``$type $parameter``\n";
1865         } else {
1866             print "``$parameter``\n";
1867         }
1868
1869         print_lineno($parameterdesc_start_lines{$parameter_name});
1870
1871         if (defined($args{'parameterdescs'}{$parameter_name}) &&
1872             $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1873             output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1874         } else {
1875             print "  *undescribed*\n";
1876         }
1877         print "\n";
1878     }
1879
1880     $lineprefix = $oldprefix;
1881     output_section_rst(@_);
1882 }
1883
1884 sub output_section_rst(%) {
1885     my %args = %{$_[0]};
1886     my $section;
1887     my $oldprefix = $lineprefix;
1888     $lineprefix = "";
1889
1890     foreach $section (@{$args{'sectionlist'}}) {
1891         print "**$section**\n\n";
1892         print_lineno($section_start_lines{$section});
1893         output_highlight_rst($args{'sections'}{$section});
1894         print "\n";
1895     }
1896     print "\n";
1897     $lineprefix = $oldprefix;
1898 }
1899
1900 sub output_enum_rst(%) {
1901     my %args = %{$_[0]};
1902     my ($parameter);
1903     my $oldprefix = $lineprefix;
1904     my $count;
1905     my $name = "enum " . $args{'enum'};
1906
1907     print "\n\n.. c:type:: " . $name . "\n\n";
1908     print_lineno($declaration_start_line);
1909     $lineprefix = "   ";
1910     output_highlight_rst($args{'purpose'});
1911     print "\n";
1912
1913     print "**Constants**\n\n";
1914     $lineprefix = "  ";
1915     foreach $parameter (@{$args{'parameterlist'}}) {
1916         print "``$parameter``\n";
1917         if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1918             output_highlight_rst($args{'parameterdescs'}{$parameter});
1919         } else {
1920             print "  *undescribed*\n";
1921         }
1922         print "\n";
1923     }
1924
1925     $lineprefix = $oldprefix;
1926     output_section_rst(@_);
1927 }
1928
1929 sub output_typedef_rst(%) {
1930     my %args = %{$_[0]};
1931     my ($parameter);
1932     my $oldprefix = $lineprefix;
1933     my $name = "typedef " . $args{'typedef'};
1934
1935     print "\n\n.. c:type:: " . $name . "\n\n";
1936     print_lineno($declaration_start_line);
1937     $lineprefix = "   ";
1938     output_highlight_rst($args{'purpose'});
1939     print "\n";
1940
1941     $lineprefix = $oldprefix;
1942     output_section_rst(@_);
1943 }
1944
1945 sub output_struct_rst(%) {
1946     my %args = %{$_[0]};
1947     my ($parameter);
1948     my $oldprefix = $lineprefix;
1949     my $name = $args{'type'} . " " . $args{'struct'};
1950
1951     print "\n\n.. c:type:: " . $name . "\n\n";
1952     print_lineno($declaration_start_line);
1953     $lineprefix = "   ";
1954     output_highlight_rst($args{'purpose'});
1955     print "\n";
1956
1957     print "**Definition**\n\n";
1958     print "::\n\n";
1959     print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
1960     foreach $parameter (@{$args{'parameterlist'}}) {
1961         if ($parameter =~ /^#/) {
1962             print "  " . "$parameter\n";
1963             next;
1964         }
1965
1966         my $parameter_name = $parameter;
1967         $parameter_name =~ s/\[.*//;
1968
1969         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1970         $type = $args{'parametertypes'}{$parameter};
1971         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1972             # pointer-to-function
1973             print "    $1 $parameter) ($2);\n";
1974         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1975             # bitfield
1976             print "    $1 $parameter$2;\n";
1977         } else {
1978             print "    " . $type . " " . $parameter . ";\n";
1979         }
1980     }
1981     print "  };\n\n";
1982
1983     print "**Members**\n\n";
1984     $lineprefix = "  ";
1985     foreach $parameter (@{$args{'parameterlist'}}) {
1986         ($parameter =~ /^#/) && next;
1987
1988         my $parameter_name = $parameter;
1989         $parameter_name =~ s/\[.*//;
1990
1991         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1992         $type = $args{'parametertypes'}{$parameter};
1993         print_lineno($parameterdesc_start_lines{$parameter_name});
1994         print "``$type $parameter``\n";
1995         output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1996         print "\n";
1997     }
1998     print "\n";
1999
2000     $lineprefix = $oldprefix;
2001     output_section_rst(@_);
2002 }
2003
2004
2005 ## list mode output functions
2006
2007 sub output_function_list(%) {
2008     my %args = %{$_[0]};
2009
2010     print $args{'function'} . "\n";
2011 }
2012
2013 # output enum in list
2014 sub output_enum_list(%) {
2015     my %args = %{$_[0]};
2016     print $args{'enum'} . "\n";
2017 }
2018
2019 # output typedef in list
2020 sub output_typedef_list(%) {
2021     my %args = %{$_[0]};
2022     print $args{'typedef'} . "\n";
2023 }
2024
2025 # output struct as list
2026 sub output_struct_list(%) {
2027     my %args = %{$_[0]};
2028
2029     print $args{'struct'} . "\n";
2030 }
2031
2032 sub output_blockhead_list(%) {
2033     my %args = %{$_[0]};
2034     my ($parameter, $section);
2035
2036     foreach $section (@{$args{'sectionlist'}}) {
2037         print "DOC: $section\n";
2038     }
2039 }
2040
2041 ##
2042 # generic output function for all types (function, struct/union, typedef, enum);
2043 # calls the generated, variable output_ function name based on
2044 # functype and output_mode
2045 sub output_declaration {
2046     no strict 'refs';
2047     my $name = shift;
2048     my $functype = shift;
2049     my $func = "output_${functype}_$output_mode";
2050     if (($output_selection == OUTPUT_ALL) ||
2051         (($output_selection == OUTPUT_INCLUDE ||
2052           $output_selection == OUTPUT_EXPORTED) &&
2053          defined($function_table{$name})) ||
2054         (($output_selection == OUTPUT_EXCLUDE ||
2055           $output_selection == OUTPUT_INTERNAL) &&
2056          !($functype eq "function" && defined($function_table{$name}))))
2057     {
2058         &$func(@_);
2059         $section_counter++;
2060     }
2061 }
2062
2063 ##
2064 # generic output function - calls the right one based on current output mode.
2065 sub output_blockhead {
2066     no strict 'refs';
2067     my $func = "output_blockhead_" . $output_mode;
2068     &$func(@_);
2069     $section_counter++;
2070 }
2071
2072 ##
2073 # takes a declaration (struct, union, enum, typedef) and
2074 # invokes the right handler. NOT called for functions.
2075 sub dump_declaration($$) {
2076     no strict 'refs';
2077     my ($prototype, $file) = @_;
2078     my $func = "dump_" . $decl_type;
2079     &$func(@_);
2080 }
2081
2082 sub dump_union($$) {
2083     dump_struct(@_);
2084 }
2085
2086 sub dump_struct($$) {
2087     my $x = shift;
2088     my $file = shift;
2089     my $nested;
2090
2091     if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2092         #my $decl_type = $1;
2093         $declaration_name = $2;
2094         my $members = $3;
2095
2096         # ignore embedded structs or unions
2097         $members =~ s/({.*})//g;
2098         $nested = $1;
2099
2100         # ignore members marked private:
2101         $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2102         $members =~ s/\/\*\s*private:.*//gosi;
2103         # strip comments:
2104         $members =~ s/\/\*.*?\*\///gos;
2105         $nested =~ s/\/\*.*?\*\///gos;
2106         # strip kmemcheck_bitfield_{begin,end}.*;
2107         $members =~ s/kmemcheck_bitfield_.*?;//gos;
2108         # strip attributes
2109         $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2110         $members =~ s/__aligned\s*\([^;]*\)//gos;
2111         $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2112         # replace DECLARE_BITMAP
2113         $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2114
2115         create_parameterlist($members, ';', $file);
2116         check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
2117
2118         output_declaration($declaration_name,
2119                            'struct',
2120                            {'struct' => $declaration_name,
2121                             'module' => $modulename,
2122                             'parameterlist' => \@parameterlist,
2123                             'parameterdescs' => \%parameterdescs,
2124                             'parametertypes' => \%parametertypes,
2125                             'sectionlist' => \@sectionlist,
2126                             'sections' => \%sections,
2127                             'purpose' => $declaration_purpose,
2128                             'type' => $decl_type
2129                            });
2130     }
2131     else {
2132         print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2133         ++$errors;
2134     }
2135 }
2136
2137 sub dump_enum($$) {
2138     my $x = shift;
2139     my $file = shift;
2140
2141     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
2142     # strip #define macros inside enums
2143     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2144
2145     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2146         $declaration_name = $1;
2147         my $members = $2;
2148
2149         foreach my $arg (split ',', $members) {
2150             $arg =~ s/^\s*(\w+).*/$1/;
2151             push @parameterlist, $arg;
2152             if (!$parameterdescs{$arg}) {
2153                 $parameterdescs{$arg} = $undescribed;
2154                 print STDERR "${file}:$.: warning: Enum value '$arg' ".
2155                     "not described in enum '$declaration_name'\n";
2156             }
2157
2158         }
2159
2160         output_declaration($declaration_name,
2161                            'enum',
2162                            {'enum' => $declaration_name,
2163                             'module' => $modulename,
2164                             'parameterlist' => \@parameterlist,
2165                             'parameterdescs' => \%parameterdescs,
2166                             'sectionlist' => \@sectionlist,
2167                             'sections' => \%sections,
2168                             'purpose' => $declaration_purpose
2169                            });
2170     }
2171     else {
2172         print STDERR "${file}:$.: error: Cannot parse enum!\n";
2173         ++$errors;
2174     }
2175 }
2176
2177 sub dump_typedef($$) {
2178     my $x = shift;
2179     my $file = shift;
2180
2181     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
2182
2183     # Parse function prototypes
2184     if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2185         # Function typedefs
2186         $return_type = $1;
2187         $declaration_name = $2;
2188         my $args = $3;
2189
2190         create_parameterlist($args, ',', $file);
2191
2192         output_declaration($declaration_name,
2193                            'function',
2194                            {'function' => $declaration_name,
2195                             'module' => $modulename,
2196                             'functiontype' => $return_type,
2197                             'parameterlist' => \@parameterlist,
2198                             'parameterdescs' => \%parameterdescs,
2199                             'parametertypes' => \%parametertypes,
2200                             'sectionlist' => \@sectionlist,
2201                             'sections' => \%sections,
2202                             'purpose' => $declaration_purpose
2203                            });
2204         return;
2205     }
2206
2207     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2208         $x =~ s/\(*.\)\s*;$/;/;
2209         $x =~ s/\[*.\]\s*;$/;/;
2210     }
2211
2212     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2213         $declaration_name = $1;
2214
2215         output_declaration($declaration_name,
2216                            'typedef',
2217                            {'typedef' => $declaration_name,
2218                             'module' => $modulename,
2219                             'sectionlist' => \@sectionlist,
2220                             'sections' => \%sections,
2221                             'purpose' => $declaration_purpose
2222                            });
2223     }
2224     else {
2225         print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2226         ++$errors;
2227     }
2228 }
2229
2230 sub save_struct_actual($) {
2231     my $actual = shift;
2232
2233     # strip all spaces from the actual param so that it looks like one string item
2234     $actual =~ s/\s*//g;
2235     $struct_actual = $struct_actual . $actual . " ";
2236 }
2237
2238 sub create_parameterlist($$$) {
2239     my $args = shift;
2240     my $splitter = shift;
2241     my $file = shift;
2242     my $type;
2243     my $param;
2244
2245     # temporarily replace commas inside function pointer definition
2246     while ($args =~ /(\([^\),]+),/) {
2247         $args =~ s/(\([^\),]+),/$1#/g;
2248     }
2249
2250     foreach my $arg (split($splitter, $args)) {
2251         # strip comments
2252         $arg =~ s/\/\*.*\*\///;
2253         # strip leading/trailing spaces
2254         $arg =~ s/^\s*//;
2255         $arg =~ s/\s*$//;
2256         $arg =~ s/\s+/ /;
2257
2258         if ($arg =~ /^#/) {
2259             # Treat preprocessor directive as a typeless variable just to fill
2260             # corresponding data structures "correctly". Catch it later in
2261             # output_* subs.
2262             push_parameter($arg, "", $file);
2263         } elsif ($arg =~ m/\(.+\)\s*\(/) {
2264             # pointer-to-function
2265             $arg =~ tr/#/,/;
2266             $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2267             $param = $1;
2268             $type = $arg;
2269             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2270             save_struct_actual($param);
2271             push_parameter($param, $type, $file);
2272         } elsif ($arg) {
2273             $arg =~ s/\s*:\s*/:/g;
2274             $arg =~ s/\s*\[/\[/g;
2275
2276             my @args = split('\s*,\s*', $arg);
2277             if ($args[0] =~ m/\*/) {
2278                 $args[0] =~ s/(\*+)\s*/ $1/;
2279             }
2280
2281             my @first_arg;
2282             if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2283                     shift @args;
2284                     push(@first_arg, split('\s+', $1));
2285                     push(@first_arg, $2);
2286             } else {
2287                     @first_arg = split('\s+', shift @args);
2288             }
2289
2290             unshift(@args, pop @first_arg);
2291             $type = join " ", @first_arg;
2292
2293             foreach $param (@args) {
2294                 if ($param =~ m/^(\*+)\s*(.*)/) {
2295                     save_struct_actual($2);
2296                     push_parameter($2, "$type $1", $file);
2297                 }
2298                 elsif ($param =~ m/(.*?):(\d+)/) {
2299                     if ($type ne "") { # skip unnamed bit-fields
2300                         save_struct_actual($1);
2301                         push_parameter($1, "$type:$2", $file)
2302                     }
2303                 }
2304                 else {
2305                     save_struct_actual($param);
2306                     push_parameter($param, $type, $file);
2307                 }
2308             }
2309         }
2310     }
2311 }
2312
2313 sub push_parameter($$$) {
2314         my $param = shift;
2315         my $type = shift;
2316         my $file = shift;
2317
2318         if (($anon_struct_union == 1) && ($type eq "") &&
2319             ($param eq "}")) {
2320                 return;         # ignore the ending }; from anon. struct/union
2321         }
2322
2323         $anon_struct_union = 0;
2324         my $param_name = $param;
2325         $param_name =~ s/\[.*//;
2326
2327         if ($type eq "" && $param =~ /\.\.\.$/)
2328         {
2329             if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2330                 $parameterdescs{$param} = "variable arguments";
2331             }
2332         }
2333         elsif ($type eq "" && ($param eq "" or $param eq "void"))
2334         {
2335             $param="void";
2336             $parameterdescs{void} = "no arguments";
2337         }
2338         elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2339         # handle unnamed (anonymous) union or struct:
2340         {
2341                 $type = $param;
2342                 $param = "{unnamed_" . $param . "}";
2343                 $parameterdescs{$param} = "anonymous\n";
2344                 $anon_struct_union = 1;
2345         }
2346
2347         # warn if parameter has no description
2348         # (but ignore ones starting with # as these are not parameters
2349         # but inline preprocessor statements);
2350         # also ignore unnamed structs/unions;
2351         if (!$anon_struct_union) {
2352         if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2353
2354             $parameterdescs{$param_name} = $undescribed;
2355
2356             if (($type eq 'function') || ($type eq 'enum')) {
2357                 print STDERR "${file}:$.: warning: Function parameter ".
2358                     "or member '$param' not " .
2359                     "described in '$declaration_name'\n";
2360             }
2361             print STDERR "${file}:$.: warning:" .
2362                          " No description found for parameter '$param'\n";
2363             ++$warnings;
2364         }
2365         }
2366
2367         $param = xml_escape($param);
2368
2369         # strip spaces from $param so that it is one continuous string
2370         # on @parameterlist;
2371         # this fixes a problem where check_sections() cannot find
2372         # a parameter like "addr[6 + 2]" because it actually appears
2373         # as "addr[6", "+", "2]" on the parameter list;
2374         # but it's better to maintain the param string unchanged for output,
2375         # so just weaken the string compare in check_sections() to ignore
2376         # "[blah" in a parameter string;
2377         ###$param =~ s/\s*//g;
2378         push @parameterlist, $param;
2379         $parametertypes{$param} = $type;
2380 }
2381
2382 sub check_sections($$$$$$) {
2383         my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2384         my @sects = split ' ', $sectcheck;
2385         my @prms = split ' ', $prmscheck;
2386         my $err;
2387         my ($px, $sx);
2388         my $prm_clean;          # strip trailing "[array size]" and/or beginning "*"
2389
2390         foreach $sx (0 .. $#sects) {
2391                 $err = 1;
2392                 foreach $px (0 .. $#prms) {
2393                         $prm_clean = $prms[$px];
2394                         $prm_clean =~ s/\[.*\]//;
2395                         $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2396                         # ignore array size in a parameter string;
2397                         # however, the original param string may contain
2398                         # spaces, e.g.:  addr[6 + 2]
2399                         # and this appears in @prms as "addr[6" since the
2400                         # parameter list is split at spaces;
2401                         # hence just ignore "[..." for the sections check;
2402                         $prm_clean =~ s/\[.*//;
2403
2404                         ##$prm_clean =~ s/^\**//;
2405                         if ($prm_clean eq $sects[$sx]) {
2406                                 $err = 0;
2407                                 last;
2408                         }
2409                 }
2410                 if ($err) {
2411                         if ($decl_type eq "function") {
2412                                 print STDERR "${file}:$.: warning: " .
2413                                         "Excess function parameter " .
2414                                         "'$sects[$sx]' " .
2415                                         "description in '$decl_name'\n";
2416                                 ++$warnings;
2417                         } else {
2418                                 if ($nested !~ m/\Q$sects[$sx]\E/) {
2419                                     print STDERR "${file}:$.: warning: " .
2420                                         "Excess struct/union/enum/typedef member " .
2421                                         "'$sects[$sx]' " .
2422                                         "description in '$decl_name'\n";
2423                                     ++$warnings;
2424                                 }
2425                         }
2426                 }
2427         }
2428 }
2429
2430 ##
2431 # Checks the section describing the return value of a function.
2432 sub check_return_section {
2433         my $file = shift;
2434         my $declaration_name = shift;
2435         my $return_type = shift;
2436
2437         # Ignore an empty return type (It's a macro)
2438         # Ignore functions with a "void" return type. (But don't ignore "void *")
2439         if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2440                 return;
2441         }
2442
2443         if (!defined($sections{$section_return}) ||
2444             $sections{$section_return} eq "") {
2445                 print STDERR "${file}:$.: warning: " .
2446                         "No description found for return value of " .
2447                         "'$declaration_name'\n";
2448                 ++$warnings;
2449         }
2450 }
2451
2452 ##
2453 # takes a function prototype and the name of the current file being
2454 # processed and spits out all the details stored in the global
2455 # arrays/hashes.
2456 sub dump_function($$) {
2457     my $prototype = shift;
2458     my $file = shift;
2459     my $noret = 0;
2460
2461     $prototype =~ s/^static +//;
2462     $prototype =~ s/^extern +//;
2463     $prototype =~ s/^asmlinkage +//;
2464     $prototype =~ s/^inline +//;
2465     $prototype =~ s/^__inline__ +//;
2466     $prototype =~ s/^__inline +//;
2467     $prototype =~ s/^__always_inline +//;
2468     $prototype =~ s/^noinline +//;
2469     $prototype =~ s/__init +//;
2470     $prototype =~ s/__init_or_module +//;
2471     $prototype =~ s/__meminit +//;
2472     $prototype =~ s/__must_check +//;
2473     $prototype =~ s/__weak +//;
2474     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2475     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2476
2477     # Yes, this truly is vile.  We are looking for:
2478     # 1. Return type (may be nothing if we're looking at a macro)
2479     # 2. Function name
2480     # 3. Function parameters.
2481     #
2482     # All the while we have to watch out for function pointer parameters
2483     # (which IIRC is what the two sections are for), C types (these
2484     # regexps don't even start to express all the possibilities), and
2485     # so on.
2486     #
2487     # If you mess with these regexps, it's a good idea to check that
2488     # the following functions' documentation still comes out right:
2489     # - parport_register_device (function pointer parameters)
2490     # - atomic_set (macro)
2491     # - pci_match_device, __copy_to_user (long return type)
2492
2493     if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2494         # This is an object-like macro, it has no return type and no parameter
2495         # list.
2496         # Function-like macros are not allowed to have spaces between
2497         # declaration_name and opening parenthesis (notice the \s+).
2498         $return_type = $1;
2499         $declaration_name = $2;
2500         $noret = 1;
2501     } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2502         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2503         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2504         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2505         $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2506         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2507         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2508         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2509         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2510         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2511         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2512         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2513         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2514         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2515         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2516         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2517         $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
2518         $return_type = $1;
2519         $declaration_name = $2;
2520         my $args = $3;
2521
2522         create_parameterlist($args, ',', $file);
2523     } else {
2524         print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2525         return;
2526     }
2527
2528         my $prms = join " ", @parameterlist;
2529         check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2530
2531         # This check emits a lot of warnings at the moment, because many
2532         # functions don't have a 'Return' doc section. So until the number
2533         # of warnings goes sufficiently down, the check is only performed in
2534         # verbose mode.
2535         # TODO: always perform the check.
2536         if ($verbose && !$noret) {
2537                 check_return_section($file, $declaration_name, $return_type);
2538         }
2539
2540     output_declaration($declaration_name,
2541                        'function',
2542                        {'function' => $declaration_name,
2543                         'module' => $modulename,
2544                         'functiontype' => $return_type,
2545                         'parameterlist' => \@parameterlist,
2546                         'parameterdescs' => \%parameterdescs,
2547                         'parametertypes' => \%parametertypes,
2548                         'sectionlist' => \@sectionlist,
2549                         'sections' => \%sections,
2550                         'purpose' => $declaration_purpose
2551                        });
2552 }
2553
2554 sub reset_state {
2555     $function = "";
2556     %parameterdescs = ();
2557     %parametertypes = ();
2558     @parameterlist = ();
2559     %sections = ();
2560     @sectionlist = ();
2561     $sectcheck = "";
2562     $struct_actual = "";
2563     $prototype = "";
2564
2565     $state = STATE_NORMAL;
2566     $inline_doc_state = STATE_INLINE_NA;
2567 }
2568
2569 sub tracepoint_munge($) {
2570         my $file = shift;
2571         my $tracepointname = 0;
2572         my $tracepointargs = 0;
2573
2574         if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2575                 $tracepointname = $1;
2576         }
2577         if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2578                 $tracepointname = $1;
2579         }
2580         if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2581                 $tracepointname = $2;
2582         }
2583         $tracepointname =~ s/^\s+//; #strip leading whitespace
2584         if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2585                 $tracepointargs = $1;
2586         }
2587         if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2588                 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2589                              "$prototype\n";
2590         } else {
2591                 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2592         }
2593 }
2594
2595 sub syscall_munge() {
2596         my $void = 0;
2597
2598         $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2599 ##      if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2600         if ($prototype =~ m/SYSCALL_DEFINE0/) {
2601                 $void = 1;
2602 ##              $prototype = "long sys_$1(void)";
2603         }
2604
2605         $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2606         if ($prototype =~ m/long (sys_.*?),/) {
2607                 $prototype =~ s/,/\(/;
2608         } elsif ($void) {
2609                 $prototype =~ s/\)/\(void\)/;
2610         }
2611
2612         # now delete all of the odd-number commas in $prototype
2613         # so that arg types & arg names don't have a comma between them
2614         my $count = 0;
2615         my $len = length($prototype);
2616         if ($void) {
2617                 $len = 0;       # skip the for-loop
2618         }
2619         for (my $ix = 0; $ix < $len; $ix++) {
2620                 if (substr($prototype, $ix, 1) eq ',') {
2621                         $count++;
2622                         if ($count % 2 == 1) {
2623                                 substr($prototype, $ix, 1) = ' ';
2624                         }
2625                 }
2626         }
2627 }
2628
2629 sub process_proto_function($$) {
2630     my $x = shift;
2631     my $file = shift;
2632
2633     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2634
2635     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2636         # do nothing
2637     }
2638     elsif ($x =~ /([^\{]*)/) {
2639         $prototype .= $1;
2640     }
2641
2642     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2643         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2644         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2645         $prototype =~ s@^\s+@@gos; # strip leading spaces
2646         if ($prototype =~ /SYSCALL_DEFINE/) {
2647                 syscall_munge();
2648         }
2649         if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2650             $prototype =~ /DEFINE_SINGLE_EVENT/)
2651         {
2652                 tracepoint_munge($file);
2653         }
2654         dump_function($prototype, $file);
2655         reset_state();
2656     }
2657 }
2658
2659 sub process_proto_type($$) {
2660     my $x = shift;
2661     my $file = shift;
2662
2663     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2664     $x =~ s@^\s+@@gos; # strip leading spaces
2665     $x =~ s@\s+$@@gos; # strip trailing spaces
2666     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2667
2668     if ($x =~ /^#/) {
2669         # To distinguish preprocessor directive from regular declaration later.
2670         $x .= ";";
2671     }
2672
2673     while (1) {
2674         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2675             $prototype .= $1 . $2;
2676             ($2 eq '{') && $brcount++;
2677             ($2 eq '}') && $brcount--;
2678             if (($2 eq ';') && ($brcount == 0)) {
2679                 dump_declaration($prototype, $file);
2680                 reset_state();
2681                 last;
2682             }
2683             $x = $3;
2684         } else {
2685             $prototype .= $x;
2686             last;
2687         }
2688     }
2689 }
2690
2691 # xml_escape: replace <, >, and & in the text stream;
2692 #
2693 # however, formatting controls that are generated internally/locally in the
2694 # kernel-doc script are not escaped here; instead, they begin life like
2695 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2696 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2697 # just before actual output; (this is done by local_unescape())
2698 sub xml_escape($) {
2699         my $text = shift;
2700         if (($output_mode eq "text") || ($output_mode eq "man")) {
2701                 return $text;
2702         }
2703         $text =~ s/\&/\\\\\\amp;/g;
2704         $text =~ s/\</\\\\\\lt;/g;
2705         $text =~ s/\>/\\\\\\gt;/g;
2706         return $text;
2707 }
2708
2709 # xml_unescape: reverse the effects of xml_escape
2710 sub xml_unescape($) {
2711         my $text = shift;
2712         if (($output_mode eq "text") || ($output_mode eq "man")) {
2713                 return $text;
2714         }
2715         $text =~ s/\\\\\\amp;/\&/g;
2716         $text =~ s/\\\\\\lt;/</g;
2717         $text =~ s/\\\\\\gt;/>/g;
2718         return $text;
2719 }
2720
2721 # convert local escape strings to html
2722 # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
2723 sub local_unescape($) {
2724         my $text = shift;
2725         if (($output_mode eq "text") || ($output_mode eq "man")) {
2726                 return $text;
2727         }
2728         $text =~ s/\\\\\\\\lt:/</g;
2729         $text =~ s/\\\\\\\\gt:/>/g;
2730         return $text;
2731 }
2732
2733 sub process_file($) {
2734     my $file;
2735     my $identifier;
2736     my $func;
2737     my $descr;
2738     my $in_purpose = 0;
2739     my $initial_section_counter = $section_counter;
2740     my ($orig_file) = @_;
2741     my $leading_space;
2742
2743     if (defined($ENV{'SRCTREE'})) {
2744         $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2745     }
2746     else {
2747         $file = $orig_file;
2748     }
2749     if (defined($source_map{$file})) {
2750         $file = $source_map{$file};
2751     }
2752
2753     if (!open(IN,"<$file")) {
2754         print STDERR "Error: Cannot open file $file\n";
2755         ++$errors;
2756         return;
2757     }
2758
2759     # two passes for -export and -internal
2760     if ($output_selection == OUTPUT_EXPORTED ||
2761         $output_selection == OUTPUT_INTERNAL) {
2762         while (<IN>) {
2763             if (/$export_symbol/o) {
2764                 $function_table{$2} = 1;
2765             }
2766         }
2767         seek(IN, 0, 0);
2768     }
2769
2770     $. = 1;
2771
2772     $section_counter = 0;
2773     while (<IN>) {
2774         while (s/\\\s*$//) {
2775             $_ .= <IN>;
2776         }
2777         if ($state == STATE_NORMAL) {
2778             if (/$doc_start/o) {
2779                 $state = STATE_NAME;    # next line is always the function name
2780                 $in_doc_sect = 0;
2781                 $declaration_start_line = $. + 1;
2782             }
2783         } elsif ($state == STATE_NAME) {# this line is the function name (always)
2784             if (/$doc_block/o) {
2785                 $state = STATE_DOCBLOCK;
2786                 $contents = "";
2787                 $new_start_line = $. + 1;
2788
2789                 if ( $1 eq "" ) {
2790                         $section = $section_intro;
2791                 } else {
2792                         $section = $1;
2793                 }
2794             }
2795             elsif (/$doc_decl/o) {
2796                 $identifier = $1;
2797                 if (/\s*([\w\s]+?)\s*-/) {
2798                     $identifier = $1;
2799                 }
2800
2801                 $state = STATE_FIELD;
2802                 # if there's no @param blocks need to set up default section
2803                 # here
2804                 $contents = "";
2805                 $section = $section_default;
2806                 $new_start_line = $. + 1;
2807                 if (/-(.*)/) {
2808                     # strip leading/trailing/multiple spaces
2809                     $descr= $1;
2810                     $descr =~ s/^\s*//;
2811                     $descr =~ s/\s*$//;
2812                     $descr =~ s/\s+/ /g;
2813                     $declaration_purpose = xml_escape($descr);
2814                     $in_purpose = 1;
2815                 } else {
2816                     $declaration_purpose = "";
2817                 }
2818
2819                 if (($declaration_purpose eq "") && $verbose) {
2820                         print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2821                         print STDERR $_;
2822                         ++$warnings;
2823                 }
2824
2825                 if ($identifier =~ m/^struct/) {
2826                     $decl_type = 'struct';
2827                 } elsif ($identifier =~ m/^union/) {
2828                     $decl_type = 'union';
2829                 } elsif ($identifier =~ m/^enum/) {
2830                     $decl_type = 'enum';
2831                 } elsif ($identifier =~ m/^typedef/) {
2832                     $decl_type = 'typedef';
2833                 } else {
2834                     $decl_type = 'function';
2835                 }
2836
2837                 if ($verbose) {
2838                     print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2839                 }
2840             } else {
2841                 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2842                 " - I thought it was a doc line\n";
2843                 ++$warnings;
2844                 $state = STATE_NORMAL;
2845             }
2846         } elsif ($state == STATE_FIELD) {       # look for head: lines, and include content
2847             if (/$doc_sect/i) { # case insensitive for supported section names
2848                 $newsection = $1;
2849                 $newcontents = $2;
2850
2851                 # map the supported section names to the canonical names
2852                 if ($newsection =~ m/^description$/i) {
2853                     $newsection = $section_default;
2854                 } elsif ($newsection =~ m/^context$/i) {
2855                     $newsection = $section_context;
2856                 } elsif ($newsection =~ m/^returns?$/i) {
2857                     $newsection = $section_return;
2858                 } elsif ($newsection =~ m/^\@return$/) {
2859                     # special: @return is a section, not a param description
2860                     $newsection = $section_return;
2861                 }
2862
2863                 if (($contents ne "") && ($contents ne "\n")) {
2864                     if (!$in_doc_sect && $verbose) {
2865                         print STDERR "${file}:$.: warning: contents before sections\n";
2866                         ++$warnings;
2867                     }
2868                     dump_section($file, $section, xml_escape($contents));
2869                     $section = $section_default;
2870                 }
2871
2872                 $in_doc_sect = 1;
2873                 $in_purpose = 0;
2874                 $contents = $newcontents;
2875                 $new_start_line = $.;
2876                 while ((substr($contents, 0, 1) eq " ") ||
2877                        substr($contents, 0, 1) eq "\t") {
2878                     $contents = substr($contents, 1);
2879                 }
2880                 if ($contents ne "") {
2881                     $contents .= "\n";
2882                 }
2883                 $section = $newsection;
2884                 $leading_space = undef;
2885             } elsif (/$doc_end/) {
2886                 if (($contents ne "") && ($contents ne "\n")) {
2887                     dump_section($file, $section, xml_escape($contents));
2888                     $section = $section_default;
2889                     $contents = "";
2890                 }
2891                 # look for doc_com + <text> + doc_end:
2892                 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2893                     print STDERR "${file}:$.: warning: suspicious ending line: $_";
2894                     ++$warnings;
2895                 }
2896
2897                 $prototype = "";
2898                 $state = STATE_PROTO;
2899                 $brcount = 0;
2900 #               print STDERR "end of doc comment, looking for prototype\n";
2901             } elsif (/$doc_content/) {
2902                 # miguel-style comment kludge, look for blank lines after
2903                 # @parameter line to signify start of description
2904                 if ($1 eq "") {
2905                     if ($section =~ m/^@/ || $section eq $section_context) {
2906                         dump_section($file, $section, xml_escape($contents));
2907                         $section = $section_default;
2908                         $contents = "";
2909                         $new_start_line = $.;
2910                     } else {
2911                         $contents .= "\n";
2912                     }
2913                     $in_purpose = 0;
2914                 } elsif ($in_purpose == 1) {
2915                     # Continued declaration purpose
2916                     chomp($declaration_purpose);
2917                     $declaration_purpose .= " " . xml_escape($1);
2918                     $declaration_purpose =~ s/\s+/ /g;
2919                 } else {
2920                     my $cont = $1;
2921                     if ($section =~ m/^@/ || $section eq $section_context) {
2922                         if (!defined $leading_space) {
2923                             if ($cont =~ m/^(\s+)/) {
2924                                 $leading_space = $1;
2925                             } else {
2926                                 $leading_space = "";
2927                             }
2928                         }
2929
2930                         $cont =~ s/^$leading_space//;
2931                     }
2932                     $contents .= $cont . "\n";
2933                 }
2934             } else {
2935                 # i dont know - bad line?  ignore.
2936                 print STDERR "${file}:$.: warning: bad line: $_";
2937                 ++$warnings;
2938             }
2939         } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2940             # First line (state 1) needs to be a @parameter
2941             if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2942                 $section = $1;
2943                 $contents = $2;
2944                 $new_start_line = $.;
2945                 if ($contents ne "") {
2946                     while ((substr($contents, 0, 1) eq " ") ||
2947                            substr($contents, 0, 1) eq "\t") {
2948                         $contents = substr($contents, 1);
2949                     }
2950                     $contents .= "\n";
2951                 }
2952                 $inline_doc_state = STATE_INLINE_TEXT;
2953             # Documentation block end */
2954             } elsif (/$doc_inline_end/) {
2955                 if (($contents ne "") && ($contents ne "\n")) {
2956                     dump_section($file, $section, xml_escape($contents));
2957                     $section = $section_default;
2958                     $contents = "";
2959                 }
2960                 $state = STATE_PROTO;
2961                 $inline_doc_state = STATE_INLINE_NA;
2962             # Regular text
2963             } elsif (/$doc_content/) {
2964                 if ($inline_doc_state == STATE_INLINE_TEXT) {
2965                     $contents .= $1 . "\n";
2966                     # nuke leading blank lines
2967                     if ($contents =~ /^\s*$/) {
2968                         $contents = "";
2969                     }
2970                 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2971                     $inline_doc_state = STATE_INLINE_ERROR;
2972                     print STDERR "Warning(${file}:$.): ";
2973                     print STDERR "Incorrect use of kernel-doc format: $_";
2974                     ++$warnings;
2975                 }
2976             }
2977         } elsif ($state == STATE_PROTO) {       # scanning for function '{' (end of prototype)
2978             if (/$doc_inline_start/) {
2979                 $state = STATE_INLINE;
2980                 $inline_doc_state = STATE_INLINE_NAME;
2981             } elsif ($decl_type eq 'function') {
2982                 process_proto_function($_, $file);
2983             } else {
2984                 process_proto_type($_, $file);
2985             }
2986         } elsif ($state == STATE_DOCBLOCK) {
2987                 if (/$doc_end/)
2988                 {
2989                         dump_doc_section($file, $section, xml_escape($contents));
2990                         $section = $section_default;
2991                         $contents = "";
2992                         $function = "";
2993                         %parameterdescs = ();
2994                         %parametertypes = ();
2995                         @parameterlist = ();
2996                         %sections = ();
2997                         @sectionlist = ();
2998                         $prototype = "";
2999                         $state = STATE_NORMAL;
3000                 }
3001                 elsif (/$doc_content/)
3002                 {
3003                         if ( $1 eq "" )
3004                         {
3005                                 $contents .= $blankline;
3006                         }
3007                         else
3008                         {
3009                                 $contents .= $1 . "\n";
3010                         }
3011                 }
3012         }
3013     }
3014     if ($initial_section_counter == $section_counter) {
3015         print STDERR "${file}:1: warning: no structured comments found\n";
3016         if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
3017             print STDERR "    Was looking for '$_'.\n" for keys %function_table;
3018         }
3019         if ($output_mode eq "xml") {
3020             # The template wants at least one RefEntry here; make one.
3021             print "<refentry>\n";
3022             print " <refnamediv>\n";
3023             print "  <refname>\n";
3024             print "   ${orig_file}\n";
3025             print "  </refname>\n";
3026             print "  <refpurpose>\n";
3027             print "   Document generation inconsistency\n";
3028             print "  </refpurpose>\n";
3029             print " </refnamediv>\n";
3030             print " <refsect1>\n";
3031             print "  <title>\n";
3032             print "   Oops\n";
3033             print "  </title>\n";
3034             print "  <warning>\n";
3035             print "   <para>\n";
3036             print "    The template for this document tried to insert\n";
3037             print "    the structured comment from the file\n";
3038             print "    <filename>${orig_file}</filename> at this point,\n";
3039             print "    but none was found.\n";
3040             print "    This dummy section is inserted to allow\n";
3041             print "    generation to continue.\n";
3042             print "   </para>\n";
3043             print "  </warning>\n";
3044             print " </refsect1>\n";
3045             print "</refentry>\n";
3046         }
3047     }
3048 }
3049
3050
3051 $kernelversion = get_kernel_version();
3052
3053 # generate a sequence of code that will splice in highlighting information
3054 # using the s// operator.
3055 for (my $k = 0; $k < @highlights; $k++) {
3056     my $pattern = $highlights[$k][0];
3057     my $result = $highlights[$k][1];
3058 #   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
3059     $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
3060 }
3061
3062 # Read the file that maps relative names to absolute names for
3063 # separate source and object directories and for shadow trees.
3064 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
3065         my ($relname, $absname);
3066         while(<SOURCE_MAP>) {
3067                 chop();
3068                 ($relname, $absname) = (split())[0..1];
3069                 $relname =~ s:^/+::;
3070                 $source_map{$relname} = $absname;
3071         }
3072         close(SOURCE_MAP);
3073 }
3074
3075 foreach (@ARGV) {
3076     chomp;
3077     process_file($_);
3078 }
3079 if ($verbose && $errors) {
3080   print STDERR "$errors errors\n";
3081 }
3082 if ($verbose && $warnings) {
3083   print STDERR "$warnings warnings\n";
3084 }
3085
3086 exit($errors);