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