5 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6 ## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7 ## Copyright (C) 2001 Simon Huggins ##
8 ## Copyright (C) 2005-2012 Randy Dunlap ##
9 ## Copyright (C) 2012 Dan Luedtke ##
11 ## #define enhancements by Armin Kuster <akuster@mvista.com> ##
12 ## Copyright (c) 2000 MontaVista Software, Inc. ##
14 ## This software falls under the GNU General Public License. ##
15 ## Please read the COPYING file for more information ##
17 # 18/01/2001 - Cleanups
18 # Functions prototyped as foo(void) same as foo()
19 # Stop eval'ing where we don't need to.
22 # 27/06/2001 - Allowed whitespace after initial "/**" and
23 # allowed comments before function declarations.
24 # -- Christian Kreibich <ck@whoop.org>
27 # - add perldoc documentation
28 # - Look more closely at some of the scarier bits :)
30 # 26/05/2001 - Support for separate source and object trees.
32 # Keith Owens <kaos@ocs.com.au>
34 # 23/09/2001 - Added support for typedefs, structs, enums and unions
35 # Support for Context section; can be terminated using empty line
36 # Small fixes (like spaces vs. \s in regex)
37 # -- Tim Jansen <tim@tjansen.de>
39 # 25/07/2012 - Added support for HTML5
40 # -- Dan Luedtke <mail@danrl.de>
43 my $message = <<"EOF";
44 Usage: $0 [OPTION ...] FILE ...
46 Read C language source or header FILEs, extract embedded documentation comments,
47 and print formatted documentation to standard output.
49 The documentation comments are identified by "/**" opening comment mark. See
50 Documentation/kernel-doc-nano-HOWTO.txt for the documentation comment syntax.
52 Output format selection (mutually exclusive):
53 -docbook Output DocBook format.
54 -html Output HTML format.
55 -html5 Output HTML5 format.
56 -list Output symbol list format. This is for use by docproc.
57 -man Output troff manual page format. This is the default.
58 -rst Output reStructuredText format.
59 -text Output plain text format.
61 Output selection (mutually exclusive):
62 -export Only output documentation for symbols that have been
63 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
65 -internal Only output documentation for symbols that have NOT been
66 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
68 -function NAME Only output documentation for the given function(s)
69 or DOC: section title(s). All other functions and DOC:
70 sections are ignored. May be specified multiple times.
71 -nofunction NAME Do NOT output documentation for the given function(s);
72 only output documentation for the other functions and
73 DOC: sections. May be specified multiple times.
75 Output selection modifiers:
76 -no-doc-sections Do not output DOC: sections.
79 -v Verbose output, more warnings and other information.
89 # In the following table, (...)? signifies optional structure.
90 # (...)* signifies 0 or more structure elements
92 # * function_name(:)? (- short description)?
93 # (* @parameterx: (description of parameter x)?)*
95 # * (Description:)? (Description of function)?
96 # * (section header: (section description)? )*
99 # So .. the trivial example would be:
105 # If the Description: header tag is omitted, then there must be a blank line
106 # after the last parameter specification.
109 # * my_function - does my stuff
110 # * @my_arg: its mine damnit
112 # * Does my stuff explained.
115 # or, could also use:
117 # * my_function - does my stuff
118 # * @my_arg: its mine damnit
119 # * Description: Does my stuff explained.
123 # Besides functions you can also write documentation for structs, unions,
124 # enums and typedefs. Instead of the function name you must write the name
125 # of the declaration; the struct/union/enum/typedef must always precede
126 # the name. Nesting of declarations is not supported.
127 # Use the argument mechanism to document members or constants.
130 # * struct my_struct - short description
132 # * @b: second member
134 # * Longer description
143 # All descriptions can be multiline, except the short function description.
145 # For really longs structs, you can also describe arguments inside the
146 # body of the struct.
149 # * struct my_struct - short description
151 # * @b: second member
153 # * Longer description
159 # * @c: This is longer description of C
161 # * You can use paragraphs to describe arguments
162 # * using this method.
167 # This should be use only for struct/enum members.
169 # You can also add additional sections. When documenting kernel functions you
170 # should document the "Context:" of the function, e.g. whether the functions
171 # can be called form interrupts. Unlike other sections you can end it with an
173 # A non-void function should have a "Return:" section describing the return
175 # Example-sections should contain the string EXAMPLE so that they are marked
176 # appropriately in DocBook.
180 # * user_function - function that can only be called in user context
181 # * @a: some argument
182 # * Context: !in_interrupt()
186 # * user_function(22);
191 # All descriptive text is further processed, scanning for the following special
192 # patterns, which are highlighted appropriately.
194 # 'funcname()' - function
195 # '$ENVVAR' - environmental variable
196 # '&struct_name' - name of a structure (up to two words including 'struct')
197 # '@parameter' - name of a parameter
198 # '%CONST' - name of a constant.
204 my $anon_struct_union = 0;
206 # match expressions used to find embedded type information
207 my $type_constant = '\%([-_\w]+)';
208 my $type_func = '(\w+)\(\)';
209 my $type_param = '\@(\w+)';
210 my $type_struct = '\&((struct\s*)*[_\w]+)';
211 my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
212 my $type_env = '(\$\w+)';
213 my $type_enum_full = '\&(enum)\s*([_\w]+)';
214 my $type_struct_full = '\&(struct)\s*([_\w]+)';
216 # Output conversion substitutions.
217 # One for each output format
219 # these work fairly well
220 my @highlights_html = (
221 [$type_constant, "<i>\$1</i>"],
222 [$type_func, "<b>\$1</b>"],
223 [$type_struct_xml, "<i>\$1</i>"],
224 [$type_env, "<b><i>\$1</i></b>"],
225 [$type_param, "<tt><b>\$1</b></tt>"]
227 my $local_lt = "\\\\\\\\lt:";
228 my $local_gt = "\\\\\\\\gt:";
229 my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
232 my @highlights_html5 = (
233 [$type_constant, "<span class=\"const\">\$1</span>"],
234 [$type_func, "<span class=\"func\">\$1</span>"],
235 [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
236 [$type_env, "<span class=\"env\">\$1</span>"],
237 [$type_param, "<span class=\"param\">\$1</span>]"]
239 my $blankline_html5 = $local_lt . "br /" . $local_gt;
241 # XML, docbook format
242 my @highlights_xml = (
243 ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
244 [$type_constant, "<constant>\$1</constant>"],
245 [$type_struct_xml, "<structname>\$1</structname>"],
246 [$type_param, "<parameter>\$1</parameter>"],
247 [$type_func, "<function>\$1</function>"],
248 [$type_env, "<envar>\$1</envar>"]
250 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
252 # gnome, docbook format
253 my @highlights_gnome = (
254 [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
255 [$type_func, "<function>\$1</function>"],
256 [$type_struct, "<structname>\$1</structname>"],
257 [$type_env, "<envar>\$1</envar>"],
258 [$type_param, "<parameter>\$1</parameter>" ]
260 my $blankline_gnome = "</para><para>\n";
262 # these are pretty rough
263 my @highlights_man = (
264 [$type_constant, "\$1"],
265 [$type_func, "\\\\fB\$1\\\\fP"],
266 [$type_struct, "\\\\fI\$1\\\\fP"],
267 [$type_param, "\\\\fI\$1\\\\fP"]
269 my $blankline_man = "";
272 my @highlights_text = (
273 [$type_constant, "\$1"],
275 [$type_struct, "\$1"],
278 my $blankline_text = "";
281 my @highlights_rst = (
282 [$type_constant, "``\$1``"],
283 [$type_func, "\\:c\\:func\\:`\$1`"],
284 [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
285 [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
286 [$type_struct, "\\:c\\:type\\:`struct \$1 <\$1>`"],
287 [$type_param, "**\$1**"]
289 my $blankline_rst = "\n";
292 my @highlights_list = (
293 [$type_constant, "\$1"],
295 [$type_struct, "\$1"],
298 my $blankline_list = "";
306 my $dohighlight = "";
309 my $output_mode = "man";
310 my $output_preformatted = 0;
311 my $no_doc_sections = 0;
312 my @highlights = @highlights_man;
313 my $blankline = $blankline_man;
314 my $modulename = "Kernel API";
317 OUTPUT_ALL => 0, # output all symbols and doc sections
318 OUTPUT_INCLUDE => 1, # output only specified symbols
319 OUTPUT_EXCLUDE => 2, # output everything except specified symbols
320 OUTPUT_EXPORTED => 3, # output exported symbols
321 OUTPUT_INTERNAL => 4, # output non-exported symbols
323 my $output_selection = OUTPUT_ALL;
324 my $show_not_found = 0;
327 if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
328 (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
329 @build_time = gmtime($seconds);
331 @build_time = localtime;
334 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
335 'July', 'August', 'September', 'October',
336 'November', 'December')[$build_time[4]] .
337 " " . ($build_time[5]+1900);
339 # Essentially these are globals.
340 # They probably want to be tidied up, made more localised or something.
341 # CAVEAT EMPTOR! Some of the others I localised may not want to be, which
342 # could cause "use of undefined value" or other bugs.
343 my ($function, %function_table, %parametertypes, $declaration_purpose);
344 my ($type, $declaration_name, $return_type);
345 my ($newsection, $newcontents, $prototype, $brcount, %source_map);
347 if (defined($ENV{'KBUILD_VERBOSE'})) {
348 $verbose = "$ENV{'KBUILD_VERBOSE'}";
351 # Generated docbook code is inserted in a template at a point where
352 # docbook v3.1 requires a non-zero sequence of RefEntry's; see:
353 # http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
354 # We keep track of number of generated entries and generate a dummy
355 # if needs be to ensure the expanded template can be postprocessed
357 my $section_counter = 0;
363 STATE_NORMAL => 0, # normal code
364 STATE_NAME => 1, # looking for function name
365 STATE_FIELD => 2, # scanning field start
366 STATE_PROTO => 3, # scanning prototype
367 STATE_DOCBLOCK => 4, # documentation block
368 STATE_INLINE => 5, # gathering documentation outside main block
373 # Inline documentation state
375 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
376 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
377 STATE_INLINE_TEXT => 2, # looking for member documentation
378 STATE_INLINE_END => 3, # done
379 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
380 # Spit a warning as it's not
381 # proper kernel-doc and ignore the rest.
383 my $inline_doc_state;
385 #declaration types: can be
386 # 'function', 'struct', 'union', 'enum', 'typedef'
389 my $doc_special = "\@\%\$\&";
391 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
393 my $doc_com = '\s*\*\s*';
394 my $doc_com_body = '\s*\* ?';
395 my $doc_decl = $doc_com . '(\w+)';
396 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
397 my $doc_content = $doc_com_body . '(.*)';
398 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
399 my $doc_inline_start = '^\s*/\*\*\s*$';
400 my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
401 my $doc_inline_end = '^\s*\*/\s*$';
402 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
413 my $section_default = "Description"; # default section
414 my $section_intro = "Introduction";
415 my $section = $section_default;
416 my $section_context = "Context";
417 my $section_return = "Return";
419 my $undescribed = "-- undescribed --";
423 while ($ARGV[0] =~ m/^-(.*)/) {
424 my $cmd = shift @ARGV;
425 if ($cmd eq "-html") {
426 $output_mode = "html";
427 @highlights = @highlights_html;
428 $blankline = $blankline_html;
429 } elsif ($cmd eq "-html5") {
430 $output_mode = "html5";
431 @highlights = @highlights_html5;
432 $blankline = $blankline_html5;
433 } elsif ($cmd eq "-man") {
434 $output_mode = "man";
435 @highlights = @highlights_man;
436 $blankline = $blankline_man;
437 } elsif ($cmd eq "-text") {
438 $output_mode = "text";
439 @highlights = @highlights_text;
440 $blankline = $blankline_text;
441 } elsif ($cmd eq "-rst") {
442 $output_mode = "rst";
443 @highlights = @highlights_rst;
444 $blankline = $blankline_rst;
445 } elsif ($cmd eq "-docbook") {
446 $output_mode = "xml";
447 @highlights = @highlights_xml;
448 $blankline = $blankline_xml;
449 } elsif ($cmd eq "-list") {
450 $output_mode = "list";
451 @highlights = @highlights_list;
452 $blankline = $blankline_list;
453 } elsif ($cmd eq "-gnome") {
454 $output_mode = "gnome";
455 @highlights = @highlights_gnome;
456 $blankline = $blankline_gnome;
457 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
458 $modulename = shift @ARGV;
459 } elsif ($cmd eq "-function") { # to only output specific functions
460 $output_selection = OUTPUT_INCLUDE;
461 $function = shift @ARGV;
462 $function_table{$function} = 1;
463 } elsif ($cmd eq "-nofunction") { # output all except specific functions
464 $output_selection = OUTPUT_EXCLUDE;
465 $function = shift @ARGV;
466 $function_table{$function} = 1;
467 } elsif ($cmd eq "-export") { # only exported symbols
468 $output_selection = OUTPUT_EXPORTED;
470 } elsif ($cmd eq "-internal") { # only non-exported symbols
471 $output_selection = OUTPUT_INTERNAL;
473 } elsif ($cmd eq "-v") {
475 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
477 } elsif ($cmd eq '-no-doc-sections') {
478 $no_doc_sections = 1;
479 } elsif ($cmd eq '-show-not-found') {
484 # continue execution near EOF;
486 # get kernel version from env
487 sub get_kernel_version() {
488 my $version = 'unknown kernel version';
490 if (defined($ENV{'KERNELVERSION'})) {
491 $version = $ENV{'KERNELVERSION'};
497 # dumps section contents to arrays/hashes intended for that purpose.
502 my $contents = join "\n", @_;
504 if ($name =~ m/$type_constant/) {
506 # print STDERR "constant section '$1' = '$contents'\n";
507 $constants{$name} = $contents;
508 } elsif ($name =~ m/$type_param/) {
509 # print STDERR "parameter def '$1' = '$contents'\n";
511 $parameterdescs{$name} = $contents;
512 $sectcheck = $sectcheck . $name . " ";
513 } elsif ($name eq "@\.\.\.") {
514 # print STDERR "parameter def '...' = '$contents'\n";
516 $parameterdescs{$name} = $contents;
517 $sectcheck = $sectcheck . $name . " ";
519 # print STDERR "other section '$name' = '$contents'\n";
520 if (defined($sections{$name}) && ($sections{$name} ne "")) {
521 print STDERR "${file}:$.: error: duplicate section name '$name'\n";
524 $sections{$name} = $contents;
525 push @sectionlist, $name;
530 # dump DOC: section after checking that it should go out
532 sub dump_doc_section {
535 my $contents = join "\n", @_;
537 if ($no_doc_sections) {
541 if (($output_selection == OUTPUT_ALL) ||
542 ($output_selection == OUTPUT_INCLUDE &&
543 defined($function_table{$name})) ||
544 ($output_selection == OUTPUT_EXCLUDE &&
545 !defined($function_table{$name})))
547 dump_section($file, $name, $contents);
548 output_blockhead({'sectionlist' => \@sectionlist,
549 'sections' => \%sections,
550 'module' => $modulename,
551 'content-only' => ($output_selection != OUTPUT_ALL), });
558 # parameterdescs, a hash.
559 # function => "function name"
560 # parameterlist => @list of parameters
561 # parameterdescs => %parameter descriptions
562 # sectionlist => @list of sections
563 # sections => %section descriptions
566 sub output_highlight {
567 my $contents = join "\n",@_;
571 # if (!defined $contents) {
573 # confess "output_highlight got called with no args?\n";
576 if ($output_mode eq "html" || $output_mode eq "html5" ||
577 $output_mode eq "xml") {
578 $contents = local_unescape($contents);
579 # convert data read & converted thru xml_escape() into &xyz; format:
580 $contents =~ s/\\\\\\/\&/g;
582 # print STDERR "contents b4:$contents\n";
585 # print STDERR "contents af:$contents\n";
587 # strip whitespaces when generating html5
588 if ($output_mode eq "html5") {
589 $contents =~ s/^\s+//;
590 $contents =~ s/\s+$//;
592 foreach $line (split "\n", $contents) {
593 if (! $output_preformatted) {
597 if (! $output_preformatted) {
598 print $lineprefix, local_unescape($blankline);
601 $line =~ s/\\\\\\/\&/g;
602 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
605 print $lineprefix, $line;
612 # output sections in html
613 sub output_section_html(%) {
617 foreach $section (@{$args{'sectionlist'}}) {
618 print "<h3>$section</h3>\n";
619 print "<blockquote>\n";
620 output_highlight($args{'sections'}{$section});
621 print "</blockquote>\n";
625 # output enum in html
626 sub output_enum_html(%) {
630 print "<h2>enum " . $args{'enum'} . "</h2>\n";
632 print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
634 foreach $parameter (@{$args{'parameterlist'}}) {
635 print " <b>" . $parameter . "</b>";
636 if ($count != $#{$args{'parameterlist'}}) {
644 print "<h3>Constants</h3>\n";
646 foreach $parameter (@{$args{'parameterlist'}}) {
647 print "<dt><b>" . $parameter . "</b>\n";
649 output_highlight($args{'parameterdescs'}{$parameter});
652 output_section_html(@_);
656 # output typedef in html
657 sub output_typedef_html(%) {
661 print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
663 print "<b>typedef " . $args{'typedef'} . "</b>\n";
664 output_section_html(@_);
668 # output struct in html
669 sub output_struct_html(%) {
673 print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
674 print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
675 foreach $parameter (@{$args{'parameterlist'}}) {
676 if ($parameter =~ /^#/) {
677 print "$parameter<br>\n";
680 my $parameter_name = $parameter;
681 $parameter_name =~ s/\[.*//;
683 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
684 $type = $args{'parametertypes'}{$parameter};
685 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
686 # pointer-to-function
687 print " <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
688 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
690 print " <i>$1</i> <b>$parameter</b>$2;<br>\n";
692 print " <i>$type</i> <b>$parameter</b>;<br>\n";
697 print "<h3>Members</h3>\n";
699 foreach $parameter (@{$args{'parameterlist'}}) {
700 ($parameter =~ /^#/) && next;
702 my $parameter_name = $parameter;
703 $parameter_name =~ s/\[.*//;
705 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
706 print "<dt><b>" . $parameter . "</b>\n";
708 output_highlight($args{'parameterdescs'}{$parameter_name});
711 output_section_html(@_);
715 # output function in html
716 sub output_function_html(%) {
718 my ($parameter, $section);
721 print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
722 print "<i>" . $args{'functiontype'} . "</i>\n";
723 print "<b>" . $args{'function'} . "</b>\n";
726 foreach $parameter (@{$args{'parameterlist'}}) {
727 $type = $args{'parametertypes'}{$parameter};
728 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
729 # pointer-to-function
730 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
732 print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
734 if ($count != $#{$args{'parameterlist'}}) {
741 print "<h3>Arguments</h3>\n";
743 foreach $parameter (@{$args{'parameterlist'}}) {
744 my $parameter_name = $parameter;
745 $parameter_name =~ s/\[.*//;
747 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
748 print "<dt><b>" . $parameter . "</b>\n";
750 output_highlight($args{'parameterdescs'}{$parameter_name});
753 output_section_html(@_);
757 # output DOC: block header in html
758 sub output_blockhead_html(%) {
760 my ($parameter, $section);
763 foreach $section (@{$args{'sectionlist'}}) {
764 print "<h3>$section</h3>\n";
766 output_highlight($args{'sections'}{$section});
772 # output sections in html5
773 sub output_section_html5(%) {
777 foreach $section (@{$args{'sectionlist'}}) {
779 print "<h1>$section</h1>\n";
781 output_highlight($args{'sections'}{$section});
783 print "</section>\n";
787 # output enum in html5
788 sub output_enum_html5(%) {
794 $html5id = $args{'enum'};
795 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
796 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
797 print "<h1>enum " . $args{'enum'} . "</h1>\n";
798 print "<ol class=\"code\">\n";
800 print "<span class=\"keyword\">enum</span> ";
801 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
804 foreach $parameter (@{$args{'parameterlist'}}) {
805 print "<li class=\"indent\">";
806 print "<span class=\"param\">" . $parameter . "</span>";
807 if ($count != $#{$args{'parameterlist'}}) {
813 print "<li>};</li>\n";
817 print "<h1>Constants</h1>\n";
819 foreach $parameter (@{$args{'parameterlist'}}) {
820 print "<dt>" . $parameter . "</dt>\n";
822 output_highlight($args{'parameterdescs'}{$parameter});
826 print "</section>\n";
827 output_section_html5(@_);
828 print "</article>\n";
831 # output typedef in html5
832 sub output_typedef_html5(%) {
838 $html5id = $args{'typedef'};
839 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
840 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
841 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
843 print "<ol class=\"code\">\n";
845 print "<span class=\"keyword\">typedef</span> ";
846 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
849 output_section_html5(@_);
850 print "</article>\n";
853 # output struct in html5
854 sub output_struct_html5(%) {
859 $html5id = $args{'struct'};
860 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
861 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
863 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
864 print "<h2>". $args{'purpose'} . "</h2>\n";
866 print "<ol class=\"code\">\n";
868 print "<span class=\"type\">" . $args{'type'} . "</span> ";
869 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
871 foreach $parameter (@{$args{'parameterlist'}}) {
872 print "<li class=\"indent\">";
873 if ($parameter =~ /^#/) {
874 print "<span class=\"param\">" . $parameter ."</span>\n";
878 my $parameter_name = $parameter;
879 $parameter_name =~ s/\[.*//;
881 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
882 $type = $args{'parametertypes'}{$parameter};
883 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
884 # pointer-to-function
885 print "<span class=\"type\">$1</span> ";
886 print "<span class=\"param\">$parameter</span>";
887 print "<span class=\"type\">)</span> ";
888 print "(<span class=\"args\">$2</span>);";
889 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
891 print "<span class=\"type\">$1</span> ";
892 print "<span class=\"param\">$parameter</span>";
893 print "<span class=\"bits\">$2</span>;";
895 print "<span class=\"type\">$type</span> ";
896 print "<span class=\"param\">$parameter</span>;";
900 print "<li>};</li>\n";
904 print "<h1>Members</h1>\n";
906 foreach $parameter (@{$args{'parameterlist'}}) {
907 ($parameter =~ /^#/) && next;
909 my $parameter_name = $parameter;
910 $parameter_name =~ s/\[.*//;
912 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
913 print "<dt>" . $parameter . "</dt>\n";
915 output_highlight($args{'parameterdescs'}{$parameter_name});
919 print "</section>\n";
920 output_section_html5(@_);
921 print "</article>\n";
924 # output function in html5
925 sub output_function_html5(%) {
927 my ($parameter, $section);
931 $html5id = $args{'function'};
932 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
933 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
935 print "<h1>" . $args{'function'} . "</h1>";
936 print "<h2>" . $args{'purpose'} . "</h2>\n";
938 print "<ol class=\"code\">\n";
940 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
941 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
944 foreach $parameter (@{$args{'parameterlist'}}) {
945 print "<li class=\"indent\">";
946 $type = $args{'parametertypes'}{$parameter};
947 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
948 # pointer-to-function
949 print "<span class=\"type\">$1</span> ";
950 print "<span class=\"param\">$parameter</span>";
951 print "<span class=\"type\">)</span> ";
952 print "(<span class=\"args\">$2</span>)";
954 print "<span class=\"type\">$type</span> ";
955 print "<span class=\"param\">$parameter</span>";
957 if ($count != $#{$args{'parameterlist'}}) {
963 print "<li>)</li>\n";
967 print "<h1>Arguments</h1>\n";
970 foreach $parameter (@{$args{'parameterlist'}}) {
971 my $parameter_name = $parameter;
972 $parameter_name =~ s/\[.*//;
974 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
975 print "<dt>" . $parameter . "</dt>\n";
977 output_highlight($args{'parameterdescs'}{$parameter_name});
981 print "</section>\n";
982 output_section_html5(@_);
983 print "</article>\n";
986 # output DOC: block header in html5
987 sub output_blockhead_html5(%) {
989 my ($parameter, $section);
993 foreach $section (@{$args{'sectionlist'}}) {
995 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
996 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
997 print "<h1>$section</h1>\n";
999 output_highlight($args{'sections'}{$section});
1002 print "</article>\n";
1005 sub output_section_xml(%) {
1006 my %args = %{$_[0]};
1008 # print out each section
1010 foreach $section (@{$args{'sectionlist'}}) {
1011 print "<refsect1>\n";
1012 print "<title>$section</title>\n";
1013 if ($section =~ m/EXAMPLE/i) {
1014 print "<informalexample><programlisting>\n";
1015 $output_preformatted = 1;
1019 output_highlight($args{'sections'}{$section});
1020 $output_preformatted = 0;
1021 if ($section =~ m/EXAMPLE/i) {
1022 print "</programlisting></informalexample>\n";
1026 print "</refsect1>\n";
1030 # output function in XML DocBook
1031 sub output_function_xml(%) {
1032 my %args = %{$_[0]};
1033 my ($parameter, $section);
1037 $id = "API-" . $args{'function'};
1038 $id =~ s/[^A-Za-z0-9]/-/g;
1040 print "<refentry id=\"$id\">\n";
1041 print "<refentryinfo>\n";
1042 print " <title>LINUX</title>\n";
1043 print " <productname>Kernel Hackers Manual</productname>\n";
1044 print " <date>$man_date</date>\n";
1045 print "</refentryinfo>\n";
1046 print "<refmeta>\n";
1047 print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
1048 print " <manvolnum>9</manvolnum>\n";
1049 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1050 print "</refmeta>\n";
1051 print "<refnamediv>\n";
1052 print " <refname>" . $args{'function'} . "</refname>\n";
1053 print " <refpurpose>\n";
1055 output_highlight ($args{'purpose'});
1056 print " </refpurpose>\n";
1057 print "</refnamediv>\n";
1059 print "<refsynopsisdiv>\n";
1060 print " <title>Synopsis</title>\n";
1061 print " <funcsynopsis><funcprototype>\n";
1062 print " <funcdef>" . $args{'functiontype'} . " ";
1063 print "<function>" . $args{'function'} . " </function></funcdef>\n";
1066 if ($#{$args{'parameterlist'}} >= 0) {
1067 foreach $parameter (@{$args{'parameterlist'}}) {
1068 $type = $args{'parametertypes'}{$parameter};
1069 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1070 # pointer-to-function
1071 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
1072 print " <funcparams>$2</funcparams></paramdef>\n";
1074 print " <paramdef>" . $type;
1075 print " <parameter>$parameter</parameter></paramdef>\n";
1081 print " </funcprototype></funcsynopsis>\n";
1082 print "</refsynopsisdiv>\n";
1085 print "<refsect1>\n <title>Arguments</title>\n";
1086 if ($#{$args{'parameterlist'}} >= 0) {
1087 print " <variablelist>\n";
1088 foreach $parameter (@{$args{'parameterlist'}}) {
1089 my $parameter_name = $parameter;
1090 $parameter_name =~ s/\[.*//;
1092 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1093 print " <listitem>\n <para>\n";
1095 output_highlight($args{'parameterdescs'}{$parameter_name});
1096 print " </para>\n </listitem>\n </varlistentry>\n";
1098 print " </variablelist>\n";
1100 print " <para>\n None\n </para>\n";
1102 print "</refsect1>\n";
1104 output_section_xml(@_);
1105 print "</refentry>\n\n";
1108 # output struct in XML DocBook
1109 sub output_struct_xml(%) {
1110 my %args = %{$_[0]};
1111 my ($parameter, $section);
1114 $id = "API-struct-" . $args{'struct'};
1115 $id =~ s/[^A-Za-z0-9]/-/g;
1117 print "<refentry id=\"$id\">\n";
1118 print "<refentryinfo>\n";
1119 print " <title>LINUX</title>\n";
1120 print " <productname>Kernel Hackers Manual</productname>\n";
1121 print " <date>$man_date</date>\n";
1122 print "</refentryinfo>\n";
1123 print "<refmeta>\n";
1124 print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
1125 print " <manvolnum>9</manvolnum>\n";
1126 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1127 print "</refmeta>\n";
1128 print "<refnamediv>\n";
1129 print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
1130 print " <refpurpose>\n";
1132 output_highlight ($args{'purpose'});
1133 print " </refpurpose>\n";
1134 print "</refnamediv>\n";
1136 print "<refsynopsisdiv>\n";
1137 print " <title>Synopsis</title>\n";
1138 print " <programlisting>\n";
1139 print $args{'type'} . " " . $args{'struct'} . " {\n";
1140 foreach $parameter (@{$args{'parameterlist'}}) {
1141 if ($parameter =~ /^#/) {
1142 my $prm = $parameter;
1143 # convert data read & converted thru xml_escape() into &xyz; format:
1144 # This allows us to have #define macros interspersed in a struct.
1145 $prm =~ s/\\\\\\/\&/g;
1150 my $parameter_name = $parameter;
1151 $parameter_name =~ s/\[.*//;
1153 defined($args{'parameterdescs'}{$parameter_name}) || next;
1154 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1155 $type = $args{'parametertypes'}{$parameter};
1156 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1157 # pointer-to-function
1158 print " $1 $parameter) ($2);\n";
1159 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1161 print " $1 $parameter$2;\n";
1163 print " " . $type . " " . $parameter . ";\n";
1167 print " </programlisting>\n";
1168 print "</refsynopsisdiv>\n";
1170 print " <refsect1>\n";
1171 print " <title>Members</title>\n";
1173 if ($#{$args{'parameterlist'}} >= 0) {
1174 print " <variablelist>\n";
1175 foreach $parameter (@{$args{'parameterlist'}}) {
1176 ($parameter =~ /^#/) && next;
1178 my $parameter_name = $parameter;
1179 $parameter_name =~ s/\[.*//;
1181 defined($args{'parameterdescs'}{$parameter_name}) || next;
1182 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1183 print " <varlistentry>";
1184 print " <term>$parameter</term>\n";
1185 print " <listitem><para>\n";
1186 output_highlight($args{'parameterdescs'}{$parameter_name});
1187 print " </para></listitem>\n";
1188 print " </varlistentry>\n";
1190 print " </variablelist>\n";
1192 print " <para>\n None\n </para>\n";
1194 print " </refsect1>\n";
1196 output_section_xml(@_);
1198 print "</refentry>\n\n";
1201 # output enum in XML DocBook
1202 sub output_enum_xml(%) {
1203 my %args = %{$_[0]};
1204 my ($parameter, $section);
1208 $id = "API-enum-" . $args{'enum'};
1209 $id =~ s/[^A-Za-z0-9]/-/g;
1211 print "<refentry id=\"$id\">\n";
1212 print "<refentryinfo>\n";
1213 print " <title>LINUX</title>\n";
1214 print " <productname>Kernel Hackers Manual</productname>\n";
1215 print " <date>$man_date</date>\n";
1216 print "</refentryinfo>\n";
1217 print "<refmeta>\n";
1218 print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
1219 print " <manvolnum>9</manvolnum>\n";
1220 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1221 print "</refmeta>\n";
1222 print "<refnamediv>\n";
1223 print " <refname>enum " . $args{'enum'} . "</refname>\n";
1224 print " <refpurpose>\n";
1226 output_highlight ($args{'purpose'});
1227 print " </refpurpose>\n";
1228 print "</refnamediv>\n";
1230 print "<refsynopsisdiv>\n";
1231 print " <title>Synopsis</title>\n";
1232 print " <programlisting>\n";
1233 print "enum " . $args{'enum'} . " {\n";
1235 foreach $parameter (@{$args{'parameterlist'}}) {
1236 print " $parameter";
1237 if ($count != $#{$args{'parameterlist'}}) {
1244 print " </programlisting>\n";
1245 print "</refsynopsisdiv>\n";
1247 print "<refsect1>\n";
1248 print " <title>Constants</title>\n";
1249 print " <variablelist>\n";
1250 foreach $parameter (@{$args{'parameterlist'}}) {
1251 my $parameter_name = $parameter;
1252 $parameter_name =~ s/\[.*//;
1254 print " <varlistentry>";
1255 print " <term>$parameter</term>\n";
1256 print " <listitem><para>\n";
1257 output_highlight($args{'parameterdescs'}{$parameter_name});
1258 print " </para></listitem>\n";
1259 print " </varlistentry>\n";
1261 print " </variablelist>\n";
1262 print "</refsect1>\n";
1264 output_section_xml(@_);
1266 print "</refentry>\n\n";
1269 # output typedef in XML DocBook
1270 sub output_typedef_xml(%) {
1271 my %args = %{$_[0]};
1272 my ($parameter, $section);
1275 $id = "API-typedef-" . $args{'typedef'};
1276 $id =~ s/[^A-Za-z0-9]/-/g;
1278 print "<refentry id=\"$id\">\n";
1279 print "<refentryinfo>\n";
1280 print " <title>LINUX</title>\n";
1281 print " <productname>Kernel Hackers Manual</productname>\n";
1282 print " <date>$man_date</date>\n";
1283 print "</refentryinfo>\n";
1284 print "<refmeta>\n";
1285 print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
1286 print " <manvolnum>9</manvolnum>\n";
1287 print "</refmeta>\n";
1288 print "<refnamediv>\n";
1289 print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
1290 print " <refpurpose>\n";
1292 output_highlight ($args{'purpose'});
1293 print " </refpurpose>\n";
1294 print "</refnamediv>\n";
1296 print "<refsynopsisdiv>\n";
1297 print " <title>Synopsis</title>\n";
1298 print " <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
1299 print "</refsynopsisdiv>\n";
1301 output_section_xml(@_);
1303 print "</refentry>\n\n";
1306 # output in XML DocBook
1307 sub output_blockhead_xml(%) {
1308 my %args = %{$_[0]};
1309 my ($parameter, $section);
1312 my $id = $args{'module'};
1313 $id =~ s/[^A-Za-z0-9]/-/g;
1315 # print out each section
1317 foreach $section (@{$args{'sectionlist'}}) {
1318 if (!$args{'content-only'}) {
1319 print "<refsect1>\n <title>$section</title>\n";
1321 if ($section =~ m/EXAMPLE/i) {
1322 print "<example><para>\n";
1323 $output_preformatted = 1;
1327 output_highlight($args{'sections'}{$section});
1328 $output_preformatted = 0;
1329 if ($section =~ m/EXAMPLE/i) {
1330 print "</para></example>\n";
1334 if (!$args{'content-only'}) {
1335 print "\n</refsect1>\n";
1342 # output in XML DocBook
1343 sub output_function_gnome {
1344 my %args = %{$_[0]};
1345 my ($parameter, $section);
1349 $id = $args{'module'} . "-" . $args{'function'};
1350 $id =~ s/[^A-Za-z0-9]/-/g;
1353 print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
1355 print " <funcsynopsis>\n";
1356 print " <funcdef>" . $args{'functiontype'} . " ";
1357 print "<function>" . $args{'function'} . " ";
1358 print "</function></funcdef>\n";
1361 if ($#{$args{'parameterlist'}} >= 0) {
1362 foreach $parameter (@{$args{'parameterlist'}}) {
1363 $type = $args{'parametertypes'}{$parameter};
1364 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1365 # pointer-to-function
1366 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
1367 print " <funcparams>$2</funcparams></paramdef>\n";
1369 print " <paramdef>" . $type;
1370 print " <parameter>$parameter</parameter></paramdef>\n";
1376 print " </funcsynopsis>\n";
1377 if ($#{$args{'parameterlist'}} >= 0) {
1378 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1379 print "<tgroup cols=\"2\">\n";
1380 print "<colspec colwidth=\"2*\">\n";
1381 print "<colspec colwidth=\"8*\">\n";
1383 foreach $parameter (@{$args{'parameterlist'}}) {
1384 my $parameter_name = $parameter;
1385 $parameter_name =~ s/\[.*//;
1387 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1390 output_highlight($args{'parameterdescs'}{$parameter_name});
1391 print " </entry></row>\n";
1393 print " </tbody></tgroup></informaltable>\n";
1395 print " <para>\n None\n </para>\n";
1398 # print out each section
1400 foreach $section (@{$args{'sectionlist'}}) {
1401 print "<simplesect>\n <title>$section</title>\n";
1402 if ($section =~ m/EXAMPLE/i) {
1403 print "<example><programlisting>\n";
1404 $output_preformatted = 1;
1408 output_highlight($args{'sections'}{$section});
1409 $output_preformatted = 0;
1411 if ($section =~ m/EXAMPLE/i) {
1412 print "</programlisting></example>\n";
1415 print " </simplesect>\n";
1418 print "</sect2>\n\n";
1422 # output function in man
1423 sub output_function_man(%) {
1424 my %args = %{$_[0]};
1425 my ($parameter, $section);
1428 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1431 print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
1433 print ".SH SYNOPSIS\n";
1434 if ($args{'functiontype'} ne "") {
1435 print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1437 print ".B \"" . $args{'function'} . "\n";
1442 foreach my $parameter (@{$args{'parameterlist'}}) {
1443 if ($count == $#{$args{'parameterlist'}}) {
1446 $type = $args{'parametertypes'}{$parameter};
1447 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1448 # pointer-to-function
1449 print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
1451 $type =~ s/([^\*])$/$1 /;
1452 print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
1458 print ".SH ARGUMENTS\n";
1459 foreach $parameter (@{$args{'parameterlist'}}) {
1460 my $parameter_name = $parameter;
1461 $parameter_name =~ s/\[.*//;
1463 print ".IP \"" . $parameter . "\" 12\n";
1464 output_highlight($args{'parameterdescs'}{$parameter_name});
1466 foreach $section (@{$args{'sectionlist'}}) {
1467 print ".SH \"", uc $section, "\"\n";
1468 output_highlight($args{'sections'}{$section});
1473 # output enum in man
1474 sub output_enum_man(%) {
1475 my %args = %{$_[0]};
1476 my ($parameter, $section);
1479 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1482 print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
1484 print ".SH SYNOPSIS\n";
1485 print "enum " . $args{'enum'} . " {\n";
1487 foreach my $parameter (@{$args{'parameterlist'}}) {
1488 print ".br\n.BI \" $parameter\"\n";
1489 if ($count == $#{$args{'parameterlist'}}) {
1499 print ".SH Constants\n";
1500 foreach $parameter (@{$args{'parameterlist'}}) {
1501 my $parameter_name = $parameter;
1502 $parameter_name =~ s/\[.*//;
1504 print ".IP \"" . $parameter . "\" 12\n";
1505 output_highlight($args{'parameterdescs'}{$parameter_name});
1507 foreach $section (@{$args{'sectionlist'}}) {
1508 print ".SH \"$section\"\n";
1509 output_highlight($args{'sections'}{$section});
1514 # output struct in man
1515 sub output_struct_man(%) {
1516 my %args = %{$_[0]};
1517 my ($parameter, $section);
1519 print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
1522 print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
1524 print ".SH SYNOPSIS\n";
1525 print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
1527 foreach my $parameter (@{$args{'parameterlist'}}) {
1528 if ($parameter =~ /^#/) {
1529 print ".BI \"$parameter\"\n.br\n";
1532 my $parameter_name = $parameter;
1533 $parameter_name =~ s/\[.*//;
1535 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1536 $type = $args{'parametertypes'}{$parameter};
1537 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1538 # pointer-to-function
1539 print ".BI \" " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
1540 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1542 print ".BI \" " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
1544 $type =~ s/([^\*])$/$1 /;
1545 print ".BI \" " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
1551 print ".SH Members\n";
1552 foreach $parameter (@{$args{'parameterlist'}}) {
1553 ($parameter =~ /^#/) && next;
1555 my $parameter_name = $parameter;
1556 $parameter_name =~ s/\[.*//;
1558 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1559 print ".IP \"" . $parameter . "\" 12\n";
1560 output_highlight($args{'parameterdescs'}{$parameter_name});
1562 foreach $section (@{$args{'sectionlist'}}) {
1563 print ".SH \"$section\"\n";
1564 output_highlight($args{'sections'}{$section});
1569 # output typedef in man
1570 sub output_typedef_man(%) {
1571 my %args = %{$_[0]};
1572 my ($parameter, $section);
1574 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1577 print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
1579 foreach $section (@{$args{'sectionlist'}}) {
1580 print ".SH \"$section\"\n";
1581 output_highlight($args{'sections'}{$section});
1585 sub output_blockhead_man(%) {
1586 my %args = %{$_[0]};
1587 my ($parameter, $section);
1590 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1592 foreach $section (@{$args{'sectionlist'}}) {
1593 print ".SH \"$section\"\n";
1594 output_highlight($args{'sections'}{$section});
1600 sub output_function_text(%) {
1601 my %args = %{$_[0]};
1602 my ($parameter, $section);
1606 print $args{'function'} . " - " . $args{'purpose'} . "\n";
1608 print "\nSynopsis:\n\n";
1609 if ($args{'functiontype'} ne "") {
1610 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1612 $start = $args{'function'} . " (";
1617 foreach my $parameter (@{$args{'parameterlist'}}) {
1618 $type = $args{'parametertypes'}{$parameter};
1619 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1620 # pointer-to-function
1621 print $1 . $parameter . ") (" . $2;
1623 print $type . " " . $parameter;
1625 if ($count != $#{$args{'parameterlist'}}) {
1628 print " " x length($start);
1634 print "Arguments:\n\n";
1635 foreach $parameter (@{$args{'parameterlist'}}) {
1636 my $parameter_name = $parameter;
1637 $parameter_name =~ s/\[.*//;
1639 print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
1641 output_section_text(@_);
1644 #output sections in text
1645 sub output_section_text(%) {
1646 my %args = %{$_[0]};
1650 foreach $section (@{$args{'sectionlist'}}) {
1651 print "$section:\n\n";
1652 output_highlight($args{'sections'}{$section});
1657 # output enum in text
1658 sub output_enum_text(%) {
1659 my %args = %{$_[0]};
1664 print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
1665 print "enum " . $args{'enum'} . " {\n";
1667 foreach $parameter (@{$args{'parameterlist'}}) {
1668 print "\t$parameter";
1669 if ($count != $#{$args{'parameterlist'}}) {
1677 print "Constants:\n\n";
1678 foreach $parameter (@{$args{'parameterlist'}}) {
1679 print "$parameter\n\t";
1680 print $args{'parameterdescs'}{$parameter} . "\n";
1683 output_section_text(@_);
1686 # output typedef in text
1687 sub output_typedef_text(%) {
1688 my %args = %{$_[0]};
1691 print "Typedef:\n\n";
1693 print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
1694 output_section_text(@_);
1697 # output struct as text
1698 sub output_struct_text(%) {
1699 my %args = %{$_[0]};
1702 print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
1703 print $args{'type'} . " " . $args{'struct'} . " {\n";
1704 foreach $parameter (@{$args{'parameterlist'}}) {
1705 if ($parameter =~ /^#/) {
1706 print "$parameter\n";
1710 my $parameter_name = $parameter;
1711 $parameter_name =~ s/\[.*//;
1713 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1714 $type = $args{'parametertypes'}{$parameter};
1715 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1716 # pointer-to-function
1717 print "\t$1 $parameter) ($2);\n";
1718 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1720 print "\t$1 $parameter$2;\n";
1722 print "\t" . $type . " " . $parameter . ";\n";
1727 print "Members:\n\n";
1728 foreach $parameter (@{$args{'parameterlist'}}) {
1729 ($parameter =~ /^#/) && next;
1731 my $parameter_name = $parameter;
1732 $parameter_name =~ s/\[.*//;
1734 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1735 print "$parameter\n\t";
1736 print $args{'parameterdescs'}{$parameter_name} . "\n";
1739 output_section_text(@_);
1742 sub output_blockhead_text(%) {
1743 my %args = %{$_[0]};
1744 my ($parameter, $section);
1746 foreach $section (@{$args{'sectionlist'}}) {
1747 print " $section:\n";
1749 output_highlight($args{'sections'}{$section});
1754 # output in restructured text
1758 # This could use some work; it's used to output the DOC: sections, and
1759 # starts by putting out the name of the doc section itself, but that tends
1760 # to duplicate a header already in the template file.
1762 sub output_blockhead_rst(%) {
1763 my %args = %{$_[0]};
1764 my ($parameter, $section);
1766 foreach $section (@{$args{'sectionlist'}}) {
1767 if ($output_selection != OUTPUT_INCLUDE) {
1768 print "**$section**\n\n";
1770 output_highlight_rst($args{'sections'}{$section});
1775 sub output_highlight_rst {
1776 my $contents = join "\n",@_;
1779 # undo the evil effects of xml_escape() earlier
1780 $contents = xml_unescape($contents);
1785 foreach $line (split "\n", $contents) {
1787 print $lineprefix, $blankline;
1789 $line =~ s/\\\\\\/\&/g;
1790 print $lineprefix, $line;
1796 sub output_function_rst(%) {
1797 my %args = %{$_[0]};
1798 my ($parameter, $section);
1801 print ".. c:function:: ";
1802 if ($args{'functiontype'} ne "") {
1803 $start = $args{'functiontype'} . " " . $args{'function'} . " (";
1805 $start = $args{'function'} . " (";
1810 foreach my $parameter (@{$args{'parameterlist'}}) {
1815 $type = $args{'parametertypes'}{$parameter};
1816 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1817 # pointer-to-function
1818 print $1 . $parameter . ") (" . $2;
1820 print $type . " " . $parameter;
1823 print ")\n\n " . $args{'purpose'} . "\n\n";
1825 print ":Parameters:\n\n";
1826 foreach $parameter (@{$args{'parameterlist'}}) {
1827 my $parameter_name = $parameter;
1828 #$parameter_name =~ s/\[.*//;
1829 $type = $args{'parametertypes'}{$parameter};
1832 print " ``$type $parameter``\n";
1834 print " ``$parameter``\n";
1836 if (defined($args{'parameterdescs'}{$parameter_name}) &&
1837 $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
1838 my $oldprefix = $lineprefix;
1840 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1841 $lineprefix = $oldprefix;
1843 print "\n _undescribed_\n";
1847 output_section_rst(@_);
1850 sub output_section_rst(%) {
1851 my %args = %{$_[0]};
1853 my $oldprefix = $lineprefix;
1856 foreach $section (@{$args{'sectionlist'}}) {
1857 print ":$section:\n\n";
1858 output_highlight_rst($args{'sections'}{$section});
1862 $lineprefix = $oldprefix;
1865 sub output_enum_rst(%) {
1866 my %args = %{$_[0]};
1869 my $name = "enum " . $args{'enum'};
1871 print "\n\n.. c:type:: " . $name . "\n\n";
1872 print " " . $args{'purpose'} . "\n\n";
1874 print "..\n\n:Constants:\n\n";
1875 my $oldprefix = $lineprefix;
1877 foreach $parameter (@{$args{'parameterlist'}}) {
1878 print " `$parameter`\n";
1879 if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
1880 output_highlight_rst($args{'parameterdescs'}{$parameter});
1882 print " undescribed\n";
1886 $lineprefix = $oldprefix;
1887 output_section_rst(@_);
1890 sub output_typedef_rst(%) {
1891 my %args = %{$_[0]};
1894 my $name = "typedef " . $args{'typedef'};
1896 ### FIXME: should the name below contain "typedef" or not?
1897 print "\n\n.. c:type:: " . $name . "\n\n";
1898 print " " . $args{'purpose'} . "\n\n";
1900 output_section_rst(@_);
1903 sub output_struct_rst(%) {
1904 my %args = %{$_[0]};
1906 my $name = $args{'type'} . " " . $args{'struct'};
1908 print "\n\n.. c:type:: " . $name . "\n\n";
1909 print " " . $args{'purpose'} . "\n\n";
1911 print ":Definition:\n\n";
1913 print " " . $args{'type'} . " " . $args{'struct'} . " {\n";
1914 foreach $parameter (@{$args{'parameterlist'}}) {
1915 if ($parameter =~ /^#/) {
1916 print " " . "$parameter\n";
1920 my $parameter_name = $parameter;
1921 $parameter_name =~ s/\[.*//;
1923 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1924 $type = $args{'parametertypes'}{$parameter};
1925 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1926 # pointer-to-function
1927 print " $1 $parameter) ($2);\n";
1928 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1930 print " $1 $parameter$2;\n";
1932 print " " . $type . " " . $parameter . ";\n";
1937 print ":Members:\n\n";
1938 foreach $parameter (@{$args{'parameterlist'}}) {
1939 ($parameter =~ /^#/) && next;
1941 my $parameter_name = $parameter;
1942 $parameter_name =~ s/\[.*//;
1944 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1945 $type = $args{'parametertypes'}{$parameter};
1946 print " `$type $parameter`" . "\n";
1947 my $oldprefix = $lineprefix;
1949 output_highlight_rst($args{'parameterdescs'}{$parameter_name});
1950 $lineprefix = $oldprefix;
1954 output_section_rst(@_);
1958 ## list mode output functions
1960 sub output_function_list(%) {
1961 my %args = %{$_[0]};
1963 print $args{'function'} . "\n";
1966 # output enum in list
1967 sub output_enum_list(%) {
1968 my %args = %{$_[0]};
1969 print $args{'enum'} . "\n";
1972 # output typedef in list
1973 sub output_typedef_list(%) {
1974 my %args = %{$_[0]};
1975 print $args{'typedef'} . "\n";
1978 # output struct as list
1979 sub output_struct_list(%) {
1980 my %args = %{$_[0]};
1982 print $args{'struct'} . "\n";
1985 sub output_blockhead_list(%) {
1986 my %args = %{$_[0]};
1987 my ($parameter, $section);
1989 foreach $section (@{$args{'sectionlist'}}) {
1990 print "DOC: $section\n";
1995 # generic output function for all types (function, struct/union, typedef, enum);
1996 # calls the generated, variable output_ function name based on
1997 # functype and output_mode
1998 sub output_declaration {
2001 my $functype = shift;
2002 my $func = "output_${functype}_$output_mode";
2003 if (($output_selection == OUTPUT_ALL) ||
2004 (($output_selection == OUTPUT_INCLUDE ||
2005 $output_selection == OUTPUT_EXPORTED) &&
2006 defined($function_table{$name})) ||
2007 (($output_selection == OUTPUT_EXCLUDE ||
2008 $output_selection == OUTPUT_INTERNAL) &&
2009 !($functype eq "function" && defined($function_table{$name}))))
2017 # generic output function - calls the right one based on current output mode.
2018 sub output_blockhead {
2020 my $func = "output_blockhead_" . $output_mode;
2026 # takes a declaration (struct, union, enum, typedef) and
2027 # invokes the right handler. NOT called for functions.
2028 sub dump_declaration($$) {
2030 my ($prototype, $file) = @_;
2031 my $func = "dump_" . $decl_type;
2035 sub dump_union($$) {
2039 sub dump_struct($$) {
2044 if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
2045 #my $decl_type = $1;
2046 $declaration_name = $2;
2049 # ignore embedded structs or unions
2050 $members =~ s/({.*})//g;
2053 # ignore members marked private:
2054 $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
2055 $members =~ s/\/\*\s*private:.*//gosi;
2057 $members =~ s/\/\*.*?\*\///gos;
2058 $nested =~ s/\/\*.*?\*\///gos;
2059 # strip kmemcheck_bitfield_{begin,end}.*;
2060 $members =~ s/kmemcheck_bitfield_.*?;//gos;
2062 $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2063 $members =~ s/__aligned\s*\([^;]*\)//gos;
2064 $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
2065 # replace DECLARE_BITMAP
2066 $members =~ s/DECLARE_BITMAP\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
2068 create_parameterlist($members, ';', $file);
2069 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
2071 output_declaration($declaration_name,
2073 {'struct' => $declaration_name,
2074 'module' => $modulename,
2075 'parameterlist' => \@parameterlist,
2076 'parameterdescs' => \%parameterdescs,
2077 'parametertypes' => \%parametertypes,
2078 'sectionlist' => \@sectionlist,
2079 'sections' => \%sections,
2080 'purpose' => $declaration_purpose,
2081 'type' => $decl_type
2085 print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
2094 $x =~ s@/\*.*?\*/@@gos; # strip comments.
2095 # strip #define macros inside enums
2096 $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
2098 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
2099 $declaration_name = $1;
2102 foreach my $arg (split ',', $members) {
2103 $arg =~ s/^\s*(\w+).*/$1/;
2104 push @parameterlist, $arg;
2105 if (!$parameterdescs{$arg}) {
2106 $parameterdescs{$arg} = $undescribed;
2107 print STDERR "${file}:$.: warning: Enum value '$arg' ".
2108 "not described in enum '$declaration_name'\n";
2113 output_declaration($declaration_name,
2115 {'enum' => $declaration_name,
2116 'module' => $modulename,
2117 'parameterlist' => \@parameterlist,
2118 'parameterdescs' => \%parameterdescs,
2119 'sectionlist' => \@sectionlist,
2120 'sections' => \%sections,
2121 'purpose' => $declaration_purpose
2125 print STDERR "${file}:$.: error: Cannot parse enum!\n";
2130 sub dump_typedef($$) {
2134 $x =~ s@/\*.*?\*/@@gos; # strip comments.
2136 # Parse function prototypes
2137 if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
2140 $declaration_name = $2;
2143 create_parameterlist($args, ',', $file);
2145 output_declaration($declaration_name,
2147 {'function' => $declaration_name,
2148 'module' => $modulename,
2149 'functiontype' => $return_type,
2150 'parameterlist' => \@parameterlist,
2151 'parameterdescs' => \%parameterdescs,
2152 'parametertypes' => \%parametertypes,
2153 'sectionlist' => \@sectionlist,
2154 'sections' => \%sections,
2155 'purpose' => $declaration_purpose
2160 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
2161 $x =~ s/\(*.\)\s*;$/;/;
2162 $x =~ s/\[*.\]\s*;$/;/;
2165 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
2166 $declaration_name = $1;
2168 output_declaration($declaration_name,
2170 {'typedef' => $declaration_name,
2171 'module' => $modulename,
2172 'sectionlist' => \@sectionlist,
2173 'sections' => \%sections,
2174 'purpose' => $declaration_purpose
2178 print STDERR "${file}:$.: error: Cannot parse typedef!\n";
2183 sub save_struct_actual($) {
2186 # strip all spaces from the actual param so that it looks like one string item
2187 $actual =~ s/\s*//g;
2188 $struct_actual = $struct_actual . $actual . " ";
2191 sub create_parameterlist($$$) {
2193 my $splitter = shift;
2198 # temporarily replace commas inside function pointer definition
2199 while ($args =~ /(\([^\),]+),/) {
2200 $args =~ s/(\([^\),]+),/$1#/g;
2203 foreach my $arg (split($splitter, $args)) {
2205 $arg =~ s/\/\*.*\*\///;
2206 # strip leading/trailing spaces
2212 # Treat preprocessor directive as a typeless variable just to fill
2213 # corresponding data structures "correctly". Catch it later in
2215 push_parameter($arg, "", $file);
2216 } elsif ($arg =~ m/\(.+\)\s*\(/) {
2217 # pointer-to-function
2219 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
2222 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
2223 save_struct_actual($param);
2224 push_parameter($param, $type, $file);
2226 $arg =~ s/\s*:\s*/:/g;
2227 $arg =~ s/\s*\[/\[/g;
2229 my @args = split('\s*,\s*', $arg);
2230 if ($args[0] =~ m/\*/) {
2231 $args[0] =~ s/(\*+)\s*/ $1/;
2235 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
2237 push(@first_arg, split('\s+', $1));
2238 push(@first_arg, $2);
2240 @first_arg = split('\s+', shift @args);
2243 unshift(@args, pop @first_arg);
2244 $type = join " ", @first_arg;
2246 foreach $param (@args) {
2247 if ($param =~ m/^(\*+)\s*(.*)/) {
2248 save_struct_actual($2);
2249 push_parameter($2, "$type $1", $file);
2251 elsif ($param =~ m/(.*?):(\d+)/) {
2252 if ($type ne "") { # skip unnamed bit-fields
2253 save_struct_actual($1);
2254 push_parameter($1, "$type:$2", $file)
2258 save_struct_actual($param);
2259 push_parameter($param, $type, $file);
2266 sub push_parameter($$$) {
2271 if (($anon_struct_union == 1) && ($type eq "") &&
2273 return; # ignore the ending }; from anon. struct/union
2276 $anon_struct_union = 0;
2277 my $param_name = $param;
2278 $param_name =~ s/\[.*//;
2280 if ($type eq "" && $param =~ /\.\.\.$/)
2282 if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
2283 $parameterdescs{$param} = "variable arguments";
2286 elsif ($type eq "" && ($param eq "" or $param eq "void"))
2289 $parameterdescs{void} = "no arguments";
2291 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
2292 # handle unnamed (anonymous) union or struct:
2295 $param = "{unnamed_" . $param . "}";
2296 $parameterdescs{$param} = "anonymous\n";
2297 $anon_struct_union = 1;
2300 # warn if parameter has no description
2301 # (but ignore ones starting with # as these are not parameters
2302 # but inline preprocessor statements);
2303 # also ignore unnamed structs/unions;
2304 if (!$anon_struct_union) {
2305 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
2307 $parameterdescs{$param_name} = $undescribed;
2309 if (($type eq 'function') || ($type eq 'enum')) {
2310 print STDERR "${file}:$.: warning: Function parameter ".
2311 "or member '$param' not " .
2312 "described in '$declaration_name'\n";
2314 print STDERR "${file}:$.: warning:" .
2315 " No description found for parameter '$param'\n";
2320 $param = xml_escape($param);
2322 # strip spaces from $param so that it is one continuous string
2323 # on @parameterlist;
2324 # this fixes a problem where check_sections() cannot find
2325 # a parameter like "addr[6 + 2]" because it actually appears
2326 # as "addr[6", "+", "2]" on the parameter list;
2327 # but it's better to maintain the param string unchanged for output,
2328 # so just weaken the string compare in check_sections() to ignore
2329 # "[blah" in a parameter string;
2330 ###$param =~ s/\s*//g;
2331 push @parameterlist, $param;
2332 $parametertypes{$param} = $type;
2335 sub check_sections($$$$$$) {
2336 my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
2337 my @sects = split ' ', $sectcheck;
2338 my @prms = split ' ', $prmscheck;
2341 my $prm_clean; # strip trailing "[array size]" and/or beginning "*"
2343 foreach $sx (0 .. $#sects) {
2345 foreach $px (0 .. $#prms) {
2346 $prm_clean = $prms[$px];
2347 $prm_clean =~ s/\[.*\]//;
2348 $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
2349 # ignore array size in a parameter string;
2350 # however, the original param string may contain
2351 # spaces, e.g.: addr[6 + 2]
2352 # and this appears in @prms as "addr[6" since the
2353 # parameter list is split at spaces;
2354 # hence just ignore "[..." for the sections check;
2355 $prm_clean =~ s/\[.*//;
2357 ##$prm_clean =~ s/^\**//;
2358 if ($prm_clean eq $sects[$sx]) {
2364 if ($decl_type eq "function") {
2365 print STDERR "${file}:$.: warning: " .
2366 "Excess function parameter " .
2368 "description in '$decl_name'\n";
2371 if ($nested !~ m/\Q$sects[$sx]\E/) {
2372 print STDERR "${file}:$.: warning: " .
2373 "Excess struct/union/enum/typedef member " .
2375 "description in '$decl_name'\n";
2384 # Checks the section describing the return value of a function.
2385 sub check_return_section {
2387 my $declaration_name = shift;
2388 my $return_type = shift;
2390 # Ignore an empty return type (It's a macro)
2391 # Ignore functions with a "void" return type. (But don't ignore "void *")
2392 if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
2396 if (!defined($sections{$section_return}) ||
2397 $sections{$section_return} eq "") {
2398 print STDERR "${file}:$.: warning: " .
2399 "No description found for return value of " .
2400 "'$declaration_name'\n";
2406 # takes a function prototype and the name of the current file being
2407 # processed and spits out all the details stored in the global
2409 sub dump_function($$) {
2410 my $prototype = shift;
2414 $prototype =~ s/^static +//;
2415 $prototype =~ s/^extern +//;
2416 $prototype =~ s/^asmlinkage +//;
2417 $prototype =~ s/^inline +//;
2418 $prototype =~ s/^__inline__ +//;
2419 $prototype =~ s/^__inline +//;
2420 $prototype =~ s/^__always_inline +//;
2421 $prototype =~ s/^noinline +//;
2422 $prototype =~ s/__init +//;
2423 $prototype =~ s/__init_or_module +//;
2424 $prototype =~ s/__meminit +//;
2425 $prototype =~ s/__must_check +//;
2426 $prototype =~ s/__weak +//;
2427 my $define = $prototype =~ s/^#\s*define\s+//; #ak added
2428 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2430 # Yes, this truly is vile. We are looking for:
2431 # 1. Return type (may be nothing if we're looking at a macro)
2433 # 3. Function parameters.
2435 # All the while we have to watch out for function pointer parameters
2436 # (which IIRC is what the two sections are for), C types (these
2437 # regexps don't even start to express all the possibilities), and
2440 # If you mess with these regexps, it's a good idea to check that
2441 # the following functions' documentation still comes out right:
2442 # - parport_register_device (function pointer parameters)
2443 # - atomic_set (macro)
2444 # - pci_match_device, __copy_to_user (long return type)
2446 if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) {
2447 # This is an object-like macro, it has no return type and no parameter
2449 # Function-like macros are not allowed to have spaces between
2450 # declaration_name and opening parenthesis (notice the \s+).
2452 $declaration_name = $2;
2454 } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2455 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2456 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2457 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2458 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2459 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2460 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
2461 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2462 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2463 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2464 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2465 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2466 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2467 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2468 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2469 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
2470 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
2472 $declaration_name = $2;
2475 create_parameterlist($args, ',', $file);
2477 print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n";
2481 my $prms = join " ", @parameterlist;
2482 check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");
2484 # This check emits a lot of warnings at the moment, because many
2485 # functions don't have a 'Return' doc section. So until the number
2486 # of warnings goes sufficiently down, the check is only performed in
2488 # TODO: always perform the check.
2489 if ($verbose && !$noret) {
2490 check_return_section($file, $declaration_name, $return_type);
2493 output_declaration($declaration_name,
2495 {'function' => $declaration_name,
2496 'module' => $modulename,
2497 'functiontype' => $return_type,
2498 'parameterlist' => \@parameterlist,
2499 'parameterdescs' => \%parameterdescs,
2500 'parametertypes' => \%parametertypes,
2501 'sectionlist' => \@sectionlist,
2502 'sections' => \%sections,
2503 'purpose' => $declaration_purpose
2510 %parameterdescs = ();
2511 %parametertypes = ();
2512 @parameterlist = ();
2516 $struct_actual = "";
2519 $state = STATE_NORMAL;
2520 $inline_doc_state = STATE_INLINE_NA;
2523 sub tracepoint_munge($) {
2525 my $tracepointname = 0;
2526 my $tracepointargs = 0;
2528 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
2529 $tracepointname = $1;
2531 if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
2532 $tracepointname = $1;
2534 if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
2535 $tracepointname = $2;
2537 $tracepointname =~ s/^\s+//; #strip leading whitespace
2538 if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
2539 $tracepointargs = $1;
2541 if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
2542 print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
2545 $prototype = "static inline void trace_$tracepointname($tracepointargs)";
2549 sub syscall_munge() {
2552 $prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
2553 ## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
2554 if ($prototype =~ m/SYSCALL_DEFINE0/) {
2556 ## $prototype = "long sys_$1(void)";
2559 $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
2560 if ($prototype =~ m/long (sys_.*?),/) {
2561 $prototype =~ s/,/\(/;
2563 $prototype =~ s/\)/\(void\)/;
2566 # now delete all of the odd-number commas in $prototype
2567 # so that arg types & arg names don't have a comma between them
2569 my $len = length($prototype);
2571 $len = 0; # skip the for-loop
2573 for (my $ix = 0; $ix < $len; $ix++) {
2574 if (substr($prototype, $ix, 1) eq ',') {
2576 if ($count % 2 == 1) {
2577 substr($prototype, $ix, 1) = ' ';
2583 sub process_state3_function($$) {
2587 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2589 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2592 elsif ($x =~ /([^\{]*)/) {
2596 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2597 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2598 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2599 $prototype =~ s@^\s+@@gos; # strip leading spaces
2600 if ($prototype =~ /SYSCALL_DEFINE/) {
2603 if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
2604 $prototype =~ /DEFINE_SINGLE_EVENT/)
2606 tracepoint_munge($file);
2608 dump_function($prototype, $file);
2613 sub process_state3_type($$) {
2617 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2618 $x =~ s@^\s+@@gos; # strip leading spaces
2619 $x =~ s@\s+$@@gos; # strip trailing spaces
2620 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2623 # To distinguish preprocessor directive from regular declaration later.
2628 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2629 $prototype .= $1 . $2;
2630 ($2 eq '{') && $brcount++;
2631 ($2 eq '}') && $brcount--;
2632 if (($2 eq ';') && ($brcount == 0)) {
2633 dump_declaration($prototype, $file);
2645 # xml_escape: replace <, >, and & in the text stream;
2647 # however, formatting controls that are generated internally/locally in the
2648 # kernel-doc script are not escaped here; instead, they begin life like
2649 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2650 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2651 # just before actual output; (this is done by local_unescape())
2654 if (($output_mode eq "text") || ($output_mode eq "man")) {
2657 $text =~ s/\&/\\\\\\amp;/g;
2658 $text =~ s/\</\\\\\\lt;/g;
2659 $text =~ s/\>/\\\\\\gt;/g;
2663 # xml_unescape: reverse the effects of xml_escape
2664 sub xml_unescape($) {
2666 if (($output_mode eq "text") || ($output_mode eq "man")) {
2669 $text =~ s/\\\\\\amp;/\&/g;
2670 $text =~ s/\\\\\\lt;/</g;
2671 $text =~ s/\\\\\\gt;/>/g;
2675 # convert local escape strings to html
2676 # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2677 sub local_unescape($) {
2679 if (($output_mode eq "text") || ($output_mode eq "man")) {
2682 $text =~ s/\\\\\\\\lt:/</g;
2683 $text =~ s/\\\\\\\\gt:/>/g;
2687 sub process_file($) {
2693 my $initial_section_counter = $section_counter;
2694 my ($orig_file) = @_;
2696 if (defined($ENV{'SRCTREE'})) {
2697 $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
2702 if (defined($source_map{$file})) {
2703 $file = $source_map{$file};
2706 if (!open(IN,"<$file")) {
2707 print STDERR "Error: Cannot open file $file\n";
2712 # two passes for -export and -internal
2713 if ($output_selection == OUTPUT_EXPORTED ||
2714 $output_selection == OUTPUT_INTERNAL) {
2716 if (/$export_symbol/o) {
2717 $function_table{$2} = 1;
2725 $section_counter = 0;
2727 while (s/\\\s*$//) {
2730 if ($state == STATE_NORMAL) {
2731 if (/$doc_start/o) {
2732 $state = STATE_NAME; # next line is always the function name
2735 } elsif ($state == STATE_NAME) {# this line is the function name (always)
2736 if (/$doc_block/o) {
2737 $state = STATE_DOCBLOCK;
2740 $section = $section_intro;
2745 elsif (/$doc_decl/o) {
2747 if (/\s*([\w\s]+?)\s*-/) {
2751 $state = STATE_FIELD;
2753 # strip leading/trailing/multiple spaces
2757 $descr =~ s/\s+/ /g;
2758 $declaration_purpose = xml_escape($descr);
2761 $declaration_purpose = "";
2764 if (($declaration_purpose eq "") && $verbose) {
2765 print STDERR "${file}:$.: warning: missing initial short description on line:\n";
2770 if ($identifier =~ m/^struct/) {
2771 $decl_type = 'struct';
2772 } elsif ($identifier =~ m/^union/) {
2773 $decl_type = 'union';
2774 } elsif ($identifier =~ m/^enum/) {
2775 $decl_type = 'enum';
2776 } elsif ($identifier =~ m/^typedef/) {
2777 $decl_type = 'typedef';
2779 $decl_type = 'function';
2783 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2786 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2787 " - I thought it was a doc line\n";
2789 $state = STATE_NORMAL;
2791 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
2796 if (($contents ne "") && ($contents ne "\n")) {
2797 if (!$in_doc_sect && $verbose) {
2798 print STDERR "${file}:$.: warning: contents before sections\n";
2801 dump_section($file, $section, xml_escape($contents));
2802 $section = $section_default;
2807 $contents = $newcontents;
2808 if ($contents ne "") {
2809 while ((substr($contents, 0, 1) eq " ") ||
2810 substr($contents, 0, 1) eq "\t") {
2811 $contents = substr($contents, 1);
2815 $section = $newsection;
2816 } elsif (/$doc_end/) {
2817 if (($contents ne "") && ($contents ne "\n")) {
2818 dump_section($file, $section, xml_escape($contents));
2819 $section = $section_default;
2822 # look for doc_com + <text> + doc_end:
2823 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2824 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2829 $state = STATE_PROTO;
2831 # print STDERR "end of doc comment, looking for prototype\n";
2832 } elsif (/$doc_content/) {
2833 # miguel-style comment kludge, look for blank lines after
2834 # @parameter line to signify start of description
2836 if ($section =~ m/^@/ || $section eq $section_context) {
2837 dump_section($file, $section, xml_escape($contents));
2838 $section = $section_default;
2844 } elsif ($in_purpose == 1) {
2845 # Continued declaration purpose
2846 chomp($declaration_purpose);
2847 $declaration_purpose .= " " . xml_escape($1);
2848 $declaration_purpose =~ s/\s+/ /g;
2850 $contents .= $1 . "\n";
2853 # i dont know - bad line? ignore.
2854 print STDERR "${file}:$.: warning: bad line: $_";
2857 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2858 # First line (state 1) needs to be a @parameter
2859 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2862 if ($contents ne "") {
2863 while ((substr($contents, 0, 1) eq " ") ||
2864 substr($contents, 0, 1) eq "\t") {
2865 $contents = substr($contents, 1);
2869 $inline_doc_state = STATE_INLINE_TEXT;
2870 # Documentation block end */
2871 } elsif (/$doc_inline_end/) {
2872 if (($contents ne "") && ($contents ne "\n")) {
2873 dump_section($file, $section, xml_escape($contents));
2874 $section = $section_default;
2877 $state = STATE_PROTO;
2878 $inline_doc_state = STATE_INLINE_NA;
2880 } elsif (/$doc_content/) {
2881 if ($inline_doc_state == STATE_INLINE_TEXT) {
2882 $contents .= $1 . "\n";
2883 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2884 $inline_doc_state = STATE_INLINE_ERROR;
2885 print STDERR "Warning(${file}:$.): ";
2886 print STDERR "Incorrect use of kernel-doc format: $_";
2890 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
2891 if (/$doc_inline_start/) {
2892 $state = STATE_INLINE;
2893 $inline_doc_state = STATE_INLINE_NAME;
2894 } elsif ($decl_type eq 'function') {
2895 process_state3_function($_, $file);
2897 process_state3_type($_, $file);
2899 } elsif ($state == STATE_DOCBLOCK) {
2900 # Documentation block
2902 dump_doc_section($file, $section, xml_escape($contents));
2906 %parameterdescs = ();
2907 %parametertypes = ();
2908 @parameterlist = ();
2913 $section = $section_intro;
2920 dump_doc_section($file, $section, xml_escape($contents));
2924 %parameterdescs = ();
2925 %parametertypes = ();
2926 @parameterlist = ();
2930 $state = STATE_NORMAL;
2932 elsif (/$doc_content/)
2936 $contents .= $blankline;
2940 $contents .= $1 . "\n";
2945 if ($initial_section_counter == $section_counter) {
2946 print STDERR "${file}:1: warning: no structured comments found\n";
2947 if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
2948 print STDERR " Was looking for '$_'.\n" for keys %function_table;
2950 if ($output_mode eq "xml") {
2951 # The template wants at least one RefEntry here; make one.
2952 print "<refentry>\n";
2953 print " <refnamediv>\n";
2954 print " <refname>\n";
2955 print " ${orig_file}\n";
2956 print " </refname>\n";
2957 print " <refpurpose>\n";
2958 print " Document generation inconsistency\n";
2959 print " </refpurpose>\n";
2960 print " </refnamediv>\n";
2961 print " <refsect1>\n";
2964 print " </title>\n";
2965 print " <warning>\n";
2967 print " The template for this document tried to insert\n";
2968 print " the structured comment from the file\n";
2969 print " <filename>${orig_file}</filename> at this point,\n";
2970 print " but none was found.\n";
2971 print " This dummy section is inserted to allow\n";
2972 print " generation to continue.\n";
2974 print " </warning>\n";
2975 print " </refsect1>\n";
2976 print "</refentry>\n";
2982 $kernelversion = get_kernel_version();
2984 # generate a sequence of code that will splice in highlighting information
2985 # using the s// operator.
2986 for (my $k = 0; $k < @highlights; $k++) {
2987 my $pattern = $highlights[$k][0];
2988 my $result = $highlights[$k][1];
2989 # print STDERR "scanning pattern:$pattern, highlight:($result)\n";
2990 $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
2993 # Read the file that maps relative names to absolute names for
2994 # separate source and object directories and for shadow trees.
2995 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2996 my ($relname, $absname);
2997 while(<SOURCE_MAP>) {
2999 ($relname, $absname) = (split())[0..1];
3000 $relname =~ s:^/+::;
3001 $source_map{$relname} = $absname;
3010 if ($verbose && $errors) {
3011 print STDERR "$errors errors\n";
3013 if ($verbose && $warnings) {
3014 print STDERR "$warnings warnings\n";