scripts/kernel-doc

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