From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575038666; cv=none; d=zohomail.com; s=zohoarc; b=bya0JTb7PW7YVKBsUvCAbh6+raF59vQNg7MQyERHCIjc3G6ff/n6UauxsDcB1QVs/NuqQi0BsUtjcIdRZGH+N5eljVuCvvhhR0tZcbKvDxIe54W+BPRgbtcUegVXNHdYvMtALWCYUOjebub7q3vwxyHJ5uiuu02yS6uIgZFNK2M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575038666; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Yo1psJFkJ7l1dmatMOcWJYr++QsVD7kN97CZSlcsQqA=; b=Zq8SpW1wwnLCzTviZCLBOeGvOuN42NzaF1TVnfR6t5LRP5nSjngq/YP+9ii6Czj/77iyuLyP3lHRglHcWETtjA4/+24lZzosbf4Xdt4t7ssN7zbOMvd4mlxwUAwn+TCMZ6pZxt4FLUKtJlCGXUH6CskyAllA4V4lyxNs/6UbVQk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575038666705950.1819795220199; Fri, 29 Nov 2019 06:44:26 -0800 (PST) Received: from localhost ([::1]:59854 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iahVP-0007Vj-AU for importer@patchew.org; Fri, 29 Nov 2019 09:44:23 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37536) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagr1-0002Kz-Pr for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqt-0003Sq-EU for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:38 -0500 Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:41006) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqp-0003KH-8L for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:29 -0500 Received: by mail-wr1-x42c.google.com with SMTP id b18so35332003wrj.8 for ; Fri, 29 Nov 2019 06:02:25 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:19 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Yo1psJFkJ7l1dmatMOcWJYr++QsVD7kN97CZSlcsQqA=; b=LviTfvDjHIRkFk/5DHdMtwgpsP2K7egNV1biN7NWKzYTepwDEFCWUSQ1Mf4tfulu1F lqDeeHRqY9bwhAGrAG6pj2Ur7wfSfWdhUCji/Z911sqmyRxEXlx0dgENT0ABmshQj+0O kcuSajLZ9BsAI56Ex6zj+cpDtVFvApQ4pyUxhFJ6SZ7TClyPoRW7KsmdD2TqKeq2Qav8 gnEaUaLtey7h64YtMQ61RJOSZKj0ZUGOK8zZs0VOcn1dSwNS38EhUaF5rBPSlz7XGFmo Irg5p0m5+klNYL7yCQeQPis/ouEsXRcVt/QELPU0VvnquawpdN74k1coiewwLBbBa9gX x2QQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=Yo1psJFkJ7l1dmatMOcWJYr++QsVD7kN97CZSlcsQqA=; b=TIshh0od1u7ryiUuihcTNVlLJBMIjSBmRVBDeYR1uWj/mgmoDwzzQ7SkPrUf3MfFki 23F0gkz7SqU56vsFfVC1YLJWTUvj+TcY5jXI11xVfb3O7hxKnicFv/36mWxL9gvCyQA/ Ab7qNcblj/jpjf24vmE/wG+w83NQ3hHhbkOOa89euvaWl3gHs55OHkTE8aol3MRHGT2T cXk8IzI2giEPyO0V01psGE+BiD6Aeo7C7ZLL6kbHjcpbtzDOgRHRmJv3Yn3x6TFJVa9n gtplR61gVUWHmqoL1Sca8+dl508qsZp2kjx17/N8AAOa9blnexTJt8JRmt2oDFXkpnMx G1cA== X-Gm-Message-State: APjAAAUv6V4u7aCLegZSivxbM73ud9hxqujUNekPeTLaadHXNxWFPHvp vd4zDW+VKHrWou/+Ls1u0+Tv/gC8 X-Google-Smtp-Source: APXvYqxiFBPqCbtSs5ZjTLJkBI0brYc88MpAvFm6jcZKjdZFfuKCbdpgoTUUHkHK+4oQEazPsHUNTw== X-Received: by 2002:adf:8297:: with SMTP id 23mr8492642wrc.379.1575036140284; Fri, 29 Nov 2019 06:02:20 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 1/8] docs: import Linux kernel-doc script and extension Date: Fri, 29 Nov 2019 15:02:10 +0100 Message-Id: <20191129140217.17797-2-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42c X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Import Linux's kernel-doc script, as well as the Linux extension to call kernel-doc according to the arguments and parameters given to a reStructuredText directive. The kernel-doc extension accepts a filename, which is relative to the QEMU source tree root. The extension also notifies Sphinx about the document dependency on the file, causing the document to be rebuilt when the file has been changed. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/sphinx/kerneldoc.py | 172 +++ docs/sphinx/kernellog.py | 28 + scripts/kernel-doc | 2226 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 2426 insertions(+) create mode 100644 docs/sphinx/kerneldoc.py create mode 100644 docs/sphinx/kernellog.py create mode 100755 scripts/kernel-doc diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py new file mode 100644 index 0000000000..1159405cb9 --- /dev/null +++ b/docs/sphinx/kerneldoc.py @@ -0,0 +1,172 @@ +# coding=3Dutf-8 +# +# Copyright =C2=A9 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 OTH= ER +# 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 DEAL= INGS +# IN THE SOFTWARE. +# +# Authors: +# Jani Nikula +# +# 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 + +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI =3D sphinx.__version__[:3] >=3D '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + +import kernellog + +__version__ =3D '1.0' + +class KernelDocDirective(Directive): + """Extract kernel-doc comments from the specified file""" + required_argument =3D 1 + optional_arguments =3D 4 + option_spec =3D { + 'doc': directives.unchanged_required, + 'functions': directives.unchanged, + 'export': directives.unchanged, + 'internal': directives.unchanged, + } + has_content =3D False + + def run(self): + env =3D self.state.document.settings.env + cmd =3D [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + + filename =3D env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns =3D [] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(filename)) + + tab_width =3D self.options.get('tab-width', self.state.document.se= ttings.tab_width) + + # FIXME: make this nicer and more robust against errors + if 'export' in self.options: + cmd +=3D ['-export'] + export_file_patterns =3D str(self.options.get('export')).split= () + elif 'internal' in self.options: + cmd +=3D ['-internal'] + export_file_patterns =3D str(self.options.get('internal')).spl= it() + elif 'doc' in self.options: + cmd +=3D ['-function', str(self.options.get('doc'))] + elif 'functions' in self.options: + functions =3D self.options.get('functions').split() + if functions: + for f in functions: + cmd +=3D ['-function', f] + else: + cmd +=3D ['-no-doc-sections'] + + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + patter= n): + env.note_dependency(os.path.abspath(f)) + cmd +=3D ['-export-file', f] + + cmd +=3D [filename] + + try: + kernellog.verbose(env.app, + 'calling kernel-doc \'%s\'' % (" ".join(cmd)= )) + + p =3D subprocess.Popen(cmd, stdout=3Dsubprocess.PIPE, stderr= =3Dsubprocess.PIPE) + out, err =3D p.communicate() + + out, err =3D codecs.decode(out, 'utf-8'), codecs.decode(err, '= utf-8') + + if p.returncode !=3D 0: + sys.stderr.write(err) + + kernellog.warn(env.app, + 'kernel-doc \'%s\' failed with return code = %d' % (" ".join(cmd), p.returncode)) + return [nodes.error(None, nodes.paragraph(text =3D "kernel= -doc missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) + + lines =3D statemachine.string2lines(out, tab_width, convert_wh= itespace=3DTrue) + result =3D ViewList() + + lineoffset =3D 0; + line_regex =3D re.compile("^#define LINENO ([0-9]+)$") + for line in lines: + match =3D line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset =3D int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + result.append(line, filename, lineoffset) + lineoffset +=3D 1 + + node =3D nodes.section() + self.do_parse(result, node) + + return node.children + + except Exception as e: # pylint: disable=3DW0703 + kernellog.warn(env.app, 'kernel-doc \'%s\' processing failed w= ith: %s' % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text =3D "kernel-doc= missing"))] + + def do_parse(self, result, node): + if Use_SSI: + with switch_source_input(self.state, result): + self.state.nested_parse(result, 0, node, match_titles=3D1) + else: + save =3D self.state.memo.title_styles, self.state.memo.section= _level, self.state.memo.reporter + self.state.memo.reporter =3D AutodocReporter(result, self.stat= e.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = =3D [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=3D1) + finally: + self.state.memo.title_styles, self.state.memo.section_leve= l, self.state.memo.reporter =3D save + + +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 =3D __version__, + parallel_read_safe =3D True, + parallel_write_safe =3D True + ) diff --git a/docs/sphinx/kernellog.py b/docs/sphinx/kernellog.py new file mode 100644 index 0000000000..af924f51a7 --- /dev/null +++ b/docs/sphinx/kernellog.py @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: GPL-2.0 +# +# Sphinx has deprecated its older logging interface, but the replacement +# only goes back to 1.6. So here's a wrapper layer to keep around for +# as long as we support 1.4. +# +import sphinx + +if sphinx.__version__[:3] >=3D '1.6': + UseLogging =3D True + from sphinx.util import logging + logger =3D logging.getLogger('kerneldoc') +else: + UseLogging =3D False + +def warn(app, message): + if UseLogging: + logger.warning(message) + else: + app.warn(message) + +def verbose(app, message): + if UseLogging: + logger.verbose(message) + else: + app.verbose(message) + + diff --git a/scripts/kernel-doc b/scripts/kernel-doc new file mode 100755 index 0000000000..81dc91760b --- /dev/null +++ b/scripts/kernel-doc @@ -0,0 +1,2226 @@ +#!/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 ## +## Copyright (C) 2001 Simon Huggins ## +## Copyright (C) 2005-2012 Randy Dunlap ## +## Copyright (C) 2012 Dan Luedtke ## +## ## +## #define enhancements by Armin Kuster ## +## 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 + +# 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 + +# 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 + +# 25/07/2012 - Added support for HTML5 +# -- Dan Luedtke + +sub usage { + my $message =3D <<"EOF"; +Usage: $0 [OPTION ...] FILE ... + +Read C language source or header FILEs, extract embedded documentation com= ments, +and print formatted documentation to standard output. + +The documentation comments are identified by "/**" opening comment mark. S= ee +Documentation/doc-guide/kernel-doc.rst for the documentation comment synta= x. + +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 use= d with + -export or -internal. May be specified multiple ti= mes. + +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 li= ne +# 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 functio= ns +# 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 mark= ed +# 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 sp= ecial +# 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 =3D 0; +my $warnings =3D 0; +my $anon_struct_union =3D 0; + +# match expressions used to find embedded type information +my $type_constant =3D '\b``([^\`]+)``\b'; +my $type_constant2 =3D '\%([-_\w]+)'; +my $type_func =3D '(\w+)\(\)'; +my $type_param =3D '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; +my $type_fp_param =3D '\@(\w+)\(\)'; # Special RST handling for func ptr = params +my $type_env =3D '(\$\w+)'; +my $type_enum =3D '\&(enum\s*([_\w]+))'; +my $type_struct =3D '\&(struct\s*([_\w]+))'; +my $type_typedef =3D '\&(typedef\s*([_\w]+))'; +my $type_union =3D '\&(union\s*([_\w]+))'; +my $type_member =3D '\&([_\w]+)(\.|->)([_\w]+)'; +my $type_fallback =3D '\&([_\w]+)'; +my $type_member_func =3D $type_member . '\(\)'; + +# Output conversion substitutions. +# One for each output format + +# these are pretty rough +my @highlights_man =3D ( + [$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 =3D ""; + +# rst-mode +my @highlights_rst =3D ( + [$type_constant, "``\$1``"], + [$type_constant2, "``\$1``"], + # Note: need to escape () to avoid func matching la= ter + [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\= \\\) <\$1>`"], + [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], + [$type_fp_param, "**\$1\\\\(\\\\)**"], + [$type_func, "\$1()"], + [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], + # in rst this can refer to any type + [$type_fallback, "\\:c\\:type\\:`\$1`"], + [$type_param, "**\$1**"] + ); +my $blankline_rst =3D "\n"; + +# read arguments +if ($#ARGV =3D=3D -1) { + usage(); +} + +my $kernelversion; +my $dohighlight =3D ""; + +my $verbose =3D 0; +my $output_mode =3D "rst"; +my $output_preformatted =3D 0; +my $no_doc_sections =3D 0; +my $enable_lineno =3D 0; +my @highlights =3D @highlights_rst; +my $blankline =3D $blankline_rst; +my $modulename =3D "Kernel API"; + +use constant { + OUTPUT_ALL =3D> 0, # output all symbols and doc sections + OUTPUT_INCLUDE =3D> 1, # output only specified symbols + OUTPUT_EXCLUDE =3D> 2, # output everything except specified symbo= ls + OUTPUT_EXPORTED =3D> 3, # output exported symbols + OUTPUT_INTERNAL =3D> 4, # output non-exported symbols +}; +my $output_selection =3D OUTPUT_ALL; +my $show_not_found =3D 0; # No longer used + +my @export_file_list; + +my @build_time; +if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && + (my $seconds =3D `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '= ') { + @build_time =3D gmtime($seconds); +} else { + @build_time =3D localtime; +} + +my $man_date =3D ('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 =3D "$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 =3D 0; + +my $lineprefix=3D""; + +# Parser states +use constant { + STATE_NORMAL =3D> 0, # normal code + STATE_NAME =3D> 1, # looking for function name + STATE_BODY_MAYBE =3D> 2, # body - or maybe more description + STATE_BODY =3D> 3, # the body of the comment + STATE_PROTO =3D> 4, # scanning prototype + STATE_DOCBLOCK =3D> 5, # documentation block + STATE_INLINE =3D> 6, # gathering documentation outside main blo= ck +}; +my $state; +my $in_doc_sect; +my $leading_space; + +# Inline documentation state +use constant { + STATE_INLINE_NA =3D> 0, # not applicable ($state !=3D STATE_INLINE) + STATE_INLINE_NAME =3D> 1, # looking for member name (@foo:) + STATE_INLINE_TEXT =3D> 2, # looking for member documentation + STATE_INLINE_END =3D> 3, # done + STATE_INLINE_ERROR =3D> 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 =3D '^/\*\*\s*$'; # Allow whitespace at end of comment start. +my $doc_end =3D '\*/'; +my $doc_com =3D '\s*\*\s*'; +my $doc_com_body =3D '\s*\* ?'; +my $doc_decl =3D $doc_com . '(\w+)'; +# @params and a strictly limited set of supported section names +my $doc_sect =3D $doc_com . + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\= s*:(.*)'; +my $doc_content =3D $doc_com_body . '(.*)'; +my $doc_block =3D $doc_com . 'DOC:\s*(.*)?'; +my $doc_inline_start =3D '^\s*/\*\*\s*$'; +my $doc_inline_sect =3D '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)'; +my $doc_inline_end =3D '^\s*\*/\s*$'; +my $doc_inline_oneline =3D '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$'; +my $export_symbol =3D '^\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 =3D ""; +my $new_start_line =3D 0; + +# the canonical section names. see also $doc_sect above. +my $section_default =3D "Description"; # default section +my $section_intro =3D "Introduction"; +my $section =3D $section_default; +my $section_context =3D "Context"; +my $section_return =3D "Return"; + +my $undescribed =3D "-- undescribed --"; + +reset_state(); + +while ($ARGV[0] =3D~ m/^--?(.*)/) { + my $cmd =3D $1; + shift @ARGV; + if ($cmd eq "man") { + $output_mode =3D "man"; + @highlights =3D @highlights_man; + $blankline =3D $blankline_man; + } elsif ($cmd eq "rst") { + $output_mode =3D "rst"; + @highlights =3D @highlights_rst; + $blankline =3D $blankline_rst; + } elsif ($cmd eq "none") { + $output_mode =3D "none"; + } elsif ($cmd eq "module") { # not needed for XML, inherits from calli= ng document + $modulename =3D shift @ARGV; + } elsif ($cmd eq "function") { # to only output specific functions + $output_selection =3D OUTPUT_INCLUDE; + $function =3D shift @ARGV; + $function_table{$function} =3D 1; + } elsif ($cmd eq "nofunction") { # output all except specific functions + $output_selection =3D OUTPUT_EXCLUDE; + $function =3D shift @ARGV; + $function_table{$function} =3D 1; + } elsif ($cmd eq "export") { # only exported symbols + $output_selection =3D OUTPUT_EXPORTED; + %function_table =3D (); + } elsif ($cmd eq "internal") { # only non-exported symbols + $output_selection =3D OUTPUT_INTERNAL; + %function_table =3D (); + } elsif ($cmd eq "export-file") { + my $file =3D shift @ARGV; + push(@export_file_list, $file); + } elsif ($cmd eq "v") { + $verbose =3D 1; + } elsif (($cmd eq "h") || ($cmd eq "help")) { + usage(); + } elsif ($cmd eq 'no-doc-sections') { + $no_doc_sections =3D 1; + } elsif ($cmd eq 'enable-lineno') { + $enable_lineno =3D 1; + } elsif ($cmd eq 'show-not-found') { + $show_not_found =3D 1; # A no-op but don't fail + } else { + # Unknown argument + usage(); + } +} + +# continue execution near EOF; + +# get kernel version from env +sub get_kernel_version() { + my $version =3D 'unknown kernel version'; + + if (defined($ENV{'KERNELVERSION'})) { + $version =3D $ENV{'KERNELVERSION'}; + } + return $version; +} + +# +sub print_lineno { + my $lineno =3D 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 =3D shift; + my $name =3D shift; + my $contents =3D join "\n", @_; + + if ($name =3D~ m/$type_param/) { + $name =3D $1; + $parameterdescs{$name} =3D $contents; + $sectcheck =3D $sectcheck . $name . " "; + $parameterdesc_start_lines{$name} =3D $new_start_line; + $new_start_line =3D 0; + } elsif ($name eq "@\.\.\.") { + $name =3D "..."; + $parameterdescs{$name} =3D $contents; + $sectcheck =3D $sectcheck . $name . " "; + $parameterdesc_start_lines{$name} =3D $new_start_line; + $new_start_line =3D 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} .=3D $contents; + } else { + $sections{$name} =3D $contents; + push @sectionlist, $name; + $section_start_lines{$name} =3D $new_start_line; + $new_start_line =3D 0; + } + } +} + +## +# dump DOC: section after checking that it should go out +# +sub dump_doc_section { + my $file =3D shift; + my $name =3D shift; + my $contents =3D join "\n", @_; + + if ($no_doc_sections) { + return; + } + + if (($output_selection =3D=3D OUTPUT_ALL) || + ($output_selection =3D=3D OUTPUT_INCLUDE && + defined($function_table{$name})) || + ($output_selection =3D=3D OUTPUT_EXCLUDE && + !defined($function_table{$name}))) + { + dump_section($file, $name, $contents); + output_blockhead({'sectionlist' =3D> \@sectionlist, + 'sections' =3D> \%sections, + 'module' =3D> $modulename, + 'content-only' =3D> ($output_selection !=3D OUTPUT_ALL), }); + } +} + +## +# output function +# +# parameterdescs, a hash. +# function =3D> "function name" +# parameterlist =3D> @list of parameters +# parameterdescs =3D> %parameter descriptions +# sectionlist =3D> @list of sections +# sections =3D> %section descriptions +# + +sub output_highlight { + my $contents =3D 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 =3D~ 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 =3D %{$_[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 =3D 0; + my $parenth =3D "("; + my $post =3D ","; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count =3D=3D $#{$args{'parameterlist'}}) { + $post =3D ");"; + } + $type =3D $args{'parametertypes'}{$parameter}; + if ($type =3D~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 .= ")" . $post . "\"\n"; + } else { + $type =3D~ s/([^\*])$/$1 /; + print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $pos= t . "\"\n"; + } + $count++; + $parenth =3D ""; + } + + print ".SH ARGUMENTS\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name =3D $parameter; + $parameter_name =3D~ 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 =3D %{$_[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 =3D 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + print ".br\n.BI \" $parameter\"\n"; + if ($count =3D=3D $#{$args{'parameterlist'}}) { + print "\n};\n"; + last; + } + else { + print ", \n.br\n"; + } + $count++; + } + + print ".SH Constants\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name =3D $parameter; + $parameter_name =3D~ 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 =3D %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'st= ruct'} . "\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose= '} . "\n"; + + my $declaration =3D $args{'definition'}; + $declaration =3D~ s/\t/ /g; + $declaration =3D~ 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 =3D~ /^#/) && next; + + my $parameter_name =3D $parameter; + $parameter_name =3D~ 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 =3D %{$_[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 =3D %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"A= PI 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 =3D %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + if ($output_selection !=3D 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 =3D shift; + eval $dohighlight; + die $@ if $@; + return $contents; +} + +# +# Regexes used only here. +# +my $sphinx_literal =3D '^[^.].*::$'; +my $sphinx_cblock =3D '^\.\.\ +code-block::'; + +sub output_highlight_rst { + my $input =3D join "\n",@_; + my $output =3D ""; + my $line; + my $in_literal =3D 0; + my $litprefix; + my $block =3D ""; + + 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 =3D~ /^\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 =3D~ /^(\s*)/; + $litprefix =3D '^' . $1; + $output .=3D $line . "\n"; + } elsif (! ($line =3D~ /$litprefix/)) { + $in_literal =3D 0; + } else { + $output .=3D $line . "\n"; + } + } else { + $output .=3D $line . "\n"; + } + } + # + # Not in a literal block (or just dropped out) + # + if (! $in_literal) { + $block .=3D $line . "\n"; + if (($line =3D~ /$sphinx_literal/) || ($line =3D~ /$sphinx_cblock/)) { + $in_literal =3D 1; + $litprefix =3D ""; + $output .=3D highlight_block($block); + $block =3D "" + } + } + } + + if ($block) { + $output .=3D highlight_block($block); + } + foreach $line (split "\n", $output) { + print $lineprefix . $line . "\n"; + } +} + +sub output_function_rst(%) { + my %args =3D %{$_[0]}; + my ($parameter, $section); + my $oldprefix =3D $lineprefix; + my $start =3D ""; + + if ($args{'typedef'}) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix =3D ""; + output_highlight_rst($args{'purpose'}); + $start =3D "\n\n**Syntax**\n\n ``"; + } else { + print ".. c:function:: "; + } + if ($args{'functiontype'} ne "") { + $start .=3D $args{'functiontype'} . " " . $args{'function'} . " ("; + } else { + $start .=3D $args{'function'} . " ("; + } + print $start; + + my $count =3D 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count ne 0) { + print ", "; + } + $count++; + $type =3D $args{'parametertypes'}{$parameter}; + + if ($type =3D~ 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 =3D " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + } + + print "**Parameters**\n\n"; + $lineprefix =3D " "; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name =3D $parameter; + $parameter_name =3D~ s/\[.*//; + $type =3D $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 =3D $oldprefix; + output_section_rst(@_); +} + +sub output_section_rst(%) { + my %args =3D %{$_[0]}; + my $section; + my $oldprefix =3D $lineprefix; + $lineprefix =3D ""; + + 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 =3D $oldprefix; +} + +sub output_enum_rst(%) { + my %args =3D %{$_[0]}; + my ($parameter); + my $oldprefix =3D $lineprefix; + my $count; + my $name =3D "enum " . $args{'enum'}; + + print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); + $lineprefix =3D " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + + print "**Constants**\n\n"; + $lineprefix =3D " "; + 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 =3D $oldprefix; + output_section_rst(@_); +} + +sub output_typedef_rst(%) { + my %args =3D %{$_[0]}; + my ($parameter); + my $oldprefix =3D $lineprefix; + my $name =3D "typedef " . $args{'typedef'}; + + print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); + $lineprefix =3D " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + + $lineprefix =3D $oldprefix; + output_section_rst(@_); +} + +sub output_struct_rst(%) { + my %args =3D %{$_[0]}; + my ($parameter); + my $oldprefix =3D $lineprefix; + my $name =3D $args{'type'} . " " . $args{'struct'}; + + print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); + $lineprefix =3D " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + + print "**Definition**\n\n"; + print "::\n\n"; + my $declaration =3D $args{'definition'}; + $declaration =3D~ s/\t/ /g; + print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration= };\n\n"; + + print "**Members**\n\n"; + $lineprefix =3D " "; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =3D~ /^#/) && next; + + my $parameter_name =3D $parameter; + $parameter_name =3D~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type =3D $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 =3D $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 =3D shift; + my $functype =3D shift; + my $func =3D "output_${functype}_$output_mode"; + if (($output_selection =3D=3D OUTPUT_ALL) || + (($output_selection =3D=3D OUTPUT_INCLUDE || + $output_selection =3D=3D OUTPUT_EXPORTED) && + defined($function_table{$name})) || + (($output_selection =3D=3D OUTPUT_EXCLUDE || + $output_selection =3D=3D OUTPUT_INTERNAL) && + !($functype eq "function" && defined($function_table{$name})))) + { + &$func(@_); + $section_counter++; + } +} + +## +# generic output function - calls the right one based on current output mo= de. +sub output_blockhead { + no strict 'refs'; + my $func =3D "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) =3D @_; + my $func =3D "dump_" . $decl_type; + &$func(@_); +} + +sub dump_union($$) { + dump_struct(@_); +} + +sub dump_struct($$) { + my $x =3D shift; + my $file =3D shift; + + if ($x =3D~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|= __attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { + my $decl_type =3D $1; + $declaration_name =3D $2; + my $members =3D $3; + + # ignore members marked private: + $members =3D~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; + $members =3D~ s/\/\*\s*private:.*//gosi; + # strip comments: + $members =3D~ s/\/\*.*?\*\///gos; + # strip attributes + $members =3D~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi; + $members =3D~ s/\s*__aligned\s*\([^;]*\)//gos; + $members =3D~ s/\s*__packed\s*//gos; + $members =3D~ s/\s*CRYPTO_MINALIGN_ATTR//gos; + # replace DECLARE_BITMAP + $members =3D~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $= 1\[BITS_TO_LONGS($2)\]/gos; + # replace DECLARE_HASHTABLE + $members =3D~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned lon= g $1\[1 << (($2) - 1)\]/gos; + # replace DECLARE_KFIFO + $members =3D~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \= *$1/gos; + # replace DECLARE_KFIFO_PTR + $members =3D~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; + + my $declaration =3D $members; + + # Split nested struct/union elements as newer ones + while ($members =3D~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*= )\;/) { + my $newmember; + my $maintype =3D $1; + my $ids =3D $4; + my $content =3D $3; + foreach my $id(split /,/, $ids) { + $newmember .=3D "$maintype $id; "; + + $id =3D~ s/[:\[].*//; + $id =3D~ s/^\s*\**(\S+)\s*/$1/; + foreach my $arg (split /;/, $content) { + next if ($arg =3D~ m/^\s*$/); + if ($arg =3D~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) { + # pointer-to-function + my $type =3D $1; + my $name =3D $2; + my $extra =3D $3; + next if (!$name); + if ($id =3D~ m/^\s*$/) { + # anonymous struct/union + $newmember .=3D "$type$name$extra; "; + } else { + $newmember .=3D "$type$id.$name$extra; "; + } + } else { + my $type; + my $names; + $arg =3D~ s/^\s+//; + $arg =3D~ s/\s+$//; + # Handle bitmaps + $arg =3D~ s/:\s*\d+\s*//g; + # Handle arrays + $arg =3D~ 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 =3D~ s/\s*,\s*/,/g; + if ($arg =3D~ m/(.*)\s+([\S+,]+)/) { + $type =3D $1; + $names =3D $2; + } else { + $newmember .=3D "$arg; "; + next; + } + foreach my $name (split /,/, $names) { + $name =3D~ s/^\s*\**(\S+)\s*/$1/; + next if (($name =3D~ m/^\s*$/)); + if ($id =3D~ m/^\s*$/) { + # anonymous struct/union + $newmember .=3D "$type $name; "; + } else { + $newmember .=3D "$type $id.$name; "; + } + } + } + } + } + $members =3D~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$n= ewmember/; + } + + # Ignore other nested elements, like enums + $members =3D~ s/(\{[^\{\}]*\})//g; + + create_parameterlist($members, ';', $file, $declaration_name); + check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_= actual); + + # Adjust declaration for better display + $declaration =3D~ s/([\{;])/$1\n/g; + $declaration =3D~ s/\}\s+;/};/g; + # Better handle inlined enums + do {} while ($declaration =3D~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/); + + my @def_args =3D split /\n/, $declaration; + my $level =3D 1; + $declaration =3D ""; + foreach my $clause (@def_args) { + $clause =3D~ s/^\s+//; + $clause =3D~ s/\s+$//; + $clause =3D~ s/\s+/ /; + next if (!$clause); + $level-- if ($clause =3D~ m/(\})/ && $level > 1); + if (!($clause =3D~ m/^\s*#/)) { + $declaration .=3D "\t" x $level; + } + $declaration .=3D "\t" . $clause . "\n"; + $level++ if ($clause =3D~ m/(\{)/ && !($clause =3D~m/\}/)); + } + output_declaration($declaration_name, + 'struct', + {'struct' =3D> $declaration_name, + 'module' =3D> $modulename, + 'definition' =3D> $declaration, + 'parameterlist' =3D> \@parameterlist, + 'parameterdescs' =3D> \%parameterdescs, + 'parametertypes' =3D> \%parametertypes, + 'sectionlist' =3D> \@sectionlist, + 'sections' =3D> \%sections, + 'purpose' =3D> $declaration_purpose, + 'type' =3D> $decl_type + }); + } + else { + print STDERR "${file}:$.: error: Cannot parse struct or union!\n"; + ++$errors; + } +} + + +sub show_warnings($$) { + my $functype =3D shift; + my $name =3D shift; + + return 1 if ($output_selection =3D=3D OUTPUT_ALL); + + if ($output_selection =3D=3D OUTPUT_EXPORTED) { + if (defined($function_table{$name})) { + return 1; + } else { + return 0; + } + } + if ($output_selection =3D=3D OUTPUT_INTERNAL) { + if (!($functype eq "function" && defined($function_table{$name}))) { + return 1; + } else { + return 0; + } + } + if ($output_selection =3D=3D OUTPUT_INCLUDE) { + if (defined($function_table{$name})) { + return 1; + } else { + return 0; + } + } + if ($output_selection =3D=3D 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 =3D shift; + my $file =3D shift; + + $x =3D~ s@/\*.*?\*/@@gos; # strip comments. + # strip #define macros inside enums + $x =3D~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; + + if ($x =3D~ /enum\s+(\w*)\s*\{(.*)\}/) { + $declaration_name =3D $1; + my $members =3D $2; + my %_members; + + $members =3D~ s/\s+$//; + + foreach my $arg (split ',', $members) { + $arg =3D~ s/^\s*(\w+).*/$1/; + push @parameterlist, $arg; + if (!$parameterdescs{$arg}) { + $parameterdescs{$arg} =3D $undescribed; + if (show_warnings("enum", $declaration_name)) { + print STDERR "${file}:$.: warning: Enum value '$arg' not described in e= num '$declaration_name'\n"; + } + } + $_members{$arg} =3D 1; + } + + while (my ($k, $v) =3D each %parameterdescs) { + if (!exists($_members{$k})) { + if (show_warnings("enum", $declaration_name)) { + print STDERR "${file}:$.: warning: Excess enum value '$k' descripti= on in '$declaration_name'\n"; + } + } + } + + output_declaration($declaration_name, + 'enum', + {'enum' =3D> $declaration_name, + 'module' =3D> $modulename, + 'parameterlist' =3D> \@parameterlist, + 'parameterdescs' =3D> \%parameterdescs, + 'sectionlist' =3D> \@sectionlist, + 'sections' =3D> \%sections, + 'purpose' =3D> $declaration_purpose + }); + } + else { + print STDERR "${file}:$.: error: Cannot parse enum!\n"; + ++$errors; + } +} + +sub dump_typedef($$) { + my $x =3D shift; + my $file =3D shift; + + $x =3D~ s@/\*.*?\*/@@gos; # strip comments. + + # Parse function prototypes + if ($x =3D~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ || + $x =3D~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) { + + # Function typedefs + $return_type =3D $1; + $declaration_name =3D $2; + my $args =3D $3; + + create_parameterlist($args, ',', $file, $declaration_name); + + output_declaration($declaration_name, + 'function', + {'function' =3D> $declaration_name, + 'typedef' =3D> 1, + 'module' =3D> $modulename, + 'functiontype' =3D> $return_type, + 'parameterlist' =3D> \@parameterlist, + 'parameterdescs' =3D> \%parameterdescs, + 'parametertypes' =3D> \%parametertypes, + 'sectionlist' =3D> \@sectionlist, + 'sections' =3D> \%sections, + 'purpose' =3D> $declaration_purpose + }); + return; + } + + while (($x =3D~ /\(*.\)\s*;$/) || ($x =3D~ /\[*.\]\s*;$/)) { + $x =3D~ s/\(*.\)\s*;$/;/; + $x =3D~ s/\[*.\]\s*;$/;/; + } + + if ($x =3D~ /typedef.*\s+(\w+)\s*;/) { + $declaration_name =3D $1; + + output_declaration($declaration_name, + 'typedef', + {'typedef' =3D> $declaration_name, + 'module' =3D> $modulename, + 'sectionlist' =3D> \@sectionlist, + 'sections' =3D> \%sections, + 'purpose' =3D> $declaration_purpose + }); + } + else { + print STDERR "${file}:$.: error: Cannot parse typedef!\n"; + ++$errors; + } +} + +sub save_struct_actual($) { + my $actual =3D shift; + + # strip all spaces from the actual param so that it looks like one str= ing item + $actual =3D~ s/\s*//g; + $struct_actual =3D $struct_actual . $actual . " "; +} + +sub create_parameterlist($$$$) { + my $args =3D shift; + my $splitter =3D shift; + my $file =3D shift; + my $declaration_name =3D shift; + my $type; + my $param; + + # temporarily replace commas inside function pointer definition + while ($args =3D~ /(\([^\),]+),/) { + $args =3D~ s/(\([^\),]+),/$1#/g; + } + + foreach my $arg (split($splitter, $args)) { + # strip comments + $arg =3D~ s/\/\*.*\*\///; + # strip leading/trailing spaces + $arg =3D~ s/^\s*//; + $arg =3D~ s/\s*$//; + $arg =3D~ s/\s+/ /; + + if ($arg =3D~ /^#/) { + # 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 =3D~ m/\(.+\)\s*\(/) { + # pointer-to-function + $arg =3D~ tr/#/,/; + $arg =3D~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/; + $param =3D $1; + $type =3D $arg; + $type =3D~ s/([^\(]+\(\*?)\s*$param/$1/; + save_struct_actual($param); + push_parameter($param, $type, $file, $declaration_name); + } elsif ($arg) { + $arg =3D~ s/\s*:\s*/:/g; + $arg =3D~ s/\s*\[/\[/g; + + my @args =3D split('\s*,\s*', $arg); + if ($args[0] =3D~ m/\*/) { + $args[0] =3D~ s/(\*+)\s*/ $1/; + } + + my @first_arg; + if ($args[0] =3D~ /^(.*\s+)(.*?\[.*\].*)$/) { + shift @args; + push(@first_arg, split('\s+', $1)); + push(@first_arg, $2); + } else { + @first_arg =3D split('\s+', shift @args); + } + + unshift(@args, pop @first_arg); + $type =3D join " ", @first_arg; + + foreach $param (@args) { + if ($param =3D~ m/^(\*+)\s*(.*)/) { + save_struct_actual($2); + push_parameter($2, "$type $1", $file, $declaration_name); + } + elsif ($param =3D~ 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 =3D shift; + my $type =3D shift; + my $file =3D shift; + my $declaration_name =3D shift; + + if (($anon_struct_union =3D=3D 1) && ($type eq "") && + ($param eq "}")) { + return; # ignore the ending }; from anon. struct/union + } + + $anon_struct_union =3D 0; + $param =3D~ s/[\[\)].*//; + + if ($type eq "" && $param =3D~ /\.\.\.$/) + { + if (!$param =3D~ /\w\.\.\.$/) { + # handles unnamed variable parameters + $param =3D "..."; + } + if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq ""= ) { + $parameterdescs{$param} =3D "variable arguments"; + } + } + elsif ($type eq "" && ($param eq "" or $param eq "void")) + { + $param=3D"void"; + $parameterdescs{void} =3D "no arguments"; + } + elsif ($type eq "" && ($param eq "struct" or $param eq "union")) + # handle unnamed (anonymous) union or struct: + { + $type =3D $param; + $param =3D "{unnamed_" . $param . "}"; + $parameterdescs{$param} =3D "anonymous\n"; + $anon_struct_union =3D 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} =3D $undescribed; + + if (show_warnings($type, $declaration_name) && $param !~ /\./) { + print STDERR + "${file}:$.: warning: Function parameter or member '$param' not d= escribed 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 =3D~ s/\s*//g; + push @parameterlist, $param; + $type =3D~ s/\s\s+/ /g; + $parametertypes{$param} =3D $type; +} + +sub check_sections($$$$$) { + my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) =3D @_; + my @sects =3D split ' ', $sectcheck; + my @prms =3D split ' ', $prmscheck; + my $err; + my ($px, $sx); + my $prm_clean; # strip trailing "[array size]" and/or beginning "*" + + foreach $sx (0 .. $#sects) { + $err =3D 1; + foreach $px (0 .. $#prms) { + $prm_clean =3D $prms[$px]; + $prm_clean =3D~ s/\[.*\]//; + $prm_clean =3D~ 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 =3D~ s/\[.*//; + + ##$prm_clean =3D~ s/^\**//; + if ($prm_clean eq $sects[$sx]) { + $err =3D 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 =3D shift; + my $declaration_name =3D shift; + my $return_type =3D shift; + + # Ignore an empty return type (It's a macro) + # Ignore functions with a "void" return type. (But don't ignore "v= oid *") + if (($return_type eq "") || ($return_type =3D~ /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 =3D shift; + my $file =3D shift; + my $noret =3D 0; + + $prototype =3D~ s/^static +//; + $prototype =3D~ s/^extern +//; + $prototype =3D~ s/^asmlinkage +//; + $prototype =3D~ s/^inline +//; + $prototype =3D~ s/^__inline__ +//; + $prototype =3D~ s/^__inline +//; + $prototype =3D~ s/^__always_inline +//; + $prototype =3D~ s/^noinline +//; + $prototype =3D~ s/__init +//; + $prototype =3D~ s/__init_or_module +//; + $prototype =3D~ s/__meminit +//; + $prototype =3D~ s/__must_check +//; + $prototype =3D~ s/__weak +//; + $prototype =3D~ s/__sched +//; + $prototype =3D~ s/__printf\s*\(\s*\d*\s*,\s*\d*\s*\) +//; + my $define =3D $prototype =3D~ s/^#\s*define\s+//; #ak added + $prototype =3D~ 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 =3D~ m/^()([a-zA-Z0-9_~:]+)\s+/) { + # This is an object-like macro, it has no return type and no param= eter + # list. + # Function-like macros are not allowed to have spaces between + # declaration_name and opening parenthesis (notice the \s+). + $return_type =3D $1; + $declaration_name =3D $2; + $noret =3D 1; + } elsif ($prototype =3D~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =3D~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =3D~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =3D~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =3D~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ = || + $prototype =3D~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ = || + $prototype =3D~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]= *)\)/ || + $prototype =3D~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =3D~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =3D~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =3D~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =3D~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ = || + $prototype =3D~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ = || + $prototype =3D~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]= *)\)/ || + $prototype =3D~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]= *)\)/ || + $prototype =3D~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(= ([^\{]*)\)/ || + $prototype =3D~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s= *\(([^\{]*)\)/) { + $return_type =3D $1; + $declaration_name =3D $2; + my $args =3D $3; + + create_parameterlist($args, ',', $file, $declaration_name); + } else { + print STDERR "${file}:$.: warning: cannot understand function prototype: = '$prototype'\n"; + return; + } + + my $prms =3D 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_typ= e); + } + + output_declaration($declaration_name, + 'function', + {'function' =3D> $declaration_name, + 'module' =3D> $modulename, + 'functiontype' =3D> $return_type, + 'parameterlist' =3D> \@parameterlist, + 'parameterdescs' =3D> \%parameterdescs, + 'parametertypes' =3D> \%parametertypes, + 'sectionlist' =3D> \@sectionlist, + 'sections' =3D> \%sections, + 'purpose' =3D> $declaration_purpose + }); +} + +sub reset_state { + $function =3D ""; + %parameterdescs =3D (); + %parametertypes =3D (); + @parameterlist =3D (); + %sections =3D (); + @sectionlist =3D (); + $sectcheck =3D ""; + $struct_actual =3D ""; + $prototype =3D ""; + + $state =3D STATE_NORMAL; + $inline_doc_state =3D STATE_INLINE_NA; +} + +sub tracepoint_munge($) { + my $file =3D shift; + my $tracepointname =3D 0; + my $tracepointargs =3D 0; + + if ($prototype =3D~ m/TRACE_EVENT\((.*?),/) { + $tracepointname =3D $1; + } + if ($prototype =3D~ m/DEFINE_SINGLE_EVENT\((.*?),/) { + $tracepointname =3D $1; + } + if ($prototype =3D~ m/DEFINE_EVENT\((.*?),(.*?),/) { + $tracepointname =3D $2; + } + $tracepointname =3D~ s/^\s+//; #strip leading whitespace + if ($prototype =3D~ m/TP_PROTO\((.*?)\)/) { + $tracepointargs =3D $1; + } + if (($tracepointname eq 0) || ($tracepointargs eq 0)) { + print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n". + "$prototype\n"; + } else { + $prototype =3D "static inline void trace_$tracepointname($tracepointargs= )"; + } +} + +sub syscall_munge() { + my $void =3D 0; + + $prototype =3D~ s@[\r\n]+@ @gos; # strip newlines/CR's +## if ($prototype =3D~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) { + if ($prototype =3D~ m/SYSCALL_DEFINE0/) { + $void =3D 1; +## $prototype =3D "long sys_$1(void)"; + } + + $prototype =3D~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func= name + if ($prototype =3D~ m/long (sys_.*?),/) { + $prototype =3D~ s/,/\(/; + } elsif ($void) { + $prototype =3D~ 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 =3D 0; + my $len =3D length($prototype); + if ($void) { + $len =3D 0; # skip the for-loop + } + for (my $ix =3D 0; $ix < $len; $ix++) { + if (substr($prototype, $ix, 1) eq ',') { + $count++; + if ($count % 2 =3D=3D 1) { + substr($prototype, $ix, 1) =3D ' '; + } + } + } +} + +sub process_proto_function($$) { + my $x =3D shift; + my $file =3D shift; + + $x =3D~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =3D~ m#\s*/\*\s+MACDOC\s*#io || ($x =3D~ /^#/ && $x !~ /^#\s*de= fine/)) { + # do nothing + } + elsif ($x =3D~ /([^\{]*)/) { + $prototype .=3D $1; + } + + if (($x =3D~ /\{/) || ($x =3D~ /\#\s*define/) || ($x =3D~ /;/)) { + $prototype =3D~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =3D~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =3D~ s@^\s+@@gos; # strip leading spaces + if ($prototype =3D~ /SYSCALL_DEFINE/) { + syscall_munge(); + } + if ($prototype =3D~ /TRACE_EVENT/ || $prototype =3D~ /DEFINE_EVENT/ || + $prototype =3D~ /DEFINE_SINGLE_EVENT/) + { + tracepoint_munge($file); + } + dump_function($prototype, $file); + reset_state(); + } +} + +sub process_proto_type($$) { + my $x =3D shift; + my $file =3D shift; + + $x =3D~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $x =3D~ s@^\s+@@gos; # strip leading spaces + $x =3D~ s@\s+$@@gos; # strip trailing spaces + $x =3D~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =3D~ /^#/) { + # To distinguish preprocessor directive from regular declaration later. + $x .=3D ";"; + } + + while (1) { + if ( $x =3D~ /([^\{\};]*)([\{\};])(.*)/ ) { + if( length $prototype ) { + $prototype .=3D " " + } + $prototype .=3D $1 . $2; + ($2 eq '{') && $brcount++; + ($2 eq '}') && $brcount--; + if (($2 eq ';') && ($brcount =3D=3D 0)) { + dump_declaration($prototype, $file); + reset_state(); + last; + } + $x =3D $3; + } else { + $prototype .=3D $x; + last; + } + } +} + + +sub map_filename($) { + my $file; + my ($orig_file) =3D @_; + + if (defined($ENV{'SRCTREE'})) { + $file =3D "$ENV{'SRCTREE'}" . "/" . $orig_file; + } else { + $file =3D $orig_file; + } + + if (defined($source_map{$file})) { + $file =3D $source_map{$file}; + } + + return $file; +} + +sub process_export_file($) { + my ($orig_file) =3D @_; + my $file =3D map_filename($orig_file); + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + while () { + if (/$export_symbol/) { + $function_table{$2} =3D 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 =3D STATE_NAME; # next line is always the function name + $in_doc_sect =3D 0; + $declaration_start_line =3D $. + 1; + } +} + +# +# STATE_NAME: Looking for the "name - description" line +# +sub process_name($$) { + my $file =3D shift; + my $identifier; + my $descr; + + if (/$doc_block/o) { + $state =3D STATE_DOCBLOCK; + $contents =3D ""; + $new_start_line =3D $. + 1; + + if ( $1 eq "" ) { + $section =3D $section_intro; + } else { + $section =3D $1; + } + } + elsif (/$doc_decl/o) { + $identifier =3D $1; + if (/\s*([\w\s]+?)(\(\))?\s*-/) { + $identifier =3D $1; + } + + $state =3D STATE_BODY; + # if there's no @param blocks need to set up default section + # here + $contents =3D ""; + $section =3D $section_default; + $new_start_line =3D $. + 1; + if (/-(.*)/) { + # strip leading/trailing/multiple spaces + $descr=3D $1; + $descr =3D~ s/^\s*//; + $descr =3D~ s/\s*$//; + $descr =3D~ s/\s+/ /g; + $declaration_purpose =3D $descr; + $state =3D STATE_BODY_MAYBE; + } else { + $declaration_purpose =3D ""; + } + + if (($declaration_purpose eq "") && $verbose) { + print STDERR "${file}:$.: warning: missing initial short description = on line:\n"; + print STDERR $_; + ++$warnings; + } + + if ($identifier =3D~ m/^struct\b/) { + $decl_type =3D 'struct'; + } elsif ($identifier =3D~ m/^union\b/) { + $decl_type =3D 'union'; + } elsif ($identifier =3D~ m/^enum\b/) { + $decl_type =3D 'enum'; + } elsif ($identifier =3D~ m/^typedef\b/) { + $decl_type =3D 'typedef'; + } else { + $decl_type =3D '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 =3D STATE_NORMAL; + } +} + + +# +# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. +# +sub process_body($$) { + my $file =3D shift; + + if (/$doc_sect/i) { # case insensitive for supported section names + $newsection =3D $1; + $newcontents =3D $2; + + # map the supported section names to the canonical names + if ($newsection =3D~ m/^description$/i) { + $newsection =3D $section_default; + } elsif ($newsection =3D~ m/^context$/i) { + $newsection =3D $section_context; + } elsif ($newsection =3D~ m/^returns?$/i) { + $newsection =3D $section_return; + } elsif ($newsection =3D~ m/^\@return$/) { + # special: @return is a section, not a param description + $newsection =3D $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 =3D $section_default; + } + + $in_doc_sect =3D 1; + $state =3D STATE_BODY; + $contents =3D $newcontents; + $new_start_line =3D $.; + while (substr($contents, 0, 1) eq " ") { + $contents =3D substr($contents, 1); + } + if ($contents ne "") { + $contents .=3D "\n"; + } + $section =3D $newsection; + $leading_space =3D undef; + } elsif (/$doc_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section =3D $section_default; + $contents =3D ""; + } + # look for doc_com + + doc_end: + if ($_ =3D~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { + print STDERR "${file}:$.: warning: suspicious ending line: $_"; + ++$warnings; + } + + $prototype =3D ""; + $state =3D STATE_PROTO; + $brcount =3D 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 =3D~ m/^@/ || $section eq $section_context) { + dump_section($file, $section, $contents); + $section =3D $section_default; + $contents =3D ""; + $new_start_line =3D $.; + } else { + $contents .=3D "\n"; + } + $state =3D STATE_BODY; + } elsif ($state =3D=3D STATE_BODY_MAYBE) { + # Continued declaration purpose + chomp($declaration_purpose); + $declaration_purpose .=3D " " . $1; + $declaration_purpose =3D~ s/\s+/ /g; + } else { + my $cont =3D $1; + if ($section =3D~ m/^@/ || $section eq $section_context) { + if (!defined $leading_space) { + if ($cont =3D~ m/^(\s+)/) { + $leading_space =3D $1; + } else { + $leading_space =3D ""; + } + } + $cont =3D~ s/^$leading_space//; + } + $contents .=3D $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 =3D shift; + + if (/$doc_inline_oneline/) { + $section =3D $1; + $contents =3D $2; + if ($contents ne "") { + $contents .=3D "\n"; + dump_section($file, $section, $contents); + $section =3D $section_default; + $contents =3D ""; + } + } elsif (/$doc_inline_start/) { + $state =3D STATE_INLINE; + $inline_doc_state =3D 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 =3D shift; + + if (/$doc_end/) { + dump_doc_section($file, $section, $contents); + $section =3D $section_default; + $contents =3D ""; + $function =3D ""; + %parameterdescs =3D (); + %parametertypes =3D (); + @parameterlist =3D (); + %sections =3D (); + @sectionlist =3D (); + $prototype =3D ""; + $state =3D STATE_NORMAL; + } elsif (/$doc_content/) { + if ( $1 eq "" ) { + $contents .=3D $blankline; + } else { + $contents .=3D $1 . "\n"; + } + } +} + +# +# STATE_INLINE: docbook comments within a prototype. +# +sub process_inline($$) { + my $file =3D shift; + + # First line (state 1) needs to be a @parameter + if ($inline_doc_state =3D=3D STATE_INLINE_NAME && /$doc_inline_sect/o)= { + $section =3D $1; + $contents =3D $2; + $new_start_line =3D $.; + if ($contents ne "") { + while (substr($contents, 0, 1) eq " ") { + $contents =3D substr($contents, 1); + } + $contents .=3D "\n"; + } + $inline_doc_state =3D STATE_INLINE_TEXT; + # Documentation block end */ + } elsif (/$doc_inline_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section =3D $section_default; + $contents =3D ""; + } + $state =3D STATE_PROTO; + $inline_doc_state =3D STATE_INLINE_NA; + # Regular text + } elsif (/$doc_content/) { + if ($inline_doc_state =3D=3D STATE_INLINE_TEXT) { + $contents .=3D $1 . "\n"; + # nuke leading blank lines + if ($contents =3D~ /^\s*$/) { + $contents =3D ""; + } + } elsif ($inline_doc_state =3D=3D STATE_INLINE_NAME) { + $inline_doc_state =3D 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 =3D $section_counter; + my ($orig_file) =3D @_; + + $file =3D map_filename($orig_file); + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + $. =3D 1; + + $section_counter =3D 0; + while () { + while (s/\\\s*$//) { + $_ .=3D ; + } + # Replace tabs by spaces + while ($_ =3D~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; + # Hand this line to the appropriate state handler + if ($state =3D=3D STATE_NORMAL) { + process_normal(); + } elsif ($state =3D=3D STATE_NAME) { + process_name($file, $_); + } elsif ($state =3D=3D STATE_BODY || $state =3D=3D STATE_BODY_MAYBE) { + process_body($file, $_); + } elsif ($state =3D=3D STATE_INLINE) { # scanning for inline parameters + process_inline($file, $_); + } elsif ($state =3D=3D STATE_PROTO) { + process_proto($file, $_); + } elsif ($state =3D=3D STATE_DOCBLOCK) { + process_docblock($file, $_); + } + } + + # Make sure we got something interesting. + if ($initial_section_counter =3D=3D $section_counter && $ + output_mode ne "none") { + if ($output_selection =3D=3D OUTPUT_INCLUDE) { + print STDERR "${file}:1: warning: '$_' not found\n" + for keys %function_table; + } + else { + print STDERR "${file}:1: warning: no structured comments found\n"; + } + } +} + + +$kernelversion =3D get_kernel_version(); + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +for (my $k =3D 0; $k < @highlights; $k++) { + my $pattern =3D $highlights[$k][0]; + my $result =3D $highlights[$k][1]; +# print STDERR "scanning pattern:$pattern, highlight:($result)\n"; + $dohighlight .=3D "\$contents =3D~ 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() { + chop(); + ($relname, $absname) =3D (split())[0..1]; + $relname =3D~ s:^/+::; + $source_map{$relname} =3D $absname; + } + close(SOURCE_MAP); +} + +if ($output_selection =3D=3D OUTPUT_EXPORTED || + $output_selection =3D=3D 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); --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575036394; cv=none; d=zohomail.com; s=zohoarc; b=c8eP6f5Mmgfq4YKtPTX4dmVlLnT5QLv5KzCxQob23W5svPfIEYbPNjXWDuPGDHUluPTOq3HKS4mY2a76yWqJ8fZtfVLQpZCBZgTO5UQq+6EpFlkeHWn9CVvQEy3ik9UHys4vwsotuPvoG3dRhTXSGOdVUYdKyh9xA5FVcALXn0g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575036394; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=GITb2fVxR4h7bhXASG9JI0LI0GYSIzOlpGLPA3IIb7s=; b=B0ic776N0whgW3u/R65VDsNg8cEr1sRKEucsolxQ21JexsxmipfseWCIJNQSefMegivlnM8ex/X8GrA4R+FPLBVkRAbgDOiMoSy5BOUj4iPsrzh1b6NxeadApsbFyUCF/Su5G22dyvlronalrQ6W85REL7fLwmzOueyerMNEvLA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575036394729246.23360512775923; Fri, 29 Nov 2019 06:06:34 -0800 (PST) Received: from localhost ([::1]:59510 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagum-0003tA-Dd for importer@patchew.org; Fri, 29 Nov 2019 09:06:32 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37046) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagqq-00022S-7x for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:29 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqm-0003Lc-Vm for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:27 -0500 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:39876) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagql-0003GP-GW for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:24 -0500 Received: by mail-wr1-x441.google.com with SMTP id y11so32194906wrt.6 for ; Fri, 29 Nov 2019 06:02:22 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:20 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=GITb2fVxR4h7bhXASG9JI0LI0GYSIzOlpGLPA3IIb7s=; b=BtCZJWTy83YusnG4CVFiGPT8sh8Ir2hKiWbxTImDaD7IbNKb1WeTZkBhm0QKl3hyJC mV0VmrZNiFUizECkEes+pqJ3C+Q8TV9t8FrOtjM/RdBHzL4qANIXMY149FXyxaB/8Lbb Elqrqfsr9JF+Hvf/9dkMjbnlM0xamfGOZTBiqrOKgOoazFEpSMJU4fXxMzBKTuTKA2AA 2TNpOKffEXGrbD5YORdGiH7vgctjuxr6ZHDrxHZrcOsIHFhHGmLkTNzPk6j6STaWw9XQ u9/c9lpyHu7a9LFHCRGiNkKnQUbrYuFFXbKJqQQs5relNBqrdrnmiKvxVilTIaOSv+si N1ZQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=GITb2fVxR4h7bhXASG9JI0LI0GYSIzOlpGLPA3IIb7s=; b=sOWBDEFrIZ090gxzZjrt+D92O/YuMgUwyH6Cqr4/P+Ia4sE9Hlg4GVc7xwADaV91pT 5QSKYQY4q4nIuYj9XOIvXOZXTl+RRIipXRWn5cKoYj+fNWfoeqxW3w7BLTeGuHMsjsxT yANR1ebvhqg/1CQ9epC1xVNxEQyYieNaqa49KoZs1Z8ThIjeBdkqv1urto166IDZQtw5 AU41z+UtnKnd0ChqHfX/4d1Zy25G0oKDJsT16vn2Kh4KV71QKDOSD+PTFkz9dLioIPUe Fdu6K/tKKD3mtccFTjhBfYAOF/G3oRxweSLwgBgsdN3NnRggp0Ap3iEfnGhe4GuC63q6 sd2Q== X-Gm-Message-State: APjAAAXalXKEvOsBU3y7mPtwk4hAcFjniKp1jOYQxmIq8xwqnJlw3XbW rjozjQPPQ7YIX3/VNXupEqjhVF7m X-Google-Smtp-Source: APXvYqw160vQLb3isYSsvCCQqbqH5wYFoSNDhtpGMfItvozNk7Z/QqoHJbfJtSM0lK9S3v4d1shYvQ== X-Received: by 2002:adf:f50b:: with SMTP id q11mr54720687wro.343.1575036141020; Fri, 29 Nov 2019 06:02:21 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 2/8] docs: tweak kernel-doc for QEMU coding standards Date: Fri, 29 Nov 2019 15:02:11 +0100 Message-Id: <20191129140217.17797-3-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::441 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Surprisingly, QEMU does have a pretty consistent doc comment style and it is not very different from the Linux kernel's. Of the documentation "sigils", only "#" separates the QEMU doc comment style from Linux's, and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in accel/tcg/translate-all.c), so it's clear that the two standards are different in this respect. In addition, our structs are typedefed and recognized by CamelCase names. Adjust kernel-doc's parser for these two aspects of the QEMU coding standards. The patch has been valid, with hardly any change, for over two years, so it should not be an issue to keep kernel-doc in sync with the Linux copy. Signed-off-by: Paolo Bonzini --- scripts/kernel-doc | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 81dc91760b..af470eb321 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -215,12 +215,12 @@ my $type_func =3D '(\w+)\(\)'; my $type_param =3D '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; my $type_fp_param =3D '\@(\w+)\(\)'; # Special RST handling for func ptr = params my $type_env =3D '(\$\w+)'; -my $type_enum =3D '\&(enum\s*([_\w]+))'; -my $type_struct =3D '\&(struct\s*([_\w]+))'; -my $type_typedef =3D '\&(typedef\s*([_\w]+))'; -my $type_union =3D '\&(union\s*([_\w]+))'; -my $type_member =3D '\&([_\w]+)(\.|->)([_\w]+)'; -my $type_fallback =3D '\&([_\w]+)'; +my $type_enum =3D '#(enum\s*([_\w]+))'; +my $type_struct =3D '#(struct\s*([_\w]+))'; +my $type_typedef =3D '#(([A-Z][_\w]*))'; +my $type_union =3D '#(union\s*([_\w]+))'; +my $type_member =3D '#([_\w]+)(\.|->)([_\w]+)'; +my $type_fallback =3D '(?!)'; # this never matches my $type_member_func =3D $type_member . '\(\)'; =20 # Output conversion substitutions. @@ -1050,6 +1050,14 @@ sub output_blockhead { sub dump_declaration($$) { no strict 'refs'; my ($prototype, $file) =3D @_; + if ($decl_type eq 'type name') { + if ($prototype =3D~ /^(enum|struct|union)\s+/) { + $decl_type =3D $1; + } else { + return; + } + } + my $func =3D "dump_" . $decl_type; &$func(@_); } @@ -1878,7 +1886,7 @@ sub process_name($$) { } elsif (/$doc_decl/o) { $identifier =3D $1; - if (/\s*([\w\s]+?)(\(\))?\s*-/) { + if (/\s*([\w\s]+?)(\s*-|:)/) { $identifier =3D $1; } =20 @@ -1888,7 +1896,7 @@ sub process_name($$) { $contents =3D ""; $section =3D $section_default; $new_start_line =3D $. + 1; - if (/-(.*)/) { + if (/[-:](.*)/) { # strip leading/trailing/multiple spaces $descr=3D $1; $descr =3D~ s/^\s*//; @@ -1906,7 +1914,9 @@ sub process_name($$) { ++$warnings; } =20 - if ($identifier =3D~ m/^struct\b/) { + if ($identifier =3D~ m/^[A-Z]/) { + $decl_type =3D 'type name'; + } elsif ($identifier =3D~ m/^struct\b/) { $decl_type =3D 'struct'; } elsif ($identifier =3D~ m/^union\b/) { $decl_type =3D 'union'; --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575036431; cv=none; d=zohomail.com; s=zohoarc; b=STh49l83fXCmAOmDp4B8UHt/pl9lKHadt8xsUSGE6g15bFf1DcMdY37aJbidn/W6PdpGGvo+N+gQQNxre2UHy0M0HG7wwvqlSP52LnwE+ieHNN+m5eoKBLewTd6pSO8i9g0b+MSR6HH0sAdnnyh0sOk0/j8IJ8ua4DoTYnqmPTw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575036431; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Bl/q66EQnB/Vpv+0jM7P6EssXQ6U7FEXGyqS8D7LPwk=; b=A3gHLpVTn/KfB6DUzZGPsMIPXn/mv2lOtwKk+3OGgx0SIgkFzT0OjLqCYcHxyLkAjEpkmxo8AUS5gen/3TVVtOQsh5eEv1AwQMRSPJCZtrl/PB9j47EYXcUEdqO2MGhb8sJzh8b3nK26I8mcNwEei2EdgIkgLahbFj74M/TAmBE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575036431558743.3809801623802; Fri, 29 Nov 2019 06:07:11 -0800 (PST) Received: from localhost ([::1]:59512 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagvM-0004a3-DL for importer@patchew.org; Fri, 29 Nov 2019 09:07:08 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37121) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagqt-00028G-EU for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:33 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqn-0003NB-75 for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:31 -0500 Received: from mail-wr1-x434.google.com ([2a00:1450:4864:20::434]:39942) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqm-0003I2-UZ for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:25 -0500 Received: by mail-wr1-x434.google.com with SMTP id c14so10716892wrn.7 for ; Fri, 29 Nov 2019 06:02:23 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:21 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=Bl/q66EQnB/Vpv+0jM7P6EssXQ6U7FEXGyqS8D7LPwk=; b=n2sU53h1JPh4ueANeHRgmU8jWPm7UL0w7WWkdFZ8WFvzmpuXpGNlh5l+MIffaGR5xk HF5zPpxZW1oMvwgNRYRLuHIZow6Flsdgnp0uJ0pt7j9Of2xkHMzKN7IzVK02OoaXGgGr oixjlf1p/pKUgwtw53CILGiDFIvAg2N+WUXegg3mi5TeCyCBJ5BYF5nenOk/BfGJONu0 rQ916JbNRPLxUMViPlEo5yB+xrIAnOu/DBAmqrE0ZByl9rtm5qhQdhuHhcNXZkiStN7L HSVhuf8HcH3EQyvtnI/84b+lIvnfiAdSfQpayt60fpUpJr5vzqv+VvF9jn5Q+BbjeRa3 GYUg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=Bl/q66EQnB/Vpv+0jM7P6EssXQ6U7FEXGyqS8D7LPwk=; b=Kt67rsqJDLxZrnr9BZZMIzZBc1Zq0StqtloTfAmiN+sxngLViDd1irmIhIIntTnxNW R6ONaPGUIDvET9aVsw/vAMoxcK2q7V8P5H4LmXovyqiFHMthF9LcR5rAehtXXw5dV0VN Evu4yUTDzdohsaoDsCQXPVkW3dvBCIopdYosLH+uNFGjUvCkFiJn6z9fKGacH3N0I1Ud VJP+ZEupPPoqCkor9xRzT0YvqfYlM17nmx16usBLg3J5KaEW+otKy2gsRnXLuSDo1iz7 3xqDM7gAZ6hdvDKVPu/+btaalEUuHEJkPsEDqTcjyNVfon8tEsHTQQHZ/XzM8CBCNa8W /6TQ== X-Gm-Message-State: APjAAAUdHpzU/IyMOGaHT3M93jFCrs/YDZo3N9ADA4PYZFEm2Ux+yKWS 5m0XxrnRhjCRJR7Uamzc/K1jaQCC X-Google-Smtp-Source: APXvYqzE05ST/aPpBmHHr+HdmKgPdF+s6wFeYrBUZZ4wP6cUXVJfYztL48liJJagUSJ3DNjvQne6qA== X-Received: by 2002:adf:db86:: with SMTP id u6mr57316160wri.318.1575036141866; Fri, 29 Nov 2019 06:02:21 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 3/8] docs/conf.py: Enable use of kerneldoc sphinx extension Date: Fri, 29 Nov 2019 15:02:12 +0100 Message-Id: <20191129140217.17797-4-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::434 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" From: Peter Maydell Signed-off-by: Peter Maydell Message-Id: <20190521122519.12573-4-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini --- docs/conf.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index b7edb0666b..259c6049da 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,7 +54,7 @@ needs_sphinx =3D '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 =3D ['qmp_lexer'] +extensions =3D ['kerneldoc', 'qmp_lexer'] =20 # Add any paths that contain templates here, relative to this directory. templates_path =3D ['_templates'] @@ -216,3 +216,8 @@ texinfo_documents =3D [ =20 =20 =20 +# 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 =3D os.path.join(qemu_docdir, '../scripts/kernel-doc') +kerneldoc_srctree =3D os.path.join(qemu_docdir, '..') --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575037632; cv=none; d=zohomail.com; s=zohoarc; b=PYI6chI85oUPpvmgnescycZt9wFE7EF2Ka6r1mhFop/cfBWyb6hALg1Rk+A1quonibiQtRc+kDtmkbeo4BwhVQHW2F2Y2Ru3ZmfhRAf833BwaUYFyV+UarmUaFuVPWLamTciwdVbBtLaOxm68/6/EtsUtaKFIbqcZ4412K+BV40= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575037632; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=lx6DGULeUoiZGfGxG0Zx1Ji9gkFvHa0kVzeH7vCeWUY=; b=AUQtI/6VIP1HrKg/IQHV9+BDzvyQC/30CJ723NX1FNdL2FCpALDqQ5bDxSxuiYLm7pjNLN3yUUyu7vwPOGiJgRIT0FEnkVTOYRJVMpil4DfmzMp/TCMoAO7N98dxnRp5bqcpcR+JeVoS3qf8NMxBq9z5AWMYprIVq8KOfmIwsNI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575037632897325.74682295708396; Fri, 29 Nov 2019 06:27:12 -0800 (PST) Received: from localhost ([::1]:59648 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iahEk-0001dZ-47 for importer@patchew.org; Fri, 29 Nov 2019 09:27:10 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37093) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagqs-00023c-C8 for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqp-0003PG-AR for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:29 -0500 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:55820) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqn-0003KQ-WC for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:27 -0500 Received: by mail-wm1-x32e.google.com with SMTP id a131so9970522wme.5 for ; Fri, 29 Nov 2019 06:02:24 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:22 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=lx6DGULeUoiZGfGxG0Zx1Ji9gkFvHa0kVzeH7vCeWUY=; b=UShhFgHgj7KXd3tkLQdDvEoS53pMxysTrfFinCoHFFXVTGxzt18RDKP+ejfL3aOznk X3KxEpLftVXodMQtLkT+2Lt1TO2FlVBCUvdIfJjxWjLmnPPG7n6ciXjRhrMidz/oFHUJ 2ygckf+rr0pGuZ9AkRDyIuv9BcH64+cxLJa0zEAP64yIIA9ecD1ivytSGBPVKkPXbnMt +FMVW949mYPiQvr/awp90c636Bkf+Ol137xH30PTJP+grKhrKQjVhKfoACkT0Fwl3bOe eqRWpciXBTFl1TweGMRGa8pCyuU0WAFmt4MCUynoSKazl+7QsTG9PR+8/9XDfrr7cM6Z Rvlw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=lx6DGULeUoiZGfGxG0Zx1Ji9gkFvHa0kVzeH7vCeWUY=; b=OWOIMU9P0/B/mHvaTiLWvyZSANh1zD+PVNEGOEBTt4FzEAN/gItmWhVof6DabRDt8H OhB7nIJW6R9AkgdnnbMViZWxt88i9uugEsKOqXP+brHvLwpBC6NWko+N6PR/ZSwhVv73 oRrTo9MRe0iw7J36BaJrR9ZV64s4QTtZXAOJ6ZnjBW9vd8iNlfiBMOnYZ+ajppJcCt2h KMlpkv2xpqgUx642+qFqluWuvvNlPlLI7eJBrXuJORwBQfBIoO3hUjTDXAmqk/jaGmJK laA/PJL2alEc6SLDDBnzNvKFT9wv/U0oYLtRMCrJOJj3AZNohD8olctVZckK2Uwjhp+A GhgQ== X-Gm-Message-State: APjAAAWLy+RLUnqppILRVq5g2/AFjNTikR6gs7q8k2gQ+DAdagJt7L1n SO/nCYmbEwD8HCCwpL3oGoL6fMym X-Google-Smtp-Source: APXvYqxEX0gDZelP6dDZvN6wTc+eVVBc3e5ru1citNwTAnnyTXXEuEHG/PpxfDkSuB0gPFTAj/GZFA== X-Received: by 2002:a1c:9602:: with SMTP id y2mr14039647wmd.23.1575036142861; Fri, 29 Nov 2019 06:02:22 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 4/8] Makefile: disable Sphinx nitpicking Date: Fri, 29 Nov 2019 15:02:13 +0100 Message-Id: <20191129140217.17797-5-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32e X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" From: Peter Maydell Turn off Sphinx nitpicking as a temporary (?) measure so sphinx builds complete even with warnings about missing references. Signed-off-by: Peter Maydell Message-Id: <20190521122519.12573-11-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index b437a346d7..fcf16dc4cf 100644 --- a/Makefile +++ b/Makefile @@ -1010,7 +1010,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MAN= UAL_BUILDDIR)/interop/index # Note the use of different doctree for each (manual, builder) tuple; # this works around Sphinx not handling parallel invocation on # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 -build-manual =3D $(call quiet-command,CONFDIR=3D"$(qemu_confdir)" sphinx-b= uild $(if $(V),,-q) -W -n -b $2 -D version=3D$(VERSION) -D release=3D"$(FUL= L_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"= SPHINX","$(MANUAL_BUILDDIR)/$1") +build-manual =3D $(call quiet-command,CONFDIR=3D"$(qemu_confdir)" sphinx-b= uild $(if $(V),,-q) -W -b $2 -D version=3D$(VERSION) -D release=3D"$(FULL_V= ERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPH= INX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it manual-deps =3D $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/= conf.py $(SRC_PATH)/docs/conf.py =20 --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575038007; cv=none; d=zohomail.com; s=zohoarc; b=M6RfHQE41sNR9dXNASH2wwNvtpGWMdk+KnFayqeHe8Z7GKZy9pIlqC9xRsielyES7/vLEZRcAVU5duogDw4ICbE6a6oaQizQS/6jKv4ZgRBlwSDDJjsNhXiSKoeWwOY4OMBRYRqQbL7GXOlpLAk5n7Fe1tZ6xbPdwLJMraWml2g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575038007; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=O5ALt6XeKJY7X9PuLNRV7urYrSvgNCwCrlCEcwFrxJI=; b=Lgcr7T9FMwgSehBmZD1idsQdXJ3WBN6eXSQeK2TP+W3S8tjKxh5qUIO5ezBACMgTETq870yuZEfhknld9Hg/3XWFOO1ITApSX7QiFiPU5xUs7AACauw75bAZ9QJxMAfoySdBMP4gCz3C87HpiBo+fiWLNOfcmjyx5nq/P87Sk5w= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575038007626382.4672305042126; Fri, 29 Nov 2019 06:33:27 -0800 (PST) Received: from localhost ([::1]:59706 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iahKo-0006mJ-99 for importer@patchew.org; Fri, 29 Nov 2019 09:33:26 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37179) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagqu-0002Bi-Gz for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqp-0003PQ-9x for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:32 -0500 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:38899) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqo-0003Kz-4t for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:27 -0500 Received: by mail-wm1-x341.google.com with SMTP id p17so2333649wmi.3 for ; Fri, 29 Nov 2019 06:02:25 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:23 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=O5ALt6XeKJY7X9PuLNRV7urYrSvgNCwCrlCEcwFrxJI=; b=o13CjgqKpfljAKwquI/u7d0vnyH5XeD1OPrJYWKUaW9LqAG7QCjsbqA3RGve2Ut3yL XW8s3U1o8NBzlCJ5xKOJ9a97Qv2MIieKqwMGUuSLi2kMkIDMnTvnVlqlIVm+OlxInsP6 D64yjFHs+8zP2GFn+2ktt2Rp7+zO55osnnMJHyCk0ylOcngGOn93VWRgBCTmOBVb/kAo hE1cccBZuRXv5LLsgPHZv/6mShfn6Kn1T81gxMdbESormEI/yKi1rQQ1aMttQ3zlBWYZ 8YX4YzobftTojk0Mn/HtEQKZ94e6Pi34pI9v7CdAliGNkbMVuawUoBVV4dTb6iwhyUkh GqrA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=O5ALt6XeKJY7X9PuLNRV7urYrSvgNCwCrlCEcwFrxJI=; b=sxkXmfb9ISLfDQ0/6Nu7nxO/okxibGJ4gOK9HuZOC10LjILzSe73QBowsa9ZSc0mAn A7J5o9gR/Oglcy66flQV2eOrZvYa5uKAfyuAsj8TdngrtKF98NHL/aovF2LZFXlDWdev z5WGw6UrM+cUVKL46peBtPUV2QDw06O/yxespz7r9iabUHoN7FdZz5IUCFxreqo+yqlL OOYBmX6dZS5syCcTLiAK8MVvFCMwlSlv+zudfBBLpx9cYsxUaaEWyW8cWtW1sMFYs3t9 sIH6uR85ff3qOERSEiYiVEBLPQuoEc2M6+pbTiQe7pTsu6Vb+O3M7u7sWWkm0Urptf4/ 18uA== X-Gm-Message-State: APjAAAWNOr/7e4KcgfOSahywClkHgC13hN5XZCPciBTs5fQuQYeAE9Gx fwaqfy9Ngs59MaGJ68tsQxvrQLz2 X-Google-Smtp-Source: APXvYqyVx1rg3R6nnwC3nz3k+TekEGkovVi0Yqhn0nNDPeAE45wuUUfZyxru5Ynvu7XEfjIJo6D3Aw== X-Received: by 2002:a7b:c449:: with SMTP id l9mr2223764wmi.150.1575036143775; Fri, 29 Nov 2019 06:02:23 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 5/8] bitops.h: Silence kernel-doc complaints Date: Fri, 29 Nov 2019 15:02:14 +0100 Message-Id: <20191129140217.17797-6-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::341 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" From: Peter Maydell 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 Message-Id: <20190521122519.12573-6-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini --- 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 ee76552c06..02c1ce6a5d 100644 --- a/include/qemu/bitops.h +++ b/include/qemu/bitops.h @@ -424,13 +424,16 @@ static inline uint64_t deposit64(uint64_t value, int = start, int length, =20 /** * 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. * @@ -450,13 +453,16 @@ static inline uint32_t half_shuffle32(uint32_t x) =20 /** * 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. * @@ -477,13 +483,16 @@ static inline uint64_t half_shuffle64(uint64_t x) =20 /** * 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. * @@ -504,13 +513,16 @@ static inline uint32_t half_unshuffle32(uint32_t x) =20 /** * 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. * --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575038319; cv=none; d=zohomail.com; s=zohoarc; b=JtYMvgaV0YD7YN8MobYKjI6Y+ndmFEdowSXEvgwaST1DbcEUnZeQQdq0lveNedw6OgniZ1kuZw5qGu8Bt5tWpAysH3YO2DdZs3Q1CU45V+0yveeDfUN/qEY0YPh2cpbuNo2xwFFUJgshVS1ZLH/wKRb+6czvAUu09O6xhG+nyOQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575038319; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=7qR4CglT38h4RrB/48A3ve+rvnXStcx62AzXZuMT/HA=; b=MyN8Is6fXjwzzrIzATQaH16Q7DtfB3K4msDoXkV468ZeO+Bwz+zViO+VWnNLqcP1NcIpvofhEpx1t6PTbzVvRBTDsijHton9hwnjNECM/8GE89BdlPJs7NXTNJGlLKG2DalhLUs4JZHcFZOa9klyAwpq252WQofCEcreOdfDta0= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575038319883293.6386870879454; Fri, 29 Nov 2019 06:38:39 -0800 (PST) Received: from localhost ([::1]:59782 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iahPp-0003D7-LW for importer@patchew.org; Fri, 29 Nov 2019 09:38:37 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37288) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagqx-0002Dx-8a for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:37 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqr-0003RI-Em for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:34 -0500 Received: from mail-wm1-x343.google.com ([2a00:1450:4864:20::343]:37775) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqp-0003Nx-8B for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:29 -0500 Received: by mail-wm1-x343.google.com with SMTP id f129so15200845wmf.2 for ; Fri, 29 Nov 2019 06:02:26 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:24 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=7qR4CglT38h4RrB/48A3ve+rvnXStcx62AzXZuMT/HA=; b=IWgM/z5fCdtIMvwoVahfbTRwTMlIeJTZR0gvPYiYP7LVw0BrhE/bSZgEpd1FUFJmLv jkhwVjib8k6BSdqD4OvM+Vtd0hF3X0JS27m/3EFhAji1WXrycz6ZaCxjiSOOjei6reiv rLulXnVT79+DQhkYlZdkYHnH+7gcrlzvhXNJRkHazJc6V7o46PXZM9cmPU5+3w3VdvHw IDppNkcfC9Hls30dHiXenUUdUGTavnYmnhhiFEWXezfpjOvDM9wwLiHBWOOLS38QOAFb RBRB2DLcxs3Mfg/9JXVb9TwO4hujYXiJYAj2nxx2KyBSmKMMdbT+t+0tbhqZaTX9bOSQ 5kRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=7qR4CglT38h4RrB/48A3ve+rvnXStcx62AzXZuMT/HA=; b=gEnpPVCUb5J8elNhKyBXgcdmq0l99YX3wpULnHvzTliHuUeJFYNB/TLFhZUdCF4J5k bFeZmTCLzI81SSuJssmOfkgOuiviJL3wFq/x45QUpzvSIo2AZ/EbHC9lj14eJoLszcTe fTYQ5gjoiqRkwl3N9IBYTNBM4j4ywytFuNI/d13B40ip5VRu1paXbtfYDeP7cJMcp7nu NrD6uqyfGKz1nOg8qF2PVigH8B9cJ6AK00DFWgTGOI3YFA31vlsSHCeknRPQjWc+kmiQ er8lzQ2MhiZqKjZNKdny3Tt5ZlGUzKbfnDcEPcd5bpKe5aVyXt39M+0QwgukZqER3ril NXYQ== X-Gm-Message-State: APjAAAUIJKKOfOOROwJ+qtCwYX2nv8sO0Ro1mhAY9QoLtgaaPQ0qHyYP RG3NQywC5pHJaO6KdMmNCHqB8CC9 X-Google-Smtp-Source: APXvYqwAB2jZ7Hus0NBK8VoulJb2ImEJ0+fc80BejkogCfl7xmt+PrpW4HScI7g2BQt+C3f03P6tFA== X-Received: by 2002:a7b:c768:: with SMTP id x8mr15480299wmk.26.1575036144750; Fri, 29 Nov 2019 06:02:24 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 6/8] docs: Create bitops.rst as example of kernel-docs Date: Fri, 29 Nov 2019 15:02:15 +0100 Message-Id: <20191129140217.17797-7-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::343 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" From: Peter Maydell 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 Message-Id: <20190521122519.12573-7-peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini --- 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 0000000000..6addaecf8d --- /dev/null +++ b/docs/devel/bitops.rst @@ -0,0 +1,8 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Bitwise operations +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +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 c86a3cdff2..ac862152dc 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -23,3 +23,4 @@ Contents: secure-coding-practices tcg tcg-plugins + bitops --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575037198; cv=none; d=zohomail.com; s=zohoarc; b=fbiKhE/t3+89kWfIhQkpjbvOuQZKOlH7nwIjzaD6aUC7SDm4Ad+ysopv3n30QCE4dFykwf4IPgLwmbGXAoFPmyGfTJD03bKItWu7iNAnxTJigmoO18XTj0vKckxqOXq3k3+a1M8OLflDkxVlcSMTLyQWwzEec15FERO83HwmN04= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575037198; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=CKVENrRxKr+yy55UKAYjTBDTqL1/JJ86swpmf0+y21k=; b=S9UQtNDclmmxs8OXbP9E7FHT9NzUk1lRrQ4a8iA65y3Va4XXu+oP3ANSwk5AFjZXVIp8teBazRZOZG0NNzucvxS8Lr8W2b89mkHNiGSH6BdU6XKel+ktFJyPwdli/kegBZRTS/7/laFyg3ZX6DHYkksvqg0auQAKbhBAPka7cJY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575037198616443.72972435032443; Fri, 29 Nov 2019 06:19:58 -0800 (PST) Received: from localhost ([::1]:59610 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iah7h-0005Nc-Sz for importer@patchew.org; Fri, 29 Nov 2019 09:19:53 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37139) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagqt-00029N-MT for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:33 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqr-0003R4-Dr for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:31 -0500 Received: from mail-wm1-x342.google.com ([2a00:1450:4864:20::342]:35280) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqp-0003ON-Au for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:29 -0500 Received: by mail-wm1-x342.google.com with SMTP id n5so15203883wmc.0 for ; Fri, 29 Nov 2019 06:02:26 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=CKVENrRxKr+yy55UKAYjTBDTqL1/JJ86swpmf0+y21k=; b=fwbFRKD+1YbilVGvErK7cPKPmDiHX/94U1SysPMy+ea07KJ5aC8IW+OtHlmn/P1ZYA 9Q/GoUnCIaZ8U756KytY6peyfNh564fFuyUE61C6VGw4szBxuquqG7zTYVVQVbqBeevE DZZh8G8g4yy2C0g12kGsRqDqW3pSXr6r2h0cYHB2lDx27IYMPmfSHdzx7EbpF4UnbfoM 0PZjslUSUDiA/skUigPflZfH0AhySfAOb+8kYjS04FlDHdHg1OwaznjN/2bCGrEfBWcM 2GaNYYTRsTGQT+iPSNbB++fxUQfNd0WUIzQ1jQji4l63eIwR5NtC6LdiauRJGWzOHt+t kavg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=CKVENrRxKr+yy55UKAYjTBDTqL1/JJ86swpmf0+y21k=; b=fCVD+JNTQrOS+GUYwTQa1J9J+GpfV+YwdAUkSe0EARsia/GFP6V0sar+sEiGDsKCNg Yjd1zZMM+GqsD0qIpLPXKgCa8i+x2QR2jzTA4T/JAWv81JWcXj0/Qpab6R3i/cMVpMGJ aKgicdlADEMedNYfjIvcU0cb86l9G2qFPkZE5gAPABNpaY535bS4dyFsL+9uBq5a/qA+ 1U6gzFXciGxFq9lib7vvhUvcehGlij/nh4Amz0onF5B4OcOH1H9kHKrORCbCgWcC3OtY oMPGphXhTyTmmQz7UGWkoQWlXxC/UNf9ubTH7D9G248ft/RVlhPuKQgaAH9ZtEicNY9K u1gQ== X-Gm-Message-State: APjAAAWCREsG7XSgkFJ4JOuM6N1Gu2DE46aQrD0tR3khsa/tIeUNSI9N QwsDbVAKyCGshUre6KPT0QgfXbda X-Google-Smtp-Source: APXvYqyudCsNKqBBoX/lHgexCg7d38Nr3EB1GK4pNeDXX7OsaUOSlRuTTTF1xcJxq69hNNXwfGkt+g== X-Received: by 2002:a05:600c:290d:: with SMTP id i13mr14860689wmd.139.1575036145597; Fri, 29 Nov 2019 06:02:25 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 7/8] memory.h: Silence kernel-doc complaints Date: Fri, 29 Nov 2019 15:02:16 +0100 Message-Id: <20191129140217.17797-8-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::342 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Fix a few instances where kernel-doc complains about doc comments in memory.h. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- include/exec/memory.h | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/include/exec/memory.h b/include/exec/memory.h index e499dc215b..1e875996ec 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -360,10 +360,14 @@ typedef struct IOMMUMemoryRegionClass { typedef struct CoalescedMemoryRange CoalescedMemoryRange; typedef struct MemoryRegionIoeventfd MemoryRegionIoeventfd; =20 +/** MemoryRegion: + * + * A struct representing a memory region. + */ struct MemoryRegion { Object parent_obj; =20 - /* All fields are private - violators will be prosecuted */ + /* private: */ =20 /* The following fields should fit in a cache line */ bool romd_mode; @@ -452,7 +456,7 @@ struct MemoryListener { * AddressSpace: describes a mapping of addresses to #MemoryRegion objects */ struct AddressSpace { - /* All fields are private. */ + /* private: */ struct rcu_head rcu; char *name; MemoryRegion *root; @@ -1673,8 +1677,8 @@ bool memory_region_is_mapped(MemoryRegion *mr); * * Returns a #MemoryRegionSection that describes a contiguous overlap. * It will have the following characteristics: - * .@size =3D 0 iff no overlap was found - * .@mr is non-%NULL iff an overlap was found + * - @size =3D 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 @@ -1685,8 +1689,8 @@ bool memory_region_is_mapped(MemoryRegion *mr); * 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 >=3D @addr - * .@offset_within_address_space + .@size <=3D @addr + @size + * - @offset_within_address_space >=3D @addr + * - @offset_within_address_space + .@size <=3D @addr + @size * * @mr: a MemoryRegion within which @addr is a relative address * @addr: start of the area within @as to be searched --=20 2.21.0 From nobody Thu Apr 25 05:13:17 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1575036759; cv=none; d=zohomail.com; s=zohoarc; b=g+0QUq1miA2AN7LlGs+nuhjjPHX7OCU5xi78Q+s9WlAeKVjLaenWJoGAcoZIg9aBYmbB11J9k1fJXliWKMYTUTQEE/NsnKrVlwL8aJUzS+QSg1VZ7ib4MpJr+xJEHDtfIhNHefBUDYLq6lFH7rifS75WxO8ZbbJMCrmTy9uGg4Q= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1575036759; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=h1QbsiBqD4r5lnwOURLn9f9iSFyppDHdfk3gzxS4r6U=; b=FouajbvmrUtt7Ra38RT06/BdUEJcsTtO45kDyh6B5FGIZwDk4JIrT2GlpHIWLicEGEtJhO7eD/BMh4rZ45cO5LUO9jb7tw6YoGTpOfDBlHep+8NzJeQ4anttgiIlOCRE7m67Dt32OMAeUq8FOvNhARc0zZ7FWEavQB45aMTDujE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1575036759335279.89964185144254; Fri, 29 Nov 2019 06:12:39 -0800 (PST) Received: from localhost ([::1]:59560 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iah0e-0000Bg-QV for importer@patchew.org; Fri, 29 Nov 2019 09:12:36 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37531) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iagr2-0002Kv-Q0 for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iagqt-0003SR-CM for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:38 -0500 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:33692) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iagqs-0003Oq-E4 for qemu-devel@nongnu.org; Fri, 29 Nov 2019 09:02:31 -0500 Received: by mail-wr1-x442.google.com with SMTP id b6so5692696wrq.0 for ; Fri, 29 Nov 2019 06:02:28 -0800 (PST) Received: from donizetti.redhat.com ([2001:b07:6468:f312:56e1:adff:fed9:caf0]) by smtp.gmail.com with ESMTPSA id e7sm14190030wrp.43.2019.11.29.06.02.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 29 Nov 2019 06:02:25 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=h1QbsiBqD4r5lnwOURLn9f9iSFyppDHdfk3gzxS4r6U=; b=tSJ2I0B2seMeP/UtIUygaGcCRA/q1CkN/xkDd6INo/COSc4Xk6eahl120pirFFstgP NaJm5SZJOXqjquD2XpmvQ8b4lZkIRXnrkxbFBIhdyEpx7m5PjpkThHKgje4D7TdAcPCB w+TX0sM3oTd2f3efgHUXuBafAtwtpvIX/DO+e8P9OtBBPPlFWQpUXkFSJRIlVpCXD4xF 0aZHjzI3pVVxQpM4JKKU9gIkioET7xGjzNh3KiZTgaQ7SF297k98dVeLG+2zi8LLdynn BmuHc2NTzTodfzAGNeSHhhhDLWD6KP+McIZ5S2V+Sh/0bB35GSzHv08rCobQ13kkvQyn WSAA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=h1QbsiBqD4r5lnwOURLn9f9iSFyppDHdfk3gzxS4r6U=; b=RyANwkZenPQhqXcvnOo7YYZ1eVZ7B/posbs3z7cUbkTZvUTCuEbmfU24/Dupc/cbVh PPY7Q3tBWg/31Cw92Qx+wXXBEE3f9jnJ8jdljvXljBt/Qd2URwHPd0/AbVKm/CKSh/ik vXq3k3/5f5ADteYmxHDxkwiTFj4oAUipFZKYpzGEicuwVqF11ogzq1i7ENus2ojQJbJC cqE0VzSB6Bn6Lyn5Mnpp9iu+oG/llkkeOwo6Y6mGIen6XHjK9yRbQ8MGqKLGgg9I6fuH POzFYGy4AQYMD2z0bYINgpVad6p3LCQsrbfmYcto2AXfQ/tOWegEXzDFh84Twos+ftrx xmzA== X-Gm-Message-State: APjAAAW4InEiEkHWrTxACN2nTSW/i02xOEGpMU7Q0ueQz6amrb/dujhw YJzYiwW51449CbY67s2u3FYkLZN+ X-Google-Smtp-Source: APXvYqx1WIIInDGb72aBl/1BYgPYZS9QYZ9ueLZMgQsQ0y72hW7dPZan8LMGS1i9vAnFAI7pXRtUsg== X-Received: by 2002:a05:6000:1602:: with SMTP id u2mr57822402wrb.249.1575036146566; Fri, 29 Nov 2019 06:02:26 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 8/8] docs: add memory API reference Date: Fri, 29 Nov 2019 15:02:17 +0100 Message-Id: <20191129140217.17797-9-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191129140217.17797-1-pbonzini@redhat.com> References: <20191129140217.17797-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::442 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Add kernel-doc directive to parse and include doc comments from include/exec/memory.h. Signed-off-by: Paolo Bonzini Reviewed-by: Peter Maydell --- docs/devel/memory.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst index b6a4c37ea5..5dc8a12682 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. + +API Reference +------------- + +.. kernel-doc:: include/exec/memory.h --=20 2.21.0