Back to home page

LXR

 
 

    


0001 #!/usr/bin/perl -w
0002 
0003 use strict;
0004 
0005 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
0006 ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
0007 ## Copyright (C) 2001  Simon Huggins                             ##
0008 ## Copyright (C) 2005-2012  Randy Dunlap                         ##
0009 ## Copyright (C) 2012  Dan Luedtke                               ##
0010 ##                               ##
0011 ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
0012 ## Copyright (c) 2000 MontaVista Software, Inc.          ##
0013 ##                               ##
0014 ## This software falls under the GNU General Public License.     ##
0015 ## Please read the COPYING file for more information             ##
0016 
0017 # 18/01/2001 -  Cleanups
0018 #       Functions prototyped as foo(void) same as foo()
0019 #       Stop eval'ing where we don't need to.
0020 # -- huggie@earth.li
0021 
0022 # 27/06/2001 -  Allowed whitespace after initial "/**" and
0023 #               allowed comments before function declarations.
0024 # -- Christian Kreibich <ck@whoop.org>
0025 
0026 # Still to do:
0027 #   - add perldoc documentation
0028 #   - Look more closely at some of the scarier bits :)
0029 
0030 # 26/05/2001 -  Support for separate source and object trees.
0031 #       Return error code.
0032 #       Keith Owens <kaos@ocs.com.au>
0033 
0034 # 23/09/2001 - Added support for typedefs, structs, enums and unions
0035 #              Support for Context section; can be terminated using empty line
0036 #              Small fixes (like spaces vs. \s in regex)
0037 # -- Tim Jansen <tim@tjansen.de>
0038 
0039 # 25/07/2012 - Added support for HTML5
0040 # -- Dan Luedtke <mail@danrl.de>
0041 
0042 sub usage {
0043     my $message = <<"EOF";
0044 Usage: $0 [OPTION ...] FILE ...
0045 
0046 Read C language source or header FILEs, extract embedded documentation comments,
0047 and print formatted documentation to standard output.
0048 
0049 The documentation comments are identified by "/**" opening comment mark. See
0050 Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
0051 
0052 Output format selection (mutually exclusive):
0053   -docbook      Output DocBook format.
0054   -html         Output HTML format.
0055   -html5        Output HTML5 format.
0056   -list         Output symbol list format. This is for use by docproc.
0057   -man          Output troff manual page format. This is the default.
0058   -rst          Output reStructuredText format.
0059   -text         Output plain text format.
0060 
0061 Output selection (mutually exclusive):
0062   -export       Only output documentation for symbols that have been
0063             exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
0064                         in any input FILE or -export-file FILE.
0065   -internal     Only output documentation for symbols that have NOT been
0066             exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
0067                         in any input FILE or -export-file FILE.
0068   -function NAME    Only output documentation for the given function(s)
0069             or DOC: section title(s). All other functions and DOC:
0070             sections are ignored. May be specified multiple times.
0071   -nofunction NAME  Do NOT output documentation for the given function(s);
0072             only output documentation for the other functions and
0073             DOC: sections. May be specified multiple times.
0074 
0075 Output selection modifiers:
0076   -no-doc-sections  Do not output DOC: sections.
0077   -enable-lineno        Enable output of #define LINENO lines. Only works with
0078                         reStructuredText format.
0079   -export-file FILE     Specify an additional FILE in which to look for
0080                         EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
0081                         -export or -internal. May be specified multiple times.
0082 
0083 Other parameters:
0084   -v            Verbose output, more warnings and other information.
0085   -h            Print this help.
0086 
0087 EOF
0088     print $message;
0089     exit 1;
0090 }
0091 
0092 #
0093 # format of comments.
0094 # In the following table, (...)? signifies optional structure.
0095 #                         (...)* signifies 0 or more structure elements
0096 # /**
0097 #  * function_name(:)? (- short description)?
0098 # (* @parameterx: (description of parameter x)?)*
0099 # (* a blank line)?
0100 #  * (Description:)? (Description of function)?
0101 #  * (section header: (section description)? )*
0102 #  (*)?*/
0103 #
0104 # So .. the trivial example would be:
0105 #
0106 # /**
0107 #  * my_function
0108 #  */
0109 #
0110 # If the Description: header tag is omitted, then there must be a blank line
0111 # after the last parameter specification.
0112 # e.g.
0113 # /**
0114 #  * my_function - does my stuff
0115 #  * @my_arg: its mine damnit
0116 #  *
0117 #  * Does my stuff explained.
0118 #  */
0119 #
0120 #  or, could also use:
0121 # /**
0122 #  * my_function - does my stuff
0123 #  * @my_arg: its mine damnit
0124 #  * Description: Does my stuff explained.
0125 #  */
0126 # etc.
0127 #
0128 # Besides functions you can also write documentation for structs, unions,
0129 # enums and typedefs. Instead of the function name you must write the name
0130 # of the declaration;  the struct/union/enum/typedef must always precede
0131 # the name. Nesting of declarations is not supported.
0132 # Use the argument mechanism to document members or constants.
0133 # e.g.
0134 # /**
0135 #  * struct my_struct - short description
0136 #  * @a: first member
0137 #  * @b: second member
0138 #  *
0139 #  * Longer description
0140 #  */
0141 # struct my_struct {
0142 #     int a;
0143 #     int b;
0144 # /* private: */
0145 #     int c;
0146 # };
0147 #
0148 # All descriptions can be multiline, except the short function description.
0149 #
0150 # For really longs structs, you can also describe arguments inside the
0151 # body of the struct.
0152 # eg.
0153 # /**
0154 #  * struct my_struct - short description
0155 #  * @a: first member
0156 #  * @b: second member
0157 #  *
0158 #  * Longer description
0159 #  */
0160 # struct my_struct {
0161 #     int a;
0162 #     int b;
0163 #     /**
0164 #      * @c: This is longer description of C
0165 #      *
0166 #      * You can use paragraphs to describe arguments
0167 #      * using this method.
0168 #      */
0169 #     int c;
0170 # };
0171 #
0172 # This should be use only for struct/enum members.
0173 #
0174 # You can also add additional sections. When documenting kernel functions you
0175 # should document the "Context:" of the function, e.g. whether the functions
0176 # can be called form interrupts. Unlike other sections you can end it with an
0177 # empty line.
0178 # A non-void function should have a "Return:" section describing the return
0179 # value(s).
0180 # Example-sections should contain the string EXAMPLE so that they are marked
0181 # appropriately in DocBook.
0182 #
0183 # Example:
0184 # /**
0185 #  * user_function - function that can only be called in user context
0186 #  * @a: some argument
0187 #  * Context: !in_interrupt()
0188 #  *
0189 #  * Some description
0190 #  * Example:
0191 #  *    user_function(22);
0192 #  */
0193 # ...
0194 #
0195 #
0196 # All descriptive text is further processed, scanning for the following special
0197 # patterns, which are highlighted appropriately.
0198 #
0199 # 'funcname()' - function
0200 # '$ENVVAR' - environmental variable
0201 # '&struct_name' - name of a structure (up to two words including 'struct')
0202 # '@parameter' - name of a parameter
0203 # '%CONST' - name of a constant.
0204 
0205 ## init lots of data
0206 
0207 
0208 my $errors = 0;
0209 my $warnings = 0;
0210 my $anon_struct_union = 0;
0211 
0212 # match expressions used to find embedded type information
0213 my $type_constant = '\%([-_\w]+)';
0214 my $type_func = '(\w+)\(\)';
0215 my $type_param = '\@(\w+(\.\.\.)?)';
0216 my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
0217 my $type_struct = '\&((struct\s*)*[_\w]+)';
0218 my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
0219 my $type_env = '(\$\w+)';
0220 my $type_enum_full = '\&(enum)\s*([_\w]+)';
0221 my $type_struct_full = '\&(struct)\s*([_\w]+)';
0222 my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
0223 my $type_union_full = '\&(union)\s*([_\w]+)';
0224 my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
0225 my $type_member_func = $type_member . '\(\)';
0226 
0227 # Output conversion substitutions.
0228 #  One for each output format
0229 
0230 # these work fairly well
0231 my @highlights_html = (
0232                        [$type_constant, "<i>\$1</i>"],
0233                        [$type_func, "<b>\$1</b>"],
0234                        [$type_struct_xml, "<i>\$1</i>"],
0235                        [$type_env, "<b><i>\$1</i></b>"],
0236                        [$type_param, "<tt><b>\$1</b></tt>"]
0237                       );
0238 my $local_lt = "\\\\\\\\lt:";
0239 my $local_gt = "\\\\\\\\gt:";
0240 my $blankline_html = $local_lt . "p" . $local_gt;   # was "<p>"
0241 
0242 # html version 5
0243 my @highlights_html5 = (
0244                         [$type_constant, "<span class=\"const\">\$1</span>"],
0245                         [$type_func, "<span class=\"func\">\$1</span>"],
0246                         [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
0247                         [$type_env, "<span class=\"env\">\$1</span>"],
0248                         [$type_param, "<span class=\"param\">\$1</span>]"]
0249                );
0250 my $blankline_html5 = $local_lt . "br /" . $local_gt;
0251 
0252 # XML, docbook format
0253 my @highlights_xml = (
0254                       ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
0255                       [$type_constant, "<constant>\$1</constant>"],
0256                       [$type_struct_xml, "<structname>\$1</structname>"],
0257                       [$type_param, "<parameter>\$1</parameter>"],
0258                       [$type_func, "<function>\$1</function>"],
0259                       [$type_env, "<envar>\$1</envar>"]
0260              );
0261 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
0262 
0263 # gnome, docbook format
0264 my @highlights_gnome = (
0265                         [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
0266                         [$type_func, "<function>\$1</function>"],
0267                         [$type_struct, "<structname>\$1</structname>"],
0268                         [$type_env, "<envar>\$1</envar>"],
0269                         [$type_param, "<parameter>\$1</parameter>" ]
0270                );
0271 my $blankline_gnome = "</para><para>\n";
0272 
0273 # these are pretty rough
0274 my @highlights_man = (
0275                       [$type_constant, "\$1"],
0276                       [$type_func, "\\\\fB\$1\\\\fP"],
0277                       [$type_struct, "\\\\fI\$1\\\\fP"],
0278                       [$type_param, "\\\\fI\$1\\\\fP"]
0279              );
0280 my $blankline_man = "";
0281 
0282 # text-mode
0283 my @highlights_text = (
0284                        [$type_constant, "\$1"],
0285                        [$type_func, "\$1"],
0286                        [$type_struct, "\$1"],
0287                        [$type_param, "\$1"]
0288               );
0289 my $blankline_text = "";
0290 
0291 # rst-mode
0292 my @highlights_rst = (
0293                        [$type_constant, "``\$1``"],
0294                        # Note: need to escape () to avoid func matching later
0295                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
0296                        [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
0297                [$type_fp_param, "**\$1\\\\(\\\\)**"],
0298                        [$type_func, "\\:c\\:func\\:`\$1()`"],
0299                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
0300                        [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
0301                        [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
0302                        [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
0303                        # in rst this can refer to any type
0304                        [$type_struct, "\\:c\\:type\\:`\$1`"],
0305                        [$type_param, "**\$1**"]
0306               );
0307 my $blankline_rst = "\n";
0308 
0309 # list mode
0310 my @highlights_list = (
0311                        [$type_constant, "\$1"],
0312                        [$type_func, "\$1"],
0313                        [$type_struct, "\$1"],
0314                        [$type_param, "\$1"]
0315               );
0316 my $blankline_list = "";
0317 
0318 # read arguments
0319 if ($#ARGV == -1) {
0320     usage();
0321 }
0322 
0323 my $kernelversion;
0324 my $dohighlight = "";
0325 
0326 my $verbose = 0;
0327 my $output_mode = "man";
0328 my $output_preformatted = 0;
0329 my $no_doc_sections = 0;
0330 my $enable_lineno = 0;
0331 my @highlights = @highlights_man;
0332 my $blankline = $blankline_man;
0333 my $modulename = "Kernel API";
0334 
0335 use constant {
0336     OUTPUT_ALL          => 0, # output all symbols and doc sections
0337     OUTPUT_INCLUDE      => 1, # output only specified symbols
0338     OUTPUT_EXCLUDE      => 2, # output everything except specified symbols
0339     OUTPUT_EXPORTED     => 3, # output exported symbols
0340     OUTPUT_INTERNAL     => 4, # output non-exported symbols
0341 };
0342 my $output_selection = OUTPUT_ALL;
0343 my $show_not_found = 0;
0344 
0345 my @export_file_list;
0346 
0347 my @build_time;
0348 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
0349     (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
0350     @build_time = gmtime($seconds);
0351 } else {
0352     @build_time = localtime;
0353 }
0354 
0355 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
0356         'July', 'August', 'September', 'October',
0357         'November', 'December')[$build_time[4]] .
0358   " " . ($build_time[5]+1900);
0359 
0360 # Essentially these are globals.
0361 # They probably want to be tidied up, made more localised or something.
0362 # CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
0363 # could cause "use of undefined value" or other bugs.
0364 my ($function, %function_table, %parametertypes, $declaration_purpose);
0365 my $declaration_start_line;
0366 my ($type, $declaration_name, $return_type);
0367 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
0368 
0369 if (defined($ENV{'KBUILD_VERBOSE'})) {
0370     $verbose = "$ENV{'KBUILD_VERBOSE'}";
0371 }
0372 
0373 # Generated docbook code is inserted in a template at a point where
0374 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
0375 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
0376 # We keep track of number of generated entries and generate a dummy
0377 # if needs be to ensure the expanded template can be postprocessed
0378 # into html.
0379 my $section_counter = 0;
0380 
0381 my $lineprefix="";
0382 
0383 # Parser states
0384 use constant {
0385     STATE_NORMAL        => 0, # normal code
0386     STATE_NAME          => 1, # looking for function name
0387     STATE_FIELD         => 2, # scanning field start
0388     STATE_PROTO         => 3, # scanning prototype
0389     STATE_DOCBLOCK      => 4, # documentation block
0390     STATE_INLINE        => 5, # gathering documentation outside main block
0391 };
0392 my $state;
0393 my $in_doc_sect;
0394 
0395 # Inline documentation state
0396 use constant {
0397     STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
0398     STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
0399     STATE_INLINE_TEXT   => 2, # looking for member documentation
0400     STATE_INLINE_END    => 3, # done
0401     STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
0402                               # Spit a warning as it's not
0403                               # proper kernel-doc and ignore the rest.
0404 };
0405 my $inline_doc_state;
0406 
0407 #declaration types: can be
0408 # 'function', 'struct', 'union', 'enum', 'typedef'
0409 my $decl_type;
0410 
0411 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
0412 my $doc_end = '\*/';
0413 my $doc_com = '\s*\*\s*';
0414 my $doc_com_body = '\s*\* ?';
0415 my $doc_decl = $doc_com . '(\w+)';
0416 # @params and a strictly limited set of supported section names
0417 my $doc_sect = $doc_com . 
0418     '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
0419 my $doc_content = $doc_com_body . '(.*)';
0420 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
0421 my $doc_inline_start = '^\s*/\*\*\s*$';
0422 my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
0423 my $doc_inline_end = '^\s*\*/\s*$';
0424 my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
0425 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
0426 
0427 my %parameterdescs;
0428 my %parameterdesc_start_lines;
0429 my @parameterlist;
0430 my %sections;
0431 my @sectionlist;
0432 my %section_start_lines;
0433 my $sectcheck;
0434 my $struct_actual;
0435 
0436 my $contents = "";
0437 my $new_start_line = 0;
0438 
0439 # the canonical section names. see also $doc_sect above.
0440 my $section_default = "Description";    # default section
0441 my $section_intro = "Introduction";
0442 my $section = $section_default;
0443 my $section_context = "Context";
0444 my $section_return = "Return";
0445 
0446 my $undescribed = "-- undescribed --";
0447 
0448 reset_state();
0449 
0450 while ($ARGV[0] =~ m/^-(.*)/) {
0451     my $cmd = shift @ARGV;
0452     if ($cmd eq "-html") {
0453     $output_mode = "html";
0454     @highlights = @highlights_html;
0455     $blankline = $blankline_html;
0456     } elsif ($cmd eq "-html5") {
0457     $output_mode = "html5";
0458     @highlights = @highlights_html5;
0459     $blankline = $blankline_html5;
0460     } elsif ($cmd eq "-man") {
0461     $output_mode = "man";
0462     @highlights = @highlights_man;
0463     $blankline = $blankline_man;
0464     } elsif ($cmd eq "-text") {
0465     $output_mode = "text";
0466     @highlights = @highlights_text;
0467     $blankline = $blankline_text;
0468     } elsif ($cmd eq "-rst") {
0469     $output_mode = "rst";
0470     @highlights = @highlights_rst;
0471     $blankline = $blankline_rst;
0472     } elsif ($cmd eq "-docbook") {
0473     $output_mode = "xml";
0474     @highlights = @highlights_xml;
0475     $blankline = $blankline_xml;
0476     } elsif ($cmd eq "-list") {
0477     $output_mode = "list";
0478     @highlights = @highlights_list;
0479     $blankline = $blankline_list;
0480     } elsif ($cmd eq "-gnome") {
0481     $output_mode = "gnome";
0482     @highlights = @highlights_gnome;
0483     $blankline = $blankline_gnome;
0484     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
0485     $modulename = shift @ARGV;
0486     } elsif ($cmd eq "-function") { # to only output specific functions
0487     $output_selection = OUTPUT_INCLUDE;
0488     $function = shift @ARGV;
0489     $function_table{$function} = 1;
0490     } elsif ($cmd eq "-nofunction") { # output all except specific functions
0491     $output_selection = OUTPUT_EXCLUDE;
0492     $function = shift @ARGV;
0493     $function_table{$function} = 1;
0494     } elsif ($cmd eq "-export") { # only exported symbols
0495     $output_selection = OUTPUT_EXPORTED;
0496     %function_table = ();
0497     } elsif ($cmd eq "-internal") { # only non-exported symbols
0498     $output_selection = OUTPUT_INTERNAL;
0499     %function_table = ();
0500     } elsif ($cmd eq "-export-file") {
0501     my $file = shift @ARGV;
0502     push(@export_file_list, $file);
0503     } elsif ($cmd eq "-v") {
0504     $verbose = 1;
0505     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
0506     usage();
0507     } elsif ($cmd eq '-no-doc-sections') {
0508         $no_doc_sections = 1;
0509     } elsif ($cmd eq '-enable-lineno') {
0510         $enable_lineno = 1;
0511     } elsif ($cmd eq '-show-not-found') {
0512     $show_not_found = 1;
0513     }
0514 }
0515 
0516 # continue execution near EOF;
0517 
0518 # get kernel version from env
0519 sub get_kernel_version() {
0520     my $version = 'unknown kernel version';
0521 
0522     if (defined($ENV{'KERNELVERSION'})) {
0523     $version = $ENV{'KERNELVERSION'};
0524     }
0525     return $version;
0526 }
0527 
0528 #
0529 sub print_lineno {
0530     my $lineno = shift;
0531     if ($enable_lineno && defined($lineno)) {
0532         print "#define LINENO " . $lineno . "\n";
0533     }
0534 }
0535 ##
0536 # dumps section contents to arrays/hashes intended for that purpose.
0537 #
0538 sub dump_section {
0539     my $file = shift;
0540     my $name = shift;
0541     my $contents = join "\n", @_;
0542 
0543     if ($name =~ m/$type_param/) {
0544     $name = $1;
0545     $parameterdescs{$name} = $contents;
0546     $sectcheck = $sectcheck . $name . " ";
0547         $parameterdesc_start_lines{$name} = $new_start_line;
0548         $new_start_line = 0;
0549     } elsif ($name eq "@\.\.\.") {
0550     $name = "...";
0551     $parameterdescs{$name} = $contents;
0552     $sectcheck = $sectcheck . $name . " ";
0553         $parameterdesc_start_lines{$name} = $new_start_line;
0554         $new_start_line = 0;
0555     } else {
0556     if (defined($sections{$name}) && ($sections{$name} ne "")) {
0557         # Only warn on user specified duplicate section names.
0558         if ($name ne $section_default) {
0559         print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
0560         ++$warnings;
0561         }
0562         $sections{$name} .= $contents;
0563     } else {
0564         $sections{$name} = $contents;
0565         push @sectionlist, $name;
0566             $section_start_lines{$name} = $new_start_line;
0567             $new_start_line = 0;
0568     }
0569     }
0570 }
0571 
0572 ##
0573 # dump DOC: section after checking that it should go out
0574 #
0575 sub dump_doc_section {
0576     my $file = shift;
0577     my $name = shift;
0578     my $contents = join "\n", @_;
0579 
0580     if ($no_doc_sections) {
0581         return;
0582     }
0583 
0584     if (($output_selection == OUTPUT_ALL) ||
0585     ($output_selection == OUTPUT_INCLUDE &&
0586      defined($function_table{$name})) ||
0587     ($output_selection == OUTPUT_EXCLUDE &&
0588      !defined($function_table{$name})))
0589     {
0590     dump_section($file, $name, $contents);
0591     output_blockhead({'sectionlist' => \@sectionlist,
0592               'sections' => \%sections,
0593               'module' => $modulename,
0594               'content-only' => ($output_selection != OUTPUT_ALL), });
0595     }
0596 }
0597 
0598 ##
0599 # output function
0600 #
0601 # parameterdescs, a hash.
0602 #  function => "function name"
0603 #  parameterlist => @list of parameters
0604 #  parameterdescs => %parameter descriptions
0605 #  sectionlist => @list of sections
0606 #  sections => %section descriptions
0607 #
0608 
0609 sub output_highlight {
0610     my $contents = join "\n",@_;
0611     my $line;
0612 
0613 #   DEBUG
0614 #   if (!defined $contents) {
0615 #   use Carp;
0616 #   confess "output_highlight got called with no args?\n";
0617 #   }
0618 
0619     if ($output_mode eq "html" || $output_mode eq "html5" ||
0620     $output_mode eq "xml") {
0621     $contents = local_unescape($contents);
0622     # convert data read & converted thru xml_escape() into &xyz; format:
0623     $contents =~ s/\\\\\\/\&/g;
0624     }
0625 #   print STDERR "contents b4:$contents\n";
0626     eval $dohighlight;
0627     die $@ if $@;
0628 #   print STDERR "contents af:$contents\n";
0629 
0630 #   strip whitespaces when generating html5
0631     if ($output_mode eq "html5") {
0632     $contents =~ s/^\s+//;
0633     $contents =~ s/\s+$//;
0634     }
0635     foreach $line (split "\n", $contents) {
0636     if (! $output_preformatted) {
0637         $line =~ s/^\s*//;
0638     }
0639     if ($line eq ""){
0640         if (! $output_preformatted) {
0641         print $lineprefix, local_unescape($blankline);
0642         }
0643     } else {
0644         $line =~ s/\\\\\\/\&/g;
0645         if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
0646         print "\\&$line";
0647         } else {
0648         print $lineprefix, $line;
0649         }
0650     }
0651     print "\n";
0652     }
0653 }
0654 
0655 # output sections in html
0656 sub output_section_html(%) {
0657     my %args = %{$_[0]};
0658     my $section;
0659 
0660     foreach $section (@{$args{'sectionlist'}}) {
0661     print "<h3>$section</h3>\n";
0662     print "<blockquote>\n";
0663     output_highlight($args{'sections'}{$section});
0664     print "</blockquote>\n";
0665     }
0666 }
0667 
0668 # output enum in html
0669 sub output_enum_html(%) {
0670     my %args = %{$_[0]};
0671     my ($parameter);
0672     my $count;
0673     print "<h2>enum " . $args{'enum'} . "</h2>\n";
0674 
0675     print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
0676     $count = 0;
0677     foreach $parameter (@{$args{'parameterlist'}}) {
0678     print " <b>" . $parameter . "</b>";
0679     if ($count != $#{$args{'parameterlist'}}) {
0680         $count++;
0681         print ",\n";
0682     }
0683     print "<br>";
0684     }
0685     print "};<br>\n";
0686 
0687     print "<h3>Constants</h3>\n";
0688     print "<dl>\n";
0689     foreach $parameter (@{$args{'parameterlist'}}) {
0690     print "<dt><b>" . $parameter . "</b>\n";
0691     print "<dd>";
0692     output_highlight($args{'parameterdescs'}{$parameter});
0693     }
0694     print "</dl>\n";
0695     output_section_html(@_);
0696     print "<hr>\n";
0697 }
0698 
0699 # output typedef in html
0700 sub output_typedef_html(%) {
0701     my %args = %{$_[0]};
0702     my ($parameter);
0703     my $count;
0704     print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
0705 
0706     print "<b>typedef " . $args{'typedef'} . "</b>\n";
0707     output_section_html(@_);
0708     print "<hr>\n";
0709 }
0710 
0711 # output struct in html
0712 sub output_struct_html(%) {
0713     my %args = %{$_[0]};
0714     my ($parameter);
0715 
0716     print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
0717     print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
0718     foreach $parameter (@{$args{'parameterlist'}}) {
0719     if ($parameter =~ /^#/) {
0720         print "$parameter<br>\n";
0721         next;
0722     }
0723     my $parameter_name = $parameter;
0724     $parameter_name =~ s/\[.*//;
0725 
0726     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
0727     $type = $args{'parametertypes'}{$parameter};
0728     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
0729         # pointer-to-function
0730         print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
0731     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
0732         # bitfield
0733         print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
0734     } else {
0735         print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
0736     }
0737     }
0738     print "};<br>\n";
0739 
0740     print "<h3>Members</h3>\n";
0741     print "<dl>\n";
0742     foreach $parameter (@{$args{'parameterlist'}}) {
0743     ($parameter =~ /^#/) && next;
0744 
0745     my $parameter_name = $parameter;
0746     $parameter_name =~ s/\[.*//;
0747 
0748     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
0749     print "<dt><b>" . $parameter . "</b>\n";
0750     print "<dd>";
0751     output_highlight($args{'parameterdescs'}{$parameter_name});
0752     }
0753     print "</dl>\n";
0754     output_section_html(@_);
0755     print "<hr>\n";
0756 }
0757 
0758 # output function in html
0759 sub output_function_html(%) {
0760     my %args = %{$_[0]};
0761     my ($parameter, $section);
0762     my $count;
0763 
0764     print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
0765     print "<i>" . $args{'functiontype'} . "</i>\n";
0766     print "<b>" . $args{'function'} . "</b>\n";
0767     print "(";
0768     $count = 0;
0769     foreach $parameter (@{$args{'parameterlist'}}) {
0770     $type = $args{'parametertypes'}{$parameter};
0771     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
0772         # pointer-to-function
0773         print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
0774     } else {
0775         print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
0776     }
0777     if ($count != $#{$args{'parameterlist'}}) {
0778         $count++;
0779         print ",\n";
0780     }
0781     }
0782     print ")\n";
0783 
0784     print "<h3>Arguments</h3>\n";
0785     print "<dl>\n";
0786     foreach $parameter (@{$args{'parameterlist'}}) {
0787     my $parameter_name = $parameter;
0788     $parameter_name =~ s/\[.*//;
0789 
0790     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
0791     print "<dt><b>" . $parameter . "</b>\n";
0792     print "<dd>";
0793     output_highlight($args{'parameterdescs'}{$parameter_name});
0794     }
0795     print "</dl>\n";
0796     output_section_html(@_);
0797     print "<hr>\n";
0798 }
0799 
0800 # output DOC: block header in html
0801 sub output_blockhead_html(%) {
0802     my %args = %{$_[0]};
0803     my ($parameter, $section);
0804     my $count;
0805 
0806     foreach $section (@{$args{'sectionlist'}}) {
0807     print "<h3>$section</h3>\n";
0808     print "<ul>\n";
0809     output_highlight($args{'sections'}{$section});
0810     print "</ul>\n";
0811     }
0812     print "<hr>\n";
0813 }
0814 
0815 # output sections in html5
0816 sub output_section_html5(%) {
0817     my %args = %{$_[0]};
0818     my $section;
0819 
0820     foreach $section (@{$args{'sectionlist'}}) {
0821     print "<section>\n";
0822     print "<h1>$section</h1>\n";
0823     print "<p>\n";
0824     output_highlight($args{'sections'}{$section});
0825     print "</p>\n";
0826     print "</section>\n";
0827     }
0828 }
0829 
0830 # output enum in html5
0831 sub output_enum_html5(%) {
0832     my %args = %{$_[0]};
0833     my ($parameter);
0834     my $count;
0835     my $html5id;
0836 
0837     $html5id = $args{'enum'};
0838     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
0839     print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
0840     print "<h1>enum " . $args{'enum'} . "</h1>\n";
0841     print "<ol class=\"code\">\n";
0842     print "<li>";
0843     print "<span class=\"keyword\">enum</span> ";
0844     print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
0845     print "</li>\n";
0846     $count = 0;
0847     foreach $parameter (@{$args{'parameterlist'}}) {
0848     print "<li class=\"indent\">";
0849     print "<span class=\"param\">" . $parameter . "</span>";
0850     if ($count != $#{$args{'parameterlist'}}) {
0851         $count++;
0852         print ",";
0853     }
0854     print "</li>\n";
0855     }
0856     print "<li>};</li>\n";
0857     print "</ol>\n";
0858 
0859     print "<section>\n";
0860     print "<h1>Constants</h1>\n";
0861     print "<dl>\n";
0862     foreach $parameter (@{$args{'parameterlist'}}) {
0863     print "<dt>" . $parameter . "</dt>\n";
0864     print "<dd>";
0865     output_highlight($args{'parameterdescs'}{$parameter});
0866     print "</dd>\n";
0867     }
0868     print "</dl>\n";
0869     print "</section>\n";
0870     output_section_html5(@_);
0871     print "</article>\n";
0872 }
0873 
0874 # output typedef in html5
0875 sub output_typedef_html5(%) {
0876     my %args = %{$_[0]};
0877     my ($parameter);
0878     my $count;
0879     my $html5id;
0880 
0881     $html5id = $args{'typedef'};
0882     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
0883     print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
0884     print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
0885 
0886     print "<ol class=\"code\">\n";
0887     print "<li>";
0888     print "<span class=\"keyword\">typedef</span> ";
0889     print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
0890     print "</li>\n";
0891     print "</ol>\n";
0892     output_section_html5(@_);
0893     print "</article>\n";
0894 }
0895 
0896 # output struct in html5
0897 sub output_struct_html5(%) {
0898     my %args = %{$_[0]};
0899     my ($parameter);
0900     my $html5id;
0901 
0902     $html5id = $args{'struct'};
0903     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
0904     print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
0905     print "<hgroup>\n";
0906     print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
0907     print "<h2>". $args{'purpose'} . "</h2>\n";
0908     print "</hgroup>\n";
0909     print "<ol class=\"code\">\n";
0910     print "<li>";
0911     print "<span class=\"type\">" . $args{'type'} . "</span> ";
0912     print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
0913     print "</li>\n";
0914     foreach $parameter (@{$args{'parameterlist'}}) {
0915     print "<li class=\"indent\">";
0916     if ($parameter =~ /^#/) {
0917         print "<span class=\"param\">" . $parameter ."</span>\n";
0918         print "</li>\n";
0919         next;
0920     }
0921     my $parameter_name = $parameter;
0922     $parameter_name =~ s/\[.*//;
0923 
0924     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
0925     $type = $args{'parametertypes'}{$parameter};
0926     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
0927         # pointer-to-function
0928         print "<span class=\"type\">$1</span> ";
0929         print "<span class=\"param\">$parameter</span>";
0930         print "<span class=\"type\">)</span> ";
0931         print "(<span class=\"args\">$2</span>);";
0932     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
0933         # bitfield
0934         print "<span class=\"type\">$1</span> ";
0935         print "<span class=\"param\">$parameter</span>";
0936         print "<span class=\"bits\">$2</span>;";
0937     } else {
0938         print "<span class=\"type\">$type</span> ";
0939         print "<span class=\"param\">$parameter</span>;";
0940     }
0941     print "</li>\n";
0942     }
0943     print "<li>};</li>\n";
0944     print "</ol>\n";
0945 
0946     print "<section>\n";
0947     print "<h1>Members</h1>\n";
0948     print "<dl>\n";
0949     foreach $parameter (@{$args{'parameterlist'}}) {
0950     ($parameter =~ /^#/) && next;
0951 
0952     my $parameter_name = $parameter;
0953     $parameter_name =~ s/\[.*//;
0954 
0955     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
0956     print "<dt>" . $parameter . "</dt>\n";
0957     print "<dd>";
0958     output_highlight($args{'parameterdescs'}{$parameter_name});
0959     print "</dd>\n";
0960     }
0961     print "</dl>\n";
0962     print "</section>\n";
0963     output_section_html5(@_);
0964     print "</article>\n";
0965 }
0966 
0967 # output function in html5
0968 sub output_function_html5(%) {
0969     my %args = %{$_[0]};
0970     my ($parameter, $section);
0971     my $count;
0972     my $html5id;
0973 
0974     $html5id = $args{'function'};
0975     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
0976     print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
0977     print "<hgroup>\n";
0978     print "<h1>" . $args{'function'} . "</h1>";
0979     print "<h2>" . $args{'purpose'} . "</h2>\n";
0980     print "</hgroup>\n";
0981     print "<ol class=\"code\">\n";
0982     print "<li>";
0983     print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
0984     print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
0985     print "</li>";
0986     $count = 0;
0987     foreach $parameter (@{$args{'parameterlist'}}) {
0988     print "<li class=\"indent\">";
0989     $type = $args{'parametertypes'}{$parameter};
0990     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
0991         # pointer-to-function
0992         print "<span class=\"type\">$1</span> ";
0993         print "<span class=\"param\">$parameter</span>";
0994         print "<span class=\"type\">)</span> ";
0995         print "(<span class=\"args\">$2</span>)";
0996     } else {
0997         print "<span class=\"type\">$type</span> ";
0998         print "<span class=\"param\">$parameter</span>";
0999     }
1000     if ($count != $#{$args{'parameterlist'}}) {
1001         $count++;
1002         print ",";
1003     }
1004     print "</li>\n";
1005     }
1006     print "<li>)</li>\n";
1007     print "</ol>\n";
1008 
1009     print "<section>\n";
1010     print "<h1>Arguments</h1>\n";
1011     print "<p>\n";
1012     print "<dl>\n";
1013     foreach $parameter (@{$args{'parameterlist'}}) {
1014     my $parameter_name = $parameter;
1015     $parameter_name =~ s/\[.*//;
1016 
1017     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1018     print "<dt>" . $parameter . "</dt>\n";
1019     print "<dd>";
1020     output_highlight($args{'parameterdescs'}{$parameter_name});
1021     print "</dd>\n";
1022     }
1023     print "</dl>\n";
1024     print "</section>\n";
1025     output_section_html5(@_);
1026     print "</article>\n";
1027 }
1028 
1029 # output DOC: block header in html5
1030 sub output_blockhead_html5(%) {
1031     my %args = %{$_[0]};
1032     my ($parameter, $section);
1033     my $count;
1034     my $html5id;
1035 
1036     foreach $section (@{$args{'sectionlist'}}) {
1037     $html5id = $section;
1038     $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
1039     print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
1040     print "<h1>$section</h1>\n";
1041     print "<p>\n";
1042     output_highlight($args{'sections'}{$section});
1043     print "</p>\n";
1044     }
1045     print "</article>\n";
1046 }
1047 
1048 sub output_section_xml(%) {
1049     my %args = %{$_[0]};
1050     my $section;
1051     # print out each section
1052     $lineprefix="   ";
1053     foreach $section (@{$args{'sectionlist'}}) {
1054     print "<refsect1>\n";
1055     print "<title>$section</title>\n";
1056     if ($section =~ m/EXAMPLE/i) {
1057         print "<informalexample><programlisting>\n";
1058         $output_preformatted = 1;
1059     } else {
1060         print "<para>\n";
1061     }
1062     output_highlight($args{'sections'}{$section});
1063     $output_preformatted = 0;
1064     if ($section =~ m/EXAMPLE/i) {
1065         print "</programlisting></informalexample>\n";
1066     } else {
1067         print "</para>\n";
1068     }
1069     print "</refsect1>\n";
1070     }
1071 }
1072 
1073 # output function in XML DocBook
1074 sub output_function_xml(%) {
1075     my %args = %{$_[0]};
1076     my ($parameter, $section);
1077     my $count;
1078     my $id;
1079 
1080     $id = "API-" . $args{'function'};
1081     $id =~ s/[^A-Za-z0-9]/-/g;
1082 
1083     print "<refentry id=\"$id\">\n";
1084     print "<refentryinfo>\n";
1085     print " <title>LINUX</title>\n";
1086     print " <productname>Kernel Hackers Manual</productname>\n";
1087     print " <date>$man_date</date>\n";
1088     print "</refentryinfo>\n";
1089     print "<refmeta>\n";
1090     print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
1091     print " <manvolnum>9</manvolnum>\n";
1092     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1093     print "</refmeta>\n";
1094     print "<refnamediv>\n";
1095     print " <refname>" . $args{'function'} . "</refname>\n";
1096     print " <refpurpose>\n";
1097     print "  ";
1098     output_highlight ($args{'purpose'});
1099     print " </refpurpose>\n";
1100     print "</refnamediv>\n";
1101 
1102     print "<refsynopsisdiv>\n";
1103     print " <title>Synopsis</title>\n";
1104     print "  <funcsynopsis><funcprototype>\n";
1105     print "   <funcdef>" . $args{'functiontype'} . " ";
1106     print "<function>" . $args{'function'} . " </function></funcdef>\n";
1107 
1108     $count = 0;
1109     if ($#{$args{'parameterlist'}} >= 0) {
1110     foreach $parameter (@{$args{'parameterlist'}}) {
1111         $type = $args{'parametertypes'}{$parameter};
1112         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1113         # pointer-to-function
1114         print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
1115         print "     <funcparams>$2</funcparams></paramdef>\n";
1116         } else {
1117         print "   <paramdef>" . $type;
1118         print " <parameter>$parameter</parameter></paramdef>\n";
1119         }
1120     }
1121     } else {
1122     print "  <void/>\n";
1123     }
1124     print "  </funcprototype></funcsynopsis>\n";
1125     print "</refsynopsisdiv>\n";
1126 
1127     # print parameters
1128     print "<refsect1>\n <title>Arguments</title>\n";
1129     if ($#{$args{'parameterlist'}} >= 0) {
1130     print " <variablelist>\n";
1131     foreach $parameter (@{$args{'parameterlist'}}) {
1132         my $parameter_name = $parameter;
1133         $parameter_name =~ s/\[.*//;
1134 
1135         print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
1136         print "   <listitem>\n    <para>\n";
1137         $lineprefix="     ";
1138         output_highlight($args{'parameterdescs'}{$parameter_name});
1139         print "    </para>\n   </listitem>\n  </varlistentry>\n";
1140     }
1141     print " </variablelist>\n";
1142     } else {
1143     print " <para>\n  None\n </para>\n";
1144     }
1145     print "</refsect1>\n";
1146 
1147     output_section_xml(@_);
1148     print "</refentry>\n\n";
1149 }
1150 
1151 # output struct in XML DocBook
1152 sub output_struct_xml(%) {
1153     my %args = %{$_[0]};
1154     my ($parameter, $section);
1155     my $id;
1156 
1157     $id = "API-struct-" . $args{'struct'};
1158     $id =~ s/[^A-Za-z0-9]/-/g;
1159 
1160     print "<refentry id=\"$id\">\n";
1161     print "<refentryinfo>\n";
1162     print " <title>LINUX</title>\n";
1163     print " <productname>Kernel Hackers Manual</productname>\n";
1164     print " <date>$man_date</date>\n";
1165     print "</refentryinfo>\n";
1166     print "<refmeta>\n";
1167     print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1168     print " <manvolnum>9</manvolnum>\n";
1169     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1170     print "</refmeta>\n";
1171     print "<refnamediv>\n";
1172     print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1173     print " <refpurpose>\n";
1174     print "  ";
1175     output_highlight ($args{'purpose'});
1176     print " </refpurpose>\n";
1177     print "</refnamediv>\n";
1178 
1179     print "<refsynopsisdiv>\n";
1180     print " <title>Synopsis</title>\n";
1181     print "  <programlisting>\n";
1182     print $args{'type'} . " " . $args{'struct'} . " {\n";
1183     foreach $parameter (@{$args{'parameterlist'}}) {
1184     if ($parameter =~ /^#/) {
1185         my $prm = $parameter;
1186         # convert data read & converted thru xml_escape() into &xyz; format:
1187         # This allows us to have #define macros interspersed in a struct.
1188         $prm =~ s/\\\\\\/\&/g;
1189         print "$prm\n";
1190         next;
1191     }
1192 
1193     my $parameter_name = $parameter;
1194     $parameter_name =~ s/\[.*//;
1195 
1196     defined($args{'parameterdescs'}{$parameter_name}) || next;
1197     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1198     $type = $args{'parametertypes'}{$parameter};
1199     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1200         # pointer-to-function
1201         print "  $1 $parameter) ($2);\n";
1202     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1203         # bitfield
1204         print "  $1 $parameter$2;\n";
1205     } else {
1206         print "  " . $type . " " . $parameter . ";\n";
1207     }
1208     }
1209     print "};";
1210     print "  </programlisting>\n";
1211     print "</refsynopsisdiv>\n";
1212 
1213     print " <refsect1>\n";
1214     print "  <title>Members</title>\n";
1215 
1216     if ($#{$args{'parameterlist'}} >= 0) {
1217     print "  <variablelist>\n";
1218     foreach $parameter (@{$args{'parameterlist'}}) {
1219       ($parameter =~ /^#/) && next;
1220 
1221       my $parameter_name = $parameter;
1222       $parameter_name =~ s/\[.*//;
1223 
1224       defined($args{'parameterdescs'}{$parameter_name}) || next;
1225       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1226       print "    <varlistentry>";
1227       print "      <term>$parameter</term>\n";
1228       print "      <listitem><para>\n";
1229       output_highlight($args{'parameterdescs'}{$parameter_name});
1230       print "      </para></listitem>\n";
1231       print "    </varlistentry>\n";
1232     }
1233     print "  </variablelist>\n";
1234     } else {
1235     print " <para>\n  None\n </para>\n";
1236     }
1237     print " </refsect1>\n";
1238 
1239     output_section_xml(@_);
1240 
1241     print "</refentry>\n\n";
1242 }
1243 
1244 # output enum in XML DocBook
1245 sub output_enum_xml(%) {
1246     my %args = %{$_[0]};
1247     my ($parameter, $section);
1248     my $count;
1249     my $id;
1250 
1251     $id = "API-enum-" . $args{'enum'};
1252     $id =~ s/[^A-Za-z0-9]/-/g;
1253 
1254     print "<refentry id=\"$id\">\n";
1255     print "<refentryinfo>\n";
1256     print " <title>LINUX</title>\n";
1257     print " <productname>Kernel Hackers Manual</productname>\n";
1258     print " <date>$man_date</date>\n";
1259     print "</refentryinfo>\n";
1260     print "<refmeta>\n";
1261     print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1262     print " <manvolnum>9</manvolnum>\n";
1263     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1264     print "</refmeta>\n";
1265     print "<refnamediv>\n";
1266     print " <refname>enum " . $args{'enum'} . "</refname>\n";
1267     print " <refpurpose>\n";
1268     print "  ";
1269     output_highlight ($args{'purpose'});
1270     print " </refpurpose>\n";
1271     print "</refnamediv>\n";
1272 
1273     print "<refsynopsisdiv>\n";
1274     print " <title>Synopsis</title>\n";
1275     print "  <programlisting>\n";
1276     print "enum " . $args{'enum'} . " {\n";
1277     $count = 0;
1278     foreach $parameter (@{$args{'parameterlist'}}) {
1279     print "  $parameter";
1280     if ($count != $#{$args{'parameterlist'}}) {
1281         $count++;
1282         print ",";
1283     }
1284     print "\n";
1285     }
1286     print "};";
1287     print "  </programlisting>\n";
1288     print "</refsynopsisdiv>\n";
1289 
1290     print "<refsect1>\n";
1291     print " <title>Constants</title>\n";
1292     print "  <variablelist>\n";
1293     foreach $parameter (@{$args{'parameterlist'}}) {
1294       my $parameter_name = $parameter;
1295       $parameter_name =~ s/\[.*//;
1296 
1297       print "    <varlistentry>";
1298       print "      <term>$parameter</term>\n";
1299       print "      <listitem><para>\n";
1300       output_highlight($args{'parameterdescs'}{$parameter_name});
1301       print "      </para></listitem>\n";
1302       print "    </varlistentry>\n";
1303     }
1304     print "  </variablelist>\n";
1305     print "</refsect1>\n";
1306 
1307     output_section_xml(@_);
1308 
1309     print "</refentry>\n\n";
1310 }
1311 
1312 # output typedef in XML DocBook
1313 sub output_typedef_xml(%) {
1314     my %args = %{$_[0]};
1315     my ($parameter, $section);
1316     my $id;
1317 
1318     $id = "API-typedef-" . $args{'typedef'};
1319     $id =~ s/[^A-Za-z0-9]/-/g;
1320 
1321     print "<refentry id=\"$id\">\n";
1322     print "<refentryinfo>\n";
1323     print " <title>LINUX</title>\n";
1324     print " <productname>Kernel Hackers Manual</productname>\n";
1325     print " <date>$man_date</date>\n";
1326     print "</refentryinfo>\n";
1327     print "<refmeta>\n";
1328     print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1329     print " <manvolnum>9</manvolnum>\n";
1330     print "</refmeta>\n";
1331     print "<refnamediv>\n";
1332     print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1333     print " <refpurpose>\n";
1334     print "  ";
1335     output_highlight ($args{'purpose'});
1336     print " </refpurpose>\n";
1337     print "</refnamediv>\n";
1338 
1339     print "<refsynopsisdiv>\n";
1340     print " <title>Synopsis</title>\n";
1341     print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1342     print "</refsynopsisdiv>\n";
1343 
1344     output_section_xml(@_);
1345 
1346     print "</refentry>\n\n";
1347 }
1348 
1349 # output in XML DocBook
1350 sub output_blockhead_xml(%) {
1351     my %args = %{$_[0]};
1352     my ($parameter, $section);
1353     my $count;
1354 
1355     my $id = $args{'module'};
1356     $id =~ s/[^A-Za-z0-9]/-/g;
1357 
1358     # print out each section
1359     $lineprefix="   ";
1360     foreach $section (@{$args{'sectionlist'}}) {
1361     if (!$args{'content-only'}) {
1362         print "<refsect1>\n <title>$section</title>\n";
1363     }
1364     if ($section =~ m/EXAMPLE/i) {
1365         print "<example><para>\n";
1366         $output_preformatted = 1;
1367     } else {
1368         print "<para>\n";
1369     }
1370     output_highlight($args{'sections'}{$section});
1371     $output_preformatted = 0;
1372     if ($section =~ m/EXAMPLE/i) {
1373         print "</para></example>\n";
1374     } else {
1375         print "</para>";
1376     }
1377     if (!$args{'content-only'}) {
1378         print "\n</refsect1>\n";
1379     }
1380     }
1381 
1382     print "\n\n";
1383 }
1384 
1385 # output in XML DocBook
1386 sub output_function_gnome {
1387     my %args = %{$_[0]};
1388     my ($parameter, $section);
1389     my $count;
1390     my $id;
1391 
1392     $id = $args{'module'} . "-" . $args{'function'};
1393     $id =~ s/[^A-Za-z0-9]/-/g;
1394 
1395     print "<sect2>\n";
1396     print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1397 
1398     print "  <funcsynopsis>\n";
1399     print "   <funcdef>" . $args{'functiontype'} . " ";
1400     print "<function>" . $args{'function'} . " ";
1401     print "</function></funcdef>\n";
1402 
1403     $count = 0;
1404     if ($#{$args{'parameterlist'}} >= 0) {
1405     foreach $parameter (@{$args{'parameterlist'}}) {
1406         $type = $args{'parametertypes'}{$parameter};
1407         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1408         # pointer-to-function
1409         print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
1410         print "     <funcparams>$2</funcparams></paramdef>\n";
1411         } else {
1412         print "   <paramdef>" . $type;
1413         print " <parameter>$parameter</parameter></paramdef>\n";
1414         }
1415     }
1416     } else {
1417     print "  <void>\n";
1418     }
1419     print "  </funcsynopsis>\n";
1420     if ($#{$args{'parameterlist'}} >= 0) {
1421     print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1422     print "<tgroup cols=\"2\">\n";
1423     print "<colspec colwidth=\"2*\">\n";
1424     print "<colspec colwidth=\"8*\">\n";
1425     print "<tbody>\n";
1426     foreach $parameter (@{$args{'parameterlist'}}) {
1427         my $parameter_name = $parameter;
1428         $parameter_name =~ s/\[.*//;
1429 
1430         print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1431         print "   <entry>\n";
1432         $lineprefix="     ";
1433         output_highlight($args{'parameterdescs'}{$parameter_name});
1434         print "    </entry></row>\n";
1435     }
1436     print " </tbody></tgroup></informaltable>\n";
1437     } else {
1438     print " <para>\n  None\n </para>\n";
1439     }
1440 
1441     # print out each section
1442     $lineprefix="   ";
1443     foreach $section (@{$args{'sectionlist'}}) {
1444     print "<simplesect>\n <title>$section</title>\n";
1445     if ($section =~ m/EXAMPLE/i) {
1446         print "<example><programlisting>\n";
1447         $output_preformatted = 1;
1448     } else {
1449     }
1450     print "<para>\n";
1451     output_highlight($args{'sections'}{$section});
1452     $output_preformatted = 0;
1453     print "</para>\n";
1454     if ($section =~ m/EXAMPLE/i) {
1455         print "</programlisting></example>\n";
1456     } else {
1457     }
1458     print " </simplesect>\n";
1459     }
1460 
1461     print "</sect2>\n\n";
1462 }
1463 
1464 ##
1465 # output function in man
1466 sub output_function_man(%) {
1467     my %args = %{$_[0]};
1468     my ($parameter, $section);
1469     my $count;
1470 
1471     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1472 
1473     print ".SH NAME\n";
1474     print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1475 
1476     print ".SH SYNOPSIS\n";
1477     if ($args{'functiontype'} ne "") {
1478     print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1479     } else {
1480     print ".B \"" . $args{'function'} . "\n";
1481     }
1482     $count = 0;
1483     my $parenth = "(";
1484     my $post = ",";
1485     foreach my $parameter (@{$args{'parameterlist'}}) {
1486     if ($count == $#{$args{'parameterlist'}}) {
1487         $post = ");";
1488     }
1489     $type = $args{'parametertypes'}{$parameter};
1490     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1491         # pointer-to-function
1492         print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1493     } else {
1494         $type =~ s/([^\*])$/$1 /;
1495         print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1496     }
1497     $count++;
1498     $parenth = "";
1499     }
1500 
1501     print ".SH ARGUMENTS\n";
1502     foreach $parameter (@{$args{'parameterlist'}}) {
1503     my $parameter_name = $parameter;
1504     $parameter_name =~ s/\[.*//;
1505 
1506     print ".IP \"" . $parameter . "\" 12\n";
1507     output_highlight($args{'parameterdescs'}{$parameter_name});
1508     }
1509     foreach $section (@{$args{'sectionlist'}}) {
1510     print ".SH \"", uc $section, "\"\n";
1511     output_highlight($args{'sections'}{$section});
1512     }
1513 }
1514 
1515 ##
1516 # output enum in man
1517 sub output_enum_man(%) {
1518     my %args = %{$_[0]};
1519     my ($parameter, $section);
1520     my $count;
1521 
1522     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1523 
1524     print ".SH NAME\n";
1525     print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1526 
1527     print ".SH SYNOPSIS\n";
1528     print "enum " . $args{'enum'} . " {\n";
1529     $count = 0;
1530     foreach my $parameter (@{$args{'parameterlist'}}) {
1531     print ".br\n.BI \"    $parameter\"\n";
1532     if ($count == $#{$args{'parameterlist'}}) {
1533         print "\n};\n";
1534         last;
1535     }
1536     else {
1537         print ", \n.br\n";
1538     }
1539     $count++;
1540     }
1541 
1542     print ".SH Constants\n";
1543     foreach $parameter (@{$args{'parameterlist'}}) {
1544     my $parameter_name = $parameter;
1545     $parameter_name =~ s/\[.*//;
1546 
1547     print ".IP \"" . $parameter . "\" 12\n";
1548     output_highlight($args{'parameterdescs'}{$parameter_name});
1549     }
1550     foreach $section (@{$args{'sectionlist'}}) {
1551     print ".SH \"$section\"\n";
1552     output_highlight($args{'sections'}{$section});
1553     }
1554 }
1555 
1556 ##
1557 # output struct in man
1558 sub output_struct_man(%) {
1559     my %args = %{$_[0]};
1560     my ($parameter, $section);
1561 
1562     print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1563 
1564     print ".SH NAME\n";
1565     print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1566 
1567     print ".SH SYNOPSIS\n";
1568     print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1569 
1570     foreach my $parameter (@{$args{'parameterlist'}}) {
1571     if ($parameter =~ /^#/) {
1572         print ".BI \"$parameter\"\n.br\n";
1573         next;
1574     }
1575     my $parameter_name = $parameter;
1576     $parameter_name =~ s/\[.*//;
1577 
1578     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1579     $type = $args{'parametertypes'}{$parameter};
1580     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1581         # pointer-to-function
1582         print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1583     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1584         # bitfield
1585         print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1586     } else {
1587         $type =~ s/([^\*])$/$1 /;
1588         print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1589     }
1590     print "\n.br\n";
1591     }
1592     print "};\n.br\n";
1593 
1594     print ".SH Members\n";
1595     foreach $parameter (@{$args{'parameterlist'}}) {
1596     ($parameter =~ /^#/) && next;
1597 
1598     my $parameter_name = $parameter;
1599     $parameter_name =~ s/\[.*//;
1600 
1601     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1602     print ".IP \"" . $parameter . "\" 12\n";
1603     output_highlight($args{'parameterdescs'}{$parameter_name});
1604     }
1605     foreach $section (@{$args{'sectionlist'}}) {
1606     print ".SH \"$section\"\n";
1607     output_highlight($args{'sections'}{$section});
1608     }
1609 }
1610 
1611 ##
1612 # output typedef in man
1613 sub output_typedef_man(%) {
1614     my %args = %{$_[0]};
1615     my ($parameter, $section);
1616 
1617     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1618 
1619     print ".SH NAME\n";
1620     print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1621 
1622     foreach $section (@{$args{'sectionlist'}}) {
1623     print ".SH \"$section\"\n";
1624     output_highlight($args{'sections'}{$section});
1625     }
1626 }
1627 
1628 sub output_blockhead_man(%) {
1629     my %args = %{$_[0]};
1630     my ($parameter, $section);
1631     my $count;
1632 
1633     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1634 
1635     foreach $section (@{$args{'sectionlist'}}) {
1636     print ".SH \"$section\"\n";
1637     output_highlight($args{'sections'}{$section});
1638     }
1639 }
1640 
1641 ##
1642 # output in text
1643 sub output_function_text(%) {
1644     my %args = %{$_[0]};
1645     my ($parameter, $section);
1646     my $start;
1647 
1648     print "Name:\n\n";
1649     print $args{'function'} . " - " . $args{'purpose'} . "\n";
1650 
1651     print "\nSynopsis:\n\n";
1652     if ($args{'functiontype'} ne "") {
1653     $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1654     } else {
1655     $start = $args{'function'} . " (";
1656     }
1657     print $start;
1658 
1659     my $count = 0;
1660     foreach my $parameter (@{$args{'parameterlist'}}) {
1661     $type = $args{'parametertypes'}{$parameter};
1662     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1663         # pointer-to-function
1664         print $1 . $parameter . ") (" . $2;
1665     } else {
1666         print $type . " " . $parameter;
1667     }
1668     if ($count != $#{$args{'parameterlist'}}) {
1669         $count++;
1670         print ",\n";
1671         print " " x length($start);
1672     } else {
1673         print ");\n\n";
1674     }
1675     }
1676 
1677     print "Arguments:\n\n";
1678     foreach $parameter (@{$args{'parameterlist'}}) {
1679     my $parameter_name = $parameter;
1680     $parameter_name =~ s/\[.*//;
1681 
1682     print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1683     }
1684     output_section_text(@_);
1685 }
1686 
1687 #output sections in text
1688 sub output_section_text(%) {
1689     my %args = %{$_[0]};
1690     my $section;
1691 
1692     print "\n";
1693     foreach $section (@{$args{'sectionlist'}}) {
1694     print "$section:\n\n";
1695     output_highlight($args{'sections'}{$section});
1696     }
1697     print "\n\n";
1698 }
1699 
1700 # output enum in text
1701 sub output_enum_text(%) {
1702     my %args = %{$_[0]};
1703     my ($parameter);
1704     my $count;
1705     print "Enum:\n\n";
1706 
1707     print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1708     print "enum " . $args{'enum'} . " {\n";
1709     $count = 0;
1710     foreach $parameter (@{$args{'parameterlist'}}) {
1711     print "\t$parameter";
1712     if ($count != $#{$args{'parameterlist'}}) {
1713         $count++;
1714         print ",";
1715     }
1716     print "\n";
1717     }
1718     print "};\n\n";
1719 
1720     print "Constants:\n\n";
1721     foreach $parameter (@{$args{'parameterlist'}}) {
1722     print "$parameter\n\t";
1723     print $args{'parameterdescs'}{$parameter} . "\n";
1724     }
1725 
1726     output_section_text(@_);
1727 }
1728 
1729 # output typedef in text
1730 sub output_typedef_text(%) {
1731     my %args = %{$_[0]};
1732     my ($parameter);
1733     my $count;
1734     print "Typedef:\n\n";
1735 
1736     print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1737     output_section_text(@_);
1738 }
1739 
1740 # output struct as text
1741 sub output_struct_text(%) {
1742     my %args = %{$_[0]};
1743     my ($parameter);
1744 
1745     print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1746     print $args{'type'} . " " . $args{'struct'} . " {\n";
1747     foreach $parameter (@{$args{'parameterlist'}}) {
1748     if ($parameter =~ /^#/) {
1749         print "$parameter\n";
1750         next;
1751     }
1752 
1753     my $parameter_name = $parameter;
1754     $parameter_name =~ s/\[.*//;
1755 
1756     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1757     $type = $args{'parametertypes'}{$parameter};
1758     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1759         # pointer-to-function
1760         print "\t$1 $parameter) ($2);\n";
1761     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1762         # bitfield
1763         print "\t$1 $parameter$2;\n";
1764     } else {
1765         print "\t" . $type . " " . $parameter . ";\n";
1766     }
1767     }
1768     print "};\n\n";
1769 
1770     print "Members:\n\n";
1771     foreach $parameter (@{$args{'parameterlist'}}) {
1772     ($parameter =~ /^#/) && next;
1773 
1774     my $parameter_name = $parameter;
1775     $parameter_name =~ s/\[.*//;
1776 
1777     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1778     print "$parameter\n\t";
1779     print $args{'parameterdescs'}{$parameter_name} . "\n";
1780     }
1781     print "\n";
1782     output_section_text(@_);
1783 }
1784 
1785 sub output_blockhead_text(%) {
1786     my %args = %{$_[0]};
1787     my ($parameter, $section);
1788 
1789     foreach $section (@{$args{'sectionlist'}}) {
1790     print " $section:\n";
1791     print "    -> ";
1792     output_highlight($args{'sections'}{$section});
1793     }
1794 }
1795 
1796 ##
1797 # output in restructured text
1798 #
1799 
1800 #
1801 # This could use some work; it's used to output the DOC: sections, and
1802 # starts by putting out the name of the doc section itself, but that tends
1803 # to duplicate a header already in the template file.
1804 #
1805 sub output_blockhead_rst(%) {
1806     my %args = %{$_[0]};
1807     my ($parameter, $section);
1808 
1809     foreach $section (@{$args{'sectionlist'}}) {
1810     if ($output_selection != OUTPUT_INCLUDE) {
1811         print "**$section**\n\n";
1812     }
1813         print_lineno($section_start_lines{$section});
1814     output_highlight_rst($args{'sections'}{$section});
1815     print "\n";
1816     }
1817 }
1818 
1819 sub output_highlight_rst {
1820     my $contents = join "\n",@_;
1821     my $line;
1822 
1823     # undo the evil effects of xml_escape() earlier
1824     $contents = xml_unescape($contents);
1825 
1826     eval $dohighlight;
1827     die $@ if $@;
1828 
1829     foreach $line (split "\n", $contents) {
1830     print $lineprefix . $line . "\n";
1831     }
1832 }
1833 
1834 sub output_function_rst(%) {
1835     my %args = %{$_[0]};
1836     my ($parameter, $section);
1837     my $oldprefix = $lineprefix;
1838     my $start = "";
1839 
1840     if ($args{'typedef'}) {
1841     print ".. c:type:: ". $args{'function'} . "\n\n";
1842     print_lineno($declaration_start_line);
1843     print "   **Typedef**: ";
1844     $lineprefix = "";
1845     output_highlight_rst($args{'purpose'});
1846     $start = "\n\n**Syntax**\n\n  ``";
1847     } else {
1848     print ".. c:function:: ";
1849     }
1850     if ($args{'functiontype'} ne "") {
1851     $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
1852     } else {
1853     $start .= $args{'function'} . " (";
1854     }
1855     print $start;
1856 
1857     my $count = 0;
1858     foreach my $parameter (@{$args{'parameterlist'}}) {
1859     if ($count ne 0) {
1860         print ", ";
1861     }
1862     $count++;
1863     $type = $args{'parametertypes'}{$parameter};
1864 
1865     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1866         # pointer-to-function
1867         print $1 . $parameter . ") (" . $2;
1868     } else {
1869         print $type . " " . $parameter;
1870     }
1871     }
1872     if ($args{'typedef'}) {
1873     print ");``\n\n";
1874     } else {
1875     print ")\n\n";
1876     print_lineno($declaration_start_line);
1877     $lineprefix = "   ";
1878     output_highlight_rst($args{'purpose'});
1879     print "\n";
1880     }
1881 
1882     print "**Parameters**\n\n";
1883     $lineprefix = "  ";
1884     foreach $parameter (@{$args{'parameterlist'}}) {
1885     my $parameter_name = $parameter;
1886     #$parameter_name =~ s/\[.*//;
1887     $type = $args{'parametertypes'}{$parameter};
1888 
1889     if ($type ne "") {
1890         print "``$type $parameter``\n";
1891     } else {
1892         print "``$parameter``\n";
1893     }
1894 
1895         print_lineno($parameterdesc_start_lines{$parameter_name});
1896 
1897     if (defined($args{'parameterdescs'}{$parameter_name}) &&
1898         $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1899         output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1900     } else {
1901         print "  *undescribed*\n";
1902     }
1903     print "\n";
1904     }
1905 
1906     $lineprefix = $oldprefix;
1907     output_section_rst(@_);
1908 }
1909 
1910 sub output_section_rst(%) {
1911     my %args = %{$_[0]};
1912     my $section;
1913     my $oldprefix = $lineprefix;
1914     $lineprefix = "";
1915 
1916     foreach $section (@{$args{'sectionlist'}}) {
1917     print "**$section**\n\n";
1918         print_lineno($section_start_lines{$section});
1919     output_highlight_rst($args{'sections'}{$section});
1920     print "\n";
1921     }
1922     print "\n";
1923     $lineprefix = $oldprefix;
1924 }
1925 
1926 sub output_enum_rst(%) {
1927     my %args = %{$_[0]};
1928     my ($parameter);
1929     my $oldprefix = $lineprefix;
1930     my $count;
1931     my $name = "enum " . $args{'enum'};
1932 
1933     print "\n\n.. c:type:: " . $name . "\n\n";
1934     print_lineno($declaration_start_line);
1935     $lineprefix = "   ";
1936     output_highlight_rst($args{'purpose'});
1937     print "\n";
1938 
1939     print "**Constants**\n\n";
1940     $lineprefix = "  ";
1941     foreach $parameter (@{$args{'parameterlist'}}) {
1942     print "``$parameter``\n";
1943     if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1944         output_highlight_rst($args{'parameterdescs'}{$parameter});
1945     } else {
1946         print "  *undescribed*\n";
1947     }
1948     print "\n";
1949     }
1950 
1951     $lineprefix = $oldprefix;
1952     output_section_rst(@_);
1953 }
1954 
1955 sub output_typedef_rst(%) {
1956     my %args = %{$_[0]};
1957     my ($parameter);
1958     my $oldprefix = $lineprefix;
1959     my $name = "typedef " . $args{'typedef'};
1960 
1961     print "\n\n.. c:type:: " . $name . "\n\n";
1962     print_lineno($declaration_start_line);
1963     $lineprefix = "   ";
1964     output_highlight_rst($args{'purpose'});
1965     print "\n";
1966 
1967     $lineprefix = $oldprefix;
1968     output_section_rst(@_);
1969 }
1970 
1971 sub output_struct_rst(%) {
1972     my %args = %{$_[0]};
1973     my ($parameter);
1974     my $oldprefix = $lineprefix;
1975     my $name = $args{'type'} . " " . $args{'struct'};
1976 
1977     print "\n\n.. c:type:: " . $name . "\n\n";
1978     print_lineno($declaration_start_line);
1979     $lineprefix = "   ";
1980     output_highlight_rst($args{'purpose'});
1981     print "\n";
1982 
1983     print "**Definition**\n\n";
1984     print "::\n\n";
1985     print "  " . $args{'type'} . " " . $args{'struct'} . " {\n";
1986     foreach $parameter (@{$args{'parameterlist'}}) {
1987     if ($parameter =~ /^#/) {
1988         print "  " . "$parameter\n";
1989         next;
1990     }
1991 
1992     my $parameter_name = $parameter;
1993     $parameter_name =~ s/\[.*//;
1994 
1995     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1996     $type = $args{'parametertypes'}{$parameter};
1997     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1998         # pointer-to-function
1999         print "    $1 $parameter) ($2);\n";
2000     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
2001         # bitfield
2002         print "    $1 $parameter$2;\n";
2003     } else {
2004         print "    " . $type . " " . $parameter . ";\n";
2005     }
2006     }
2007     print "  };\n\n";
2008 
2009     print "**Members**\n\n";
2010     $lineprefix = "  ";
2011     foreach $parameter (@{$args{'parameterlist'}}) {
2012     ($parameter =~ /^#/) && next;
2013 
2014     my $parameter_name = $parameter;
2015     $parameter_name =~ s/\[.*//;
2016 
2017     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
2018     $type = $args{'parametertypes'}{$parameter};
2019         print_lineno($parameterdesc_start_lines{$parameter_name});
2020     print "``" . $parameter . "``\n";
2021     output_highlight_rst($args{'parameterdescs'}{$parameter_name});
2022     print "\n";
2023     }
2024     print "\n";
2025 
2026     $lineprefix = $oldprefix;
2027     output_section_rst(@_);
2028 }
2029 
2030 
2031 ## list mode output functions
2032 
2033 sub output_function_list(%) {
2034     my %args = %{$_[0]};
2035 
2036     print $args{'function'} . "\n";
2037 }
2038 
2039 # output enum in list
2040 sub output_enum_list(%) {
2041     my %args = %{$_[0]};
2042     print $args{'enum'} . "\n";
2043 }
2044 
2045 # output typedef in list
2046 sub output_typedef_list(%) {
2047     my %args = %{$_[0]};
2048     print $args{'typedef'} . "\n";
2049 }
2050 
2051 # output struct as list
2052 sub output_struct_list(%) {
2053     my %args = %{$_[0]};
2054 
2055     print $args{'struct'} . "\n";
2056 }
2057 
2058 sub output_blockhead_list(%) {
2059     my %args = %{$_[0]};
2060     my ($parameter, $section);
2061 
2062     foreach $section (@{$args{'sectionlist'}}) {
2063     print "DOC: $section\n";
2064     }
2065 }
2066 
2067 ##
2068 # generic output function for all types (function, struct/union, typedef, enum);
2069 # calls the generated, variable output_ function name based on
2070 # functype and output_mode
2071 sub output_declaration {
2072     no strict 'refs';
2073     my $name = shift;
2074     my $functype = shift;
2075     my $func = "output_${functype}_$output_mode";
2076     if (($output_selection == OUTPUT_ALL) ||
2077     (($output_selection == OUTPUT_INCLUDE ||
2078       $output_selection == OUTPUT_EXPORTED) &&
2079      defined($function_table{$name})) ||
2080     (($output_selection == OUTPUT_EXCLUDE ||
2081       $output_selection == OUTPUT_INTERNAL) &&
2082      !($functype eq "function" && defined($function_table{$name}))))
2083     {
2084     &$func(@_);
2085     $section_counter++;
2086     }
2087 }
2088 
2089 ##
2090 # generic output function - calls the right one based on current output mode.
2091 sub output_blockhead {
2092     no strict 'refs';
2093     my $func = "output_blockhead_" . $output_mode;
2094     &$func(@_);
2095     $section_counter++;
2096 }
2097 
2098 ##
2099 # takes a declaration (struct, union, enum, typedef) and
2100 # invokes the right handler. NOT called for functions.
2101 sub dump_declaration($$) {
2102     no strict 'refs';
2103     my ($prototype, $file) = @_;
2104     my $func = "dump_" . $decl_type;
2105     &$func(@_);
2106 }
2107 
2108 sub dump_union($$) {
2109     dump_struct(@_);
2110 }
2111 
2112 sub dump_struct($$) {
2113     my $x = shift;
2114     my $file = shift;
2115     my $nested;
2116 
2117     if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2118     #my $decl_type = $1;
2119     $declaration_name = $2;
2120     my $members = $3;
2121 
2122     # ignore embedded structs or unions
2123     $members =~ s/({.*})//g;
2124     $nested = $1;
2125 
2126     # ignore members marked private:
2127     $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2128     $members =~ s/\/\*\s*private:.*//gosi;
2129     # strip comments:
2130     $members =~ s/\/\*.*?\*\///gos;
2131     $nested =~ s/\/\*.*?\*\///gos;
2132     # strip kmemcheck_bitfield_{begin,end}.*;
2133     $members =~ s/kmemcheck_bitfield_.*?;//gos;
2134     # strip attributes
2135     $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2136     $members =~ s/__aligned\s*\([^;]*\)//gos;
2137     $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2138     # replace DECLARE_BITMAP
2139     $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2140 
2141     create_parameterlist($members, ';', $file);
2142     check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
2143 
2144     output_declaration($declaration_name,
2145                'struct',
2146                {'struct' => $declaration_name,
2147                 'module' => $modulename,
2148                 'parameterlist' => \@parameterlist,
2149                 'parameterdescs' => \%parameterdescs,
2150                 'parametertypes' => \%parametertypes,
2151                 'sectionlist' => \@sectionlist,
2152                 'sections' => \%sections,
2153                 'purpose' => $declaration_purpose,
2154                 'type' => $decl_type
2155                });
2156     }
2157     else {
2158     print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2159     ++$errors;
2160     }
2161 }
2162 
2163 sub dump_enum($$) {
2164     my $x = shift;
2165     my $file = shift;
2166 
2167     $x =~ s@/\*.*?\*/@@gos; # strip comments.
2168     # strip #define macros inside enums
2169     $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2170 
2171     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2172     $declaration_name = $1;
2173     my $members = $2;
2174 
2175     foreach my $arg (split ',', $members) {
2176         $arg =~ s/^\s*(\w+).*/$1/;
2177         push @parameterlist, $arg;
2178         if (!$parameterdescs{$arg}) {
2179         $parameterdescs{$arg} = $undescribed;
2180         print STDERR "${file}:$.: warning: Enum value '$arg' ".
2181             "not described in enum '$declaration_name'\n";
2182         }
2183 
2184     }
2185 
2186     output_declaration($declaration_name,
2187                'enum',
2188                {'enum' => $declaration_name,
2189                 'module' => $modulename,
2190                 'parameterlist' => \@parameterlist,
2191                 'parameterdescs' => \%parameterdescs,
2192                 'sectionlist' => \@sectionlist,
2193                 'sections' => \%sections,
2194                 'purpose' => $declaration_purpose
2195                });
2196     }
2197     else {
2198     print STDERR "${file}:$.: error: Cannot parse enum!\n";
2199     ++$errors;
2200     }
2201 }
2202 
2203 sub dump_typedef($$) {
2204     my $x = shift;
2205     my $file = shift;
2206 
2207     $x =~ s@/\*.*?\*/@@gos; # strip comments.
2208 
2209     # Parse function prototypes
2210     if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
2211     $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
2212 
2213     # Function typedefs
2214     $return_type = $1;
2215     $declaration_name = $2;
2216     my $args = $3;
2217 
2218     create_parameterlist($args, ',', $file);
2219 
2220     output_declaration($declaration_name,
2221                'function',
2222                {'function' => $declaration_name,
2223                 'typedef' => 1,
2224                 'module' => $modulename,
2225                 'functiontype' => $return_type,
2226                 'parameterlist' => \@parameterlist,
2227                 'parameterdescs' => \%parameterdescs,
2228                 'parametertypes' => \%parametertypes,
2229                 'sectionlist' => \@sectionlist,
2230                 'sections' => \%sections,
2231                 'purpose' => $declaration_purpose
2232                });
2233     return;
2234     }
2235 
2236     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2237     $x =~ s/\(*.\)\s*;$/;/;
2238     $x =~ s/\[*.\]\s*;$/;/;
2239     }
2240 
2241     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2242     $declaration_name = $1;
2243 
2244     output_declaration($declaration_name,
2245                'typedef',
2246                {'typedef' => $declaration_name,
2247                 'module' => $modulename,
2248                 'sectionlist' => \@sectionlist,
2249                 'sections' => \%sections,
2250                 'purpose' => $declaration_purpose
2251                });
2252     }
2253     else {
2254     print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2255     ++$errors;
2256     }
2257 }
2258 
2259 sub save_struct_actual($) {
2260     my $actual = shift;
2261 
2262     # strip all spaces from the actual param so that it looks like one string item
2263     $actual =~ s/\s*//g;
2264     $struct_actual = $struct_actual . $actual . " ";
2265 }
2266 
2267 sub create_parameterlist($$$) {
2268     my $args = shift;
2269     my $splitter = shift;
2270     my $file = shift;
2271     my $type;
2272     my $param;
2273 
2274     # temporarily replace commas inside function pointer definition
2275     while ($args =~ /(\([^\),]+),/) {
2276     $args =~ s/(\([^\),]+),/$1#/g;
2277     }
2278 
2279     foreach my $arg (split($splitter, $args)) {
2280     # strip comments
2281     $arg =~ s/\/\*.*\*\///;
2282     # strip leading/trailing spaces
2283     $arg =~ s/^\s*//;
2284     $arg =~ s/\s*$//;
2285     $arg =~ s/\s+/ /;
2286 
2287     if ($arg =~ /^#/) {
2288         # Treat preprocessor directive as a typeless variable just to fill
2289         # corresponding data structures "correctly". Catch it later in
2290         # output_* subs.
2291         push_parameter($arg, "", $file);
2292     } elsif ($arg =~ m/\(.+\)\s*\(/) {
2293         # pointer-to-function
2294         $arg =~ tr/#/,/;
2295         $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2296         $param = $1;
2297         $type = $arg;
2298         $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2299         save_struct_actual($param);
2300         push_parameter($param, $type, $file);
2301     } elsif ($arg) {
2302         $arg =~ s/\s*:\s*/:/g;
2303         $arg =~ s/\s*\[/\[/g;
2304 
2305         my @args = split('\s*,\s*', $arg);
2306         if ($args[0] =~ m/\*/) {
2307         $args[0] =~ s/(\*+)\s*/ $1/;
2308         }
2309 
2310         my @first_arg;
2311         if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2312             shift @args;
2313             push(@first_arg, split('\s+', $1));
2314             push(@first_arg, $2);
2315         } else {
2316             @first_arg = split('\s+', shift @args);
2317         }
2318 
2319         unshift(@args, pop @first_arg);
2320         $type = join " ", @first_arg;
2321 
2322         foreach $param (@args) {
2323         if ($param =~ m/^(\*+)\s*(.*)/) {
2324             save_struct_actual($2);
2325             push_parameter($2, "$type $1", $file);
2326         }
2327         elsif ($param =~ m/(.*?):(\d+)/) {
2328             if ($type ne "") { # skip unnamed bit-fields
2329             save_struct_actual($1);
2330             push_parameter($1, "$type:$2", $file)
2331             }
2332         }
2333         else {
2334             save_struct_actual($param);
2335             push_parameter($param, $type, $file);
2336         }
2337         }
2338     }
2339     }
2340 }
2341 
2342 sub push_parameter($$$) {
2343     my $param = shift;
2344     my $type = shift;
2345     my $file = shift;
2346 
2347     if (($anon_struct_union == 1) && ($type eq "") &&
2348         ($param eq "}")) {
2349         return;     # ignore the ending }; from anon. struct/union
2350     }
2351 
2352     $anon_struct_union = 0;
2353     my $param_name = $param;
2354     $param_name =~ s/\[.*//;
2355 
2356     if ($type eq "" && $param =~ /\.\.\.$/)
2357     {
2358         if (!$param =~ /\w\.\.\.$/) {
2359           # handles unnamed variable parameters
2360           $param = "...";
2361         }
2362         if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2363         $parameterdescs{$param} = "variable arguments";
2364         }
2365     }
2366     elsif ($type eq "" && ($param eq "" or $param eq "void"))
2367     {
2368         $param="void";
2369         $parameterdescs{void} = "no arguments";
2370     }
2371     elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2372     # handle unnamed (anonymous) union or struct:
2373     {
2374         $type = $param;
2375         $param = "{unnamed_" . $param . "}";
2376         $parameterdescs{$param} = "anonymous\n";
2377         $anon_struct_union = 1;
2378     }
2379 
2380     # warn if parameter has no description
2381     # (but ignore ones starting with # as these are not parameters
2382     # but inline preprocessor statements);
2383     # also ignore unnamed structs/unions;
2384     if (!$anon_struct_union) {
2385     if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2386 
2387         $parameterdescs{$param_name} = $undescribed;
2388 
2389         if (($type eq 'function') || ($type eq 'enum')) {
2390         print STDERR "${file}:$.: warning: Function parameter ".
2391             "or member '$param' not " .
2392             "described in '$declaration_name'\n";
2393         }
2394         print STDERR "${file}:$.: warning:" .
2395              " No description found for parameter '$param'\n";
2396         ++$warnings;
2397     }
2398     }
2399 
2400     $param = xml_escape($param);
2401 
2402     # strip spaces from $param so that it is one continuous string
2403     # on @parameterlist;
2404     # this fixes a problem where check_sections() cannot find
2405     # a parameter like "addr[6 + 2]" because it actually appears
2406     # as "addr[6", "+", "2]" on the parameter list;
2407     # but it's better to maintain the param string unchanged for output,
2408     # so just weaken the string compare in check_sections() to ignore
2409     # "[blah" in a parameter string;
2410     ###$param =~ s/\s*//g;
2411     push @parameterlist, $param;
2412     $parametertypes{$param} = $type;
2413 }
2414 
2415 sub check_sections($$$$$$) {
2416     my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2417     my @sects = split ' ', $sectcheck;
2418     my @prms = split ' ', $prmscheck;
2419     my $err;
2420     my ($px, $sx);
2421     my $prm_clean;      # strip trailing "[array size]" and/or beginning "*"
2422 
2423     foreach $sx (0 .. $#sects) {
2424         $err = 1;
2425         foreach $px (0 .. $#prms) {
2426             $prm_clean = $prms[$px];
2427             $prm_clean =~ s/\[.*\]//;
2428             $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2429             # ignore array size in a parameter string;
2430             # however, the original param string may contain
2431             # spaces, e.g.:  addr[6 + 2]
2432             # and this appears in @prms as "addr[6" since the
2433             # parameter list is split at spaces;
2434             # hence just ignore "[..." for the sections check;
2435             $prm_clean =~ s/\[.*//;
2436 
2437             ##$prm_clean =~ s/^\**//;
2438             if ($prm_clean eq $sects[$sx]) {
2439                 $err = 0;
2440                 last;
2441             }
2442         }
2443         if ($err) {
2444             if ($decl_type eq "function") {
2445                 print STDERR "${file}:$.: warning: " .
2446                     "Excess function parameter " .
2447                     "'$sects[$sx]' " .
2448                     "description in '$decl_name'\n";
2449                 ++$warnings;
2450             } else {
2451                 if ($nested !~ m/\Q$sects[$sx]\E/) {
2452                     print STDERR "${file}:$.: warning: " .
2453                     "Excess struct/union/enum/typedef member " .
2454                     "'$sects[$sx]' " .
2455                     "description in '$decl_name'\n";
2456                     ++$warnings;
2457                 }
2458             }
2459         }
2460     }
2461 }
2462 
2463 ##
2464 # Checks the section describing the return value of a function.
2465 sub check_return_section {
2466         my $file = shift;
2467         my $declaration_name = shift;
2468         my $return_type = shift;
2469 
2470         # Ignore an empty return type (It's a macro)
2471         # Ignore functions with a "void" return type. (But don't ignore "void *")
2472         if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2473                 return;
2474         }
2475 
2476         if (!defined($sections{$section_return}) ||
2477             $sections{$section_return} eq "") {
2478                 print STDERR "${file}:$.: warning: " .
2479                         "No description found for return value of " .
2480                         "'$declaration_name'\n";
2481                 ++$warnings;
2482         }
2483 }
2484 
2485 ##
2486 # takes a function prototype and the name of the current file being
2487 # processed and spits out all the details stored in the global
2488 # arrays/hashes.
2489 sub dump_function($$) {
2490     my $prototype = shift;
2491     my $file = shift;
2492     my $noret = 0;
2493 
2494     $prototype =~ s/^static +//;
2495     $prototype =~ s/^extern +//;
2496     $prototype =~ s/^asmlinkage +//;
2497     $prototype =~ s/^inline +//;
2498     $prototype =~ s/^__inline__ +//;
2499     $prototype =~ s/^__inline +//;
2500     $prototype =~ s/^__always_inline +//;
2501     $prototype =~ s/^noinline +//;
2502     $prototype =~ s/__init +//;
2503     $prototype =~ s/__init_or_module +//;
2504     $prototype =~ s/__meminit +//;
2505     $prototype =~ s/__must_check +//;
2506     $prototype =~ s/__weak +//;
2507     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2508     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2509 
2510     # Yes, this truly is vile.  We are looking for:
2511     # 1. Return type (may be nothing if we're looking at a macro)
2512     # 2. Function name
2513     # 3. Function parameters.
2514     #
2515     # All the while we have to watch out for function pointer parameters
2516     # (which IIRC is what the two sections are for), C types (these
2517     # regexps don't even start to express all the possibilities), and
2518     # so on.
2519     #
2520     # If you mess with these regexps, it's a good idea to check that
2521     # the following functions' documentation still comes out right:
2522     # - parport_register_device (function pointer parameters)
2523     # - atomic_set (macro)
2524     # - pci_match_device, __copy_to_user (long return type)
2525 
2526     if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2527         # This is an object-like macro, it has no return type and no parameter
2528         # list.
2529         # Function-like macros are not allowed to have spaces between
2530         # declaration_name and opening parenthesis (notice the \s+).
2531         $return_type = $1;
2532         $declaration_name = $2;
2533         $noret = 1;
2534     } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2535     $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2536     $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2537     $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2538     $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2539     $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2540     $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2541     $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2542     $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2543     $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2544     $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2545     $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2546     $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2547     $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2548     $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2549     $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2550     $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
2551     $return_type = $1;
2552     $declaration_name = $2;
2553     my $args = $3;
2554 
2555     create_parameterlist($args, ',', $file);
2556     } else {
2557     print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2558     return;
2559     }
2560 
2561     my $prms = join " ", @parameterlist;
2562     check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2563 
2564         # This check emits a lot of warnings at the moment, because many
2565         # functions don't have a 'Return' doc section. So until the number
2566         # of warnings goes sufficiently down, the check is only performed in
2567         # verbose mode.
2568         # TODO: always perform the check.
2569         if ($verbose && !$noret) {
2570                 check_return_section($file, $declaration_name, $return_type);
2571         }
2572 
2573     output_declaration($declaration_name,
2574                'function',
2575                {'function' => $declaration_name,
2576             'module' => $modulename,
2577             'functiontype' => $return_type,
2578             'parameterlist' => \@parameterlist,
2579             'parameterdescs' => \%parameterdescs,
2580             'parametertypes' => \%parametertypes,
2581             'sectionlist' => \@sectionlist,
2582             'sections' => \%sections,
2583             'purpose' => $declaration_purpose
2584                });
2585 }
2586 
2587 sub reset_state {
2588     $function = "";
2589     %parameterdescs = ();
2590     %parametertypes = ();
2591     @parameterlist = ();
2592     %sections = ();
2593     @sectionlist = ();
2594     $sectcheck = "";
2595     $struct_actual = "";
2596     $prototype = "";
2597 
2598     $state = STATE_NORMAL;
2599     $inline_doc_state = STATE_INLINE_NA;
2600 }
2601 
2602 sub tracepoint_munge($) {
2603     my $file = shift;
2604     my $tracepointname = 0;
2605     my $tracepointargs = 0;
2606 
2607     if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2608         $tracepointname = $1;
2609     }
2610     if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2611         $tracepointname = $1;
2612     }
2613     if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2614         $tracepointname = $2;
2615     }
2616     $tracepointname =~ s/^\s+//; #strip leading whitespace
2617     if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2618         $tracepointargs = $1;
2619     }
2620     if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2621         print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2622                  "$prototype\n";
2623     } else {
2624         $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2625     }
2626 }
2627 
2628 sub syscall_munge() {
2629     my $void = 0;
2630 
2631     $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2632 ##  if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2633     if ($prototype =~ m/SYSCALL_DEFINE0/) {
2634         $void = 1;
2635 ##      $prototype = "long sys_$1(void)";
2636     }
2637 
2638     $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2639     if ($prototype =~ m/long (sys_.*?),/) {
2640         $prototype =~ s/,/\(/;
2641     } elsif ($void) {
2642         $prototype =~ s/\)/\(void\)/;
2643     }
2644 
2645     # now delete all of the odd-number commas in $prototype
2646     # so that arg types & arg names don't have a comma between them
2647     my $count = 0;
2648     my $len = length($prototype);
2649     if ($void) {
2650         $len = 0;   # skip the for-loop
2651     }
2652     for (my $ix = 0; $ix < $len; $ix++) {
2653         if (substr($prototype, $ix, 1) eq ',') {
2654             $count++;
2655             if ($count % 2 == 1) {
2656                 substr($prototype, $ix, 1) = ' ';
2657             }
2658         }
2659     }
2660 }
2661 
2662 sub process_proto_function($$) {
2663     my $x = shift;
2664     my $file = shift;
2665 
2666     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2667 
2668     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2669     # do nothing
2670     }
2671     elsif ($x =~ /([^\{]*)/) {
2672     $prototype .= $1;
2673     }
2674 
2675     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2676     $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2677     $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2678     $prototype =~ s@^\s+@@gos; # strip leading spaces
2679     if ($prototype =~ /SYSCALL_DEFINE/) {
2680         syscall_munge();
2681     }
2682     if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2683         $prototype =~ /DEFINE_SINGLE_EVENT/)
2684     {
2685         tracepoint_munge($file);
2686     }
2687     dump_function($prototype, $file);
2688     reset_state();
2689     }
2690 }
2691 
2692 sub process_proto_type($$) {
2693     my $x = shift;
2694     my $file = shift;
2695 
2696     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2697     $x =~ s@^\s+@@gos; # strip leading spaces
2698     $x =~ s@\s+$@@gos; # strip trailing spaces
2699     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2700 
2701     if ($x =~ /^#/) {
2702     # To distinguish preprocessor directive from regular declaration later.
2703     $x .= ";";
2704     }
2705 
2706     while (1) {
2707     if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2708         $prototype .= $1 . $2;
2709         ($2 eq '{') && $brcount++;
2710         ($2 eq '}') && $brcount--;
2711         if (($2 eq ';') && ($brcount == 0)) {
2712         dump_declaration($prototype, $file);
2713         reset_state();
2714         last;
2715         }
2716         $x = $3;
2717     } else {
2718         $prototype .= $x;
2719         last;
2720     }
2721     }
2722 }
2723 
2724 # xml_escape: replace <, >, and & in the text stream;
2725 #
2726 # however, formatting controls that are generated internally/locally in the
2727 # kernel-doc script are not escaped here; instead, they begin life like
2728 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2729 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2730 # just before actual output; (this is done by local_unescape())
2731 sub xml_escape($) {
2732     my $text = shift;
2733     if (($output_mode eq "text") || ($output_mode eq "man")) {
2734         return $text;
2735     }
2736     $text =~ s/\&/\\\\\\amp;/g;
2737     $text =~ s/\</\\\\\\lt;/g;
2738     $text =~ s/\>/\\\\\\gt;/g;
2739     return $text;
2740 }
2741 
2742 # xml_unescape: reverse the effects of xml_escape
2743 sub xml_unescape($) {
2744     my $text = shift;
2745     if (($output_mode eq "text") || ($output_mode eq "man")) {
2746         return $text;
2747     }
2748     $text =~ s/\\\\\\amp;/\&/g;
2749     $text =~ s/\\\\\\lt;/</g;
2750     $text =~ s/\\\\\\gt;/>/g;
2751     return $text;
2752 }
2753 
2754 # convert local escape strings to html
2755 # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
2756 sub local_unescape($) {
2757     my $text = shift;
2758     if (($output_mode eq "text") || ($output_mode eq "man")) {
2759         return $text;
2760     }
2761     $text =~ s/\\\\\\\\lt:/</g;
2762     $text =~ s/\\\\\\\\gt:/>/g;
2763     return $text;
2764 }
2765 
2766 sub map_filename($) {
2767     my $file;
2768     my ($orig_file) = @_;
2769 
2770     if (defined($ENV{'SRCTREE'})) {
2771     $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2772     } else {
2773     $file = $orig_file;
2774     }
2775 
2776     if (defined($source_map{$file})) {
2777     $file = $source_map{$file};
2778     }
2779 
2780     return $file;
2781 }
2782 
2783 sub process_export_file($) {
2784     my ($orig_file) = @_;
2785     my $file = map_filename($orig_file);
2786 
2787     if (!open(IN,"<$file")) {
2788     print STDERR "Error: Cannot open file $file\n";
2789     ++$errors;
2790     return;
2791     }
2792 
2793     while (<IN>) {
2794     if (/$export_symbol/) {
2795         $function_table{$2} = 1;
2796     }
2797     }
2798 
2799     close(IN);
2800 }
2801 
2802 sub process_file($) {
2803     my $file;
2804     my $identifier;
2805     my $func;
2806     my $descr;
2807     my $in_purpose = 0;
2808     my $initial_section_counter = $section_counter;
2809     my ($orig_file) = @_;
2810     my $leading_space;
2811 
2812     $file = map_filename($orig_file);
2813 
2814     if (!open(IN,"<$file")) {
2815     print STDERR "Error: Cannot open file $file\n";
2816     ++$errors;
2817     return;
2818     }
2819 
2820     $. = 1;
2821 
2822     $section_counter = 0;
2823     while (<IN>) {
2824     while (s/\\\s*$//) {
2825         $_ .= <IN>;
2826     }
2827     if ($state == STATE_NORMAL) {
2828         if (/$doc_start/o) {
2829         $state = STATE_NAME;    # next line is always the function name
2830         $in_doc_sect = 0;
2831         $declaration_start_line = $. + 1;
2832         }
2833     } elsif ($state == STATE_NAME) {# this line is the function name (always)
2834         if (/$doc_block/o) {
2835         $state = STATE_DOCBLOCK;
2836         $contents = "";
2837                 $new_start_line = $. + 1;
2838 
2839         if ( $1 eq "" ) {
2840             $section = $section_intro;
2841         } else {
2842             $section = $1;
2843         }
2844         }
2845         elsif (/$doc_decl/o) {
2846         $identifier = $1;
2847         if (/\s*([\w\s]+?)\s*-/) {
2848             $identifier = $1;
2849         }
2850 
2851         $state = STATE_FIELD;
2852         # if there's no @param blocks need to set up default section
2853         # here
2854         $contents = "";
2855         $section = $section_default;
2856         $new_start_line = $. + 1;
2857         if (/-(.*)/) {
2858             # strip leading/trailing/multiple spaces
2859             $descr= $1;
2860             $descr =~ s/^\s*//;
2861             $descr =~ s/\s*$//;
2862             $descr =~ s/\s+/ /g;
2863             $declaration_purpose = xml_escape($descr);
2864             $in_purpose = 1;
2865         } else {
2866             $declaration_purpose = "";
2867         }
2868 
2869         if (($declaration_purpose eq "") && $verbose) {
2870             print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2871             print STDERR $_;
2872             ++$warnings;
2873         }
2874 
2875         if ($identifier =~ m/^struct/) {
2876             $decl_type = 'struct';
2877         } elsif ($identifier =~ m/^union/) {
2878             $decl_type = 'union';
2879         } elsif ($identifier =~ m/^enum/) {
2880             $decl_type = 'enum';
2881         } elsif ($identifier =~ m/^typedef/) {
2882             $decl_type = 'typedef';
2883         } else {
2884             $decl_type = 'function';
2885         }
2886 
2887         if ($verbose) {
2888             print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2889         }
2890         } else {
2891         print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2892         " - I thought it was a doc line\n";
2893         ++$warnings;
2894         $state = STATE_NORMAL;
2895         }
2896     } elsif ($state == STATE_FIELD) {   # look for head: lines, and include content
2897         if (/$doc_sect/i) { # case insensitive for supported section names
2898         $newsection = $1;
2899         $newcontents = $2;
2900 
2901         # map the supported section names to the canonical names
2902         if ($newsection =~ m/^description$/i) {
2903             $newsection = $section_default;
2904         } elsif ($newsection =~ m/^context$/i) {
2905             $newsection = $section_context;
2906         } elsif ($newsection =~ m/^returns?$/i) {
2907             $newsection = $section_return;
2908         } elsif ($newsection =~ m/^\@return$/) {
2909             # special: @return is a section, not a param description
2910             $newsection = $section_return;
2911         }
2912 
2913         if (($contents ne "") && ($contents ne "\n")) {
2914             if (!$in_doc_sect && $verbose) {
2915             print STDERR "${file}:$.: warning: contents before sections\n";
2916             ++$warnings;
2917             }
2918             dump_section($file, $section, xml_escape($contents));
2919             $section = $section_default;
2920         }
2921 
2922         $in_doc_sect = 1;
2923         $in_purpose = 0;
2924         $contents = $newcontents;
2925                 $new_start_line = $.;
2926         while ((substr($contents, 0, 1) eq " ") ||
2927                substr($contents, 0, 1) eq "\t") {
2928             $contents = substr($contents, 1);
2929         }
2930         if ($contents ne "") {
2931             $contents .= "\n";
2932         }
2933         $section = $newsection;
2934         $leading_space = undef;
2935         } elsif (/$doc_end/) {
2936         if (($contents ne "") && ($contents ne "\n")) {
2937             dump_section($file, $section, xml_escape($contents));
2938             $section = $section_default;
2939             $contents = "";
2940         }
2941         # look for doc_com + <text> + doc_end:
2942         if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2943             print STDERR "${file}:$.: warning: suspicious ending line: $_";
2944             ++$warnings;
2945         }
2946 
2947         $prototype = "";
2948         $state = STATE_PROTO;
2949         $brcount = 0;
2950 #       print STDERR "end of doc comment, looking for prototype\n";
2951         } elsif (/$doc_content/) {
2952         # miguel-style comment kludge, look for blank lines after
2953         # @parameter line to signify start of description
2954         if ($1 eq "") {
2955             if ($section =~ m/^@/ || $section eq $section_context) {
2956             dump_section($file, $section, xml_escape($contents));
2957             $section = $section_default;
2958             $contents = "";
2959                         $new_start_line = $.;
2960             } else {
2961             $contents .= "\n";
2962             }
2963             $in_purpose = 0;
2964         } elsif ($in_purpose == 1) {
2965             # Continued declaration purpose
2966             chomp($declaration_purpose);
2967             $declaration_purpose .= " " . xml_escape($1);
2968             $declaration_purpose =~ s/\s+/ /g;
2969         } else {
2970             my $cont = $1;
2971             if ($section =~ m/^@/ || $section eq $section_context) {
2972             if (!defined $leading_space) {
2973                 if ($cont =~ m/^(\s+)/) {
2974                 $leading_space = $1;
2975                 } else {
2976                 $leading_space = "";
2977                 }
2978             }
2979 
2980             $cont =~ s/^$leading_space//;
2981             }
2982             $contents .= $cont . "\n";
2983         }
2984         } else {
2985         # i dont know - bad line?  ignore.
2986         print STDERR "${file}:$.: warning: bad line: $_";
2987         ++$warnings;
2988         }
2989     } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2990         # First line (state 1) needs to be a @parameter
2991         if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2992         $section = $1;
2993         $contents = $2;
2994                 $new_start_line = $.;
2995         if ($contents ne "") {
2996             while ((substr($contents, 0, 1) eq " ") ||
2997                    substr($contents, 0, 1) eq "\t") {
2998             $contents = substr($contents, 1);
2999             }
3000             $contents .= "\n";
3001         }
3002         $inline_doc_state = STATE_INLINE_TEXT;
3003         # Documentation block end */
3004         } elsif (/$doc_inline_end/) {
3005         if (($contents ne "") && ($contents ne "\n")) {
3006             dump_section($file, $section, xml_escape($contents));
3007             $section = $section_default;
3008             $contents = "";
3009         }
3010         $state = STATE_PROTO;
3011         $inline_doc_state = STATE_INLINE_NA;
3012         # Regular text
3013         } elsif (/$doc_content/) {
3014         if ($inline_doc_state == STATE_INLINE_TEXT) {
3015             $contents .= $1 . "\n";
3016             # nuke leading blank lines
3017             if ($contents =~ /^\s*$/) {
3018             $contents = "";
3019             }
3020         } elsif ($inline_doc_state == STATE_INLINE_NAME) {
3021             $inline_doc_state = STATE_INLINE_ERROR;
3022             print STDERR "${file}:$.: warning: ";
3023             print STDERR "Incorrect use of kernel-doc format: $_";
3024             ++$warnings;
3025         }
3026         }
3027     } elsif ($state == STATE_PROTO) {   # scanning for function '{' (end of prototype)
3028         if (/$doc_inline_oneline/) {
3029         $section = $1;
3030         $contents = $2;
3031         if ($contents ne "") {
3032             $contents .= "\n";
3033             dump_section($file, $section, xml_escape($contents));
3034             $section = $section_default;
3035             $contents = "";
3036         }
3037         } elsif (/$doc_inline_start/) {
3038         $state = STATE_INLINE;
3039         $inline_doc_state = STATE_INLINE_NAME;
3040         } elsif ($decl_type eq 'function') {
3041         process_proto_function($_, $file);
3042         } else {
3043         process_proto_type($_, $file);
3044         }
3045     } elsif ($state == STATE_DOCBLOCK) {
3046         if (/$doc_end/)
3047         {
3048             dump_doc_section($file, $section, xml_escape($contents));
3049             $section = $section_default;
3050             $contents = "";
3051             $function = "";
3052             %parameterdescs = ();
3053             %parametertypes = ();
3054             @parameterlist = ();
3055             %sections = ();
3056             @sectionlist = ();
3057             $prototype = "";
3058             $state = STATE_NORMAL;
3059         }
3060         elsif (/$doc_content/)
3061         {
3062             if ( $1 eq "" )
3063             {
3064                 $contents .= $blankline;
3065             }
3066             else
3067             {
3068                 $contents .= $1 . "\n";
3069             }
3070         }
3071     }
3072     }
3073     if ($initial_section_counter == $section_counter) {
3074     print STDERR "${file}:1: warning: no structured comments found\n";
3075     if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
3076         print STDERR "    Was looking for '$_'.\n" for keys %function_table;
3077     }
3078     if ($output_mode eq "xml") {
3079         # The template wants at least one RefEntry here; make one.
3080         print "<refentry>\n";
3081         print " <refnamediv>\n";
3082         print "  <refname>\n";
3083         print "   ${orig_file}\n";
3084         print "  </refname>\n";
3085         print "  <refpurpose>\n";
3086         print "   Document generation inconsistency\n";
3087         print "  </refpurpose>\n";
3088         print " </refnamediv>\n";
3089         print " <refsect1>\n";
3090         print "  <title>\n";
3091         print "   Oops\n";
3092         print "  </title>\n";
3093         print "  <warning>\n";
3094         print "   <para>\n";
3095         print "    The template for this document tried to insert\n";
3096         print "    the structured comment from the file\n";
3097         print "    <filename>${orig_file}</filename> at this point,\n";
3098         print "    but none was found.\n";
3099         print "    This dummy section is inserted to allow\n";
3100         print "    generation to continue.\n";
3101         print "   </para>\n";
3102         print "  </warning>\n";
3103         print " </refsect1>\n";
3104         print "</refentry>\n";
3105     }
3106     }
3107 }
3108 
3109 
3110 $kernelversion = get_kernel_version();
3111 
3112 # generate a sequence of code that will splice in highlighting information
3113 # using the s// operator.
3114 for (my $k = 0; $k < @highlights; $k++) {
3115     my $pattern = $highlights[$k][0];
3116     my $result = $highlights[$k][1];
3117 #   print STDERR "scanning pattern:$pattern, highlight:($result)\n";
3118     $dohighlight .=  "\$contents =~ s:$pattern:$result:gs;\n";
3119 }
3120 
3121 # Read the file that maps relative names to absolute names for
3122 # separate source and object directories and for shadow trees.
3123 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
3124     my ($relname, $absname);
3125     while(<SOURCE_MAP>) {
3126         chop();
3127         ($relname, $absname) = (split())[0..1];
3128         $relname =~ s:^/+::;
3129         $source_map{$relname} = $absname;
3130     }
3131     close(SOURCE_MAP);
3132 }
3133 
3134 if ($output_selection == OUTPUT_EXPORTED ||
3135     $output_selection == OUTPUT_INTERNAL) {
3136 
3137     push(@export_file_list, @ARGV);
3138 
3139     foreach (@export_file_list) {
3140     chomp;
3141     process_export_file($_);
3142     }
3143 }
3144 
3145 foreach (@ARGV) {
3146     chomp;
3147     process_file($_);
3148 }
3149 if ($verbose && $errors) {
3150   print STDERR "$errors errors\n";
3151 }
3152 if ($verbose && $warnings) {
3153   print STDERR "$warnings warnings\n";
3154 }
3155 
3156 exit($errors);