scripts/kernel-doc

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