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