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