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