kernel-doc

	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;

    $id = "API-struct-" . $args{'struct'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<refentry id=\"$id\">\n";
    print "<refentryinfo>\n";
    print " <title>U-BOOT</title>\n";
    print " <productname>Bootloader Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
    print "<refmeta>\n";
    print " <refentrytitle><phrase>" . $args{'type'} . " " . $args{'struct'} . "</phrase></refentrytitle>\n";
    print " <manvolnum>9</manvolnum>\n";
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>" . $args{'type'} . " " . $args{'struct'} . "</refname>\n";
    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";
    print $args{'type'} . " " . $args{'struct'} . " {\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
	    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";
	    next;
	}

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

	defined($args{'parameterdescs'}{$parameter_name}) || next;
	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "  $1 $parameter) ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
	    # bitfield
	    print "  $1 $parameter$2;\n";
	} else {
	    print "  " . $type . " " . $parameter . ";\n";
	}
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

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

    if ($#{$args{'parameterlist'}} >= 0) {
    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";
    } else {
	print " <para>\n  None\n </para>\n";
    }
    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;

    $id = "API-enum-" . $args{'enum'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<refentry id=\"$id\">\n";
    print "<refentryinfo>\n";
    print " <title>U-BOOT</title>\n";
    print " <productname>Bootloader Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
    print "<refmeta>\n";
    print " <refentrytitle><phrase>enum " . $args{'enum'} . "</phrase></refentrytitle>\n";
    print " <manvolnum>9</manvolnum>\n";
    print " <refmiscinfo class=\"version\">" . $kernelversion . "</refmiscinfo>\n";
    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>enum " . $args{'enum'} . "</refname>\n";
    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";
    print "enum " . $args{'enum'} . " {\n";
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
	print "  $parameter";
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",";
	}
	print "\n";
    }
    print "};";
    print "  </programlisting>\n";
    print "</refsynopsisdiv>\n";

    print "<refsect1>\n";
    print " <title>Constants</title>\n";
    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;

    $id = "API-typedef-" . $args{'typedef'};
    $id =~ s/[^A-Za-z0-9]/-/g;

    print "<refentry id=\"$id\">\n";
    print "<refentryinfo>\n";
    print " <title>U-BOOT</title>\n";
    print " <productname>Bootloader Hackers Manual</productname>\n";
    print " <date>$man_date</date>\n";
    print "</refentryinfo>\n";
    print "<refmeta>\n";
    print " <refentrytitle><phrase>typedef " . $args{'typedef'} . "</phrase></refentrytitle>\n";
    print " <manvolnum>9</manvolnum>\n";
    print "</refmeta>\n";
    print "<refnamediv>\n";
    print " <refname>typedef " . $args{'typedef'} . "</refname>\n";
    print " <refpurpose>\n";
    print "  ";
    output_highlight ($args{'purpose'});
    print " </refpurpose>\n";
    print "</refnamediv>\n";

    print "<refsynopsisdiv>\n";
    print " <title>Synopsis</title>\n";
    print "  <synopsis>typedef " . $args{'typedef'} . ";</synopsis>\n";
    print "</refsynopsisdiv>\n";

    output_section_xml(@_);

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

# output in XML DocBook
sub output_blockhead_xml(%) {
    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'}}) {
	if (!$args{'content-only'}) {
		print "<refsect1>\n <title>$section</title>\n";
	}
	if ($section =~ m/EXAMPLE/i) {
	    print "<example><para>\n";
	    $output_preformatted = 1;
	} else {
	    print "<para>\n";
	}
	output_highlight($args{'sections'}{$section});
	$output_preformatted = 0;
	if ($section =~ m/EXAMPLE/i) {
	    print "</para></example>\n";
	} else {
	    print "</para>";
	}
	if (!$args{'content-only'}) {
		print "\n</refsect1>\n";
	}
    }

    print "\n\n";
}

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

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

    print "<sect2>\n";
    print " <title id=\"$id\">" . $args{'function'} . "</title>\n";

    print "  <funcsynopsis>\n";
    print "   <funcdef>" . $args{'functiontype'} . " ";
    print "<function>" . $args{'function'} . " ";
    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 {
		print "   <paramdef>" . $type;
		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";
	    $output_preformatted = 1;
	} else {
	}
	print "<para>\n";
	output_highlight($args{'sections'}{$section});
	$output_preformatted = 0;
	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\" \"Bootloader Hacker's Manual\" U-BOOT\n";

    print ".SH NAME\n";
    print $args{'function'} . " \\- " . $args{'purpose'} . "\n";

    print ".SH SYNOPSIS\n";
    if ($args{'functiontype'} ne "") {
	print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";
    } else {
	print ".B \"" . $args{'function'} . "\n";
    }
    $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
	    print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n";
	} else {
	    $type =~ s/([^\*])$/$1 /;
	    print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n";
	}
	$count++;
	$parenth = "";
    }

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

	print ".IP \"" . $parameter . "\" 12\n";
	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\" U-BOOT\n";

    print ".SH NAME\n";
    print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";

    print ".SH SYNOPSIS\n";
    print "enum " . $args{'enum'} . " {\n";
    $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
	print ".br\n.BI \"    $parameter\"\n";
	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/\[.*//;

	print ".IP \"" . $parameter . "\" 12\n";
	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);

    print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" U-BOOT\n";

    print ".SH NAME\n";
    print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";

    print ".SH SYNOPSIS\n";
    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";

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

	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print ".BI \"    " . $1 . "\" " . $parameter . " \") (" . $2 . ")" . "\"\n;\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
	    # bitfield
	    print ".BI \"    " . $1 . "\ \" " . $parameter . $2 . " \"" . "\"\n;\n";
	} else {
	    $type =~ s/([^\*])$/$1 /;
	    print ".BI \"    " . $type . "\" " . $parameter . " \"" . "\"\n;\n";
	}
	print "\n.br\n";
    }
    print "};\n.br\n";

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

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

	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
	print ".IP \"" . $parameter . "\" 12\n";
	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\" U-BOOT\n";

    print ".SH NAME\n";
    print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";

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

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

    print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" U-BOOT\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);
    my $start;

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

    print "\nSynopsis:\n\n";
    if ($args{'functiontype'} ne "") {
	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
    } else {
	$start = $args{'function'} . " (";
    }
    print $start;

    my $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print $1 . $parameter . ") (" . $2;
	} else {
	    print $type . " " . $parameter;
	}
	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/\[.*//;

	print $parameter . "\n\t" . $args{'parameterdescs'}{$parameter_name} . "\n";
    }
    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});
    }
    print "\n\n";
}

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

    print "enum " . $args{'enum'} . " - " . $args{'purpose'} . "\n\n";
    print "enum " . $args{'enum'} . " {\n";
    $count = 0;
    foreach $parameter (@{$args{'parameterlist'}}) {
	print "\t$parameter";
	if ($count != $#{$args{'parameterlist'}}) {
	    $count++;
	    print ",";
	}
	print "\n";
    }
    print "};\n\n";

    print "Constants:\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	print "$parameter\n\t";
	print $args{'parameterdescs'}{$parameter} . "\n";
    }

    output_section_text(@_);
}

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

    print "typedef " . $args{'typedef'} . " - " . $args{'purpose'} . "\n";
    output_section_text(@_);
}

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

    print $args{'type'} . " " . $args{'struct'} . " - " . $args{'purpose'} . "\n\n";
    print $args{'type'} . " " . $args{'struct'} . " {\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
	if ($parameter =~ /^#/) {
	    print "$parameter\n";
	    next;
	}

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

	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
	$type = $args{'parametertypes'}{$parameter};
	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
	    # pointer-to-function
	    print "\t$1 $parameter) ($2);\n";
	} elsif ($type =~ m/^(.*?)\s*(:.*)/) {
	    # bitfield
	    print "\t$1 $parameter$2;\n";
	} else {
	    print "\t" . $type . " " . $parameter . ";\n";
	}
    }
    print "};\n\n";

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

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

	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
	print "$parameter\n\t";
	print $args{'parameterdescs'}{$parameter_name} . "\n";
    }
    print "\n";
    output_section_text(@_);
}

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

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

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

##
# generic output function for all types (function, struct/union, typedef, enum);
# calls the generated, variable output_ function name based on
# functype and output_mode
sub output_declaration {
    no strict 'refs';
    my $name = shift;
    my $functype = shift;
    my $func = "output_${functype}_$output_mode";
    if (($function_only==0) ||
	( $function_only == 1 && defined($function_table{$name})) ||
	( $function_only == 2 && !defined($function_table{$name})))
    {
	&$func(@_);
	$section_counter++;
    }
}

##
# generic output function - calls the right one based on current output mode.
sub output_blockhead {
    no strict 'refs';
    my $func = "output_blockhead_" . $output_mode;
    &$func(@_);
    $section_counter++;
}

##
# takes a declaration (struct, union, enum, typedef) and
# invokes the right handler. NOT called for functions.
sub dump_declaration($$) {
    no strict 'refs';
    my ($prototype, $file) = @_;
    my $func = "dump_" . $decl_type;
    &$func(@_);
}

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

sub dump_struct($$) {
    my $x = shift;
    my $file = shift;
    my $nested;

    if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) {
	#my $decl_type = $1;
	$declaration_name = $2;
	my $members = $3;

	# ignore embedded structs or unions
	$members =~ s/({.*})//g;
	$nested = $1;

	# ignore members marked private:
	$members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gos;
	$members =~ s/\/\*\s*private:.*//gos;
	# strip comments:
	$members =~ s/\/\*.*?\*\///gos;
	$nested =~ s/\/\*.*?\*\///gos;
	# strip kmemcheck_bitfield_{begin,end}.*;
	$members =~ s/kmemcheck_bitfield_.*?;//gos;
	# strip attributes
	$members =~ s/__aligned\s*\(.+\)//gos;

	create_parameterlist($members, ';', $file);
	check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);

	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 {
	print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
	++$errors;
    }
}

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

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

    if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
	$declaration_name = $1;
	my $members = $2;

	foreach my $arg (split ',', $members) {
	    $arg =~ s/^\s*(\w+).*/$1/;
	    push @parameterlist, $arg;
	    if (!$parameterdescs{$arg}) {
		$parameterdescs{$arg} = $undescribed;
		print STDERR "Warning(${file}:$.): Enum value '$arg' ".
		    "not described in enum '$declaration_name'\n";
	    }

	}

	output_declaration($declaration_name,
			   'enum',
			   {'enum' => $declaration_name,
			    'module' => $modulename,
			    'parameterlist' => \@parameterlist,
			    'parameterdescs' => \%parameterdescs,
			    'sectionlist' => \@sectionlist,
			    'sections' => \%sections,
			    'purpose' => $declaration_purpose
			   });
    }
    else {
	print STDERR "Error(${file}:$.): Cannot parse enum!\n";
	++$errors;
    }
}

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

    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
    while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
	$x =~ s/\(*.\)\s*;$/;/;
	$x =~ s/\[*.\]\s*;$/;/;
    }

    if ($x =~ /typedef.*\s+(\w+)\s*;/) {
	$declaration_name = $1;

	output_declaration($declaration_name,
			   'typedef',
			   {'typedef' => $declaration_name,
			    'module' => $modulename,
			    'sectionlist' => \@sectionlist,
			    'sections' => \%sections,
			    'purpose' => $declaration_purpose
			   });
    }
    else {
	print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
	++$errors;
    }
}

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 . " ";
}

sub create_parameterlist($$$) {
    my $args = shift;
    my $splitter = shift;
    my $file = shift;
    my $type;
    my $param;

    # temporarily replace commas inside function pointer definition
    while ($args =~ /(\([^\),]+),/) {
	$args =~ s/(\([^\),]+),/$1#/g;
    }

    foreach my $arg (split($splitter, $args)) {
	# strip comments
	$arg =~ s/\/\*.*\*\///;
	# strip leading/trailing spaces
	$arg =~ s/^\s*//;
	$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);
	} elsif ($arg =~ m/\(.+\)\s*\(/) {
	    # pointer-to-function
	    $arg =~ tr/#/,/;
	    $arg =~ m/[^\(]+\(\*?\s*(\w*)\s*\)/;
	    $param = $1;
	    $type = $arg;
	    $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
	    save_struct_actual($param);
	    push_parameter($param, $type, $file);
	} elsif ($arg) {
	    $arg =~ s/\s*:\s*/:/g;
	    $arg =~ s/\s*\[/\[/g;

	    my @args = split('\s*,\s*', $arg);
	    if ($args[0] =~ m/\*/) {
		$args[0] =~ s/(\*+)\s*/ $1/;
	    }

	    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);
	    }

	    unshift(@args, pop @first_arg);
	    $type = join " ", @first_arg;

	    foreach $param (@args) {
		if ($param =~ m/^(\*+)\s*(.*)/) {
		    save_struct_actual($2);
		    push_parameter($2, "$type $1", $file);
		}
		elsif ($param =~ m/(.*?):(\d+)/) {
		    if ($type ne "") { # skip unnamed bit-fields
			save_struct_actual($1);
			push_parameter($1, "$type:$2", $file)
		    }
		}
		else {
		    save_struct_actual($param);
		    push_parameter($param, $type, $file);
		}
	    }
	}
    }
}

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

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

	$anon_struct_union = 0;
	my $param_name = $param;
	$param_name =~ s/\[.*//;

	if ($type eq "" && $param =~ /\.\.\.$/)
	{
	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
		$parameterdescs{$param} = "variable arguments";
	    }
	}
	elsif ($type eq "" && ($param eq "" or $param eq "void"))
	{
	    $param="void";
	    $parameterdescs{void} = "no arguments";
	}
	elsif ($type eq "" && ($param eq "struct" or $param eq "union"))
	# handle unnamed (anonymous) union or struct:
	{
		$type = $param;
		$param = "{unnamed_" . $param . "}";
		$parameterdescs{$param} = "anonymous\n";
		$anon_struct_union = 1;
	}

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

	    $parameterdescs{$param_name} = $undescribed;

	    if (($type eq 'function') || ($type eq 'enum')) {
		print STDERR "Warning(${file}:$.): Function parameter ".
		    "or member '$param' not " .
		    "described in '$declaration_name'\n";
	    }
	    print STDERR "Warning(${file}:$.):" .
			 " No description found for parameter '$param'\n";
	    ++$warnings;
	}
	}

	$param = xml_escape($param);

	# strip spaces from $param so that it is one continuous 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;
	push @parameterlist, $param;
	$parametertypes{$param} = $type;
}

sub check_sections($$$$$$) {
	my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck, $nested) = @_;