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, "\\:ref\\:`\$1 \$2`"],
 279                        [$type_enum_full, "\\:ref\\:`\$1 \$2`"],
 280                        [$type_struct, "\\:ref\\:`struct \$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
1839     my $name = "enum " . $args{'enum'};
1840     print ".. _" . $name . ":\n\n";
1841     print "**$name**\n\n";
1842     print "    " . $args{'purpose'} . "\n\n";
1843
1844     print "..\n\n:Constants:\n\n";
1845     my $oldprefix = $lineprefix;
1846     $lineprefix = "    ";
1847     foreach $parameter (@{$args{'parameterlist'}}) {
1848         print "  `$parameter`\n";
1849         if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1850             output_highlight_rst($args{'parameterdescs'}{$parameter});
1851         } else {
1852             print "    undescribed\n";
1853         }
1854         print "\n";
1855     }
1856     $lineprefix = $oldprefix;
1857     output_section_rst(@_);
1858 }
1859
1860 sub output_typedef_rst(%) {
1861     my %args = %{$_[0]};
1862     my ($parameter);
1863     my $count;
1864     my $name = "typedef " . $args{'typedef'};
1865
1866     print "**$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 ".. _" . $name . ":\n\n";
1878     print "**$name**\n\n";
1879     print "    " . $args{'purpose'} . "\n\n";
1880
1881     print ":Definition:\n\n";
1882     print " ::\n\n";
1883     print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
1884     foreach $parameter (@{$args{'parameterlist'}}) {
1885         if ($parameter =~ /^#/) {
1886             print "    " . "$parameter\n";
1887             next;
1888         }
1889
1890         my $parameter_name = $parameter;
1891         $parameter_name =~ s/\[.*//;
1892
1893         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1894         $type = $args{'parametertypes'}{$parameter};
1895         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1896             # pointer-to-function
1897             print "    $1 $parameter) ($2);\n";
1898         } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1899             # bitfield
1900             print "    $1 $parameter$2;\n";
1901         } else {
1902             print "    " . $type . " " . $parameter . ";\n";
1903         }
1904     }
1905     print "  };\n\n";
1906
1907     print ":Members:\n\n";
1908     foreach $parameter (@{$args{'parameterlist'}}) {
1909         ($parameter =~ /^#/) && next;
1910
1911         my $parameter_name = $parameter;
1912         $parameter_name =~ s/\[.*//;
1913
1914         ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1915         $type = $args{'parametertypes'}{$parameter};
1916         print "      `$type $parameter`" . "\n";
1917         my $oldprefix = $lineprefix;
1918         $lineprefix = "        ";
1919         output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1920         $lineprefix = $oldprefix;
1921         print "\n";
1922     }
1923     print "\n";
1924     output_section_rst(@_);
1925 }
1926
1927
1928 ## list mode output functions
1929
1930 sub output_function_list(%) {
1931     my %args = %{$_[0]};
1932
1933     print $args{'function'} . "\n";
1934 }
1935
1936 # output enum in list
1937 sub output_enum_list(%) {
1938     my %args = %{$_[0]};
1939     print $args{'enum'} . "\n";
1940 }
1941
1942 # output typedef in list
1943 sub output_typedef_list(%) {
1944     my %args = %{$_[0]};
1945     print $args{'typedef'} . "\n";
1946 }
1947
1948 # output struct as list
1949 sub output_struct_list(%) {
1950     my %args = %{$_[0]};
1951
1952     print $args{'struct'} . "\n";
1953 }
1954
1955 sub output_blockhead_list(%) {
1956     my %args = %{$_[0]};
1957     my ($parameter, $section);
1958
1959     foreach $section (@{$args{'sectionlist'}}) {
1960         print "DOC: $section\n";
1961     }
1962 }
1963
1964 ##
1965 # generic output function for all types (function, struct/union, typedef, enum);
1966 # calls the generated, variable output_ function name based on
1967 # functype and output_mode
1968 sub output_declaration {
1969     no strict 'refs';
1970     my $name = shift;
1971     my $functype = shift;
1972     my $func = "output_${functype}_$output_mode";
1973     if (($function_only==0) ||
1974         ( $function_only == 1 && defined($function_table{$name})) ||
1975         ( $function_only == 2 && !($functype eq "function" && defined($function_table{$name}))))
1976     {
1977         &$func(@_);
1978         $section_counter++;
1979     }
1980 }
1981
1982 ##
1983 # generic output function - calls the right one based on current output mode.
1984 sub output_blockhead {
1985     no strict 'refs';
1986     my $func = "output_blockhead_" . $output_mode;
1987     &$func(@_);
1988     $section_counter++;
1989 }
1990
1991 ##
1992 # takes a declaration (struct, union, enum, typedef) and
1993 # invokes the right handler. NOT called for functions.
1994 sub dump_declaration($$) {
1995     no strict 'refs';
1996     my ($prototype, $file) = @_;
1997     my $func = "dump_" . $decl_type;
1998     &$func(@_);
1999 }
2000
2001 sub dump_union($$) {
2002     dump_struct(@_);
2003 }
2004
2005 sub dump_struct($$) {
2006     my $x = shift;
2007     my $file = shift;
2008     my $nested;
2009
2010     if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2011         #my $decl_type = $1;
2012         $declaration_name = $2;
2013         my $members = $3;
2014
2015         # ignore embedded structs or unions
2016         $members =~ s/({.*})//g;
2017         $nested = $1;
2018
2019         # ignore members marked private:
2020         $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2021         $members =~ s/\/\*\s*private:.*//gosi;
2022         # strip comments:
2023         $members =~ s/\/\*.*?\*\///gos;
2024         $nested =~ s/\/\*.*?\*\///gos;
2025         # strip kmemcheck_bitfield_{begin,end}.*;
2026         $members =~ s/kmemcheck_bitfield_.*?;//gos;
2027         # strip attributes
2028         $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2029         $members =~ s/__aligned\s*\([^;]*\)//gos;
2030         $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2031         # replace DECLARE_BITMAP
2032         $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2033
2034         create_parameterlist($members, ';', $file);
2035         check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
2036
2037         output_declaration($declaration_name,
2038                            'struct',
2039                            {'struct' => $declaration_name,
2040                             'module' => $modulename,
2041                             'parameterlist' => \@parameterlist,
2042                             'parameterdescs' => \%parameterdescs,
2043                             'parametertypes' => \%parametertypes,
2044                             'sectionlist' => \@sectionlist,
2045                             'sections' => \%sections,
2046                             'purpose' => $declaration_purpose,
2047                             'type' => $decl_type
2048                            });
2049     }
2050     else {
2051         print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2052         ++$errors;
2053     }
2054 }
2055
2056 sub dump_enum($$) {
2057     my $x = shift;
2058     my $file = shift;
2059
2060     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
2061     # strip #define macros inside enums
2062     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2063
2064     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2065         $declaration_name = $1;
2066         my $members = $2;
2067
2068         foreach my $arg (split ',', $members) {
2069             $arg =~ s/^\s*(\w+).*/$1/;
2070             push @parameterlist, $arg;
2071             if (!$parameterdescs{$arg}) {
2072                 $parameterdescs{$arg} = $undescribed;
2073                 print STDERR "${file}:$.: warning: Enum value '$arg' ".
2074                     "not described in enum '$declaration_name'\n";
2075             }
2076
2077         }
2078
2079         output_declaration($declaration_name,
2080                            'enum',
2081                            {'enum' => $declaration_name,
2082                             'module' => $modulename,
2083                             'parameterlist' => \@parameterlist,
2084                             'parameterdescs' => \%parameterdescs,
2085                             'sectionlist' => \@sectionlist,
2086                             'sections' => \%sections,
2087                             'purpose' => $declaration_purpose
2088                            });
2089     }
2090     else {
2091         print STDERR "${file}:$.: error: Cannot parse enum!\n";
2092         ++$errors;
2093     }
2094 }
2095
2096 sub dump_typedef($$) {
2097     my $x = shift;
2098     my $file = shift;
2099
2100     $x =~ s@/\*.*?\*/@@gos;     # strip comments.
2101
2102     # Parse function prototypes
2103     if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2104         # Function typedefs
2105         $return_type = $1;
2106         $declaration_name = $2;
2107         my $args = $3;
2108
2109         create_parameterlist($args, ',', $file);
2110
2111         output_declaration($declaration_name,
2112                            'function',
2113                            {'function' => $declaration_name,
2114                             'module' => $modulename,
2115                             'functiontype' => $return_type,
2116                             'parameterlist' => \@parameterlist,
2117                             'parameterdescs' => \%parameterdescs,
2118                             'parametertypes' => \%parametertypes,
2119                             'sectionlist' => \@sectionlist,
2120                             'sections' => \%sections,
2121                             'purpose' => $declaration_purpose
2122                            });
2123         return;
2124     }
2125
2126     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2127         $x =~ s/\(*.\)\s*;$/;/;
2128         $x =~ s/\[*.\]\s*;$/;/;
2129     }
2130
2131     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2132         $declaration_name = $1;
2133
2134         output_declaration($declaration_name,
2135                            'typedef',
2136                            {'typedef' => $declaration_name,
2137                             'module' => $modulename,
2138                             'sectionlist' => \@sectionlist,
2139                             'sections' => \%sections,
2140                             'purpose' => $declaration_purpose
2141                            });
2142     }
2143     else {
2144         print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2145         ++$errors;
2146     }
2147 }
2148
2149 sub save_struct_actual($) {
2150     my $actual = shift;
2151
2152     # strip all spaces from the actual param so that it looks like one string item
2153     $actual =~ s/\s*//g;
2154     $struct_actual = $struct_actual . $actual . " ";
2155 }
2156
2157 sub create_parameterlist($$$) {
2158     my $args = shift;
2159     my $splitter = shift;
2160     my $file = shift;
2161     my $type;
2162     my $param;
2163
2164     # temporarily replace commas inside function pointer definition
2165     while ($args =~ /(\([^\),]+),/) {
2166         $args =~ s/(\([^\),]+),/$1#/g;
2167     }
2168
2169     foreach my $arg (split($splitter, $args)) {
2170         # strip comments
2171         $arg =~ s/\/\*.*\*\///;
2172         # strip leading/trailing spaces
2173         $arg =~ s/^\s*//;
2174         $arg =~ s/\s*$//;
2175         $arg =~ s/\s+/ /;
2176
2177         if ($arg =~ /^#/) {
2178             # Treat preprocessor directive as a typeless variable just to fill
2179             # corresponding data structures "correctly". Catch it later in
2180             # output_* subs.
2181             push_parameter($arg, "", $file);
2182         } elsif ($arg =~ m/\(.+\)\s*\(/) {
2183             # pointer-to-function
2184             $arg =~ tr/#/,/;
2185             $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2186             $param = $1;
2187             $type = $arg;
2188             $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2189             save_struct_actual($param);
2190             push_parameter($param, $type, $file);
2191         } elsif ($arg) {
2192             $arg =~ s/\s*:\s*/:/g;
2193             $arg =~ s/\s*\[/\[/g;
2194
2195             my @args = split('\s*,\s*', $arg);
2196             if ($args[0] =~ m/\*/) {
2197                 $args[0] =~ s/(\*+)\s*/ $1/;
2198             }
2199
2200             my @first_arg;
2201             if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2202                     shift @args;
2203                     push(@first_arg, split('\s+', $1));
2204                     push(@first_arg, $2);
2205             } else {
2206                     @first_arg = split('\s+', shift @args);
2207             }
2208
2209             unshift(@args, pop @first_arg);
2210             $type = join " ", @first_arg;
2211
2212             foreach $param (@args) {
2213                 if ($param =~ m/^(\*+)\s*(.*)/) {
2214                     save_struct_actual($2);
2215                     push_parameter($2, "$type $1", $file);
2216                 }
2217                 elsif ($param =~ m/(.*?):(\d+)/) {
2218                     if ($type ne "") { # skip unnamed bit-fields
2219                         save_struct_actual($1);
2220                         push_parameter($1, "$type:$2", $file)
2221                     }
2222                 }
2223                 else {
2224                     save_struct_actual($param);
2225                     push_parameter($param, $type, $file);
2226                 }
2227             }
2228         }
2229     }
2230 }
2231
2232 sub push_parameter($$$) {
2233         my $param = shift;
2234         my $type = shift;
2235         my $file = shift;
2236
2237         if (($anon_struct_union == 1) && ($type eq "") &&
2238             ($param eq "}")) {
2239                 return;         # ignore the ending }; from anon. struct/union
2240         }
2241
2242         $anon_struct_union = 0;
2243         my $param_name = $param;
2244         $param_name =~ s/\[.*//;
2245
2246         if ($type eq "" && $param =~ /\.\.\.$/)
2247         {
2248             if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2249                 $parameterdescs{$param} = "variable arguments";
2250             }
2251         }
2252         elsif ($type eq "" && ($param eq "" or $param eq "void"))
2253         {
2254             $param="void";
2255             $parameterdescs{void} = "no arguments";
2256         }
2257         elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2258         # handle unnamed (anonymous) union or struct:
2259         {
2260                 $type = $param;
2261                 $param = "{unnamed_" . $param . "}";
2262                 $parameterdescs{$param} = "anonymous\n";
2263                 $anon_struct_union = 1;
2264         }
2265
2266         # warn if parameter has no description
2267         # (but ignore ones starting with # as these are not parameters
2268         # but inline preprocessor statements);
2269         # also ignore unnamed structs/unions;
2270         if (!$anon_struct_union) {
2271         if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2272
2273             $parameterdescs{$param_name} = $undescribed;
2274
2275             if (($type eq 'function') || ($type eq 'enum')) {
2276                 print STDERR "${file}:$.: warning: Function parameter ".
2277                     "or member '$param' not " .
2278                     "described in '$declaration_name'\n";
2279             }
2280             print STDERR "${file}:$.: warning:" .
2281                          " No description found for parameter '$param'\n";
2282             ++$warnings;
2283         }
2284         }
2285
2286         $param = xml_escape($param);
2287
2288         # strip spaces from $param so that it is one continuous string
2289         # on @parameterlist;
2290         # this fixes a problem where check_sections() cannot find
2291         # a parameter like "addr[6 + 2]" because it actually appears
2292         # as "addr[6", "+", "2]" on the parameter list;
2293         # but it's better to maintain the param string unchanged for output,
2294         # so just weaken the string compare in check_sections() to ignore
2295         # "[blah" in a parameter string;
2296         ###$param =~ s/\s*//g;
2297         push @parameterlist, $param;
2298         $parametertypes{$param} = $type;
2299 }
2300
2301 sub check_sections($$$$$$) {
2302         my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2303         my @sects = split ' ', $sectcheck;
2304         my @prms = split ' ', $prmscheck;
2305         my $err;
2306         my ($px, $sx);
2307         my $prm_clean;          # strip trailing "[array size]" and/or beginning "*"
2308
2309         foreach $sx (0 .. $#sects) {
2310                 $err = 1;
2311                 foreach $px (0 .. $#prms) {
2312                         $prm_clean = $prms[$px];
2313                         $prm_clean =~ s/\[.*\]//;
2314                         $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2315                         # ignore array size in a parameter string;
2316                         # however, the original param string may contain
2317                         # spaces, e.g.:  addr[6 + 2]
2318                         # and this appears in @prms as "addr[6" since the
2319                         # parameter list is split at spaces;
2320                         # hence just ignore "[..." for the sections check;
2321                         $prm_clean =~ s/\[.*//;
2322
2323                         ##$prm_clean =~ s/^\**//;
2324                         if ($prm_clean eq $sects[$sx]) {
2325                                 $err = 0;
2326                                 last;
2327                         }
2328                 }
2329                 if ($err) {
2330                         if ($decl_type eq "function") {
2331                                 print STDERR "${file}:$.: warning: " .
2332                                         "Excess function parameter " .
2333                                         "'$sects[$sx]' " .
2334                                         "description in '$decl_name'\n";
2335                                 ++$warnings;
2336                         } else {
2337                                 if ($nested !~ m/\Q$sects[$sx]\E/) {
2338                                     print STDERR "${file}:$.: warning: " .
2339                                         "Excess struct/union/enum/typedef member " .
2340                                         "'$sects[$sx]' " .
2341                                         "description in '$decl_name'\n";
2342                                     ++$warnings;
2343                                 }
2344                         }
2345                 }
2346         }
2347 }
2348
2349 ##
2350 # Checks the section describing the return value of a function.
2351 sub check_return_section {
2352         my $file = shift;
2353         my $declaration_name = shift;
2354         my $return_type = shift;
2355
2356         # Ignore an empty return type (It's a macro)
2357         # Ignore functions with a "void" return type. (But don't ignore "void *")
2358         if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2359                 return;
2360         }
2361
2362         if (!defined($sections{$section_return}) ||
2363             $sections{$section_return} eq "") {
2364                 print STDERR "${file}:$.: warning: " .
2365                         "No description found for return value of " .
2366                         "'$declaration_name'\n";
2367                 ++$warnings;
2368         }
2369 }
2370
2371 ##
2372 # takes a function prototype and the name of the current file being
2373 # processed and spits out all the details stored in the global
2374 # arrays/hashes.
2375 sub dump_function($$) {
2376     my $prototype = shift;
2377     my $file = shift;
2378     my $noret = 0;
2379
2380     $prototype =~ s/^static +//;
2381     $prototype =~ s/^extern +//;
2382     $prototype =~ s/^asmlinkage +//;
2383     $prototype =~ s/^inline +//;
2384     $prototype =~ s/^__inline__ +//;
2385     $prototype =~ s/^__inline +//;
2386     $prototype =~ s/^__always_inline +//;
2387     $prototype =~ s/^noinline +//;
2388     $prototype =~ s/__init +//;
2389     $prototype =~ s/__init_or_module +//;
2390     $prototype =~ s/__meminit +//;
2391     $prototype =~ s/__must_check +//;
2392     $prototype =~ s/__weak +//;
2393     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2394     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2395
2396     # Yes, this truly is vile.  We are looking for:
2397     # 1. Return type (may be nothing if we're looking at a macro)
2398     # 2. Function name
2399     # 3. Function parameters.
2400     #
2401     # All the while we have to watch out for function pointer parameters
2402     # (which IIRC is what the two sections are for), C types (these
2403     # regexps don't even start to express all the possibilities), and
2404     # so on.
2405     #
2406     # If you mess with these regexps, it's a good idea to check that
2407     # the following functions' documentation still comes out right:
2408     # - parport_register_device (function pointer parameters)
2409     # - atomic_set (macro)
2410     # - pci_match_device, __copy_to_user (long return type)
2411
2412     if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2413         # This is an object-like macro, it has no return type and no parameter
2414         # list.
2415         # Function-like macros are not allowed to have spaces between
2416         # declaration_name and opening parenthesis (notice the \s+).
2417         $return_type = $1;
2418         $declaration_name = $2;
2419         $noret = 1;
2420     } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2421         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2422         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2423         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2424         $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2425         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2426         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2427         $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2428         $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2429         $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2430         $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2431         $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2432         $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2433         $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2434         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2435         $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2436         $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
2437         $return_type = $1;
2438         $declaration_name = $2;
2439         my $args = $3;
2440
2441         create_parameterlist($args, ',', $file);
2442     } else {
2443         print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2444         return;
2445     }
2446
2447         my $prms = join " ", @parameterlist;
2448         check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2449
2450         # This check emits a lot of warnings at the moment, because many
2451         # functions don't have a 'Return' doc section. So until the number
2452         # of warnings goes sufficiently down, the check is only performed in
2453         # verbose mode.
2454         # TODO: always perform the check.
2455         if ($verbose && !$noret) {
2456                 check_return_section($file, $declaration_name, $return_type);
2457         }
2458
2459     output_declaration($declaration_name,
2460                        'function',
2461                        {'function' => $declaration_name,
2462                         'module' => $modulename,
2463                         'functiontype' => $return_type,
2464                         'parameterlist' => \@parameterlist,
2465                         'parameterdescs' => \%parameterdescs,
2466                         'parametertypes' => \%parametertypes,
2467                         'sectionlist' => \@sectionlist,
2468                         'sections' => \%sections,
2469                         'purpose' => $declaration_purpose
2470                        });
2471 }
2472
2473 sub reset_state {
2474     $function = "";
2475     %constants = ();
2476     %parameterdescs = ();
2477     %parametertypes = ();
2478     @parameterlist = ();
2479     %sections = ();
2480     @sectionlist = ();
2481     $sectcheck = "";
2482     $struct_actual = "";
2483     $prototype = "";
2484
2485     $state = 0;
2486     $split_doc_state = 0;
2487 }
2488
2489 sub tracepoint_munge($) {
2490         my $file = shift;
2491         my $tracepointname = 0;
2492         my $tracepointargs = 0;
2493
2494         if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2495                 $tracepointname = $1;
2496         }
2497         if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2498                 $tracepointname = $1;
2499         }
2500         if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2501                 $tracepointname = $2;
2502         }
2503         $tracepointname =~ s/^\s+//; #strip leading whitespace
2504         if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2505                 $tracepointargs = $1;
2506         }
2507         if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2508                 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2509                              "$prototype\n";
2510         } else {
2511                 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2512         }
2513 }
2514
2515 sub syscall_munge() {
2516         my $void = 0;
2517
2518         $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2519 ##      if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2520         if ($prototype =~ m/SYSCALL_DEFINE0/) {
2521                 $void = 1;
2522 ##              $prototype = "long sys_$1(void)";
2523         }
2524
2525         $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2526         if ($prototype =~ m/long (sys_.*?),/) {
2527                 $prototype =~ s/,/\(/;
2528         } elsif ($void) {
2529                 $prototype =~ s/\)/\(void\)/;
2530         }
2531
2532         # now delete all of the odd-number commas in $prototype
2533         # so that arg types & arg names don't have a comma between them
2534         my $count = 0;
2535         my $len = length($prototype);
2536         if ($void) {
2537                 $len = 0;       # skip the for-loop
2538         }
2539         for (my $ix = 0; $ix < $len; $ix++) {
2540                 if (substr($prototype, $ix, 1) eq ',') {
2541                         $count++;
2542                         if ($count % 2 == 1) {
2543                                 substr($prototype, $ix, 1) = ' ';
2544                         }
2545                 }
2546         }
2547 }
2548
2549 sub process_state3_function($$) {
2550     my $x = shift;
2551     my $file = shift;
2552
2553     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2554
2555     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2556         # do nothing
2557     }
2558     elsif ($x =~ /([^\{]*)/) {
2559         $prototype .= $1;
2560     }
2561
2562     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2563         $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2564         $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2565         $prototype =~ s@^\s+@@gos; # strip leading spaces
2566         if ($prototype =~ /SYSCALL_DEFINE/) {
2567                 syscall_munge();
2568         }
2569         if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2570             $prototype =~ /DEFINE_SINGLE_EVENT/)
2571         {
2572                 tracepoint_munge($file);
2573         }
2574         dump_function($prototype, $file);
2575         reset_state();
2576     }
2577 }
2578
2579 sub process_state3_type($$) {
2580     my $x = shift;
2581     my $file = shift;
2582
2583     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2584     $x =~ s@^\s+@@gos; # strip leading spaces
2585     $x =~ s@\s+$@@gos; # strip trailing spaces
2586     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2587
2588     if ($x =~ /^#/) {
2589         # To distinguish preprocessor directive from regular declaration later.
2590         $x .= ";";
2591     }
2592
2593     while (1) {
2594         if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2595             $prototype .= $1 . $2;
2596             ($2 eq '{') && $brcount++;
2597             ($2 eq '}') && $brcount--;
2598             if (($2 eq ';') && ($brcount == 0)) {
2599                 dump_declaration($prototype, $file);
2600                 reset_state();
2601                 last;
2602             }
2603             $x = $3;
2604         } else {
2605             $prototype .= $x;
2606             last;
2607         }
2608     }
2609 }
2610
2611 # xml_escape: replace <, >, and & in the text stream;
2612 #
2613 # however, formatting controls that are generated internally/locally in the
2614 # kernel-doc script are not escaped here; instead, they begin life like
2615 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2616 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2617 # just before actual output; (this is done by local_unescape())
2618 sub xml_escape($) {
2619         my $text = shift;
2620         if (($output_mode eq "text") || ($output_mode eq "man")) {
2621                 return $text;
2622         }
2623         $text =~ s/\&/\\\\\\amp;/g;
2624         $text =~ s/\</\\\\\\lt;/g;
2625         $text =~ s/\>/\\\\\\gt;/g;
2626         return $text;
2627 }
2628
2629 # xml_unescape: reverse the effects of xml_escape
2630 sub xml_unescape($) {
2631         my $text = shift;
2632         if (($output_mode eq "text") || ($output_mode eq "man")) {
2633                 return $text;
2634         }
2635         $text =~ s/\\\\\\amp;/\&/g;
2636         $text =~ s/\\\\\\lt;/</g;
2637         $text =~ s/\\\\\\gt;/>/g;
2638         return $text;
2639 }
2640
2641 # convert local escape strings to html
2642 # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
2643 sub local_unescape($) {
2644         my $text = shift;
2645         if (($output_mode eq "text") || ($output_mode eq "man")) {
2646                 return $text;
2647         }
2648         $text =~ s/\\\\\\\\lt:/</g;
2649         $text =~ s/\\\\\\\\gt:/>/g;
2650         return $text;
2651 }
2652
2653 sub process_file($) {
2654     my $file;
2655     my $identifier;
2656     my $func;
2657     my $descr;
2658     my $in_purpose = 0;
2659     my $initial_section_counter = $section_counter;
2660     my ($orig_file) = @_;
2661
2662     if (defined($ENV{'SRCTREE'})) {
2663         $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2664     }
2665     else {
2666         $file = $orig_file;
2667     }
2668     if (defined($source_map{$file})) {
2669         $file = $source_map{$file};
2670     }
2671
2672     if (!open(IN,"<$file")) {
2673         print STDERR "Error: Cannot open file $file\n";
2674         ++$errors;
2675         return;
2676     }
2677
2678     $. = 1;
2679
2680     $section_counter = 0;
2681     while (<IN>) {
2682         while (s/\\\s*$//) {
2683             $_ .= <IN>;
2684         }
2685         if ($state == 0) {
2686             if (/$doc_start/o) {
2687                 $state = 1;             # next line is always the function name
2688                 $in_doc_sect = 0;
2689             }
2690         } elsif ($state == 1) { # this line is the function name (always)
2691             if (/$doc_block/o) {
2692                 $state = 4;
2693                 $contents = "";
2694                 if ( $1 eq "" ) {
2695                         $section = $section_intro;
2696                 } else {
2697                         $section = $1;
2698                 }
2699             }
2700             elsif (/$doc_decl/o) {
2701                 $identifier = $1;
2702                 if (/\s*([\w\s]+?)\s*-/) {
2703                     $identifier = $1;
2704                 }
2705
2706                 $state = 2;
2707                 if (/-(.*)/) {
2708                     # strip leading/trailing/multiple spaces
2709                     $descr= $1;
2710                     $descr =~ s/^\s*//;
2711                     $descr =~ s/\s*$//;
2712                     $descr =~ s/\s+/ /g;
2713                     $declaration_purpose = xml_escape($descr);
2714                     $in_purpose = 1;
2715                 } else {
2716                     $declaration_purpose = "";
2717                 }
2718
2719                 if (($declaration_purpose eq "") && $verbose) {
2720                         print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2721                         print STDERR $_;
2722                         ++$warnings;
2723                 }
2724
2725                 if ($identifier =~ m/^struct/) {
2726                     $decl_type = 'struct';
2727                 } elsif ($identifier =~ m/^union/) {
2728                     $decl_type = 'union';
2729                 } elsif ($identifier =~ m/^enum/) {
2730                     $decl_type = 'enum';
2731                 } elsif ($identifier =~ m/^typedef/) {
2732                     $decl_type = 'typedef';
2733                 } else {
2734                     $decl_type = 'function';
2735                 }
2736
2737                 if ($verbose) {
2738                     print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2739                 }
2740             } else {
2741                 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2742                 " - I thought it was a doc line\n";
2743                 ++$warnings;
2744                 $state = 0;
2745             }
2746         } elsif ($state == 2) { # look for head: lines, and include content
2747             if (/$doc_sect/o) {
2748                 $newsection = $1;
2749                 $newcontents = $2;
2750
2751                 if (($contents ne "") && ($contents ne "\n")) {
2752                     if (!$in_doc_sect && $verbose) {
2753                         print STDERR "${file}:$.: warning: contents before sections\n";
2754                         ++$warnings;
2755                     }
2756                     dump_section($file, $section, xml_escape($contents));
2757                     $section = $section_default;
2758                 }
2759
2760                 $in_doc_sect = 1;
2761                 $in_purpose = 0;
2762                 $contents = $newcontents;
2763                 if ($contents ne "") {
2764                     while ((substr($contents, 0, 1) eq " ") ||
2765                         substr($contents, 0, 1) eq "\t") {
2766                             $contents = substr($contents, 1);
2767                     }
2768                     $contents .= "\n";
2769                 }
2770                 $section = $newsection;
2771             } elsif (/$doc_end/) {
2772                 if (($contents ne "") && ($contents ne "\n")) {
2773                     dump_section($file, $section, xml_escape($contents));
2774                     $section = $section_default;
2775                     $contents = "";
2776                 }
2777                 # look for doc_com + <text> + doc_end:
2778                 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2779                     print STDERR "${file}:$.: warning: suspicious ending line: $_";
2780                     ++$warnings;
2781                 }
2782
2783                 $prototype = "";
2784                 $state = 3;
2785                 $brcount = 0;
2786 #               print STDERR "end of doc comment, looking for prototype\n";
2787             } elsif (/$doc_content/) {
2788                 # miguel-style comment kludge, look for blank lines after
2789                 # @parameter line to signify start of description
2790                 if ($1 eq "") {
2791                     if ($section =~ m/^@/ || $section eq $section_context) {
2792                         dump_section($file, $section, xml_escape($contents));
2793                         $section = $section_default;
2794                         $contents = "";
2795                     } else {
2796                         $contents .= "\n";
2797                     }
2798                     $in_purpose = 0;
2799                 } elsif ($in_purpose == 1) {
2800                     # Continued declaration purpose
2801                     chomp($declaration_purpose);
2802                     $declaration_purpose .= " " . xml_escape($1);
2803                     $declaration_purpose =~ s/\s+/ /g;
2804                 } else {
2805                     $contents .= $1 . "\n";
2806                 }
2807             } else {
2808                 # i dont know - bad line?  ignore.
2809                 print STDERR "${file}:$.: warning: bad line: $_";
2810                 ++$warnings;
2811             }
2812         } elsif ($state == 5) { # scanning for split parameters
2813             # First line (state 1) needs to be a @parameter
2814             if ($split_doc_state == 1 && /$doc_split_sect/o) {
2815                 $section = $1;
2816                 $contents = $2;
2817                 if ($contents ne "") {
2818                     while ((substr($contents, 0, 1) eq " ") ||
2819                            substr($contents, 0, 1) eq "\t") {
2820                         $contents = substr($contents, 1);
2821                     }
2822                 $contents .= "\n";
2823                 }
2824                 $split_doc_state = 2;
2825             # Documentation block end */
2826             } elsif (/$doc_split_end/) {
2827                 if (($contents ne "") && ($contents ne "\n")) {
2828                     dump_section($file, $section, xml_escape($contents));
2829                     $section = $section_default;
2830                     $contents = "";
2831                 }
2832                 $state = 3;
2833                 $split_doc_state = 0;
2834             # Regular text
2835             } elsif (/$doc_content/) {
2836                 if ($split_doc_state == 2) {
2837                     $contents .= $1 . "\n";
2838                 } elsif ($split_doc_state == 1) {
2839                     $split_doc_state = 4;
2840                     print STDERR "Warning(${file}:$.): ";
2841                     print STDERR "Incorrect use of kernel-doc format: $_";
2842                     ++$warnings;
2843                 }
2844             }
2845         } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2846             if (/$doc_split_start/) {
2847                 $state = 5;
2848                 $split_doc_state = 1;
2849             } elsif ($decl_type eq 'function') {
2850                 process_state3_function($_, $file);
2851             } else {
2852                 process_state3_type($_, $file);
2853             }
2854         } elsif ($state == 4) {
2855                 # Documentation block
2856                 if (/$doc_block/) {
2857                         dump_doc_section($file, $section, xml_escape($contents));
2858                         $contents = "";
2859                         $function = "";
2860                         %constants = ();
2861                         %parameterdescs = ();
2862                         %parametertypes = ();
2863                         @parameterlist = ();
2864                         %sections = ();
2865                         @sectionlist = ();
2866                         $prototype = "";
2867                         if ( $1 eq "" ) {
2868                                 $section = $section_intro;
2869                         } else {
2870                                 $section = $1;
2871                         }
2872                 }
2873                 elsif (/$doc_end/)
2874                 {
2875                         dump_doc_section($file, $section, xml_escape($contents));
2876                         $contents = "";
2877                         $function = "";
2878                         %constants = ();
2879                         %parameterdescs = ();
2880                         %parametertypes = ();
2881                         @parameterlist = ();
2882                         %sections = ();
2883                         @sectionlist = ();
2884                         $prototype = "";
2885                         $state = 0;
2886                 }
2887                 elsif (/$doc_content/)
2888                 {
2889                         if ( $1 eq "" )
2890                         {
2891                                 $contents .= $blankline;
2892                         }
2893                         else
2894                         {
2895                                 $contents .= $1 . "\n";
2896                         }
2897                 }
2898         }
2899     }
2900     if ($initial_section_counter == $section_counter) {
2901         print STDERR "${file}:1: warning: no structured comments found\n";
2902         if (($function_only == 1) && ($show_not_found == 1)) {
2903             print STDERR "    Was looking for '$_'.\n" for keys %function_table;
2904         }
2905         if ($output_mode eq "xml") {
2906             # The template wants at least one RefEntry here; make one.
2907             print "<refentry>\n";
2908             print " <refnamediv>\n";
2909             print "  <refname>\n";
2910             print "   ${orig_file}\n";
2911             print "  </refname>\n";
2912             print "  <refpurpose>\n";
2913             print "   Document generation inconsistency\n";
2914             print "  </refpurpose>\n";
2915             print " </refnamediv>\n";
2916             print " <refsect1>\n";
2917             print "  <title>\n";
2918             print "   Oops\n";
2919             print "  </title>\n";
2920             print "  <warning>\n";
2921             print "   <para>\n";
2922             print "    The template for this document tried to insert\n";
2923             print "    the structured comment from the file\n";
2924             print "    <filename>${orig_file}</filename> at this point,\n";
2925             print "    but none was found.\n";
2926             print "    This dummy section is inserted to allow\n";
2927             print "    generation to continue.\n";
2928             print "   </para>\n";
2929             print "  </warning>\n";
2930             print " </refsect1>\n";
2931             print "</refentry>\n";
2932         }
2933     }
2934 }
2935
2936
2937 $kernelversion = get_kernel_version();
2938
2939 # generate a sequence of code that will splice in highlighting information
2940 # using the s// operator.
2941 for (my $k = 0; $k < @highlights; $k++) {
2942     my $pattern = $highlights[$k][0];
2943     my $result = $highlights[$k][1];
2944 #   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2945     $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
2946 }
2947
2948 # Read the file that maps relative names to absolute names for
2949 # separate source and object directories and for shadow trees.
2950 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2951         my ($relname, $absname);
2952         while(<SOURCE_MAP>) {
2953                 chop();
2954                 ($relname, $absname) = (split())[0..1];
2955                 $relname =~ s:^/+::;
2956                 $source_map{$relname} = $absname;
2957         }
2958         close(SOURCE_MAP);
2959 }
2960
2961 foreach (@ARGV) {
2962     chomp;
2963     process_file($_);
2964 }
2965 if ($verbose && $errors) {
2966   print STDERR "$errors errors\n";
2967 }
2968 if ($verbose && $warnings) {
2969   print STDERR "$warnings warnings\n";
2970 }
2971
2972 exit($errors);