Quelle kernel-doc.pl Sprache: Shell

#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0
# vim: softtabstop=4

use warnings;
use strict;

## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
## Copyright (C) 2000, 1  Tim Waugh <twaugh@redhat.com>          ##
## Copyright (C) 2001  Simon Huggins                             ##
## Copyright (C) 2005-2012  Randy Dunlap                         ##
## Copyright (C) 2012  Dan Luedtke                               ##
## ##
## #define enhancements by Armin Kuster <akuster@mvista.com> ##
## Copyright (c) 2000 MontaVista Software, Inc. ##
#
# Copyright (C) 2022 Tomasz Warniełło (POD)

use Pod::Usage qw/pod2usage/;

=head1 NAME

kernel-doc - Print formatted kernel documentation to stdout

=head1 SYNOPSIS

kernel-doc [-h] [-v] [-Werror] [-Wall] [-Wreturn] [-Wshort-desc[ription]] [-Wcontents-before-sections]
   [ -man |
     -rst [-enable-lineno] |
     -none
   ]
   [
     -export |
     -internal |
     [-function NAME] ... |
     [-nosymbol NAME] ...
   ]
   [-no-doc-sections]
   [-export-file FILE] ...
   FILE ...

Run `kernel-doc -h` for details.

=head1 DESCRIPTION

Read C language source or header FILEs, extract embedded documentation comments,
and print formatted documentation to standard output.

The documentation comments are identified by the "/**" opening comment mark.

See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.

=cut

# more perldoc at the end of the file

## init lots of data

my $errors = 0;
my $warnings = 0;
my $anon_struct_union = 0;

# match expressions used to find embedded type information
my $type_constant = '\b``([^\`]+)``\b';
my $type_constant2 = '\%([-_*\w]+)';
my $type_func = '(\w+)';
my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
my $type_param_ref = '([\!~\*]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';
my $type_fp_param = '\@(\w+)';  # Special RST handling for func ptr params
my $type_fp_param2 = '\@(\w+->\S+)';  # Special RST handling for structs with func ptr params
my $type_env = '(\$\w+)';
my $type_enum = '\&(enum\s*([_\w]+))';
my $type_struct = '\&(struct\s*([_\w]+))';
my $type_typedef = '\&(typedef\s*([_\w]+))';
my $type_union = '\&(union\s*([_\w]+))';
my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
my $type_fallback = '\&([_\w]+)';
my $type_member_func = $type_member . '';

# Output conversion substitutions.
#  One for each output format

# these are pretty rough
my @highlights_man = (
    [$type_constant, "\$1"],
    [$type_constant2, "\$1"],
    [$type_func, "\\\\fB\$1\\\\fP"],
    [$type_enum, "\\\\fI\$1\\\\fP"],
    [$type_struct, "\\\\fI\$1\\\\fP"],
    [$type_typedef, "\\\\fI\$1\\\\fP"],
    [$type_union, "\\\\fI\$1\\\\fP"],
    [$type_param, "\\\\fI\$1\\\\fP"],
    [$type_param_ref, "\\\\fI\$1\$2\\\\fP"],
    [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
    [$type_fallback, "\\\\fI\$1\\\\fP"]
  );
my $blankline_man = "";

# rst-mode
my @highlights_rst = (
    [$type_constant, "``\$1``"],
    [$type_constant2, "``\$1``"],

    # Note: need to escape () to avoid func matching later
    [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\$\\\$ <\$1>`"],
    [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
    [$type_fp_param, "**\$1\\\$\\\$**"],
    [$type_fp_param2, "**\$1\\\$\\\$**"],
    [$type_func, "\$1()"],
    [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
    [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
    [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
    [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],

    # in rst this can refer to any type
    [$type_fallback, "\\:c\\:type\\:`\$1`"],
    [$type_param_ref, "**\$1\$2**"]
  );
my $blankline_rst = "\n";

# read arguments
if ($#ARGV == -1) {
    pod2usage(
        -message => "No arguments!\n",
        -exitval => 1,
        -verbose => 99,
        -sections => 'SYNOPSIS',
        -output => \*STDERR,
      );
}

my $kernelversion;

my $dohighlight = "";

my $verbose = 0;
my $Werror = 0;
my $Wreturn = 0;
my $Wshort_desc = 0;
my $output_mode = "rst";
my $output_preformatted = 0;
my $no_doc_sections = 0;
my $enable_lineno = 0;
my @highlights = @highlights_rst;
my $blankline = $blankline_rst;
my $modulename = "Kernel API";

use constant {
    OUTPUT_ALL          => 0, # output all symbols and doc sections
    OUTPUT_INCLUDE      => 1, # output only specified symbols
    OUTPUT_EXPORTED     => 2, # output exported symbols
    OUTPUT_INTERNAL     => 3, # output non-exported symbols
};
my $output_selection = OUTPUT_ALL;
my $show_not_found = 0; # No longer used

my @export_file_list;

my @build_time;
if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
    (my $seconds = `date -d "${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
    @build_time = gmtime($seconds);
} else {
    @build_time = localtime;
}

my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
                'July', 'August', 'September', 'October',
                'November', 'December')[$build_time[4]] .
    " " . ($build_time[5]+1900);

# Essentially these are globals.
# 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
# could cause "use of undefined value" or other bugs.
my ($function, %function_table, %parametertypes, $declaration_purpose);
my %nosymbol_table = ();
my $declaration_start_line;
my ($type, $declaration_name, $return_type);
my ($newsection, $newcontents, $prototype, $brcount);

if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1') {
    $verbose = 1;
}

if (defined($ENV{'KCFLAGS'})) {
    my $kcflags = "$ENV{'KCFLAGS'}";

    if ($kcflags =~ /(\s|^)-Werror(\s|$)/) {
        $Werror = 1;
    }
}

# reading this variable is for backwards compat just in case
# someone was calling it with the variable from outside the
# kernel's build system
if (defined($ENV{'KDOC_WERROR'})) {
    $Werror = "$ENV{'KDOC_WERROR'}";
}
# other environment variables are converted to command-line
# arguments in cmd_checkdoc in the build system

# Generated docbook code is inserted in a template at a point where
# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
# https://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="";

# Parser states
use constant {
    STATE_NORMAL        => 0,        # normal code
    STATE_NAME          => 1,        # looking for function name
    STATE_BODY_MAYBE    => 2,        # body - or maybe more description
    STATE_BODY          => 3,        # the body of the comment
    STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line
    STATE_PROTO         => 5,        # scanning prototype
    STATE_DOCBLOCK      => 6,        # documentation block
    STATE_INLINE        => 7,        # gathering doc outside main block
};
my $state;
my $leading_space;

# Inline documentation state
use constant {
    STATE_INLINE_NA     => 0, # not applicable ($state != STATE_INLINE)
    STATE_INLINE_NAME   => 1, # looking for member name (@foo:)
    STATE_INLINE_TEXT   => 2, # looking for member documentation
    STATE_INLINE_END    => 3, # done
    STATE_INLINE_ERROR  => 4, # error - Comment without header was found.
                              # Spit a warning as it's not
                              # proper kernel-doc and ignore the rest.
};
my $inline_doc_state;

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

# Name of the kernel-doc identifier for non-DOC markups
my $identifier;

my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
my $doc_end = '\*/';
my $doc_com = '\s*\*\s*';
my $doc_com_body = '\s*\* ?';
my $doc_decl = $doc_com . '(\w+)';
# @params and a strictly limited set of supported section names
# Specifically:
#   Match @word:
#   @...:
#         @{section-name}:
# while trying to not match literal block starts like "example::"
#
my $doc_sect = $doc_com .
    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:([^:].*)?$';
my $doc_content = $doc_com_body . '(.*)';
my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$';
my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';
my $doc_inline_end = '^\s*\*/\s*$';
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*$\s*(\w+)\s*$\s*;';
my $export_symbol_ns = '^\s*EXPORT_SYMBOL_NS(_GPL)?\s*$\s*(\w+)\s*,\s*"\S+"$\s*;';
my $function_pointer = qr{([^$]*\(\*)\s*$\s*$([^$]*)\)};
my $attribute = qr{__attribute__\s*$\([a-z0-9,_\*\s\($]*\)\)}i;

my %parameterdescs;
my %parameterdesc_start_lines;
my @parameterlist;
my %sections;
my @sectionlist;
my %section_start_lines;
my $sectcheck;
my $struct_actual;

my $contents = "";
my $new_start_line = 0;

# the canonical section names. see also $doc_sect above.
my $section_default = "Description"; # default section
my $section_intro = "Introduction";
my $section = $section_default;
my $section_context = "Context";
my $section_return = "Return";

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

reset_state();

while ($ARGV[0] =~ m/^--?(.*)/) {
    my $cmd = $1;
    shift @ARGV;
    if ($cmd eq "man") {
        $output_mode = "man";
        @highlights = @highlights_man;
        $blankline = $blankline_man;
    } elsif ($cmd eq "rst") {
        $output_mode = "rst";
        @highlights = @highlights_rst;
        $blankline = $blankline_rst;
    } elsif ($cmd eq "none") {
        $output_mode = "none";
    } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document
        $modulename = shift @ARGV;
    } elsif ($cmd eq "function") { # to only output specific functions
        $output_selection = OUTPUT_INCLUDE;
        $function = shift @ARGV;
        $function_table{$function} = 1;
    } elsif ($cmd eq "nosymbol") { # Exclude specific symbols
        my $symbol = shift @ARGV;
        $nosymbol_table{$symbol} = 1;
    } elsif ($cmd eq "export") { # only exported symbols
        $output_selection = OUTPUT_EXPORTED;
        %function_table = ();
    } elsif ($cmd eq "internal") { # only non-exported symbols
        $output_selection = OUTPUT_INTERNAL;
        %function_table = ();
    } elsif ($cmd eq "export-file") {
        my $file = shift @ARGV;
        push(@export_file_list, $file);
    } elsif ($cmd eq "v") {
        $verbose = 1;
    } elsif ($cmd eq "Werror") {
        $Werror = 1;
    } elsif ($cmd eq "Wreturn") {
        $Wreturn = 1;
    } elsif ($cmd eq "Wshort-desc" or $cmd eq "Wshort-description") {
        $Wshort_desc = 1;
    } elsif ($cmd eq "Wall") {
        $Wreturn = 1;
        $Wshort_desc = 1;
    } elsif (($cmd eq "h") || ($cmd eq "help")) {
        pod2usage(-exitval => 0, -verbose => 2);
    } elsif ($cmd eq 'no-doc-sections') {
        $no_doc_sections = 1;
    } elsif ($cmd eq 'enable-lineno') {
        $enable_lineno = 1;
    } elsif ($cmd eq 'show-not-found') {
        $show_not_found = 1;  # A no-op but don't fail
    } else {
        # Unknown argument
        pod2usage(
            -message => "Argument unknown!\n",
            -exitval => 1,
            -verbose => 99,
            -sections => 'SYNOPSIS',
            -output => \*STDERR,
            );
    }
    if ($#ARGV < 0){
        pod2usage(
            -message => "FILE argument missing\n",
            -exitval => 1,
            -verbose => 99,
            -sections => 'SYNOPSIS',
            -output => \*STDERR,
            );
    }
}

# continue execution near EOF;

sub findprog($)
{
    foreach(split(/:/, $ENV{PATH})) {
        return "$_/$_[0]" if(-x "$_/$_[0]");
    }
}

# get kernel version from env
sub get_kernel_version() {
    my $version = 'unknown kernel version';

    if (defined($ENV{'KERNELVERSION'})) {
        $version = $ENV{'KERNELVERSION'};
    }
    return $version;
}

#
sub print_lineno {
    my $lineno = shift;
    if ($enable_lineno && defined($lineno)) {
        print ".. LINENO " . $lineno . "\n";
    }
}

sub emit_warning {
    my $location = shift;
    my $msg = shift;
    print STDERR "$location: warning: $msg";
    ++$warnings;
}
##
# dumps section contents to arrays/hashes intended for that purpose.
#
sub dump_section {
    my $file = shift;
    my $name = shift;
    my $contents = join "\n", @_;

    if ($name =~ m/$type_param/) {
        $name = $1;
        $parameterdescs{$name} = $contents;
        $sectcheck = $sectcheck . $name . " ";
        $parameterdesc_start_lines{$name} = $new_start_line;
        $new_start_line = 0;
    } elsif ($name eq "@\.\.\.") {
        $name = "...";
        $parameterdescs{$name} = $contents;
        $sectcheck = $sectcheck . $name . " ";
        $parameterdesc_start_lines{$name} = $new_start_line;
        $new_start_line = 0;
    } else {
        if (defined($sections{$name}) && ($sections{$name} ne "")) {
            # Only warn on user specified duplicate section names.
            if ($name ne $section_default) {
                emit_warning("${file}:$.", "duplicate section name '$name'\n");
            }
            $sections{$name} .= $contents;
        } else {
            $sections{$name} = $contents;
            push @sectionlist, $name;
            $section_start_lines{$name} = $new_start_line;
            $new_start_line = 0;
        }
    }
}

##
# dump DOC: section after checking that it should go out
#
sub dump_doc_section {
    my $file = shift;
    my $name = shift;
    my $contents = join "\n", @_;

    if ($no_doc_sections) {
        return;
    }

    return if (defined($nosymbol_table{$name}));

    if (($output_selection == OUTPUT_ALL) ||
        (($output_selection == OUTPUT_INCLUDE) &&
         defined($function_table{$name})))
    {
        dump_section($file, $name, $contents);
        output_blockhead({'sectionlist' => \@sectionlist,
                          'sections' => \%sections,
                          'module' => $modulename,
                          'content-only' => ($output_selection != OUTPUT_ALL), });
    }
}

##
# output function
#
# parameterdescs, a hash.
#  function => "function name"
#  parameterlist => @list of parameters
#  parameterdescs => %parameter descriptions
#  sectionlist => @list of sections
#  sections => %section descriptions
#

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

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

#   print STDERR "contents b4:$contents\n";
    eval $dohighlight;
    die $@ if $@;
#   print STDERR "contents af:$contents\n";

    foreach $line (split "\n", $contents) {
        if (! $output_preformatted) {
            $line =~ s/^\s*//;
        }
        if ($line eq ""){
            if (! $output_preformatted) {
                print $lineprefix, $blankline;
            }
        } else {
            if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
                print "\\&$line";
            } else {
                print $lineprefix, $line;
            }
        }
        print "\n";
    }
}

##
# output function in man
sub output_function_man(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);
    my $count;
    my $func_macro = $args{'func_macro'};
    my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty

    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\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/$function_pointer/) {
            # pointer-to-function
            print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";
        } else {
            $type =~ s/([^\*])$/$1 /;
            print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";
        }
        $count++;
        $parenth = "";
    }

    $paramcount = $#{$args{'parameterlist'}}; # -1 is empty
    if ($paramcount >= 0) {
     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\" LINUX\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\" LINUX\n";

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

    my $declaration = $args{'definition'};
    $declaration =~ s/\t/  /g;
    $declaration =~ s/\n/"\n.br\n.BI \"/g;
    print ".SH SYNOPSIS\n";
    print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";
    print ".BI \"$declaration\n};\n.br\n\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\" LINUX\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\" LINUX\n";

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

##
# output in restructured text
#

#
# This could use some work; it's used to output the DOC: sections, and
# starts by putting out the name of the doc section itself, but that tends
# to duplicate a header already in the template file.
#
sub output_blockhead_rst(%) {
    my %args = %{$_[0]};
    my ($parameter, $section);

    foreach $section (@{$args{'sectionlist'}}) {
        next if (defined($nosymbol_table{$section}));

        if ($output_selection != OUTPUT_INCLUDE) {
            print ".. _$section:\n\n";
            print "**$section**\n\n";
        }
        print_lineno($section_start_lines{$section});
        output_highlight_rst($args{'sections'}{$section});
        print "\n";
    }
}

#
# Apply the RST highlights to a sub-block of text.
#
sub highlight_block($) {
    # The dohighlight kludge requires the text be called $contents
    my $contents = shift;
    eval $dohighlight;
    die $@ if $@;
    return $contents;
}

#
# Regexes used only here.
#
my $sphinx_literal = '^[^.].*::$';
my $sphinx_cblock = '^\.\.\ +code-block::';

sub output_highlight_rst {
    my $input = join "\n",@_;
    my $output = "";
    my $line;
    my $in_literal = 0;
    my $litprefix;
    my $block = "";

    foreach $line (split "\n",$input) {
        #
        # If we're in a literal block, see if we should drop out
        # of it.  Otherwise pass the line straight through unmunged.
        #
        if ($in_literal) {
            if (! ($line =~ /^\s*$/)) {
                #
                # If this is the first non-blank line in a literal
                # block we need to figure out what the proper indent is.
                #
                if ($litprefix eq "") {
                    $line =~ /^(\s*)/;
                    $litprefix = '^' . $1;
                    $output .= $line . "\n";
                } elsif (! ($line =~ /$litprefix/)) {
                    $in_literal = 0;
                } else {
                    $output .= $line . "\n";
                }
            } else {
                $output .= $line . "\n";
            }
        }
        #
        # Not in a literal block (or just dropped out)
        #
        if (! $in_literal) {
            $block .= $line . "\n";
            if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {
                $in_literal = 1;
                $litprefix = "";
                $output .= highlight_block($block);
                $block = ""
            }
        }
    }

    if ($block) {
        $output .= highlight_block($block);
    }

    $output =~ s/^\n+//g;
    $output =~ s/\n+$//g;

    foreach $line (split "\n", $output) {
        print $lineprefix . $line . "\n";
    }
}

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

    my $signature = "";
    my $func_macro = $args{'func_macro'};
    my $paramcount = $#{$args{'parameterlist'}}; # -1 is empty

if ($func_macro) {
        $signature = $args{'function'};
} else {
  if ($args{'functiontype'}) {
         $signature = $args{'functiontype'} . " ";
  }
  $signature .= $args{'function'} . " (";
    }

    my $count = 0;
    foreach my $parameter (@{$args{'parameterlist'}}) {
        if ($count ne 0) {
            $signature .= ", ";
        }
        $count++;
        $type = $args{'parametertypes'}{$parameter};

        if ($type =~ m/$function_pointer/) {
            # pointer-to-function
            $signature .= $1 . $parameter . ") (" . $2 . ")";
        } else {
            $signature .= $type;
        }
    }

    if (!$func_macro) {
     $signature .= ")";
    }

    if ($args{'typedef'} || $args{'functiontype'} eq "") {
        print ".. c:macro:: ". $args{'function'} . "\n\n";

        if ($args{'typedef'}) {
            print_lineno($declaration_start_line);
            print " **Typedef**: ";
            $lineprefix = "";
            output_highlight_rst($args{'purpose'});
            print "\n\n**Syntax**\n\n";
            print " ``$signature``\n\n";
        } else {
            print "``$signature``\n\n";
        }
    } else {
        print ".. c:function:: $signature\n\n";
    }

    if (!$args{'typedef'}) {
        print_lineno($declaration_start_line);
        $lineprefix = " ";
        output_highlight_rst($args{'purpose'});
        print "\n";
    }

    #
    # Put our descriptive text into a container (thus an HTML <div>) to help
    # set the function prototypes apart.
    #
    $lineprefix = " ";
if ($paramcount >= 0) {
     print ".. container:: kernelindent\n\n";
     print $lineprefix . "**Parameters**\n\n";
    }
    foreach $parameter (@{$args{'parameterlist'}}) {
        my $parameter_name = $parameter;
        $parameter_name =~ s/\[.*//;
        $type = $args{'parametertypes'}{$parameter};

        if ($type ne "") {
            print $lineprefix . "``$type``\n";
        } else {
            print $lineprefix . "``$parameter``\n";
        }

        print_lineno($parameterdesc_start_lines{$parameter_name});

        $lineprefix = " ";
        if (defined($args{'parameterdescs'}{$parameter_name}) &&
            $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
            output_highlight_rst($args{'parameterdescs'}{$parameter_name});
        } else {
            print $lineprefix . "*undescribed*\n";
        }
        $lineprefix = " ";
        print "\n";
    }

    output_section_rst(@_);
    $lineprefix = $oldprefix;
}

sub output_section_rst(%) {
    my %args = %{$_[0]};
    my $section;
    my $oldprefix = $lineprefix;

    foreach $section (@{$args{'sectionlist'}}) {
        print $lineprefix . "**$section**\n\n";
        print_lineno($section_start_lines{$section});
        output_highlight_rst($args{'sections'}{$section});
        print "\n";
    }
    print "\n";
}

sub output_enum_rst(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $oldprefix = $lineprefix;
    my $count;
    my $outer;

    my $name = $args{'enum'};
    print "\n\n.. c:enum:: " . $name . "\n\n";

    print_lineno($declaration_start_line);
    $lineprefix = " ";
    output_highlight_rst($args{'purpose'});
    print "\n";

    print ".. container:: kernelindent\n\n";
    $outer = $lineprefix . " ";
    $lineprefix = $outer . " ";
    print $outer . "**Constants**\n\n";
    foreach $parameter (@{$args{'parameterlist'}}) {
        print $outer . "``$parameter``\n";

        if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
            output_highlight_rst($args{'parameterdescs'}{$parameter});
        } else {
            print $lineprefix . "*undescribed*\n";
        }
        print "\n";
    }
    print "\n";
    $lineprefix = $oldprefix;
    output_section_rst(@_);
}

sub output_typedef_rst(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $oldprefix = $lineprefix;
    my $name;

    $name = $args{'typedef'};

    print "\n\n.. c:type:: " . $name . "\n\n";
    print_lineno($declaration_start_line);
    $lineprefix = " ";
    output_highlight_rst($args{'purpose'});
    print "\n";

    $lineprefix = $oldprefix;
    output_section_rst(@_);
}

sub output_struct_rst(%) {
    my %args = %{$_[0]};
    my ($parameter);
    my $oldprefix = $lineprefix;

    my $name = $args{'struct'};
    if ($args{'type'} eq 'union') {
        print "\n\n.. c:union:: " . $name . "\n\n";
    } else {
        print "\n\n.. c:struct:: " . $name . "\n\n";
    }

    print_lineno($declaration_start_line);
    $lineprefix = " ";
    output_highlight_rst($args{'purpose'});
    print "\n";

    print ".. container:: kernelindent\n\n";
    print $lineprefix . "**Definition**::\n\n";
    my $declaration = $args{'definition'};
    $lineprefix = $lineprefix . " ";
    $declaration =~ s/\t/$lineprefix/g;
    print $lineprefix . $args{'type'} . " " . $args{'struct'} . " {\n$declaration" . $lineprefix . "};\n\n";

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

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

        ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
        $type = $args{'parametertypes'}{$parameter};
        print_lineno($parameterdesc_start_lines{$parameter_name});
        print $lineprefix . "``" . $parameter . "``\n";
        $lineprefix = " ";
        output_highlight_rst($args{'parameterdescs'}{$parameter_name});
        $lineprefix = " ";
        print "\n";
    }
    print "\n";

    $lineprefix = $oldprefix;
    output_section_rst(@_);
}

## none mode output functions

sub output_function_none(%) {
}

sub output_enum_none(%) {
}

sub output_typedef_none(%) {
}

sub output_struct_none(%) {
}

sub output_blockhead_none(%) {
}

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

    return if (defined($nosymbol_table{$name}));

    if (($output_selection == OUTPUT_ALL) ||
        (($output_selection == OUTPUT_INCLUDE ||
          $output_selection == OUTPUT_EXPORTED) &&
         defined($function_table{$name})) ||
        ($output_selection == OUTPUT_INTERNAL &&
         !($functype eq "function" && 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 $decl_type;
    my $members;
    my $type = qr{struct|union};
    # For capturing struct/union definition body, i.e. "{members*}qualifiers*"
    my $qualifiers = qr{$attribute|__packed|__aligned|____cacheline_aligned_in_smp|____cacheline_aligned};
    my $definition_body = qr{\{(.*)\}\s*$qualifiers*};
    my $struct_members = qr{($type)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;};

    if ($x =~ /($type)\s+(\w+)\s*$definition_body/) {
        $decl_type = $1;
        $declaration_name = $2;
        $members = $3;
    } elsif ($x =~ /typedef\s+($type)\s*$definition_body\s*(\w+)\s*;/) {
        $decl_type = $1;
        $declaration_name = $3;
        $members = $2;
    }

    if ($members) {
        if ($identifier ne $declaration_name) {
            emit_warning("${file}:$.", "expecting prototype for $decl_type $identifier. Prototype was for $decl_type $declaration_name instead\n");
            return;
        }

        # ignore members marked private:
        $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
        $members =~ s/\/\*\s*private:.*//gosi;
        # strip comments:
        $members =~ s/\/\*.*?\*\///gos;
        # strip attributes
        $members =~ s/\s*$attribute/ /gi;
        $members =~ s/\s*__aligned\s*$[^;]*$/ /gos;
        $members =~ s/\s*__counted_by\s*$[^;]*$/ /gos;
        $members =~ s/\s*__counted_by_(le|be)\s*$[^;]*$/ /gos;
        $members =~ s/\s*__packed\s*/ /gos;
        $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos;
        $members =~ s/\s*____cacheline_aligned_in_smp/ /gos;
        $members =~ s/\s*____cacheline_aligned/ /gos;
        # unwrap struct_group():
        # - first eat non-declaration parameters and rewrite for final match
        # - then remove macro, outer parens, and trailing semicolon
        $members =~ s/\bstruct_group\s*$([^,]*,)/STRUCT_GROUP(/gos;
        $members =~ s/\bstruct_group_attr\s*\(([^,]*,){2}/STRUCT_GROUP(/gos;
        $members =~ s/\bstruct_group_tagged\s*\(([^,]*),([^,]*),/struct $1 $2; STRUCT_GROUP(/gos;
        $members =~ s/\b__struct_group\s*\(([^,]*,){3}/STRUCT_GROUP(/gos;
        $members =~ s/\bSTRUCT_GROUP(\(((?:(?>[^)(]+)|(?1))*)$)[^;]*;/$2/gos;

        my $args = qr{([^,)]+)};
        # replace DECLARE_BITMAP
        $members =~ s/__ETHTOOL_DECLARE_LINK_MODE_MASK\s*$([^$]+)\)/DECLARE_BITMAP($1, __ETHTOOL_LINK_MODE_MASK_NBITS)/gos;
        $members =~ s/DECLARE_PHY_INTERFACE_MASK\s*$([^$]+)\)/DECLARE_BITMAP($1, PHY_INTERFACE_MODE_MAX)/gos;
        $members =~ s/DECLARE_BITMAP\s*$$args,\s*$args$/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
        # replace DECLARE_HASHTABLE
        $members =~ s/DECLARE_HASHTABLE\s*$$args,\s*$args$/unsigned long $1\[1 << (($2) - 1)\]/gos;
        # replace DECLARE_KFIFO
        $members =~ s/DECLARE_KFIFO\s*$$args,\s*$args,\s*$args$/$2 \*$1/gos;
        # replace DECLARE_KFIFO_PTR
        $members =~ s/DECLARE_KFIFO_PTR\s*$$args,\s*$args$/$2 \*$1/gos;
        # replace DECLARE_FLEX_ARRAY
        $members =~ s/(?:__)?DECLARE_FLEX_ARRAY\s*$$args,\s*$args$/$1 $2\[\]/gos;
        #replace DEFINE_DMA_UNMAP_ADDR
        $members =~ s/DEFINE_DMA_UNMAP_ADDR\s*$$args$/dma_addr_t $1/gos;
        #replace DEFINE_DMA_UNMAP_LEN
        $members =~ s/DEFINE_DMA_UNMAP_LEN\s*$$args$/__u32 $1/gos;
        my $declaration = $members;

        # Split nested struct/union elements as newer ones
        while ($members =~ m/$struct_members/) {
            my $newmember;
            my $maintype = $1;
            my $ids = $4;
            my $content = $3;
            foreach my $id(split /,/, $ids) {
                $newmember .= "$maintype $id; ";

                $id =~ s/[:\[].*//;
                $id =~ s/^\s*\**(\S+)\s*/$1/;
                foreach my $arg (split /;/, $content) {
                    next if ($arg =~ m/^\s*$/);
                    if ($arg =~ m/^([^$]+\(\*?\s*)([\w\.]*)(\s*$.*)/) {
                        # pointer-to-function
                        my $type = $1;
                        my $name = $2;
                        my $extra = $3;
                        next if (!$name);
                        if ($id =~ m/^\s*$/) {
                            # anonymous struct/union
                            $newmember .= "$type$name$extra; ";
                        } else {
                            $newmember .= "$type$id.$name$extra; ";
                        }
                    } else {
                        my $type;
                        my $names;
                        $arg =~ s/^\s+//;
                        $arg =~ s/\s+$//;
                        # Handle bitmaps
                        $arg =~ s/:\s*\d+\s*//g;
                        # Handle arrays
                        $arg =~ s/\[.*\]//g;
                        # The type may have multiple words,
                        # and multiple IDs can be defined, like:
                        #    const struct foo, *bar, foobar
                        # So, we remove spaces when parsing the
                        # names, in order to match just names
                        # and commas for the names
                        $arg =~ s/\s*,\s*/,/g;
                        if ($arg =~ m/(.*)\s+([\S+,]+)/) {
                            $type = $1;
                            $names = $2;
                        } else {
                            $newmember .= "$arg; ";
                            next;
                        }
                        foreach my $name (split /,/, $names) {
                            $name =~ s/^\s*\**(\S+)\s*/$1/;
                            next if (($name =~ m/^\s*$/));
                            if ($id =~ m/^\s*$/) {
                                # anonymous struct/union
                                $newmember .= "$type $name; ";
                            } else {
                                $newmember .= "$type $id.$name; ";
                            }
                        }
                    }
                }
            }
            $members =~ s/$struct_members/$newmember/;
        }

        # Ignore other nested elements, like enums
        $members =~ s/(\{[^\{\}]*\})//g;

        create_parameterlist($members, ';', $file, $declaration_name);
        check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual);

        # Adjust declaration for better display
        $declaration =~ s/([\{;])/$1\n/g;
        $declaration =~ s/\}\s+;/};/g;
        # Better handle inlined enums
        do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/);

        my @def_args = split /\n/, $declaration;
        my $level = 1;
        $declaration = "";
        foreach my $clause (@def_args) {
            $clause =~ s/^\s+//;
            $clause =~ s/\s+$//;
            $clause =~ s/\s+/ /;
            next if (!$clause);
            $level-- if ($clause =~ m/(\})/ && $level > 1);
            if (!($clause =~ m/^\s*#/)) {
                $declaration .= "\t" x $level;
            }
            $declaration .= "\t" . $clause . "\n";
            $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/));
        }
        output_declaration($declaration_name,
                   'struct',
                   {'struct' => $declaration_name,
                    'module' => $modulename,
                    'definition' => $declaration,
                    'parameterlist' => \@parameterlist,
                    'parameterdescs' => \%parameterdescs,
                    'parametertypes' => \%parametertypes,
                    'sectionlist' => \@sectionlist,
                    'sections' => \%sections,
                    'purpose' => $declaration_purpose,
                    'type' => $decl_type
                   });
    } else {
        print STDERR "${file}:$.: error: Cannot parse struct or union!\n";
        ++$errors;
    }
}

sub show_warnings($$) {
    my $functype = shift;
    my $name = shift;

    return 0 if (defined($nosymbol_table{$name}));

    return 1 if ($output_selection == OUTPUT_ALL);

    if ($output_selection == OUTPUT_EXPORTED) {
        if (defined($function_table{$name})) {
            return 1;
        } else {
            return 0;
        }
    }
    if ($output_selection == OUTPUT_INTERNAL) {
        if (!($functype eq "function" && defined($function_table{$name}))) {
            return 1;
        } else {
            return 0;
        }
    }
    if ($output_selection == OUTPUT_INCLUDE) {
        if (defined($function_table{$name})) {
            return 1;
        } else {
            return 0;
        }
    }
    die("Please add the new output type at show_warnings()");
}

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

    # ignore members marked private:
    $x =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi;
    $x =~ s/\/\*\s*private:.*}/}/gosi;

    $x =~ s@/\*.*?\*/@@gos; # strip comments.
    # strip #define macros inside enums
    $x =~ s@#\s*((define|ifdef|if)\s+|endif)[^;]*;@@gos;

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

    if ($members) {
        if ($identifier ne $declaration_name) {
            if ($identifier eq "") {
                emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n");
            } else {
                emit_warning("${file}:$.", "expecting prototype for enum $identifier. Prototype was for enum $declaration_name instead\n");
            }
            return;
        }
        $declaration_name = "(anonymous)" if ($declaration_name eq "");

        my %_members;

        $members =~ s/\s+$//;
        $members =~ s/$[^;]*?[$]//g;

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

        while (my ($k, $v) = each %parameterdescs) {
            if (!exists($_members{$k})) {
                if (show_warnings("enum", $declaration_name)) {
                    emit_warning("${file}:$.", "Excess enum value '$k' description in '$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 "${file}:$.: error: Cannot parse enum!\n";
        ++$errors;
    }
}

my $typedef_type = qr { ((?:\s+[\w\*]+\b){0,7}\s+(?:\w+\b|\*+))\s* }x;
my $typedef_ident = qr { \*?\s*(\w\S+)\s* }x;
my $typedef_args = qr { \s*$(.*)$; }x;

my $typedef1 = qr { typedef$typedef_type$$typedef_ident$$typedef_args }x;
my $typedef2 = qr { typedef$typedef_type$typedef_ident$typedef_args }x;

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

    $x =~ s@/\*.*?\*/@@gos; # strip comments.

    # Parse function typedef prototypes
    if ($x =~ $typedef1 || $x =~ $typedef2) {
        $return_type = $1;
        $declaration_name = $2;
        my $args = $3;
        $return_type =~ s/^\s+//;

        if ($identifier ne $declaration_name) {
            emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
            return;
        }

        create_parameterlist($args, ',', $file, $declaration_name);

        output_declaration($declaration_name,
                           'function',
                           {'function' => $declaration_name,
                            'typedef' => 1,
                            'module' => $modulename,
                            'functiontype' => $return_type,
                            'parameterlist' => \@parameterlist,
                            'parameterdescs' => \%parameterdescs,
                            'parametertypes' => \%parametertypes,
                            'sectionlist' => \@sectionlist,
                            'sections' => \%sections,
                            'purpose' => $declaration_purpose
                           });
        return;
    }

    while (($x =~ /$*.$\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
        $x =~ s/$*.$\s*;$/;/;
        $x =~ s/\[*.\]\s*;$/;/;
    }

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

        if ($identifier ne $declaration_name) {
            emit_warning("${file}:$.", "expecting prototype for typedef $identifier. Prototype was for typedef $declaration_name instead\n");
            return;
        }

        output_declaration($declaration_name,
                           'typedef',
                           {'typedef' => $declaration_name,
                            'module' => $modulename,
                            'sectionlist' => \@sectionlist,
                            'sections' => \%sections,
                            'purpose' => $declaration_purpose
                           });
    } else {
        print STDERR "${file}:$.: error: 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 $declaration_name = shift;
    my $type;
    my $param;

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

    foreach my $arg (split($splitter, $args)) {
        # strip comments
        $arg =~ s/\/\*.*\*\///;
        # ignore argument attributes
        $arg =~ s/\sPOS0?\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, $arg, $file, $declaration_name);
        } elsif ($arg =~ m/\(.+$\s*\[/) {
            # array-of-pointers
            $arg =~ tr/#/,/;
            $arg =~ m/[^$]+\(\s*\*\s*([\w\[\]\.]*?)\s*(\s*\[\s*[\w]+\s*\]\s*)*$/;
            $param = $1;
            $type = $arg;
            $type =~ s/([^\(]+\(\*?)\s*$param/$1/;
            save_struct_actual($param);
            push_parameter($param, $type, $arg, $file, $declaration_name);
        } 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", $arg, $file, $declaration_name);
                } elsif ($param =~ m/(.*?):(\w+)/) {
                    if ($type ne "") { # skip unnamed bit-fields
                        save_struct_actual($1);
                        push_parameter($1, "$type:$2", $arg, $file, $declaration_name)
                    }
                } else {
                    save_struct_actual($param);
                    push_parameter($param, $type, $arg, $file, $declaration_name);
                }
            }
        }
    }
}

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

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

    $anon_struct_union = 0;
    $param =~ s/[\[\)].*//;

    if ($type eq "" && $param =~ /\.\.\.$/)
    {
        if (!$param =~ /\w\.\.\.$/) {
            # handles unnamed variable parameters
            $param = "...";
        } elsif ($param =~ /\w\.\.\.$/) {
            # for named variable parameters of the form `x...`, remove the dots
            $param =~ s/\.\.\.$//;
        }
        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;
    }
    elsif ($param =~ "__cacheline_group" )
    # handle cache group enforcing variables: they do not need be described in header files
    {
        return; # ignore __cacheline_group_begin and __cacheline_group_end
    }

    # warn if parameter has no description
    # (but ignore ones starting with # as these are not parameters
    # but inline preprocessor statements);
    # Note: It will also ignore void params and unnamed structs/unions
    if (!defined $parameterdescs{$param} && $param !~ /^#/) {
        $parameterdescs{$param} = $undescribed;

        if (show_warnings($type, $declaration_name) && $param !~ /\./) {
            emit_warning("${file}:$.", "Function parameter or struct member '$param' not described in '$declaration_name'\n");
        }
    }

    # 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;
    $org_arg =~ s/\s\s+/ /g;
    $parametertypes{$param} = $org_arg;
}

sub check_sections($$$$$) {
    my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_;
    my @sects = split ' ', $sectcheck;
    my @prms = split ' ', $prmscheck;
    my $err;
    my ($px, $sx);
    my $prm_clean;        # strip trailing "[array size]" and/or beginning "*"

    foreach $sx (0 .. $#sects) {
        $err = 1;
        foreach $px (0 .. $#prms) {
            $prm_clean = $prms[$px];
            $prm_clean =~ s/\[.*\]//;
            $prm_clean =~ s/$attribute//i;
            # 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/\[.*//;

            ##$prm_clean =~ s/^\**//;
            if ($prm_clean eq $sects[$sx]) {
                $err = 0;
                last;
            }
        }
        if ($err) {
            if ($decl_type eq "function") {
                emit_warning("${file}:$.",
                    "Excess function parameter " .
                    "'$sects[$sx]' " .
                    "description in '$decl_name'\n");
            } elsif (($decl_type eq "struct") or
                          ($decl_type eq "union")) {
                emit_warning("${file}:$.",
                    "Excess $decl_type member " .
                    "'$sects[$sx]' " .
                    "description in '$decl_name'\n");
            }
        }
    }
}

##
# Checks the section describing the return value of a function.
sub check_return_section {
    my $file = shift;
    my $declaration_name = shift;
    my $return_type = shift;

    # Ignore an empty return type (It's a macro)
    # Ignore functions with a "void" return type. (But don't ignore "void *")
    if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) {
        return;
    }

    if (!defined($sections{$section_return}) ||
        $sections{$section_return} eq "")
    {
        emit_warning("${file}:$.",
                     "No description found for return value of " .
                     "'$declaration_name'\n");
    }
}

##
# 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;
    my $func_macro = 0;

    print_lineno($new_start_line);

    $prototype =~ s/^static +//;
    $prototype =~ s/^extern +//;
    $prototype =~ s/^asmlinkage +//;
    $prototype =~ s/^inline +//;
    $prototype =~ s/^__inline__ +//;
    $prototype =~ s/^__inline +//;
    $prototype =~ s/^__always_inline +//;
    $prototype =~ s/^noinline +//;
    $prototype =~ s/^__FORTIFY_INLINE +//;
    $prototype =~ s/__init +//;
    $prototype =~ s/__init_or_module +//;
    $prototype =~ s/__deprecated +//;
    $prototype =~ s/__flatten +//;
    $prototype =~ s/__meminit +//;
    $prototype =~ s/__must_check +//;
    $prototype =~ s/__weak +//;
    $prototype =~ s/__sched +//;
    $prototype =~ s/_noprof//;
    $prototype =~ s/__printf\s*$\s*\d*\s*,\s*\d*\s*$ +//;
    $prototype =~ s/__(?:re)?alloc_size\s*$\s*\d+\s*(?:,\s*\d+\s*)?$ +//;
    $prototype =~ s/__diagnose_as\s*$\s*\S+\s*(?:,\s*\d+\s*)*$ +//;
    $prototype =~ s/DECL_BUCKET_PARAMS\s*$\s*(\S+)\s*,\s*(\S+)\s*$/$1, $2/;
    my $define = $prototype =~ s/^#\s*define\s+//; #ak added
    $prototype =~ s/__attribute_const__ +//;
    $prototype =~ s/__attribute__\s*$\(
            (?:
                 [\w\s]++          # attribute name
                 (?:\([^)]*+$)?   # attribute arguments
                 \s*+,?            # optional comma at the end
            )+
          \)\)\s+//x;

    # 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)
    # - pci_match_device, __copy_to_user (long return type)
    my $name = qr{[a-zA-Z0-9_~:]+};
    my $prototype_end1 = qr{[^$]*};
    my $prototype_end2 = qr{[^\{]*};
    my $prototype_end = qr{\(($prototype_end1|$prototype_end2)$};
    my $type1 = qr{[\w\s]+};
    my $type2 = qr{$type1\*+};

    if ($define && $prototype =~ m/^()($name)\s+/) {
        # This is an object-like macro, it has no return type and no parameter
        # list.
        # Function-like macros are not allowed to have spaces between
        # declaration_name and opening parenthesis (notice the \s+).
        $return_type = $1;
        $declaration_name = $2;
        $func_macro = 1;
    } elsif ($prototype =~ m/^()($name)\s*$prototype_end/ ||
        $prototype =~ m/^($type1)\s+($name)\s*$prototype_end/ ||
        $prototype =~ m/^($type2+)\s*($name)\s*$prototype_end/)  {
        $return_type = $1;
        $declaration_name = $2;
        my $args = $3;

        create_parameterlist($args, ',', $file, $declaration_name);
    } else {
        emit_warning("${file}:$.", "cannot understand function prototype: '$prototype'\n");
        return;
    }

    if ($identifier ne $declaration_name) {
        emit_warning("${file}:$.", "expecting prototype for $identifier(). Prototype was for $declaration_name() instead\n");
        return;
    }

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

    # This check emits a lot of warnings at the moment, because many
    # functions don't have a 'Return' doc section. So until the number
    # of warnings goes sufficiently down, the check is only performed in
    # -Wreturn mode.
    # TODO: always perform the check.
    if ($Wreturn && !$func_macro) {
        check_return_section($file, $declaration_name, $return_type);
    }

    # The function parser can be called with a typedef parameter.
    # Handle it.
    if ($return_type =~ /typedef/) {
        output_declaration($declaration_name,
                           'function',
                           {'function' => $declaration_name,
                            'typedef' => 1,
                            'module' => $modulename,
                            'functiontype' => $return_type,
                            'parameterlist' => \@parameterlist,
                            'parameterdescs' => \%parameterdescs,
                            'parametertypes' => \%parametertypes,
                            'sectionlist' => \@sectionlist,
                            'sections' => \%sections,
                            'purpose' => $declaration_purpose,
       'func_macro' => $func_macro
                           });
    } else {
        output_declaration($declaration_name,
                           'function',
                           {'function' => $declaration_name,
                            'module' => $modulename,
                            'functiontype' => $return_type,
                            'parameterlist' => \@parameterlist,
                            'parameterdescs' => \%parameterdescs,
                            'parametertypes' => \%parametertypes,
                            'sectionlist' => \@sectionlist,
                            'sections' => \%sections,
                            'purpose' => $declaration_purpose,
       'func_macro' => $func_macro
                           });
    }
}

sub reset_state {
    $function = "";
    %parameterdescs = ();
    %parametertypes = ();
    @parameterlist = ();
    %sections = ();
    @sectionlist = ();
    $sectcheck = "";
    $struct_actual = "";
    $prototype = "";

    $state = STATE_NORMAL;
    $inline_doc_state = STATE_INLINE_NA;
}

sub tracepoint_munge($) {
    my $file = shift;
    my $tracepointname = 0;
    my $tracepointargs = 0;

    if ($prototype =~ m/TRACE_EVENT$(.*?),/) {
        $tracepointname = $1;
    }
    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\((.*?)$/) {
        $tracepointargs = $1;
    }
    if (($tracepointname eq 0) || ($tracepointargs eq 0)) {
        emit_warning("${file}:$.", "Unrecognized tracepoint format: \n".
                 "$prototype\n");
    } else {
        $prototype = "static inline void trace_$tracepointname($tracepointargs)";
        $identifier = "trace_$identifier";
    }
}

sub syscall_munge() {
    my $void = 0;

    $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's
##    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) = ' ';
            }
        }
    }
}

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

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

    if ($x =~ /^#/ && $x !~ /^#\s*define/) {
        # do nothing
    } elsif ($x =~ /([^\{]*)/) {
        $prototype .= $1;
    }

    if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) {
        $prototype =~ s@/\*.*?\*/@@gos;        # strip comments.
        $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
        $prototype =~ s@^\s+@@gos; # strip leading spaces

        # Handle prototypes for function pointers like:
        # int (*pcs_config)(struct foo)
        $prototype =~ s@^(\S+\s+)$\s*\*(\S+)$@$1$2@gos;

        if ($prototype =~ /SYSCALL_DEFINE/) {
            syscall_munge();
        }
        if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ ||
            $prototype =~ /DEFINE_SINGLE_EVENT/)
        {
            tracepoint_munge($file);
        }
        dump_function($prototype, $file);
        reset_state();
    }
}

sub process_proto_type($$) {
    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
    $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line

    if ($x =~ /^#/) {
        # To distinguish preprocessor directive from regular declaration later.
        $x .= ";";
    }

    while (1) {
        if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) {
            if( length $prototype ) {
                $prototype .= " "
            }
            $prototype .= $1 . $2;
            ($2 eq '{') && $brcount++;
            ($2 eq '}') && $brcount--;
            if (($2 eq ';') && ($brcount == 0)) {
                dump_declaration($prototype, $file);
                reset_state();
                last;
            }
            $x = $3;
        } else {
            $prototype .= $x;
            last;
        }
    }
}

sub map_filename($) {
    my $file;
    my ($orig_file) = @_;

    if (defined($ENV{'SRCTREE'})) {
        $file = "$ENV{'SRCTREE'}" . "/" . $orig_file;
    } else {
        $file = $orig_file;
    }

    return $file;
}

sub process_export_file($) {
    my ($orig_file) = @_;
    my $file = map_filename($orig_file);

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

    while (<IN>) {
        if (/$export_symbol/) {
            next if (defined($nosymbol_table{$2}));
            $function_table{$2} = 1;
        }
        if (/$export_symbol_ns/) {
            next if (defined($nosymbol_table{$2}));
            $function_table{$2} = 1;
        }
    }

    close(IN);
}

#
# Parsers for the various processing states.
#
# STATE_NORMAL: looking for the /** to begin everything.
#
sub process_normal() {
    if (/$doc_start/o) {
        $state = STATE_NAME;        # next line is always the function name
        $declaration_start_line = $. + 1;
    }
}

#
# STATE_NAME: Looking for the "name - description" line
#
sub process_name($$) {
    my $file = shift;
    my $descr;

    if (/$doc_block/o) {
        $state = STATE_DOCBLOCK;
        $contents = "";
        $new_start_line = $.;

        if ( $1 eq "" ) {
            $section = $section_intro;
        } else {
            $section = $1;
        }
    } elsif (/$doc_decl/o) {
        $identifier = $1;
        my $is_kernel_comment = 0;
        my $decl_start = qr{$doc_com};
        # test for pointer declaration type, foo * bar() - desc
        my $fn_type = qr{\w+\s*\*\s*};
        my $parenthesis = qr{$\w*$};
        my $decl_end = qr{[-:].*};
        if (/^$decl_start([\w\s]+?)$parenthesis?\s*$decl_end?$/) {
            $identifier = $1;
        }
        if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
            $decl_type = $1;
            $identifier = $2;
            $is_kernel_comment = 1;
        }
        # Look for foo() or static void foo() - description; or misspelt
        # identifier
        elsif (/^$decl_start$fn_type?(\w+)\s*$parenthesis?\s*$decl_end?$/ ||
            /^$decl_start$fn_type?(\w+[^-:]*)$parenthesis?\s*$decl_end$/) {
            $identifier = $1;
            $decl_type = 'function';
            $identifier =~ s/^define\s+//;
            $is_kernel_comment = 1;
        }
        $identifier =~ s/\s+$//;

        $state = STATE_BODY;
        # if there's no @param blocks need to set up default section
        # here
        $contents = "";
        $section = $section_default;
        $new_start_line = $. + 1;
        if (/[-:](.*)/) {
            # strip leading/trailing/multiple spaces
            $descr= $1;
            $descr =~ s/^\s*//;
            $descr =~ s/\s*$//;
            $descr =~ s/\s+/ /g;
            $declaration_purpose = $descr;
            $state = STATE_BODY_MAYBE;
        } else {
            $declaration_purpose = "";
        }

        if (!$is_kernel_comment) {
            emit_warning("${file}:$.", "This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n$_");
            $state = STATE_NORMAL;
        }

        if (($declaration_purpose eq "") && $Wshort_desc) {
            emit_warning("${file}:$.", "missing initial short description on line:\n$_");
        }

        if ($identifier eq "" && $decl_type ne "enum") {
            emit_warning("${file}:$.", "wrong kernel-doc identifier on line:\n$_");
            $state = STATE_NORMAL;
        }

        if ($verbose) {
            print STDERR "${file}:$.: info: Scanning doc for $decl_type $identifier\n";
        }
--> --------------------

--> maximum size reached

--> --------------------

quality93%

¤ Dauer der Verarbeitung: 0.68 Sekunden (vorverarbeitet) ¤

Wurzel

Suchen

Beweissystem der NASA

Beweissystem Isabelle

NIST Cobol Testsuite

Cephes Mathematical Library

Wiener Entwicklungsmethode

Haftungshinweis

Die Informationen auf dieser Webseite wurden nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit, noch Qualität der bereit gestellten Informationen zugesichert.

Bemerkung:

Die farbliche Syntaxdarstellung ist noch experimentell.