kernel-doc 62.8 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                             ##
8
## Copyright (C) 2005-2012  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 | -list ] [ -no-doc-sections ]
L
Linus Torvalds 已提交
48 49 50 51 52
#           [ -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.
53
#  The -list format is for internal use by docproc.
L
Linus Torvalds 已提交
54
#
55 56 57
#  -no-doc-sections
#	Do not output DOC: sections
#
L
Linus Torvalds 已提交
58
#  -function funcname
59 60
#	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 已提交
61 62
#
#  -nofunction funcname
63 64 65
#	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 已提交
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
#
#  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
87
#  */
L
Linus Torvalds 已提交
88
#
89
# If the Description: header tag is omitted, then there must be a blank line
L
Linus Torvalds 已提交
90 91 92 93 94 95
# after the last parameter specification.
# e.g.
# /**
#  * my_function - does my stuff
#  * @my_arg: its mine damnit
#  *
96
#  * Does my stuff explained.
L
Linus Torvalds 已提交
97 98 99 100 101 102
#  */
#
#  or, could also use:
# /**
#  * my_function - does my stuff
#  * @my_arg: its mine damnit
103
#  * Description: Does my stuff explained.
L
Linus Torvalds 已提交
104 105 106
#  */
# etc.
#
107
# Besides functions you can also write documentation for structs, unions,
108 109 110
# 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 已提交
111 112 113 114 115 116
# Use the argument mechanism to document members or constants.
# e.g.
# /**
#  * struct my_struct - short description
#  * @a: first member
#  * @b: second member
117
#  *
L
Linus Torvalds 已提交
118 119 120 121 122
#  * Longer description
#  */
# struct my_struct {
#     int a;
#     int b;
123 124
# /* private: */
#     int c;
L
Linus Torvalds 已提交
125 126 127
# };
#
# All descriptions can be multiline, except the short function description.
128 129 130
#
# 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 已提交
131
# can be called form interrupts. Unlike other sections you can end it with an
132 133
# empty line.
# Example-sections should contain the string EXAMPLE so that they are marked
L
Linus Torvalds 已提交
134 135 136 137 138 139 140
# appropriately in DocBook.
#
# Example:
# /**
#  * user_function - function that can only be called in user context
#  * @a: some argument
#  * Context: !in_interrupt()
141
#  *
L
Linus Torvalds 已提交
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
#  * 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.

158 159
## init lots of data

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

# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
my $type_func = '(\w+)\(\)';
my $type_param = '\@(\w+)';
168
my $type_struct = '\&((struct\s*)*[_\w]+)';
169
my $type_struct_xml = '\\&amp;((struct\s*)*[_\w]+)';
L
Linus Torvalds 已提交
170 171 172 173 174 175 176 177
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>",
178 179
			$type_struct_xml, "<i>\$1</i>",
			$type_env, "<b><i>\$1</i></b>",
L
Linus Torvalds 已提交
180
			$type_param, "<tt><b>\$1</b></tt>" );
181 182 183
my $local_lt = "\\\\\\\\lt:";
my $local_gt = "\\\\\\\\gt:";
my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
L
Linus Torvalds 已提交
184 185 186 187 188

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

# 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 = "";

216 217 218 219 220 221
# list mode
my %highlights_list = ( $type_constant, "\$1",
			$type_func, "\$1",
			$type_struct, "\$1",
			$type_param, "\$1" );
my $blankline_list = "";
L
Linus Torvalds 已提交
222 223

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

228 229 230
my $kernelversion;
my $dohighlight = "";

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

244
# Essentially these are globals.
245 246
# 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 已提交
247
# could cause "use of undefined value" or other bugs.
248 249
my ($function, %function_table, %parametertypes, $declaration_purpose);
my ($type, $declaration_name, $return_type);
250
my ($newsection, $newcontents, $prototype, $brcount, %source_map);
L
Linus Torvalds 已提交
251

252 253 254 255
if (defined($ENV{'KBUILD_VERBOSE'})) {
	$verbose = "$ENV{'KBUILD_VERBOSE'}";
}

256
# Generated docbook code is inserted in a template at a point where
L
Linus Torvalds 已提交
257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
# 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;
273
my $in_doc_sect;
L
Linus Torvalds 已提交
274 275 276 277 278 279 280 281 282 283

#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*';
284
my $doc_com_body = '\s*\* ?';
285 286
my $doc_decl = $doc_com . '(\w+)';
my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
287
my $doc_content = $doc_com_body . '(.*)';
288
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
L
Linus Torvalds 已提交
289 290 291 292 293 294

my %constants;
my %parameterdescs;
my @parameterlist;
my %sections;
my @sectionlist;
295 296
my $sectcheck;
my $struct_actual;
L
Linus Torvalds 已提交
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

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;
326 327 328 329
    } elsif ($cmd eq "-list") {
	$output_mode = "list";
	%highlights = %highlights_list;
	$blankline = $blankline_list;
L
Linus Torvalds 已提交
330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347
    } 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();
348 349
    } elsif ($cmd eq '-no-doc-sections') {
	    $no_doc_sections = 1;
L
Linus Torvalds 已提交
350 351 352
    }
}

353 354 355 356 357 358 359 360 361 362 363 364
# continue execution near EOF;

sub usage {
    print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n";
    print "         [ -no-doc-sections ]\n";
    print "         [ -function funcname [ -function funcname ...] ]\n";
    print "         [ -nofunction funcname [ -nofunction funcname ...] ]\n";
    print "         c source file(s) > outputfile\n";
    print "         -v : verbose output, more warnings & other info listed\n";
    exit 1;
}

365 366
# get kernel version from env
sub get_kernel_version() {
367
    my $version = 'unknown kernel version';
368 369 370 371 372 373

    if (defined($ENV{'KERNELVERSION'})) {
	$version = $ENV{'KERNELVERSION'};
    }
    return $version;
}
L
Linus Torvalds 已提交
374 375 376 377 378

##
# dumps section contents to arrays/hashes intended for that purpose.
#
sub dump_section {
379
    my $file = shift;
L
Linus Torvalds 已提交
380 381 382 383 384 385 386 387 388 389 390
    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;
391
	$sectcheck = $sectcheck . $name . " ";
392 393 394 395
    } elsif ($name eq "@\.\.\.") {
#	print STDERR "parameter def '...' = '$contents'\n";
	$name = "...";
	$parameterdescs{$name} = $contents;
396
	$sectcheck = $sectcheck . $name . " ";
L
Linus Torvalds 已提交
397 398
    } else {
#	print STDERR "other section '$name' = '$contents'\n";
399 400 401 402
	if (defined($sections{$name}) && ($sections{$name} ne "")) {
		print STDERR "Error(${file}:$.): duplicate section name '$name'\n";
		++$errors;
	}
L
Linus Torvalds 已提交
403 404 405 406 407
	$sections{$name} = $contents;
	push @sectionlist, $name;
    }
}

408 409 410 411
##
# dump DOC: section after checking that it should go out
#
sub dump_doc_section {
412
    my $file = shift;
413 414 415
    my $name = shift;
    my $contents = join "\n", @_;

416 417 418 419
    if ($no_doc_sections) {
        return;
    }

420 421 422 423
    if (($function_only == 0) ||
	( $function_only == 1 && defined($function_table{$name})) ||
	( $function_only == 2 && !defined($function_table{$name})))
    {
424
	dump_section($file, $name, $contents);
425 426 427 428 429 430 431
	output_blockhead({'sectionlist' => \@sectionlist,
			  'sections' => \%sections,
			  'module' => $modulename,
			  'content-only' => ($function_only != 0), });
    }
}

L
Linus Torvalds 已提交
432 433 434 435 436 437 438 439
##
# output function
#
# parameterdescs, a hash.
#  function => "function name"
#  parameterlist => @list of parameters
#  parameterdescs => %parameter descriptions
#  sectionlist => @list of sections
440
#  sections => %section descriptions
441
#
L
Linus Torvalds 已提交
442 443 444 445 446 447 448 449 450 451 452

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

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

453
    if ($output_mode eq "html" || $output_mode eq "xml") {
454 455
	$contents = local_unescape($contents);
	# convert data read & converted thru xml_escape() into &xyz; format:
456
	$contents =~ s/\\\\\\/\&/g;
457
    }
458
#   print STDERR "contents b4:$contents\n";
L
Linus Torvalds 已提交
459 460
    eval $dohighlight;
    die $@ if $@;
461 462
#   print STDERR "contents af:$contents\n";

L
Linus Torvalds 已提交
463
    foreach $line (split "\n", $contents) {
464 465 466
	if (! $output_preformatted) {
	    $line =~ s/^\s*//;
	}
467
	if ($line eq ""){
468 469 470
	    if (! $output_preformatted) {
		print $lineprefix, local_unescape($blankline);
	    }
L
Linus Torvalds 已提交
471
	} else {
472
	    $line =~ s/\\\\\\/\&/g;
473 474 475 476 477
	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
		print "\\&$line";
	    } else {
		print $lineprefix, $line;
	    }
L
Linus Torvalds 已提交
478 479 480 481 482 483 484 485 486 487 488 489 490 491 492
	}
	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";
493
    }
L
Linus Torvalds 已提交
494 495 496 497 498 499 500
}

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

503
    print "<b>enum " . $args{'enum'} . "</b> {<br>\n";
L
Linus Torvalds 已提交
504 505
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
506
	print " <b>" . $parameter . "</b>";
L
Linus Torvalds 已提交
507 508 509 510 511 512 513 514 515 516 517
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",\n";
	}
	print "<br>";
    }
    print "};<br>\n";

    print "<h3>Constants</h3>\n";
    print "<dl>\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
518
	print "<dt><b>" . $parameter . "</b>\n";
L
Linus Torvalds 已提交
519 520 521 522 523 524 525 526
	print "<dd>";
	output_highlight($args{'parameterdescs'}{$parameter});
    }
    print "</dl>\n";
    output_section_html(@_);
    print "<hr>\n";
}

527
# output typedef in html
L
Linus Torvalds 已提交
528 529 530 531
sub output_typedef_html(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $count;
532
    print "<h2>typedef " . $args{'typedef'} . "</h2>\n";
L
Linus Torvalds 已提交
533

534
    print "<b>typedef " . $args{'typedef'} . "</b>\n";
L
Linus Torvalds 已提交
535 536 537 538 539 540 541 542 543
    output_section_html(@_);
    print "<hr>\n";
}

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

544 545
    print "<h2>" . $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "</h2>\n";
    print "<b>" . $args{'type'} . " " . $args{'struct'} . "</b> {<br>\n";
L
Linus Torvalds 已提交
546 547 548 549 550 551 552 553
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
		print "$parameter<br>\n";
		next;
	}
	my $parameter_name = $parameter;
	$parameter_name =~ s/\[.*//;

554
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
555 556 557
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
558
	    print "&nbsp; &nbsp; <i>$1</i><b>$parameter</b>) <i>($2)</i>;<br>\n";
L
Linus Torvalds 已提交
559
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
560 561
	    # bitfield
	    print "&nbsp; &nbsp; <i>$1</i> <b>$parameter</b>$2;<br>\n";
L
Linus Torvalds 已提交
562
	} else {
563
	    print "&nbsp; &nbsp; <i>$type</i> <b>$parameter</b>;<br>\n";
L
Linus Torvalds 已提交
564 565 566 567 568 569 570 571 572 573 574 575
	}
    }
    print "};<br>\n";

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

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

576
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
577
	print "<dt><b>" . $parameter . "</b>\n";
L
Linus Torvalds 已提交
578 579 580 581 582 583 584 585 586 587 588 589 590 591
	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;

592 593 594
    print "<h2>" . $args{'function'} . " - " . $args{'purpose'} . "</h2>\n";
    print "<i>" . $args{'functiontype'} . "</i>\n";
    print "<b>" . $args{'function'} . "</b>\n";
L
Linus Torvalds 已提交
595 596 597 598 599 600 601 602
    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 {
603
	    print "<i>" . $type . "</i> <b>" . $parameter . "</b>";
L
Linus Torvalds 已提交
604 605 606 607 608 609 610 611 612 613 614 615 616 617
	}
	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/\[.*//;

618
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
619
	print "<dt><b>" . $parameter . "</b>\n";
L
Linus Torvalds 已提交
620 621 622 623 624 625 626 627
	print "<dd>";
	output_highlight($args{'parameterdescs'}{$parameter_name});
    }
    print "</dl>\n";
    output_section_html(@_);
    print "<hr>\n";
}

628 629
# output DOC: block header in html
sub output_blockhead_html(%) {
L
Linus Torvalds 已提交
630 631 632 633 634 635 636 637 638 639 640 641 642 643 644
    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]};
645
    my $section;
L
Linus Torvalds 已提交
646 647 648
    # print out each section
    $lineprefix="   ";
    foreach $section (@{$args{'sectionlist'}}) {
649 650
	print "<refsect1>\n";
	print "<title>$section</title>\n";
L
Linus Torvalds 已提交
651
	if ($section =~ m/EXAMPLE/i) {
652
	    print "<informalexample><programlisting>\n";
653
	    $output_preformatted = 1;
654 655
	} else {
	    print "<para>\n";
L
Linus Torvalds 已提交
656 657
	}
	output_highlight($args{'sections'}{$section});
658
	$output_preformatted = 0;
L
Linus Torvalds 已提交
659
	if ($section =~ m/EXAMPLE/i) {
660 661 662
	    print "</programlisting></informalexample>\n";
	} else {
	    print "</para>\n";
L
Linus Torvalds 已提交
663
	}
664
	print "</refsect1>\n";
L
Linus Torvalds 已提交
665 666 667 668 669 670 671 672 673 674
    }
}

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

675
    $id = "API-" . $args{'function'};
L
Linus Torvalds 已提交
676 677
    $id =~ s/[^A-Za-z0-9]/-/g;

678
    print "<refentry id=\"$id\">\n";
679 680 681 682 683
    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 已提交
684
    print "<refmeta>\n";
685
    print " <refentrytitle><phrase>" . $args{'function'} . "</phrase></refentrytitle>\n";
686
    print " <manvolnum>9</manvolnum>\n";
687
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
L
Linus Torvalds 已提交
688 689
    print "</refmeta>\n";
    print "<refnamediv>\n";
690
    print " <refname>" . $args{'function'} . "</refname>\n";
L
Linus Torvalds 已提交
691 692 693 694 695 696 697 698 699
    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";
700 701
    print "   <funcdef>" . $args{'functiontype'} . " ";
    print "<function>" . $args{'function'} . " </function></funcdef>\n";
L
Linus Torvalds 已提交
702 703 704 705 706 707 708 709 710 711

    $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 {
712
		print "   <paramdef>" . $type;
L
Linus Torvalds 已提交
713 714 715 716
		print " <parameter>$parameter</parameter></paramdef>\n";
	    }
	}
    } else {
717
	print "  <void/>\n";
L
Linus Torvalds 已提交
718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751
    }
    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;

752
    $id = "API-struct-" . $args{'struct'};
L
Linus Torvalds 已提交
753 754
    $id =~ s/[^A-Za-z0-9]/-/g;

755
    print "<refentry id=\"$id\">\n";
756 757 758 759 760
    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 已提交
761
    print "<refmeta>\n";
762
    print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
763
    print " <manvolnum>9</manvolnum>\n";
764
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
L
Linus Torvalds 已提交
765 766
    print "</refmeta>\n";
    print "<refnamediv>\n";
767
    print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
L
Linus Torvalds 已提交
768 769 770 771 772 773 774 775 776
    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";
777
    print $args{'type'} . " " . $args{'struct'} . " {\n";
L
Linus Torvalds 已提交
778 779
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
780 781 782 783 784
	    my $prm = $parameter;
	    # convert data read & converted thru xml_escape() into &xyz; format:
	    # This allows us to have #define macros interspersed in a struct.
	    $prm =~ s/\\\\\\/\&/g;
	    print "$prm\n";
L
Linus Torvalds 已提交
785 786 787 788 789 790 791
	    next;
	}

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

	defined($args{'parameterdescs'}{$parameter_name}) || next;
792
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
793 794 795 796 797
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "  $1 $parameter) ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
798
	    # bitfield
L
Linus Torvalds 已提交
799 800
	    print "  $1 $parameter$2;\n";
	} else {
801
	    print "  " . $type . " " . $parameter . ";\n";
L
Linus Torvalds 已提交
802 803 804 805 806 807 808 809 810
	}
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

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

811
    if ($#{$args{'parameterlist'}} >= 0) {
L
Linus Torvalds 已提交
812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828
    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";
829 830 831
    } else {
	print " <para>\n  None\n </para>\n";
    }
L
Linus Torvalds 已提交
832 833 834 835 836 837 838 839 840 841 842 843 844 845
    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;

846
    $id = "API-enum-" . $args{'enum'};
L
Linus Torvalds 已提交
847 848
    $id =~ s/[^A-Za-z0-9]/-/g;

849
    print "<refentry id=\"$id\">\n";
850 851 852 853 854
    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 已提交
855
    print "<refmeta>\n";
856
    print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
857
    print " <manvolnum>9</manvolnum>\n";
858
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
L
Linus Torvalds 已提交
859 860
    print "</refmeta>\n";
    print "<refnamediv>\n";
861
    print " <refname>enum " . $args{'enum'} . "</refname>\n";
L
Linus Torvalds 已提交
862 863 864 865 866 867 868 869 870
    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";
871
    print "enum " . $args{'enum'} . " {\n";
L
Linus Torvalds 已提交
872 873
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
874 875
	print "  $parameter";
	if ($count != $#{$args{'parameterlist'}}) {
L
Linus Torvalds 已提交
876 877
	    $count++;
	    print ",";
878
	}
L
Linus Torvalds 已提交
879 880 881 882 883 884 885
	print "\n";
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

    print "<refsect1>\n";
886
    print " <title>Constants</title>\n";
L
Linus Torvalds 已提交
887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912
    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;

913
    $id = "API-typedef-" . $args{'typedef'};
L
Linus Torvalds 已提交
914 915
    $id =~ s/[^A-Za-z0-9]/-/g;

916
    print "<refentry id=\"$id\">\n";
917 918 919 920 921
    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 已提交
922
    print "<refmeta>\n";
923
    print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
924
    print " <manvolnum>9</manvolnum>\n";
L
Linus Torvalds 已提交
925 926
    print "</refmeta>\n";
    print "<refnamediv>\n";
927
    print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
L
Linus Torvalds 已提交
928 929 930 931 932 933 934 935
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
936
    print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
L
Linus Torvalds 已提交
937 938 939 940 941 942 943 944
    print "</refsynopsisdiv>\n";

    output_section_xml(@_);

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

# output in XML DocBook
945
sub output_blockhead_xml(%) {
L
Linus Torvalds 已提交
946 947 948 949 950 951 952 953 954 955
    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'}}) {
956 957 958
	if (!$args{'content-only'}) {
		print "<refsect1>\n <title>$section</title>\n";
	}
L
Linus Torvalds 已提交
959 960
	if ($section =~ m/EXAMPLE/i) {
	    print "<example><para>\n";
961
	    $output_preformatted = 1;
962 963
	} else {
	    print "<para>\n";
L
Linus Torvalds 已提交
964 965
	}
	output_highlight($args{'sections'}{$section});
966
	$output_preformatted = 0;
L
Linus Torvalds 已提交
967 968
	if ($section =~ m/EXAMPLE/i) {
	    print "</para></example>\n";
969 970 971 972 973
	} else {
	    print "</para>";
	}
	if (!$args{'content-only'}) {
		print "\n</refsect1>\n";
L
Linus Torvalds 已提交
974 975 976 977 978 979 980 981 982 983 984 985 986
	}
    }

    print "\n\n";
}

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

987
    $id = $args{'module'} . "-" . $args{'function'};
L
Linus Torvalds 已提交
988 989 990
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<sect2>\n";
991
    print " <title id=\"$id\">" . $args{'function'} . "</title>\n";
L
Linus Torvalds 已提交
992 993

    print "  <funcsynopsis>\n";
994 995
    print "   <funcdef>" . $args{'functiontype'} . " ";
    print "<function>" . $args{'function'} . " ";
L
Linus Torvalds 已提交
996 997 998 999 1000 1001 1002 1003 1004 1005 1006
    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 {
1007
		print "   <paramdef>" . $type;
L
Linus Torvalds 已提交
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";
1042
	    $output_preformatted = 1;
L
Linus Torvalds 已提交
1043 1044 1045 1046
	} else {
	}
	print "<para>\n";
	output_highlight($args{'sections'}{$section});
1047
	$output_preformatted = 0;
L
Linus Torvalds 已提交
1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068
	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";
1069
    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1070 1071

    print ".SH SYNOPSIS\n";
1072
    if ($args{'functiontype'} ne "") {
1073
	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
1074
    } else {
1075
	print ".B \"" . $args{'function'} . "\n";
1076
    }
L
Linus Torvalds 已提交
1077 1078 1079 1080 1081 1082 1083 1084 1085 1086
    $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
1087
	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
L
Linus Torvalds 已提交
1088 1089
	} else {
	    $type =~ s/([^\*])$/$1 /;
1090
	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
L
Linus Torvalds 已提交
1091 1092 1093 1094 1095 1096 1097 1098 1099 1100
	}
	$count++;
	$parenth = "";
    }

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

1101
	print ".IP \"" . $parameter . "\" 12\n";
L
Linus Torvalds 已提交
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119
	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";
1120
    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1121 1122

    print ".SH SYNOPSIS\n";
1123
    print "enum " . $args{'enum'} . " {\n";
L
Linus Torvalds 已提交
1124 1125
    $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
1126
	print ".br\n.BI \"    $parameter\"\n";
L
Linus Torvalds 已提交
1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141
	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/\[.*//;

1142
	print ".IP \"" . $parameter . "\" 12\n";
L
Linus Torvalds 已提交
1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156
	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);

1157
    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";
L
Linus Torvalds 已提交
1158 1159

    print ".SH NAME\n";
1160
    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1161 1162

    print ".SH SYNOPSIS\n";
1163
    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
L
Linus Torvalds 已提交
1164 1165 1166 1167 1168 1169 1170 1171 1172

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

1173
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
1174 1175 1176
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
1177
	    print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
L
Linus Torvalds 已提交
1178
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1179
	    # bitfield
1180
	    print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
L
Linus Torvalds 已提交
1181 1182
	} else {
	    $type =~ s/([^\*])$/$1 /;
1183
	    print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
L
Linus Torvalds 已提交
1184 1185 1186 1187 1188
	}
	print "\n.br\n";
    }
    print "};\n.br\n";

1189
    print ".SH Members\n";
L
Linus Torvalds 已提交
1190 1191 1192 1193 1194 1195
    foreach $parameter (@{$args{'parameterlist'}}) {
	($parameter =~ /^#/) && next;

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

1196
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
1197
	print ".IP \"" . $parameter . "\" 12\n";
L
Linus Torvalds 已提交
1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214
	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";
1215
    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1216 1217 1218 1219 1220 1221 1222

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

1223
sub output_blockhead_man(%) {
L
Linus Torvalds 已提交
1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240
    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);
1241
    my $start;
L
Linus Torvalds 已提交
1242

1243
    print "Name:\n\n";
1244
    print $args{'function'} . " - " . $args{'purpose'} . "\n";
1245 1246

    print "\nSynopsis:\n\n";
1247
    if ($args{'functiontype'} ne "") {
1248
	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
1249
    } else {
1250
	$start = $args{'function'} . " (";
1251
    }
L
Linus Torvalds 已提交
1252
    print $start;
1253

L
Linus Torvalds 已提交
1254 1255 1256 1257 1258
    my $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
1259
	    print $1 . $parameter . ") (" . $2;
L
Linus Torvalds 已提交
1260
	} else {
1261
	    print $type . " " . $parameter;
L
Linus Torvalds 已提交
1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276
	}
	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/\[.*//;

1277
	print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
L
Linus Torvalds 已提交
1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290
    }
    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});
1291
    }
L
Linus Torvalds 已提交
1292 1293 1294 1295 1296 1297 1298 1299 1300 1301
    print "\n\n";
}

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

1302 1303
    print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
    print "enum " . $args{'enum'} . " {\n";
L
Linus Torvalds 已提交
1304 1305
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
1306
	print "\t$parameter";
L
Linus Torvalds 已提交
1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",";
	}
	print "\n";
    }
    print "};\n\n";

    print "Constants:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print "$parameter\n\t";
1318
	print $args{'parameterdescs'}{$parameter} . "\n";
L
Linus Torvalds 已提交
1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330
    }

    output_section_text(@_);
}

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

1331
    print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
L
Linus Torvalds 已提交
1332 1333 1334 1335 1336 1337 1338 1339
    output_section_text(@_);
}

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

1340 1341
    print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
    print $args{'type'} . " " . $args{'struct'} . " {\n";
L
Linus Torvalds 已提交
1342 1343 1344 1345 1346 1347 1348 1349 1350
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
	    print "$parameter\n";
	    next;
	}

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

1351
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
1352 1353 1354 1355 1356
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "\t$1 $parameter) ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
1357
	    # bitfield
L
Linus Torvalds 已提交
1358 1359
	    print "\t$1 $parameter$2;\n";
	} else {
1360
	    print "\t" . $type . " " . $parameter . ";\n";
L
Linus Torvalds 已提交
1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371
	}
    }
    print "};\n\n";

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

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

1372
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
L
Linus Torvalds 已提交
1373
	print "$parameter\n\t";
1374
	print $args{'parameterdescs'}{$parameter_name} . "\n";
L
Linus Torvalds 已提交
1375 1376 1377 1378 1379
    }
    print "\n";
    output_section_text(@_);
}

1380
sub output_blockhead_text(%) {
L
Linus Torvalds 已提交
1381 1382 1383 1384 1385 1386 1387 1388 1389 1390
    my %args = %{$_[0]};
    my ($parameter, $section);

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

1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426
## list mode output functions

sub output_function_list(%) {
    my %args = %{$_[0]};

    print $args{'function'} . "\n";
}

# output enum in list
sub output_enum_list(%) {
    my %args = %{$_[0]};
    print $args{'enum'} . "\n";
}

# output typedef in list
sub output_typedef_list(%) {
    my %args = %{$_[0]};
    print $args{'typedef'} . "\n";
}

# output struct as list
sub output_struct_list(%) {
    my %args = %{$_[0]};

    print $args{'struct'} . "\n";
}

sub output_blockhead_list(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

    foreach $section (@{$args{'sectionlist'}}) {
	print "DOC: $section\n";
    }
}

L
Linus Torvalds 已提交
1427
##
1428 1429 1430
# 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 已提交
1431 1432 1433 1434 1435
sub output_declaration {
    no strict 'refs';
    my $name = shift;
    my $functype = shift;
    my $func = "output_${functype}_$output_mode";
1436 1437
    if (($function_only==0) ||
	( $function_only == 1 && defined($function_table{$name})) ||
L
Linus Torvalds 已提交
1438 1439
	( $function_only == 2 && !defined($function_table{$name})))
    {
1440
	&$func(@_);
L
Linus Torvalds 已提交
1441 1442 1443 1444 1445
	$section_counter++;
    }
}

##
1446
# generic output function - calls the right one based on current output mode.
1447
sub output_blockhead {
L
Linus Torvalds 已提交
1448
    no strict 'refs';
1449
    my $func = "output_blockhead_" . $output_mode;
L
Linus Torvalds 已提交
1450 1451 1452 1453 1454
    &$func(@_);
    $section_counter++;
}

##
1455
# takes a declaration (struct, union, enum, typedef) and
L
Linus Torvalds 已提交
1456 1457 1458 1459
# invokes the right handler. NOT called for functions.
sub dump_declaration($$) {
    no strict 'refs';
    my ($prototype, $file) = @_;
1460
    my $func = "dump_" . $decl_type;
L
Linus Torvalds 已提交
1461 1462 1463 1464 1465 1466 1467 1468 1469 1470
    &$func(@_);
}

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

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

1473 1474
    if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
	#my $decl_type = $1;
1475 1476
	$declaration_name = $2;
	my $members = $3;
L
Linus Torvalds 已提交
1477 1478

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

1482
	# ignore members marked private:
1483 1484
	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
	$members =~ s/\/\*\s*private:.*//gos;
1485 1486
	# strip comments:
	$members =~ s/\/\*.*?\*\///gos;
1487
	$nested =~ s/\/\*.*?\*\///gos;
1488 1489
	# strip kmemcheck_bitfield_{begin,end}.*;
	$members =~ s/kmemcheck_bitfield_.*?;//gos;
1490 1491
	# strip attributes
	$members =~ s/__aligned\s*\(\d+\)//gos;
1492

L
Linus Torvalds 已提交
1493
	create_parameterlist($members, ';', $file);
1494
	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
L
Linus Torvalds 已提交
1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509

	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 {
1510
	print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
L
Linus Torvalds 已提交
1511 1512 1513 1514 1515 1516 1517 1518
	++$errors;
    }
}

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

1519
    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
1520 1521
    $x =~ s/^#\s*define\s+.*$//; # strip #define macros inside enums

L
Linus Torvalds 已提交
1522
    if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
1523 1524
	$declaration_name = $1;
	my $members = $2;
L
Linus Torvalds 已提交
1525 1526 1527 1528 1529

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

	}
1536

L
Linus Torvalds 已提交
1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548
	output_declaration($declaration_name,
			   'enum',
			   {'enum' => $declaration_name,
			    'module' => $modulename,
			    'parameterlist' => \@parameterlist,
			    'parameterdescs' => \%parameterdescs,
			    'sectionlist' => \@sectionlist,
			    'sections' => \%sections,
			    'purpose' => $declaration_purpose
			   });
    }
    else {
1549
	print STDERR "Error(${file}:$.): Cannot parse enum!\n";
L
Linus Torvalds 已提交
1550 1551 1552 1553 1554 1555 1556 1557
	++$errors;
    }
}

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

1558
    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
L
Linus Torvalds 已提交
1559
    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
1560
	$x =~ s/\(*.\)\s*;$/;/;
L
Linus Torvalds 已提交
1561 1562 1563 1564
	$x =~ s/\[*.\]\s*;$/;/;
    }

    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
1565
	$declaration_name = $1;
L
Linus Torvalds 已提交
1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576

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

1582 1583 1584 1585 1586 1587 1588 1589
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 已提交
1590 1591 1592 1593 1594 1595 1596
sub create_parameterlist($$$) {
    my $args = shift;
    my $splitter = shift;
    my $file = shift;
    my $type;
    my $param;

1597
    # temporarily replace commas inside function pointer definition
L
Linus Torvalds 已提交
1598
    while ($args =~ /(\([^\),]+),/) {
1599
	$args =~ s/(\([^\),]+),/$1#/g;
L
Linus Torvalds 已提交
1600
    }
1601

L
Linus Torvalds 已提交
1602 1603 1604
    foreach my $arg (split($splitter, $args)) {
	# strip comments
	$arg =~ s/\/\*.*\*\///;
1605 1606
	# strip leading/trailing spaces
	$arg =~ s/^\s*//;
L
Linus Torvalds 已提交
1607 1608 1609 1610 1611 1612 1613 1614
	$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);
1615
	} elsif ($arg =~ m/\(.+\)\s*\(/) {
L
Linus Torvalds 已提交
1616 1617
	    # pointer-to-function
	    $arg =~ tr/#/,/;
1618
	    $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
L
Linus Torvalds 已提交
1619 1620
	    $param = $1;
	    $type = $arg;
1621
	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
1622
	    save_struct_actual($param);
L
Linus Torvalds 已提交
1623
	    push_parameter($param, $type, $file);
1624
	} elsif ($arg) {
L
Linus Torvalds 已提交
1625 1626 1627 1628 1629 1630 1631
	    $arg =~ s/\s*:\s*/:/g;
	    $arg =~ s/\s*\[/\[/g;

	    my @args = split('\s*,\s*', $arg);
	    if ($args[0] =~ m/\*/) {
		$args[0] =~ s/(\*+)\s*/ $1/;
	    }
1632 1633 1634 1635 1636 1637 1638 1639 1640 1641

	    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 已提交
1642 1643 1644 1645 1646
	    unshift(@args, pop @first_arg);
	    $type = join " ", @first_arg;

	    foreach $param (@args) {
		if ($param =~ m/^(\*+)\s*(.*)/) {
1647
		    save_struct_actual($2);
L
Linus Torvalds 已提交
1648 1649 1650
		    push_parameter($2, "$type $1", $file);
		}
		elsif ($param =~ m/(.*?):(\d+)/) {
1651
		    if ($type ne "") { # skip unnamed bit-fields
1652
			save_struct_actual($1);
1653 1654
			push_parameter($1, "$type:$2", $file)
		    }
L
Linus Torvalds 已提交
1655 1656
		}
		else {
1657
		    save_struct_actual($param);
L
Linus Torvalds 已提交
1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669
		    push_parameter($param, $type, $file);
		}
	    }
	}
    }
}

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

1670 1671 1672 1673 1674 1675
	if (($anon_struct_union == 1) && ($type eq "") &&
	    ($param eq "}")) {
		return;		# ignore the ending }; from anon. struct/union
	}

	$anon_struct_union = 0;
L
Linus Torvalds 已提交
1676 1677 1678
	my $param_name = $param;
	$param_name =~ s/\[.*//;

1679
	if ($type eq "" && $param =~ /\.\.\.$/)
L
Linus Torvalds 已提交
1680
	{
1681 1682 1683
	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
		$parameterdescs{$param} = "variable arguments";
	    }
L
Linus Torvalds 已提交
1684 1685 1686 1687 1688 1689
	}
	elsif ($type eq "" && ($param eq "" or $param eq "void"))
	{
	    $param="void";
	    $parameterdescs{void} = "no arguments";
	}
1690 1691 1692 1693
	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
	# handle unnamed (anonymous) union or struct:
	{
		$type = $param;
1694
		$param = "{unnamed_" . $param . "}";
1695
		$parameterdescs{$param} = "anonymous\n";
1696
		$anon_struct_union = 1;
1697 1698
	}

1699
	# warn if parameter has no description
1700 1701 1702
	# (but ignore ones starting with # as these are not parameters
	# but inline preprocessor statements);
	# also ignore unnamed structs/unions;
1703
	if (!$anon_struct_union) {
1704 1705
	if (!defined $parameterdescs{$param_name} && $param_name !~ /^#/) {

L
Linus Torvalds 已提交
1706 1707 1708
	    $parameterdescs{$param_name} = $undescribed;

	    if (($type eq 'function') || ($type eq 'enum')) {
1709
		print STDERR "Warning(${file}:$.): Function parameter ".
L
Linus Torvalds 已提交
1710 1711 1712
		    "or member '$param' not " .
		    "described in '$declaration_name'\n";
	    }
1713
	    print STDERR "Warning(${file}:$.):" .
1714
			 " No description found for parameter '$param'\n";
L
Linus Torvalds 已提交
1715
	    ++$warnings;
1716 1717
	}
	}
L
Linus Torvalds 已提交
1718

1719 1720
	$param = xml_escape($param);

L
Lucas De Marchi 已提交
1721
	# strip spaces from $param so that it is one continuous string
1722 1723 1724 1725 1726 1727 1728 1729
	# 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 已提交
1730 1731 1732 1733
	push @parameterlist, $param;
	$parametertypes{$param} = $type;
}

1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746
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/\[.*\]//;
1747
			$prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
1748 1749 1750 1751 1752 1753 1754 1755
			# 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/\[.*//;

1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781
			##$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 已提交
1782 1783 1784 1785 1786 1787 1788 1789 1790 1791
##
# 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 +//;
1792
    $prototype =~ s/^asmlinkage +//;
L
Linus Torvalds 已提交
1793 1794
    $prototype =~ s/^inline +//;
    $prototype =~ s/^__inline__ +//;
1795 1796 1797
    $prototype =~ s/^__inline +//;
    $prototype =~ s/^__always_inline +//;
    $prototype =~ s/^noinline +//;
1798
    $prototype =~ s/__devinit +//;
1799
    $prototype =~ s/__init +//;
1800
    $prototype =~ s/__init_or_module +//;
1801
    $prototype =~ s/__must_check +//;
1802
    $prototype =~ s/__weak +//;
1803
    $prototype =~ s/^#\s*define\s+//; #ak added
1804
    $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
L
Linus Torvalds 已提交
1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819

    # 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)
1820
    # - pci_match_device, __copy_to_user (long return type)
L
Linus Torvalds 已提交
1821 1822 1823 1824 1825

    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*\(([^\(]*)\)/ ||
1826
	$prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
L
Linus Torvalds 已提交
1827 1828 1829 1830 1831 1832 1833 1834
	$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*\(([^\{]*)\)/ ||
1835 1836
	$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*\(([^\{]*)\)/ ||
1837 1838
	$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 已提交
1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849
	$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;
    }

1850 1851 1852
	my $prms = join " ", @parameterlist;
	check_sections($file, $declaration_name, "function", $sectcheck, $prms, "");

1853
    output_declaration($declaration_name,
L
Linus Torvalds 已提交
1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874
		       'function',
		       {'function' => $declaration_name,
			'module' => $modulename,
			'functiontype' => $return_type,
			'parameterlist' => \@parameterlist,
			'parameterdescs' => \%parameterdescs,
			'parametertypes' => \%parametertypes,
			'sectionlist' => \@sectionlist,
			'sections' => \%sections,
			'purpose' => $declaration_purpose
		       });
}

sub reset_state {
    $function = "";
    %constants = ();
    %parameterdescs = ();
    %parametertypes = ();
    @parameterlist = ();
    %sections = ();
    @sectionlist = ();
1875 1876
    $sectcheck = "";
    $struct_actual = "";
L
Linus Torvalds 已提交
1877
    $prototype = "";
1878

L
Linus Torvalds 已提交
1879 1880 1881
    $state = 0;
}

1882 1883 1884 1885 1886
sub tracepoint_munge($) {
	my $file = shift;
	my $tracepointname = 0;
	my $tracepointargs = 0;

1887
	if ($prototype =~ m/TRACE_EVENT\((.*?),/) {
1888 1889
		$tracepointname = $1;
	}
1890 1891 1892 1893 1894 1895 1896 1897
	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\((.*?)\)/) {
1898 1899 1900 1901 1902 1903 1904 1905 1906 1907
		$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)";
	}
}

1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941
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) = ' ';
			}
		}
	}
}

1942
sub process_state3_function($$) {
L
Linus Torvalds 已提交
1943 1944 1945
    my $x = shift;
    my $file = shift;

1946 1947
    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

1948
    if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) {
L
Linus Torvalds 已提交
1949 1950 1951
	# do nothing
    }
    elsif ($x =~ /([^\{]*)/) {
1952
	$prototype .= $1;
L
Linus Torvalds 已提交
1953
    }
1954

1955
    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
1956
	$prototype =~ s@/\*.*?\*/@@gos;	# strip comments.
L
Linus Torvalds 已提交
1957 1958
	$prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
	$prototype =~ s@^\s+@@gos; # strip leading spaces
1959 1960 1961
	if ($prototype =~ /SYSCALL_DEFINE/) {
		syscall_munge();
	}
1962 1963 1964
	if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
	    $prototype =~ /DEFINE_SINGLE_EVENT/)
	{
1965 1966
		tracepoint_munge($file);
	}
1967
	dump_function($prototype, $file);
L
Linus Torvalds 已提交
1968 1969 1970 1971
	reset_state();
    }
}

1972
sub process_state3_type($$) {
L
Linus Torvalds 已提交
1973 1974 1975 1976 1977 1978
    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
1979 1980
    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

L
Linus Torvalds 已提交
1981 1982 1983 1984 1985 1986
    if ($x =~ /^#/) {
	# To distinguish preprocessor directive from regular declaration later.
	$x .= ";";
    }

    while (1) {
1987
	if ( $x =~ /([^{};]*)([{};])(.*)/ ) {
L
Linus Torvalds 已提交
1988 1989 1990 1991
	    $prototype .= $1 . $2;
	    ($2 eq '{') && $brcount++;
	    ($2 eq '}') && $brcount--;
	    if (($2 eq ';') && ($brcount == 0)) {
1992
		dump_declaration($prototype, $file);
L
Linus Torvalds 已提交
1993
		reset_state();
1994
		last;
L
Linus Torvalds 已提交
1995 1996
	    }
	    $x = $3;
1997
	} else {
L
Linus Torvalds 已提交
1998 1999 2000 2001 2002 2003
	    $prototype .= $x;
	    last;
	}
    }
}

2004 2005 2006 2007 2008 2009 2010
# 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 已提交
2011 2012
sub xml_escape($) {
	my $text = shift;
2013 2014 2015
	if (($output_mode eq "text") || ($output_mode eq "man")) {
		return $text;
	}
L
Linus Torvalds 已提交
2016 2017 2018 2019 2020 2021
	$text =~ s/\&/\\\\\\amp;/g;
	$text =~ s/\</\\\\\\lt;/g;
	$text =~ s/\>/\\\\\\gt;/g;
	return $text;
}

2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033
# 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 已提交
2034
sub process_file($) {
2035
    my $file;
L
Linus Torvalds 已提交
2036 2037
    my $identifier;
    my $func;
2038
    my $descr;
2039
    my $in_purpose = 0;
L
Linus Torvalds 已提交
2040 2041
    my $initial_section_counter = $section_counter;

2042 2043 2044 2045 2046 2047
    if (defined($ENV{'SRCTREE'})) {
	$file = "$ENV{'SRCTREE'}" . "/" . "@_";
    }
    else {
	$file = "@_";
    }
L
Linus Torvalds 已提交
2048 2049 2050 2051 2052 2053 2054 2055 2056 2057
    if (defined($source_map{$file})) {
	$file = $source_map{$file};
    }

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

2058 2059
    $. = 1;

L
Linus Torvalds 已提交
2060 2061
    $section_counter = 0;
    while (<IN>) {
2062 2063 2064
	while (s/\\\s*$//) {
	    $_ .= <IN>;
	}
L
Linus Torvalds 已提交
2065 2066 2067
	if ($state == 0) {
	    if (/$doc_start/o) {
		$state = 1;		# next line is always the function name
2068
		$in_doc_sect = 0;
L
Linus Torvalds 已提交
2069 2070 2071 2072 2073 2074 2075 2076 2077 2078
	    }
	} 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;
		}
2079
	    }
L
Linus Torvalds 已提交
2080 2081 2082 2083 2084 2085 2086 2087
	    elsif (/$doc_decl/o) {
		$identifier = $1;
		if (/\s*([\w\s]+?)\s*-/) {
		    $identifier = $1;
		}

		$state = 2;
		if (/-(.*)/) {
2088
		    # strip leading/trailing/multiple spaces
2089 2090 2091
		    $descr= $1;
		    $descr =~ s/^\s*//;
		    $descr =~ s/\s*$//;
2092
		    $descr =~ s/\s+/ /g;
2093
		    $declaration_purpose = xml_escape($descr);
2094
		    $in_purpose = 1;
L
Linus Torvalds 已提交
2095 2096 2097
		} else {
		    $declaration_purpose = "";
		}
2098 2099 2100 2101 2102 2103 2104

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

L
Linus Torvalds 已提交
2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130
		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;

2131
		if (($contents ne "") && ($contents ne "\n")) {
2132 2133 2134 2135
		    if (!$in_doc_sect && $verbose) {
			print STDERR "Warning(${file}:$.): contents before sections\n";
			++$warnings;
		    }
2136
		    dump_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2137 2138 2139
		    $section = $section_default;
		}

2140
		$in_doc_sect = 1;
2141
		$in_purpose = 0;
L
Linus Torvalds 已提交
2142 2143
		$contents = $newcontents;
		if ($contents ne "") {
2144 2145 2146
		    while ((substr($contents, 0, 1) eq " ") ||
			substr($contents, 0, 1) eq "\t") {
			    $contents = substr($contents, 1);
2147
		    }
L
Linus Torvalds 已提交
2148 2149 2150 2151 2152
		    $contents .= "\n";
		}
		$section = $newsection;
	    } elsif (/$doc_end/) {

2153
		if (($contents ne "") && ($contents ne "\n")) {
2154
		    dump_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2155 2156 2157
		    $section = $section_default;
		    $contents = "";
		}
2158 2159 2160 2161 2162
		# 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 已提交
2163 2164 2165 2166

		$prototype = "";
		$state = 3;
		$brcount = 0;
2167
#		print STDERR "end of doc comment, looking for prototype\n";
L
Linus Torvalds 已提交
2168 2169 2170
	    } elsif (/$doc_content/) {
		# miguel-style comment kludge, look for blank lines after
		# @parameter line to signify start of description
2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183
		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);
2184
		    $declaration_purpose =~ s/\s+/ /g;
L
Linus Torvalds 已提交
2185
		} else {
2186
		    $contents .= $1 . "\n";
L
Linus Torvalds 已提交
2187 2188 2189
		}
	    } else {
		# i dont know - bad line?  ignore.
2190
		print STDERR "Warning(${file}:$.): bad line: $_";
L
Linus Torvalds 已提交
2191 2192
		++$warnings;
	    }
2193
	} elsif ($state == 3) {	# scanning for function '{' (end of prototype)
L
Linus Torvalds 已提交
2194
	    if ($decl_type eq 'function') {
2195
		process_state3_function($_, $file);
L
Linus Torvalds 已提交
2196
	    } else {
2197
		process_state3_type($_, $file);
L
Linus Torvalds 已提交
2198 2199 2200
	    }
	} elsif ($state == 4) {
		# Documentation block
2201
		if (/$doc_block/) {
2202
			dump_doc_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216
			$contents = "";
			$function = "";
			%constants = ();
			%parameterdescs = ();
			%parametertypes = ();
			@parameterlist = ();
			%sections = ();
			@sectionlist = ();
			$prototype = "";
			if ( $1 eq "" ) {
				$section = $section_intro;
			} else {
				$section = $1;
			}
2217
		}
L
Linus Torvalds 已提交
2218 2219
		elsif (/$doc_end/)
		{
2220
			dump_doc_section($file, $section, xml_escape($contents));
L
Linus Torvalds 已提交
2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240
			$contents = "";
			$function = "";
			%constants = ();
			%parameterdescs = ();
			%parametertypes = ();
			@parameterlist = ();
			%sections = ();
			@sectionlist = ();
			$prototype = "";
			$state = 0;
		}
		elsif (/$doc_content/)
		{
			if ( $1 eq "" )
			{
				$contents .= $blankline;
			}
			else
			{
				$contents .= $1 . "\n";
2241
			}
2242 2243
		}
	}
L
Linus Torvalds 已提交
2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276
    }
    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";
	}
    }
}
2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312


$kernelversion = get_kernel_version();

# generate a sequence of code that will splice in highlighting information
# using the s// operator.
foreach my $pattern (keys %highlights) {
#   print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
    $dohighlight .=  "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
}

# 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);
新手
引导
客服 返回
顶部