scripts/kernel-doc

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