* [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup
@ 2019-05-21 12:25 Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux Peter Maydell
` (11 more replies)
0 siblings, 12 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Hi; this is an RFC patchset which I'm sending out mostly to provide a
work-in-progress snapshot that might be useful for Gabriel's GSoC
project on API documentation generation. You can find the equivalent
git branch here:
https://git.linaro.org/people/peter.maydell/qemu-arm.git/log/?h=sphinx-docs
(git url/branch for cloning:
https://git.linaro.org/people/peter.maydell/qemu-arm.git sphinx-docs )
The patchset starts by pulling in the kernel-doc script from the
kernel sources and wiring it up in our Sphinx config. The version of
the script is just from head-of-kernel-git from when I was working on
this at the beginning of the year; we should probably check whether
we should update it to something newer and/or something from a more
specific kernel release.
The patchset then demonstrates the functionality with two documents:
a standalone file that just has API docs of the functions from
bitops.h, and an extension of the existing memory.rst doc to include
a "detailed API docs" section at the end with the generated docs from
memory.h. In both cases to get the build to not error out we need to
fix up syntax issues in the header comments. For the memory.h stuff
in particular some of the fixes are a bit ropy, and I also ended up
using a big "disable nitpick mode" hammer to shut up an error
(leaving some non-fatal warnings still generated).
Broadly speaking the earlier patches in the series are more
"solid" than the later ones which are a little more hacky.
Some specific notes:
(1) our Makefile rune runs sphinx-build with -n, which enables
"nitpick mode", where sphinx will complain about references that it
wanted to hyperlink but which it doesn't have anywhere te link them
to. This is something that I think I got from the kernel's makefile
rules, and it's obviously nice for catching typos, but sphinx also
complains about references to "uint8_t" and other system types
because obviously there are no definitions of those in our headers.
I have a patch in there which tries to whitelist these, but this may
not be the best approach. (Nitpick mode might also be awkward if we
want to generate docs for API A which uses some types from API B
which we have not yet started generating docs for.)
(2) kernel-doc assumes the kernel C coding style which always uses
explicit 'struct'. This clashes with QEMU's style which usually
hides 'struct' behind typedefs, and seems to result in needing to
write 'struct' in the doc comment to get it recognised as being
documentation of the struct (see eg "memory.h: attempted kernel-doc
fixes") and also failure to recognize that "#MemoryRegion" is a
reference to the MemoryRegion struct type (resulting in errors about
references not being found). I'm not sure exactly what to do here --
it may be some combination of making kernel-doc more flexible in
coping with structs that hide behind typedefs, and fixing up syntax
in our doc comments.
(3) There are definitely some other syntax issues that still need
fixing -- for instance if you look at the generated documentation for
memory_region_init_ram_nomigrate() the "Description" section is just
a sentence fragment, because the doc comment has been misparsed due
to the way the descriptive text following "function() - " is split
over multiple lines. We would need to do a more thorough
proofreading check and fix up the syntax as needed.
(4) Some Sphinx warnings generated are legitimate -- it complains
correctly that we don't have doc comments covering all the fields in
some of the structs in memory.h, for instance. In an ideal world we
would fix these too :-)
thanks
-- PMM
Peter Maydell (10):
scripts/kernel-doc: Import kernel-doc script from Linux
docs: Add kerneldoc sphinx module from Linux
docs/conf.py: Enable use of kerneldoc sphinx extension
docs/conf.py: Ignore some missing references in nitpick mode
bitops.h: Silence kernel-doc complaints
docs: Create bitops.rst as example of kernel-docs
memory.h: Fix kerneldoc syntax issues
docs: Add kernel-doc API documentation to memory.rst
memory.h: attempted kernel-doc fixes
Makefile: disable Sphinx nitpicking
Makefile | 2 +-
include/exec/memory.h | 31 +-
include/qemu/bitops.h | 52 +-
docs/conf.py | 22 +-
docs/devel/bitops.rst | 8 +
docs/devel/index.rst | 1 +
docs/devel/memory.rst | 5 +
docs/sphinx/kerneldoc.py | 150 +++
scripts/kernel-doc | 2223 ++++++++++++++++++++++++++++++++++++++
9 files changed, 2458 insertions(+), 36 deletions(-)
create mode 100644 docs/devel/bitops.rst
create mode 100644 docs/sphinx/kerneldoc.py
create mode 100755 scripts/kernel-doc
--
2.20.1
^ permalink raw reply [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module " Peter Maydell
` (10 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Import the kernel-doc script as of Linux commit 30bac164aca750892b93.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
scripts/kernel-doc | 2223 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 2223 insertions(+)
create mode 100755 scripts/kernel-doc
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
new file mode 100755
index 00000000000..c5333d25198
--- /dev/null
+++ b/scripts/kernel-doc
@@ -0,0 +1,2223 @@
+#!/usr/bin/env perl
+# SPDX-License-Identifier: GPL-2.0
+
+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. ##
+## ##
+## This software falls under the GNU General Public License. ##
+## Please read the COPYING file for more information ##
+
+# 18/01/2001 - Cleanups
+# Functions prototyped as foo(void) same as foo()
+# Stop eval'ing where we don't need to.
+# -- huggie@earth.li
+
+# 27/06/2001 - Allowed whitespace after initial "/**" and
+# allowed comments before function declarations.
+# -- Christian Kreibich <ck@whoop.org>
+
+# Still to do:
+# - add perldoc documentation
+# - Look more closely at some of the scarier bits :)
+
+# 26/05/2001 - Support for separate source and object trees.
+# Return error code.
+# Keith Owens <kaos@ocs.com.au>
+
+# 23/09/2001 - Added support for typedefs, structs, enums and unions
+# Support for Context section; can be terminated using empty line
+# Small fixes (like spaces vs. \s in regex)
+# -- Tim Jansen <tim@tjansen.de>
+
+# 25/07/2012 - Added support for HTML5
+# -- Dan Luedtke <mail@danrl.de>
+
+sub usage {
+ my $message = <<"EOF";
+Usage: $0 [OPTION ...] FILE ...
+
+Read C language source or header FILEs, extract embedded documentation comments,
+and print formatted documentation to standard output.
+
+The documentation comments are identified by "/**" opening comment mark. See
+Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
+
+Output format selection (mutually exclusive):
+ -man Output troff manual page format. This is the default.
+ -rst Output reStructuredText format.
+ -none Do not output documentation, only warnings.
+
+Output selection (mutually exclusive):
+ -export Only output documentation for symbols that have been
+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+ in any input FILE or -export-file FILE.
+ -internal Only output documentation for symbols that have NOT been
+ exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
+ in any input FILE or -export-file FILE.
+ -function NAME Only output documentation for the given function(s)
+ or DOC: section title(s). All other functions and DOC:
+ sections are ignored. May be specified multiple times.
+ -nofunction NAME Do NOT output documentation for the given function(s);
+ only output documentation for the other functions and
+ DOC: sections. May be specified multiple times.
+
+Output selection modifiers:
+ -no-doc-sections Do not output DOC: sections.
+ -enable-lineno Enable output of #define LINENO lines. Only works with
+ reStructuredText format.
+ -export-file FILE Specify an additional FILE in which to look for
+ EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with
+ -export or -internal. May be specified multiple times.
+
+Other parameters:
+ -v Verbose output, more warnings and other information.
+ -h Print this help.
+
+EOF
+ print $message;
+ exit 1;
+}
+
+#
+# format of comments.
+# In the following table, (...)? signifies optional structure.
+# (...)* signifies 0 or more structure elements
+# /**
+# * function_name(:)? (- short description)?
+# (* @parameterx: (description of parameter x)?)*
+# (* a blank line)?
+# * (Description:)? (Description of function)?
+# * (section header: (section description)? )*
+# (*)?*/
+#
+# So .. the trivial example would be:
+#
+# /**
+# * my_function
+# */
+#
+# If the Description: header tag is omitted, then there must be a blank line
+# after the last parameter specification.
+# e.g.
+# /**
+# * my_function - does my stuff
+# * @my_arg: its mine damnit
+# *
+# * Does my stuff explained.
+# */
+#
+# or, could also use:
+# /**
+# * my_function - does my stuff
+# * @my_arg: its mine damnit
+# * Description: Does my stuff explained.
+# */
+# etc.
+#
+# Besides functions you can also write documentation for structs, unions,
+# enums and typedefs. Instead of the function name you must write the name
+# of the declaration; the struct/union/enum/typedef must always precede
+# the name. Nesting of declarations is not supported.
+# Use the argument mechanism to document members or constants.
+# e.g.
+# /**
+# * struct my_struct - short description
+# * @a: first member
+# * @b: second member
+# *
+# * Longer description
+# */
+# struct my_struct {
+# int a;
+# int b;
+# /* private: */
+# int c;
+# };
+#
+# All descriptions can be multiline, except the short function description.
+#
+# For really longs structs, you can also describe arguments inside the
+# body of the struct.
+# eg.
+# /**
+# * struct my_struct - short description
+# * @a: first member
+# * @b: second member
+# *
+# * Longer description
+# */
+# struct my_struct {
+# int a;
+# int b;
+# /**
+# * @c: This is longer description of C
+# *
+# * You can use paragraphs to describe arguments
+# * using this method.
+# */
+# int c;
+# };
+#
+# This should be use only for struct/enum members.
+#
+# You can also add additional sections. When documenting kernel functions you
+# should document the "Context:" of the function, e.g. whether the functions
+# can be called form interrupts. Unlike other sections you can end it with an
+# empty line.
+# A non-void function should have a "Return:" section describing the return
+# value(s).
+# Example-sections should contain the string EXAMPLE so that they are marked
+# appropriately in DocBook.
+#
+# Example:
+# /**
+# * user_function - function that can only be called in user context
+# * @a: some argument
+# * Context: !in_interrupt()
+# *
+# * Some description
+# * Example:
+# * user_function(22);
+# */
+# ...
+#
+#
+# All descriptive text is further processed, scanning for the following special
+# patterns, which are highlighted appropriately.
+#
+# 'funcname()' - function
+# '$ENVVAR' - environmental variable
+# '&struct_name' - name of a structure (up to two words including 'struct')
+# '&struct_name.member' - name of a structure member
+# '@parameter' - name of a parameter
+# '%CONST' - name of a constant.
+# '``LITERAL``' - literal string without any spaces on it.
+
+## 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_fp_param = '\@(\w+)\(\)'; # Special RST handling for 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_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_func, "\\:c\\: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, "**\$1**"]
+ );
+my $blankline_rst = "\n";
+
+# read arguments
+if ($#ARGV == -1) {
+ usage();
+}
+
+my $kernelversion;
+my $dohighlight = "";
+
+my $verbose = 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_EXCLUDE => 2, # output everything except specified symbols
+ OUTPUT_EXPORTED => 3, # output exported symbols
+ OUTPUT_INTERNAL => 4, # output non-exported symbols
+};
+my $output_selection = OUTPUT_ALL;
+my $show_not_found = 0;
+
+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 $declaration_start_line;
+my ($type, $declaration_name, $return_type);
+my ($newsection, $newcontents, $prototype, $brcount, %source_map);
+
+if (defined($ENV{'KBUILD_VERBOSE'})) {
+ $verbose = "$ENV{'KBUILD_VERBOSE'}";
+}
+
+# Generated docbook code is inserted in a template at a point where
+# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
+# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
+# We keep track of number of generated entries and generate a dummy
+# if needs be to ensure the expanded template can be postprocessed
+# into html.
+my $section_counter = 0;
+
+my $lineprefix="";
+
+# 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_PROTO => 4, # scanning prototype
+ STATE_DOCBLOCK => 5, # documentation block
+ STATE_INLINE => 6, # gathering documentation outside main block
+};
+my $state;
+my $in_doc_sect;
+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;
+
+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
+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 %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 "nofunction") { # output all except specific functions
+ $output_selection = OUTPUT_EXCLUDE;
+ $function = shift @ARGV;
+ $function_table{$function} = 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 "h") || ($cmd eq "help")) {
+ usage();
+ } 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;
+ } else {
+ # Unknown argument
+ usage();
+ }
+}
+
+# continue execution near EOF;
+
+# 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 "#define LINENO " . $lineno . "\n";
+ }
+}
+##
+# 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) {
+ print STDERR "${file}:$.: warning: duplicate section name '$name'\n";
+ ++$warnings;
+ }
+ $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;
+ }
+
+ if (($output_selection == OUTPUT_ALL) ||
+ ($output_selection == OUTPUT_INCLUDE &&
+ defined($function_table{$name})) ||
+ ($output_selection == OUTPUT_EXCLUDE &&
+ !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;
+
+ 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/([^\(]*\(\*)\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\" 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'}}) {
+ if ($output_selection != OUTPUT_INCLUDE) {
+ 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);
+ }
+ foreach $line (split "\n", $output) {
+ print $lineprefix . $line . "\n";
+ }
+}
+
+sub output_function_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter, $section);
+ my $oldprefix = $lineprefix;
+ my $start = "";
+
+ if ($args{'typedef'}) {
+ print ".. c:type:: ". $args{'function'} . "\n\n";
+ print_lineno($declaration_start_line);
+ print " **Typedef**: ";
+ $lineprefix = "";
+ output_highlight_rst($args{'purpose'});
+ $start = "\n\n**Syntax**\n\n ``";
+ } else {
+ print ".. c:function:: ";
+ }
+ if ($args{'functiontype'} ne "") {
+ $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
+ } else {
+ $start .= $args{'function'} . " (";
+ }
+ print $start;
+
+ my $count = 0;
+ foreach my $parameter (@{$args{'parameterlist'}}) {
+ if ($count ne 0) {
+ print ", ";
+ }
+ $count++;
+ $type = $args{'parametertypes'}{$parameter};
+
+ if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
+ # pointer-to-function
+ print $1 . $parameter . ") (" . $2;
+ } else {
+ print $type . " " . $parameter;
+ }
+ }
+ if ($args{'typedef'}) {
+ print ");``\n\n";
+ } else {
+ print ")\n\n";
+ print_lineno($declaration_start_line);
+ $lineprefix = " ";
+ output_highlight_rst($args{'purpose'});
+ print "\n";
+ }
+
+ print "**Parameters**\n\n";
+ $lineprefix = " ";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ my $parameter_name = $parameter;
+ $parameter_name =~ s/\[.*//;
+ $type = $args{'parametertypes'}{$parameter};
+
+ if ($type ne "") {
+ print "``$type $parameter``\n";
+ } else {
+ print "``$parameter``\n";
+ }
+
+ print_lineno($parameterdesc_start_lines{$parameter_name});
+
+ if (defined($args{'parameterdescs'}{$parameter_name}) &&
+ $args{'parameterdescs'}{$parameter_name} ne $undescribed) {
+ output_highlight_rst($args{'parameterdescs'}{$parameter_name});
+ } else {
+ print " *undescribed*\n";
+ }
+ print "\n";
+ }
+
+ $lineprefix = $oldprefix;
+ output_section_rst(@_);
+}
+
+sub output_section_rst(%) {
+ my %args = %{$_[0]};
+ my $section;
+ my $oldprefix = $lineprefix;
+ $lineprefix = "";
+
+ foreach $section (@{$args{'sectionlist'}}) {
+ print "**$section**\n\n";
+ print_lineno($section_start_lines{$section});
+ output_highlight_rst($args{'sections'}{$section});
+ print "\n";
+ }
+ print "\n";
+ $lineprefix = $oldprefix;
+}
+
+sub output_enum_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $oldprefix = $lineprefix;
+ my $count;
+ my $name = "enum " . $args{'enum'};
+
+ print "\n\n.. c:type:: " . $name . "\n\n";
+ print_lineno($declaration_start_line);
+ $lineprefix = " ";
+ output_highlight_rst($args{'purpose'});
+ print "\n";
+
+ print "**Constants**\n\n";
+ $lineprefix = " ";
+ foreach $parameter (@{$args{'parameterlist'}}) {
+ print "``$parameter``\n";
+ if ($args{'parameterdescs'}{$parameter} ne $undescribed) {
+ output_highlight_rst($args{'parameterdescs'}{$parameter});
+ } else {
+ print " *undescribed*\n";
+ }
+ print "\n";
+ }
+
+ $lineprefix = $oldprefix;
+ output_section_rst(@_);
+}
+
+sub output_typedef_rst(%) {
+ my %args = %{$_[0]};
+ my ($parameter);
+ my $oldprefix = $lineprefix;
+ my $name = "typedef " . $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{'type'} . " " . $args{'struct'};
+
+ print "\n\n.. c:type:: " . $name . "\n\n";
+ print_lineno($declaration_start_line);
+ $lineprefix = " ";
+ output_highlight_rst($args{'purpose'});
+ print "\n";
+
+ print "**Definition**\n\n";
+ print "::\n\n";
+ my $declaration = $args{'definition'};
+ $declaration =~ s/\t/ /g;
+ print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n";
+
+ print "**Members**\n\n";
+ $lineprefix = " ";
+ 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 "``" . $parameter . "``\n";
+ output_highlight_rst($args{'parameterdescs'}{$parameter_name});
+ 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";
+ if (($output_selection == OUTPUT_ALL) ||
+ (($output_selection == OUTPUT_INCLUDE ||
+ $output_selection == OUTPUT_EXPORTED) &&
+ defined($function_table{$name})) ||
+ (($output_selection == OUTPUT_EXCLUDE ||
+ $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;
+
+ if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) {
+ my $decl_type = $1;
+ $declaration_name = $2;
+ my $members = $3;
+
+ # 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__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi;
+ $members =~ s/\s*__aligned\s*\([^;]*\)//gos;
+ $members =~ s/\s*__packed\s*//gos;
+ $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
+ # replace DECLARE_BITMAP
+ $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos;
+ # replace DECLARE_HASHTABLE
+ $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos;
+ # replace DECLARE_KFIFO
+ $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
+ # replace DECLARE_KFIFO_PTR
+ $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos;
+
+ my $declaration = $members;
+
+ # Split nested struct/union elements as newer ones
+ while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) {
+ 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|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$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 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;
+ }
+ }
+ if ($output_selection == OUTPUT_EXCLUDE) {
+ 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;
+
+ $x =~ s@/\*.*?\*/@@gos; # strip comments.
+ # strip #define macros inside enums
+ $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos;
+
+ if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) {
+ $declaration_name = $1;
+ my $members = $2;
+ my %_members;
+
+ $members =~ s/\s+$//;
+
+ 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)) {
+ print STDERR "${file}:$.: warning: 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)) {
+ print STDERR "${file}:$.: warning: 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;
+ }
+}
+
+sub dump_typedef($$) {
+ my $x = shift;
+ my $file = shift;
+
+ $x =~ s@/\*.*?\*/@@gos; # strip comments.
+
+ # Parse function prototypes
+ if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+ $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+
+ # Function typedefs
+ $return_type = $1;
+ $declaration_name = $2;
+ my $args = $3;
+
+ 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;
+
+ 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
+ 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, $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", $file, $declaration_name);
+ }
+ elsif ($param =~ m/(.*?):(\d+)/) {
+ if ($type ne "") { # skip unnamed bit-fields
+ save_struct_actual($1);
+ push_parameter($1, "$type:$2", $file, $declaration_name)
+ }
+ }
+ else {
+ save_struct_actual($param);
+ push_parameter($param, $type, $file, $declaration_name);
+ }
+ }
+ }
+ }
+}
+
+sub push_parameter($$$$) {
+ my $param = shift;
+ my $type = 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 = "...";
+ }
+ 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);
+ # 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)) {
+ print STDERR
+ "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n";
+ ++$warnings;
+ }
+ }
+
+ # 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;
+ $type =~ s/\s\s+/ /g;
+ $parametertypes{$param} = $type;
+}
+
+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__\s*\(\([a-z,_\*\s\(\)]*\)\)//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") {
+ print STDERR "${file}:$.: warning: " .
+ "Excess function parameter " .
+ "'$sects[$sx]' " .
+ "description in '$decl_name'\n";
+ ++$warnings;
+ }
+ }
+ }
+}
+
+##
+# 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 "") {
+ print STDERR "${file}:$.: warning: " .
+ "No description found for return value of " .
+ "'$declaration_name'\n";
+ ++$warnings;
+ }
+}
+
+##
+# 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 $noret = 0;
+
+ $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/__init +//;
+ $prototype =~ s/__init_or_module +//;
+ $prototype =~ s/__meminit +//;
+ $prototype =~ s/__must_check +//;
+ $prototype =~ s/__weak +//;
+ $prototype =~ s/__sched +//;
+ my $define = $prototype =~ s/^#\s*define\s+//; #ak added
+ $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)
+
+ if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\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;
+ $noret = 1;
+ } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ ||
+ $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ ||
+ $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) {
+ $return_type = $1;
+ $declaration_name = $2;
+ my $args = $3;
+
+ create_parameterlist($args, ',', $file, $declaration_name);
+ } else {
+ print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\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
+ # verbose mode.
+ # TODO: always perform the check.
+ if ($verbose && !$noret) {
+ check_return_section($file, $declaration_name, $return_type);
+ }
+
+ 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
+ });
+}
+
+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)) {
+ print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n".
+ "$prototype\n";
+ } else {
+ $prototype = "static inline void trace_$tracepointname($tracepointargs)";
+ }
+}
+
+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 =~ m#\s*/\*\s+MACDOC\s*#io || ($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
+ 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;
+ }
+
+ if (defined($source_map{$file})) {
+ $file = $source_map{$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/) {
+ $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
+ $in_doc_sect = 0;
+ $declaration_start_line = $. + 1;
+ }
+}
+
+#
+# STATE_NAME: Looking for the "name - description" line
+#
+sub process_name($$) {
+ my $file = shift;
+ my $identifier;
+ my $descr;
+
+ if (/$doc_block/o) {
+ $state = STATE_DOCBLOCK;
+ $contents = "";
+ $new_start_line = $. + 1;
+
+ if ( $1 eq "" ) {
+ $section = $section_intro;
+ } else {
+ $section = $1;
+ }
+ }
+ elsif (/$doc_decl/o) {
+ $identifier = $1;
+ if (/\s*([\w\s]+?)(\(\))?\s*-/) {
+ $identifier = $1;
+ }
+
+ $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 (($declaration_purpose eq "") && $verbose) {
+ print STDERR "${file}:$.: warning: missing initial short description on line:\n";
+ print STDERR $_;
+ ++$warnings;
+ }
+
+ if ($identifier =~ m/^struct\b/) {
+ $decl_type = 'struct';
+ } elsif ($identifier =~ m/^union\b/) {
+ $decl_type = 'union';
+ } elsif ($identifier =~ m/^enum\b/) {
+ $decl_type = 'enum';
+ } elsif ($identifier =~ m/^typedef\b/) {
+ $decl_type = 'typedef';
+ } else {
+ $decl_type = 'function';
+ }
+
+ if ($verbose) {
+ print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
+ }
+ } else {
+ print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
+ " - I thought it was a doc line\n";
+ ++$warnings;
+ $state = STATE_NORMAL;
+ }
+}
+
+
+#
+# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment.
+#
+sub process_body($$) {
+ my $file = shift;
+
+ if (/$doc_sect/i) { # case insensitive for supported section names
+ $newsection = $1;
+ $newcontents = $2;
+
+ # map the supported section names to the canonical names
+ if ($newsection =~ m/^description$/i) {
+ $newsection = $section_default;
+ } elsif ($newsection =~ m/^context$/i) {
+ $newsection = $section_context;
+ } elsif ($newsection =~ m/^returns?$/i) {
+ $newsection = $section_return;
+ } elsif ($newsection =~ m/^\@return$/) {
+ # special: @return is a section, not a param description
+ $newsection = $section_return;
+ }
+
+ if (($contents ne "") && ($contents ne "\n")) {
+ if (!$in_doc_sect && $verbose) {
+ print STDERR "${file}:$.: warning: contents before sections\n";
+ ++$warnings;
+ }
+ dump_section($file, $section, $contents);
+ $section = $section_default;
+ }
+
+ $in_doc_sect = 1;
+ $state = STATE_BODY;
+ $contents = $newcontents;
+ $new_start_line = $.;
+ while (substr($contents, 0, 1) eq " ") {
+ $contents = substr($contents, 1);
+ }
+ if ($contents ne "") {
+ $contents .= "\n";
+ }
+ $section = $newsection;
+ $leading_space = undef;
+ } elsif (/$doc_end/) {
+ if (($contents ne "") && ($contents ne "\n")) {
+ dump_section($file, $section, $contents);
+ $section = $section_default;
+ $contents = "";
+ }
+ # look for doc_com + <text> + doc_end:
+ if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
+ print STDERR "${file}:$.: warning: suspicious ending line: $_";
+ ++$warnings;
+ }
+
+ $prototype = "";
+ $state = STATE_PROTO;
+ $brcount = 0;
+ } elsif (/$doc_content/) {
+ # miguel-style comment kludge, look for blank lines after
+ # @parameter line to signify start of description
+ if ($1 eq "") {
+ if ($section =~ m/^@/ || $section eq $section_context) {
+ dump_section($file, $section, $contents);
+ $section = $section_default;
+ $contents = "";
+ $new_start_line = $.;
+ } else {
+ $contents .= "\n";
+ }
+ $state = STATE_BODY;
+ } elsif ($state == STATE_BODY_MAYBE) {
+ # Continued declaration purpose
+ chomp($declaration_purpose);
+ $declaration_purpose .= " " . $1;
+ $declaration_purpose =~ s/\s+/ /g;
+ } else {
+ my $cont = $1;
+ if ($section =~ m/^@/ || $section eq $section_context) {
+ if (!defined $leading_space) {
+ if ($cont =~ m/^(\s+)/) {
+ $leading_space = $1;
+ } else {
+ $leading_space = "";
+ }
+ }
+ $cont =~ s/^$leading_space//;
+ }
+ $contents .= $cont . "\n";
+ }
+ } else {
+ # i dont know - bad line? ignore.
+ print STDERR "${file}:$.: warning: bad line: $_";
+ ++$warnings;
+ }
+}
+
+
+#
+# STATE_PROTO: reading a function/whatever prototype.
+#
+sub process_proto($$) {
+ my $file = shift;
+
+ if (/$doc_inline_oneline/) {
+ $section = $1;
+ $contents = $2;
+ if ($contents ne "") {
+ $contents .= "\n";
+ dump_section($file, $section, $contents);
+ $section = $section_default;
+ $contents = "";
+ }
+ } elsif (/$doc_inline_start/) {
+ $state = STATE_INLINE;
+ $inline_doc_state = STATE_INLINE_NAME;
+ } elsif ($decl_type eq 'function') {
+ process_proto_function($_, $file);
+ } else {
+ process_proto_type($_, $file);
+ }
+}
+
+#
+# STATE_DOCBLOCK: within a DOC: block.
+#
+sub process_docblock($$) {
+ my $file = shift;
+
+ if (/$doc_end/) {
+ dump_doc_section($file, $section, $contents);
+ $section = $section_default;
+ $contents = "";
+ $function = "";
+ %parameterdescs = ();
+ %parametertypes = ();
+ @parameterlist = ();
+ %sections = ();
+ @sectionlist = ();
+ $prototype = "";
+ $state = STATE_NORMAL;
+ } elsif (/$doc_content/) {
+ if ( $1 eq "" ) {
+ $contents .= $blankline;
+ } else {
+ $contents .= $1 . "\n";
+ }
+ }
+}
+
+#
+# STATE_INLINE: docbook comments within a prototype.
+#
+sub process_inline($$) {
+ my $file = shift;
+
+ # First line (state 1) needs to be a @parameter
+ if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
+ $section = $1;
+ $contents = $2;
+ $new_start_line = $.;
+ if ($contents ne "") {
+ while (substr($contents, 0, 1) eq " ") {
+ $contents = substr($contents, 1);
+ }
+ $contents .= "\n";
+ }
+ $inline_doc_state = STATE_INLINE_TEXT;
+ # Documentation block end */
+ } elsif (/$doc_inline_end/) {
+ if (($contents ne "") && ($contents ne "\n")) {
+ dump_section($file, $section, $contents);
+ $section = $section_default;
+ $contents = "";
+ }
+ $state = STATE_PROTO;
+ $inline_doc_state = STATE_INLINE_NA;
+ # Regular text
+ } elsif (/$doc_content/) {
+ if ($inline_doc_state == STATE_INLINE_TEXT) {
+ $contents .= $1 . "\n";
+ # nuke leading blank lines
+ if ($contents =~ /^\s*$/) {
+ $contents = "";
+ }
+ } elsif ($inline_doc_state == STATE_INLINE_NAME) {
+ $inline_doc_state = STATE_INLINE_ERROR;
+ print STDERR "${file}:$.: warning: ";
+ print STDERR "Incorrect use of kernel-doc format: $_";
+ ++$warnings;
+ }
+ }
+}
+
+
+sub process_file($) {
+ my $file;
+ my $initial_section_counter = $section_counter;
+ my ($orig_file) = @_;
+
+ $file = map_filename($orig_file);
+
+ if (!open(IN,"<$file")) {
+ print STDERR "Error: Cannot open file $file\n";
+ ++$errors;
+ return;
+ }
+
+ $. = 1;
+
+ $section_counter = 0;
+ while (<IN>) {
+ while (s/\\\s*$//) {
+ $_ .= <IN>;
+ }
+ # Replace tabs by spaces
+ while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {};
+ # Hand this line to the appropriate state handler
+ if ($state == STATE_NORMAL) {
+ process_normal();
+ } elsif ($state == STATE_NAME) {
+ process_name($file, $_);
+ } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) {
+ process_body($file, $_);
+ } elsif ($state == STATE_INLINE) { # scanning for inline parameters
+ process_inline($file, $_);
+ } elsif ($state == STATE_PROTO) {
+ process_proto($file, $_);
+ } elsif ($state == STATE_DOCBLOCK) {
+ process_docblock($file, $_);
+ }
+ }
+
+ # Make sure we got something interesting.
+ if ($initial_section_counter == $section_counter) {
+ if ($output_mode ne "none") {
+ print STDERR "${file}:1: warning: no structured comments found\n";
+ }
+ if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) {
+ print STDERR " Was looking for '$_'.\n" for keys %function_table;
+ }
+ }
+}
+
+
+$kernelversion = get_kernel_version();
+
+# generate a sequence of code that will splice in highlighting information
+# using the s// operator.
+for (my $k = 0; $k < @highlights; $k++) {
+ my $pattern = $highlights[$k][0];
+ my $result = $highlights[$k][1];
+# print STDERR "scanning pattern:$pattern, highlight:($result)\n";
+ $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n";
+}
+
+# Read the file that maps relative names to absolute names for
+# separate source and object directories and for shadow trees.
+if (open(SOURCE_MAP, "<.tmp_filelist.txt")) {
+ my ($relname, $absname);
+ while(<SOURCE_MAP>) {
+ chop();
+ ($relname, $absname) = (split())[0..1];
+ $relname =~ s:^/+::;
+ $source_map{$relname} = $absname;
+ }
+ close(SOURCE_MAP);
+}
+
+if ($output_selection == OUTPUT_EXPORTED ||
+ $output_selection == OUTPUT_INTERNAL) {
+
+ push(@export_file_list, @ARGV);
+
+ foreach (@export_file_list) {
+ chomp;
+ process_export_file($_);
+ }
+}
+
+foreach (@ARGV) {
+ chomp;
+ process_file($_);
+}
+if ($verbose && $errors) {
+ print STDERR "$errors errors\n";
+}
+if ($verbose && $warnings) {
+ print STDERR "$warnings warnings\n";
+}
+
+exit($output_mode eq "none" ? 0 : $errors);
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module from Linux
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 03/10] docs/conf.py: Enable use of kerneldoc sphinx extension Peter Maydell
` (9 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Add the kerneldoc sphinx module from Linux kernel
commit 30bac164aca750892.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/sphinx/kerneldoc.py | 150 +++++++++++++++++++++++++++++++++++++++
1 file changed, 150 insertions(+)
create mode 100644 docs/sphinx/kerneldoc.py
diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
new file mode 100644
index 00000000000..9d0a7f08f93
--- /dev/null
+++ b/docs/sphinx/kerneldoc.py
@@ -0,0 +1,150 @@
+# coding=utf-8
+#
+# Copyright © 2016 Intel Corporation
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice (including the next
+# paragraph) shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+#
+# Authors:
+# Jani Nikula <jani.nikula@intel.com>
+#
+# Please make sure this works on both python2 and python3.
+#
+
+import codecs
+import os
+import subprocess
+import sys
+import re
+import glob
+
+from docutils import nodes, statemachine
+from docutils.statemachine import ViewList
+from docutils.parsers.rst import directives, Directive
+from sphinx.ext.autodoc import AutodocReporter
+
+__version__ = '1.0'
+
+class KernelDocDirective(Directive):
+ """Extract kernel-doc comments from the specified file"""
+ required_argument = 1
+ optional_arguments = 4
+ option_spec = {
+ 'doc': directives.unchanged_required,
+ 'functions': directives.unchanged,
+ 'export': directives.unchanged,
+ 'internal': directives.unchanged,
+ }
+ has_content = False
+
+ def run(self):
+ env = self.state.document.settings.env
+ cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']
+
+ filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
+ export_file_patterns = []
+
+ # Tell sphinx of the dependency
+ env.note_dependency(os.path.abspath(filename))
+
+ tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
+
+ # FIXME: make this nicer and more robust against errors
+ if 'export' in self.options:
+ cmd += ['-export']
+ export_file_patterns = str(self.options.get('export')).split()
+ elif 'internal' in self.options:
+ cmd += ['-internal']
+ export_file_patterns = str(self.options.get('internal')).split()
+ elif 'doc' in self.options:
+ cmd += ['-function', str(self.options.get('doc'))]
+ elif 'functions' in self.options:
+ functions = self.options.get('functions').split()
+ if functions:
+ for f in functions:
+ cmd += ['-function', f]
+ else:
+ cmd += ['-no-doc-sections']
+
+ for pattern in export_file_patterns:
+ for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern):
+ env.note_dependency(os.path.abspath(f))
+ cmd += ['-export-file', f]
+
+ cmd += [filename]
+
+ try:
+ env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd)))
+
+ p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+ out, err = p.communicate()
+
+ out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
+
+ if p.returncode != 0:
+ sys.stderr.write(err)
+
+ env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
+ return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
+ elif env.config.kerneldoc_verbosity > 0:
+ sys.stderr.write(err)
+
+ lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
+ result = ViewList()
+
+ lineoffset = 0;
+ line_regex = re.compile("^#define LINENO ([0-9]+)$")
+ for line in lines:
+ match = line_regex.search(line)
+ if match:
+ # sphinx counts lines from 0
+ lineoffset = int(match.group(1)) - 1
+ # we must eat our comments since the upset the markup
+ else:
+ result.append(line, filename, lineoffset)
+ lineoffset += 1
+
+ node = nodes.section()
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+ self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
+ self.state.memo.title_styles, self.state.memo.section_level = [], 0
+ try:
+ self.state.nested_parse(result, 0, node, match_titles=1)
+ finally:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
+ return node.children
+
+ except Exception as e: # pylint: disable=W0703
+ env.app.warn('kernel-doc \'%s\' processing failed with: %s' %
+ (" ".join(cmd), str(e)))
+ return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
+
+def setup(app):
+ app.add_config_value('kerneldoc_bin', None, 'env')
+ app.add_config_value('kerneldoc_srctree', None, 'env')
+ app.add_config_value('kerneldoc_verbosity', 1, 'env')
+
+ app.add_directive('kernel-doc', KernelDocDirective)
+
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 03/10] docs/conf.py: Enable use of kerneldoc sphinx extension
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module " Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 04/10] docs/conf.py: Ignore some missing references in nitpick mode Peter Maydell
` (8 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/conf.py | 11 ++++++++---
1 file changed, 8 insertions(+), 3 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index befbcc6c3e1..9109edbcb97 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -41,8 +41,7 @@ except NameError:
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use an absolute path starting from qemu_docdir.
#
-# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir"))
-
+sys.path.insert(0, os.path.join(qemu_docdir, "sphinx"))
# -- General configuration ------------------------------------------------
@@ -54,7 +53,7 @@ needs_sphinx = '1.3'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = []
+extensions = ['kerneldoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -213,4 +212,10 @@ texinfo_documents = [
]
+# -- Options for configuring kerneldoc extension -------------------------
+# We use paths starting from qemu_docdir here so that you can run
+# sphinx-build from anywhere and the kerneldoc extension can still
+# find everything.
+kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc')
+kerneldoc_srctree = os.path.join(qemu_docdir, '..')
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 04/10] docs/conf.py: Ignore some missing references in nitpick mode
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (2 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 03/10] docs/conf.py: Enable use of kerneldoc sphinx extension Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 05/10] bitops.h: Silence kernel-doc complaints Peter Maydell
` (7 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
We enable Sphinx's 'nitpick' mode via the command line -n switch, which
means it warns about references to things it doesn't know about. Add
a whitelist of expected-not-to-be-present types, to avoid false
positives when C function prototypes use standard integer types.
If this whitelist gets too long and unmanageable we might be better
off switching to non-nitpick mode instead.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/conf.py | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/docs/conf.py b/docs/conf.py
index 9109edbcb97..388299fb25b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -114,6 +114,17 @@ todo_include_todos = False
# with "option::" in the document being processed. Turn that off.
suppress_warnings = ["ref.option"]
+nitpick_ignore = [
+ ("c:type", "int8_t"),
+ ("c:type", "int16_t"),
+ ("c:type", "int32_t"),
+ ("c:type", "int64_t"),
+ ("c:type", "uint8_t"),
+ ("c:type", "uint16_t"),
+ ("c:type", "uint32_t"),
+ ("c:type", "uint64_t"),
+]
+
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 05/10] bitops.h: Silence kernel-doc complaints
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (3 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 04/10] docs/conf.py: Ignore some missing references in nitpick mode Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 06/10] docs: Create bitops.rst as example of kernel-docs Peter Maydell
` (6 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Fix the problems with kernel-doc/sphinx syntax in the
doc comments for the shuffle and unshuffle functions:
* mismatch between comment and prototype for argument name
* the inline bit patterns need to be marked up so they
are processed properly and rendered as monospace
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
include/qemu/bitops.h | 52 ++++++++++++++++++++++++++-----------------
1 file changed, 32 insertions(+), 20 deletions(-)
diff --git a/include/qemu/bitops.h b/include/qemu/bitops.h
index 3f0926cf40c..f6e76b5952d 100644
--- a/include/qemu/bitops.h
+++ b/include/qemu/bitops.h
@@ -423,13 +423,16 @@ static inline uint64_t deposit64(uint64_t value, int start, int length,
/**
* half_shuffle32:
- * @value: 32-bit value (of which only the bottom 16 bits are of interest)
+ * @x: 32-bit value (of which only the bottom 16 bits are of interest)
+ *
+ * Given an input value::
+ *
+ * xxxx xxxx xxxx xxxx ABCD EFGH IJKL MNOP
*
- * Given an input value:
- * xxxx xxxx xxxx xxxx ABCD EFGH IJKL MNOP
* return the value where the bottom 16 bits are spread out into
- * the odd bits in the word, and the even bits are zeroed:
- * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N 0O0P
+ * the odd bits in the word, and the even bits are zeroed::
+ *
+ * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N 0O0P
*
* Any bits set in the top half of the input are ignored.
*
@@ -449,13 +452,16 @@ static inline uint32_t half_shuffle32(uint32_t x)
/**
* half_shuffle64:
- * @value: 64-bit value (of which only the bottom 32 bits are of interest)
+ * @x: 64-bit value (of which only the bottom 32 bits are of interest)
+ *
+ * Given an input value::
+ *
+ * xxxx xxxx xxxx .... xxxx xxxx ABCD EFGH IJKL MNOP QRST UVWX YZab cdef
*
- * Given an input value:
- * xxxx xxxx xxxx .... xxxx xxxx ABCD EFGH IJKL MNOP QRST UVWX YZab cdef
* return the value where the bottom 32 bits are spread out into
- * the odd bits in the word, and the even bits are zeroed:
- * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N .... 0U0V 0W0X 0Y0Z 0a0b 0c0d 0e0f
+ * the odd bits in the word, and the even bits are zeroed::
+ *
+ * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N .... 0U0V 0W0X 0Y0Z 0a0b 0c0d 0e0f
*
* Any bits set in the top half of the input are ignored.
*
@@ -476,13 +482,16 @@ static inline uint64_t half_shuffle64(uint64_t x)
/**
* half_unshuffle32:
- * @value: 32-bit value (of which only the odd bits are of interest)
+ * @x: 32-bit value (of which only the odd bits are of interest)
+ *
+ * Given an input value::
+ *
+ * xAxB xCxD xExF xGxH xIxJ xKxL xMxN xOxP
*
- * Given an input value:
- * xAxB xCxD xExF xGxH xIxJ xKxL xMxN xOxP
* return the value where all the odd bits are compressed down
- * into the low half of the word, and the high half is zeroed:
- * 0000 0000 0000 0000 ABCD EFGH IJKL MNOP
+ * into the low half of the word, and the high half is zeroed::
+ *
+ * 0000 0000 0000 0000 ABCD EFGH IJKL MNOP
*
* Any even bits set in the input are ignored.
*
@@ -503,13 +512,16 @@ static inline uint32_t half_unshuffle32(uint32_t x)
/**
* half_unshuffle64:
- * @value: 64-bit value (of which only the odd bits are of interest)
+ * @x: 64-bit value (of which only the odd bits are of interest)
+ *
+ * Given an input value::
+ *
+ * xAxB xCxD xExF xGxH xIxJ xKxL xMxN .... xUxV xWxX xYxZ xaxb xcxd xexf
*
- * Given an input value:
- * xAxB xCxD xExF xGxH xIxJ xKxL xMxN .... xUxV xWxX xYxZ xaxb xcxd xexf
* return the value where all the odd bits are compressed down
- * into the low half of the word, and the high half is zeroed:
- * 0000 0000 0000 .... 0000 0000 ABCD EFGH IJKL MNOP QRST UVWX YZab cdef
+ * into the low half of the word, and the high half is zeroed::
+ *
+ * 0000 0000 0000 .... 0000 0000 ABCD EFGH IJKL MNOP QRST UVWX YZab cdef
*
* Any even bits set in the input are ignored.
*
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 06/10] docs: Create bitops.rst as example of kernel-docs
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (4 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 05/10] bitops.h: Silence kernel-doc complaints Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues Peter Maydell
` (5 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Create a bitops.rst which is just a container for the
kernel-doc comments in qemu/bitops.h.
This is mostly a test of the kernel-doc extension machinery.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/devel/bitops.rst | 8 ++++++++
docs/devel/index.rst | 1 +
2 files changed, 9 insertions(+)
create mode 100644 docs/devel/bitops.rst
diff --git a/docs/devel/bitops.rst b/docs/devel/bitops.rst
new file mode 100644
index 00000000000..6addaecf8d7
--- /dev/null
+++ b/docs/devel/bitops.rst
@@ -0,0 +1,8 @@
+==================
+Bitwise operations
+==================
+
+The header ``qemu/bitops.h`` provides utility functions for
+performing bitwise operations.
+
+.. kernel-doc:: include/qemu/bitops.h
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 2a4ddf40ad3..49cb212a8b4 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -21,3 +21,4 @@ Contents:
testing
decodetree
secure-coding-practices
+ bitops
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (5 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 06/10] docs: Create bitops.rst as example of kernel-docs Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 08/10] docs: Add kernel-doc API documentation to memory.rst Peter Maydell
` (4 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
If you try to use kerneldoc to extract the doc comments from
memory.h and run sphinx on it, it generates some warnings:
* various functions are missing a parameter in the docs
* some 'unexpected indentation' warnings where a list
isn't marked up with the leading/trailing blank lines and
bullet markers that rST expects
These aren't the only issues, but they are the only ones
that are actually warned about (as opposed to generating
misformatted output).
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
include/exec/memory.h | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/include/exec/memory.h b/include/exec/memory.h
index 9144a47f571..8447a16ded1 100644
--- a/include/exec/memory.h
+++ b/include/exec/memory.h
@@ -907,6 +907,7 @@ void memory_region_init_rom(MemoryRegion *mr,
* @mr: the #MemoryRegion to be initialized.
* @owner: the object that tracks the region's reference count
* @ops: callbacks for write access handling (must not be NULL).
+ * @opaque: passed to the read and write callbacks of the @ops structure.
* @name: Region name, becomes part of RAMBlock name used in migration stream
* must be unique within any device
* @size: size of the region.
@@ -995,7 +996,7 @@ static inline IOMMUMemoryRegion *memory_region_get_iommu(MemoryRegion *mr)
* Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu,
* otherwise NULL. This is fast path avoiding QOM checking, use with caution.
*
- * @mr: the memory region being queried
+ * @iommu_mr: the memory region being queried
*/
static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck(
IOMMUMemoryRegion *iommu_mr)
@@ -1558,6 +1559,7 @@ void memory_region_add_subregion_overlap(MemoryRegion *mr,
/**
* memory_region_get_ram_addr: Get the ram address associated with a memory
* region
+ * @mr: the memory region to get the ram address for
*/
ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr);
@@ -1650,6 +1652,7 @@ bool memory_region_is_mapped(MemoryRegion *mr);
*
* Returns a #MemoryRegionSection that describes a contiguous overlap.
* It will have the following characteristics:
+ *
* .@size = 0 iff no overlap was found
* .@mr is non-%NULL iff an overlap was found
*
@@ -1657,11 +1660,12 @@ bool memory_region_is_mapped(MemoryRegion *mr);
* relative to the returned region (in the .@mr field), not to the
* @mr argument.
*
- * Similarly, the .@offset_within_address_space is relative to the
+ * Similarly, the @.offset_within_address_space is relative to the
* address space that contains both regions, the passed and the
* returned one. However, in the special case where the @mr argument
* has no container (and thus is the root of the address space), the
* following will hold:
+ *
* .@offset_within_address_space >= @addr
* .@offset_within_address_space + .@size <= @addr + @size
*
@@ -2107,6 +2111,7 @@ static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write)
* @addr: address within that address space
* @attrs: memory transaction attributes
* @buf: buffer with the data transferred
+ * @len: length of the buffer
*/
static inline __attribute__((__always_inline__))
MemTxResult address_space_read(AddressSpace *as, hwaddr addr,
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 08/10] docs: Add kernel-doc API documentation to memory.rst
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (6 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 09/10] memory.h: attempted kernel-doc fixes Peter Maydell
` (3 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Add the API documentation as generated by kernel-doc to memory.rst.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
Note that this generates errors that break the build, at
least with the 1.7.5 version of Sphinx I'm currently using.
---
docs/devel/memory.rst | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst
index b6a4c37ea5e..68bc6202797 100644
--- a/docs/devel/memory.rst
+++ b/docs/devel/memory.rst
@@ -361,3 +361,8 @@ callbacks are called:
- .impl.unaligned specifies that the *implementation* supports unaligned
accesses; if false, unaligned accesses will be emulated by two aligned
accesses.
+
+Detailed API documentation
+--------------------------
+
+.. kernel-doc:: include/exec/memory.h
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 09/10] memory.h: attempted kernel-doc fixes
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (7 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 08/10] docs: Add kernel-doc API documentation to memory.rst Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 10/10] Makefile: disable Sphinx nitpicking Peter Maydell
` (2 subsequent siblings)
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
kernel-doc needs the "struct" or it complains that it
can't parse a function prototype which is actually a struct
definition.
Note that this then creates a lot of warnings about
undocumented struct fields...
---
include/exec/memory.h | 22 ++++++++++++----------
1 file changed, 12 insertions(+), 10 deletions(-)
diff --git a/include/exec/memory.h b/include/exec/memory.h
index 8447a16ded1..d0f35be1c3b 100644
--- a/include/exec/memory.h
+++ b/include/exec/memory.h
@@ -208,7 +208,7 @@ enum IOMMUMemoryRegionAttr {
};
/**
- * IOMMUMemoryRegionClass:
+ * struct IOMMUMemoryRegionClass:
*
* All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION
* and provide an implementation of at least the @translate method here
@@ -224,8 +224,10 @@ enum IOMMUMemoryRegionAttr {
* attributes and the output TLB entry depends on the transaction
* attributes, we represent this using IOMMU indexes. Each index
* selects a particular translation table that the IOMMU has:
- * @attrs_to_index returns the IOMMU index for a set of transaction attributes
- * @translate takes an input address and an IOMMU index
+ *
+ * - @attrs_to_index returns the IOMMU index for a set of transaction attributes
+ * - @translate takes an input address and an IOMMU index
+ *
* and the mapping returned can only depend on the input address and the
* IOMMU index.
*
@@ -398,7 +400,7 @@ struct IOMMUMemoryRegion {
QLIST_FOREACH((n), &(mr)->iommu_notify, node)
/**
- * MemoryListener: callbacks structure for updates to the physical memory map
+ * struct MemoryListener: callbacks structure for updates to the physical memory map
*
* Allows a component to adjust to changes in the guest-visible memory map.
* Use with memory_listener_register() and memory_listener_unregister().
@@ -432,7 +434,7 @@ struct MemoryListener {
};
/**
- * AddressSpace: describes a mapping of addresses to #MemoryRegion objects
+ * struct AddressSpace: describes a mapping of addresses to #MemoryRegion objects
*/
struct AddressSpace {
/* All fields are private. */
@@ -472,7 +474,7 @@ static inline FlatView *address_space_to_flatview(AddressSpace *as)
/**
- * MemoryRegionSection: describes a fragment of a #MemoryRegion
+ * struct MemoryRegionSection: describes a fragment of a #MemoryRegion
*
* @mr: the region, or %NULL if empty
* @fv: the flat view of the address space the region is mapped in
@@ -1653,8 +1655,8 @@ bool memory_region_is_mapped(MemoryRegion *mr);
* Returns a #MemoryRegionSection that describes a contiguous overlap.
* It will have the following characteristics:
*
- * .@size = 0 iff no overlap was found
- * .@mr is non-%NULL iff an overlap was found
+ * - .@size = 0 iff no overlap was found
+ * - .@mr is non-%NULL iff an overlap was found
*
* Remember that in the return value the @offset_within_region is
* relative to the returned region (in the .@mr field), not to the
@@ -1666,8 +1668,8 @@ bool memory_region_is_mapped(MemoryRegion *mr);
* has no container (and thus is the root of the address space), the
* following will hold:
*
- * .@offset_within_address_space >= @addr
- * .@offset_within_address_space + .@size <= @addr + @size
+ * - .@offset_within_address_space >= @addr
+ * - .@offset_within_address_space + .@size <= @addr + @size
*
* @mr: a MemoryRegion within which @addr is a relative address
* @addr: start of the area within @as to be searched
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* [Qemu-devel] [RFC 10/10] Makefile: disable Sphinx nitpicking
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (8 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 09/10] memory.h: attempted kernel-doc fixes Peter Maydell
@ 2019-05-21 12:25 ` Peter Maydell
2019-05-21 12:42 ` [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup no-reply
2019-05-21 12:48 ` Peter Maydell
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:25 UTC (permalink / raw)
To: qemu-devel
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
Turn off Sphinx nitpicking as a temporary measure so
sphinx builds complete even with warnings about missing
references.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
Makefile | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Makefile b/Makefile
index 155f066a206..b4be96ce9a6 100644
--- a/Makefile
+++ b/Makefile
@@ -932,7 +932,7 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html
# Canned command to build a single manual
-build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
+build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
# We assume all RST files in the manual's directory are used in it
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
--
2.20.1
^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (9 preceding siblings ...)
2019-05-21 12:25 ` [Qemu-devel] [RFC 10/10] Makefile: disable Sphinx nitpicking Peter Maydell
@ 2019-05-21 12:42 ` no-reply
2019-05-21 12:48 ` Peter Maydell
11 siblings, 0 replies; 13+ messages in thread
From: no-reply @ 2019-05-21 12:42 UTC (permalink / raw)
To: peter.maydell
Cc: fam, berrange, ehabkost, sbarreto.gabriel, qemu-devel, cota,
stefanha, crosa, pbonzini, jsnow
Patchew URL: https://patchew.org/QEMU/20190521122519.12573-1-peter.maydell@linaro.org/
Hi,
This series seems to have some coding style problems. See output below for
more information:
Subject: [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup
Message-id: 20190521122519.12573-1-peter.maydell@linaro.org
Type: series
=== TEST SCRIPT BEGIN ===
#!/bin/bash
git rev-parse base > /dev/null || exit 0
git config --local diff.renamelimit 0
git config --local diff.renames True
git config --local diff.algorithm histogram
./scripts/checkpatch.pl --mailback base..
=== TEST SCRIPT END ===
From https://github.com/patchew-project/qemu
* [new tag] patchew/20190521122519.12573-1-peter.maydell@linaro.org -> patchew/20190521122519.12573-1-peter.maydell@linaro.org
Switched to a new branch 'test'
02a0d0d337 Makefile: disable Sphinx nitpicking
2124e52316 memory.h: attempted kernel-doc fixes
f73463aa82 docs: Add kernel-doc API documentation to memory.rst
e775bbb9db memory.h: Fix kerneldoc syntax issues
b7a8bdc1ba docs: Create bitops.rst as example of kernel-docs
19ff73c38a bitops.h: Silence kernel-doc complaints
5a4c54aa09 docs/conf.py: Ignore some missing references in nitpick mode
a08b2a1c93 docs/conf.py: Enable use of kerneldoc sphinx extension
c4f9da74ce docs: Add kerneldoc sphinx module from Linux
e97b2d12d4 scripts/kernel-doc: Import kernel-doc script from Linux
=== OUTPUT BEGIN ===
1/10 Checking commit e97b2d12d441 (scripts/kernel-doc: Import kernel-doc script from Linux)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#13:
new file mode 100755
total: 0 errors, 1 warnings, 2223 lines checked
Patch 1/10 has style problems, please review. If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
2/10 Checking commit c4f9da74cecb (docs: Add kerneldoc sphinx module from Linux)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#14:
new file mode 100644
WARNING: line over 80 characters
#84: FILE: docs/sphinx/kerneldoc.py:66:
+ tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
WARNING: line over 80 characters
#113: FILE: docs/sphinx/kerneldoc.py:95:
+ p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
ERROR: line over 90 characters
#121: FILE: docs/sphinx/kerneldoc.py:103:
+ env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode))
WARNING: line over 80 characters
#122: FILE: docs/sphinx/kerneldoc.py:104:
+ return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
WARNING: line over 80 characters
#126: FILE: docs/sphinx/kerneldoc.py:108:
+ lines = statemachine.string2lines(out, tab_width, convert_whitespace=True)
ERROR: line over 90 characters
#142: FILE: docs/sphinx/kerneldoc.py:124:
+ buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
WARNING: line over 80 characters
#143: FILE: docs/sphinx/kerneldoc.py:125:
+ self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter)
ERROR: line over 90 characters
#148: FILE: docs/sphinx/kerneldoc.py:130:
+ self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
WARNING: line over 80 characters
#155: FILE: docs/sphinx/kerneldoc.py:137:
+ return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))]
total: 3 errors, 7 warnings, 150 lines checked
Patch 2/10 has style problems, please review. If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
3/10 Checking commit a08b2a1c931a (docs/conf.py: Enable use of kerneldoc sphinx extension)
4/10 Checking commit 5a4c54aa09f6 (docs/conf.py: Ignore some missing references in nitpick mode)
5/10 Checking commit 19ff73c38a62 (bitops.h: Silence kernel-doc complaints)
6/10 Checking commit b7a8bdc1ba62 (docs: Create bitops.rst as example of kernel-docs)
WARNING: added, moved or deleted file(s), does MAINTAINERS need updating?
#16:
new file mode 100644
total: 0 errors, 1 warnings, 12 lines checked
Patch 6/10 has style problems, please review. If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
7/10 Checking commit e775bbb9db99 (memory.h: Fix kerneldoc syntax issues)
8/10 Checking commit f73463aa82c3 (docs: Add kernel-doc API documentation to memory.rst)
9/10 Checking commit 2124e5231685 (memory.h: attempted kernel-doc fixes)
WARNING: line over 80 characters
#35: FILE: include/exec/memory.h:228:
+ * - @attrs_to_index returns the IOMMU index for a set of transaction attributes
WARNING: line over 80 characters
#46: FILE: include/exec/memory.h:403:
+ * struct MemoryListener: callbacks structure for updates to the physical memory map
WARNING: line over 80 characters
#55: FILE: include/exec/memory.h:437:
+ * struct AddressSpace: describes a mapping of addresses to #MemoryRegion objects
ERROR: Missing Signed-off-by: line(s)
total: 1 errors, 3 warnings, 64 lines checked
Patch 9/10 has style problems, please review. If any of these errors
are false positives report them to the maintainer, see
CHECKPATCH in MAINTAINERS.
10/10 Checking commit 02a0d0d33747 (Makefile: disable Sphinx nitpicking)
=== OUTPUT END ===
Test command exited with code: 1
The full log is available at
http://patchew.org/logs/20190521122519.12573-1-peter.maydell@linaro.org/testing.checkpatch/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com
^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
` (10 preceding siblings ...)
2019-05-21 12:42 ` [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup no-reply
@ 2019-05-21 12:48 ` Peter Maydell
11 siblings, 0 replies; 13+ messages in thread
From: Peter Maydell @ 2019-05-21 12:48 UTC (permalink / raw)
To: QEMU Developers
Cc: Daniel P. Berrange, Eduardo Habkost, Gabriel Barreto,
Emilio G. Cota, Stefan Hajnoczi, Cleber Rosa, Paolo Bonzini,
John Snow
On Tue, 21 May 2019 at 13:25, Peter Maydell <peter.maydell@linaro.org> wrote:
>
> Hi; this is an RFC patchset which I'm sending out mostly to provide a
> work-in-progress snapshot
...patchew tells me it was sufficiently work-in-progress
that I forgot some signed-off-by lines, so for the
avoidance of doubt, all patches in this series can
have my
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
thanks
-- PMM
^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2019-05-21 12:59 UTC | newest]
Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-05-21 12:25 [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module " Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 03/10] docs/conf.py: Enable use of kerneldoc sphinx extension Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 04/10] docs/conf.py: Ignore some missing references in nitpick mode Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 05/10] bitops.h: Silence kernel-doc complaints Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 06/10] docs: Create bitops.rst as example of kernel-docs Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 08/10] docs: Add kernel-doc API documentation to memory.rst Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 09/10] memory.h: attempted kernel-doc fixes Peter Maydell
2019-05-21 12:25 ` [Qemu-devel] [RFC 10/10] Makefile: disable Sphinx nitpicking Peter Maydell
2019-05-21 12:42 ` [Qemu-devel] [RFC 00/10] Add kernel-doc support to our Sphinx setup no-reply
2019-05-21 12:48 ` Peter Maydell
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.