kernel-doc 60.9 KB
Newer Older
L
Linus Torvalds 已提交
1 2 3 4 5 6 7
#!/usr/bin/perl -w

use strict;

## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
## Copyright (C) 2001  Simon Huggins                             ##
R
Randy Dunlap 已提交
8
## Copyright (C) 2005-2009  Randy Dunlap                         ##
L
Linus Torvalds 已提交
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46
## 								 ##
## #define enhancements by Armin Kuster <akuster@mvista.com>	 ##
## Copyright (c) 2000 MontaVista Software, Inc.			 ##
## 								 ##
## This software falls under the GNU General Public License.     ##
## Please read the COPYING file for more information             ##

# 18/01/2001 - 	Cleanups
# 		Functions prototyped as foo(void) same as foo()
# 		Stop eval'ing where we don't need to.
# -- huggie@earth.li

# 27/06/2001 -  Allowed whitespace after initial "/**" and
#               allowed comments before function declarations.
# -- Christian Kreibich <ck@whoop.org>

# Still to do:
# 	- add perldoc documentation
# 	- Look more closely at some of the scarier bits :)

# 26/05/2001 - 	Support for separate source and object trees.
#		Return error code.
# 		Keith Owens <kaos@ocs.com.au>

# 23/09/2001 - Added support for typedefs, structs, enums and unions
#              Support for Context section; can be terminated using empty line
#              Small fixes (like spaces vs. \s in regex)
# -- Tim Jansen <tim@tjansen.de>


#
# This will read a 'c' file and scan for embedded comments in the
# style of gnome comments (+minor extensions - see below).
#

# Note: This only supports 'c'.

# usage:
47
# kernel-doc [ -docbook | -html | -text | -man ] [ -no-doc-sections ]
L
Linus Torvalds 已提交
48 49 50 51 52 53
#           [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
# or
#           [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
#
#  Set output format using one of -docbook -html -text or -man.  Default is man.
#
54 55 56
#  -no-doc-sections
#	Do not output DOC: sections
#
L
Linus Torvalds 已提交
57
#  -function funcname
58 59
#	If set, then only generate documentation for the given function(s) or
#	DOC: section titles.  All other functions and DOC: sections are ignored.
L
Linus Torvalds 已提交
60 61
#
#  -nofunction funcname
62 63 64
#	If set, then only generate documentation for the other function(s)/DOC:
#	sections. Cannot be used together with -function (yes, that's a bug --
#	perl hackers can fix it 8))
L
Linus Torvalds 已提交
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
#
#  c files - list of 'c' files to process
#
#  All output goes to stdout, with errors to stderr.

#
# format of comments.
# In the following table, (...)? signifies optional structure.
#                         (...)* signifies 0 or more structure elements
# /**
#  * function_name(:)? (- short description)?
# (* @parameterx: (description of parameter x)?)*
# (* a blank line)?
#  * (Description:)? (Description of function)?
#  * (section header: (section description)? )*
#  (*)?*/
#
# So .. the trivial example would be:
#
# /**
#  * my_function
R
Randy Dunlap 已提交
86
#  */
L
Linus Torvalds 已提交
87
#
88
# If the Description: header tag is omitted, then there must be a blank line
L
Linus Torvalds 已提交
89 90 91 92 93 94
# after the last parameter specification.
# e.g.
# /**
#  * my_function - does my stuff
#  * @my_arg: its mine damnit
#  *
95
#  * Does my stuff explained.
L
Linus Torvalds 已提交
96 97 98 99 100 101
#  */
#
#  or, could also use:
# /**
#  * my_function - does my stuff
#  * @my_arg: its mine damnit
102
#  * Description: Does my stuff explained.
L
Linus Torvalds 已提交
103 104 105
#  */
# etc.
#
R
Randy Dunlap 已提交
106
# Besides functions you can also write documentation for structs, unions,
107 108 109
# enums and typedefs. Instead of the function name you must write the name
# of the declaration;  the struct/union/enum/typedef must always precede
# the name. Nesting of declarations is not supported.
L
Linus Torvalds 已提交
110 111 112 113 114 115
# Use the argument mechanism to document members or constants.
# e.g.
# /**
#  * struct my_struct - short description
#  * @a: first member
#  * @b: second member
116
#  *
L
Linus Torvalds 已提交
117 118 119 120 121
#  * Longer description
#  */
# struct my_struct {
#     int a;
#     int b;
122 123
# /* private: */
#     int c;
L
Linus Torvalds 已提交
124 125 126
# };
#
# All descriptions can be multiline, except the short function description.
127 128 129
#
# You can also add additional sections. When documenting kernel functions you
# should document the "Context:" of the function, e.g. whether the functions
L
Linus Torvalds 已提交
130
# can be called form interrupts. Unlike other sections you can end it with an
131 132
# empty line.
# Example-sections should contain the string EXAMPLE so that they are marked
L
Linus Torvalds 已提交
133 134 135 136 137 138 139
# appropriately in DocBook.
#
# Example:
# /**
#  * user_function - function that can only be called in user context
#  * @a: some argument
#  * Context: !in_interrupt()
140
#  *
L
Linus Torvalds 已提交
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
#  * Some description
#  * Example:
#  *    user_function(22);
#  */
# ...
#
#
# All descriptive text is further processed, scanning for the following special
# patterns, which are highlighted appropriately.
#
# 'funcname()' - function
# '$ENVVAR' - environmental variable
# '&struct_name' - name of a structure (up to two words including 'struct')
# '@parameter' - name of a parameter
# '%CONST' - name of a constant.

my $errors = 0;
my $warnings = 0;
159
my $anon_struct_union = 0;
L
Linus Torvalds 已提交
160 161 162 163 164

# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
my $type_param = '\@(\w+)';
165
my $type_struct = '\&((struct\s*)*[_\w]+)';
R
Randy Dunlap 已提交
166
my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
L
Linus Torvalds 已提交
167 168 169 170 171 172 173 174
my $type_env = '(\$\w+)';

# Output conversion substitutions.
#  One for each output format

# these work fairly well
my %highlights_html = ( $type_constant, "<i>\$1</i>",
			$type_func, "<b>\$1</b>",
175 176
			$type_struct_xml, "<i>\$1</i>",
			$type_env, "<b><i>\$1</i></b>",
L
Linus Torvalds 已提交
177
			$type_param, "<tt><b>\$1</b></tt>" );
R
Randy Dunlap 已提交
178 179 180
my $local_lt = "\\\\\\\\lt:";
my $local_gt = "\\\\\\\\gt:";
my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
L
Linus Torvalds 已提交
181 182 183 184 185

# XML, docbook format
my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
			$type_constant, "<constant>\$1</constant>",
			$type_func, "<function>\$1</function>",
J
Johannes Berg 已提交
186
			$type_struct_xml, "<structname>\$1</structname>",
L
Linus Torvalds 已提交
187 188
			$type_env, "<envar>\$1</envar>",
			$type_param, "<parameter>\$1</parameter>" );
J
Johannes Berg 已提交
189
my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
L
Linus Torvalds 已提交
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214

# gnome, docbook format
my %highlights_gnome = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>",
			 $type_func, "<function>\$1</function>",
			 $type_struct, "<structname>\$1</structname>",
			 $type_env, "<envar>\$1</envar>",
			 $type_param, "<parameter>\$1</parameter>" );
my $blankline_gnome = "</para><para>\n";

# these are pretty rough
my %highlights_man = ( $type_constant, "\$1",
		       $type_func, "\\\\fB\$1\\\\fP",
		       $type_struct, "\\\\fI\$1\\\\fP",
		       $type_param, "\\\\fI\$1\\\\fP" );
my $blankline_man = "";

# text-mode
my %highlights_text = ( $type_constant, "\$1",
			$type_func, "\$1",
			$type_struct, "\$1",
			$type_param, "\$1" );
my $blankline_text = "";


sub usage {
215
    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man ] [ -no-doc-sections ]\n";
L
Linus Torvalds 已提交
216 217 218
    print "         [ -function funcname [ -function funcname ...] ]\n";
    print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
    print "         c source file(s) > outputfile\n";
219
    print "         -v : verbose output, more warnings & other info listed\n";
L
Linus Torvalds 已提交
220 221 222 223
    exit 1;
}

# read arguments
R
Randy Dunlap 已提交
224
if ($#ARGV == -1) {
L
Linus Torvalds 已提交
225 226 227 228 229
    usage();
}

my $verbose = 0;
my $output_mode = "man";
230
my $no_doc_sections = 0;
L
Linus Torvalds 已提交
231 232 233 234
my %highlights = %highlights_man;
my $blankline = $blankline_man;
my $modulename = "Kernel API";
my $function_only = 0;
235 236 237
my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
		'July', 'August', 'September', 'October',
		'November', 'December')[(localtime)[4]] .
L
Linus Torvalds 已提交
238 239 240
  " " . ((localtime)[5]+1900);

# Essentially these are globals
R
Randy Dunlap 已提交
241 242
# They probably want to be tidied up, made more localised or something.
# CAVEAT EMPTOR!  Some of the others I localised may not want to be, which
L
Linus Torvalds 已提交
243
# could cause "use of undefined value" or other bugs.
R
Randy Dunlap 已提交
244 245
my ($function, %function_table, %parametertypes, $declaration_purpose);
my ($type, $declaration_name, $return_type);
246
my ($newsection, $newcontents, $prototype, $brcount, %source_map);
L
Linus Torvalds 已提交
247

248 249 250 251
if (defined($ENV{'KBUILD_VERBOSE'})) {
	$verbose = "$ENV{'KBUILD_VERBOSE'}";
}

252
# Generated docbook code is inserted in a template at a point where
L
Linus Torvalds 已提交
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
# We keep track of number of generated entries and generate a dummy
# if needs be to ensure the expanded template can be postprocessed
# into html.
my $section_counter = 0;

my $lineprefix="";

# states
# 0 - normal code
# 1 - looking for function name
# 2 - scanning field start.
# 3 - scanning prototype.
# 4 - documentation block
my $state;
269
my $in_doc_sect;
L
Linus Torvalds 已提交
270 271 272 273 274 275 276 277 278 279

#declaration types: can be
# 'function', 'struct', 'union', 'enum', 'typedef'
my $decl_type;

my $doc_special = "\@\%\$\&";

my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
R
Randy Dunlap 已提交
280 281 282 283
my $doc_decl = $doc_com . '(\w+)';
my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
my $doc_content = $doc_com . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
L
Linus Torvalds 已提交
284 285 286 287 288 289

my %constants;
my %parameterdescs;
my @parameterlist;
my %sections;
my @sectionlist;
290 291
my $sectcheck;
my $struct_actual;
L
Linus Torvalds 已提交
292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338

my $contents = "";
my $section_default = "Description";	# default section
my $section_intro = "Introduction";
my $section = $section_default;
my $section_context = "Context";

my $undescribed = "-- undescribed --";

reset_state();

while ($ARGV[0] =~ m/^-(.*)/) {
    my $cmd = shift @ARGV;
    if ($cmd eq "-html") {
	$output_mode = "html";
	%highlights = %highlights_html;
	$blankline = $blankline_html;
    } elsif ($cmd eq "-man") {
	$output_mode = "man";
	%highlights = %highlights_man;
	$blankline = $blankline_man;
    } elsif ($cmd eq "-text") {
	$output_mode = "text";
	%highlights = %highlights_text;
	$blankline = $blankline_text;
    } elsif ($cmd eq "-docbook") {
	$output_mode = "xml";
	%highlights = %highlights_xml;
	$blankline = $blankline_xml;
    } elsif ($cmd eq "-gnome") {
	$output_mode = "gnome";
	%highlights = %highlights_gnome;
	$blankline = $blankline_gnome;
    } elsif ($cmd eq "-module") { # not needed for XML, inherits from calling document
	$modulename = shift @ARGV;
    } elsif ($cmd eq "-function") { # to only output specific functions
	$function_only = 1;
	$function = shift @ARGV;
	$function_table{$function} = 1;
    } elsif ($cmd eq "-nofunction") { # to only output specific functions
	$function_only = 2;
	$function = shift @ARGV;
	$function_table{$function} = 1;
    } elsif ($cmd eq "-v") {
	$verbose = 1;
    } elsif (($cmd eq "-h") || ($cmd eq "--help")) {
	usage();
339 340
    } elsif ($cmd eq '-no-doc-sections') {
	    $no_doc_sections = 1;
L
Linus Torvalds 已提交
341 342 343
    }
}

344 345
# get kernel version from env
sub get_kernel_version() {
J
Johannes Berg 已提交
346
    my $version = 'unknown kernel version';
347 348 349 350 351 352

    if (defined($ENV{'KERNELVERSION'})) {
	$version = $ENV{'KERNELVERSION'};
    }
    return $version;
}
353
my $kernelversion = get_kernel_version();
L
Linus Torvalds 已提交
354 355 356 357 358

# generate a sequence of code that will splice in highlighting information
# using the s// operator.
my $dohighlight = "";
foreach my $pattern (keys %highlights) {
359
#   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
L
Linus Torvalds 已提交
360 361 362 363 364 365 366
    $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
}

##
# dumps section contents to arrays/hashes intended for that purpose.
#
sub dump_section {
367
    my $file = shift;
L
Linus Torvalds 已提交
368 369 370 371 372 373 374 375 376 377 378
    my $name = shift;
    my $contents = join "\n", @_;

    if ($name =~ m/$type_constant/) {
	$name = $1;
#	print STDERR "constant section '$1' = '$contents'\n";
	$constants{$name} = $contents;
    } elsif ($name =~ m/$type_param/) {
#	print STDERR "parameter def '$1' = '$contents'\n";
	$name = $1;
	$parameterdescs{$name} = $contents;
379
	$sectcheck = $sectcheck . $name . " ";
R
Randy Dunlap 已提交
380 381 382 383
    } elsif ($name eq "@\.\.\.") {
#	print STDERR "parameter def '...' = '$contents'\n";
	$name = "...";
	$parameterdescs{$name} = $contents;
384
	$sectcheck = $sectcheck . $name . " ";
L
Linus Torvalds 已提交
385 386
    } else {
#	print STDERR "other section '$name' = '$contents'\n";
387 388 389 390
	if (defined($sections{$name}) && ($sections{$name} ne "")) {
		print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
		++$errors;
	}
L
Linus Torvalds 已提交
391 392 393 394 395
	$sections{$name} = $contents;
	push @sectionlist, $name;
    }
}

396 397 398 399
##
# dump DOC: section after checking that it should go out
#
sub dump_doc_section {
400
    my $file = shift;
401 402 403
    my $name = shift;
    my $contents = join "\n", @_;

404 405 406 407
    if ($no_doc_sections) {
        return;
    }

408 409 410 411
    if (($function_only == 0) ||
	( $function_only == 1 && defined($function_table{$name})) ||
	( $function_only == 2 && !defined($function_table{$name})))
    {
412
	dump_section($file, $name, $contents);
413 414 415 416 417 418 419
	output_blockhead({'sectionlist' => \@sectionlist,
			  'sections' => \%sections,
			  'module' => $modulename,
			  'content-only' => ($function_only != 0), });
    }
}

L
Linus Torvalds 已提交
420 421 422 423 424 425 426 427
##
# output function
#
# parameterdescs, a hash.
#  function => "function name"
#  parameterlist => @list of parameters
#  parameterdescs => %parameter descriptions
#  sectionlist => @list of sections
428
#  sections => %section descriptions
429
#
L
Linus Torvalds 已提交
430 431 432 433 434 435 436 437 438 439 440

sub output_highlight {
    my $contents = join "\n",@_;
    my $line;

#   DEBUG
#   if (!defined $contents) {
#	use Carp;
#	confess "output_highlight got called with no args?\n";
#   }

J
Johannes Berg 已提交
441
    if ($output_mode eq "html" || $output_mode eq "xml") {
R
Randy Dunlap 已提交
442 443 444 445
	$contents = local_unescape($contents);
	# convert data read & converted thru xml_escape() into &xyz; format:
	$contents =~ s/\\\\\\/&/g;
    }
446
#   print STDERR "contents b4:$contents\n";
L
Linus Torvalds 已提交
447 448
    eval $dohighlight;
    die $@ if $@;
449 450
#   print STDERR "contents af:$contents\n";

L
Linus Torvalds 已提交
451
    foreach $line (split "\n", $contents) {
452
	if ($line eq ""){
R
Randy Dunlap 已提交
453
	    print $lineprefix, local_unescape($blankline);
L
Linus Torvalds 已提交
454
	} else {
455
	    $line =~ s/\\\\\\/\&/g;
456 457 458 459 460
	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
		print "\\&$line";
	    } else {
		print $lineprefix, $line;
	    }
L
Linus Torvalds 已提交
461 462 463 464 465 466 467 468 469 470 471 472 473 474 475
	}
	print "\n";
    }
}

#output sections in html
sub output_section_html(%) {
    my %args = %{$_[0]};
    my $section;

    foreach $section (@{$args{'sectionlist'}}) {
	print "<h3>$section</h3>\n";
	print "<blockquote>\n";
	output_highlight($args{'sections'}{$section});
	print "</blockquote>\n";
476
    }
L
Linus Torvalds 已提交
477 478 479 480 481 482 483
}

# output enum in html
sub output_enum_html(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
R
Randy Dunlap 已提交
484
    print "<h2>enum " . $args{'enum'} . "</h2>\n";
L
Linus Torvalds 已提交
485

R
Randy Dunlap 已提交
486
    print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
L
Linus Torvalds 已提交
487 488
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
R
Randy Dunlap 已提交
489
	print " <b>" . $parameter . "</b>";
L
Linus Torvalds 已提交
490 491 492 493 494 495 496 497 498 499 500
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",\n";
	}
	print "<br>";
    }
    print "};<br>\n";

    print "<h3>Constants</h3>\n";
    print "<dl>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
R
Randy Dunlap 已提交
501
	print "<dt><b>" . $parameter . "</b>\n";
L
Linus Torvalds 已提交
502 503 504 505 506 507 508 509
	print "<dd>";
	output_highlight($args{'parameterdescs'}{$parameter});
    }
    print "</dl>\n";
    output_section_html(@_);
    print "<hr>\n";
}

510
# output typedef in html
L
Linus Torvalds 已提交
511 512 513 514
sub output_typedef_html(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
R
Randy Dunlap 已提交
515
    print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
L
Linus Torvalds 已提交
516

R
Randy Dunlap 已提交
517
    print "<b>typedef " . $args{'typedef'} . "</b>\n";
L
Linus Torvalds 已提交
518 519 520 521 522 523 524 525 526
    output_section_html(@_);
    print "<hr>\n";
}

# output struct in html
sub output_struct_html(%) {
    my %args = %{$_[0]};
    my ($parameter);

R
Randy Dunlap 已提交
527 528
    print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
    print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
L
Linus Torvalds 已提交
529 530 531 532 533 534 535 536
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
		print "$parameter<br>\n";
		next;
	}
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

537
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
538 539 540
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
541
	    print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
L
Linus Torvalds 已提交
542
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
543 544
	    # bitfield
	    print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
L
Linus Torvalds 已提交
545
	} else {
546
	    print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
L
Linus Torvalds 已提交
547 548 549 550 551 552 553 554 555 556 557 558
	}
    }
    print "};<br>\n";

    print "<h3>Members</h3>\n";
    print "<dl>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	($parameter =~ /^#/) && next;

	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

559
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
R
Randy Dunlap 已提交
560
	print "<dt><b>" . $parameter . "</b>\n";
L
Linus Torvalds 已提交
561 562 563 564 565 566 567 568 569 570 571 572 573 574
	print "<dd>";
	output_highlight($args{'parameterdescs'}{$parameter_name});
    }
    print "</dl>\n";
    output_section_html(@_);
    print "<hr>\n";
}

# output function in html
sub output_function_html(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

R
Randy Dunlap 已提交
575 576 577
    print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
    print "<i>" . $args{'functiontype'} . "</i>\n";
    print "<b>" . $args{'function'} . "</b>\n";
L
Linus Torvalds 已提交
578 579 580 581 582 583 584 585
    print "(";
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "<i>$1</i><b>$parameter</b>) <i>($2)</i>";
	} else {
R
Randy Dunlap 已提交
586
	    print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
L
Linus Torvalds 已提交
587 588 589 590 591 592 593 594 595 596 597 598 599 600
	}
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",\n";
	}
    }
    print ")\n";

    print "<h3>Arguments</h3>\n";
    print "<dl>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

601
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
R
Randy Dunlap 已提交
602
	print "<dt><b>" . $parameter . "</b>\n";
L
Linus Torvalds 已提交
603 604 605 606 607 608 609 610
	print "<dd>";
	output_highlight($args{'parameterdescs'}{$parameter_name});
    }
    print "</dl>\n";
    output_section_html(@_);
    print "<hr>\n";
}

611 612
# output DOC: block header in html
sub output_blockhead_html(%) {
L
Linus Torvalds 已提交
613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    foreach $section (@{$args{'sectionlist'}}) {
	print "<h3>$section</h3>\n";
	print "<ul>\n";
	output_highlight($args{'sections'}{$section});
	print "</ul>\n";
    }
    print "<hr>\n";
}

sub output_section_xml(%) {
    my %args = %{$_[0]};
628
    my $section;
L
Linus Torvalds 已提交
629 630 631
    # print out each section
    $lineprefix="   ";
    foreach $section (@{$args{'sectionlist'}}) {
632 633
	print "<refsect1>\n";
	print "<title>$section</title>\n";
L
Linus Torvalds 已提交
634
	if ($section =~ m/EXAMPLE/i) {
635 636 637
	    print "<informalexample><programlisting>\n";
	} else {
	    print "<para>\n";
L
Linus Torvalds 已提交
638 639 640
	}
	output_highlight($args{'sections'}{$section});
	if ($section =~ m/EXAMPLE/i) {
641 642 643
	    print "</programlisting></informalexample>\n";
	} else {
	    print "</para>\n";
L
Linus Torvalds 已提交
644
	}
645
	print "</refsect1>\n";
L
Linus Torvalds 已提交
646 647 648 649 650 651 652 653 654 655
    }
}

# output function in XML DocBook
sub output_function_xml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;
    my $id;

R
Randy Dunlap 已提交
656
    $id = "API-" . $args{'function'};
L
Linus Torvalds 已提交
657 658
    $id =~ s/[^A-Za-z0-9]/-/g;

659
    print "<refentry id=\"$id\">\n";
660 661 662 663 664
    print "<refentryinfo>\n";
    print " <title>LINUX</title>\n";
    print " <productname>Kernel Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
L
Linus Torvalds 已提交
665
    print "<refmeta>\n";
R
Randy Dunlap 已提交
666
    print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
667
    print " <manvolnum>9</manvolnum>\n";
668
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
L
Linus Torvalds 已提交
669 670
    print "</refmeta>\n";
    print "<refnamediv>\n";
R
Randy Dunlap 已提交
671
    print " <refname>" . $args{'function'} . "</refname>\n";
L
Linus Torvalds 已提交
672 673 674 675 676 677 678 679 680
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <funcsynopsis><funcprototype>\n";
R
Randy Dunlap 已提交
681 682
    print "   <funcdef>" . $args{'functiontype'} . " ";
    print "<function>" . $args{'function'} . " </function></funcdef>\n";
L
Linus Torvalds 已提交
683 684 685 686 687 688 689 690 691 692

    $count = 0;
    if ($#{$args{'parameterlist'}} >= 0) {
	foreach $parameter (@{$args{'parameterlist'}}) {
	    $type = $args{'parametertypes'}{$parameter};
	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
		# pointer-to-function
		print "   <paramdef>$1<parameter>$parameter</parameter>)\n";
		print "     <funcparams>$2</funcparams></paramdef>\n";
	    } else {
R
Randy Dunlap 已提交
693
		print "   <paramdef>" . $type;
L
Linus Torvalds 已提交
694 695 696 697
		print " <parameter>$parameter</parameter></paramdef>\n";
	    }
	}
    } else {
698
	print "  <void/>\n";
L
Linus Torvalds 已提交
699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732
    }
    print "  </funcprototype></funcsynopsis>\n";
    print "</refsynopsisdiv>\n";

    # print parameters
    print "<refsect1>\n <title>Arguments</title>\n";
    if ($#{$args{'parameterlist'}} >= 0) {
	print " <variablelist>\n";
	foreach $parameter (@{$args{'parameterlist'}}) {
	    my $parameter_name = $parameter;
	    $parameter_name =~ s/\[.*//;

	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
	    print "   <listitem>\n    <para>\n";
	    $lineprefix="     ";
	    output_highlight($args{'parameterdescs'}{$parameter_name});
	    print "    </para>\n   </listitem>\n  </varlistentry>\n";
	}
	print " </variablelist>\n";
    } else {
	print " <para>\n  None\n </para>\n";
    }
    print "</refsect1>\n";

    output_section_xml(@_);
    print "</refentry>\n\n";
}

# output struct in XML DocBook
sub output_struct_xml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $id;

R
Randy Dunlap 已提交
733
    $id = "API-struct-" . $args{'struct'};
L
Linus Torvalds 已提交
734 735
    $id =~ s/[^A-Za-z0-9]/-/g;

736
    print "<refentry id=\"$id\">\n";
737 738 739 740 741
    print "<refentryinfo>\n";
    print " <title>LINUX</title>\n";
    print " <productname>Kernel Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
L
Linus Torvalds 已提交
742
    print "<refmeta>\n";
R
Randy Dunlap 已提交
743
    print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
744
    print " <manvolnum>9</manvolnum>\n";
745
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
L
Linus Torvalds 已提交
746 747
    print "</refmeta>\n";
    print "<refnamediv>\n";
R
Randy Dunlap 已提交
748
    print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
L
Linus Torvalds 已提交
749 750 751 752 753 754 755 756 757
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <programlisting>\n";
R
Randy Dunlap 已提交
758
    print $args{'type'} . " " . $args{'struct'} . " {\n";
L
Linus Torvalds 已提交
759 760 761 762 763 764 765 766 767 768
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
	    print "$parameter\n";
	    next;
	}

	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

	defined($args{'parameterdescs'}{$parameter_name}) || next;
769
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
770 771 772 773 774
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "  $1 $parameter) ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
R
Randy Dunlap 已提交
775
	    # bitfield
L
Linus Torvalds 已提交
776 777
	    print "  $1 $parameter$2;\n";
	} else {
R
Randy Dunlap 已提交
778
	    print "  " . $type . " " . $parameter . ";\n";
L
Linus Torvalds 已提交
779 780 781 782 783 784 785 786 787
	}
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

    print " <refsect1>\n";
    print "  <title>Members</title>\n";

788
    if ($#{$args{'parameterlist'}} >= 0) {
L
Linus Torvalds 已提交
789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805
    print "  <variablelist>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
      ($parameter =~ /^#/) && next;

      my $parameter_name = $parameter;
      $parameter_name =~ s/\[.*//;

      defined($args{'parameterdescs'}{$parameter_name}) || next;
      ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
      print "    <varlistentry>";
      print "      <term>$parameter</term>\n";
      print "      <listitem><para>\n";
      output_highlight($args{'parameterdescs'}{$parameter_name});
      print "      </para></listitem>\n";
      print "    </varlistentry>\n";
    }
    print "  </variablelist>\n";
806 807 808
    } else {
	print " <para>\n  None\n </para>\n";
    }
L
Linus Torvalds 已提交
809 810 811 812 813 814 815 816 817 818 819 820 821 822
    print " </refsect1>\n";

    output_section_xml(@_);

    print "</refentry>\n\n";
}

# output enum in XML DocBook
sub output_enum_xml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;
    my $id;

R
Randy Dunlap 已提交
823
    $id = "API-enum-" . $args{'enum'};
L
Linus Torvalds 已提交
824 825
    $id =~ s/[^A-Za-z0-9]/-/g;

826
    print "<refentry id=\"$id\">\n";
827 828 829 830 831
    print "<refentryinfo>\n";
    print " <title>LINUX</title>\n";
    print " <productname>Kernel Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
L
Linus Torvalds 已提交
832
    print "<refmeta>\n";
R
Randy Dunlap 已提交
833
    print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
834
    print " <manvolnum>9</manvolnum>\n";
835
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
L
Linus Torvalds 已提交
836 837
    print "</refmeta>\n";
    print "<refnamediv>\n";
R
Randy Dunlap 已提交
838
    print " <refname>enum " . $args{'enum'} . "</refname>\n";
L
Linus Torvalds 已提交
839 840 841 842 843 844 845 846 847
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <programlisting>\n";
R
Randy Dunlap 已提交
848
    print "enum " . $args{'enum'} . " {\n";
L
Linus Torvalds 已提交
849 850
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
851 852
	print "  $parameter";
	if ($count != $#{$args{'parameterlist'}}) {
L
Linus Torvalds 已提交
853 854
	    $count++;
	    print ",";
855
	}
L
Linus Torvalds 已提交
856 857 858 859 860 861 862
	print "\n";
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

    print "<refsect1>\n";
863
    print " <title>Constants</title>\n";
L
Linus Torvalds 已提交
864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889
    print "  <variablelist>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
      my $parameter_name = $parameter;
      $parameter_name =~ s/\[.*//;

      print "    <varlistentry>";
      print "      <term>$parameter</term>\n";
      print "      <listitem><para>\n";
      output_highlight($args{'parameterdescs'}{$parameter_name});
      print "      </para></listitem>\n";
      print "    </varlistentry>\n";
    }
    print "  </variablelist>\n";
    print "</refsect1>\n";

    output_section_xml(@_);

    print "</refentry>\n\n";
}

# output typedef in XML DocBook
sub output_typedef_xml(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $id;

R
Randy Dunlap 已提交
890
    $id = "API-typedef-" . $args{'typedef'};
L
Linus Torvalds 已提交
891 892
    $id =~ s/[^A-Za-z0-9]/-/g;

893
    print "<refentry id=\"$id\">\n";
894 895 896 897 898
    print "<refentryinfo>\n";
    print " <title>LINUX</title>\n";
    print " <productname>Kernel Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
L
Linus Torvalds 已提交
899
    print "<refmeta>\n";
R
Randy Dunlap 已提交
900
    print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
901
    print " <manvolnum>9</manvolnum>\n";
L
Linus Torvalds 已提交
902 903
    print "</refmeta>\n";
    print "<refnamediv>\n";
R
Randy Dunlap 已提交
904
    print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
L
Linus Torvalds 已提交
905 906 907 908 909 910 911 912
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
R
Randy Dunlap 已提交
913
    print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
L
Linus Torvalds 已提交
914 915 916 917 918 919 920 921
    print "</refsynopsisdiv>\n";

    output_section_xml(@_);

    print "</refentry>\n\n";
}

# output in XML DocBook
922
sub output_blockhead_xml(%) {
L
Linus Torvalds 已提交
923 924 925 926 927 928 929 930 931 932
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    my $id = $args{'module'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    # print out each section
    $lineprefix="   ";
    foreach $section (@{$args{'sectionlist'}}) {
933 934 935
	if (!$args{'content-only'}) {
		print "<refsect1>\n <title>$section</title>\n";
	}
L
Linus Torvalds 已提交
936 937
	if ($section =~ m/EXAMPLE/i) {
	    print "<example><para>\n";
938 939
	} else {
	    print "<para>\n";
L
Linus Torvalds 已提交
940 941 942 943
	}
	output_highlight($args{'sections'}{$section});
	if ($section =~ m/EXAMPLE/i) {
	    print "</para></example>\n";
944 945 946 947 948
	} else {
	    print "</para>";
	}
	if (!$args{'content-only'}) {
		print "\n</refsect1>\n";
L
Linus Torvalds 已提交
949 950 951 952 953 954 955 956 957 958 959 960 961
	}
    }

    print "\n\n";
}

# output in XML DocBook
sub output_function_gnome {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;
    my $id;

R
Randy Dunlap 已提交
962
    $id = $args{'module'} . "-" . $args{'function'};
L
Linus Torvalds 已提交
963 964 965
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<sect2>\n";
R
Randy Dunlap 已提交
966
    print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
L
Linus Torvalds 已提交
967 968

    print "  <funcsynopsis>\n";
R
Randy Dunlap 已提交
969 970
    print "   <funcdef>" . $args{'functiontype'} . " ";
    print "<function>" . $args{'function'} . " ";
L
Linus Torvalds 已提交
971 972 973 974 975 976 977 978 979 980 981
    print "</function></funcdef>\n";

    $count = 0;
    if ($#{$args{'parameterlist'}} >= 0) {
	foreach $parameter (@{$args{'parameterlist'}}) {
	    $type = $args{'parametertypes'}{$parameter};
	    if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
		# pointer-to-function
		print "   <paramdef>$1 <parameter>$parameter</parameter>)\n";
		print "     <funcparams>$2</funcparams></paramdef>\n";
	    } else {
R
Randy Dunlap 已提交
982
		print "   <paramdef>" . $type;
L
Linus Torvalds 已提交
983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041
		print " <parameter>$parameter</parameter></paramdef>\n";
	    }
	}
    } else {
	print "  <void>\n";
    }
    print "  </funcsynopsis>\n";
    if ($#{$args{'parameterlist'}} >= 0) {
	print " <informaltable pgwide=\"1\" frame=\"none\" role=\"params\">\n";
	print "<tgroup cols=\"2\">\n";
	print "<colspec colwidth=\"2*\">\n";
	print "<colspec colwidth=\"8*\">\n";
	print "<tbody>\n";
	foreach $parameter (@{$args{'parameterlist'}}) {
	    my $parameter_name = $parameter;
	    $parameter_name =~ s/\[.*//;

	    print "  <row><entry align=\"right\"><parameter>$parameter</parameter></entry>\n";
	    print "   <entry>\n";
	    $lineprefix="     ";
	    output_highlight($args{'parameterdescs'}{$parameter_name});
	    print "    </entry></row>\n";
	}
	print " </tbody></tgroup></informaltable>\n";
    } else {
	print " <para>\n  None\n </para>\n";
    }

    # print out each section
    $lineprefix="   ";
    foreach $section (@{$args{'sectionlist'}}) {
	print "<simplesect>\n <title>$section</title>\n";
	if ($section =~ m/EXAMPLE/i) {
	    print "<example><programlisting>\n";
	} else {
	}
	print "<para>\n";
	output_highlight($args{'sections'}{$section});
	print "</para>\n";
	if ($section =~ m/EXAMPLE/i) {
	    print "</programlisting></example>\n";
	} else {
	}
	print " </simplesect>\n";
    }

    print "</sect2>\n\n";
}

##
# output function in man
sub output_function_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";

    print ".SH NAME\n";
R
Randy Dunlap 已提交
1042
    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1043 1044

    print ".SH SYNOPSIS\n";
1045
    if ($args{'functiontype'} ne "") {
R
Randy Dunlap 已提交
1046
	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1047
    } else {
R
Randy Dunlap 已提交
1048
	print ".B \"" . $args{'function'} . "\n";
1049
    }
L
Linus Torvalds 已提交
1050 1051 1052 1053 1054 1055 1056 1057 1058 1059
    $count = 0;
    my $parenth = "(";
    my $post = ",";
    foreach my $parameter (@{$args{'parameterlist'}}) {
	if ($count == $#{$args{'parameterlist'}}) {
	    $post = ");";
	}
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
R
Randy Dunlap 已提交
1060
	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
L
Linus Torvalds 已提交
1061 1062
	} else {
	    $type =~ s/([^\*])$/$1 /;
R
Randy Dunlap 已提交
1063
	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
L
Linus Torvalds 已提交
1064 1065 1066 1067 1068 1069 1070 1071 1072 1073
	}
	$count++;
	$parenth = "";
    }

    print ".SH ARGUMENTS\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

R
Randy Dunlap 已提交
1074
	print ".IP \"" . $parameter . "\" 12\n";
L
Linus Torvalds 已提交
1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092
	output_highlight($args{'parameterdescs'}{$parameter_name});
    }
    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"", uc $section, "\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output enum in man
sub output_enum_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";

    print ".SH NAME\n";
R
Randy Dunlap 已提交
1093
    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1094 1095

    print ".SH SYNOPSIS\n";
R
Randy Dunlap 已提交
1096
    print "enum " . $args{'enum'} . " {\n";
L
Linus Torvalds 已提交
1097 1098
    $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
1099
	print ".br\n.BI \"    $parameter\"\n";
L
Linus Torvalds 已提交
1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114
	if ($count == $#{$args{'parameterlist'}}) {
	    print "\n};\n";
	    last;
	}
	else {
	    print ", \n.br\n";
	}
	$count++;
    }

    print ".SH Constants\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

R
Randy Dunlap 已提交
1115
	print ".IP \"" . $parameter . "\" 12\n";
L
Linus Torvalds 已提交
1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129
	output_highlight($args{'parameterdescs'}{$parameter_name});
    }
    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output struct in man
sub output_struct_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

R
Randy Dunlap 已提交
1130
    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
L
Linus Torvalds 已提交
1131 1132

    print ".SH NAME\n";
R
Randy Dunlap 已提交
1133
    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1134 1135

    print ".SH SYNOPSIS\n";
R
Randy Dunlap 已提交
1136
    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
L
Linus Torvalds 已提交
1137 1138 1139 1140 1141 1142 1143 1144 1145

    foreach my $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
	    print ".BI \"$parameter\"\n.br\n";
	    next;
	}
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

1146
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
1147 1148 1149
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
R
Randy Dunlap 已提交
1150
	    print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
L
Linus Torvalds 已提交
1151
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1152
	    # bitfield
R
Randy Dunlap 已提交
1153
	    print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
L
Linus Torvalds 已提交
1154 1155
	} else {
	    $type =~ s/([^\*])$/$1 /;
R
Randy Dunlap 已提交
1156
	    print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
L
Linus Torvalds 已提交
1157 1158 1159 1160 1161
	}
	print "\n.br\n";
    }
    print "};\n.br\n";

1162
    print ".SH Members\n";
L
Linus Torvalds 已提交
1163 1164 1165 1166 1167 1168
    foreach $parameter (@{$args{'parameterlist'}}) {
	($parameter =~ /^#/) && next;

	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

1169
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
R
Randy Dunlap 已提交
1170
	print ".IP \"" . $parameter . "\" 12\n";
L
Linus Torvalds 已提交
1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187
	output_highlight($args{'parameterdescs'}{$parameter_name});
    }
    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output typedef in man
sub output_typedef_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

    print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

    print ".SH NAME\n";
R
Randy Dunlap 已提交
1188
    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1189 1190 1191 1192 1193 1194 1195

    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

1196
sub output_blockhead_man(%) {
L
Linus Torvalds 已提交
1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;

    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

    foreach $section (@{$args{'sectionlist'}}) {
	print ".SH \"$section\"\n";
	output_highlight($args{'sections'}{$section});
    }
}

##
# output in text
sub output_function_text(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
1214
    my $start;
L
Linus Torvalds 已提交
1215

1216
    print "Name:\n\n";
R
Randy Dunlap 已提交
1217
    print $args{'function'} . " - " . $args{'purpose'} . "\n";
1218 1219

    print "\nSynopsis:\n\n";
1220
    if ($args{'functiontype'} ne "") {
R
Randy Dunlap 已提交
1221
	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
1222
    } else {
R
Randy Dunlap 已提交
1223
	$start = $args{'function'} . " (";
1224
    }
L
Linus Torvalds 已提交
1225
    print $start;
1226

L
Linus Torvalds 已提交
1227 1228 1229 1230 1231
    my $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
R
Randy Dunlap 已提交
1232
	    print $1 . $parameter . ") (" . $2;
L
Linus Torvalds 已提交
1233
	} else {
R
Randy Dunlap 已提交
1234
	    print $type . " " . $parameter;
L
Linus Torvalds 已提交
1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249
	}
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",\n";
	    print " " x length($start);
	} else {
	    print ");\n\n";
	}
    }

    print "Arguments:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

R
Randy Dunlap 已提交
1250
	print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
L
Linus Torvalds 已提交
1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263
    }
    output_section_text(@_);
}

#output sections in text
sub output_section_text(%) {
    my %args = %{$_[0]};
    my $section;

    print "\n";
    foreach $section (@{$args{'sectionlist'}}) {
	print "$section:\n\n";
	output_highlight($args{'sections'}{$section});
1264
    }
L
Linus Torvalds 已提交
1265 1266 1267 1268 1269 1270 1271 1272 1273 1274
    print "\n\n";
}

# output enum in text
sub output_enum_text(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
    print "Enum:\n\n";

R
Randy Dunlap 已提交
1275 1276
    print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
    print "enum " . $args{'enum'} . " {\n";
L
Linus Torvalds 已提交
1277 1278
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
1279
	print "\t$parameter";
L
Linus Torvalds 已提交
1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",";
	}
	print "\n";
    }
    print "};\n\n";

    print "Constants:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print "$parameter\n\t";
R
Randy Dunlap 已提交
1291
	print $args{'parameterdescs'}{$parameter} . "\n";
L
Linus Torvalds 已提交
1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303
    }

    output_section_text(@_);
}

# output typedef in text
sub output_typedef_text(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
    print "Typedef:\n\n";

R
Randy Dunlap 已提交
1304
    print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1305 1306 1307 1308 1309 1310 1311 1312
    output_section_text(@_);
}

# output struct as text
sub output_struct_text(%) {
    my %args = %{$_[0]};
    my ($parameter);

R
Randy Dunlap 已提交
1313 1314
    print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
    print $args{'type'} . " " . $args{'struct'} . " {\n";
L
Linus Torvalds 已提交
1315 1316 1317 1318 1319 1320 1321 1322 1323
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
	    print "$parameter\n";
	    next;
	}

	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

1324
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
1325 1326 1327 1328 1329
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "\t$1 $parameter) ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
R
Randy Dunlap 已提交
1330
	    # bitfield
L
Linus Torvalds 已提交
1331 1332
	    print "\t$1 $parameter$2;\n";
	} else {
R
Randy Dunlap 已提交
1333
	    print "\t" . $type . " " . $parameter . ";\n";
L
Linus Torvalds 已提交
1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344
	}
    }
    print "};\n\n";

    print "Members:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	($parameter =~ /^#/) && next;

	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

1345
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
1346
	print "$parameter\n\t";
R
Randy Dunlap 已提交
1347
	print $args{'parameterdescs'}{$parameter_name} . "\n";
L
Linus Torvalds 已提交
1348 1349 1350 1351 1352
    }
    print "\n";
    output_section_text(@_);
}

1353
sub output_blockhead_text(%) {
L
Linus Torvalds 已提交
1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364
    my %args = %{$_[0]};
    my ($parameter, $section);

    foreach $section (@{$args{'sectionlist'}}) {
	print " $section:\n";
	print "    -> ";
	output_highlight($args{'sections'}{$section});
    }
}

##
1365 1366 1367
# generic output function for all types (function, struct/union, typedef, enum);
# calls the generated, variable output_ function name based on
# functype and output_mode
L
Linus Torvalds 已提交
1368 1369 1370 1371 1372
sub output_declaration {
    no strict 'refs';
    my $name = shift;
    my $functype = shift;
    my $func = "output_${functype}_$output_mode";
1373 1374
    if (($function_only==0) ||
	( $function_only == 1 && defined($function_table{$name})) ||
L
Linus Torvalds 已提交
1375 1376
	( $function_only == 2 && !defined($function_table{$name})))
    {
1377
	&$func(@_);
L
Linus Torvalds 已提交
1378 1379 1380 1381 1382
	$section_counter++;
    }
}

##
1383
# generic output function - calls the right one based on current output mode.
1384
sub output_blockhead {
L
Linus Torvalds 已提交
1385
    no strict 'refs';
R
Randy Dunlap 已提交
1386
    my $func = "output_blockhead_" . $output_mode;
L
Linus Torvalds 已提交
1387 1388 1389 1390 1391
    &$func(@_);
    $section_counter++;
}

##
1392
# takes a declaration (struct, union, enum, typedef) and
L
Linus Torvalds 已提交
1393 1394 1395 1396
# invokes the right handler. NOT called for functions.
sub dump_declaration($$) {
    no strict 'refs';
    my ($prototype, $file) = @_;
R
Randy Dunlap 已提交
1397
    my $func = "dump_" . $decl_type;
L
Linus Torvalds 已提交
1398 1399 1400 1401 1402 1403 1404 1405 1406 1407
    &$func(@_);
}

sub dump_union($$) {
    dump_struct(@_);
}

sub dump_struct($$) {
    my $x = shift;
    my $file = shift;
1408
    my $nested;
L
Linus Torvalds 已提交
1409

1410 1411
    if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
	#my $decl_type = $1;
1412 1413
	$declaration_name = $2;
	my $members = $3;
L
Linus Torvalds 已提交
1414 1415

	# ignore embedded structs or unions
1416 1417
	$members =~ s/({.*})//g;
	$nested = $1;
L
Linus Torvalds 已提交
1418

1419
	# ignore members marked private:
1420 1421
	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
	$members =~ s/\/\*\s*private:.*//gos;
1422 1423
	# strip comments:
	$members =~ s/\/\*.*?\*\///gos;
1424
	$nested =~ s/\/\*.*?\*\///gos;
1425 1426
	# strip kmemcheck_bitfield_{begin,end}.*;
	$members =~ s/kmemcheck_bitfield_.*?;//gos;
1427

L
Linus Torvalds 已提交
1428
	create_parameterlist($members, ';', $file);
1429
	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
L
Linus Torvalds 已提交
1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444

	output_declaration($declaration_name,
			   'struct',
			   {'struct' => $declaration_name,
			    'module' => $modulename,
			    'parameterlist' => \@parameterlist,
			    'parameterdescs' => \%parameterdescs,
			    'parametertypes' => \%parametertypes,
			    'sectionlist' => \@sectionlist,
			    'sections' => \%sections,
			    'purpose' => $declaration_purpose,
			    'type' => $decl_type
			   });
    }
    else {
1445
	print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
L
Linus Torvalds 已提交
1446 1447 1448 1449 1450 1451 1452 1453
	++$errors;
    }
}

sub dump_enum($$) {
    my $x = shift;
    my $file = shift;

1454
    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
L
Linus Torvalds 已提交
1455
    if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1456 1457
	$declaration_name = $1;
	my $members = $2;
L
Linus Torvalds 已提交
1458 1459 1460 1461 1462

	foreach my $arg (split ',', $members) {
	    $arg =~ s/^\s*(\w+).*/$1/;
	    push @parameterlist, $arg;
	    if (!$parameterdescs{$arg}) {
1463 1464
		$parameterdescs{$arg} = $undescribed;
		print STDERR "Warning(${file}:$.): Enum value '$arg' ".
L
Linus Torvalds 已提交
1465 1466 1467 1468
		    "not described in enum '$declaration_name'\n";
	    }

	}
1469

L
Linus Torvalds 已提交
1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481
	output_declaration($declaration_name,
			   'enum',
			   {'enum' => $declaration_name,
			    'module' => $modulename,
			    'parameterlist' => \@parameterlist,
			    'parameterdescs' => \%parameterdescs,
			    'sectionlist' => \@sectionlist,
			    'sections' => \%sections,
			    'purpose' => $declaration_purpose
			   });
    }
    else {
1482
	print STDERR "Error(${file}:$.): Cannot parse enum!\n";
L
Linus Torvalds 已提交
1483 1484 1485 1486 1487 1488 1489 1490
	++$errors;
    }
}

sub dump_typedef($$) {
    my $x = shift;
    my $file = shift;

1491
    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
L
Linus Torvalds 已提交
1492
    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1493
	$x =~ s/\(*.\)\s*;$/;/;
L
Linus Torvalds 已提交
1494 1495 1496 1497
	$x =~ s/\[*.\]\s*;$/;/;
    }

    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1498
	$declaration_name = $1;
L
Linus Torvalds 已提交
1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509

	output_declaration($declaration_name,
			   'typedef',
			   {'typedef' => $declaration_name,
			    'module' => $modulename,
			    'sectionlist' => \@sectionlist,
			    'sections' => \%sections,
			    'purpose' => $declaration_purpose
			   });
    }
    else {
1510
	print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
L
Linus Torvalds 已提交
1511 1512 1513 1514
	++$errors;
    }
}

1515 1516 1517 1518 1519 1520 1521 1522
sub save_struct_actual($) {
    my $actual = shift;

    # strip all spaces from the actual param so that it looks like one string item
    $actual =~ s/\s*//g;
    $struct_actual = $struct_actual . $actual . " ";
}

L
Linus Torvalds 已提交
1523 1524 1525 1526 1527 1528 1529
sub create_parameterlist($$$) {
    my $args = shift;
    my $splitter = shift;
    my $file = shift;
    my $type;
    my $param;

1530
    # temporarily replace commas inside function pointer definition
L
Linus Torvalds 已提交
1531
    while ($args =~ /(\([^\),]+),/) {
1532
	$args =~ s/(\([^\),]+),/$1#/g;
L
Linus Torvalds 已提交
1533
    }
1534

L
Linus Torvalds 已提交
1535 1536 1537
    foreach my $arg (split($splitter, $args)) {
	# strip comments
	$arg =~ s/\/\*.*\*\///;
1538 1539
	# strip leading/trailing spaces
	$arg =~ s/^\s*//;
L
Linus Torvalds 已提交
1540 1541 1542 1543 1544 1545 1546 1547
	$arg =~ s/\s*$//;
	$arg =~ s/\s+/ /;

	if ($arg =~ /^#/) {
	    # Treat preprocessor directive as a typeless variable just to fill
	    # corresponding data structures "correctly". Catch it later in
	    # output_* subs.
	    push_parameter($arg, "", $file);
1548
	} elsif ($arg =~ m/\(.+\)\s*\(/) {
L
Linus Torvalds 已提交
1549 1550
	    # pointer-to-function
	    $arg =~ tr/#/,/;
1551
	    $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
L
Linus Torvalds 已提交
1552 1553
	    $param = $1;
	    $type = $arg;
1554
	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1555
	    save_struct_actual($param);
L
Linus Torvalds 已提交
1556
	    push_parameter($param, $type, $file);
1557
	} elsif ($arg) {
L
Linus Torvalds 已提交
1558 1559 1560 1561 1562 1563 1564
	    $arg =~ s/\s*:\s*/:/g;
	    $arg =~ s/\s*\[/\[/g;

	    my @args = split('\s*,\s*', $arg);
	    if ($args[0] =~ m/\*/) {
		$args[0] =~ s/(\*+)\s*/ $1/;
	    }
1565 1566 1567 1568 1569 1570 1571 1572 1573 1574

	    my @first_arg;
	    if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) {
		    shift @args;
		    push(@first_arg, split('\s+', $1));
		    push(@first_arg, $2);
	    } else {
		    @first_arg = split('\s+', shift @args);
	    }

L
Linus Torvalds 已提交
1575 1576 1577 1578 1579
	    unshift(@args, pop @first_arg);
	    $type = join " ", @first_arg;

	    foreach $param (@args) {
		if ($param =~ m/^(\*+)\s*(.*)/) {
1580
		    save_struct_actual($2);
L
Linus Torvalds 已提交
1581 1582 1583
		    push_parameter($2, "$type $1", $file);
		}
		elsif ($param =~ m/(.*?):(\d+)/) {
1584
		    if ($type ne "") { # skip unnamed bit-fields
1585
			save_struct_actual($1);
1586 1587
			push_parameter($1, "$type:$2", $file)
		    }
L
Linus Torvalds 已提交
1588 1589
		}
		else {
1590
		    save_struct_actual($param);
L
Linus Torvalds 已提交
1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602
		    push_parameter($param, $type, $file);
		}
	    }
	}
    }
}

sub push_parameter($$$) {
	my $param = shift;
	my $type = shift;
	my $file = shift;

1603 1604 1605 1606 1607 1608
	if (($anon_struct_union == 1) && ($type eq "") &&
	    ($param eq "}")) {
		return;		# ignore the ending }; from anon. struct/union
	}

	$anon_struct_union = 0;
L
Linus Torvalds 已提交
1609 1610 1611
	my $param_name = $param;
	$param_name =~ s/\[.*//;

1612
	if ($type eq "" && $param =~ /\.\.\.$/)
L
Linus Torvalds 已提交
1613
	{
R
Randy Dunlap 已提交
1614 1615 1616
	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
		$parameterdescs{$param} = "variable arguments";
	    }
L
Linus Torvalds 已提交
1617 1618 1619 1620 1621 1622
	}
	elsif ($type eq "" && ($param eq "" or $param eq "void"))
	{
	    $param="void";
	    $parameterdescs{void} = "no arguments";
	}
1623 1624 1625 1626
	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
	# handle unnamed (anonymous) union or struct:
	{
		$type = $param;
1627
		$param = "{unnamed_" . $param . "}";
1628
		$parameterdescs{$param} = "anonymous\n";
1629
		$anon_struct_union = 1;
1630 1631
	}

1632
	# warn if parameter has no description
1633 1634 1635
	# (but ignore ones starting with # as these are not parameters
	# but inline preprocessor statements);
	# also ignore unnamed structs/unions;
1636
	if (!$anon_struct_union) {
1637 1638
	if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {

L
Linus Torvalds 已提交
1639 1640 1641
	    $parameterdescs{$param_name} = $undescribed;

	    if (($type eq 'function') || ($type eq 'enum')) {
1642
		print STDERR "Warning(${file}:$.): Function parameter ".
L
Linus Torvalds 已提交
1643 1644 1645
		    "or member '$param' not " .
		    "described in '$declaration_name'\n";
	    }
R
Randy Dunlap 已提交
1646
	    print STDERR "Warning(${file}:$.):" .
1647
			 " No description found for parameter '$param'\n";
L
Linus Torvalds 已提交
1648
	    ++$warnings;
1649 1650
	}
	}
L
Linus Torvalds 已提交
1651

1652 1653 1654 1655 1656 1657 1658 1659 1660
	# strip spaces from $param so that it is one continous string
	# on @parameterlist;
	# this fixes a problem where check_sections() cannot find
	# a parameter like "addr[6 + 2]" because it actually appears
	# as "addr[6", "+", "2]" on the parameter list;
	# but it's better to maintain the param string unchanged for output,
	# so just weaken the string compare in check_sections() to ignore
	# "[blah" in a parameter string;
	###$param =~ s/\s*//g;
L
Linus Torvalds 已提交
1661 1662 1663 1664
	push @parameterlist, $param;
	$parametertypes{$param} = $type;
}

1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678
sub check_sections($$$$$$) {
	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;
	my @sects = split ' ', $sectcheck;
	my @prms = split ' ', $prmscheck;
	my $err;
	my ($px, $sx);
	my $prm_clean;		# strip trailing "[array size]" and/or beginning "*"

	foreach $sx (0 .. $#sects) {
		$err = 1;
		foreach $px (0 .. $#prms) {
			$prm_clean = $prms[$px];
			$prm_clean =~ s/\[.*\]//;
			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//;
1679 1680 1681 1682 1683 1684 1685 1686
			# ignore array size in a parameter string;
			# however, the original param string may contain
			# spaces, e.g.:  addr[6 + 2]
			# and this appears in @prms as "addr[6" since the
			# parameter list is split at spaces;
			# hence just ignore "[..." for the sections check;
			$prm_clean =~ s/\[.*//;

1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712
			##$prm_clean =~ s/^\**//;
			if ($prm_clean eq $sects[$sx]) {
				$err = 0;
				last;
			}
		}
		if ($err) {
			if ($decl_type eq "function") {
				print STDERR "Warning(${file}:$.): " .
					"Excess function parameter " .
					"'$sects[$sx]' " .
					"description in '$decl_name'\n";
				++$warnings;
			} else {
				if ($nested !~ m/\Q$sects[$sx]\E/) {
				    print STDERR "Warning(${file}:$.): " .
					"Excess struct/union/enum/typedef member " .
					"'$sects[$sx]' " .
					"description in '$decl_name'\n";
				    ++$warnings;
				}
			}
		}
	}
}

L
Linus Torvalds 已提交
1713 1714 1715 1716 1717 1718 1719 1720 1721 1722
##
# takes a function prototype and the name of the current file being
# processed and spits out all the details stored in the global
# arrays/hashes.
sub dump_function($$) {
    my $prototype = shift;
    my $file = shift;

    $prototype =~ s/^static +//;
    $prototype =~ s/^extern +//;
1723
    $prototype =~ s/^asmlinkage +//;
L
Linus Torvalds 已提交
1724 1725
    $prototype =~ s/^inline +//;
    $prototype =~ s/^__inline__ +//;
1726 1727 1728
    $prototype =~ s/^__inline +//;
    $prototype =~ s/^__always_inline +//;
    $prototype =~ s/^noinline +//;
1729
    $prototype =~ s/__devinit +//;
R
Randy Dunlap 已提交
1730
    $prototype =~ s/__init +//;
1731
    $prototype =~ s/^#\s*define\s+//; #ak added
1732
    $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
L
Linus Torvalds 已提交
1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747

    # Yes, this truly is vile.  We are looking for:
    # 1. Return type (may be nothing if we're looking at a macro)
    # 2. Function name
    # 3. Function parameters.
    #
    # All the while we have to watch out for function pointer parameters
    # (which IIRC is what the two sections are for), C types (these
    # regexps don't even start to express all the possibilities), and
    # so on.
    #
    # If you mess with these regexps, it's a good idea to check that
    # the following functions' documentation still comes out right:
    # - parport_register_device (function pointer parameters)
    # - atomic_set (macro)
1748
    # - pci_match_device, __copy_to_user (long return type)
L
Linus Torvalds 已提交
1749 1750 1751 1752 1753

    if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
1754
	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
L
Linus Torvalds 已提交
1755 1756 1757 1758 1759 1760 1761 1762
	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
	$prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1763 1764
	$prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
1765 1766
	$prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
	$prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/)  {
L
Linus Torvalds 已提交
1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777
	$return_type = $1;
	$declaration_name = $2;
	my $args = $3;

	create_parameterlist($args, ',', $file);
    } else {
	print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
	++$errors;
	return;
    }

1778 1779 1780
	my $prms = join " ", @parameterlist;
	check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");

1781
    output_declaration($declaration_name,
L
Linus Torvalds 已提交
1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830
		       'function',
		       {'function' => $declaration_name,
			'module' => $modulename,
			'functiontype' => $return_type,
			'parameterlist' => \@parameterlist,
			'parameterdescs' => \%parameterdescs,
			'parametertypes' => \%parametertypes,
			'sectionlist' => \@sectionlist,
			'sections' => \%sections,
			'purpose' => $declaration_purpose
		       });
}

sub process_file($);

# Read the file that maps relative names to absolute names for
# separate source and object directories and for shadow trees.
if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
	my ($relname, $absname);
	while(<SOURCE_MAP>) {
		chop();
		($relname, $absname) = (split())[0..1];
		$relname =~ s:^/+::;
		$source_map{$relname} = $absname;
	}
	close(SOURCE_MAP);
}

foreach (@ARGV) {
    chomp;
    process_file($_);
}
if ($verbose && $errors) {
  print STDERR "$errors errors\n";
}
if ($verbose && $warnings) {
  print STDERR "$warnings warnings\n";
}

exit($errors);

sub reset_state {
    $function = "";
    %constants = ();
    %parameterdescs = ();
    %parametertypes = ();
    @parameterlist = ();
    %sections = ();
    @sectionlist = ();
1831 1832
    $sectcheck = "";
    $struct_actual = "";
L
Linus Torvalds 已提交
1833
    $prototype = "";
1834

L
Linus Torvalds 已提交
1835 1836 1837
    $state = 0;
}

1838 1839 1840 1841 1842
sub tracepoint_munge($) {
	my $file = shift;
	my $tracepointname = 0;
	my $tracepointargs = 0;

1843
	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
1844 1845
		$tracepointname = $1;
	}
1846 1847 1848 1849 1850 1851 1852 1853
	if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) {
		$tracepointname = $1;
	}
	if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) {
		$tracepointname = $2;
	}
	$tracepointname =~ s/^\s+//; #strip leading whitespace
	if ($prototype =~ m/TP_PROTO\((.*?)\)/) {
1854 1855 1856 1857 1858 1859 1860 1861 1862 1863
		$tracepointargs = $1;
	}
	if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
		print STDERR "Warning(${file}:$.): Unrecognized tracepoint format: \n".
			     "$prototype\n";
	} else {
		$prototype = "static inline void trace_$tracepointname($tracepointargs)";
	}
}

1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897
sub syscall_munge() {
	my $void = 0;

	$prototype =~ s@[\r\n\t]+@ @gos; # strip newlines/CR's/tabs
##	if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) {
	if ($prototype =~ m/SYSCALL_DEFINE0/) {
		$void = 1;
##		$prototype = "long sys_$1(void)";
	}

	$prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name
	if ($prototype =~ m/long (sys_.*?),/) {
		$prototype =~ s/,/\(/;
	} elsif ($void) {
		$prototype =~ s/\)/\(void\)/;
	}

	# now delete all of the odd-number commas in $prototype
	# so that arg types & arg names don't have a comma between them
	my $count = 0;
	my $len = length($prototype);
	if ($void) {
		$len = 0;	# skip the for-loop
	}
	for (my $ix = 0; $ix < $len; $ix++) {
		if (substr($prototype, $ix, 1) eq ',') {
			$count++;
			if ($count % 2 == 1) {
				substr($prototype, $ix, 1) = ' ';
			}
		}
	}
}

1898
sub process_state3_function($$) {
L
Linus Torvalds 已提交
1899 1900 1901
    my $x = shift;
    my $file = shift;

R
Randy Dunlap 已提交
1902 1903
    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1904
    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
L
Linus Torvalds 已提交
1905 1906 1907
	# do nothing
    }
    elsif ($x =~ /([^\{]*)/) {
1908
	$prototype .= $1;
L
Linus Torvalds 已提交
1909
    }
1910

1911
    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1912
	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
L
Linus Torvalds 已提交
1913 1914
	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
	$prototype =~ s@^\s+@@gos; # strip leading spaces
1915 1916 1917
	if ($prototype =~ /SYSCALL_DEFINE/) {
		syscall_munge();
	}
1918 1919 1920
	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
	    $prototype =~ /DEFINE_SINGLE_EVENT/)
	{
1921 1922
		tracepoint_munge($file);
	}
1923
	dump_function($prototype, $file);
L
Linus Torvalds 已提交
1924 1925 1926 1927
	reset_state();
    }
}

1928
sub process_state3_type($$) {
L
Linus Torvalds 已提交
1929 1930 1931 1932 1933 1934
    my $x = shift;
    my $file = shift;

    $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
    $x =~ s@^\s+@@gos; # strip leading spaces
    $x =~ s@\s+$@@gos; # strip trailing spaces
R
Randy Dunlap 已提交
1935 1936
    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

L
Linus Torvalds 已提交
1937 1938 1939 1940 1941 1942
    if ($x =~ /^#/) {
	# To distinguish preprocessor directive from regular declaration later.
	$x .= ";";
    }

    while (1) {
1943
	if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
L
Linus Torvalds 已提交
1944 1945 1946 1947
	    $prototype .= $1 . $2;
	    ($2 eq '{') && $brcount++;
	    ($2 eq '}') && $brcount--;
	    if (($2 eq ';') && ($brcount == 0)) {
R
Randy Dunlap 已提交
1948
		dump_declaration($prototype, $file);
L
Linus Torvalds 已提交
1949
		reset_state();
1950
		last;
L
Linus Torvalds 已提交
1951 1952
	    }
	    $x = $3;
1953
	} else {
L
Linus Torvalds 已提交
1954 1955 1956 1957 1958 1959
	    $prototype .= $x;
	    last;
	}
    }
}

R
Randy Dunlap 已提交
1960 1961 1962 1963 1964 1965 1966
# xml_escape: replace <, >, and & in the text stream;
#
# however, formatting controls that are generated internally/locally in the
# kernel-doc script are not escaped here; instead, they begin life like
# $blankline_html (4 of '\' followed by a mnemonic + ':'), then these strings
# are converted to their mnemonic-expected output, without the 4 * '\' & ':',
# just before actual output; (this is done by local_unescape())
L
Linus Torvalds 已提交
1967 1968
sub xml_escape($) {
	my $text = shift;
1969 1970 1971
	if (($output_mode eq "text") || ($output_mode eq "man")) {
		return $text;
	}
L
Linus Torvalds 已提交
1972 1973 1974 1975 1976 1977
	$text =~ s/\&/\\\\\\amp;/g;
	$text =~ s/\</\\\\\\lt;/g;
	$text =~ s/\>/\\\\\\gt;/g;
	return $text;
}

R
Randy Dunlap 已提交
1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989
# convert local escape strings to html
# local escape strings look like:  '\\\\menmonic:' (that's 4 backslashes)
sub local_unescape($) {
	my $text = shift;
	if (($output_mode eq "text") || ($output_mode eq "man")) {
		return $text;
	}
	$text =~ s/\\\\\\\\lt:/</g;
	$text =~ s/\\\\\\\\gt:/>/g;
	return $text;
}

L
Linus Torvalds 已提交
1990
sub process_file($) {
1991
    my $file;
L
Linus Torvalds 已提交
1992 1993
    my $identifier;
    my $func;
1994
    my $descr;
1995
    my $in_purpose = 0;
L
Linus Torvalds 已提交
1996 1997
    my $initial_section_counter = $section_counter;

1998 1999 2000 2001 2002 2003
    if (defined($ENV{'SRCTREE'})) {
	$file = "$ENV{'SRCTREE'}" . "/" . "@_";
    }
    else {
	$file = "@_";
    }
L
Linus Torvalds 已提交
2004 2005 2006 2007 2008 2009 2010 2011 2012 2013
    if (defined($source_map{$file})) {
	$file = $source_map{$file};
    }

    if (!open(IN,"<$file")) {
	print STDERR "Error: Cannot open file $file\n";
	++$errors;
	return;
    }

2014 2015
    $. = 1;

L
Linus Torvalds 已提交
2016 2017 2018 2019 2020
    $section_counter = 0;
    while (<IN>) {
	if ($state == 0) {
	    if (/$doc_start/o) {
		$state = 1;		# next line is always the function name
2021
		$in_doc_sect = 0;
L
Linus Torvalds 已提交
2022 2023 2024 2025 2026 2027 2028 2029 2030 2031
	    }
	} elsif ($state == 1) {	# this line is the function name (always)
	    if (/$doc_block/o) {
		$state = 4;
		$contents = "";
		if ( $1 eq "" ) {
			$section = $section_intro;
		} else {
			$section = $1;
		}
2032
	    }
L
Linus Torvalds 已提交
2033 2034 2035 2036 2037 2038 2039 2040
	    elsif (/$doc_decl/o) {
		$identifier = $1;
		if (/\s*([\w\s]+?)\s*-/) {
		    $identifier = $1;
		}

		$state = 2;
		if (/-(.*)/) {
R
Randy Dunlap 已提交
2041
		    # strip leading/trailing/multiple spaces
2042 2043 2044 2045 2046
		    $descr= $1;
		    $descr =~ s/^\s*//;
		    $descr =~ s/\s*$//;
		    $descr =~ s/\s+/ /;
		    $declaration_purpose = xml_escape($descr);
2047
		    $in_purpose = 1;
L
Linus Torvalds 已提交
2048 2049 2050
		} else {
		    $declaration_purpose = "";
		}
2051 2052 2053 2054 2055 2056 2057

		if (($declaration_purpose eq "") && $verbose) {
			print STDERR "Warning(${file}:$.): missing initial short description on line:\n";
			print STDERR $_;
			++$warnings;
		}

L
Linus Torvalds 已提交
2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083
		if ($identifier =~ m/^struct/) {
		    $decl_type = 'struct';
		} elsif ($identifier =~ m/^union/) {
		    $decl_type = 'union';
		} elsif ($identifier =~ m/^enum/) {
		    $decl_type = 'enum';
		} elsif ($identifier =~ m/^typedef/) {
		    $decl_type = 'typedef';
		} else {
		    $decl_type = 'function';
		}

		if ($verbose) {
		    print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
		}
	    } else {
		print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
		" - I thought it was a doc line\n";
		++$warnings;
		$state = 0;
	    }
	} elsif ($state == 2) {	# look for head: lines, and include content
	    if (/$doc_sect/o) {
		$newsection = $1;
		$newcontents = $2;

2084
		if (($contents ne "") && ($contents ne "\n")) {
2085 2086 2087 2088
		    if (!$in_doc_sect && $verbose) {
			print STDERR "Warning(${file}:$.): contents before sections\n";
			++$warnings;
		    }
2089
		    dump_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2090 2091 2092
		    $section = $section_default;
		}

2093
		$in_doc_sect = 1;
2094
		$in_purpose = 0;
L
Linus Torvalds 已提交
2095 2096
		$contents = $newcontents;
		if ($contents ne "") {
2097 2098 2099
		    while ((substr($contents, 0, 1) eq " ") ||
			substr($contents, 0, 1) eq "\t") {
			    $contents = substr($contents, 1);
2100
		    }
L
Linus Torvalds 已提交
2101 2102 2103 2104 2105 2106
		    $contents .= "\n";
		}
		$section = $newsection;
	    } elsif (/$doc_end/) {

		if ($contents ne "") {
2107
		    dump_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2108 2109 2110
		    $section = $section_default;
		    $contents = "";
		}
2111 2112 2113 2114 2115
		# look for doc_com + <text> + doc_end:
		if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
		    print STDERR "Warning(${file}:$.): suspicious ending line: $_";
		    ++$warnings;
		}
L
Linus Torvalds 已提交
2116 2117 2118 2119

		$prototype = "";
		$state = 3;
		$brcount = 0;
2120
#		print STDERR "end of doc comment, looking for prototype\n";
L
Linus Torvalds 已提交
2121 2122 2123
	    } elsif (/$doc_content/) {
		# miguel-style comment kludge, look for blank lines after
		# @parameter line to signify start of description
2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136
		if ($1 eq "") {
		    if ($section =~ m/^@/ || $section eq $section_context) {
			dump_section($file, $section, xml_escape($contents));
			$section = $section_default;
			$contents = "";
		    } else {
			$contents .= "\n";
		    }
		    $in_purpose = 0;
		} elsif ($in_purpose == 1) {
		    # Continued declaration purpose
		    chomp($declaration_purpose);
		    $declaration_purpose .= " " . xml_escape($1);
L
Linus Torvalds 已提交
2137
		} else {
R
Randy Dunlap 已提交
2138
		    $contents .= $1 . "\n";
L
Linus Torvalds 已提交
2139 2140 2141
		}
	    } else {
		# i dont know - bad line?  ignore.
2142
		print STDERR "Warning(${file}:$.): bad line: $_";
L
Linus Torvalds 已提交
2143 2144
		++$warnings;
	    }
2145
	} elsif ($state == 3) {	# scanning for function '{' (end of prototype)
L
Linus Torvalds 已提交
2146
	    if ($decl_type eq 'function') {
2147
		process_state3_function($_, $file);
L
Linus Torvalds 已提交
2148
	    } else {
2149
		process_state3_type($_, $file);
L
Linus Torvalds 已提交
2150 2151 2152
	    }
	} elsif ($state == 4) {
		# Documentation block
2153
		if (/$doc_block/) {
2154
			dump_doc_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168
			$contents = "";
			$function = "";
			%constants = ();
			%parameterdescs = ();
			%parametertypes = ();
			@parameterlist = ();
			%sections = ();
			@sectionlist = ();
			$prototype = "";
			if ( $1 eq "" ) {
				$section = $section_intro;
			} else {
				$section = $1;
			}
2169
		}
L
Linus Torvalds 已提交
2170 2171
		elsif (/$doc_end/)
		{
2172
			dump_doc_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192
			$contents = "";
			$function = "";
			%constants = ();
			%parameterdescs = ();
			%parametertypes = ();
			@parameterlist = ();
			%sections = ();
			@sectionlist = ();
			$prototype = "";
			$state = 0;
		}
		elsif (/$doc_content/)
		{
			if ( $1 eq "" )
			{
				$contents .= $blankline;
			}
			else
			{
				$contents .= $1 . "\n";
2193
			}
2194 2195
		}
	}
L
Linus Torvalds 已提交
2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228
    }
    if ($initial_section_counter == $section_counter) {
	print STDERR "Warning(${file}): no structured comments found\n";
	if ($output_mode eq "xml") {
	    # The template wants at least one RefEntry here; make one.
	    print "<refentry>\n";
	    print " <refnamediv>\n";
	    print "  <refname>\n";
	    print "   ${file}\n";
	    print "  </refname>\n";
	    print "  <refpurpose>\n";
	    print "   Document generation inconsistency\n";
	    print "  </refpurpose>\n";
	    print " </refnamediv>\n";
	    print " <refsect1>\n";
	    print "  <title>\n";
	    print "   Oops\n";
	    print "  </title>\n";
	    print "  <warning>\n";
	    print "   <para>\n";
	    print "    The template for this document tried to insert\n";
	    print "    the structured comment from the file\n";
	    print "    <filename>${file}</filename> at this point,\n";
	    print "    but none was found.\n";
	    print "    This dummy section is inserted to allow\n";
	    print "    generation to continue.\n";
	    print "   </para>\n";
	    print "  </warning>\n";
	    print " </refsect1>\n";
	    print "</refentry>\n";
	}
    }
}