Debian Codegraph @

scripts/kernel-doc

raw
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 <[email protected]> ##
7 ## Copyright (C) 2001 Simon Huggins ##
8 ## Copyright (C) 2005-2008 Randy Dunlap ##
9 ## ##
10 ## #define enhancements by Armin Kuster <[email protected]> ##
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 # -- [email protected]
22
23 # 27/06/2001 - Allowed whitespace after initial "/**" and
24 # allowed comments before function declarations.
25 # -- Christian Kreibich <[email protected]>
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 <[email protected]>
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 <[email protected]>
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 = '\\&amp;((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', 'probe', 'sfunction',
275 # 'smacro'
276 my $decl_type;
277
278 my $doc_special = "\@\%\$\&";
279
280 my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
281 my $doc_end = '\*/';
282 my $doc_com = '\s*\*\s*';
283 my $doc_decl = $doc_com.'(\w+)';
284 my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)';
285 my $doc_content = $doc_com.'(.*)';
286 my $doc_block = $doc_com.'DOC:\s*(.*)?';
287
288 my %constants;
289 my %parameterdescs;
290 my @parameterlist;
291 my %sections;
292 my @sectionlist;
293
294 my $contents = "";
295 my $section_default = "Description"; # default section
296 my $section_intro = "Introduction";
297 my $section = $section_default;
298 my $section_context = "Context";
299
300 my $undescribed = "-- undescribed --";
301
302 reset_state();
303
304 while ($ARGV[0] =~ m/^-(.*)/) {
305 my $cmd = shift @ARGV;
306 if ($cmd eq "-html") {
307 $output_mode = "html";
308 %highlights = %highlights_html;
309 $blankline = $blankline_html;
310 } elsif ($cmd eq "-man") {
311 $output_mode = "man";
312 %highlights = %highlights_man;
313 $blankline = $blankline_man;
314 } elsif ($cmd eq "-text") {
315 $output_mode = "text";
316 %highlights = %highlights_text;
317 $blankline = $blankline_text;
318 } elsif ($cmd eq "-docbook") {
319 $output_mode = "xml";
320 %highlights = %highlights_xml;
321 $blankline = $blankline_xml;
322 } elsif ($cmd eq "-gnome") {
323 $output_mode = "gnome";
324 %highlights = %highlights_gnome;
325 $blankline = $blankline_gnome;
326 } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
327 $modulename = shift @ARGV;
328 } elsif ($cmd eq "-function") { # to only output specific functions
329 $function_only = 1;
330 $function = shift @ARGV;
331 $function_table{$function} = 1;
332 } elsif ($cmd eq "-nofunction") { # to only output specific functions
333 $function_only = 2;
334 $function = shift @ARGV;
335 $function_table{$function} = 1;
336 } elsif ($cmd eq "-v") {
337 $verbose = 1;
338 } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
339 usage();
340 } elsif ($cmd eq '-filelist') {
341 $filelist = shift @ARGV;
342 } elsif ($cmd eq '-no-doc-sections') {
343 $no_doc_sections = 1;
344 }
345 }
346
347 # get kernel version from env
348 sub get_kernel_version() {
349 my $version = 'unknown kernel version';
350
351 if (defined($ENV{'KERNELVERSION'})) {
352 $version = $ENV{'KERNELVERSION'};
353 }
354 return $version;
355 }
356 my $kernelversion = get_kernel_version();
357
358 # generate a sequence of code that will splice in highlighting information
359 # using the s// operator.
360 my $dohighlight = "";
361 foreach my $pattern (keys %highlights) {
362 # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
363 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
364 }
365
366 ##
367 # dumps section contents to arrays/hashes intended for that purpose.
368 #
369 sub dump_section {
370 my $file = shift;
371 my $name = shift;
372 my $contents = join "\n", @_;
373
374 if ($name =~ m/$type_constant/) {
375 $name = $1;
376 # print STDERR "constant section '$1' = '$contents'\n";
377 $constants{$name} = $contents;
378 } elsif ($name =~ m/$type_param/) {
379 # print STDERR "parameter def '$1' = '$contents'\n";
380 $name = $1;
381 $parameterdescs{$name} = $contents;
382 } else {
383 # print STDERR "other section '$name' = '$contents'\n";
384 if (defined($sections{$name}) && ($sections{$name} ne "")) {
385 print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
386 ++$errors;
387 }
388 $sections{$name} = $contents;
389 push @sectionlist, $name;
390 }
391 }
392
393 ##
394 # dump DOC: section after checking that it should go out
395 #
396 sub dump_doc_section {
397 my $file = shift;
398 my $name = shift;
399 my $contents = join "\n", @_;
400
401 if ($no_doc_sections) {
402 return;
403 }
404
405 if (($function_only == 0) ||
406 ( $function_only == 1 && defined($function_table{$name})) ||
407 ( $function_only == 2 && !defined($function_table{$name})))
408 {
409 dump_section($file, $name, $contents);
410 output_blockhead({'sectionlist' => \@sectionlist,
411 'sections' => \%sections,
412 'module' => $modulename,
413 'content-only' => ($function_only != 0), });
414 }
415 }
416
417 ##
418 # output function
419 #
420 # parameterdescs, a hash.
421 # function => "function name"
422 # parameterlist => @list of parameters
423 # parameterdescs => %parameter descriptions
424 # sectionlist => @list of sections
425 # sections => %section descriptions
426 #
427
428 sub output_highlight {
429 my $contents = join "\n",@_;
430 my $line;
431
432 # DEBUG
433 # if (!defined $contents) {
434 # use Carp;
435 # confess "output_highlight got called with no args?\n";
436 # }
437
438 if ($output_mode eq "html" || $output_mode eq "xml") {
439 $contents = local_unescape($contents);
440 # convert data read & converted thru xml_escape() into &xyz; format:
441 $contents =~ s/\\\\\\/&/g;
442 }
443 # print STDERR "contents b4:$contents\n";
444 eval $dohighlight;
445 die $@ if $@;
446 # print STDERR "contents af:$contents\n";
447
448 foreach $line (split "\n", $contents) {
449 if ($line eq ""){
450 print $lineprefix, local_unescape($blankline);
451 } else {
452 $line =~ s/\\\\\\/\&/g;
453 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
454 print "\\&$line";
455 } else {
456 print $lineprefix, $line;
457 }
458 }
459 print "\n";
460 }
461 }
462
463 #output sections in html
464 sub output_section_html(%) {
465 my %args = %{$_[0]};
466 my $section;
467
468 foreach $section (@{$args{'sectionlist'}}) {
469 print "<h3>$section</h3>\n";
470 print "<blockquote>\n";
471 output_highlight($args{'sections'}{$section});
472 print "</blockquote>\n";
473 }
474 }
475
476 # output enum in html
477 sub output_enum_html(%) {
478 my %args = %{$_[0]};
479 my ($parameter);
480 my $count;
481 print "<h2>enum ".$args{'enum'}."</h2>\n";
482
483 print "<b>enum ".$args{'enum'}."</b> {<br>\n";
484 $count = 0;
485 foreach $parameter (@{$args{'parameterlist'}}) {
486 print " <b>".$parameter."</b>";
487 if ($count != $#{$args{'parameterlist'}}) {
488 $count++;
489 print ",\n";
490 }
491 print "<br>";
492 }
493 print "};<br>\n";
494
495 print "<h3>Constants</h3>\n";
496 print "<dl>\n";
497 foreach $parameter (@{$args{'parameterlist'}}) {
498 print "<dt><b>".$parameter."</b>\n";
499 print "<dd>";
500 output_highlight($args{'parameterdescs'}{$parameter});
501 }
502 print "</dl>\n";
503 output_section_html(@_);
504 print "<hr>\n";
505 }
506
507 # output typedef in html
508 sub output_typedef_html(%) {
509 my %args = %{$_[0]};
510 my ($parameter);
511 my $count;
512 print "<h2>typedef ".$args{'typedef'}."</h2>\n";
513
514 print "<b>typedef ".$args{'typedef'}."</b>\n";
515 output_section_html(@_);
516 print "<hr>\n";
517 }
518
519 # output struct in html
520 sub output_struct_html(%) {
521 my %args = %{$_[0]};
522 my ($parameter);
523
524 print "<h2>".$args{'type'}." ".$args{'struct'}. " - " .$args{'purpose'}."</h2>\n";
525 print "<b>".$args{'type'}." ".$args{'struct'}."</b> {<br>\n";
526 foreach $parameter (@{$args{'parameterlist'}}) {
527 if ($parameter =~ /^#/) {
528 print "$parameter<br>\n";
529 next;
530 }
531 my $parameter_name = $parameter;
532 $parameter_name =~ s/\[.*//;
533
534 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
535 $type = $args{'parametertypes'}{$parameter};
536 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
537 # pointer-to-function
538 print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
539 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
540 # bitfield
541 print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
542 } else {
543 print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
544 }
545 }
546 print "};<br>\n";
547
548 print "<h3>Members</h3>\n";
549 print "<dl>\n";
550 foreach $parameter (@{$args{'parameterlist'}}) {
551 ($parameter =~ /^#/) && next;
552
553 my $parameter_name = $parameter;
554 $parameter_name =~ s/\[.*//;
555
556 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
557 print "<dt><b>".$parameter."</b>\n";
558 print "<dd>";
559 output_highlight($args{'parameterdescs'}{$parameter_name});
560 }
561 print "</dl>\n";
562 output_section_html(@_);
563 print "<hr>\n";
564 }
565
566 # output function in html
567 sub output_function_html(%) {
568 my %args = %{$_[0]};
569 my ($parameter, $section);
570 my $count;
571
572 print "<h2>" .$args{'function'}." - ".$args{'purpose'}."</h2>\n";
573 print "<i>".$args{'functiontype'}."</i>\n";
574 print "<b>".$args{'function'}."</b>\n";
575 print "(";
576 $count = 0;
577 foreach $parameter (@{$args{'parameterlist'}}) {
578 $type = $args{'parametertypes'}{$parameter};
579 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
580 # pointer-to-function
581 print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
582 } else {
583 print "<i>".$type."</i> <b>".$parameter."</b>";
584 }
585 if ($count != $#{$args{'parameterlist'}}) {
586 $count++;
587 print ",\n";
588 }
589 }
590 print ")\n";
591
592 print "<h3>Arguments</h3>\n";
593 print "<dl>\n";
594 foreach $parameter (@{$args{'parameterlist'}}) {
595 my $parameter_name = $parameter;
596 $parameter_name =~ s/\[.*//;
597
598 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
599 print "<dt><b>".$parameter."</b>\n";
600 print "<dd>";
601 output_highlight($args{'parameterdescs'}{$parameter_name});
602 }
603 print "</dl>\n";
604 output_section_html(@_);
605 print "<hr>\n";
606 }
607
608 # output probe in html
609 sub output_probe_html(%) {
610 my %args = %{$_[0]};
611 my ($parameter, $section);
612 my $count;
613
614 }
615
616 # output sfunction in html
617 sub output_sfunction_html(%) {
618 my %args = %{$_[0]};
619 my ($parameter, $section);
620 my $count;
621
622 }
623
624 # output smacro in html
625 sub output_smacro_html(%) {
626 my %args = %{$_[0]};
627 my ($parameter, $section);
628 my $count;
629
630 }
631
632 # output DOC: block header in html
633 sub output_blockhead_html(%) {
634 my %args = %{$_[0]};
635 my ($parameter, $section);
636 my $count;
637
638 foreach $section (@{$args{'sectionlist'}}) {
639 print "<h3>$section</h3>\n";
640 print "<ul>\n";
641 output_highlight($args{'sections'}{$section});
642 print "</ul>\n";
643 }
644 print "<hr>\n";
645 }
646
647 sub output_section_xml(%) {
648 my %args = %{$_[0]};
649 my $section;
650 # print out each section
651 $lineprefix=" ";
652 foreach $section (@{$args{'sectionlist'}}) {
653 print "<refsect1>\n";
654 print "<title>$section</title>\n";
655 if ($section =~ m/EXAMPLE/i) {
656 print "<informalexample><programlisting>\n";
657 } else {
658 print "<para>\n";
659 }
660 output_highlight($args{'sections'}{$section});
661 if ($section =~ m/EXAMPLE/i) {
662 print "</programlisting></informalexample>\n";
663 } else {
664 print "</para>\n";
665 }
666 print "</refsect1>\n";
667 }
668 }
669
670 # output function in XML DocBook
671 sub output_function_xml(%) {
672 my %args = %{$_[0]};
673 my ($parameter, $section);
674 my $count;
675 my $id;
676
677 $id = "API-".$args{'function'};
678 $id =~ s/[^A-Za-z0-9]/-/g;
679
680 print "<refentry id=\"$id\">\n";
681 print "<refentryinfo>\n";
682 print " <title>LINUX</title>\n";
683 print " <productname>Kernel Hackers Manual</productname>\n";
684 print " <date>$man_date</date>\n";
685 print "</refentryinfo>\n";
686 print "<refmeta>\n";
687 print " <refentrytitle><phrase>".$args{'function'}."</phrase></refentrytitle>\n";
688 print " <manvolnum>9</manvolnum>\n";
689 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
690 print "</refmeta>\n";
691 print "<refnamediv>\n";
692 print " <refname>".$args{'function'}."</refname>\n";
693 print " <refpurpose>\n";
694 print " ";
695 output_highlight ($args{'purpose'});
696 print " </refpurpose>\n";
697 print "</refnamediv>\n";
698
699 print "<refsynopsisdiv>\n";
700 print " <title>Synopsis</title>\n";
701 print " <funcsynopsis><funcprototype>\n";
702 print " <funcdef>".$args{'functiontype'}." ";
703 print "<function>".$args{'function'}." </function></funcdef>\n";
704
705 $count = 0;
706 if ($#{$args{'parameterlist'}} >= 0) {
707 foreach $parameter (@{$args{'parameterlist'}}) {
708 $type = $args{'parametertypes'}{$parameter};
709 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
710 # pointer-to-function
711 print " <paramdef>$1<parameter>$parameter</parameter>)\n";
712 print " <funcparams>$2</funcparams></paramdef>\n";
713 } else {
714 print " <paramdef>".$type;
715 print " <parameter>$parameter</parameter></paramdef>\n";
716 }
717 }
718 } else {
719 print " <void/>\n";
720 }
721 print " </funcprototype></funcsynopsis>\n";
722 print "</refsynopsisdiv>\n";
723
724 # print parameters
725 print "<refsect1>\n <title>Arguments</title>\n";
726 if ($#{$args{'parameterlist'}} >= 0) {
727 print " <variablelist>\n";
728 foreach $parameter (@{$args{'parameterlist'}}) {
729 my $parameter_name = $parameter;
730 $parameter_name =~ s/\[.*//;
731
732 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
733 print " <listitem>\n <para>\n";
734 $lineprefix=" ";
735 output_highlight($args{'parameterdescs'}{$parameter_name});
736 print " </para>\n </listitem>\n </varlistentry>\n";
737 }
738 print " </variablelist>\n";
739 } else {
740 print " <para>\n None\n </para>\n";
741 }
742 print "</refsect1>\n";
743
744 output_section_xml(@_);
745 print "</refentry>\n\n";
746 }
747
748 # output struct in XML DocBook
749 sub output_struct_xml(%) {
750 my %args = %{$_[0]};
751 my ($parameter, $section);
752 my $id;
753
754 $id = "API-struct-".$args{'struct'};
755 $id =~ s/[^A-Za-z0-9]/-/g;
756
757 print "<refentry id=\"$id\">\n";
758 print "<refentryinfo>\n";
759 print " <title>LINUX</title>\n";
760 print " <productname>Kernel Hackers Manual</productname>\n";
761 print " <date>$man_date</date>\n";
762 print "</refentryinfo>\n";
763 print "<refmeta>\n";
764 print " <refentrytitle><phrase>".$args{'type'}." ".$args{'struct'}."</phrase></refentrytitle>\n";
765 print " <manvolnum>9</manvolnum>\n";
766 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
767 print "</refmeta>\n";
768 print "<refnamediv>\n";
769 print " <refname>".$args{'type'}." ".$args{'struct'}."</refname>\n";
770 print " <refpurpose>\n";
771 print " ";
772 output_highlight ($args{'purpose'});
773 print " </refpurpose>\n";
774 print "</refnamediv>\n";
775
776 print "<refsynopsisdiv>\n";
777 print " <title>Synopsis</title>\n";
778 print " <programlisting>\n";
779 print $args{'type'}." ".$args{'struct'}." {\n";
780 foreach $parameter (@{$args{'parameterlist'}}) {
781 if ($parameter =~ /^#/) {
782 print "$parameter\n";
783 next;
784 }
785
786 my $parameter_name = $parameter;
787 $parameter_name =~ s/\[.*//;
788
789 defined($args{'parameterdescs'}{$parameter_name}) || next;
790 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
791 $type = $args{'parametertypes'}{$parameter};
792 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
793 # pointer-to-function
794 print " $1 $parameter) ($2);\n";
795 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
796 # bitfield
797 print " $1 $parameter$2;\n";
798 } else {
799 print " ".$type." ".$parameter.";\n";
800 }
801 }
802 print "};";
803 print " </programlisting>\n";
804 print "</refsynopsisdiv>\n";
805
806 print " <refsect1>\n";
807 print " <title>Members</title>\n";
808
809 if ($#{$args{'parameterlist'}} >= 0) {
810 print " <variablelist>\n";
811 foreach $parameter (@{$args{'parameterlist'}}) {
812 ($parameter =~ /^#/) && next;
813
814 my $parameter_name = $parameter;
815 $parameter_name =~ s/\[.*//;
816
817 defined($args{'parameterdescs'}{$parameter_name}) || next;
818 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
819 print " <varlistentry>";
820 print " <term>$parameter</term>\n";
821 print " <listitem><para>\n";
822 output_highlight($args{'parameterdescs'}{$parameter_name});
823 print " </para></listitem>\n";
824 print " </varlistentry>\n";
825 }
826 print " </variablelist>\n";
827 } else {
828 print " <para>\n None\n </para>\n";
829 }
830 print " </refsect1>\n";
831
832 output_section_xml(@_);
833
834 print "</refentry>\n\n";
835 }
836
837 # output enum in XML DocBook
838 sub output_enum_xml(%) {
839 my %args = %{$_[0]};
840 my ($parameter, $section);
841 my $count;
842 my $id;
843
844 $id = "API-enum-".$args{'enum'};
845 $id =~ s/[^A-Za-z0-9]/-/g;
846
847 print "<refentry id=\"$id\">\n";
848 print "<refentryinfo>\n";
849 print " <title>LINUX</title>\n";
850 print " <productname>Kernel Hackers Manual</productname>\n";
851 print " <date>$man_date</date>\n";
852 print "</refentryinfo>\n";
853 print "<refmeta>\n";
854 print " <refentrytitle><phrase>enum ".$args{'enum'}."</phrase></refentrytitle>\n";
855 print " <manvolnum>9</manvolnum>\n";
856 print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
857 print "</refmeta>\n";
858 print "<refnamediv>\n";
859 print " <refname>enum ".$args{'enum'}."</refname>\n";
860 print " <refpurpose>\n";
861 print " ";
862 output_highlight ($args{'purpose'});
863 print " </refpurpose>\n";
864 print "</refnamediv>\n";
865
866 print "<refsynopsisdiv>\n";
867 print " <title>Synopsis</title>\n";
868 print " <programlisting>\n";
869 print "enum ".$args{'enum'}." {\n";
870 $count = 0;
871 foreach $parameter (@{$args{'parameterlist'}}) {
872 print " $parameter";
873 if ($count != $#{$args{'parameterlist'}}) {
874 $count++;
875 print ",";
876 }
877 print "\n";
878 }
879 print "};";
880 print " </programlisting>\n";
881 print "</refsynopsisdiv>\n";
882
883 print "<refsect1>\n";
884 print " <title>Constants</title>\n";
885 print " <variablelist>\n";
886 foreach $parameter (@{$args{'parameterlist'}}) {
887 my $parameter_name = $parameter;
888 $parameter_name =~ s/\[.*//;
889
890 print " <varlistentry>";
891 print " <term>$parameter</term>\n";
892 print " <listitem><para>\n";
893 output_highlight($args{'parameterdescs'}{$parameter_name});
894 print " </para></listitem>\n";
895 print " </varlistentry>\n";
896 }
897 print " </variablelist>\n";
898 print "</refsect1>\n";
899
900 output_section_xml(@_);
901
902 print "</refentry>\n\n";
903 }
904
905 # output typedef in XML DocBook
906 sub output_typedef_xml(%) {
907 my %args = %{$_[0]};
908 my ($parameter, $section);
909 my $id;
910
911 $id = "API-typedef-".$args{'typedef'};
912 $id =~ s/[^A-Za-z0-9]/-/g;
913
914 print "<refentry id=\"$id\">\n";
915 print "<refentryinfo>\n";
916 print " <title>LINUX</title>\n";
917 print " <productname>Kernel Hackers Manual</productname>\n";
918 print " <date>$man_date</date>\n";
919 print "</refentryinfo>\n";
920 print "<refmeta>\n";
921 print " <refentrytitle><phrase>typedef ".$args{'typedef'}."</phrase></refentrytitle>\n";
922 print " <manvolnum>9</manvolnum>\n";
923 print "</refmeta>\n";
924 print "<refnamediv>\n";
925 print " <refname>typedef ".$args{'typedef'}."</refname>\n";
926 print " <refpurpose>\n";
927 print " ";
928 output_highlight ($args{'purpose'});
929 print " </refpurpose>\n";
930 print "</refnamediv>\n";
931
932 print "<refsynopsisdiv>\n";
933 print " <title>Synopsis</title>\n";
934 print " <synopsis>typedef ".$args{'typedef'}.";</synopsis>\n";
935 print "</refsynopsisdiv>\n";
936
937 output_section_xml(@_);
938
939 print "</refentry>\n\n";
940 }
941
942 # output in XML DocBook
943 sub output_blockhead_xml(%) {
944 my %args = %{$_[0]};
945 my ($parameter, $section);
946 my $count;
947
948 my $id = $args{'module'};
949 $id =~ s/[^A-Za-z0-9]/-/g;
950
951 # print out each section
952 $lineprefix=" ";
953 foreach $section (@{$args{'sectionlist'}}) {
954 if (!$args{'content-only'}) {
955 print "<refsect1>\n <title>$section</title>\n";
956 }
957 if ($section =~ m/EXAMPLE/i) {
958 print "<example><para>\n";
959 } else {
960 print "<para>\n";
961 }
962 output_highlight($args{'sections'}{$section});
963 if ($section =~ m/EXAMPLE/i) {
964 print "</para></example>\n";
965 } else {
966 print "</para>";
967 }
968 if (!$args{'content-only'}) {
969 print "\n</refsect1>\n";
970 }
971 }
972
973 print "\n\n";
974 }
975
976 # output in XML DocBook
977 sub output_probe_xml(%) {
978 my %args = %{$_[0]};
979 my ($parameter, $section);
980 my $count;
981 my $id;
982
983 $id = "API-".$args{'probe'};
984 $id =~ s/[^A-Za-z0-9]/-/g;
985 print "<refentry id=\"$id\">\n";
986 print "<refentryinfo>\n";
987 print " <title>LINUX</title>\n";
988 print " <productname>SystemTap Tapset Reference</productname>\n";
989 print " <date>$man_date</date>\n";
990 print "</refentryinfo>\n";
991 print "<refmeta>\n";
992 print " <refentrytitle><phrase>probe::".$args{'probe'}."</phrase></refentrytitle>\n";
993 print " <manvolnum>3stap</manvolnum>\n";
994 # print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
995 print "</refmeta>\n";
996 print "<refnamediv>\n";
997 print " <refname>probe::".$args{'probe'}."</refname>\n";
998 print " <refpurpose>\n";
999 print " ";
1000 output_highlight ($args{'purpose'});
1001 print " </refpurpose>\n";
1002 print "</refnamediv>\n";
1003
1004 print "<refsynopsisdiv>\n";
1005 print " <title>Synopsis</title>\n";
1006 print "<synopsis>".$args{'probe'}." </synopsis>\n";
1007 print "</refsynopsisdiv>\n";
1008
1009 # print parameters
1010 print "<refsect1>\n <title>Values</title>\n";
1011 if ($#{$args{'parameterlist'}} >= 0) {
1012 print " <variablelist>\n";
1013 foreach $parameter (@{$args{'parameterlist'}}) {
1014 my $parameter_name = $parameter;
1015 $parameter_name =~ s/\[.*//;
1016
1017 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1018 print " <listitem>\n <para>\n";
1019 $lineprefix=" ";
1020 output_highlight($args{'parameterdescs'}{$parameter_name});
1021 print " </para>\n </listitem>\n </varlistentry>\n";
1022 }
1023 print " </variablelist>\n";
1024 } else {
1025 print " <para>\n None\n </para>\n";
1026 }
1027 print "</refsect1>\n";
1028
1029 output_section_xml(@_);
1030 print "</refentry>\n\n";
1031 }
1032
1033 # output in XML DocBook
1034 sub output_sfunction_xml(%) {
1035 my %args = %{$_[0]};
1036 my ($parameter, $section);
1037 my $count;
1038 my $id;
1039
1040 $id = "API-".$args{'sfunction'};
1041 $id =~ s/[^A-Za-z0-9]/-/g;
1042
1043 print "<refentry id=\"$id\">\n";
1044 print "<refentryinfo>\n";
1045 print " <title>LINUX</title>\n";
1046 print " <productname>SystemTap Tapset Reference</productname>\n";
1047 print " <date>$man_date</date>\n";
1048 print "</refentryinfo>\n";
1049 print "<refmeta>\n";
1050 print " <refentrytitle><phrase>function::".$args{'sfunction'}."</phrase></refentrytitle>\n";
1051 print " <manvolnum>3stap</manvolnum>\n";
1052 # print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1053 print "</refmeta>\n";
1054 print "<refnamediv>\n";
1055 print " <refname>function::".$args{'sfunction'}."</refname>\n";
1056 print " <refpurpose>\n";
1057 print " ";
1058 output_highlight ($args{'purpose'});
1059 print " </refpurpose>\n";
1060 print "</refnamediv>\n";
1061
1062 print "<refsynopsisdiv>\n";
1063 print " <title>Synopsis</title>\n";
1064 print " <programlisting>\n";
1065 print " ".$args{'sfunction'};
1066 if ($args{'functiontype'}) { print ":".$args{'functiontype'} }
1067 print "(";
1068
1069 $count = $#{$args{'parameterlist'}};
1070 if ($count >= 0) {
1071 foreach $parameter (@{$args{'parameterlist'}}) {
1072 $type = $args{'parametertypes'}{$parameter};
1073 print $parameter.":".$type;
1074 $count -= 1;
1075 if ($count >= 0) { print ","; }
1076 }
1077 }
1078 print ")\n</programlisting>\n";
1079 print "</refsynopsisdiv>\n";
1080
1081 # print parameters
1082 print "<refsect1>\n <title>Arguments</title>\n";
1083 if ($#{$args{'parameterlist'}} >= 0) {
1084 print " <variablelist>\n";
1085 foreach $parameter (@{$args{'parameterlist'}}) {
1086 my $parameter_name = $parameter;
1087 $parameter_name =~ s/\[.*//;
1088
1089 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1090 print " <listitem>\n <para>\n";
1091 $lineprefix=" ";
1092 output_highlight($args{'parameterdescs'}{$parameter_name});
1093 print " </para>\n </listitem>\n </varlistentry>\n";
1094 }
1095 print " </variablelist>\n";
1096 } else {
1097 print " <para>\n None\n </para>\n";
1098 }
1099 print "</refsect1>\n";
1100
1101 output_section_xml(@_);
1102 print "</refentry>\n\n";
1103 }
1104
1105 # output in XML DocBook
1106 sub output_smacro_xml(%) {
1107 my %args = %{$_[0]};
1108 my ($parameter, $section);
1109 my $count;
1110 my $id;
1111
1112 $id = "API-".$args{'smacro'};
1113 $id =~ s/[^A-Za-z0-9]/-/g;
1114
1115 print "<refentry id=\"$id\">\n";
1116 print "<refentryinfo>\n";
1117 print " <title>LINUX</title>\n";
1118 print " <productname>SystemTap Tapset Reference</productname>\n";
1119 print " <date>$man_date</date>\n";
1120 print "</refentryinfo>\n";
1121 print "<refmeta>\n";
1122 print " <refentrytitle><phrase>macro::".$args{'smacro'}."</phrase></refentrytitle>\n";
1123 print " <manvolnum>3stap</manvolnum>\n";
1124 # print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
1125 print "</refmeta>\n";
1126 print "<refnamediv>\n";
1127 print " <refname>macro::".$args{'smacro'}."</refname>\n";
1128 print " <refpurpose>\n";
1129 print " ";
1130 output_highlight ($args{'purpose'});
1131 print " </refpurpose>\n";
1132 print "</refnamediv>\n";
1133
1134 print "<refsynopsisdiv>\n";
1135 print " <title>Synopsis</title>\n";
1136 print " <programlisting>\n";
1137 print " @".$args{'smacro'};
1138 # if ($args{'functiontype'}) { print ":".$args{'functiontype'} }
1139 print "(";
1140
1141 $count = $#{$args{'parameterlist'}};
1142 if ($count >= 0) {
1143 foreach $parameter (@{$args{'parameterlist'}}) {
1144 # $type = $args{'parametertypes'}{$parameter};
1145 # print $parameter.":".$type;
1146 print $parameter;
1147 $count -= 1;
1148 if ($count >= 0) { print ","; }
1149 }
1150 }
1151 print ")\n</programlisting>\n";
1152 print "</refsynopsisdiv>\n";
1153
1154 # print parameters
1155 print "<refsect1>\n <title>Arguments</title>\n";
1156 if ($#{$args{'parameterlist'}} >= 0) {
1157 print " <variablelist>\n";
1158 foreach $parameter (@{$args{'parameterlist'}}) {
1159 my $parameter_name = $parameter;
1160 $parameter_name =~ s/\[.*//;
1161
1162 print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n";
1163 print " <listitem>\n <para>\n";
1164 $lineprefix=" ";
1165 output_highlight($args{'parameterdescs'}{$parameter_name});
1166 print " </para>\n </listitem>\n </varlistentry>\n";
1167 }
1168 print " </variablelist>\n";
1169 } else {
1170 print " <para>\n None\n </para>\n";
1171 }
1172 print "</refsect1>\n";
1173
1174 output_section_xml(@_);
1175 print "</refentry>\n\n";
1176 }
1177
1178 # output in XML DocBook
1179 sub output_function_gnome {
1180 my %args = %{$_[0]};
1181 my ($parameter, $section);
1182 my $count;
1183 my $id;
1184
1185 $id = $args{'module'}."-".$args{'function'};
1186 $id =~ s/[^A-Za-z0-9]/-/g;
1187
1188 print "<sect2>\n";
1189 print " <title id=\"$id\">".$args{'function'}."</title>\n";
1190
1191 print " <funcsynopsis>\n";
1192 print " <funcdef>".$args{'functiontype'}." ";
1193 print "<function>".$args{'function'}." ";
1194 print "</function></funcdef>\n";
1195
1196 $count = 0;
1197 if ($#{$args{'parameterlist'}} >= 0) {
1198 foreach $parameter (@{$args{'parameterlist'}}) {
1199 $type = $args{'parametertypes'}{$parameter};
1200 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1201 # pointer-to-function
1202 print " <paramdef>$1 <parameter>$parameter</parameter>)\n";
1203 print " <funcparams>$2</funcparams></paramdef>\n";
1204 } else {
1205 print " <paramdef>".$type;
1206 print " <parameter>$parameter</parameter></paramdef>\n";
1207 }
1208 }
1209 } else {
1210 print " <void>\n";
1211 }
1212 print " </funcsynopsis>\n";
1213 if ($#{$args{'parameterlist'}} >= 0) {
1214 print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
1215 print "<tgroup cols=\"2\">\n";
1216 print "<colspec colwidth=\"2*\">\n";
1217 print "<colspec colwidth=\"8*\">\n";
1218 print "<tbody>\n";
1219 foreach $parameter (@{$args{'parameterlist'}}) {
1220 my $parameter_name = $parameter;
1221 $parameter_name =~ s/\[.*//;
1222
1223 print " <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
1224 print " <entry>\n";
1225 $lineprefix=" ";
1226 output_highlight($args{'parameterdescs'}{$parameter_name});
1227 print " </entry></row>\n";
1228 }
1229 print " </tbody></tgroup></informaltable>\n";
1230 } else {
1231 print " <para>\n None\n </para>\n";
1232 }
1233
1234 # print out each section
1235 $lineprefix=" ";
1236 foreach $section (@{$args{'sectionlist'}}) {
1237 print "<simplesect>\n <title>$section</title>\n";
1238 if ($section =~ m/EXAMPLE/i) {
1239 print "<example><programlisting>\n";
1240 } else {
1241 }
1242 print "<para>\n";
1243 output_highlight($args{'sections'}{$section});
1244 print "</para>\n";
1245 if ($section =~ m/EXAMPLE/i) {
1246 print "</programlisting></example>\n";
1247 } else {
1248 }
1249 print " </simplesect>\n";
1250 }
1251
1252 print "</sect2>\n\n";
1253 }
1254
1255 ##
1256 # output function in man
1257 sub output_function_man(%) {
1258 my %args = %{$_[0]};
1259 my ($parameter, $section);
1260 my $count;
1261
1262 print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
1263
1264 print ".SH NAME\n";
1265 print $args{'function'}." \\- ".$args{'purpose'}."\n";
1266
1267 print ".SH SYNOPSIS\n";
1268 if ($args{'functiontype'} ne "") {
1269 print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n";
1270 } else {
1271 print ".B \"".$args{'function'}."\n";
1272 }
1273 $count = 0;
1274 my $parenth = "(";
1275 my $post = ",";
1276 foreach my $parameter (@{$args{'parameterlist'}}) {
1277 if ($count == $#{$args{'parameterlist'}}) {
1278 $post = ");";
1279 }
1280 $type = $args{'parametertypes'}{$parameter};
1281 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1282 # pointer-to-function
1283 print ".BI \"".$parenth.$1."\" ".$parameter." \") (".$2.")".$post."\"\n";
1284 } else {
1285 $type =~ s/([^\*])$/$1 /;
1286 print ".BI \"".$parenth.$type."\" ".$parameter." \"".$post."\"\n";
1287 }
1288 $count++;
1289 $parenth = "";
1290 }
1291
1292 print ".SH ARGUMENTS\n";
1293 foreach $parameter (@{$args{'parameterlist'}}) {
1294 my $parameter_name = $parameter;
1295 $parameter_name =~ s/\[.*//;
1296
1297 print ".IP \"".$parameter."\" 12\n";
1298 output_highlight($args{'parameterdescs'}{$parameter_name});
1299 }
1300 foreach $section (@{$args{'sectionlist'}}) {
1301 print ".SH \"", uc $section, "\"\n";
1302 output_highlight($args{'sections'}{$section});
1303 }
1304 }
1305
1306 ##
1307 # output enum in man
1308 sub output_enum_man(%) {
1309 my %args = %{$_[0]};
1310 my ($parameter, $section);
1311 my $count;
1312
1313 print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";
1314
1315 print ".SH NAME\n";
1316 print "enum ".$args{'enum'}." \\- ".$args{'purpose'}."\n";
1317
1318 print ".SH SYNOPSIS\n";
1319 print "enum ".$args{'enum'}." {\n";
1320 $count = 0;
1321 foreach my $parameter (@{$args{'parameterlist'}}) {
1322 print ".br\n.BI \" $parameter\"\n";
1323 if ($count == $#{$args{'parameterlist'}}) {
1324 print "\n};\n";
1325 last;
1326 }
1327 else {
1328 print ", \n.br\n";
1329 }
1330 $count++;
1331 }
1332
1333 print ".SH Constants\n";
1334 foreach $parameter (@{$args{'parameterlist'}}) {
1335 my $parameter_name = $parameter;
1336 $parameter_name =~ s/\[.*//;
1337
1338 print ".IP \"".$parameter."\" 12\n";
1339 output_highlight($args{'parameterdescs'}{$parameter_name});
1340 }
1341 foreach $section (@{$args{'sectionlist'}}) {
1342 print ".SH \"$section\"\n";
1343 output_highlight($args{'sections'}{$section});
1344 }
1345 }
1346
1347 ##
1348 # output struct in man
1349 sub output_struct_man(%) {
1350 my %args = %{$_[0]};
1351 my ($parameter, $section);
1352
1353 print ".TH \"$args{'module'}\" 9 \"".$args{'type'}." ".$args{'struct'}."\" \"$man_date\" \"API Manual\" LINUX\n";
1354
1355 print ".SH NAME\n";
1356 print $args{'type'}." ".$args{'struct'}." \\- ".$args{'purpose'}."\n";
1357
1358 print ".SH SYNOPSIS\n";
1359 print $args{'type'}." ".$args{'struct'}." {\n.br\n";
1360
1361 foreach my $parameter (@{$args{'parameterlist'}}) {
1362 if ($parameter =~ /^#/) {
1363 print ".BI \"$parameter\"\n.br\n";
1364 next;
1365 }
1366 my $parameter_name = $parameter;
1367 $parameter_name =~ s/\[.*//;
1368
1369 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1370 $type = $args{'parametertypes'}{$parameter};
1371 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1372 # pointer-to-function
1373 print ".BI \" ".$1."\" ".$parameter." \") (".$2.")"."\"\n;\n";
1374 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1375 # bitfield
1376 print ".BI \" ".$1."\ \" ".$parameter.$2." \""."\"\n;\n";
1377 } else {
1378 $type =~ s/([^\*])$/$1 /;
1379 print ".BI \" ".$type."\" ".$parameter." \""."\"\n;\n";
1380 }
1381 print "\n.br\n";
1382 }
1383 print "};\n.br\n";
1384
1385 print ".SH Members\n";
1386 foreach $parameter (@{$args{'parameterlist'}}) {
1387 ($parameter =~ /^#/) && next;
1388
1389 my $parameter_name = $parameter;
1390 $parameter_name =~ s/\[.*//;
1391
1392 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1393 print ".IP \"".$parameter."\" 12\n";
1394 output_highlight($args{'parameterdescs'}{$parameter_name});
1395 }
1396 foreach $section (@{$args{'sectionlist'}}) {
1397 print ".SH \"$section\"\n";
1398 output_highlight($args{'sections'}{$section});
1399 }
1400 }
1401
1402 ##
1403 # output typedef in man
1404 sub output_typedef_man(%) {
1405 my %args = %{$_[0]};
1406 my ($parameter, $section);
1407
1408 print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";
1409
1410 print ".SH NAME\n";
1411 print "typedef ".$args{'typedef'}." \\- ".$args{'purpose'}."\n";
1412
1413 foreach $section (@{$args{'sectionlist'}}) {
1414 print ".SH \"$section\"\n";
1415 output_highlight($args{'sections'}{$section});
1416 }
1417 }
1418
1419 sub output_blockhead_man(%) {
1420 my %args = %{$_[0]};
1421 my ($parameter, $section);
1422 my $count;
1423
1424 print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";
1425
1426 foreach $section (@{$args{'sectionlist'}}) {
1427 print ".SH \"$section\"\n";
1428 output_highlight($args{'sections'}{$section});
1429 }
1430 }
1431
1432 ##
1433 # output probe in man
1434 sub output_probe_man(%) {
1435 my %args = %{$_[0]};
1436 my ($parameter, $section);
1437
1438 }
1439
1440 ##
1441 # output sfunction in man
1442 sub output_sfunction_man(%) {
1443 my %args = %{$_[0]};
1444 my ($parameter, $section);
1445
1446 }
1447
1448 ##
1449 # output smacro in man
1450 sub output_smacro_man(%) {
1451 my %args = %{$_[0]};
1452 my ($parameter, $section);
1453
1454 }
1455
1456 ##
1457 # output in text
1458 sub output_function_text(%) {
1459 my %args = %{$_[0]};
1460 my ($parameter, $section);
1461 my $start;
1462
1463 print "Name:\n\n";
1464 print $args{'function'}." - ".$args{'purpose'}."\n";
1465
1466 print "\nSynopsis:\n\n";
1467 if ($args{'functiontype'} ne "") {
1468 $start = $args{'functiontype'}." ".$args{'function'}." (";
1469 } else {
1470 $start = $args{'function'}." (";
1471 }
1472 print $start;
1473
1474 my $count = 0;
1475 foreach my $parameter (@{$args{'parameterlist'}}) {
1476 $type = $args{'parametertypes'}{$parameter};
1477 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1478 # pointer-to-function
1479 print $1.$parameter.") (".$2;
1480 } else {
1481 print $type." ".$parameter;
1482 }
1483 if ($count != $#{$args{'parameterlist'}}) {
1484 $count++;
1485 print ",\n";
1486 print " " x length($start);
1487 } else {
1488 print ");\n\n";
1489 }
1490 }
1491
1492 print "Arguments:\n\n";
1493 foreach $parameter (@{$args{'parameterlist'}}) {
1494 my $parameter_name = $parameter;
1495 $parameter_name =~ s/\[.*//;
1496
1497 print $parameter."\n\t".$args{'parameterdescs'}{$parameter_name}."\n";
1498 }
1499 output_section_text(@_);
1500 }
1501
1502 #output sections in text
1503 sub output_section_text(%) {
1504 my %args = %{$_[0]};
1505 my $section;
1506
1507 print "\n";
1508 foreach $section (@{$args{'sectionlist'}}) {
1509 print "$section:\n\n";
1510 output_highlight($args{'sections'}{$section});
1511 }
1512 print "\n\n";
1513 }
1514
1515 # output enum in text
1516 sub output_enum_text(%) {
1517 my %args = %{$_[0]};
1518 my ($parameter);
1519 my $count;
1520 print "Enum:\n\n";
1521
1522 print "enum ".$args{'enum'}." - ".$args{'purpose'}."\n\n";
1523 print "enum ".$args{'enum'}." {\n";
1524 $count = 0;
1525 foreach $parameter (@{$args{'parameterlist'}}) {
1526 print "\t$parameter";
1527 if ($count != $#{$args{'parameterlist'}}) {
1528 $count++;
1529 print ",";
1530 }
1531 print "\n";
1532 }
1533 print "};\n\n";
1534
1535 print "Constants:\n\n";
1536 foreach $parameter (@{$args{'parameterlist'}}) {
1537 print "$parameter\n\t";
1538 print $args{'parameterdescs'}{$parameter}."\n";
1539 }
1540
1541 output_section_text(@_);
1542 }
1543
1544 # output typedef in text
1545 sub output_typedef_text(%) {
1546 my %args = %{$_[0]};
1547 my ($parameter);
1548 my $count;
1549 print "Typedef:\n\n";
1550
1551 print "typedef ".$args{'typedef'}." - ".$args{'purpose'}."\n";
1552 output_section_text(@_);
1553 }
1554
1555 # output struct as text
1556 sub output_struct_text(%) {
1557 my %args = %{$_[0]};
1558 my ($parameter);
1559
1560 print $args{'type'}." ".$args{'struct'}." - ".$args{'purpose'}."\n\n";
1561 print $args{'type'}." ".$args{'struct'}." {\n";
1562 foreach $parameter (@{$args{'parameterlist'}}) {
1563 if ($parameter =~ /^#/) {
1564 print "$parameter\n";
1565 next;
1566 }
1567
1568 my $parameter_name = $parameter;
1569 $parameter_name =~ s/\[.*//;
1570
1571 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1572 $type = $args{'parametertypes'}{$parameter};
1573 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
1574 # pointer-to-function
1575 print "\t$1 $parameter) ($2);\n";
1576 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1577 # bitfield
1578 print "\t$1 $parameter$2;\n";
1579 } else {
1580 print "\t".$type." ".$parameter.";\n";
1581 }
1582 }
1583 print "};\n\n";
1584
1585 print "Members:\n\n";
1586 foreach $parameter (@{$args{'parameterlist'}}) {
1587 ($parameter =~ /^#/) && next;
1588
1589 my $parameter_name = $parameter;
1590 $parameter_name =~ s/\[.*//;
1591
1592 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1593 print "$parameter\n\t";
1594 print $args{'parameterdescs'}{$parameter_name}."\n";
1595 }
1596 print "\n";
1597 output_section_text(@_);
1598 }
1599
1600 sub output_blockhead_text(%) {
1601 my %args = %{$_[0]};
1602 my ($parameter, $section);
1603
1604 foreach $section (@{$args{'sectionlist'}}) {
1605 print " $section:\n";
1606 print " -> ";
1607 output_highlight($args{'sections'}{$section});
1608 }
1609 }
1610
1611 # output probe as text
1612 sub output_probe_text(%) {
1613 my %args = %{$_[0]};
1614 my ($parameter);
1615
1616 }
1617
1618 # output sfunction as text
1619 sub output_sfunction_text(%) {
1620 my %args = %{$_[0]};
1621 my ($parameter);
1622
1623 }
1624
1625 # output smacro as text
1626 sub output_smacro_text(%) {
1627 my %args = %{$_[0]};
1628 my ($parameter);
1629
1630 }
1631
1632 ##
1633 # generic output function for all types (function, struct/union, typedef, enum);
1634 # calls the generated, variable output_ function name based on
1635 # functype and output_mode
1636 sub output_declaration {
1637 no strict 'refs';
1638 my $name = shift;
1639 my $functype = shift;
1640 my $func = "output_${functype}_$output_mode";
1641 if (($function_only==0) ||
1642 ( $function_only == 1 && defined($function_table{$name})) ||
1643 ( $function_only == 2 && !defined($function_table{$name})))
1644 {
1645 &$func(@_);
1646 $section_counter++;
1647 }
1648 }
1649
1650 ##
1651 # generic output function - calls the right one based on current output mode.
1652 sub output_blockhead {
1653 no strict 'refs';
1654 my $func = "output_blockhead_".$output_mode;
1655 &$func(@_);
1656 $section_counter++;
1657 }
1658
1659 sub dump_probe($$) {
1660 my $x = shift;
1661 my $file = shift;
1662
1663 @parameterlist = keys %parameterdescs;
1664
1665 $declaration_name = $x;
1666 output_declaration($declaration_name,
1667 'probe',
1668 {'probe' => $declaration_name,
1669 'parameterlist' => \@parameterlist,
1670 'module' => $modulename,
1671 'parameterdescs' => \%parameterdescs,
1672 'sectionlist' => \@sectionlist,
1673 'sections' => \%sections,
1674 'purpose' => $declaration_purpose
1675 });
1676 }
1677
1678 ##
1679 # takes a declaration (struct, union, enum, typedef) and
1680 # invokes the right handler. NOT called for functions.
1681 sub dump_declaration($$) {
1682 no strict 'refs';
1683 my ($prototype, $file) = @_;
1684 my $func = "dump_".$decl_type;
1685 &$func(@_);
1686 }
1687
1688 sub dump_union($$) {
1689 dump_struct(@_);
1690 }
1691
1692 sub dump_struct($$) {
1693 my $x = shift;
1694 my $file = shift;
1695
1696 if ($x =~/(struct|union)\s+(\w+)\s*{(.*)}/) {
1697 $declaration_name = $2;
1698 my $members = $3;
1699
1700 # ignore embedded structs or unions
1701 $members =~ s/{.*}//g;
1702
1703 # ignore members marked private:
1704 $members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
1705 $members =~ s/\/\*.*?private:.*//gos;
1706 # strip comments:
1707 $members =~ s/\/\*.*?\*\///gos;
1708
1709 create_parameterlist($members, ';', $file);
1710
1711 output_declaration($declaration_name,
1712 'struct',
1713 {'struct' => $declaration_name,
1714 'module' => $modulename,
1715 'parameterlist' => \@parameterlist,
1716 'parameterdescs' => \%parameterdescs,
1717 'parametertypes' => \%parametertypes,
1718 'sectionlist' => \@sectionlist,
1719 'sections' => \%sections,
1720 'purpose' => $declaration_purpose,
1721 'type' => $decl_type
1722 });
1723 }
1724 else {
1725 print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
1726 ++$errors;
1727 }
1728 }
1729
1730 sub dump_enum($$) {
1731 my $x = shift;
1732 my $file = shift;
1733
1734 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1735 if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1736 $declaration_name = $1;
1737 my $members = $2;
1738
1739 foreach my $arg (split ',', $members) {
1740 $arg =~ s/^\s*(\w+).*/$1/;
1741 push @parameterlist, $arg;
1742 if (!$parameterdescs{$arg}) {
1743 $parameterdescs{$arg} = $undescribed;
1744 print STDERR "Warning(${file}:$.): Enum value '$arg' ".
1745 "not described in enum '$declaration_name'\n";
1746 }
1747
1748 }
1749
1750 output_declaration($declaration_name,
1751 'enum',
1752 {'enum' => $declaration_name,
1753 'module' => $modulename,
1754 'parameterlist' => \@parameterlist,
1755 'parameterdescs' => \%parameterdescs,
1756 'sectionlist' => \@sectionlist,
1757 'sections' => \%sections,
1758 'purpose' => $declaration_purpose
1759 });
1760 }
1761 else {
1762 print STDERR "Error(${file}:$.): Cannot parse enum!\n";
1763 ++$errors;
1764 }
1765 }
1766
1767 sub dump_typedef($$) {
1768 my $x = shift;
1769 my $file = shift;
1770
1771 $x =~ s@/\*.*?\*/@@gos; # strip comments.
1772 while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1773 $x =~ s/\(*.\)\s*;$/;/;
1774 $x =~ s/\[*.\]\s*;$/;/;
1775 }
1776
1777 if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1778 $declaration_name = $1;
1779
1780 output_declaration($declaration_name,
1781 'typedef',
1782 {'typedef' => $declaration_name,
1783 'module' => $modulename,
1784 'sectionlist' => \@sectionlist,
1785 'sections' => \%sections,
1786 'purpose' => $declaration_purpose
1787 });
1788 }
1789 else {
1790 print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
1791 ++$errors;
1792 }
1793 }
1794
1795 sub create_parameterlist($$$) {
1796 my $args = shift;
1797 my $splitter = shift;
1798 my $file = shift;
1799 my $type;
1800 my $param;
1801
1802 # temporarily replace commas inside function pointer definition
1803 while ($args =~ /(\([^\),]+),/) {
1804 $args =~ s/(\([^\),]+),/$1#/g;
1805 }
1806
1807 foreach my $arg (split($splitter, $args)) {
1808 # strip comments
1809 $arg =~ s/\/\*.*\*\///;
1810 # strip leading/trailing spaces
1811 $arg =~ s/^\s*//;
1812 $arg =~ s/\s*$//;
1813 $arg =~ s/\s+/ /;
1814
1815 if ($arg =~ /^#/) {
1816 # Treat preprocessor directive as a typeless variable just to fill
1817 # corresponding data structures "correctly". Catch it later in
1818 # output_* subs.
1819 push_parameter($arg, "", $file);
1820 } elsif ($arg =~ m/\(.+\)\s*\(/) {
1821 # pointer-to-function
1822 $arg =~ tr/#/,/;
1823 $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
1824 $param = $1;
1825 $type = $arg;
1826 $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1827 push_parameter($param, $type, $file);
1828 } elsif ($arg) {
1829 $arg =~ s/\s*:\s*/:/g;
1830 $arg =~ s/\s*\[/\[/g;
1831
1832 my @args = split('\s*,\s*', $arg);
1833 if ($args[0] =~ m/\*/) {
1834 $args[0] =~ s/(\*+)\s*/ $1/;
1835 }
1836
1837 my @first_arg;
1838 if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
1839 shift @args;
1840 push(@first_arg, split('\s+', $1));
1841 push(@first_arg, $2);
1842 } else {
1843 @first_arg = split('\s+', shift @args);
1844 }
1845
1846 unshift(@args, pop @first_arg);
1847 $type = join " ", @first_arg;
1848
1849 foreach $param (@args) {
1850 if ($param =~ m/^(\*+)\s*(.*)/) {
1851 push_parameter($2, "$type $1", $file);
1852 }
1853 elsif ($param =~ m/(.*?):(\d+)/) {
1854 if ($type ne "") { # skip unnamed bit-fields
1855 push_parameter($1, "$type:$2", $file)
1856 }
1857 }
1858 else {
1859 push_parameter($param, $type, $file);
1860 }
1861 }
1862 }
1863 }
1864 }
1865
1866 sub create_sparameterlist($$$) {
1867 my $args = shift;
1868 my $splitter = shift;
1869 my $file = shift;
1870 my $type;
1871 my $param;
1872
1873 foreach my $arg (split($splitter, $args)) {
1874 if ($arg =~ m/\s*([\w]+)\s*:?\s*([\w]*)/) {
1875 $param = $1;
1876 $type = $2;
1877 push_parameter($param, $type, $file);
1878 } else {
1879 print STDERR "Error(${file}:$.): problem parsing parameters: '$prototype'\n";
1880 ++$errors;
1881 return;
1882 }
1883 }
1884 }
1885
1886 sub push_parameter($$$) {
1887 my $param = shift;
1888 my $type = shift;
1889 my $file = shift;
1890
1891 if (($anon_struct_union == 1) && ($type eq "") &&
1892 ($param eq "}")) {
1893 return; # ignore the ending }; from anon. struct/union
1894 }
1895
1896 $anon_struct_union = 0;
1897 my $param_name = $param;
1898 $param_name =~ s/\[.*//;
1899
1900 if ($type eq "" && $param =~ /\.\.\.$/)
1901 {
1902 $type="";
1903 $parameterdescs{$param} = "variable arguments";
1904 }
1905 elsif ($type eq "" && ($param eq "" or $param eq "void"))
1906 {
1907 $type="";
1908 $param="void";
1909 $parameterdescs{void} = "no arguments";
1910 }
1911 elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
1912 # handle unnamed (anonymous) union or struct:
1913 {
1914 $type = $param;
1915 $param = "{unnamed_" . $param . "}";
1916 $parameterdescs{$param} = "anonymous\n";
1917 $anon_struct_union = 1;
1918 }
1919
1920 # warn if parameter has no description
1921 # (but ignore ones starting with # as these are not parameters
1922 # but inline preprocessor statements);
1923 # also ignore unnamed structs/unions;
1924 if (!$anon_struct_union) {
1925 if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {
1926
1927 $parameterdescs{$param_name} = $undescribed;
1928
1929 if (($type eq 'function') || ($type eq 'enum')) {
1930 print STDERR "Warning(${file}:$.): Function parameter ".
1931 "or member '$param' not " .
1932 "described in '$declaration_name'\n";
1933 }
1934 print STDERR "Warning(${file}:$.):".
1935 " No description found for parameter '$param'\n";
1936 ++$warnings;
1937 }
1938 }
1939
1940 push @parameterlist, $param;
1941 $parametertypes{$param} = $type;
1942 }
1943
1944 ##
1945 # takes a function prototype and the name of the current file being
1946 # processed and spits out all the details stored in the global
1947 # arrays/hashes.
1948 sub dump_function($$) {
1949 my $prototype = shift;
1950 my $file = shift;
1951
1952 $prototype =~ s/^static +//;
1953 $prototype =~ s/^extern +//;
1954 $prototype =~ s/^asmlinkage +//;
1955 $prototype =~ s/^inline +//;
1956 $prototype =~ s/^__inline__ +//;
1957 $prototype =~ s/^__inline +//;
1958 $prototype =~ s/^__always_inline +//;
1959 $prototype =~ s/^noinline +//;
1960 $prototype =~ s/__devinit +//;
1961 $prototype =~ s/__init +//;
1962 $prototype =~ s/^#\s*define\s+//; #ak added
1963 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1964
1965 # Yes, this truly is vile. We are looking for:
1966 # 1. Return type (may be nothing if we're looking at a macro)
1967 # 2. Function name
1968 # 3. Function parameters.
1969 #
1970 # All the while we have to watch out for function pointer parameters
1971 # (which IIRC is what the two sections are for), C types (these
1972 # regexps don't even start to express all the possibilities), and
1973 # so on.
1974 #
1975 # If you mess with these regexps, it's a good idea to check that
1976 # the following functions' documentation still comes out right:
1977 # - parport_register_device (function pointer parameters)
1978 # - atomic_set (macro)
1979 # - pci_match_device, __copy_to_user (long return type)
1980
1981 if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1982 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1983 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1984 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1985 $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1986 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1987 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1988 $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1989 $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1990 $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1991 $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1992 $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1993 $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1994 $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1995 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1996 $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1997 $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
1998 $return_type = $1;
1999 $declaration_name = $2;
2000 my $args = $3;
2001
2002 create_parameterlist($args, ',', $file);
2003 } else {
2004 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
2005 ++$errors;
2006 return;
2007 }
2008
2009 output_declaration($declaration_name,
2010 'function',
2011 {'function' => $declaration_name,
2012 'module' => $modulename,
2013 'functiontype' => $return_type,
2014 'parameterlist' => \@parameterlist,
2015 'parameterdescs' => \%parameterdescs,
2016 'parametertypes' => \%parametertypes,
2017 'sectionlist' => \@sectionlist,
2018 'sections' => \%sections,
2019 'purpose' => $declaration_purpose
2020 });
2021 }
2022
2023 ##
2024 # takes a stap function prototype and the name of the current file being
2025 # processed and spits out all the details stored in the global
2026 # arrays/hashes.
2027 sub dump_sfunction($$) {
2028 my $prototype = shift;
2029 my $file = shift;
2030
2031 if ($prototype =~ m/^function\s+([\w]+)\s*:?\s*([\w]*)\s*\(([^\{]*)\)/) {
2032 $declaration_name = $1;
2033 $return_type = $2;
2034 my $args = $3;
2035
2036 create_sparameterlist($args, ',', $file);
2037 } else {
2038 print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
2039 ++$errors;
2040 return;
2041 }
2042
2043 output_declaration($declaration_name,
2044 'sfunction',
2045 {'sfunction' => $declaration_name,
2046 'module' => $modulename,
2047 'functiontype' => $return_type,
2048 'parameterlist' => \@parameterlist,
2049 'parameterdescs' => \%parameterdescs,
2050 'parametertypes' => \%parametertypes,
2051 'sectionlist' => \@sectionlist,
2052 'sections' => \%sections,
2053 'purpose' => $declaration_purpose
2054 });
2055 }
2056
2057 ##
2058 # takes a stap macro prototype and the name of the current file being
2059 # processed and spits out all the details stored in the global
2060 # arrays/hashes.
2061 sub dump_smacro($$) {
2062 my $prototype = shift;
2063 my $file = shift;
2064
2065 if ($prototype =~ m/^\@define\s+([\w]+)\s*\(([^\{]*)\)/) {
2066 $declaration_name = $1;
2067 my $args = $2;
2068
2069 create_sparameterlist($args, ',', $file);
2070 } elsif ($prototype =~ m/^\@define\s+([\w]+)\s*/) {
2071 $declaration_name = $1;
2072 my $args = "";
2073
2074 create_sparameterlist($args, ',', $file);
2075 } else {
2076 print STDERR "Error(${file}:$.): cannot understand macro prototype: '$prototype'\n";
2077 ++$errors;
2078 return;
2079 }
2080
2081 output_declaration($declaration_name,
2082 'smacro',
2083 {'smacro' => $declaration_name,
2084 'module' => $modulename,
2085 'parameterlist' => \@parameterlist,
2086 'parameterdescs' => \%parameterdescs,
2087 'parametertypes' => \%parametertypes,
2088 'sectionlist' => \@sectionlist,
2089 'sections' => \%sections,
2090 'purpose' => $declaration_purpose
2091 });
2092 }
2093
2094 sub process_file($);
2095
2096 # Read the file that maps relative names to absolute names for
2097 # separate source and object directories and for shadow trees.
2098 if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
2099 my ($relname, $absname);
2100 while(<SOURCE_MAP>) {
2101 chop();
2102 ($relname, $absname) = (split())[0..1];
2103 $relname =~ s:^/+::;
2104 $source_map{$relname} = $absname;
2105 }
2106 close(SOURCE_MAP);
2107 }
2108
2109 if ($filelist) {
2110 open(FLIST,"<$filelist") or die "Can't open file list $filelist";
2111 while(<FLIST>) {
2112 chop;
2113 process_file($_);
2114 }
2115 }
2116
2117 foreach (@ARGV) {
2118 chomp;
2119 process_file($_);
2120 }
2121 if ($verbose && $errors) {
2122 print STDERR "$errors errors\n";
2123 }
2124 if ($verbose && $warnings) {
2125 print STDERR "$warnings warnings\n";
2126 }
2127
2128 exit($errors);
2129
2130 sub reset_state {
2131 $function = "";
2132 %constants = ();
2133 %parameterdescs = ();
2134 %parametertypes = ();
2135 @parameterlist = ();
2136 %sections = ();
2137 @sectionlist = ();
2138 $prototype = "";
2139
2140 $state = 0;
2141 }
2142
2143 sub process_state3_function($$) {
2144 my $x = shift;
2145 my $file = shift;
2146
2147 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2148
2149 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2150 # do nothing
2151 }
2152 elsif ($x =~ /([^\{]*)/) {
2153 $prototype .= $1;
2154 }
2155 if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
2156 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2157 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2158 $prototype =~ s@^\s+@@gos; # strip leading spaces
2159 dump_function($prototype,$file);
2160 reset_state();
2161 }
2162 }
2163
2164 sub process_state3_type($$) {
2165 my $x = shift;
2166 my $file = shift;
2167
2168 $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2169 $x =~ s@^\s+@@gos; # strip leading spaces
2170 $x =~ s@\s+$@@gos; # strip trailing spaces
2171 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2172
2173 if ($x =~ /^#/) {
2174 # To distinguish preprocessor directive from regular declaration later.
2175 $x .= ";";
2176 }
2177
2178 while (1) {
2179 if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
2180 $prototype .= $1 . $2;
2181 ($2 eq '{') && $brcount++;
2182 ($2 eq '}') && $brcount--;
2183 if (($2 eq ';') && ($brcount == 0)) {
2184 dump_declaration($prototype,$file);
2185 reset_state();
2186 last;
2187 }
2188 $x = $3;
2189 } else {
2190 $prototype .= $x;
2191 last;
2192 }
2193 }
2194 }
2195
2196 sub process_state3_sfunction($$) {
2197 my $x = shift;
2198 my $file = shift;
2199
2200 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2201
2202 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2203 # do nothing
2204 }
2205 elsif ($x =~ /([^\{]*)/) {
2206 $prototype .= $1;
2207 }
2208
2209 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2210 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2211 $prototype =~ s@^\s+@@gos; # strip leading spaces
2212 dump_sfunction($prototype,$file);
2213 reset_state();
2214 }
2215
2216 sub process_state3_smacro($$) {
2217 my $x = shift;
2218 my $file = shift;
2219
2220 $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line
2221
2222 if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
2223 # do nothing
2224 }
2225 elsif ($x =~ /([^\{]*)/) {
2226 $prototype .= $1;
2227 }
2228
2229 $prototype =~ s@/\*.*?\*/@@gos; # strip comments.
2230 $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
2231 $prototype =~ s@^\s+@@gos; # strip leading spaces
2232 dump_smacro($prototype,$file);
2233 reset_state();
2234 }
2235
2236 sub process_state3_probe($$) {
2237 my $prototype = shift;
2238 my $file = shift;
2239
2240 $prototype =~ s@probe@@o; # strip off leading 'probe'
2241 $prototype =~ s@^\s+@@gos; # strip leading spaces
2242 dump_probe($prototype,$file);
2243 reset_state();
2244 }
2245
2246 # xml_escape: replace <, >, and & in the text stream;
2247 #
2248 # however, formatting controls that are generated internally/locally in the
2249 # kernel-doc script are not escaped here; instead, they begin life like
2250 # $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
2251 # are converted to their mnemonic-expected output, without the 4 * '\' & ':',
2252 # just before actual output; (this is done by local_unescape())
2253 sub xml_escape($) {
2254 my $text = shift;
2255 if (($output_mode eq "text") || ($output_mode eq "man")) {
2256 return $text;
2257 }
2258 $text =~ s/\&/\\\\\\amp;/g;
2259 $text =~ s/\</\\\\\\lt;/g;
2260 $text =~ s/\>/\\\\\\gt;/g;
2261 return $text;
2262 }
2263
2264 # convert local escape strings to html
2265 # local escape strings look like: '\\\\menmonic:' (that's 4 backslashes)
2266 sub local_unescape($) {
2267 my $text = shift;
2268 if (($output_mode eq "text") || ($output_mode eq "man")) {
2269 return $text;
2270 }
2271 $text =~ s/\\\\\\\\lt:/</g;
2272 $text =~ s/\\\\\\\\gt:/>/g;
2273 return $text;
2274 }
2275
2276 sub process_file($) {
2277 my $file;
2278 my $identifier;
2279 my $func;
2280 my $descr;
2281 my $initial_section_counter = $section_counter;
2282
2283 if (defined($ENV{'SRCTREE'})) {
2284 $file = "$ENV{'SRCTREE'}" . "/" . "@_";
2285 }
2286 else {
2287 $file = "@_";
2288 }
2289 if (defined($source_map{$file})) {
2290 $file = $source_map{$file};
2291 }
2292
2293 if (!open(IN,"<$file")) {
2294 print STDERR "Error: Cannot open file $file\n";
2295 ++$errors;
2296 return;
2297 }
2298
2299 $section_counter = 0;
2300 while (<IN>) {
2301 if ($state == 0) {
2302 if (/$doc_start/o) {
2303 $state = 1; # next line is always the function name
2304 $in_doc_sect = 0;
2305 }
2306 } elsif ($state == 1) { # this line is the function name (always)
2307 if (/$doc_block/o) {
2308 $state = 4;
2309 $contents = "";
2310 if ( $1 eq "" ) {
2311 $section = $section_intro;
2312 } else {
2313 $section = $1;
2314 }
2315 }
2316 elsif (/$doc_decl/o) {
2317 $identifier = $1;
2318 if (/\s*([\w\s\.]+?)\s*-/) {
2319 $identifier = $1;
2320 }
2321
2322 $state = 2;
2323 if (/-(.*)/) {
2324 # strip leading/trailing/multiple spaces
2325 $descr= $1;
2326 $descr =~ s/^\s*//;
2327 $descr =~ s/\s*$//;
2328 $descr =~ s/\s+/ /;
2329 $declaration_purpose = xml_escape($descr);
2330 } else {
2331 $declaration_purpose = "";
2332 }
2333
2334 if (($declaration_purpose eq "") && $verbose) {
2335 print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
2336 print STDERR $_;
2337 ++$warnings;
2338 }
2339
2340 if ($identifier =~ m/^struct/) {
2341 $decl_type = 'struct';
2342 } elsif ($identifier =~ m/^union/) {
2343 $decl_type = 'union';
2344 } elsif ($identifier =~ m/^enum/) {
2345 $decl_type = 'enum';
2346 } elsif ($identifier =~ m/^typedef/) {
2347 $decl_type = 'typedef';
2348 } elsif ($identifier =~ m/^probe/) {
2349 $decl_type = 'probe';
2350 } elsif ($identifier =~ m/^sfunction/) {
2351 $decl_type = 'sfunction';
2352 } elsif ($identifier =~ m/^smacro/) {
2353 $decl_type = 'smacro';
2354 } else {
2355 $decl_type = 'function';
2356 }
2357
2358 if ($verbose) {
2359 print STDERR "Info(${file}:$.): Scanning doc for $decl_type $identifier\n";
2360 }
2361 } else {
2362 print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
2363 " - I thought it was a doc line\n";
2364 ++$warnings;
2365 $state = 0;
2366 }
2367 } elsif ($state == 2) { # look for head: lines, and include content
2368 if (/$doc_sect/o) {
2369 $newsection = $1;
2370 $newcontents = $2;
2371
2372 if (($contents ne "") && ($contents ne "\n")) {
2373 if (!$in_doc_sect && $verbose) {
2374 print STDERR "Warning(${file}:$.): contents before sections\n";
2375 ++$warnings;
2376 }
2377 dump_section($file, $section, xml_escape($contents));
2378 $section = $section_default;
2379 }
2380
2381 $in_doc_sect = 1;
2382 $contents = $newcontents;
2383 if ($contents ne "") {
2384 while ((substr($contents, 0, 1) eq " ") ||
2385 substr($contents, 0, 1) eq "\t") {
2386 $contents = substr($contents, 1);
2387 }
2388 $contents .= "\n";
2389 }
2390 $section = $newsection;
2391 } elsif (/$doc_end/) {
2392
2393 if ($contents ne "") {
2394 dump_section($file, $section, xml_escape($contents));
2395 $section = $section_default;
2396 $contents = "";
2397 }
2398 # look for doc_com + <text> + doc_end:
2399 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2400 print STDERR "Warning(${file}:$.): suspicious ending line: $_";
2401 ++$warnings;
2402 }
2403
2404 $prototype = "";
2405 $state = 3;
2406 $brcount = 0;
2407 # print STDERR "end of doc comment, looking for prototype\n";
2408 } elsif (/$doc_content/) {
2409 # miguel-style comment kludge, look for blank lines after
2410 # @parameter line to signify start of description
2411 if ($1 eq "" &&
2412 ($section =~ m/^@/ || $section eq $section_context)) {
2413 dump_section($file, $section, xml_escape($contents));
2414 $section = $section_default;
2415 $contents = "";
2416 } else {
2417 $contents .= $1."\n";
2418 }
2419 } else {
2420 # i dont know - bad line? ignore.
2421 print STDERR "Warning(${file}:$.): bad line: $_";
2422 ++$warnings;
2423 }
2424 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2425 if ($decl_type eq 'function') {
2426 process_state3_function($_, $file);
2427 } elsif ($decl_type eq 'probe') {
2428 process_state3_probe($identifier, $file);
2429 } elsif ($decl_type eq 'sfunction') {
2430 process_state3_sfunction($_, $file);
2431 } elsif ($decl_type eq 'smacro') {
2432 process_state3_smacro($_, $file);
2433 } else {
2434 process_state3_type($_, $file);
2435 }
2436 } elsif ($state == 4) {
2437 # Documentation block
2438 if (/$doc_block/) {
2439 dump_doc_section($file, $section, xml_escape($contents));
2440 $contents = "";
2441 $function = "";
2442 %constants = ();
2443 %parameterdescs = ();
2444 %parametertypes = ();
2445 @parameterlist = ();
2446 %sections = ();
2447 @sectionlist = ();
2448 $prototype = "";
2449 if ( $1 eq "" ) {
2450 $section = $section_intro;
2451 } else {
2452 $section = $1;
2453 }
2454 }
2455 elsif (/$doc_end/)
2456 {
2457 dump_doc_section($file, $section, xml_escape($contents));
2458 $contents = "";
2459 $function = "";
2460 %constants = ();
2461 %parameterdescs = ();
2462 %parametertypes = ();
2463 @parameterlist = ();
2464 %sections = ();
2465 @sectionlist = ();
2466 $prototype = "";
2467 $state = 0;
2468 }
2469 elsif (/$doc_content/)
2470 {
2471 if ( $1 eq "" )
2472 {
2473 $contents .= $blankline;
2474 }
2475 else
2476 {
2477 $contents .= $1 . "\n";
2478 }
2479 }
2480 }
2481 }
2482 if ($initial_section_counter == $section_counter) {
2483 print STDERR "Warning(${file}): no structured comments found\n";
2484 if ($output_mode eq "xml") {
2485 # The template wants at least one RefEntry here; make one.
2486 print "<refentry>\n";
2487 print " <refnamediv>\n";
2488 print " <refname>\n";
2489 print " ${file}\n";
2490 print " </refname>\n";
2491 print " <refpurpose>\n";
2492 print " Document generation inconsistency\n";
2493 print " </refpurpose>\n";
2494 print " </refnamediv>\n";
2495 print " <refsect1>\n";
2496 print " <title>\n";
2497 print " Oops\n";
2498 print " </title>\n";
2499 print " <warning>\n";
2500 print " <para>\n";
2501 print " The template for this document tried to insert\n";
2502 print " the structured comment from the file\n";
2503 print " <filename>${file}</filename> at this point,\n";
2504 print " but none was found.\n";
2505 print " This dummy section is inserted to allow\n";
2506 print " generation to continue.\n";
2507 print " </para>\n";
2508 print " </warning>\n";
2509 print " </refsect1>\n";
2510 print "</refentry>\n";
2511 }
2512 }
2513 }