home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / src / linux-headers-2.6.28-15 / scripts / kernel-doc < prev    next >
Encoding:
Text File  |  2009-09-09  |  57.0 KB  |  2,112 lines
  1. #!/usr/bin/perl -w
  2.  
  3. use strict;
  4.  
  5. ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
  6. ## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
  7. ## Copyright (C) 2001  Simon Huggins                             ##
  8. ## Copyright (C) 2005-2008  Randy Dunlap                         ##
  9. ##                                  ##
  10. ## #define enhancements by Armin Kuster <akuster@mvista.com>     ##
  11. ## Copyright (c) 2000 MontaVista Software, Inc.             ##
  12. ##                                  ##
  13. ## This software falls under the GNU General Public License.     ##
  14. ## Please read the COPYING file for more information             ##
  15.  
  16. # w.o. 03-11-2000: added the '-filelist' option.
  17.  
  18. # 18/01/2001 -     Cleanups
  19. #         Functions prototyped as foo(void) same as foo()
  20. #         Stop eval'ing where we don't need to.
  21. # -- huggie@earth.li
  22.  
  23. # 27/06/2001 -  Allowed whitespace after initial "/**" and
  24. #               allowed comments before function declarations.
  25. # -- Christian Kreibich <ck@whoop.org>
  26.  
  27. # Still to do:
  28. #     - add perldoc documentation
  29. #     - Look more closely at some of the scarier bits :)
  30.  
  31. # 26/05/2001 -     Support for separate source and object trees.
  32. #        Return error code.
  33. #         Keith Owens <kaos@ocs.com.au>
  34.  
  35. # 23/09/2001 - Added support for typedefs, structs, enums and unions
  36. #              Support for Context section; can be terminated using empty line
  37. #              Small fixes (like spaces vs. \s in regex)
  38. # -- Tim Jansen <tim@tjansen.de>
  39.  
  40.  
  41. #
  42. # This will read a 'c' file and scan for embedded comments in the
  43. # style of gnome comments (+minor extensions - see below).
  44. #
  45.  
  46. # Note: This only supports 'c'.
  47.  
  48. # usage:
  49. # kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ]
  50. #           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
  51. # or
  52. #           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
  53. #
  54. #  Set output format using one of -docbook -html -text or -man.  Default is man.
  55. #
  56. #  -no-doc-sections
  57. #    Do not output DOC: sections
  58. #
  59. #  -function funcname
  60. #    If set, then only generate documentation for the given function(s) or
  61. #    DOC: section titles.  All other functions and DOC: sections are ignored.
  62. #
  63. #  -nofunction funcname
  64. #    If set, then only generate documentation for the other function(s)/DOC:
  65. #    sections. Cannot be used together with -function (yes, that's a bug --
  66. #    perl hackers can fix it 8))
  67. #
  68. #  c files - list of 'c' files to process
  69. #
  70. #  All output goes to stdout, with errors to stderr.
  71.  
  72. #
  73. # format of comments.
  74. # In the following table, (...)? signifies optional structure.
  75. #                         (...)* signifies 0 or more structure elements
  76. # /**
  77. #  * function_name(:)? (- short description)?
  78. # (* @parameterx: (description of parameter x)?)*
  79. # (* a blank line)?
  80. #  * (Description:)? (Description of function)?
  81. #  * (section header: (section description)? )*
  82. #  (*)?*/
  83. #
  84. # So .. the trivial example would be:
  85. #
  86. # /**
  87. #  * my_function
  88. #  **/
  89. #
  90. # If the Description: header tag is omitted, then there must be a blank line
  91. # after the last parameter specification.
  92. # e.g.
  93. # /**
  94. #  * my_function - does my stuff
  95. #  * @my_arg: its mine damnit
  96. #  *
  97. #  * Does my stuff explained.
  98. #  */
  99. #
  100. #  or, could also use:
  101. # /**
  102. #  * my_function - does my stuff
  103. #  * @my_arg: its mine damnit
  104. #  * Description: Does my stuff explained.
  105. #  */
  106. # etc.
  107. #
  108. # Beside functions you can also write documentation for structs, unions,
  109. # enums and typedefs. Instead of the function name you must write the name
  110. # of the declaration;  the struct/union/enum/typedef must always precede
  111. # the name. Nesting of declarations is not supported.
  112. # Use the argument mechanism to document members or constants.
  113. # e.g.
  114. # /**
  115. #  * struct my_struct - short description
  116. #  * @a: first member
  117. #  * @b: second member
  118. #  *
  119. #  * Longer description
  120. #  */
  121. # struct my_struct {
  122. #     int a;
  123. #     int b;
  124. # /* private: */
  125. #     int c;
  126. # };
  127. #
  128. # All descriptions can be multiline, except the short function description.
  129. #
  130. # You can also add additional sections. When documenting kernel functions you
  131. # should document the "Context:" of the function, e.g. whether the functions
  132. # can be called form interrupts. Unlike other sections you can end it with an
  133. # empty line.
  134. # Example-sections should contain the string EXAMPLE so that they are marked
  135. # appropriately in DocBook.
  136. #
  137. # Example:
  138. # /**
  139. #  * user_function - function that can only be called in user context
  140. #  * @a: some argument
  141. #  * Context: !in_interrupt()
  142. #  *
  143. #  * Some description
  144. #  * Example:
  145. #  *    user_function(22);
  146. #  */
  147. # ...
  148. #
  149. #
  150. # All descriptive text is further processed, scanning for the following special
  151. # patterns, which are highlighted appropriately.
  152. #
  153. # 'funcname()' - function
  154. # '$ENVVAR' - environmental variable
  155. # '&struct_name' - name of a structure (up to two words including 'struct')
  156. # '@parameter' - name of a parameter
  157. # '%CONST' - name of a constant.
  158.  
  159. my $errors = 0;
  160. my $warnings = 0;
  161. my $anon_struct_union = 0;
  162.  
  163. # match expressions used to find embedded type information
  164. my $type_constant = '\%([-_\w]+)';
  165. my $type_func = '(\w+)\(\)';
  166. my $type_param = '\@(\w+)';
  167. my $type_struct = '\&((struct\s*)*[_\w]+)';
  168. my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
  169. my $type_env = '(\$\w+)';
  170.  
  171. # Output conversion substitutions.
  172. #  One for each output format
  173.  
  174. # these work fairly well
  175. my %highlights_html = ( $type_constant, "<i>\$1</i>",
  176.             $type_func, "<b>\$1</b>",
  177.             $type_struct_xml, "<i>\$1</i>",
  178.             $type_env, "<b><i>\$1</i></b>",
  179.             $type_param, "<tt><b>\$1</b></tt>" );
  180. my $local_lt = "\\\\\\\\lt:";
  181. my $local_gt = "\\\\\\\\gt:";
  182. my $blankline_html = $local_lt . "p" . $local_gt;    # was "<p>"
  183.  
  184. # XML, docbook format
  185. my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
  186.             $type_constant, "<constant>\$1</constant>",
  187.             $type_func, "<function>\$1</function>",
  188.             $type_struct_xml, "<structname>\$1</structname>",
  189.             $type_env, "<envar>\$1</envar>",
  190.             $type_param, "<parameter>\$1</parameter>" );
  191. my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
  192.  
  193. # gnome, docbook format
  194. my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
  195.              $type_func, "<function>\$1</function>",
  196.              $type_struct, "<structname>\$1</structname>",
  197.              $type_env, "<envar>\$1</envar>",
  198.              $type_param, "<parameter>\$1</parameter>" );
  199. my $blankline_gnome = "</para><para>\n";
  200.  
  201. # these are pretty rough
  202. my %highlights_man = ( $type_constant, "\$1",
  203.                $type_func, "\\\\fB\$1\\\\fP",
  204.                $type_struct, "\\\\fI\$1\\\\fP",
  205.                $type_param, "\\\\fI\$1\\\\fP" );
  206. my $blankline_man = "";
  207.  
  208. # text-mode
  209. my %highlights_text = ( $type_constant, "\$1",
  210.             $type_func, "\$1",
  211.             $type_struct, "\$1",
  212.             $type_param, "\$1" );
  213. my $blankline_text = "";
  214.  
  215.  
  216. sub usage {
  217.     print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n";
  218.     print "         [ -function funcname [ -function funcname ...] ]\n";
  219.     print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
  220.     print "         c source file(s) > outputfile\n";
  221.     print "         -v : verbose output, more warnings & other info listed\n";
  222.     exit 1;
  223. }
  224.  
  225. # read arguments
  226. if ($#ARGV==-1) {
  227.     usage();
  228. }
  229.  
  230. my $verbose = 0;
  231. my $output_mode = "man";
  232. my $no_doc_sections = 0;
  233. my %highlights = %highlights_man;
  234. my $blankline = $blankline_man;
  235. my $modulename = "Kernel API";
  236. my $function_only = 0;
  237. my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
  238.         'July', 'August', 'September', 'October',
  239.         'November', 'December')[(localtime)[4]] .
  240.   " " . ((localtime)[5]+1900);
  241.  
  242. # Essentially these are globals
  243. # They probably want to be tidied up made more localised or summat.
  244. # CAVEAT EMPTOR!  Some of the others I localised may not want to be which
  245. # could cause "use of undefined value" or other bugs.
  246. my ($function, %function_table,%parametertypes,$declaration_purpose);
  247. my ($type,$declaration_name,$return_type);
  248. my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
  249.  
  250. if (defined($ENV{'KBUILD_VERBOSE'})) {
  251.     $verbose = "$ENV{'KBUILD_VERBOSE'}";
  252. }
  253.  
  254. # Generated docbook code is inserted in a template at a point where
  255. # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
  256. # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
  257. # We keep track of number of generated entries and generate a dummy
  258. # if needs be to ensure the expanded template can be postprocessed
  259. # into html.
  260. my $section_counter = 0;
  261.  
  262. my $lineprefix="";
  263.  
  264. # states
  265. # 0 - normal code
  266. # 1 - looking for function name
  267. # 2 - scanning field start.
  268. # 3 - scanning prototype.
  269. # 4 - documentation block
  270. my $state;
  271. my $in_doc_sect;
  272.  
  273. #declaration types: can be
  274. # 'function', 'struct', 'union', 'enum', 'typedef'
  275. my $decl_type;
  276.  
  277. my $doc_special = "\@\%\$\&";
  278.  
  279. my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
  280. my $doc_end = '\*/';
  281. my $doc_com = '\s*\*\s*';
  282. my $doc_decl = $doc_com.'(\w+)';
  283. my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
  284. my $doc_content = $doc_com.'(.*)';
  285. my $doc_block = $doc_com.'DOC:\s*(.*)?';
  286.  
  287. my %constants;
  288. my %parameterdescs;
  289. my @parameterlist;
  290. my %sections;
  291. my @sectionlist;
  292.  
  293. my $contents = "";
  294. my $section_default = "Description";    # default section
  295. my $section_intro = "Introduction";
  296. my $section = $section_default;
  297. my $section_context = "Context";
  298.  
  299. my $undescribed = "-- undescribed --";
  300.  
  301. reset_state();
  302.  
  303. while ($ARGV[0] =~ m/^-(.*)/) {
  304.     my $cmd = shift @ARGV;
  305.     if ($cmd eq "-html") {
  306.     $output_mode = "html";
  307.     %highlights = %highlights_html;
  308.     $blankline = $blankline_html;
  309.     } elsif ($cmd eq "-man") {
  310.     $output_mode = "man";
  311.     %highlights = %highlights_man;
  312.     $blankline = $blankline_man;
  313.     } elsif ($cmd eq "-text") {
  314.     $output_mode = "text";
  315.     %highlights = %highlights_text;
  316.     $blankline = $blankline_text;
  317.     } elsif ($cmd eq "-docbook") {
  318.     $output_mode = "xml";
  319.     %highlights = %highlights_xml;
  320.     $blankline = $blankline_xml;
  321.     } elsif ($cmd eq "-gnome") {
  322.     $output_mode = "gnome";
  323.     %highlights = %highlights_gnome;
  324.     $blankline = $blankline_gnome;
  325.     } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
  326.     $modulename = shift @ARGV;
  327.     } elsif ($cmd eq "-function") { # to only output specific functions
  328.     $function_only = 1;
  329.     $function = shift @ARGV;
  330.     $function_table{$function} = 1;
  331.     } elsif ($cmd eq "-nofunction") { # to only output specific functions
  332.     $function_only = 2;
  333.     $function = shift @ARGV;
  334.     $function_table{$function} = 1;
  335.     } elsif ($cmd eq "-v") {
  336.     $verbose = 1;
  337.     } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
  338.     usage();
  339.     } elsif ($cmd eq '-filelist') {
  340.         $filelist = shift @ARGV;
  341.     } elsif ($cmd eq '-no-doc-sections') {
  342.         $no_doc_sections = 1;
  343.     }
  344. }
  345.  
  346. # get kernel version from env
  347. sub get_kernel_version() {
  348.     my $version = 'unknown kernel version';
  349.  
  350.     if (defined($ENV{'KERNELVERSION'})) {
  351.     $version = $ENV{'KERNELVERSION'};
  352.     }
  353.     return $version;
  354. }
  355. my $kernelversion = get_kernel_version();
  356.  
  357. # generate a sequence of code that will splice in highlighting information
  358. # using the s// operator.
  359. my $dohighlight = "";
  360. foreach my $pattern (keys %highlights) {
  361. #   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
  362.     $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
  363. }
  364.  
  365. ##
  366. # dumps section contents to arrays/hashes intended for that purpose.
  367. #
  368. sub dump_section {
  369.     my $file = shift;
  370.     my $name = shift;
  371.     my $contents = join "\n", @_;
  372.  
  373.     if ($name =~ m/$type_constant/) {
  374.     $name = $1;
  375. #    print STDERR "constant section '$1' = '$contents'\n";
  376.     $constants{$name} = $contents;
  377.     } elsif ($name =~ m/$type_param/) {
  378. #    print STDERR "parameter def '$1' = '$contents'\n";
  379.     $name = $1;
  380.     $parameterdescs{$name} = $contents;
  381.     } elsif ($name eq "@\.\.\.") {
  382. #    print STDERR "parameter def '...' = '$contents'\n";
  383.     $name = "...";
  384.     $parameterdescs{$name} = $contents;
  385.     } else {
  386. #    print STDERR "other section '$name' = '$contents'\n";
  387.     if (defined($sections{$name}) && ($sections{$name} ne "")) {
  388.         print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
  389.         ++$errors;
  390.     }
  391.     $sections{$name} = $contents;
  392.     push @sectionlist, $name;
  393.     }
  394. }
  395.  
  396. ##
  397. # dump DOC: section after checking that it should go out
  398. #
  399. sub dump_doc_section {
  400.     my $file = shift;
  401.     my $name = shift;
  402.     my $contents = join "\n", @_;
  403.  
  404.     if ($no_doc_sections) {
  405.         return;
  406.     }
  407.  
  408.     if (($function_only == 0) ||
  409.     ( $function_only == 1 && defined($function_table{$name})) ||
  410.     ( $function_only == 2 && !defined($function_table{$name})))
  411.     {
  412.     dump_section($file, $name, $contents);
  413.     output_blockhead({'sectionlist' => \@sectionlist,
  414.               'sections' => \%sections,
  415.               'module' => $modulename,
  416.               'content-only' => ($function_only != 0), });
  417.     }
  418. }
  419.  
  420. ##
  421. # output function
  422. #
  423. # parameterdescs, a hash.
  424. #  function => "function name"
  425. #  parameterlist => @list of parameters
  426. #  parameterdescs => %parameter descriptions
  427. #  sectionlist => @list of sections
  428. #  sections => %section descriptions
  429. #
  430.  
  431. sub output_highlight {
  432.     my $contents = join "\n",@_;
  433.     my $line;
  434.  
  435. #   DEBUG
  436. #   if (!defined $contents) {
  437. #    use Carp;
  438. #    confess "output_highlight got called with no args?\n";
  439. #   }
  440.  
  441.     if ($output_mode eq "html" || $output_mode eq "xml") {
  442.     $contents = local_unescape($contents);
  443.     # convert data read & converted thru xml_escape() into &xyz; format:
  444.     $contents =~ s/\\\\\\/&/g;
  445.     }
  446. #   print STDERR "contents b4:$contents\n";
  447.     eval $dohighlight;
  448.     die $@ if $@;
  449. #   print STDERR "contents af:$contents\n";
  450.  
  451.     foreach $line (split "\n", $contents) {
  452.     if ($line eq ""){
  453.         print $lineprefix, local_unescape($blankline);
  454.     } else {
  455.         $line =~ s/\\\\\\/\&/g;
  456.         if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
  457.         print "\\&$line";
  458.         } else {
  459.         print $lineprefix, $line;
  460.         }
  461.     }
  462.     print "\n";
  463.     }
  464. }
  465.  
  466. #output sections in html
  467. sub output_section_html(%) {
  468.     my %args = %{$_[0]};
  469.     my $section;
  470.  
  471.     foreach $section (@{$args{'sectionlist'}}) {
  472.     print "<h3>$section</h3>\n";
  473.     print "<blockquote>\n";
  474.     output_highlight($args{'sections'}{$section});
  475.     print "</blockquote>\n";
  476.     }
  477. }
  478.  
  479. # output enum in html
  480. sub output_enum_html(%) {
  481.     my %args = %{$_[0]};
  482.     my ($parameter);
  483.     my $count;
  484.     print "<h2>enum ".$args{'enum'}."</h2>\n";
  485.  
  486.     print "<b>enum ".$args{'enum'}."</b> {<br>\n";
  487.     $count = 0;
  488.     foreach $parameter (@{$args{'parameterlist'}}) {
  489.     print " <b>".$parameter."</b>";
  490.     if ($count != $#{$args{'parameterlist'}}) {
  491.         $count++;
  492.         print ",\n";
  493.     }
  494.     print "<br>";
  495.     }
  496.     print "};<br>\n";
  497.  
  498.     print "<h3>Constants</h3>\n";
  499.     print "<dl>\n";
  500.     foreach $parameter (@{$args{'parameterlist'}}) {
  501.     print "<dt><b>".$parameter."</b>\n";
  502.     print "<dd>";
  503.     output_highlight($args{'parameterdescs'}{$parameter});
  504.     }
  505.     print "</dl>\n";
  506.     output_section_html(@_);
  507.     print "<hr>\n";
  508. }
  509.  
  510. # output typedef in html
  511. sub output_typedef_html(%) {
  512.     my %args = %{$_[0]};
  513.     my ($parameter);
  514.     my $count;
  515.     print "<h2>typedef ".$args{'typedef'}."</h2>\n";
  516.  
  517.     print "<b>typedef ".$args{'typedef'}."</b>\n";
  518.     output_section_html(@_);
  519.     print "<hr>\n";
  520. }
  521.  
  522. # output struct in html
  523. sub output_struct_html(%) {
  524.     my %args = %{$_[0]};
  525.     my ($parameter);
  526.  
  527.     print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
  528.     print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
  529.     foreach $parameter (@{$args{'parameterlist'}}) {
  530.     if ($parameter =~ /^#/) {
  531.         print "$parameter<br>\n";
  532.         next;
  533.     }
  534.     my $parameter_name = $parameter;
  535.     $parameter_name =~ s/\[.*//;
  536.  
  537.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  538.     $type = $args{'parametertypes'}{$parameter};
  539.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  540.         # pointer-to-function
  541.         print "    <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
  542.     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  543.         # bitfield
  544.         print "    <i>$1</i> <b>$parameter</b>$2;<br>\n";
  545.     } else {
  546.         print "    <i>$type</i> <b>$parameter</b>;<br>\n";
  547.     }
  548.     }
  549.     print "};<br>\n";
  550.  
  551.     print "<h3>Members</h3>\n";
  552.     print "<dl>\n";
  553.     foreach $parameter (@{$args{'parameterlist'}}) {
  554.     ($parameter =~ /^#/) && next;
  555.  
  556.     my $parameter_name = $parameter;
  557.     $parameter_name =~ s/\[.*//;
  558.  
  559.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  560.     print "<dt><b>".$parameter."</b>\n";
  561.     print "<dd>";
  562.     output_highlight($args{'parameterdescs'}{$parameter_name});
  563.     }
  564.     print "</dl>\n";
  565.     output_section_html(@_);
  566.     print "<hr>\n";
  567. }
  568.  
  569. # output function in html
  570. sub output_function_html(%) {
  571.     my %args = %{$_[0]};
  572.     my ($parameter, $section);
  573.     my $count;
  574.  
  575.     print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
  576.     print "<i>".$args{'functiontype'}."</i>\n";
  577.     print "<b>".$args{'function'}."</b>\n";
  578.     print "(";
  579.     $count = 0;
  580.     foreach $parameter (@{$args{'parameterlist'}}) {
  581.     $type = $args{'parametertypes'}{$parameter};
  582.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  583.         # pointer-to-function
  584.         print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
  585.     } else {
  586.         print "<i>".$type."</i> <b>".$parameter."</b>";
  587.     }
  588.     if ($count != $#{$args{'parameterlist'}}) {
  589.         $count++;
  590.         print ",\n";
  591.     }
  592.     }
  593.     print ")\n";
  594.  
  595.     print "<h3>Arguments</h3>\n";
  596.     print "<dl>\n";
  597.     foreach $parameter (@{$args{'parameterlist'}}) {
  598.     my $parameter_name = $parameter;
  599.     $parameter_name =~ s/\[.*//;
  600.  
  601.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  602.     print "<dt><b>".$parameter."</b>\n";
  603.     print "<dd>";
  604.     output_highlight($args{'parameterdescs'}{$parameter_name});
  605.     }
  606.     print "</dl>\n";
  607.     output_section_html(@_);
  608.     print "<hr>\n";
  609. }
  610.  
  611. # output DOC: block header in html
  612. sub output_blockhead_html(%) {
  613.     my %args = %{$_[0]};
  614.     my ($parameter, $section);
  615.     my $count;
  616.  
  617.     foreach $section (@{$args{'sectionlist'}}) {
  618.     print "<h3>$section</h3>\n";
  619.     print "<ul>\n";
  620.     output_highlight($args{'sections'}{$section});
  621.     print "</ul>\n";
  622.     }
  623.     print "<hr>\n";
  624. }
  625.  
  626. sub output_section_xml(%) {
  627.     my %args = %{$_[0]};
  628.     my $section;
  629.     # print out each section
  630.     $lineprefix="   ";
  631.     foreach $section (@{$args{'sectionlist'}}) {
  632.     print "<refsect1>\n";
  633.     print "<title>$section</title>\n";
  634.     if ($section =~ m/EXAMPLE/i) {
  635.         print "<informalexample><programlisting>\n";
  636.     } else {
  637.         print "<para>\n";
  638.     }
  639.     output_highlight($args{'sections'}{$section});
  640.     if ($section =~ m/EXAMPLE/i) {
  641.         print "</programlisting></informalexample>\n";
  642.     } else {
  643.         print "</para>\n";
  644.     }
  645.     print "</refsect1>\n";
  646.     }
  647. }
  648.  
  649. # output function in XML DocBook
  650. sub output_function_xml(%) {
  651.     my %args = %{$_[0]};
  652.     my ($parameter, $section);
  653.     my $count;
  654.     my $id;
  655.  
  656.     $id = "API-".$args{'function'};
  657.     $id =~ s/[^A-Za-z0-9]/-/g;
  658.  
  659.     print "<refentry id=\"$id\">\n";
  660.     print "<refentryinfo>\n";
  661.     print " <title>LINUX</title>\n";
  662.     print " <productname>Kernel Hackers Manual</productname>\n";
  663.     print " <date>$man_date</date>\n";
  664.     print "</refentryinfo>\n";
  665.     print "<refmeta>\n";
  666.     print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
  667.     print " <manvolnum>9</manvolnum>\n";
  668.     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
  669.     print "</refmeta>\n";
  670.     print "<refnamediv>\n";
  671.     print " <refname>".$args{'function'}."</refname>\n";
  672.     print " <refpurpose>\n";
  673.     print "  ";
  674.     output_highlight ($args{'purpose'});
  675.     print " </refpurpose>\n";
  676.     print "</refnamediv>\n";
  677.  
  678.     print "<refsynopsisdiv>\n";
  679.     print " <title>Synopsis</title>\n";
  680.     print "  <funcsynopsis><funcprototype>\n";
  681.     print "   <funcdef>".$args{'functiontype'}." ";
  682.     print "<function>".$args{'function'}." </function></funcdef>\n";
  683.  
  684.     $count = 0;
  685.     if ($#{$args{'parameterlist'}} >= 0) {
  686.     foreach $parameter (@{$args{'parameterlist'}}) {
  687.         $type = $args{'parametertypes'}{$parameter};
  688.         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  689.         # pointer-to-function
  690.         print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
  691.         print "     <funcparams>$2</funcparams></paramdef>\n";
  692.         } else {
  693.         print "   <paramdef>".$type;
  694.         print " <parameter>$parameter</parameter></paramdef>\n";
  695.         }
  696.     }
  697.     } else {
  698.     print "  <void/>\n";
  699.     }
  700.     print "  </funcprototype></funcsynopsis>\n";
  701.     print "</refsynopsisdiv>\n";
  702.  
  703.     # print parameters
  704.     print "<refsect1>\n <title>Arguments</title>\n";
  705.     if ($#{$args{'parameterlist'}} >= 0) {
  706.     print " <variablelist>\n";
  707.     foreach $parameter (@{$args{'parameterlist'}}) {
  708.         my $parameter_name = $parameter;
  709.         $parameter_name =~ s/\[.*//;
  710.  
  711.         print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
  712.         print "   <listitem>\n    <para>\n";
  713.         $lineprefix="     ";
  714.         output_highlight($args{'parameterdescs'}{$parameter_name});
  715.         print "    </para>\n   </listitem>\n  </varlistentry>\n";
  716.     }
  717.     print " </variablelist>\n";
  718.     } else {
  719.     print " <para>\n  None\n </para>\n";
  720.     }
  721.     print "</refsect1>\n";
  722.  
  723.     output_section_xml(@_);
  724.     print "</refentry>\n\n";
  725. }
  726.  
  727. # output struct in XML DocBook
  728. sub output_struct_xml(%) {
  729.     my %args = %{$_[0]};
  730.     my ($parameter, $section);
  731.     my $id;
  732.  
  733.     $id = "API-struct-".$args{'struct'};
  734.     $id =~ s/[^A-Za-z0-9]/-/g;
  735.  
  736.     print "<refentry id=\"$id\">\n";
  737.     print "<refentryinfo>\n";
  738.     print " <title>LINUX</title>\n";
  739.     print " <productname>Kernel Hackers Manual</productname>\n";
  740.     print " <date>$man_date</date>\n";
  741.     print "</refentryinfo>\n";
  742.     print "<refmeta>\n";
  743.     print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
  744.     print " <manvolnum>9</manvolnum>\n";
  745.     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
  746.     print "</refmeta>\n";
  747.     print "<refnamediv>\n";
  748.     print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
  749.     print " <refpurpose>\n";
  750.     print "  ";
  751.     output_highlight ($args{'purpose'});
  752.     print " </refpurpose>\n";
  753.     print "</refnamediv>\n";
  754.  
  755.     print "<refsynopsisdiv>\n";
  756.     print " <title>Synopsis</title>\n";
  757.     print "  <programlisting>\n";
  758.     print $args{'type'}." ".$args{'struct'}." {\n";
  759.     foreach $parameter (@{$args{'parameterlist'}}) {
  760.     if ($parameter =~ /^#/) {
  761.         print "$parameter\n";
  762.         next;
  763.     }
  764.  
  765.     my $parameter_name = $parameter;
  766.     $parameter_name =~ s/\[.*//;
  767.  
  768.     defined($args{'parameterdescs'}{$parameter_name}) || next;
  769.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  770.     $type = $args{'parametertypes'}{$parameter};
  771.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  772.         # pointer-to-function
  773.         print "  $1 $parameter) ($2);\n";
  774.     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  775.         # bitfield
  776.         print "  $1 $parameter$2;\n";
  777.     } else {
  778.         print "  ".$type." ".$parameter.";\n";
  779.     }
  780.     }
  781.     print "};";
  782.     print "  </programlisting>\n";
  783.     print "</refsynopsisdiv>\n";
  784.  
  785.     print " <refsect1>\n";
  786.     print "  <title>Members</title>\n";
  787.  
  788.     if ($#{$args{'parameterlist'}} >= 0) {
  789.     print "  <variablelist>\n";
  790.     foreach $parameter (@{$args{'parameterlist'}}) {
  791.       ($parameter =~ /^#/) && next;
  792.  
  793.       my $parameter_name = $parameter;
  794.       $parameter_name =~ s/\[.*//;
  795.  
  796.       defined($args{'parameterdescs'}{$parameter_name}) || next;
  797.       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  798.       print "    <varlistentry>";
  799.       print "      <term>$parameter</term>\n";
  800.       print "      <listitem><para>\n";
  801.       output_highlight($args{'parameterdescs'}{$parameter_name});
  802.       print "      </para></listitem>\n";
  803.       print "    </varlistentry>\n";
  804.     }
  805.     print "  </variablelist>\n";
  806.     } else {
  807.     print " <para>\n  None\n </para>\n";
  808.     }
  809.     print " </refsect1>\n";
  810.  
  811.     output_section_xml(@_);
  812.  
  813.     print "</refentry>\n\n";
  814. }
  815.  
  816. # output enum in XML DocBook
  817. sub output_enum_xml(%) {
  818.     my %args = %{$_[0]};
  819.     my ($parameter, $section);
  820.     my $count;
  821.     my $id;
  822.  
  823.     $id = "API-enum-".$args{'enum'};
  824.     $id =~ s/[^A-Za-z0-9]/-/g;
  825.  
  826.     print "<refentry id=\"$id\">\n";
  827.     print "<refentryinfo>\n";
  828.     print " <title>LINUX</title>\n";
  829.     print " <productname>Kernel Hackers Manual</productname>\n";
  830.     print " <date>$man_date</date>\n";
  831.     print "</refentryinfo>\n";
  832.     print "<refmeta>\n";
  833.     print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
  834.     print " <manvolnum>9</manvolnum>\n";
  835.     print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
  836.     print "</refmeta>\n";
  837.     print "<refnamediv>\n";
  838.     print " <refname>enum ".$args{'enum'}."</refname>\n";
  839.     print " <refpurpose>\n";
  840.     print "  ";
  841.     output_highlight ($args{'purpose'});
  842.     print " </refpurpose>\n";
  843.     print "</refnamediv>\n";
  844.  
  845.     print "<refsynopsisdiv>\n";
  846.     print " <title>Synopsis</title>\n";
  847.     print "  <programlisting>\n";
  848.     print "enum ".$args{'enum'}." {\n";
  849.     $count = 0;
  850.     foreach $parameter (@{$args{'parameterlist'}}) {
  851.     print "  $parameter";
  852.     if ($count != $#{$args{'parameterlist'}}) {
  853.         $count++;
  854.         print ",";
  855.     }
  856.     print "\n";
  857.     }
  858.     print "};";
  859.     print "  </programlisting>\n";
  860.     print "</refsynopsisdiv>\n";
  861.  
  862.     print "<refsect1>\n";
  863.     print " <title>Constants</title>\n";
  864.     print "  <variablelist>\n";
  865.     foreach $parameter (@{$args{'parameterlist'}}) {
  866.       my $parameter_name = $parameter;
  867.       $parameter_name =~ s/\[.*//;
  868.  
  869.       print "    <varlistentry>";
  870.       print "      <term>$parameter</term>\n";
  871.       print "      <listitem><para>\n";
  872.       output_highlight($args{'parameterdescs'}{$parameter_name});
  873.       print "      </para></listitem>\n";
  874.       print "    </varlistentry>\n";
  875.     }
  876.     print "  </variablelist>\n";
  877.     print "</refsect1>\n";
  878.  
  879.     output_section_xml(@_);
  880.  
  881.     print "</refentry>\n\n";
  882. }
  883.  
  884. # output typedef in XML DocBook
  885. sub output_typedef_xml(%) {
  886.     my %args = %{$_[0]};
  887.     my ($parameter, $section);
  888.     my $id;
  889.  
  890.     $id = "API-typedef-".$args{'typedef'};
  891.     $id =~ s/[^A-Za-z0-9]/-/g;
  892.  
  893.     print "<refentry id=\"$id\">\n";
  894.     print "<refentryinfo>\n";
  895.     print " <title>LINUX</title>\n";
  896.     print " <productname>Kernel Hackers Manual</productname>\n";
  897.     print " <date>$man_date</date>\n";
  898.     print "</refentryinfo>\n";
  899.     print "<refmeta>\n";
  900.     print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
  901.     print " <manvolnum>9</manvolnum>\n";
  902.     print "</refmeta>\n";
  903.     print "<refnamediv>\n";
  904.     print " <refname>typedef ".$args{'typedef'}."</refname>\n";
  905.     print " <refpurpose>\n";
  906.     print "  ";
  907.     output_highlight ($args{'purpose'});
  908.     print " </refpurpose>\n";
  909.     print "</refnamediv>\n";
  910.  
  911.     print "<refsynopsisdiv>\n";
  912.     print " <title>Synopsis</title>\n";
  913.     print "  <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
  914.     print "</refsynopsisdiv>\n";
  915.  
  916.     output_section_xml(@_);
  917.  
  918.     print "</refentry>\n\n";
  919. }
  920.  
  921. # output in XML DocBook
  922. sub output_blockhead_xml(%) {
  923.     my %args = %{$_[0]};
  924.     my ($parameter, $section);
  925.     my $count;
  926.  
  927.     my $id = $args{'module'};
  928.     $id =~ s/[^A-Za-z0-9]/-/g;
  929.  
  930.     # print out each section
  931.     $lineprefix="   ";
  932.     foreach $section (@{$args{'sectionlist'}}) {
  933.     if (!$args{'content-only'}) {
  934.         print "<refsect1>\n <title>$section</title>\n";
  935.     }
  936.     if ($section =~ m/EXAMPLE/i) {
  937.         print "<example><para>\n";
  938.     } else {
  939.         print "<para>\n";
  940.     }
  941.     output_highlight($args{'sections'}{$section});
  942.     if ($section =~ m/EXAMPLE/i) {
  943.         print "</para></example>\n";
  944.     } else {
  945.         print "</para>";
  946.     }
  947.     if (!$args{'content-only'}) {
  948.         print "\n</refsect1>\n";
  949.     }
  950.     }
  951.  
  952.     print "\n\n";
  953. }
  954.  
  955. # output in XML DocBook
  956. sub output_function_gnome {
  957.     my %args = %{$_[0]};
  958.     my ($parameter, $section);
  959.     my $count;
  960.     my $id;
  961.  
  962.     $id = $args{'module'}."-".$args{'function'};
  963.     $id =~ s/[^A-Za-z0-9]/-/g;
  964.  
  965.     print "<sect2>\n";
  966.     print " <title id=\"$id\">".$args{'function'}."</title>\n";
  967.  
  968.     print "  <funcsynopsis>\n";
  969.     print "   <funcdef>".$args{'functiontype'}." ";
  970.     print "<function>".$args{'function'}." ";
  971.     print "</function></funcdef>\n";
  972.  
  973.     $count = 0;
  974.     if ($#{$args{'parameterlist'}} >= 0) {
  975.     foreach $parameter (@{$args{'parameterlist'}}) {
  976.         $type = $args{'parametertypes'}{$parameter};
  977.         if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  978.         # pointer-to-function
  979.         print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
  980.         print "     <funcparams>$2</funcparams></paramdef>\n";
  981.         } else {
  982.         print "   <paramdef>".$type;
  983.         print " <parameter>$parameter</parameter></paramdef>\n";
  984.         }
  985.     }
  986.     } else {
  987.     print "  <void>\n";
  988.     }
  989.     print "  </funcsynopsis>\n";
  990.     if ($#{$args{'parameterlist'}} >= 0) {
  991.     print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
  992.     print "<tgroup cols=\"2\">\n";
  993.     print "<colspec colwidth=\"2*\">\n";
  994.     print "<colspec colwidth=\"8*\">\n";
  995.     print "<tbody>\n";
  996.     foreach $parameter (@{$args{'parameterlist'}}) {
  997.         my $parameter_name = $parameter;
  998.         $parameter_name =~ s/\[.*//;
  999.  
  1000.         print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
  1001.         print "   <entry>\n";
  1002.         $lineprefix="     ";
  1003.         output_highlight($args{'parameterdescs'}{$parameter_name});
  1004.         print "    </entry></row>\n";
  1005.     }
  1006.     print " </tbody></tgroup></informaltable>\n";
  1007.     } else {
  1008.     print " <para>\n  None\n </para>\n";
  1009.     }
  1010.  
  1011.     # print out each section
  1012.     $lineprefix="   ";
  1013.     foreach $section (@{$args{'sectionlist'}}) {
  1014.     print "<simplesect>\n <title>$section</title>\n";
  1015.     if ($section =~ m/EXAMPLE/i) {
  1016.         print "<example><programlisting>\n";
  1017.     } else {
  1018.     }
  1019.     print "<para>\n";
  1020.     output_highlight($args{'sections'}{$section});
  1021.     print "</para>\n";
  1022.     if ($section =~ m/EXAMPLE/i) {
  1023.         print "</programlisting></example>\n";
  1024.     } else {
  1025.     }
  1026.     print " </simplesect>\n";
  1027.     }
  1028.  
  1029.     print "</sect2>\n\n";
  1030. }
  1031.  
  1032. ##
  1033. # output function in man
  1034. sub output_function_man(%) {
  1035.     my %args = %{$_[0]};
  1036.     my ($parameter, $section);
  1037.     my $count;
  1038.  
  1039.     print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
  1040.  
  1041.     print ".SH NAME\n";
  1042.     print $args{'function'}." \\- ".$args{'purpose'}."\n";
  1043.  
  1044.     print ".SH SYNOPSIS\n";
  1045.     if ($args{'functiontype'} ne "") {
  1046.     print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
  1047.     } else {
  1048.     print ".B \"".$args{'function'}."\n";
  1049.     }
  1050.     $count = 0;
  1051.     my $parenth = "(";
  1052.     my $post = ",";
  1053.     foreach my $parameter (@{$args{'parameterlist'}}) {
  1054.     if ($count == $#{$args{'parameterlist'}}) {
  1055.         $post = ");";
  1056.     }
  1057.     $type = $args{'parametertypes'}{$parameter};
  1058.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1059.         # pointer-to-function
  1060.         print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
  1061.     } else {
  1062.         $type =~ s/([^\*])$/$1 /;
  1063.         print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
  1064.     }
  1065.     $count++;
  1066.     $parenth = "";
  1067.     }
  1068.  
  1069.     print ".SH ARGUMENTS\n";
  1070.     foreach $parameter (@{$args{'parameterlist'}}) {
  1071.     my $parameter_name = $parameter;
  1072.     $parameter_name =~ s/\[.*//;
  1073.  
  1074.     print ".IP \"".$parameter."\" 12\n";
  1075.     output_highlight($args{'parameterdescs'}{$parameter_name});
  1076.     }
  1077.     foreach $section (@{$args{'sectionlist'}}) {
  1078.     print ".SH \"", uc $section, "\"\n";
  1079.     output_highlight($args{'sections'}{$section});
  1080.     }
  1081. }
  1082.  
  1083. ##
  1084. # output enum in man
  1085. sub output_enum_man(%) {
  1086.     my %args = %{$_[0]};
  1087.     my ($parameter, $section);
  1088.     my $count;
  1089.  
  1090.     print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
  1091.  
  1092.     print ".SH NAME\n";
  1093.     print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
  1094.  
  1095.     print ".SH SYNOPSIS\n";
  1096.     print "enum ".$args{'enum'}." {\n";
  1097.     $count = 0;
  1098.     foreach my $parameter (@{$args{'parameterlist'}}) {
  1099.     print ".br\n.BI \"    $parameter\"\n";
  1100.     if ($count == $#{$args{'parameterlist'}}) {
  1101.         print "\n};\n";
  1102.         last;
  1103.     }
  1104.     else {
  1105.         print ", \n.br\n";
  1106.     }
  1107.     $count++;
  1108.     }
  1109.  
  1110.     print ".SH Constants\n";
  1111.     foreach $parameter (@{$args{'parameterlist'}}) {
  1112.     my $parameter_name = $parameter;
  1113.     $parameter_name =~ s/\[.*//;
  1114.  
  1115.     print ".IP \"".$parameter."\" 12\n";
  1116.     output_highlight($args{'parameterdescs'}{$parameter_name});
  1117.     }
  1118.     foreach $section (@{$args{'sectionlist'}}) {
  1119.     print ".SH \"$section\"\n";
  1120.     output_highlight($args{'sections'}{$section});
  1121.     }
  1122. }
  1123.  
  1124. ##
  1125. # output struct in man
  1126. sub output_struct_man(%) {
  1127.     my %args = %{$_[0]};
  1128.     my ($parameter, $section);
  1129.  
  1130.     print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
  1131.  
  1132.     print ".SH NAME\n";
  1133.     print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
  1134.  
  1135.     print ".SH SYNOPSIS\n";
  1136.     print $args{'type'}." ".$args{'struct'}." {\n.br\n";
  1137.  
  1138.     foreach my $parameter (@{$args{'parameterlist'}}) {
  1139.     if ($parameter =~ /^#/) {
  1140.         print ".BI \"$parameter\"\n.br\n";
  1141.         next;
  1142.     }
  1143.     my $parameter_name = $parameter;
  1144.     $parameter_name =~ s/\[.*//;
  1145.  
  1146.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1147.     $type = $args{'parametertypes'}{$parameter};
  1148.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1149.         # pointer-to-function
  1150.         print ".BI \"    ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
  1151.     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  1152.         # bitfield
  1153.         print ".BI \"    ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
  1154.     } else {
  1155.         $type =~ s/([^\*])$/$1 /;
  1156.         print ".BI \"    ".$type."\" ".$parameter." \""."\"\n;\n";
  1157.     }
  1158.     print "\n.br\n";
  1159.     }
  1160.     print "};\n.br\n";
  1161.  
  1162.     print ".SH Members\n";
  1163.     foreach $parameter (@{$args{'parameterlist'}}) {
  1164.     ($parameter =~ /^#/) && next;
  1165.  
  1166.     my $parameter_name = $parameter;
  1167.     $parameter_name =~ s/\[.*//;
  1168.  
  1169.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1170.     print ".IP \"".$parameter."\" 12\n";
  1171.     output_highlight($args{'parameterdescs'}{$parameter_name});
  1172.     }
  1173.     foreach $section (@{$args{'sectionlist'}}) {
  1174.     print ".SH \"$section\"\n";
  1175.     output_highlight($args{'sections'}{$section});
  1176.     }
  1177. }
  1178.  
  1179. ##
  1180. # output typedef in man
  1181. sub output_typedef_man(%) {
  1182.     my %args = %{$_[0]};
  1183.     my ($parameter, $section);
  1184.  
  1185.     print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
  1186.  
  1187.     print ".SH NAME\n";
  1188.     print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
  1189.  
  1190.     foreach $section (@{$args{'sectionlist'}}) {
  1191.     print ".SH \"$section\"\n";
  1192.     output_highlight($args{'sections'}{$section});
  1193.     }
  1194. }
  1195.  
  1196. sub output_blockhead_man(%) {
  1197.     my %args = %{$_[0]};
  1198.     my ($parameter, $section);
  1199.     my $count;
  1200.  
  1201.     print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
  1202.  
  1203.     foreach $section (@{$args{'sectionlist'}}) {
  1204.     print ".SH \"$section\"\n";
  1205.     output_highlight($args{'sections'}{$section});
  1206.     }
  1207. }
  1208.  
  1209. ##
  1210. # output in text
  1211. sub output_function_text(%) {
  1212.     my %args = %{$_[0]};
  1213.     my ($parameter, $section);
  1214.     my $start;
  1215.  
  1216.     print "Name:\n\n";
  1217.     print $args{'function'}." - ".$args{'purpose'}."\n";
  1218.  
  1219.     print "\nSynopsis:\n\n";
  1220.     if ($args{'functiontype'} ne "") {
  1221.     $start = $args{'functiontype'}." ".$args{'function'}." (";
  1222.     } else {
  1223.     $start = $args{'function'}." (";
  1224.     }
  1225.     print $start;
  1226.  
  1227.     my $count = 0;
  1228.     foreach my $parameter (@{$args{'parameterlist'}}) {
  1229.     $type = $args{'parametertypes'}{$parameter};
  1230.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1231.         # pointer-to-function
  1232.         print $1.$parameter.") (".$2;
  1233.     } else {
  1234.         print $type." ".$parameter;
  1235.     }
  1236.     if ($count != $#{$args{'parameterlist'}}) {
  1237.         $count++;
  1238.         print ",\n";
  1239.         print " " x length($start);
  1240.     } else {
  1241.         print ");\n\n";
  1242.     }
  1243.     }
  1244.  
  1245.     print "Arguments:\n\n";
  1246.     foreach $parameter (@{$args{'parameterlist'}}) {
  1247.     my $parameter_name = $parameter;
  1248.     $parameter_name =~ s/\[.*//;
  1249.  
  1250.     print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
  1251.     }
  1252.     output_section_text(@_);
  1253. }
  1254.  
  1255. #output sections in text
  1256. sub output_section_text(%) {
  1257.     my %args = %{$_[0]};
  1258.     my $section;
  1259.  
  1260.     print "\n";
  1261.     foreach $section (@{$args{'sectionlist'}}) {
  1262.     print "$section:\n\n";
  1263.     output_highlight($args{'sections'}{$section});
  1264.     }
  1265.     print "\n\n";
  1266. }
  1267.  
  1268. # output enum in text
  1269. sub output_enum_text(%) {
  1270.     my %args = %{$_[0]};
  1271.     my ($parameter);
  1272.     my $count;
  1273.     print "Enum:\n\n";
  1274.  
  1275.     print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
  1276.     print "enum ".$args{'enum'}." {\n";
  1277.     $count = 0;
  1278.     foreach $parameter (@{$args{'parameterlist'}}) {
  1279.     print "\t$parameter";
  1280.     if ($count != $#{$args{'parameterlist'}}) {
  1281.         $count++;
  1282.         print ",";
  1283.     }
  1284.     print "\n";
  1285.     }
  1286.     print "};\n\n";
  1287.  
  1288.     print "Constants:\n\n";
  1289.     foreach $parameter (@{$args{'parameterlist'}}) {
  1290.     print "$parameter\n\t";
  1291.     print $args{'parameterdescs'}{$parameter}."\n";
  1292.     }
  1293.  
  1294.     output_section_text(@_);
  1295. }
  1296.  
  1297. # output typedef in text
  1298. sub output_typedef_text(%) {
  1299.     my %args = %{$_[0]};
  1300.     my ($parameter);
  1301.     my $count;
  1302.     print "Typedef:\n\n";
  1303.  
  1304.     print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
  1305.     output_section_text(@_);
  1306. }
  1307.  
  1308. # output struct as text
  1309. sub output_struct_text(%) {
  1310.     my %args = %{$_[0]};
  1311.     my ($parameter);
  1312.  
  1313.     print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
  1314.     print $args{'type'}." ".$args{'struct'}." {\n";
  1315.     foreach $parameter (@{$args{'parameterlist'}}) {
  1316.     if ($parameter =~ /^#/) {
  1317.         print "$parameter\n";
  1318.         next;
  1319.     }
  1320.  
  1321.     my $parameter_name = $parameter;
  1322.     $parameter_name =~ s/\[.*//;
  1323.  
  1324.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1325.     $type = $args{'parametertypes'}{$parameter};
  1326.     if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
  1327.         # pointer-to-function
  1328.         print "\t$1 $parameter) ($2);\n";
  1329.     } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
  1330.         # bitfield
  1331.         print "\t$1 $parameter$2;\n";
  1332.     } else {
  1333.         print "\t".$type." ".$parameter.";\n";
  1334.     }
  1335.     }
  1336.     print "};\n\n";
  1337.  
  1338.     print "Members:\n\n";
  1339.     foreach $parameter (@{$args{'parameterlist'}}) {
  1340.     ($parameter =~ /^#/) && next;
  1341.  
  1342.     my $parameter_name = $parameter;
  1343.     $parameter_name =~ s/\[.*//;
  1344.  
  1345.     ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
  1346.     print "$parameter\n\t";
  1347.     print $args{'parameterdescs'}{$parameter_name}."\n";
  1348.     }
  1349.     print "\n";
  1350.     output_section_text(@_);
  1351. }
  1352.  
  1353. sub output_blockhead_text(%) {
  1354.     my %args = %{$_[0]};
  1355.     my ($parameter, $section);
  1356.  
  1357.     foreach $section (@{$args{'sectionlist'}}) {
  1358.     print " $section:\n";
  1359.     print "    -> ";
  1360.     output_highlight($args{'sections'}{$section});
  1361.     }
  1362. }
  1363.  
  1364. ##
  1365. # generic output function for all types (function, struct/union, typedef, enum);
  1366. # calls the generated, variable output_ function name based on
  1367. # functype and output_mode
  1368. sub output_declaration {
  1369.     no strict 'refs';
  1370.     my $name = shift;
  1371.     my $functype = shift;
  1372.     my $func = "output_${functype}_$output_mode";
  1373.     if (($function_only==0) ||
  1374.     ( $function_only == 1 && defined($function_table{$name})) ||
  1375.     ( $function_only == 2 && !defined($function_table{$name})))
  1376.     {
  1377.     &$func(@_);
  1378.     $section_counter++;
  1379.     }
  1380. }
  1381.  
  1382. ##
  1383. # generic output function - calls the right one based on current output mode.
  1384. sub output_blockhead {
  1385.     no strict 'refs';
  1386.     my $func = "output_blockhead_".$output_mode;
  1387.     &$func(@_);
  1388.     $section_counter++;
  1389. }
  1390.  
  1391. ##
  1392. # takes a declaration (struct, union, enum, typedef) and
  1393. # invokes the right handler. NOT called for functions.
  1394. sub dump_declaration($$) {
  1395.     no strict 'refs';
  1396.     my ($prototype, $file) = @_;
  1397.     my $func = "dump_".$decl_type;
  1398.     &$func(@_);
  1399. }
  1400.  
  1401. sub dump_union($$) {
  1402.     dump_struct(@_);
  1403. }
  1404.  
  1405. sub dump_struct($$) {
  1406.     my $x = shift;
  1407.     my $file = shift;
  1408.  
  1409.     if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
  1410.     $declaration_name = $2;
  1411.     my $members = $3;
  1412.  
  1413.     # ignore embedded structs or unions
  1414.     $members =~ s/{.*}//g;
  1415.  
  1416.     # ignore members marked private:
  1417.     $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
  1418.     $members =~ s/\/\*.*?private:.*//gos;
  1419.     # strip comments:
  1420.     $members =~ s/\/\*.*?\*\///gos;
  1421.  
  1422.     create_parameterlist($members, ';', $file);
  1423.  
  1424.     output_declaration($declaration_name,
  1425.                'struct',
  1426.                {'struct' => $declaration_name,
  1427.                 'module' => $modulename,
  1428.                 'parameterlist' => \@parameterlist,
  1429.                 'parameterdescs' => \%parameterdescs,
  1430.                 'parametertypes' => \%parametertypes,
  1431.                 'sectionlist' => \@sectionlist,
  1432.                 'sections' => \%sections,
  1433.                 'purpose' => $declaration_purpose,
  1434.                 'type' => $decl_type
  1435.                });
  1436.     }
  1437.     else {
  1438.     print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
  1439.     ++$errors;
  1440.     }
  1441. }
  1442.  
  1443. sub dump_enum($$) {
  1444.     my $x = shift;
  1445.     my $file = shift;
  1446.  
  1447.     $x =~ s@/\*.*?\*/@@gos;    # strip comments.
  1448.     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
  1449.     $declaration_name = $1;
  1450.     my $members = $2;
  1451.  
  1452.     foreach my $arg (split ',', $members) {
  1453.         $arg =~ s/^\s*(\w+).*/$1/;
  1454.         push @parameterlist, $arg;
  1455.         if (!$parameterdescs{$arg}) {
  1456.         $parameterdescs{$arg} = $undescribed;
  1457.         print STDERR "Warning(${file}:$.): Enum value '$arg' ".
  1458.             "not described in enum '$declaration_name'\n";
  1459.         }
  1460.  
  1461.     }
  1462.  
  1463.     output_declaration($declaration_name,
  1464.                'enum',
  1465.                {'enum' => $declaration_name,
  1466.                 'module' => $modulename,
  1467.                 'parameterlist' => \@parameterlist,
  1468.                 'parameterdescs' => \%parameterdescs,
  1469.                 'sectionlist' => \@sectionlist,
  1470.                 'sections' => \%sections,
  1471.                 'purpose' => $declaration_purpose
  1472.                });
  1473.     }
  1474.     else {
  1475.     print STDERR "Error(${file}:$.): Cannot parse enum!\n";
  1476.     ++$errors;
  1477.     }
  1478. }
  1479.  
  1480. sub dump_typedef($$) {
  1481.     my $x = shift;
  1482.     my $file = shift;
  1483.  
  1484.     $x =~ s@/\*.*?\*/@@gos;    # strip comments.
  1485.     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
  1486.     $x =~ s/\(*.\)\s*;$/;/;
  1487.     $x =~ s/\[*.\]\s*;$/;/;
  1488.     }
  1489.  
  1490.     if ($x =~ /typedef.*\s+(\w+)\s*;/) {
  1491.     $declaration_name = $1;
  1492.  
  1493.     output_declaration($declaration_name,
  1494.                'typedef',
  1495.                {'typedef' => $declaration_name,
  1496.                 'module' => $modulename,
  1497.                 'sectionlist' => \@sectionlist,
  1498.                 'sections' => \%sections,
  1499.                 'purpose' => $declaration_purpose
  1500.                });
  1501.     }
  1502.     else {
  1503.     print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
  1504.     ++$errors;
  1505.     }
  1506. }
  1507.  
  1508. sub create_parameterlist($$$) {
  1509.     my $args = shift;
  1510.     my $splitter = shift;
  1511.     my $file = shift;
  1512.     my $type;
  1513.     my $param;
  1514.  
  1515.     # temporarily replace commas inside function pointer definition
  1516.     while ($args =~ /(\([^\),]+),/) {
  1517.     $args =~ s/(\([^\),]+),/$1#/g;
  1518.     }
  1519.  
  1520.     foreach my $arg (split($splitter, $args)) {
  1521.     # strip comments
  1522.     $arg =~ s/\/\*.*\*\///;
  1523.     # strip leading/trailing spaces
  1524.     $arg =~ s/^\s*//;
  1525.     $arg =~ s/\s*$//;
  1526.     $arg =~ s/\s+/ /;
  1527.  
  1528.     if ($arg =~ /^#/) {
  1529.         # Treat preprocessor directive as a typeless variable just to fill
  1530.         # corresponding data structures "correctly". Catch it later in
  1531.         # output_* subs.
  1532.         push_parameter($arg, "", $file);
  1533.     } elsif ($arg =~ m/\(.+\)\s*\(/) {
  1534.         # pointer-to-function
  1535.         $arg =~ tr/#/,/;
  1536.         $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
  1537.         $param = $1;
  1538.         $type = $arg;
  1539.         $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
  1540.         push_parameter($param, $type, $file);
  1541.     } elsif ($arg) {
  1542.         $arg =~ s/\s*:\s*/:/g;
  1543.         $arg =~ s/\s*\[/\[/g;
  1544.  
  1545.         my @args = split('\s*,\s*', $arg);
  1546.         if ($args[0] =~ m/\*/) {
  1547.         $args[0] =~ s/(\*+)\s*/ $1/;
  1548.         }
  1549.  
  1550.         my @first_arg;
  1551.         if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
  1552.             shift @args;
  1553.             push(@first_arg, split('\s+', $1));
  1554.             push(@first_arg, $2);
  1555.         } else {
  1556.             @first_arg = split('\s+', shift @args);
  1557.         }
  1558.  
  1559.         unshift(@args, pop @first_arg);
  1560.         $type = join " ", @first_arg;
  1561.  
  1562.         foreach $param (@args) {
  1563.         if ($param =~ m/^(\*+)\s*(.*)/) {
  1564.             push_parameter($2, "$type $1", $file);
  1565.         }
  1566.         elsif ($param =~ m/(.*?):(\d+)/) {
  1567.             if ($type ne "") { # skip unnamed bit-fields
  1568.             push_parameter($1, "$type:$2", $file)
  1569.             }
  1570.         }
  1571.         else {
  1572.             push_parameter($param, $type, $file);
  1573.         }
  1574.         }
  1575.     }
  1576.     }
  1577. }
  1578.  
  1579. sub push_parameter($$$) {
  1580.     my $param = shift;
  1581.     my $type = shift;
  1582.     my $file = shift;
  1583.  
  1584.     if (($anon_struct_union == 1) && ($type eq "") &&
  1585.         ($param eq "}")) {
  1586.         return;        # ignore the ending }; from anon. struct/union
  1587.     }
  1588.  
  1589.     $anon_struct_union = 0;
  1590.     my $param_name = $param;
  1591.     $param_name =~ s/\[.*//;
  1592.  
  1593.     if ($type eq "" && $param =~ /\.\.\.$/)
  1594.     {
  1595.         if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
  1596.         $parameterdescs{$param} = "variable arguments";
  1597.         }
  1598.     }
  1599.     elsif ($type eq "" && ($param eq "" or $param eq "void"))
  1600.     {
  1601.         $param="void";
  1602.         $parameterdescs{void} = "no arguments";
  1603.     }
  1604.     elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
  1605.     # handle unnamed (anonymous) union or struct:
  1606.     {
  1607.         $type = $param;
  1608.         $param = "{unnamed_" . $param . "}";
  1609.         $parameterdescs{$param} = "anonymous\n";
  1610.         $anon_struct_union = 1;
  1611.     }
  1612.  
  1613.     # warn if parameter has no description
  1614.     # (but ignore ones starting with # as these are not parameters
  1615.     # but inline preprocessor statements);
  1616.     # also ignore unnamed structs/unions;
  1617.     if (!$anon_struct_union) {
  1618.     if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
  1619.  
  1620.         $parameterdescs{$param_name} = $undescribed;
  1621.  
  1622.         if (($type eq 'function') || ($type eq 'enum')) {
  1623.         print STDERR "Warning(${file}:$.): Function parameter ".
  1624.             "or member '$param' not " .
  1625.             "described in '$declaration_name'\n";
  1626.         }
  1627.         print STDERR "Warning(${file}:$.):".
  1628.              " No description found for parameter '$param'\n";
  1629.         ++$warnings;
  1630.     }
  1631.     }
  1632.  
  1633.     push @parameterlist, $param;
  1634.     $parametertypes{$param} = $type;
  1635. }
  1636.  
  1637. ##
  1638. # takes a function prototype and the name of the current file being
  1639. # processed and spits out all the details stored in the global
  1640. # arrays/hashes.
  1641. sub dump_function($$) {
  1642.     my $prototype = shift;
  1643.     my $file = shift;
  1644.  
  1645.     $prototype =~ s/^static +//;
  1646.     $prototype =~ s/^extern +//;
  1647.     $prototype =~ s/^asmlinkage +//;
  1648.     $prototype =~ s/^inline +//;
  1649.     $prototype =~ s/^__inline__ +//;
  1650.     $prototype =~ s/^__inline +//;
  1651.     $prototype =~ s/^__always_inline +//;
  1652.     $prototype =~ s/^noinline +//;
  1653.     $prototype =~ s/__devinit +//;
  1654.     $prototype =~ s/__init +//;
  1655.     $prototype =~ s/^#\s*define\s+//; #ak added
  1656.     $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
  1657.  
  1658.     # Yes, this truly is vile.  We are looking for:
  1659.     # 1. Return type (may be nothing if we're looking at a macro)
  1660.     # 2. Function name
  1661.     # 3. Function parameters.
  1662.     #
  1663.     # All the while we have to watch out for function pointer parameters
  1664.     # (which IIRC is what the two sections are for), C types (these
  1665.     # regexps don't even start to express all the possibilities), and
  1666.     # so on.
  1667.     #
  1668.     # If you mess with these regexps, it's a good idea to check that
  1669.     # the following functions' documentation still comes out right:
  1670.     # - parport_register_device (function pointer parameters)
  1671.     # - atomic_set (macro)
  1672.     # - pci_match_device, __copy_to_user (long return type)
  1673.  
  1674.     if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1675.     $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1676.     $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1677.     $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1678.     $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1679.     $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1680.     $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
  1681.     $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1682.     $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1683.     $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1684.     $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1685.     $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1686.     $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1687.     $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1688.     $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1689.     $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
  1690.     $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
  1691.     $return_type = $1;
  1692.     $declaration_name = $2;
  1693.     my $args = $3;
  1694.  
  1695.     create_parameterlist($args, ',', $file);
  1696.     } else {
  1697.     print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
  1698.     ++$errors;
  1699.     return;
  1700.     }
  1701.  
  1702.     output_declaration($declaration_name,
  1703.                'function',
  1704.                {'function' => $declaration_name,
  1705.             'module' => $modulename,
  1706.             'functiontype' => $return_type,
  1707.             'parameterlist' => \@parameterlist,
  1708.             'parameterdescs' => \%parameterdescs,
  1709.             'parametertypes' => \%parametertypes,
  1710.             'sectionlist' => \@sectionlist,
  1711.             'sections' => \%sections,
  1712.             'purpose' => $declaration_purpose
  1713.                });
  1714. }
  1715.  
  1716. sub process_file($);
  1717.  
  1718. # Read the file that maps relative names to absolute names for
  1719. # separate source and object directories and for shadow trees.
  1720. if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
  1721.     my ($relname, $absname);
  1722.     while(<SOURCE_MAP>) {
  1723.         chop();
  1724.         ($relname, $absname) = (split())[0..1];
  1725.         $relname =~ s:^/+::;
  1726.         $source_map{$relname} = $absname;
  1727.     }
  1728.     close(SOURCE_MAP);
  1729. }
  1730.  
  1731. if ($filelist) {
  1732.     open(FLIST,"<$filelist") or die "Can't open file list $filelist";
  1733.     while(<FLIST>) {
  1734.         chop;
  1735.         process_file($_);
  1736.     }
  1737. }
  1738.  
  1739. foreach (@ARGV) {
  1740.     chomp;
  1741.     process_file($_);
  1742. }
  1743. if ($verbose && $errors) {
  1744.   print STDERR "$errors errors\n";
  1745. }
  1746. if ($verbose && $warnings) {
  1747.   print STDERR "$warnings warnings\n";
  1748. }
  1749.  
  1750. exit($errors);
  1751.  
  1752. sub reset_state {
  1753.     $function = "";
  1754.     %constants = ();
  1755.     %parameterdescs = ();
  1756.     %parametertypes = ();
  1757.     @parameterlist = ();
  1758.     %sections = ();
  1759.     @sectionlist = ();
  1760.     $prototype = "";
  1761.  
  1762.     $state = 0;
  1763. }
  1764.  
  1765. sub syscall_munge() {
  1766.     my $void = 0;
  1767.  
  1768.     $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
  1769. ##    if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
  1770.     if ($prototype =~ m/SYSCALL_DEFINE0/) {
  1771.         $void = 1;
  1772. ##        $prototype = "long sys_$1(void)";
  1773.     }
  1774.  
  1775.     $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
  1776.     if ($prototype =~ m/long (sys_.*?),/) {
  1777.         $prototype =~ s/,/\(/;
  1778.     } elsif ($void) {
  1779.         $prototype =~ s/\)/\(void\)/;
  1780.     }
  1781.  
  1782.     # now delete all of the odd-number commas in $prototype
  1783.     # so that arg types & arg names don't have a comma between them
  1784.     my $count = 0;
  1785.     my $len = length($prototype);
  1786.     if ($void) {
  1787.         $len = 0;    # skip the for-loop
  1788.     }
  1789.     for (my $ix = 0; $ix < $len; $ix++) {
  1790.         if (substr($prototype, $ix, 1) eq ',') {
  1791.             $count++;
  1792.             if ($count % 2 == 1) {
  1793.                 substr($prototype, $ix, 1) = ' ';
  1794.             }
  1795.         }
  1796.     }
  1797. }
  1798.  
  1799. sub process_state3_function($$) {
  1800.     my $x = shift;
  1801.     my $file = shift;
  1802.  
  1803.     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1804.  
  1805.     if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
  1806.     # do nothing
  1807.     }
  1808.     elsif ($x =~ /([^\{]*)/) {
  1809.     $prototype .= $1;
  1810.     }
  1811.  
  1812.     if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
  1813.     $prototype =~ s@/\*.*?\*/@@gos;    # strip comments.
  1814.     $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1815.     $prototype =~ s@^\s+@@gos; # strip leading spaces
  1816.     if ($prototype =~ /SYSCALL_DEFINE/) {
  1817.         syscall_munge();
  1818.     }
  1819.     dump_function($prototype, $file);
  1820.     reset_state();
  1821.     }
  1822. }
  1823.  
  1824. sub process_state3_type($$) {
  1825.     my $x = shift;
  1826.     my $file = shift;
  1827.  
  1828.     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
  1829.     $x =~ s@^\s+@@gos; # strip leading spaces
  1830.     $x =~ s@\s+$@@gos; # strip trailing spaces
  1831.     $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
  1832.  
  1833.     if ($x =~ /^#/) {
  1834.     # To distinguish preprocessor directive from regular declaration later.
  1835.     $x .= ";";
  1836.     }
  1837.  
  1838.     while (1) {
  1839.     if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
  1840.         $prototype .= $1 . $2;
  1841.         ($2 eq '{') && $brcount++;
  1842.         ($2 eq '}') && $brcount--;
  1843.         if (($2 eq ';') && ($brcount == 0)) {
  1844.         dump_declaration($prototype,$file);
  1845.         reset_state();
  1846.         last;
  1847.         }
  1848.         $x = $3;
  1849.     } else {
  1850.         $prototype .= $x;
  1851.         last;
  1852.     }
  1853.     }
  1854. }
  1855.  
  1856. # xml_escape: replace <, >, and & in the text stream;
  1857. #
  1858. # however, formatting controls that are generated internally/locally in the
  1859. # kernel-doc script are not escaped here; instead, they begin life like
  1860. # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
  1861. # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
  1862. # just before actual output; (this is done by local_unescape())
  1863. sub xml_escape($) {
  1864.     my $text = shift;
  1865.     if (($output_mode eq "text") || ($output_mode eq "man")) {
  1866.         return $text;
  1867.     }
  1868.     $text =~ s/\&/\\\\\\amp;/g;
  1869.     $text =~ s/\</\\\\\\lt;/g;
  1870.     $text =~ s/\>/\\\\\\gt;/g;
  1871.     return $text;
  1872. }
  1873.  
  1874. # convert local escape strings to html
  1875. # local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
  1876. sub local_unescape($) {
  1877.     my $text = shift;
  1878.     if (($output_mode eq "text") || ($output_mode eq "man")) {
  1879.         return $text;
  1880.     }
  1881.     $text =~ s/\\\\\\\\lt:/</g;
  1882.     $text =~ s/\\\\\\\\gt:/>/g;
  1883.     return $text;
  1884. }
  1885.  
  1886. sub process_file($) {
  1887.     my $file;
  1888.     my $identifier;
  1889.     my $func;
  1890.     my $descr;
  1891.     my $initial_section_counter = $section_counter;
  1892.  
  1893.     if (defined($ENV{'SRCTREE'})) {
  1894.     $file = "$ENV{'SRCTREE'}" . "/" . "@_";
  1895.     }
  1896.     else {
  1897.     $file = "@_";
  1898.     }
  1899.     if (defined($source_map{$file})) {
  1900.     $file = $source_map{$file};
  1901.     }
  1902.  
  1903.     if (!open(IN,"<$file")) {
  1904.     print STDERR "Error: Cannot open file $file\n";
  1905.     ++$errors;
  1906.     return;
  1907.     }
  1908.  
  1909.     $section_counter = 0;
  1910.     while (<IN>) {
  1911.     if ($state == 0) {
  1912.         if (/$doc_start/o) {
  1913.         $state = 1;        # next line is always the function name
  1914.         $in_doc_sect = 0;
  1915.         }
  1916.     } elsif ($state == 1) {    # this line is the function name (always)
  1917.         if (/$doc_block/o) {
  1918.         $state = 4;
  1919.         $contents = "";
  1920.         if ( $1 eq "" ) {
  1921.             $section = $section_intro;
  1922.         } else {
  1923.             $section = $1;
  1924.         }
  1925.         }
  1926.         elsif (/$doc_decl/o) {
  1927.         $identifier = $1;
  1928.         if (/\s*([\w\s]+?)\s*-/) {
  1929.             $identifier = $1;
  1930.         }
  1931.  
  1932.         $state = 2;
  1933.         if (/-(.*)/) {
  1934.             # strip leading/trailing/multiple spaces
  1935.             $descr= $1;
  1936.             $descr =~ s/^\s*//;
  1937.             $descr =~ s/\s*$//;
  1938.             $descr =~ s/\s+/ /;
  1939.             $declaration_purpose = xml_escape($descr);
  1940.         } else {
  1941.             $declaration_purpose = "";
  1942.         }
  1943.  
  1944.         if (($declaration_purpose eq "") && $verbose) {
  1945.             print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
  1946.             print STDERR $_;
  1947.             ++$warnings;
  1948.         }
  1949.  
  1950.         if ($identifier =~ m/^struct/) {
  1951.             $decl_type = 'struct';
  1952.         } elsif ($identifier =~ m/^union/) {
  1953.             $decl_type = 'union';
  1954.         } elsif ($identifier =~ m/^enum/) {
  1955.             $decl_type = 'enum';
  1956.         } elsif ($identifier =~ m/^typedef/) {
  1957.             $decl_type = 'typedef';
  1958.         } else {
  1959.             $decl_type = 'function';
  1960.         }
  1961.  
  1962.         if ($verbose) {
  1963.             print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
  1964.         }
  1965.         } else {
  1966.         print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
  1967.         " - I thought it was a doc line\n";
  1968.         ++$warnings;
  1969.         $state = 0;
  1970.         }
  1971.     } elsif ($state == 2) {    # look for head: lines, and include content
  1972.         if (/$doc_sect/o) {
  1973.         $newsection = $1;
  1974.         $newcontents = $2;
  1975.  
  1976.         if (($contents ne "") && ($contents ne "\n")) {
  1977.             if (!$in_doc_sect && $verbose) {
  1978.             print STDERR "Warning(${file}:$.): contents before sections\n";
  1979.             ++$warnings;
  1980.             }
  1981.             dump_section($file, $section, xml_escape($contents));
  1982.             $section = $section_default;
  1983.         }
  1984.  
  1985.         $in_doc_sect = 1;
  1986.         $contents = $newcontents;
  1987.         if ($contents ne "") {
  1988.             while ((substr($contents, 0, 1) eq " ") ||
  1989.             substr($contents, 0, 1) eq "\t") {
  1990.                 $contents = substr($contents, 1);
  1991.             }
  1992.             $contents .= "\n";
  1993.         }
  1994.         $section = $newsection;
  1995.         } elsif (/$doc_end/) {
  1996.  
  1997.         if ($contents ne "") {
  1998.             dump_section($file, $section, xml_escape($contents));
  1999.             $section = $section_default;
  2000.             $contents = "";
  2001.         }
  2002.         # look for doc_com + <text> + doc_end:
  2003.         if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
  2004.             print STDERR "Warning(${file}:$.): suspicious ending line: $_";
  2005.             ++$warnings;
  2006.         }
  2007.  
  2008.         $prototype = "";
  2009.         $state = 3;
  2010.         $brcount = 0;
  2011. #        print STDERR "end of doc comment, looking for prototype\n";
  2012.         } elsif (/$doc_content/) {
  2013.         # miguel-style comment kludge, look for blank lines after
  2014.         # @parameter line to signify start of description
  2015.         if ($1 eq "" &&
  2016.             ($section =~ m/^@/ || $section eq $section_context)) {
  2017.             dump_section($file, $section, xml_escape($contents));
  2018.             $section = $section_default;
  2019.             $contents = "";
  2020.         } else {
  2021.             $contents .= $1."\n";
  2022.         }
  2023.         } else {
  2024.         # i dont know - bad line?  ignore.
  2025.         print STDERR "Warning(${file}:$.): bad line: $_";
  2026.         ++$warnings;
  2027.         }
  2028.     } elsif ($state == 3) {    # scanning for function '{' (end of prototype)
  2029.         if ($decl_type eq 'function') {
  2030.         process_state3_function($_, $file);
  2031.         } else {
  2032.         process_state3_type($_, $file);
  2033.         }
  2034.     } elsif ($state == 4) {
  2035.         # Documentation block
  2036.         if (/$doc_block/) {
  2037.             dump_doc_section($file, $section, xml_escape($contents));
  2038.             $contents = "";
  2039.             $function = "";
  2040.             %constants = ();
  2041.             %parameterdescs = ();
  2042.             %parametertypes = ();
  2043.             @parameterlist = ();
  2044.             %sections = ();
  2045.             @sectionlist = ();
  2046.             $prototype = "";
  2047.             if ( $1 eq "" ) {
  2048.                 $section = $section_intro;
  2049.             } else {
  2050.                 $section = $1;
  2051.             }
  2052.         }
  2053.         elsif (/$doc_end/)
  2054.         {
  2055.             dump_doc_section($file, $section, xml_escape($contents));
  2056.             $contents = "";
  2057.             $function = "";
  2058.             %constants = ();
  2059.             %parameterdescs = ();
  2060.             %parametertypes = ();
  2061.             @parameterlist = ();
  2062.             %sections = ();
  2063.             @sectionlist = ();
  2064.             $prototype = "";
  2065.             $state = 0;
  2066.         }
  2067.         elsif (/$doc_content/)
  2068.         {
  2069.             if ( $1 eq "" )
  2070.             {
  2071.                 $contents .= $blankline;
  2072.             }
  2073.             else
  2074.             {
  2075.                 $contents .= $1 . "\n";
  2076.             }
  2077.         }
  2078.     }
  2079.     }
  2080.     if ($initial_section_counter == $section_counter) {
  2081.     print STDERR "Warning(${file}): no structured comments found\n";
  2082.     if ($output_mode eq "xml") {
  2083.         # The template wants at least one RefEntry here; make one.
  2084.         print "<refentry>\n";
  2085.         print " <refnamediv>\n";
  2086.         print "  <refname>\n";
  2087.         print "   ${file}\n";
  2088.         print "  </refname>\n";
  2089.         print "  <refpurpose>\n";
  2090.         print "   Document generation inconsistency\n";
  2091.         print "  </refpurpose>\n";
  2092.         print " </refnamediv>\n";
  2093.         print " <refsect1>\n";
  2094.         print "  <title>\n";
  2095.         print "   Oops\n";
  2096.         print "  </title>\n";
  2097.         print "  <warning>\n";
  2098.         print "   <para>\n";
  2099.         print "    The template for this document tried to insert\n";
  2100.         print "    the structured comment from the file\n";
  2101.         print "    <filename>${file}</filename> at this point,\n";
  2102.         print "    but none was found.\n";
  2103.         print "    This dummy section is inserted to allow\n";
  2104.         print "    generation to continue.\n";
  2105.         print "   </para>\n";
  2106.         print "  </warning>\n";
  2107.         print " </refsect1>\n";
  2108.         print "</refentry>\n";
  2109.     }
  2110.     }
  2111. }
  2112.