From patchwork Tue May 21 12:25:10 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164724 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1543679ili; Tue, 21 May 2019 05:33:01 -0700 (PDT) X-Google-Smtp-Source: APXvYqzMhhFf/urUsKhUC/WJimEHsChkZAEQ3VHuJp4DniP2SW4Xt4Eh2y8hcwfyFJt5gFLjpbXc X-Received: by 2002:a50:e707:: with SMTP id a7mr76575225edn.68.1558441981262; Tue, 21 May 2019 05:33:01 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441981; cv=none; d=google.com; s=arc-20160816; b=iHY5vs1i8ZA+v9cBKQdgKcl9WPRMN2KdZ5CUN/8Ne9gih4nIEz1DzJq2T6iGU4SZHe IxMRXfQdN+oaqRnaCqxnxISZFm+WoXPZJkUVtE/OjlesxAO3sPQSMc+AIYS6QBNf0Zec FGJMSuE/6phk6JoncC5wWPckMTVzP2wyfqmcj6MddpQDRyuiAGZ/BwIcEmJt/h79i5er GIrKRQZw6UG+p04g9ukjH3DXeJ2CgXOaU1qxVwW5w55TNGbrve+ad5k5GKrVq1ROiBmr 8oT8KgTg9qeDO58TlHf6Lor1bscOOWfWBQNK389zUpJXHDpHModLAlmxWS+BrgV07K9D 7w0w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=F0jHsOAooYexOuuLLB0ITabm5ISjj/rT0lB1dhGA48k=; b=I9THICIFZc6AGp230tF8aiuCQ9ENs2DXLA5oA4RMBPmFHB+0FLq27KSGdn/smncLu4 QRL5mql8VHbqkX1kVL6/HZOgBGN8UICAxNO++639Z4hjWuNSSevTM9+mlnY5MCmqt4xC 5fwufLw85/uQ61SHBen7YoAidDJPX+JwkraLmzbdAcOxAmpI8WvBgPlC47kKWZcoYXV7 nYF1wu1VvZUh1+GSMDTi5qkiFc7dd5UUD50nll7oonAduwnRehXagzNb9pRGe5NwqffM dmUn84cr+MxTEjahpd3KrHfa2IX/4Ib+uVv49ARNGWSQwMns7xrs75T5P0FVJIDNmtLT qazQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=O1cHgY+9; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id b15si3910694edb.89.2019.05.21.05.33.00 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:33:01 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=O1cHgY+9; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52765 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3ww-0007XG-78 for patch@linaro.org; Tue, 21 May 2019 08:32:58 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45432) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3qA-0001aS-2O for qemu-devel@nongnu.org; Tue, 21 May 2019 08:26:03 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005GN-2b for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:54 -0400 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:37548) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00054o-Hw for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wr1-x442.google.com with SMTP id e15so18403211wrs.4 for ; Tue, 21 May 2019 05:25:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=F0jHsOAooYexOuuLLB0ITabm5ISjj/rT0lB1dhGA48k=; b=O1cHgY+9BkMjuZjL38zSsS3QS6rDbZdYxZaY0vb1rzRYpgCYIFAMzQakfrxD/4D1Ut 9XTz6pST8ohL2ee8cx5u60si1YPjjkn1VZMMVJgeIKeXIHgOeU7EqN0b514pxaIcNqYy pot5vbfA66C0vh+AhAByC6oVZ1P0SpxCjU4gupXbAyq63CnQ1MU/PmjcFZatYx32uxvO MBoZEj6tVZ1ClYkyLqd5U/7mad34CzuL7wt9X96kd3yF8yrNnc2Zg2J7j64RiGV9ejkd xmKwcHRdRZ5EyNvqKR22jzjH87KKTnUCviriE4d0yaj88iKLGSpyGMSrnhZcBd/D0eoH pxCg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=F0jHsOAooYexOuuLLB0ITabm5ISjj/rT0lB1dhGA48k=; b=GjyHWhbdMZM1XLhraCQEQpv0BzfLmZURff3nUE8005riYHn4vcaoOwNZl+HcVd8hyI OSjXJhAsMAOVyBtld7CXA+ebfmZ89mGmNzc6D2310zdpnXsV6gZO902j5xiCamC9WYTD 2hykls3HbhlfbofzdLoIjcQpD9rkPYscLRPcLOYwcCJuybo4eJGzY4Grh2x1bN5EAZkq Gsb1jqgRvgV19RGGTDtFVRv9QyC+jF2hTCEXUXUFG7o3MF32sY5vnBOE8AxVR5f17sUs uEWbVQXmajuPQNSSXgNdE2yxYjFcQkFLPyeyw7MDzMAtnX2cY2yyx8l8DWZX8jjG8BDa YmhA== X-Gm-Message-State: APjAAAXSW+FEXWnX7BKJwED1O9clN/hpNb/18t3ZBopbkCcSOr8dCz6t aVyNoXqc8Vi+keyqMgvWWB7bWDUnk6g= X-Received: by 2002:a5d:688a:: with SMTP id h10mr49640845wru.211.1558441524859; Tue, 21 May 2019 05:25:24 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.22 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:24 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:10 +0100 Message-Id: <20190521122519.12573-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::442 Subject: [Qemu-devel] [RFC 01/10] scripts/kernel-doc: Import kernel-doc script from Linux X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" Import the kernel-doc script as of Linux commit 30bac164aca750892b93. Signed-off-by: Peter Maydell --- scripts/kernel-doc | 2223 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2223 insertions(+) create mode 100755 scripts/kernel-doc -- 2.20.1 diff --git a/scripts/kernel-doc b/scripts/kernel-doc new file mode 100755 index 00000000000..c5333d25198 --- /dev/null +++ b/scripts/kernel-doc @@ -0,0 +1,2223 @@ +#!/usr/bin/env perl +# SPDX-License-Identifier: GPL-2.0 + +use warnings; +use strict; + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## Copyright (C) 2000, 1 Tim Waugh ## +## 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 = <<"EOF"; +Usage: $0 [OPTION ...] FILE ... + +Read C language source or header FILEs, extract embedded documentation comments, +and print formatted documentation to standard output. + +The documentation comments are identified by "/**" opening comment mark. See +Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. + +Output format selection (mutually exclusive): + -man Output troff manual page format. This is the default. + -rst Output reStructuredText format. + -none Do not output documentation, only warnings. + +Output selection (mutually exclusive): + -export Only output documentation for symbols that have been + exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() + in any input FILE or -export-file FILE. + -internal Only output documentation for symbols that have NOT been + exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() + in any input FILE or -export-file FILE. + -function NAME Only output documentation for the given function(s) + or DOC: section title(s). All other functions and DOC: + sections are ignored. May be specified multiple times. + -nofunction NAME Do NOT output documentation for the given function(s); + only output documentation for the other functions and + DOC: sections. May be specified multiple times. + +Output selection modifiers: + -no-doc-sections Do not output DOC: sections. + -enable-lineno Enable output of #define LINENO lines. Only works with + reStructuredText format. + -export-file FILE Specify an additional FILE in which to look for + EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with + -export or -internal. May be specified multiple times. + +Other parameters: + -v Verbose output, more warnings and other information. + -h Print this help. + +EOF + print $message; + exit 1; +} + +# +# format of comments. +# In the following table, (...)? signifies optional structure. +# (...)* signifies 0 or more structure elements +# /** +# * function_name(:)? (- short description)? +# (* @parameterx: (description of parameter x)?)* +# (* a blank line)? +# * (Description:)? (Description of function)? +# * (section header: (section description)? )* +# (*)?*/ +# +# So .. the trivial example would be: +# +# /** +# * my_function +# */ +# +# If the Description: header tag is omitted, then there must be a blank line +# after the last parameter specification. +# e.g. +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * +# * Does my stuff explained. +# */ +# +# or, could also use: +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * Description: Does my stuff explained. +# */ +# etc. +# +# Besides functions you can also write documentation for structs, unions, +# enums and typedefs. Instead of the function name you must write the name +# of the declaration; the struct/union/enum/typedef must always precede +# the name. Nesting of declarations is not supported. +# Use the argument mechanism to document members or constants. +# e.g. +# /** +# * struct my_struct - short description +# * @a: first member +# * @b: second member +# * +# * Longer description +# */ +# struct my_struct { +# int a; +# int b; +# /* private: */ +# int c; +# }; +# +# All descriptions can be multiline, except the short function description. +# +# For really longs structs, you can also describe arguments inside the +# body of the struct. +# eg. +# /** +# * struct my_struct - short description +# * @a: first member +# * @b: second member +# * +# * Longer description +# */ +# struct my_struct { +# int a; +# int b; +# /** +# * @c: This is longer description of C +# * +# * You can use paragraphs to describe arguments +# * using this method. +# */ +# int c; +# }; +# +# This should be use only for struct/enum members. +# +# You can also add additional sections. When documenting kernel functions you +# should document the "Context:" of the function, e.g. whether the functions +# can be called form interrupts. Unlike other sections you can end it with an +# empty line. +# A non-void function should have a "Return:" section describing the return +# value(s). +# Example-sections should contain the string EXAMPLE so that they are marked +# appropriately in DocBook. +# +# Example: +# /** +# * user_function - function that can only be called in user context +# * @a: some argument +# * Context: !in_interrupt() +# * +# * Some description +# * Example: +# * user_function(22); +# */ +# ... +# +# +# All descriptive text is further processed, scanning for the following special +# patterns, which are highlighted appropriately. +# +# 'funcname()' - function +# '$ENVVAR' - environmental variable +# '&struct_name' - name of a structure (up to two words including 'struct') +# '&struct_name.member' - name of a structure member +# '@parameter' - name of a parameter +# '%CONST' - name of a constant. +# '``LITERAL``' - literal string without any spaces on it. + +## init lots of data + +my $errors = 0; +my $warnings = 0; +my $anon_struct_union = 0; + +# match expressions used to find embedded type information +my $type_constant = '\b``([^\`]+)``\b'; +my $type_constant2 = '\%([-_\w]+)'; +my $type_func = '(\w+)\(\)'; +my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)'; +my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params +my $type_env = '(\$\w+)'; +my $type_enum = '\&(enum\s*([_\w]+))'; +my $type_struct = '\&(struct\s*([_\w]+))'; +my $type_typedef = '\&(typedef\s*([_\w]+))'; +my $type_union = '\&(union\s*([_\w]+))'; +my $type_member = '\&([_\w]+)(\.|->)([_\w]+)'; +my $type_fallback = '\&([_\w]+)'; +my $type_member_func = $type_member . '\(\)'; + +# Output conversion substitutions. +# One for each output format + +# these are pretty rough +my @highlights_man = ( + [$type_constant, "\$1"], + [$type_constant2, "\$1"], + [$type_func, "\\\\fB\$1\\\\fP"], + [$type_enum, "\\\\fI\$1\\\\fP"], + [$type_struct, "\\\\fI\$1\\\\fP"], + [$type_typedef, "\\\\fI\$1\\\\fP"], + [$type_union, "\\\\fI\$1\\\\fP"], + [$type_param, "\\\\fI\$1\\\\fP"], + [$type_member, "\\\\fI\$1\$2\$3\\\\fP"], + [$type_fallback, "\\\\fI\$1\\\\fP"] + ); +my $blankline_man = ""; + +# rst-mode +my @highlights_rst = ( + [$type_constant, "``\$1``"], + [$type_constant2, "``\$1``"], + # Note: need to escape () to avoid func matching later + [$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"], + [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"], + [$type_fp_param, "**\$1\\\\(\\\\)**"], + [$type_func, "\\:c\\:func\\:`\$1()`"], + [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"], + [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"], + # in rst this can refer to any type + [$type_fallback, "\\:c\\:type\\:`\$1`"], + [$type_param, "**\$1**"] + ); +my $blankline_rst = "\n"; + +# read arguments +if ($#ARGV == -1) { + usage(); +} + +my $kernelversion; +my $dohighlight = ""; + +my $verbose = 0; +my $output_mode = "rst"; +my $output_preformatted = 0; +my $no_doc_sections = 0; +my $enable_lineno = 0; +my @highlights = @highlights_rst; +my $blankline = $blankline_rst; +my $modulename = "Kernel API"; + +use constant { + OUTPUT_ALL => 0, # output all symbols and doc sections + OUTPUT_INCLUDE => 1, # output only specified symbols + OUTPUT_EXCLUDE => 2, # output everything except specified symbols + OUTPUT_EXPORTED => 3, # output exported symbols + OUTPUT_INTERNAL => 4, # output non-exported symbols +}; +my $output_selection = OUTPUT_ALL; +my $show_not_found = 0; + +my @export_file_list; + +my @build_time; +if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) && + (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') { + @build_time = gmtime($seconds); +} else { + @build_time = localtime; +} + +my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', + 'July', 'August', 'September', 'October', + 'November', 'December')[$build_time[4]] . + " " . ($build_time[5]+1900); + +# Essentially these are globals. +# They probably want to be tidied up, made more localised or something. +# CAVEAT EMPTOR! Some of the others I localised may not want to be, which +# could cause "use of undefined value" or other bugs. +my ($function, %function_table, %parametertypes, $declaration_purpose); +my $declaration_start_line; +my ($type, $declaration_name, $return_type); +my ($newsection, $newcontents, $prototype, $brcount, %source_map); + +if (defined($ENV{'KBUILD_VERBOSE'})) { + $verbose = "$ENV{'KBUILD_VERBOSE'}"; +} + +# Generated docbook code is inserted in a template at a point where +# docbook v3.1 requires a non-zero sequence of RefEntry's; see: +# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html +# We keep track of number of generated entries and generate a dummy +# if needs be to ensure the expanded template can be postprocessed +# into html. +my $section_counter = 0; + +my $lineprefix=""; + +# Parser states +use constant { + STATE_NORMAL => 0, # normal code + STATE_NAME => 1, # looking for function name + STATE_BODY_MAYBE => 2, # body - or maybe more description + STATE_BODY => 3, # the body of the comment + STATE_PROTO => 4, # scanning prototype + STATE_DOCBLOCK => 5, # documentation block + STATE_INLINE => 6, # gathering documentation outside main block +}; +my $state; +my $in_doc_sect; +my $leading_space; + +# Inline documentation state +use constant { + STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE) + STATE_INLINE_NAME => 1, # looking for member name (@foo:) + STATE_INLINE_TEXT => 2, # looking for member documentation + STATE_INLINE_END => 3, # done + STATE_INLINE_ERROR => 4, # error - Comment without header was found. + # Spit a warning as it's not + # proper kernel-doc and ignore the rest. +}; +my $inline_doc_state; + +#declaration types: can be +# 'function', 'struct', 'union', 'enum', 'typedef' +my $decl_type; + +my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. +my $doc_end = '\*/'; +my $doc_com = '\s*\*\s*'; +my $doc_com_body = '\s*\* ?'; +my $doc_decl = $doc_com . '(\w+)'; +# @params and a strictly limited set of supported section names +my $doc_sect = $doc_com . + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; +my $doc_content = $doc_com_body . '(.*)'; +my $doc_block = $doc_com . 'DOC:\s*(.*)?'; +my $doc_inline_start = '^\s*/\*\*\s*$'; +my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)'; +my $doc_inline_end = '^\s*\*/\s*$'; +my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$'; +my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; + +my %parameterdescs; +my %parameterdesc_start_lines; +my @parameterlist; +my %sections; +my @sectionlist; +my %section_start_lines; +my $sectcheck; +my $struct_actual; + +my $contents = ""; +my $new_start_line = 0; + +# the canonical section names. see also $doc_sect above. +my $section_default = "Description"; # default section +my $section_intro = "Introduction"; +my $section = $section_default; +my $section_context = "Context"; +my $section_return = "Return"; + +my $undescribed = "-- undescribed --"; + +reset_state(); + +while ($ARGV[0] =~ m/^--?(.*)/) { + my $cmd = $1; + shift @ARGV; + if ($cmd eq "man") { + $output_mode = "man"; + @highlights = @highlights_man; + $blankline = $blankline_man; + } elsif ($cmd eq "rst") { + $output_mode = "rst"; + @highlights = @highlights_rst; + $blankline = $blankline_rst; + } elsif ($cmd eq "none") { + $output_mode = "none"; + } elsif ($cmd eq "module") { # not needed for XML, inherits from calling document + $modulename = shift @ARGV; + } elsif ($cmd eq "function") { # to only output specific functions + $output_selection = OUTPUT_INCLUDE; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "nofunction") { # output all except specific functions + $output_selection = OUTPUT_EXCLUDE; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "export") { # only exported symbols + $output_selection = OUTPUT_EXPORTED; + %function_table = (); + } elsif ($cmd eq "internal") { # only non-exported symbols + $output_selection = OUTPUT_INTERNAL; + %function_table = (); + } elsif ($cmd eq "export-file") { + my $file = shift @ARGV; + push(@export_file_list, $file); + } elsif ($cmd eq "v") { + $verbose = 1; + } elsif (($cmd eq "h") || ($cmd eq "help")) { + usage(); + } elsif ($cmd eq 'no-doc-sections') { + $no_doc_sections = 1; + } elsif ($cmd eq 'enable-lineno') { + $enable_lineno = 1; + } elsif ($cmd eq 'show-not-found') { + $show_not_found = 1; + } else { + # Unknown argument + usage(); + } +} + +# continue execution near EOF; + +# get kernel version from env +sub get_kernel_version() { + my $version = 'unknown kernel version'; + + if (defined($ENV{'KERNELVERSION'})) { + $version = $ENV{'KERNELVERSION'}; + } + return $version; +} + +# +sub print_lineno { + my $lineno = shift; + if ($enable_lineno && defined($lineno)) { + print "#define LINENO " . $lineno . "\n"; + } +} +## +# dumps section contents to arrays/hashes intended for that purpose. +# +sub dump_section { + my $file = shift; + my $name = shift; + my $contents = join "\n", @_; + + if ($name =~ m/$type_param/) { + $name = $1; + $parameterdescs{$name} = $contents; + $sectcheck = $sectcheck . $name . " "; + $parameterdesc_start_lines{$name} = $new_start_line; + $new_start_line = 0; + } elsif ($name eq "@\.\.\.") { + $name = "..."; + $parameterdescs{$name} = $contents; + $sectcheck = $sectcheck . $name . " "; + $parameterdesc_start_lines{$name} = $new_start_line; + $new_start_line = 0; + } else { + if (defined($sections{$name}) && ($sections{$name} ne "")) { + # Only warn on user specified duplicate section names. + if ($name ne $section_default) { + print STDERR "${file}:$.: warning: duplicate section name '$name'\n"; + ++$warnings; + } + $sections{$name} .= $contents; + } else { + $sections{$name} = $contents; + push @sectionlist, $name; + $section_start_lines{$name} = $new_start_line; + $new_start_line = 0; + } + } +} + +## +# dump DOC: section after checking that it should go out +# +sub dump_doc_section { + my $file = shift; + my $name = shift; + my $contents = join "\n", @_; + + if ($no_doc_sections) { + return; + } + + if (($output_selection == OUTPUT_ALL) || + ($output_selection == OUTPUT_INCLUDE && + defined($function_table{$name})) || + ($output_selection == OUTPUT_EXCLUDE && + !defined($function_table{$name}))) + { + dump_section($file, $name, $contents); + output_blockhead({'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'module' => $modulename, + 'content-only' => ($output_selection != OUTPUT_ALL), }); + } +} + +## +# output function +# +# parameterdescs, a hash. +# function => "function name" +# parameterlist => @list of parameters +# parameterdescs => %parameter descriptions +# sectionlist => @list of sections +# sections => %section descriptions +# + +sub output_highlight { + my $contents = join "\n",@_; + my $line; + +# DEBUG +# if (!defined $contents) { +# use Carp; +# confess "output_highlight got called with no args?\n"; +# } + +# print STDERR "contents b4:$contents\n"; + eval $dohighlight; + die $@ if $@; +# print STDERR "contents af:$contents\n"; + + foreach $line (split "\n", $contents) { + if (! $output_preformatted) { + $line =~ s/^\s*//; + } + if ($line eq ""){ + if (! $output_preformatted) { + print $lineprefix, $blankline; + } + } else { + if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { + print "\\&$line"; + } else { + print $lineprefix, $line; + } + } + print "\n"; + } +} + +## +# output function in man +sub output_function_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'function'} . " \\- " . $args{'purpose'} . "\n"; + + print ".SH SYNOPSIS\n"; + if ($args{'functiontype'} ne "") { + print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n"; + } else { + print ".B \"" . $args{'function'} . "\n"; + } + $count = 0; + my $parenth = "("; + my $post = ","; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count == $#{$args{'parameterlist'}}) { + $post = ");"; + } + $type = $args{'parametertypes'}{$parameter}; + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print ".BI \"" . $parenth . $1 . "\" " . $parameter . " \") (" . $2 . ")" . $post . "\"\n"; + } else { + $type =~ s/([^\*])$/$1 /; + print ".BI \"" . $parenth . $type . "\" " . $parameter . " \"" . $post . "\"\n"; + } + $count++; + $parenth = ""; + } + + print ".SH ARGUMENTS\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print ".IP \"" . $parameter . "\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"", uc $section, "\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output enum in man +sub output_enum_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n"; + + print ".SH SYNOPSIS\n"; + print "enum " . $args{'enum'} . " {\n"; + $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + print ".br\n.BI \" $parameter\"\n"; + if ($count == $#{$args{'parameterlist'}}) { + print "\n};\n"; + last; + } + else { + print ", \n.br\n"; + } + $count++; + } + + print ".SH Constants\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + print ".IP \"" . $parameter . "\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output struct in man +sub output_struct_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n"; + + my $declaration = $args{'definition'}; + $declaration =~ s/\t/ /g; + $declaration =~ s/\n/"\n.br\n.BI \"/g; + print ".SH SYNOPSIS\n"; + print $args{'type'} . " " . $args{'struct'} . " {\n.br\n"; + print ".BI \"$declaration\n};\n.br\n\n"; + + print ".SH Members\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + print ".IP \"" . $parameter . "\" 12\n"; + output_highlight($args{'parameterdescs'}{$parameter_name}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output typedef in man +sub output_typedef_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + print ".SH NAME\n"; + print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +sub output_blockhead_man(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output in restructured text +# + +# +# This could use some work; it's used to output the DOC: sections, and +# starts by putting out the name of the doc section itself, but that tends +# to duplicate a header already in the template file. +# +sub output_blockhead_rst(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + + foreach $section (@{$args{'sectionlist'}}) { + if ($output_selection != OUTPUT_INCLUDE) { + print "**$section**\n\n"; + } + print_lineno($section_start_lines{$section}); + output_highlight_rst($args{'sections'}{$section}); + print "\n"; + } +} + +# +# Apply the RST highlights to a sub-block of text. +# +sub highlight_block($) { + # The dohighlight kludge requires the text be called $contents + my $contents = shift; + eval $dohighlight; + die $@ if $@; + return $contents; +} + +# +# Regexes used only here. +# +my $sphinx_literal = '^[^.].*::$'; +my $sphinx_cblock = '^\.\.\ +code-block::'; + +sub output_highlight_rst { + my $input = join "\n",@_; + my $output = ""; + my $line; + my $in_literal = 0; + my $litprefix; + my $block = ""; + + foreach $line (split "\n",$input) { + # + # If we're in a literal block, see if we should drop out + # of it. Otherwise pass the line straight through unmunged. + # + if ($in_literal) { + if (! ($line =~ /^\s*$/)) { + # + # If this is the first non-blank line in a literal + # block we need to figure out what the proper indent is. + # + if ($litprefix eq "") { + $line =~ /^(\s*)/; + $litprefix = '^' . $1; + $output .= $line . "\n"; + } elsif (! ($line =~ /$litprefix/)) { + $in_literal = 0; + } else { + $output .= $line . "\n"; + } + } else { + $output .= $line . "\n"; + } + } + # + # Not in a literal block (or just dropped out) + # + if (! $in_literal) { + $block .= $line . "\n"; + if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) { + $in_literal = 1; + $litprefix = ""; + $output .= highlight_block($block); + $block = "" + } + } + } + + if ($block) { + $output .= highlight_block($block); + } + foreach $line (split "\n", $output) { + print $lineprefix . $line . "\n"; + } +} + +sub output_function_rst(%) { + my %args = %{$_[0]}; + my ($parameter, $section); + my $oldprefix = $lineprefix; + my $start = ""; + + if ($args{'typedef'}) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; + } else { + print ".. c:function:: "; + } + if ($args{'functiontype'} ne "") { + $start .= $args{'functiontype'} . " " . $args{'function'} . " ("; + } else { + $start .= $args{'function'} . " ("; + } + print $start; + + my $count = 0; + foreach my $parameter (@{$args{'parameterlist'}}) { + if ($count ne 0) { + print ", "; + } + $count++; + $type = $args{'parametertypes'}{$parameter}; + + if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) { + # pointer-to-function + print $1 . $parameter . ") (" . $2; + } else { + print $type . " " . $parameter; + } + } + if ($args{'typedef'}) { + print ");``\n\n"; + } else { + print ")\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + } + + print "**Parameters**\n\n"; + $lineprefix = " "; + foreach $parameter (@{$args{'parameterlist'}}) { + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + $type = $args{'parametertypes'}{$parameter}; + + if ($type ne "") { + print "``$type $parameter``\n"; + } else { + print "``$parameter``\n"; + } + + print_lineno($parameterdesc_start_lines{$parameter_name}); + + if (defined($args{'parameterdescs'}{$parameter_name}) && + $args{'parameterdescs'}{$parameter_name} ne $undescribed) { + output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + } else { + print " *undescribed*\n"; + } + print "\n"; + } + + $lineprefix = $oldprefix; + output_section_rst(@_); +} + +sub output_section_rst(%) { + my %args = %{$_[0]}; + my $section; + my $oldprefix = $lineprefix; + $lineprefix = ""; + + foreach $section (@{$args{'sectionlist'}}) { + print "**$section**\n\n"; + print_lineno($section_start_lines{$section}); + output_highlight_rst($args{'sections'}{$section}); + print "\n"; + } + print "\n"; + $lineprefix = $oldprefix; +} + +sub output_enum_rst(%) { + my %args = %{$_[0]}; + my ($parameter); + my $oldprefix = $lineprefix; + my $count; + my $name = "enum " . $args{'enum'}; + + print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + + print "**Constants**\n\n"; + $lineprefix = " "; + foreach $parameter (@{$args{'parameterlist'}}) { + print "``$parameter``\n"; + if ($args{'parameterdescs'}{$parameter} ne $undescribed) { + output_highlight_rst($args{'parameterdescs'}{$parameter}); + } else { + print " *undescribed*\n"; + } + print "\n"; + } + + $lineprefix = $oldprefix; + output_section_rst(@_); +} + +sub output_typedef_rst(%) { + my %args = %{$_[0]}; + my ($parameter); + my $oldprefix = $lineprefix; + my $name = "typedef " . $args{'typedef'}; + + print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + + $lineprefix = $oldprefix; + output_section_rst(@_); +} + +sub output_struct_rst(%) { + my %args = %{$_[0]}; + my ($parameter); + my $oldprefix = $lineprefix; + my $name = $args{'type'} . " " . $args{'struct'}; + + print "\n\n.. c:type:: " . $name . "\n\n"; + print_lineno($declaration_start_line); + $lineprefix = " "; + output_highlight_rst($args{'purpose'}); + print "\n"; + + print "**Definition**\n\n"; + print "::\n\n"; + my $declaration = $args{'definition'}; + $declaration =~ s/\t/ /g; + print " " . $args{'type'} . " " . $args{'struct'} . " {\n$declaration };\n\n"; + + print "**Members**\n\n"; + $lineprefix = " "; + foreach $parameter (@{$args{'parameterlist'}}) { + ($parameter =~ /^#/) && next; + + my $parameter_name = $parameter; + $parameter_name =~ s/\[.*//; + + ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next; + $type = $args{'parametertypes'}{$parameter}; + print_lineno($parameterdesc_start_lines{$parameter_name}); + print "``" . $parameter . "``\n"; + output_highlight_rst($args{'parameterdescs'}{$parameter_name}); + print "\n"; + } + print "\n"; + + $lineprefix = $oldprefix; + output_section_rst(@_); +} + +## none mode output functions + +sub output_function_none(%) { +} + +sub output_enum_none(%) { +} + +sub output_typedef_none(%) { +} + +sub output_struct_none(%) { +} + +sub output_blockhead_none(%) { +} + +## +# generic output function for all types (function, struct/union, typedef, enum); +# calls the generated, variable output_ function name based on +# functype and output_mode +sub output_declaration { + no strict 'refs'; + my $name = shift; + my $functype = shift; + my $func = "output_${functype}_$output_mode"; + if (($output_selection == OUTPUT_ALL) || + (($output_selection == OUTPUT_INCLUDE || + $output_selection == OUTPUT_EXPORTED) && + defined($function_table{$name})) || + (($output_selection == OUTPUT_EXCLUDE || + $output_selection == OUTPUT_INTERNAL) && + !($functype eq "function" && defined($function_table{$name})))) + { + &$func(@_); + $section_counter++; + } +} + +## +# generic output function - calls the right one based on current output mode. +sub output_blockhead { + no strict 'refs'; + my $func = "output_blockhead_" . $output_mode; + &$func(@_); + $section_counter++; +} + +## +# takes a declaration (struct, union, enum, typedef) and +# invokes the right handler. NOT called for functions. +sub dump_declaration($$) { + no strict 'refs'; + my ($prototype, $file) = @_; + my $func = "dump_" . $decl_type; + &$func(@_); +} + +sub dump_union($$) { + dump_struct(@_); +} + +sub dump_struct($$) { + my $x = shift; + my $file = shift; + + if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { + my $decl_type = $1; + $declaration_name = $2; + my $members = $3; + + # ignore members marked private: + $members =~ s/\/\*\s*private:.*?\/\*\s*public:.*?\*\///gosi; + $members =~ s/\/\*\s*private:.*//gosi; + # strip comments: + $members =~ s/\/\*.*?\*\///gos; + # strip attributes + $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi; + $members =~ s/\s*__aligned\s*\([^;]*\)//gos; + $members =~ s/\s*__packed\s*//gos; + $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; + # replace DECLARE_BITMAP + $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; + # replace DECLARE_HASHTABLE + $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos; + # replace DECLARE_KFIFO + $members =~ s/DECLARE_KFIFO\s*\(([^,)]+),\s*([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; + # replace DECLARE_KFIFO_PTR + $members =~ s/DECLARE_KFIFO_PTR\s*\(([^,)]+),\s*([^,)]+)\)/$2 \*$1/gos; + + my $declaration = $members; + + # Split nested struct/union elements as newer ones + while ($members =~ m/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/) { + my $newmember; + my $maintype = $1; + my $ids = $4; + my $content = $3; + foreach my $id(split /,/, $ids) { + $newmember .= "$maintype $id; "; + + $id =~ s/[:\[].*//; + $id =~ s/^\s*\**(\S+)\s*/$1/; + foreach my $arg (split /;/, $content) { + next if ($arg =~ m/^\s*$/); + if ($arg =~ m/^([^\(]+\(\*?\s*)([\w\.]*)(\s*\).*)/) { + # pointer-to-function + my $type = $1; + my $name = $2; + my $extra = $3; + next if (!$name); + if ($id =~ m/^\s*$/) { + # anonymous struct/union + $newmember .= "$type$name$extra; "; + } else { + $newmember .= "$type$id.$name$extra; "; + } + } else { + my $type; + my $names; + $arg =~ s/^\s+//; + $arg =~ s/\s+$//; + # Handle bitmaps + $arg =~ s/:\s*\d+\s*//g; + # Handle arrays + $arg =~ s/\[.*\]//g; + # The type may have multiple words, + # and multiple IDs can be defined, like: + # const struct foo, *bar, foobar + # So, we remove spaces when parsing the + # names, in order to match just names + # and commas for the names + $arg =~ s/\s*,\s*/,/g; + if ($arg =~ m/(.*)\s+([\S+,]+)/) { + $type = $1; + $names = $2; + } else { + $newmember .= "$arg; "; + next; + } + foreach my $name (split /,/, $names) { + $name =~ s/^\s*\**(\S+)\s*/$1/; + next if (($name =~ m/^\s*$/)); + if ($id =~ m/^\s*$/) { + # anonymous struct/union + $newmember .= "$type $name; "; + } else { + $newmember .= "$type $id.$name; "; + } + } + } + } + } + $members =~ s/(struct|union)([^\{\};]+)\{([^\{\}]*)\}([^\{\}\;]*)\;/$newmember/; + } + + # Ignore other nested elements, like enums + $members =~ s/(\{[^\{\}]*\})//g; + + create_parameterlist($members, ';', $file, $declaration_name); + check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual); + + # Adjust declaration for better display + $declaration =~ s/([\{;])/$1\n/g; + $declaration =~ s/\}\s+;/};/g; + # Better handle inlined enums + do {} while ($declaration =~ s/(enum\s+\{[^\}]+),([^\n])/$1,\n$2/); + + my @def_args = split /\n/, $declaration; + my $level = 1; + $declaration = ""; + foreach my $clause (@def_args) { + $clause =~ s/^\s+//; + $clause =~ s/\s+$//; + $clause =~ s/\s+/ /; + next if (!$clause); + $level-- if ($clause =~ m/(\})/ && $level > 1); + if (!($clause =~ m/^\s*#/)) { + $declaration .= "\t" x $level; + } + $declaration .= "\t" . $clause . "\n"; + $level++ if ($clause =~ m/(\{)/ && !($clause =~m/\}/)); + } + output_declaration($declaration_name, + 'struct', + {'struct' => $declaration_name, + 'module' => $modulename, + 'definition' => $declaration, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose, + 'type' => $decl_type + }); + } + else { + print STDERR "${file}:$.: error: Cannot parse struct or union!\n"; + ++$errors; + } +} + + +sub show_warnings($$) { + my $functype = shift; + my $name = shift; + + return 1 if ($output_selection == OUTPUT_ALL); + + if ($output_selection == OUTPUT_EXPORTED) { + if (defined($function_table{$name})) { + return 1; + } else { + return 0; + } + } + if ($output_selection == OUTPUT_INTERNAL) { + if (!($functype eq "function" && defined($function_table{$name}))) { + return 1; + } else { + return 0; + } + } + if ($output_selection == OUTPUT_INCLUDE) { + if (defined($function_table{$name})) { + return 1; + } else { + return 0; + } + } + if ($output_selection == OUTPUT_EXCLUDE) { + if (!defined($function_table{$name})) { + return 1; + } else { + return 0; + } + } + die("Please add the new output type at show_warnings()"); +} + +sub dump_enum($$) { + my $x = shift; + my $file = shift; + + $x =~ s@/\*.*?\*/@@gos; # strip comments. + # strip #define macros inside enums + $x =~ s@#\s*((define|ifdef)\s+|endif)[^;]*;@@gos; + + if ($x =~ /enum\s+(\w+)\s*\{(.*)\}/) { + $declaration_name = $1; + my $members = $2; + my %_members; + + $members =~ s/\s+$//; + + foreach my $arg (split ',', $members) { + $arg =~ s/^\s*(\w+).*/$1/; + push @parameterlist, $arg; + if (!$parameterdescs{$arg}) { + $parameterdescs{$arg} = $undescribed; + if (show_warnings("enum", $declaration_name)) { + print STDERR "${file}:$.: warning: Enum value '$arg' not described in enum '$declaration_name'\n"; + } + } + $_members{$arg} = 1; + } + + while (my ($k, $v) = each %parameterdescs) { + if (!exists($_members{$k})) { + if (show_warnings("enum", $declaration_name)) { + print STDERR "${file}:$.: warning: Excess enum value '$k' description in '$declaration_name'\n"; + } + } + } + + output_declaration($declaration_name, + 'enum', + {'enum' => $declaration_name, + 'module' => $modulename, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "${file}:$.: error: Cannot parse enum!\n"; + ++$errors; + } +} + +sub dump_typedef($$) { + my $x = shift; + my $file = shift; + + $x =~ s@/\*.*?\*/@@gos; # strip comments. + + # Parse function prototypes + if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ || + $x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) { + + # Function typedefs + $return_type = $1; + $declaration_name = $2; + my $args = $3; + + create_parameterlist($args, ',', $file, $declaration_name); + + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'typedef' => 1, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + return; + } + + while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) { + $x =~ s/\(*.\)\s*;$/;/; + $x =~ s/\[*.\]\s*;$/;/; + } + + if ($x =~ /typedef.*\s+(\w+)\s*;/) { + $declaration_name = $1; + + output_declaration($declaration_name, + 'typedef', + {'typedef' => $declaration_name, + 'module' => $modulename, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); + } + else { + print STDERR "${file}:$.: error: Cannot parse typedef!\n"; + ++$errors; + } +} + +sub save_struct_actual($) { + my $actual = shift; + + # strip all spaces from the actual param so that it looks like one string item + $actual =~ s/\s*//g; + $struct_actual = $struct_actual . $actual . " "; +} + +sub create_parameterlist($$$$) { + my $args = shift; + my $splitter = shift; + my $file = shift; + my $declaration_name = shift; + my $type; + my $param; + + # temporarily replace commas inside function pointer definition + while ($args =~ /(\([^\),]+),/) { + $args =~ s/(\([^\),]+),/$1#/g; + } + + foreach my $arg (split($splitter, $args)) { + # strip comments + $arg =~ s/\/\*.*\*\///; + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; + $arg =~ s/\s+/ /; + + if ($arg =~ /^#/) { + # Treat preprocessor directive as a typeless variable just to fill + # corresponding data structures "correctly". Catch it later in + # output_* subs. + push_parameter($arg, "", $file); + } elsif ($arg =~ m/\(.+\)\s*\(/) { + # pointer-to-function + $arg =~ tr/#/,/; + $arg =~ m/[^\(]+\(\*?\s*([\w\.]*)\s*\)/; + $param = $1; + $type = $arg; + $type =~ s/([^\(]+\(\*?)\s*$param/$1/; + save_struct_actual($param); + push_parameter($param, $type, $file, $declaration_name); + } elsif ($arg) { + $arg =~ s/\s*:\s*/:/g; + $arg =~ s/\s*\[/\[/g; + + my @args = split('\s*,\s*', $arg); + if ($args[0] =~ m/\*/) { + $args[0] =~ s/(\*+)\s*/ $1/; + } + + my @first_arg; + if ($args[0] =~ /^(.*\s+)(.*?\[.*\].*)$/) { + shift @args; + push(@first_arg, split('\s+', $1)); + push(@first_arg, $2); + } else { + @first_arg = split('\s+', shift @args); + } + + unshift(@args, pop @first_arg); + $type = join " ", @first_arg; + + foreach $param (@args) { + if ($param =~ m/^(\*+)\s*(.*)/) { + save_struct_actual($2); + push_parameter($2, "$type $1", $file, $declaration_name); + } + elsif ($param =~ m/(.*?):(\d+)/) { + if ($type ne "") { # skip unnamed bit-fields + save_struct_actual($1); + push_parameter($1, "$type:$2", $file, $declaration_name) + } + } + else { + save_struct_actual($param); + push_parameter($param, $type, $file, $declaration_name); + } + } + } + } +} + +sub push_parameter($$$$) { + my $param = shift; + my $type = shift; + my $file = shift; + my $declaration_name = shift; + + if (($anon_struct_union == 1) && ($type eq "") && + ($param eq "}")) { + return; # ignore the ending }; from anon. struct/union + } + + $anon_struct_union = 0; + $param =~ s/[\[\)].*//; + + if ($type eq "" && $param =~ /\.\.\.$/) + { + if (!$param =~ /\w\.\.\.$/) { + # handles unnamed variable parameters + $param = "..."; + } + if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { + $parameterdescs{$param} = "variable arguments"; + } + } + elsif ($type eq "" && ($param eq "" or $param eq "void")) + { + $param="void"; + $parameterdescs{void} = "no arguments"; + } + elsif ($type eq "" && ($param eq "struct" or $param eq "union")) + # handle unnamed (anonymous) union or struct: + { + $type = $param; + $param = "{unnamed_" . $param . "}"; + $parameterdescs{$param} = "anonymous\n"; + $anon_struct_union = 1; + } + + # warn if parameter has no description + # (but ignore ones starting with # as these are not parameters + # but inline preprocessor statements); + # Note: It will also ignore void params and unnamed structs/unions + if (!defined $parameterdescs{$param} && $param !~ /^#/) { + $parameterdescs{$param} = $undescribed; + + if (show_warnings($type, $declaration_name)) { + print STDERR + "${file}:$.: warning: Function parameter or member '$param' not described in '$declaration_name'\n"; + ++$warnings; + } + } + + # strip spaces from $param so that it is one continuous string + # on @parameterlist; + # this fixes a problem where check_sections() cannot find + # a parameter like "addr[6 + 2]" because it actually appears + # as "addr[6", "+", "2]" on the parameter list; + # but it's better to maintain the param string unchanged for output, + # so just weaken the string compare in check_sections() to ignore + # "[blah" in a parameter string; + ###$param =~ s/\s*//g; + push @parameterlist, $param; + $type =~ s/\s\s+/ /g; + $parametertypes{$param} = $type; +} + +sub check_sections($$$$$) { + my ($file, $decl_name, $decl_type, $sectcheck, $prmscheck) = @_; + my @sects = split ' ', $sectcheck; + my @prms = split ' ', $prmscheck; + my $err; + my ($px, $sx); + my $prm_clean; # strip trailing "[array size]" and/or beginning "*" + + foreach $sx (0 .. $#sects) { + $err = 1; + foreach $px (0 .. $#prms) { + $prm_clean = $prms[$px]; + $prm_clean =~ s/\[.*\]//; + $prm_clean =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i; + # ignore array size in a parameter string; + # however, the original param string may contain + # spaces, e.g.: addr[6 + 2] + # and this appears in @prms as "addr[6" since the + # parameter list is split at spaces; + # hence just ignore "[..." for the sections check; + $prm_clean =~ s/\[.*//; + + ##$prm_clean =~ s/^\**//; + if ($prm_clean eq $sects[$sx]) { + $err = 0; + last; + } + } + if ($err) { + if ($decl_type eq "function") { + print STDERR "${file}:$.: warning: " . + "Excess function parameter " . + "'$sects[$sx]' " . + "description in '$decl_name'\n"; + ++$warnings; + } + } + } +} + +## +# Checks the section describing the return value of a function. +sub check_return_section { + my $file = shift; + my $declaration_name = shift; + my $return_type = shift; + + # Ignore an empty return type (It's a macro) + # Ignore functions with a "void" return type. (But don't ignore "void *") + if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { + return; + } + + if (!defined($sections{$section_return}) || + $sections{$section_return} eq "") { + print STDERR "${file}:$.: warning: " . + "No description found for return value of " . + "'$declaration_name'\n"; + ++$warnings; + } +} + +## +# takes a function prototype and the name of the current file being +# processed and spits out all the details stored in the global +# arrays/hashes. +sub dump_function($$) { + my $prototype = shift; + my $file = shift; + my $noret = 0; + + $prototype =~ s/^static +//; + $prototype =~ s/^extern +//; + $prototype =~ s/^asmlinkage +//; + $prototype =~ s/^inline +//; + $prototype =~ s/^__inline__ +//; + $prototype =~ s/^__inline +//; + $prototype =~ s/^__always_inline +//; + $prototype =~ s/^noinline +//; + $prototype =~ s/__init +//; + $prototype =~ s/__init_or_module +//; + $prototype =~ s/__meminit +//; + $prototype =~ s/__must_check +//; + $prototype =~ s/__weak +//; + $prototype =~ s/__sched +//; + my $define = $prototype =~ s/^#\s*define\s+//; #ak added + $prototype =~ s/__attribute__\s*\(\( + (?: + [\w\s]++ # attribute name + (?:\([^)]*+\))? # attribute arguments + \s*+,? # optional comma at the end + )+ + \)\)\s+//x; + + # Yes, this truly is vile. We are looking for: + # 1. Return type (may be nothing if we're looking at a macro) + # 2. Function name + # 3. Function parameters. + # + # All the while we have to watch out for function pointer parameters + # (which IIRC is what the two sections are for), C types (these + # regexps don't even start to express all the possibilities), and + # so on. + # + # If you mess with these regexps, it's a good idea to check that + # the following functions' documentation still comes out right: + # - parport_register_device (function pointer parameters) + # - atomic_set (macro) + # - pci_match_device, __copy_to_user (long return type) + + if ($define && $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s+/) { + # This is an object-like macro, it has no return type and no parameter + # list. + # Function-like macros are not allowed to have spaces between + # declaration_name and opening parenthesis (notice the \s+). + $return_type = $1; + $declaration_name = $2; + $noret = 1; + } elsif ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\(]*)\)/ || + $prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*+)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*+\s*\w+\s*\*+\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $return_type = $1; + $declaration_name = $2; + my $args = $3; + + create_parameterlist($args, ',', $file, $declaration_name); + } else { + print STDERR "${file}:$.: warning: cannot understand function prototype: '$prototype'\n"; + return; + } + + my $prms = join " ", @parameterlist; + check_sections($file, $declaration_name, "function", $sectcheck, $prms); + + # This check emits a lot of warnings at the moment, because many + # functions don't have a 'Return' doc section. So until the number + # of warnings goes sufficiently down, the check is only performed in + # verbose mode. + # TODO: always perform the check. + if ($verbose && !$noret) { + check_return_section($file, $declaration_name, $return_type); + } + + output_declaration($declaration_name, + 'function', + {'function' => $declaration_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameterdescs' => \%parameterdescs, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $declaration_purpose + }); +} + +sub reset_state { + $function = ""; + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $sectcheck = ""; + $struct_actual = ""; + $prototype = ""; + + $state = STATE_NORMAL; + $inline_doc_state = STATE_INLINE_NA; +} + +sub tracepoint_munge($) { + my $file = shift; + my $tracepointname = 0; + my $tracepointargs = 0; + + if ($prototype =~ m/TRACE_EVENT\((.*?),/) { + $tracepointname = $1; + } + if ($prototype =~ m/DEFINE_SINGLE_EVENT\((.*?),/) { + $tracepointname = $1; + } + if ($prototype =~ m/DEFINE_EVENT\((.*?),(.*?),/) { + $tracepointname = $2; + } + $tracepointname =~ s/^\s+//; #strip leading whitespace + if ($prototype =~ m/TP_PROTO\((.*?)\)/) { + $tracepointargs = $1; + } + if (($tracepointname eq 0) || ($tracepointargs eq 0)) { + print STDERR "${file}:$.: warning: Unrecognized tracepoint format: \n". + "$prototype\n"; + } else { + $prototype = "static inline void trace_$tracepointname($tracepointargs)"; + } +} + +sub syscall_munge() { + my $void = 0; + + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/CR's +## if ($prototype =~ m/SYSCALL_DEFINE0\s*\(\s*(a-zA-Z0-9_)*\s*\)/) { + if ($prototype =~ m/SYSCALL_DEFINE0/) { + $void = 1; +## $prototype = "long sys_$1(void)"; + } + + $prototype =~ s/SYSCALL_DEFINE.*\(/long sys_/; # fix return type & func name + if ($prototype =~ m/long (sys_.*?),/) { + $prototype =~ s/,/\(/; + } elsif ($void) { + $prototype =~ s/\)/\(void\)/; + } + + # now delete all of the odd-number commas in $prototype + # so that arg types & arg names don't have a comma between them + my $count = 0; + my $len = length($prototype); + if ($void) { + $len = 0; # skip the for-loop + } + for (my $ix = 0; $ix < $len; $ix++) { + if (substr($prototype, $ix, 1) eq ',') { + $count++; + if ($count % 2 == 1) { + substr($prototype, $ix, 1) = ' '; + } + } + } +} + +sub process_proto_function($$) { + my $x = shift; + my $file = shift; + + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =~ m#\s*/\*\s+MACDOC\s*#io || ($x =~ /^#/ && $x !~ /^#\s*define/)) { + # do nothing + } + elsif ($x =~ /([^\{]*)/) { + $prototype .= $1; + } + + if (($x =~ /\{/) || ($x =~ /\#\s*define/) || ($x =~ /;/)) { + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^\s+@@gos; # strip leading spaces + if ($prototype =~ /SYSCALL_DEFINE/) { + syscall_munge(); + } + if ($prototype =~ /TRACE_EVENT/ || $prototype =~ /DEFINE_EVENT/ || + $prototype =~ /DEFINE_SINGLE_EVENT/) + { + tracepoint_munge($file); + } + dump_function($prototype, $file); + reset_state(); + } +} + +sub process_proto_type($$) { + my $x = shift; + my $file = shift; + + $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $x =~ s@^\s+@@gos; # strip leading spaces + $x =~ s@\s+$@@gos; # strip trailing spaces + $x =~ s@\/\/.*$@@gos; # strip C99-style comments to end of line + + if ($x =~ /^#/) { + # To distinguish preprocessor directive from regular declaration later. + $x .= ";"; + } + + while (1) { + if ( $x =~ /([^\{\};]*)([\{\};])(.*)/ ) { + if( length $prototype ) { + $prototype .= " " + } + $prototype .= $1 . $2; + ($2 eq '{') && $brcount++; + ($2 eq '}') && $brcount--; + if (($2 eq ';') && ($brcount == 0)) { + dump_declaration($prototype, $file); + reset_state(); + last; + } + $x = $3; + } else { + $prototype .= $x; + last; + } + } +} + + +sub map_filename($) { + my $file; + my ($orig_file) = @_; + + if (defined($ENV{'SRCTREE'})) { + $file = "$ENV{'SRCTREE'}" . "/" . $orig_file; + } else { + $file = $orig_file; + } + + if (defined($source_map{$file})) { + $file = $source_map{$file}; + } + + return $file; +} + +sub process_export_file($) { + my ($orig_file) = @_; + my $file = map_filename($orig_file); + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + while () { + if (/$export_symbol/) { + $function_table{$2} = 1; + } + } + + close(IN); +} + +# +# Parsers for the various processing states. +# +# STATE_NORMAL: looking for the /** to begin everything. +# +sub process_normal() { + if (/$doc_start/o) { + $state = STATE_NAME; # next line is always the function name + $in_doc_sect = 0; + $declaration_start_line = $. + 1; + } +} + +# +# STATE_NAME: Looking for the "name - description" line +# +sub process_name($$) { + my $file = shift; + my $identifier; + my $descr; + + if (/$doc_block/o) { + $state = STATE_DOCBLOCK; + $contents = ""; + $new_start_line = $. + 1; + + if ( $1 eq "" ) { + $section = $section_intro; + } else { + $section = $1; + } + } + elsif (/$doc_decl/o) { + $identifier = $1; + if (/\s*([\w\s]+?)(\(\))?\s*-/) { + $identifier = $1; + } + + $state = STATE_BODY; + # if there's no @param blocks need to set up default section + # here + $contents = ""; + $section = $section_default; + $new_start_line = $. + 1; + if (/-(.*)/) { + # strip leading/trailing/multiple spaces + $descr= $1; + $descr =~ s/^\s*//; + $descr =~ s/\s*$//; + $descr =~ s/\s+/ /g; + $declaration_purpose = $descr; + $state = STATE_BODY_MAYBE; + } else { + $declaration_purpose = ""; + } + + if (($declaration_purpose eq "") && $verbose) { + print STDERR "${file}:$.: warning: missing initial short description on line:\n"; + print STDERR $_; + ++$warnings; + } + + if ($identifier =~ m/^struct\b/) { + $decl_type = 'struct'; + } elsif ($identifier =~ m/^union\b/) { + $decl_type = 'union'; + } elsif ($identifier =~ m/^enum\b/) { + $decl_type = 'enum'; + } elsif ($identifier =~ m/^typedef\b/) { + $decl_type = 'typedef'; + } else { + $decl_type = 'function'; + } + + if ($verbose) { + print STDERR "${file}:$.: info: Scanning doc for $identifier\n"; + } + } else { + print STDERR "${file}:$.: warning: Cannot understand $_ on line $.", + " - I thought it was a doc line\n"; + ++$warnings; + $state = STATE_NORMAL; + } +} + + +# +# STATE_BODY and STATE_BODY_MAYBE: the bulk of a kerneldoc comment. +# +sub process_body($$) { + my $file = shift; + + if (/$doc_sect/i) { # case insensitive for supported section names + $newsection = $1; + $newcontents = $2; + + # map the supported section names to the canonical names + if ($newsection =~ m/^description$/i) { + $newsection = $section_default; + } elsif ($newsection =~ m/^context$/i) { + $newsection = $section_context; + } elsif ($newsection =~ m/^returns?$/i) { + $newsection = $section_return; + } elsif ($newsection =~ m/^\@return$/) { + # special: @return is a section, not a param description + $newsection = $section_return; + } + + if (($contents ne "") && ($contents ne "\n")) { + if (!$in_doc_sect && $verbose) { + print STDERR "${file}:$.: warning: contents before sections\n"; + ++$warnings; + } + dump_section($file, $section, $contents); + $section = $section_default; + } + + $in_doc_sect = 1; + $state = STATE_BODY; + $contents = $newcontents; + $new_start_line = $.; + while (substr($contents, 0, 1) eq " ") { + $contents = substr($contents, 1); + } + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + $leading_space = undef; + } elsif (/$doc_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + # look for doc_com + + doc_end: + if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') { + print STDERR "${file}:$.: warning: suspicious ending line: $_"; + ++$warnings; + } + + $prototype = ""; + $state = STATE_PROTO; + $brcount = 0; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "") { + if ($section =~ m/^@/ || $section eq $section_context) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + $new_start_line = $.; + } else { + $contents .= "\n"; + } + $state = STATE_BODY; + } elsif ($state == STATE_BODY_MAYBE) { + # Continued declaration purpose + chomp($declaration_purpose); + $declaration_purpose .= " " . $1; + $declaration_purpose =~ s/\s+/ /g; + } else { + my $cont = $1; + if ($section =~ m/^@/ || $section eq $section_context) { + if (!defined $leading_space) { + if ($cont =~ m/^(\s+)/) { + $leading_space = $1; + } else { + $leading_space = ""; + } + } + $cont =~ s/^$leading_space//; + } + $contents .= $cont . "\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "${file}:$.: warning: bad line: $_"; + ++$warnings; + } +} + + +# +# STATE_PROTO: reading a function/whatever prototype. +# +sub process_proto($$) { + my $file = shift; + + if (/$doc_inline_oneline/) { + $section = $1; + $contents = $2; + if ($contents ne "") { + $contents .= "\n"; + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + } elsif (/$doc_inline_start/) { + $state = STATE_INLINE; + $inline_doc_state = STATE_INLINE_NAME; + } elsif ($decl_type eq 'function') { + process_proto_function($_, $file); + } else { + process_proto_type($_, $file); + } +} + +# +# STATE_DOCBLOCK: within a DOC: block. +# +sub process_docblock($$) { + my $file = shift; + + if (/$doc_end/) { + dump_doc_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + $function = ""; + %parameterdescs = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + $state = STATE_NORMAL; + } elsif (/$doc_content/) { + if ( $1 eq "" ) { + $contents .= $blankline; + } else { + $contents .= $1 . "\n"; + } + } +} + +# +# STATE_INLINE: docbook comments within a prototype. +# +sub process_inline($$) { + my $file = shift; + + # First line (state 1) needs to be a @parameter + if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) { + $section = $1; + $contents = $2; + $new_start_line = $.; + if ($contents ne "") { + while (substr($contents, 0, 1) eq " ") { + $contents = substr($contents, 1); + } + $contents .= "\n"; + } + $inline_doc_state = STATE_INLINE_TEXT; + # Documentation block end */ + } elsif (/$doc_inline_end/) { + if (($contents ne "") && ($contents ne "\n")) { + dump_section($file, $section, $contents); + $section = $section_default; + $contents = ""; + } + $state = STATE_PROTO; + $inline_doc_state = STATE_INLINE_NA; + # Regular text + } elsif (/$doc_content/) { + if ($inline_doc_state == STATE_INLINE_TEXT) { + $contents .= $1 . "\n"; + # nuke leading blank lines + if ($contents =~ /^\s*$/) { + $contents = ""; + } + } elsif ($inline_doc_state == STATE_INLINE_NAME) { + $inline_doc_state = STATE_INLINE_ERROR; + print STDERR "${file}:$.: warning: "; + print STDERR "Incorrect use of kernel-doc format: $_"; + ++$warnings; + } + } +} + + +sub process_file($) { + my $file; + my $initial_section_counter = $section_counter; + my ($orig_file) = @_; + + $file = map_filename($orig_file); + + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + ++$errors; + return; + } + + $. = 1; + + $section_counter = 0; + while () { + while (s/\\\s*$//) { + $_ .= ; + } + # Replace tabs by spaces + while ($_ =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}; + # Hand this line to the appropriate state handler + if ($state == STATE_NORMAL) { + process_normal(); + } elsif ($state == STATE_NAME) { + process_name($file, $_); + } elsif ($state == STATE_BODY || $state == STATE_BODY_MAYBE) { + process_body($file, $_); + } elsif ($state == STATE_INLINE) { # scanning for inline parameters + process_inline($file, $_); + } elsif ($state == STATE_PROTO) { + process_proto($file, $_); + } elsif ($state == STATE_DOCBLOCK) { + process_docblock($file, $_); + } + } + + # Make sure we got something interesting. + if ($initial_section_counter == $section_counter) { + if ($output_mode ne "none") { + print STDERR "${file}:1: warning: no structured comments found\n"; + } + if (($output_selection == OUTPUT_INCLUDE) && ($show_not_found == 1)) { + print STDERR " Was looking for '$_'.\n" for keys %function_table; + } + } +} + + +$kernelversion = get_kernel_version(); + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +for (my $k = 0; $k < @highlights; $k++) { + my $pattern = $highlights[$k][0]; + my $result = $highlights[$k][1]; +# print STDERR "scanning pattern:$pattern, highlight:($result)\n"; + $dohighlight .= "\$contents =~ s:$pattern:$result:gs;\n"; +} + +# Read the file that maps relative names to absolute names for +# separate source and object directories and for shadow trees. +if (open(SOURCE_MAP, "<.tmp_filelist.txt")) { + my ($relname, $absname); + while() { + chop(); + ($relname, $absname) = (split())[0..1]; + $relname =~ s:^/+::; + $source_map{$relname} = $absname; + } + close(SOURCE_MAP); +} + +if ($output_selection == OUTPUT_EXPORTED || + $output_selection == OUTPUT_INTERNAL) { + + push(@export_file_list, @ARGV); + + foreach (@export_file_list) { + chomp; + process_export_file($_); + } +} + +foreach (@ARGV) { + chomp; + process_file($_); +} +if ($verbose && $errors) { + print STDERR "$errors errors\n"; +} +if ($verbose && $warnings) { + print STDERR "$warnings warnings\n"; +} + +exit($output_mode eq "none" ? 0 : $errors); From patchwork Tue May 21 12:25:11 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164722 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1541932ili; Tue, 21 May 2019 05:31:25 -0700 (PDT) X-Google-Smtp-Source: APXvYqwzC/EkvkzcbRmxj+RrsWIbfQSK8BdGziOVBkKD9QDu46iX+t442NRQavUR5z4s0RhbUYMr X-Received: by 2002:a17:906:3553:: with SMTP id s19mr43441404eja.204.1558441885876; Tue, 21 May 2019 05:31:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441885; cv=none; d=google.com; s=arc-20160816; b=tLBcVYad0nYFMr3wgZ9q9PE+JnPgX6cqhvaiSWNf1RvaFvHzzc8xQ3fOLUoFVFDpW1 y3ZMB5/dX3xsybUocT313Y8GvVVpMbaKGcocKDWbWd1NOmbxKLAzlkHMwMOVFDcDul4T 85/XEllKQJ5Ycp6EG0mSWrbsWEP+SJfcNwEONkvzbD1xDMPGmXMo+BEZRm3lmpefoUiq 7Fo12am/1hCi4sv6BQdQMcgap2bCX5sa3psBVbLkC5nY53mcQhZfBQjOGTm3eWDfptmV pxwIv6Oi+Im8P5gR5TJiPeESjYW44CP/eqHzTHWrcneuETPctEOKTWnhU29pNOHSqbDA GXGQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=oe3qCNAnptAvVIC38GAVxc3L66obGAOTbhJyLwNyUsk=; b=ldOiPdgL1hh2aAuZgqjMOo5uCxnkFktQJjFGQenEtPL4oAM9RVqeKjF6DwtOYHiamx l6/RVsAihkob97LQ9D9Nn7NBTGe8lDzWSauVsnkveuHMXQOdoaAXoiU40KDS5sAPzgEq TUFXPkTeCzz1l6xGq+gavNHRnpKan0I53kX+z/GKk8Z3YhSz7SRAHvEu2Xp/0RTQPG8s JICEevaExAOyLe/vAmeTNR8OoSgo2l0WO+rNA1t9ULDJ/6PpunhRNcPXPx9mcFMdTFD2 NQ1YW3legc8SYG0fAcNqq5LpFZ0rsoSDNKVdwQ3YfSWp6CjVgWqWpZFzUzZ035QBvPRw cvtw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=CF4eudNm; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id l58si15779874edb.163.2019.05.21.05.31.25 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:31:25 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=CF4eudNm; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52755 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3vQ-0006vw-Cx for patch@linaro.org; Tue, 21 May 2019 08:31:24 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45328) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SE-QV for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005Gc-4B for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:54450) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00054z-RB for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:45 -0400 Received: by mail-wm1-x341.google.com with SMTP id i3so2779151wml.4 for ; Tue, 21 May 2019 05:25:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=oe3qCNAnptAvVIC38GAVxc3L66obGAOTbhJyLwNyUsk=; b=CF4eudNmr6WNenANAk9BDzK92mUD19XDIbKNqR4P2QmMTZGqVr/pLLjulaDg61s8lg AdgTNuLX8LSGw81aGyax7xYjb2SLTbATEWEzOTXBozCS1IwHtt1f6LCFctYzWzAHlWh4 7sCuPjaHXhlom/o7K7yTgbu72i4+MEsIL4TdMmXBQQln00mKtzABS0hSBpROLo1WTFB3 RsJ1MMfoc0uRldtvY/iNwD7e315bklA2xAIQBhCGcbiFDT26Y+m3eyKaMGcxCfEZLgHy Zoalc8X53EJEWorJ/1CtRV5ftZJVeG/F95tbi/e5PWn7ZcPueQd39da8YoMUVtSC8FJh BP3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=oe3qCNAnptAvVIC38GAVxc3L66obGAOTbhJyLwNyUsk=; b=RpIUwOV6/BhbP1OhkkiheKtk6+5v8vt5emG7ItwLdjdduu4TTVZW/ndR6cIYgeJwXl 5IgaOiB2p6VKOeMNEQ2uOJWNRtktvPcp7pZrjrVMNu/43mfe6TZcUon2REpkCiyYTazZ R+KPAc+ILotlJVg6wV1ZsSSDwWM+1mIO04gaHAol6JC58BA6EqBAhl1OPsRXFdE+qANM sC44WISTtSMoT2CtfA3jeJoW9uRJdzhQcl3nghXGW2I/eOXoWyku7kr/Pzdog05aIAl/ huOVFrzeAqP251hIoGALrV5nMUoEfK/EvJZu+RGCcEzLTfns+ev9u2+wGRcbBwBSrHLP F6GA== X-Gm-Message-State: APjAAAVcDRcASF8HqLXWA9JuwL96R7nqkGLD17hw8c834Z+5XwBqCDYc cNgYcJYZqj6PjJmVEOgkKUuwj6Dwe+s= X-Received: by 2002:a1c:6a0e:: with SMTP id f14mr3240982wmc.69.1558441526093; Tue, 21 May 2019 05:25:26 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.24 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:25 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:11 +0100 Message-Id: <20190521122519.12573-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::341 Subject: [Qemu-devel] [RFC 02/10] docs: Add kerneldoc sphinx module from Linux X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" Add the kerneldoc sphinx module from Linux kernel commit 30bac164aca750892. Signed-off-by: Peter Maydell --- docs/sphinx/kerneldoc.py | 150 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 docs/sphinx/kerneldoc.py -- 2.20.1 diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py new file mode 100644 index 00000000000..9d0a7f08f93 --- /dev/null +++ b/docs/sphinx/kerneldoc.py @@ -0,0 +1,150 @@ +# coding=utf-8 +# +# Copyright © 2016 Intel Corporation +# +# Permission is hereby granted, free of charge, to any person obtaining a +# copy of this software and associated documentation files (the "Software"), +# to deal in the Software without restriction, including without limitation +# the rights to use, copy, modify, merge, publish, distribute, sublicense, +# and/or sell copies of the Software, and to permit persons to whom the +# Software is furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS +# IN THE SOFTWARE. +# +# Authors: +# Jani Nikula +# +# Please make sure this works on both python2 and python3. +# + +import codecs +import os +import subprocess +import sys +import re +import glob + +from docutils import nodes, statemachine +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.ext.autodoc import AutodocReporter + +__version__ = '1.0' + +class KernelDocDirective(Directive): + """Extract kernel-doc comments from the specified file""" + required_argument = 1 + optional_arguments = 4 + option_spec = { + 'doc': directives.unchanged_required, + 'functions': directives.unchanged, + 'export': directives.unchanged, + 'internal': directives.unchanged, + } + has_content = False + + def run(self): + env = self.state.document.settings.env + cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] + + filename = env.config.kerneldoc_srctree + '/' + self.arguments[0] + export_file_patterns = [] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(filename)) + + tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) + + # FIXME: make this nicer and more robust against errors + if 'export' in self.options: + cmd += ['-export'] + export_file_patterns = str(self.options.get('export')).split() + elif 'internal' in self.options: + cmd += ['-internal'] + export_file_patterns = str(self.options.get('internal')).split() + elif 'doc' in self.options: + cmd += ['-function', str(self.options.get('doc'))] + elif 'functions' in self.options: + functions = self.options.get('functions').split() + if functions: + for f in functions: + cmd += ['-function', f] + else: + cmd += ['-no-doc-sections'] + + for pattern in export_file_patterns: + for f in glob.glob(env.config.kerneldoc_srctree + '/' + pattern): + env.note_dependency(os.path.abspath(f)) + cmd += ['-export-file', f] + + cmd += [filename] + + try: + env.app.verbose('calling kernel-doc \'%s\'' % (" ".join(cmd))) + + p = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE) + out, err = p.communicate() + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + + if p.returncode != 0: + sys.stderr.write(err) + + env.app.warn('kernel-doc \'%s\' failed with return code %d' % (" ".join(cmd), p.returncode)) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + elif env.config.kerneldoc_verbosity > 0: + sys.stderr.write(err) + + lines = statemachine.string2lines(out, tab_width, convert_whitespace=True) + result = ViewList() + + lineoffset = 0; + line_regex = re.compile("^#define LINENO ([0-9]+)$") + for line in lines: + match = line_regex.search(line) + if match: + # sphinx counts lines from 0 + lineoffset = int(match.group(1)) - 1 + # we must eat our comments since the upset the markup + else: + result.append(line, filename, lineoffset) + lineoffset += 1 + + node = nodes.section() + buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(result, self.state.memo.reporter) + self.state.memo.title_styles, self.state.memo.section_level = [], 0 + try: + self.state.nested_parse(result, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + return node.children + + except Exception as e: # pylint: disable=W0703 + env.app.warn('kernel-doc \'%s\' processing failed with: %s' % + (" ".join(cmd), str(e))) + return [nodes.error(None, nodes.paragraph(text = "kernel-doc missing"))] + +def setup(app): + app.add_config_value('kerneldoc_bin', None, 'env') + app.add_config_value('kerneldoc_srctree', None, 'env') + app.add_config_value('kerneldoc_verbosity', 1, 'env') + + app.add_directive('kernel-doc', KernelDocDirective) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) From patchwork Tue May 21 12:25:12 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164717 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1536201ili; Tue, 21 May 2019 05:26:08 -0700 (PDT) X-Google-Smtp-Source: APXvYqyiMPIEHeqBT+4CfHcRmT8ZcPP1IDrRb8Qaw/9H0lh+/VKQQW5gAQQmX61AAd7REd/I6aE+ X-Received: by 2002:a50:f593:: with SMTP id u19mr82096192edm.37.1558441568598; Tue, 21 May 2019 05:26:08 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441568; cv=none; d=google.com; s=arc-20160816; b=rPSnJPp8xMmXjj/SW3K5dV2Q7cCKa1avNt9O6FOIIFH61isT/SbJ6dj2Ca1AeKb/Ze fdLDdCP2S6mdkLF5QAwrSTD0DXskuoEWY9bTXEbTojGrk3As9u200SEY6epfveD6+FxG Jb6hjZsL4SOEakvH7qZdG1/384mV7P4cZIKwyKqJ7srJDNVPZwUYzG0wsn/HHbvA7+2b SE4lBqNQs2X7G6Lgo9YXiZHdlRFgZLB8SREFCG8TeYMSh+h2690bcAwhPkw4+HM//AQ6 mb39QWlfQyxFbQJfMJdEUJBbnV4Ku3PZb4oI7MTaRujBSU6X+36bDvUPsrnhaPymUxJD Skog== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=/E+PaSgrUlg3SFZHIuAu/lXW6yDb2qBLwoSSs8XJ8AE=; b=cXmDCTui6LeCNkoS17mAzbXjNTDVVIYiqP7G8Ag/INeyGjogglePjxuIUhS+pf7Jak vDk0D+fJhWjY5adir836HfA3Nbc17YsvF5DYBxQcTfSKdGjLZMtGyqLL+/LiyEAmhij0 znwPTu5DZhLa1cXJrSRD943caQxA33IH9AnsezLkR/nTFjA2XULhTOlooqUlWwHmpbQx IS8JlbK3jPke688uhFGkT5D9qilyCPH89Y0a5/i8k/F4skOSK9/q9mqTcZP45DSw9IZN MfzmMWIPqV5sj47FKDtXnzrc4mYu/4n+2HEaF0ju8rS/zyNndQC3v9QLFzZAIQ9HVWM7 v4gQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=woYXkPI3; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id x28si15285237edd.32.2019.05.21.05.26.08 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:26:08 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=woYXkPI3; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52667 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3qJ-0001Qj-Dj for patch@linaro.org; Tue, 21 May 2019 08:26:07 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45251) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3py-0001P4-3i for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3pw-0005Fr-Tm for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:46 -0400 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]:40122) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00055e-M6 for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wm1-x32f.google.com with SMTP id 15so2679193wmg.5 for ; Tue, 21 May 2019 05:25:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=/E+PaSgrUlg3SFZHIuAu/lXW6yDb2qBLwoSSs8XJ8AE=; b=woYXkPI33taUXzNCellJQiMx4dJlvYOHYHquJieBhU0SL6NDBJHRELujQpegBSR5P6 2vjq5ZnHbtyYWTbYtfOJ9t2jrQWrN9PaqMzxDMeCqkGznCsgybv7gmOG478DTDBIKrpj DJGh41W2kwiOPLhUfG5CVneJNQ/l0T0jwXHvlsXHcOtStQILelU/HHcL7+9n0HWCCr0A T5sDarpB3Exsco8HL2s3Vju3xHPsKYKMXDH2/660JwsDiaHhzk16T7iTdnLihOs78zF5 04aFwTB0B+Gdnv00x4PKGX+leVmsXCdIJVCFvz/J7fLQ6KQxKdPqY1ilb5XgVrdFfaT/ GgHw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=/E+PaSgrUlg3SFZHIuAu/lXW6yDb2qBLwoSSs8XJ8AE=; b=Xqcz4ZTtGrclnJMbi6KFxlAZWHPJtURTvclZriUxrcXLUt8KvdCyBkrURU/XBozfRq HnLK5tGbLXKoz8nvE8yDPIp67es3W7nPV9wOYv9I8xTFoajT7HFKXJz3xTUKOEs1ek8x ab3OGphkM1LHOJlR8LP787x0kPRTuua6I9hJZiLN85enO2HoxCvuvtykudOjHb9AQSPx GaUkyz304qwbnL7LaLzfsRb44CQctukYGLEo7E6h1l2aa6/KDomeD34TloYxb/76sY4C O+gMvN8z0cftUWiIFre3+Nf4sGiM59hfeGHa1gCDlHnlmOe56MpLjBgryMEN/N3yK9xY bTZw== X-Gm-Message-State: APjAAAUgH+ZTBcImwi7B8zegjVWK0ek8zj4iDCYZt1e5jZ0T0jxsEEmi jgAbllED8yjVFEblUWhXzZo6FTRmkr0= X-Received: by 2002:a7b:c301:: with SMTP id k1mr2727972wmj.43.1558441527480; Tue, 21 May 2019 05:25:27 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.26 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:26 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:12 +0100 Message-Id: <20190521122519.12573-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32f Subject: [Qemu-devel] [RFC 03/10] docs/conf.py: Enable use of kerneldoc sphinx extension X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" Signed-off-by: Peter Maydell --- docs/conf.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) -- 2.20.1 diff --git a/docs/conf.py b/docs/conf.py index befbcc6c3e1..9109edbcb97 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,8 +41,7 @@ except NameError: # add these directories to sys.path here. If the directory is relative to the # documentation root, use an absolute path starting from qemu_docdir. # -# sys.path.insert(0, os.path.join(qemu_docdir, "my_subdir")) - +sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) # -- General configuration ------------------------------------------------ @@ -54,7 +53,7 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = [] +extensions = ['kerneldoc'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -213,4 +212,10 @@ texinfo_documents = [ ] +# -- Options for configuring kerneldoc extension ------------------------- +# We use paths starting from qemu_docdir here so that you can run +# sphinx-build from anywhere and the kerneldoc extension can still +# find everything. +kerneldoc_bin = os.path.join(qemu_docdir, '../scripts/kernel-doc') +kerneldoc_srctree = os.path.join(qemu_docdir, '..') From patchwork Tue May 21 12:25:13 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164719 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1538847ili; Tue, 21 May 2019 05:28:47 -0700 (PDT) X-Google-Smtp-Source: APXvYqys76T8ZSkhY9OUmEKwyuGH6gKnOA+0kUnf1cFvw+N2Ton1MGt9jKt4Y5fVj837RNzS7/2g X-Received: by 2002:a05:6402:13cf:: with SMTP id a15mr82063885edx.70.1558441726904; Tue, 21 May 2019 05:28:46 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441726; cv=none; d=google.com; s=arc-20160816; b=F4EY0jVvoFI+NuspVR5pliA888uR5apED2mNkGq0SGQRjhrGKdg7LQH1GqXWQYADz2 amgYAKJeULRvAXTu/Dw6LDbKy3il6G8NROz3AULEzyC5L+GjSQvbDp9r7aF6FxLj0x6/ 0GGx5frFNPIs0T0mLkTotqTx/0RI6V0cckhScC+T1wrSJI2NVpm5E5bWrMmaln+2pmzn bABODdbVqrs8D+2e97btvNCMlUiAZoZUnulBxPRP7fU6EkKdqkkkVkCJdmc2B7Ets8+V esenoNyN1tphOIVeAaoUvzY8qqWXYhvNyYdxCXlJuCQKln40PdwcsjmUGmeAzZ4+nGLR iiTA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=6OFDFvuvQviFWUA+ErkQZRrbDM3t1pANZfkvzqmBlg8=; b=aT7ApVFoYFkTO6AZz9PDaFAYPPJ53+x77g5M1HmahL2Iz2S3Hnc5Q4WiLeK0Ud51Df p+BxwuVsh+Wo/h5NQYnvo0nwFLDFAXM/ve4OW4nhkeyXiDIeUenK4ff5YW5mel6x+1en YhOTDccwOLxK9Pav79ykR5ArHxDb9bgETWeMTNxYzNxLTS0N3oAnnDYEn451vQIsmA5Q g/rHyZBvRqqDfNSl6fO/cUB3m8GU0HTAgjVatdaKbn4GwMmcrwtxiK4CJHeIj6KOSriH SW5EOdPA5/CuUiJXwpEPAYQ8/sNLF6uIUrj2gSMz17Z0w+PUVKZB/OZQY+2rtKe2X+Y+ fTeA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=npj4YbrO; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id w20si3159709eda.95.2019.05.21.05.28.46 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:28:46 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=npj4YbrO; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52692 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3sr-0004FY-Ng for patch@linaro.org; Tue, 21 May 2019 08:28:45 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45331) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SG-RJ for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005GA-0V for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wm1-x329.google.com ([2a00:1450:4864:20::329]:50611) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00056N-Ii for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wm1-x329.google.com with SMTP id f204so2799900wme.0 for ; Tue, 21 May 2019 05:25:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=6OFDFvuvQviFWUA+ErkQZRrbDM3t1pANZfkvzqmBlg8=; b=npj4YbrO4P/rhMjEvX/1V6DzWudQYkMfQHNy5tszxjNs7loGgjR/IyshL2nc3YjMUk 4vi94cWZEmGyS5GlHzV5BMvAUFsI78B+ur4qTvirFuwOK4GSWsnpquL+SoFnzCn/zQTZ KWQlBxUgOT2uZwFHoj0kvUkHVds1h1nSoRL7oWWdIaZgL+1ww+FE7d9F8llWL5JNUiVK 5kTpz5LzyAG2FFh3sSjdfd3P/ggiAhKnPZ8hVsYg/2+MTO7tZ6HbwlBgUWduC+4ATNM/ omRvkt20z2Xk2Aieqv/dT7DftF9oT6/Sh1nevREJBzekv/7CBAnhlGkL8Qxyzn60Zigz sFWg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=6OFDFvuvQviFWUA+ErkQZRrbDM3t1pANZfkvzqmBlg8=; b=UBWGbD44tCd3DabT/42zg7p4cuVZdbOQW7Na/T6KB1T4uEYd525K26N+MBdVaXtoDa +WP6t058Rn6RPNisiWKxzfdI8wp87Q3LB6B0VTC9AUXGHbYGGUABWtYVUw+ZmMlpAiqE 1mhLbqGY+QI8NHQ36zbLf4tfqAs485BJJjYJr2J+JQ5nX3IMyHFa6KHWhJ//bH7SXsrA QSuT6Kb2M9TQGgcB5JOILyYzma8HqA75ccBZ4XMkx5n17L++5mt1Md1gVFIw8oRrzNxv RI8xUETIfvBKRsFU0Wv0JmvJKckcZgztSp8U3tthV6TW7O6jKFBCpl2bO6bLF4dZ6ZMt DZ5w== X-Gm-Message-State: APjAAAUjDCBcKtcw72t9pDshurTB0IbZmpeCUFidNeAbPIJ4wdGIg/je bSgOqj6bh6yHpYkJHLtQrMHPeBJ0D9I= X-Received: by 2002:a1c:740d:: with SMTP id p13mr3389604wmc.2.1558441528747; Tue, 21 May 2019 05:25:28 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.27 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:28 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:13 +0100 Message-Id: <20190521122519.12573-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::329 Subject: [Qemu-devel] [RFC 04/10] docs/conf.py: Ignore some missing references in nitpick mode X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" We enable Sphinx's 'nitpick' mode via the command line -n switch, which means it warns about references to things it doesn't know about. Add a whitelist of expected-not-to-be-present types, to avoid false positives when C function prototypes use standard integer types. If this whitelist gets too long and unmanageable we might be better off switching to non-nitpick mode instead. Signed-off-by: Peter Maydell --- docs/conf.py | 11 +++++++++++ 1 file changed, 11 insertions(+) -- 2.20.1 diff --git a/docs/conf.py b/docs/conf.py index 9109edbcb97..388299fb25b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -114,6 +114,17 @@ todo_include_todos = False # with "option::" in the document being processed. Turn that off. suppress_warnings = ["ref.option"] +nitpick_ignore = [ + ("c:type", "int8_t"), + ("c:type", "int16_t"), + ("c:type", "int32_t"), + ("c:type", "int64_t"), + ("c:type", "uint8_t"), + ("c:type", "uint16_t"), + ("c:type", "uint32_t"), + ("c:type", "uint64_t"), +] + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for From patchwork Tue May 21 12:25:14 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164720 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1539185ili; Tue, 21 May 2019 05:29:06 -0700 (PDT) X-Google-Smtp-Source: APXvYqyLqJvW3uSJRvG8ASmRcaHFVzdyAaG7VyQN2GPC0kpbaqHvZhglGWCydTdeqxe+87exCx36 X-Received: by 2002:a50:9266:: with SMTP id j35mr83338670eda.60.1558441746833; Tue, 21 May 2019 05:29:06 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441746; cv=none; d=google.com; s=arc-20160816; b=LxbF129TYnRPKsT58z/BizEBmSdUzTpxzCMoNzXN6INE+apXS7ARQSHFfiER77+X6i PPc0p8RR+5aqK3OF0VFGuKUKUzNULrmEU4GZ2ZL6YTMWE3Qp3i6Ic0xobz6mmkgJsMIX Yu27G2qj7orXd9GCE+rodc4SSSdlb3nqbDCvfE+qBqxylioreFrt5hGhJqoCWprEDcJY bJs4Dytsp4dYrxXTMtDCgdPbLacUuMXJm1Hg7fzz2WdzmGDHK+yZHC0WK4Z8tx2b8Yfl MEB+1YqS4fmzE5iCQ31OgdUSL9ud+SGQuBqsl5NEvlPijTkI4MOYqO6USHVN6/IEc6aS 47HQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=8SOMLkZr4NB3XMui3lU6laKTlnUoguc42H2phVbp83Q=; b=ohUkYXN4euK9QnAstCEyHPT3b8khn2oVMpLIaWplEYBBBXmBTwGSuRdizqkrObdZ6Q dXkRRqtwE5kudAHH9+3apyxfamyna5iSg/P+lpHkwr0AgF7ZGdb+4TXE4pkbLTxvfFPa XkdRcXmHkVjm1Fl0chfV3UKEAPBEbPkaUwLdi3Bxgcep+DeHfvw+8udbkTM1cgVRpO5q HnQZ3Ka0tIAWI4J+3SJ5Z7mlNZlzLTyv5ANAoOsrpYrHsmLWZscPc3/NiG5mpEwMAPkR 4CcJGaugG5+q9A6p398GE4J+OWRHmcVfaCYqNbAdk1gJPoOfwvpT+EdvXm8MkpfYZV33 +ArA== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=DOZi1FuK; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id r5si13440127ejn.357.2019.05.21.05.29.06 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:29:06 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=DOZi1FuK; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52690 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3tB-0004Dl-Ku for patch@linaro.org; Tue, 21 May 2019 08:29:05 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45326) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SD-QT for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005GO-2B for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wm1-x334.google.com ([2a00:1450:4864:20::334]:38529) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00057F-Om for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wm1-x334.google.com with SMTP id t5so2694773wmh.3 for ; Tue, 21 May 2019 05:25:31 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=8SOMLkZr4NB3XMui3lU6laKTlnUoguc42H2phVbp83Q=; b=DOZi1FuK9945umJVeVpsmdNtdtHLNtnhz579D1BPh57g92AwEyGTGJPgvSPHqxe6BK TrpzqSqylljDXqZ8o5WX12HHLmQ9+nECzL8rQFjvfkvSRNCyWJDZTJbX/l7Mb6VkTH3A 7cHgfjd22OxY/qECsiGCp+5QUxxtvjEFs+i38IZVmb9b3fyfVz92I9QUtlcDuESFkBLG PQd7HqWTKQnouXlroIRKv8YbOyhT/tiStAvlh5DgWeaTPubSrHFXLSwUV1dkKnNwPsuH sf5AERvKxqchnD9w192Y1scG1KNNBMRou4AjMt0U0UlGHMBBfa100YmxAMe3NCVoBQl8 EuTQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=8SOMLkZr4NB3XMui3lU6laKTlnUoguc42H2phVbp83Q=; b=j9JQqOwGlpfLWHKy1PW40oqitvMrcOHlsDWJHqbkrsCGvVuqsJcYhwFu5/8t8UXt5f oIwwnbEuwnri+sk1ipVswr46C8qM0fjdLTmYr8vw72FuFV+tOl13+oXrRky4074xnYNE TmhkXujlvZ9O2GsUf139z2ajgKucKfr2uIphlDOiyS3X4yfgqUZmSyeeg0eHOK0VEJFf zvR9q09Mm2KHUYL5i27uxaamk9eTB5PTU3s+bLb8DOgmuadf4bVY416GCSnfNOLP5QkP 6tqM4lZdX7usPp2H0cbHo6+bn2864Xu4uz0+v2W+K72aEJD5MnLIX7NMnNYwWurpkQ9Q fwww== X-Gm-Message-State: APjAAAWZ2AmhTVZJOSxiJKsMGQnj9SetbLI7Mor5PtARRJXWmEXqsNox Df6t1OCsw281fdSSzbAj/ZxOYwGrUKE= X-Received: by 2002:a1c:3c2:: with SMTP id 185mr3301459wmd.91.1558441530029; Tue, 21 May 2019 05:25:30 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.28 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:29 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:14 +0100 Message-Id: <20190521122519.12573-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::334 Subject: [Qemu-devel] [RFC 05/10] bitops.h: Silence kernel-doc complaints X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" 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 --- include/qemu/bitops.h | 52 ++++++++++++++++++++++++++----------------- 1 file changed, 32 insertions(+), 20 deletions(-) -- 2.20.1 diff --git a/include/qemu/bitops.h b/include/qemu/bitops.h index 3f0926cf40c..f6e76b5952d 100644 --- a/include/qemu/bitops.h +++ b/include/qemu/bitops.h @@ -423,13 +423,16 @@ static inline uint64_t deposit64(uint64_t value, int start, int length, /** * half_shuffle32: - * @value: 32-bit value (of which only the bottom 16 bits are of interest) + * @x: 32-bit value (of which only the bottom 16 bits are of interest) + * + * Given an input value:: + * + * xxxx xxxx xxxx xxxx ABCD EFGH IJKL MNOP * - * Given an input value: - * xxxx xxxx xxxx xxxx ABCD EFGH IJKL MNOP * return the value where the bottom 16 bits are spread out into - * the odd bits in the word, and the even bits are zeroed: - * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N 0O0P + * the odd bits in the word, and the even bits are zeroed:: + * + * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N 0O0P * * Any bits set in the top half of the input are ignored. * @@ -449,13 +452,16 @@ static inline uint32_t half_shuffle32(uint32_t x) /** * half_shuffle64: - * @value: 64-bit value (of which only the bottom 32 bits are of interest) + * @x: 64-bit value (of which only the bottom 32 bits are of interest) + * + * Given an input value:: + * + * xxxx xxxx xxxx .... xxxx xxxx ABCD EFGH IJKL MNOP QRST UVWX YZab cdef * - * Given an input value: - * xxxx xxxx xxxx .... xxxx xxxx ABCD EFGH IJKL MNOP QRST UVWX YZab cdef * return the value where the bottom 32 bits are spread out into - * the odd bits in the word, and the even bits are zeroed: - * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N .... 0U0V 0W0X 0Y0Z 0a0b 0c0d 0e0f + * the odd bits in the word, and the even bits are zeroed:: + * + * 0A0B 0C0D 0E0F 0G0H 0I0J 0K0L 0M0N .... 0U0V 0W0X 0Y0Z 0a0b 0c0d 0e0f * * Any bits set in the top half of the input are ignored. * @@ -476,13 +482,16 @@ static inline uint64_t half_shuffle64(uint64_t x) /** * half_unshuffle32: - * @value: 32-bit value (of which only the odd bits are of interest) + * @x: 32-bit value (of which only the odd bits are of interest) + * + * Given an input value:: + * + * xAxB xCxD xExF xGxH xIxJ xKxL xMxN xOxP * - * Given an input value: - * xAxB xCxD xExF xGxH xIxJ xKxL xMxN xOxP * return the value where all the odd bits are compressed down - * into the low half of the word, and the high half is zeroed: - * 0000 0000 0000 0000 ABCD EFGH IJKL MNOP + * into the low half of the word, and the high half is zeroed:: + * + * 0000 0000 0000 0000 ABCD EFGH IJKL MNOP * * Any even bits set in the input are ignored. * @@ -503,13 +512,16 @@ static inline uint32_t half_unshuffle32(uint32_t x) /** * half_unshuffle64: - * @value: 64-bit value (of which only the odd bits are of interest) + * @x: 64-bit value (of which only the odd bits are of interest) + * + * Given an input value:: + * + * xAxB xCxD xExF xGxH xIxJ xKxL xMxN .... xUxV xWxX xYxZ xaxb xcxd xexf * - * Given an input value: - * xAxB xCxD xExF xGxH xIxJ xKxL xMxN .... xUxV xWxX xYxZ xaxb xcxd xexf * return the value where all the odd bits are compressed down - * into the low half of the word, and the high half is zeroed: - * 0000 0000 0000 .... 0000 0000 ABCD EFGH IJKL MNOP QRST UVWX YZab cdef + * into the low half of the word, and the high half is zeroed:: + * + * 0000 0000 0000 .... 0000 0000 ABCD EFGH IJKL MNOP QRST UVWX YZab cdef * * Any even bits set in the input are ignored. * From patchwork Tue May 21 12:25:15 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164727 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1548075ili; Tue, 21 May 2019 05:37:08 -0700 (PDT) X-Google-Smtp-Source: APXvYqxCVR8cYmhb+6ccjFYTVU8kIO1Uigvpo6BwGyBJiTexcVMVlyhGSIWZOeWY8IxRT8FC4TQs X-Received: by 2002:a50:84e1:: with SMTP id 88mr81975732edq.193.1558442228091; Tue, 21 May 2019 05:37:08 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558442228; cv=none; d=google.com; s=arc-20160816; b=ETG4ZQnxIAnU7hop1V/AoZSEeDvRzWI8uJ6HlfYthTIeSqScBOgZOi98aYtY6a7daB T+2Uq2SJXQiDA5pVR7zkKEBfkxRS9tGo4d1Jubqm6orxZ7iI7tv3NYB1+6dFd0zaiFlM kH9FeYppg4zjjT9228jKD09Sg0iWPeLlxlhgqkGBECqoSGerICsRdsMZZYBuPmNmq/1c JQY1FcR4l8UOlDnIL16plk4WGxCyouCEwlOrA6SJbCwhe/AfwHwepxI77xqxm2Z4ONFY UUI08UxsWXDK/z/+0W+69bYDM5H2gUkmj0ywLW96MpZ1PKa63OPjRnTvMx4c/TdCofhK JKPQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=uepm/tgVGvk2ZbI1+hCKv4c6WBeYrsTqZ1hQF2HFmEo=; b=K2+4ahqLTYvcKqBwwqqBy8/wEMycatsbNXulUxFhux2nS/D1ZzEbxzv/AoLkxHkIvt QcFCNCVoci+vynZfQW4rnYC1HGaeKIr5xbWw3CFcHWtKIsiKYwJjC1ocmQ05c69f1n/5 hHrgwO16VPXraqxEbQaMX+wLJEhcWdPQo3gMg875n9zWnGxDbOiYcoF19vMsA5ZcOnSI 9F49jjkKjyj/SVgUEWBcQMb9Y/DZh4KYZM/aa2cCuhFC+GEAJiFcuAUPXGzT/U8VD/0j k9MTb6LFuAlrU7Rn85XiXAyi9kjpkVGDAqeHcyZzRwsuJAfDr90y6wzkV0l9znkWMVRt hQog== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=vnEU13DR; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id n1si2625830edd.205.2019.05.21.05.37.07 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:37:08 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=vnEU13DR; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52883 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT40x-0001xC-55 for patch@linaro.org; Tue, 21 May 2019 08:37:07 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45401) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q4-0001U6-Mm for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3pw-0005G3-Vd for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:51 -0400 Received: from mail-wr1-x441.google.com ([2a00:1450:4864:20::441]:37548) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00057w-N0 for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wr1-x441.google.com with SMTP id e15so18403506wrs.4 for ; Tue, 21 May 2019 05:25:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=uepm/tgVGvk2ZbI1+hCKv4c6WBeYrsTqZ1hQF2HFmEo=; b=vnEU13DRzO/+QhfrSenmnXb8vqzq/j7ubcYC+eMNcXj/H/niDAgNMIUlGxiPPxTbeN bnEgqupVUJwa+6kGz1SbC+5Ee73bhFI0p9XGn+wxTkbkFuqwqa1OxKjwBU+WoFemRoSY UQi89+fVxc3XaiS027YOk02WQhJWLYp/RCfcXYKDjoEs5R86guZgD2hvyn8aaUaiH/GW 4mT4goHvHEYij6D+eM2kj9hO/2ocPw1t9lxVHuPaCHXUa93ZQu/ogJeUQ0dtwqkLtlJM jSXltd5Py0V4PSpqc7es/KeZ39PIvUkWPULR7DT/BzAjBAlHC9dwEyP6k6t8LsOZn0ct 7pmw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=uepm/tgVGvk2ZbI1+hCKv4c6WBeYrsTqZ1hQF2HFmEo=; b=RYAmVjdcvopr4H5dC0nVY/JB9FhZV9UyrOVPiT1qBRdCvAX36KWBfWPVTs1ZIu+dN3 3M4kyPDns4vxyMSUwp+lqqz0HDvj4jWuOOLp3IMVSpYW3OYXxJ/fjAGcGeU8Ky2xnXRb l5fdiE1ZuAP2BhNsgv8kxoVT504xzW6ZVRh1GZNMVXJkbdKoDhret4V7S18gPyFDvBts YTLXtglWs/X2S0wAgybboL3A7B0Y2ObAa9cAYobu7z/6alYpjzfDBWMgzZeXiWg1Dcr4 84qbJpPi19UkkMOLLuVBzXs9krfzDUUrHfuFVfSpAb6pslHMSwJAS8r3u+QNEdokKtTe MWzg== X-Gm-Message-State: APjAAAWNNSH108M/zAr8tTvswlR/Bn0B60Zdh8X5D88FaIKztEfYpVVk XXFUxekkAaT2w2o9NM1BrGXLmNqJpwA= X-Received: by 2002:a5d:55c9:: with SMTP id i9mr985311wrw.261.1558441531476; Tue, 21 May 2019 05:25:31 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.30 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:30 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:15 +0100 Message-Id: <20190521122519.12573-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::441 Subject: [Qemu-devel] [RFC 06/10] docs: Create bitops.rst as example of kernel-docs X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" 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 --- docs/devel/bitops.rst | 8 ++++++++ docs/devel/index.rst | 1 + 2 files changed, 9 insertions(+) create mode 100644 docs/devel/bitops.rst -- 2.20.1 diff --git a/docs/devel/bitops.rst b/docs/devel/bitops.rst new file mode 100644 index 00000000000..6addaecf8d7 --- /dev/null +++ b/docs/devel/bitops.rst @@ -0,0 +1,8 @@ +================== +Bitwise operations +================== + +The header ``qemu/bitops.h`` provides utility functions for +performing bitwise operations. + +.. kernel-doc:: include/qemu/bitops.h diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 2a4ddf40ad3..49cb212a8b4 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -21,3 +21,4 @@ Contents: testing decodetree secure-coding-practices + bitops From patchwork Tue May 21 12:25:16 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164725 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1545342ili; Tue, 21 May 2019 05:34:29 -0700 (PDT) X-Google-Smtp-Source: APXvYqyF8zmVnsx2Z59T9Puz2OqYF780dMoWTuBM9oxI8HIqwWTCQIm1vfaUnIVZyEBlxCEG/sOo X-Received: by 2002:a17:906:843:: with SMTP id f3mr52779394ejd.70.1558442069130; Tue, 21 May 2019 05:34:29 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558442069; cv=none; d=google.com; s=arc-20160816; b=G+gGVSzTiU3W3YDO63tYpeLD61I5DLb+23EQ9Fq2y80UGAZ+7b0CgV8q4lhkWmz2Kp PZi+MX4Lv3BRg7Nl6+8Do/m/zCupZSlt9ynZ7RS10Asq8TM/2tGBqJOvzGm/W0TiZlUN 43Og6ENx0cYeRwwo7jqNrZ+fpzJHbcOK+hJ7+fxNsSPs68z9U4A4MkXXsvoeVO3ZYGNz rbT+i4pXmkHBJxUVAgY/VofQqAw1CELd03dUm8eORX+l1auV3cfdoOjrxMuP84BeOo4j Fg6QjjvQOl5Bwr9OAcHxGN1ZADGZroLHztrUrxM4ylxHRUPtllo0BrPiUTOR6KIuOmux qbtA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=R2n/a/9G76Yi92R/Ho6SyZIUaGzncWttQDNv3ZwW0cE=; b=uugK/qnTt3R1Z69aHepU/Zfk5VvliAzcbhGqZhdn5ULpo9u6TtVqN09yo7n1/DaoWv BQHsgnZmKsPUR+BcEXSwDM2K+/RmNvQvCPdQPqgrrZ9zIxpSZOJKgBsqbGKB79G6NBgm /yS3PgXJVYX9CcuL8Pp4h7xZbznmy1oRlKfnkZOxU4h+v7O1t0bKTIpnIcTwa+k4VGKr 2j+PXbfIL0e30efEi6rcDR2JzMz5xtUvoqSVqAAARsVP3S83Rb2eKnyzOx4jAfqy/neE StrsPmtGaKVfVsbCcFyBLl2rL2mN2C4DY75wBnexjqKyujrTDlvPxrWxlNXxNScU2ny2 yqnw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="daR/x1bh"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id 96si4140830edq.250.2019.05.21.05.34.28 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:34:29 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="daR/x1bh"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52778 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3yO-0000G5-3i for patch@linaro.org; Tue, 21 May 2019 08:34:28 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45332) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SH-RM for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005HP-JL for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:38683) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3px-00058d-8b for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:45 -0400 Received: by mail-wr1-x435.google.com with SMTP id d18so18397815wrs.5 for ; Tue, 21 May 2019 05:25:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=R2n/a/9G76Yi92R/Ho6SyZIUaGzncWttQDNv3ZwW0cE=; b=daR/x1bhZwTFeUyso7yuHYeAUMb94czQdx2FJ7KWqJyV/COHfFzYYjHPcYgo8/xAh8 q6Vswi6pltIJLEga1/MYgPl0Tj8VdYBK12GzKyoxa4yDIH6Gf/EDPbql/QrEdQb0rdS1 yOSBheA22pIAhykYovCVWujL7Q1jodNedDxt2tHKaTVV+YL7DSSSCxADTGNF3gIqN1gI X82qC/6tTjOQJHiPOMx/dR0nrvZjh2VVim7BqFL+Ug0G+jM2f+joxRNXtfY68fmDAI9q Uev0clPsHD0edfp+bbPflz4jxj/TkZuzax1jJbjgkzV0uXxFWwGO4l9K15sX7aLbmI4m CROA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=R2n/a/9G76Yi92R/Ho6SyZIUaGzncWttQDNv3ZwW0cE=; b=LaJni3of+sO9s4Ra9tmIJU04J9LVRDkOGekKilS3JJbWfwhl0GGM8ph+sCKttripfx K74JSDtzE9W3LcxRIGA2fm2wS2xrHZyMi6a1JuRMZrpFrl6KdsgD81GUfA8r+aCPiVp2 vbzLItg8WT5e6psTQAC7mQYnuWd3DiVI/to4ROu35vQBtmsw/4wP0PHaWprI0BE/LhwL HDmLXVtZJ8YRpsd/FKXJQkQTIFy4rJgLWIm4T5G5/2sK+V3UzbhcIB/LYENpuWJBezzC IayP/dKm3tkfvxW6W8KhWWcAj553y/4OGbXzeBgQlYF21tKgC7bujO9Hy9FOa4MG6MRd dwmQ== X-Gm-Message-State: APjAAAXnqAIHnx10gVDdBH7WVra77DjoCC9kFLtVK6Ha7RSQEwa2OOw2 zNhEa3P4wzCJ+npavue3v60lLb9+s6g= X-Received: by 2002:adf:9bd2:: with SMTP id e18mr577759wrc.210.1558441532719; Tue, 21 May 2019 05:25:32 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:32 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:16 +0100 Message-Id: <20190521122519.12573-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::435 Subject: [Qemu-devel] [RFC 07/10] memory.h: Fix kerneldoc syntax issues X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" If you try to use kerneldoc to extract the doc comments from memory.h and run sphinx on it, it generates some warnings: * various functions are missing a parameter in the docs * some 'unexpected indentation' warnings where a list isn't marked up with the leading/trailing blank lines and bullet markers that rST expects These aren't the only issues, but they are the only ones that are actually warned about (as opposed to generating misformatted output). Signed-off-by: Peter Maydell --- include/exec/memory.h | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) -- 2.20.1 diff --git a/include/exec/memory.h b/include/exec/memory.h index 9144a47f571..8447a16ded1 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -907,6 +907,7 @@ void memory_region_init_rom(MemoryRegion *mr, * @mr: the #MemoryRegion to be initialized. * @owner: the object that tracks the region's reference count * @ops: callbacks for write access handling (must not be NULL). + * @opaque: passed to the read and write callbacks of the @ops structure. * @name: Region name, becomes part of RAMBlock name used in migration stream * must be unique within any device * @size: size of the region. @@ -995,7 +996,7 @@ static inline IOMMUMemoryRegion *memory_region_get_iommu(MemoryRegion *mr) * Returns pointer to IOMMUMemoryRegionClass if a memory region is an iommu, * otherwise NULL. This is fast path avoiding QOM checking, use with caution. * - * @mr: the memory region being queried + * @iommu_mr: the memory region being queried */ static inline IOMMUMemoryRegionClass *memory_region_get_iommu_class_nocheck( IOMMUMemoryRegion *iommu_mr) @@ -1558,6 +1559,7 @@ void memory_region_add_subregion_overlap(MemoryRegion *mr, /** * memory_region_get_ram_addr: Get the ram address associated with a memory * region + * @mr: the memory region to get the ram address for */ ram_addr_t memory_region_get_ram_addr(MemoryRegion *mr); @@ -1650,6 +1652,7 @@ bool memory_region_is_mapped(MemoryRegion *mr); * * Returns a #MemoryRegionSection that describes a contiguous overlap. * It will have the following characteristics: + * * .@size = 0 iff no overlap was found * .@mr is non-%NULL iff an overlap was found * @@ -1657,11 +1660,12 @@ bool memory_region_is_mapped(MemoryRegion *mr); * relative to the returned region (in the .@mr field), not to the * @mr argument. * - * Similarly, the .@offset_within_address_space is relative to the + * Similarly, the @.offset_within_address_space is relative to the * address space that contains both regions, the passed and the * returned one. However, in the special case where the @mr argument * has no container (and thus is the root of the address space), the * following will hold: + * * .@offset_within_address_space >= @addr * .@offset_within_address_space + .@size <= @addr + @size * @@ -2107,6 +2111,7 @@ static inline bool memory_access_is_direct(MemoryRegion *mr, bool is_write) * @addr: address within that address space * @attrs: memory transaction attributes * @buf: buffer with the data transferred + * @len: length of the buffer */ static inline __attribute__((__always_inline__)) MemTxResult address_space_read(AddressSpace *as, hwaddr addr, From patchwork Tue May 21 12:25:17 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164721 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1539854ili; Tue, 21 May 2019 05:29:44 -0700 (PDT) X-Google-Smtp-Source: APXvYqy1pO6Z8Qxx+dwi5Tv5ZC3iE1KEqPPkjr6TKqfYvk5N/h6L+O6j0iCGBDHwssTqdYOPrS+G X-Received: by 2002:a50:f9cc:: with SMTP id a12mr82771316edq.272.1558441784018; Tue, 21 May 2019 05:29:44 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441784; cv=none; d=google.com; s=arc-20160816; b=ePoFyZ/AflyFs6kD3E+07sNprRsRRhxIYYqNH8bZ1T4Z5X23OkHiZjeVuZiyI/TwhL wBuP6vDfRDnQ2ux4IVJn7yRUAgKH8JqhesZjgbCvygb4OIvz59gRMJJ26NE/PCmmiU3X qEQQgUkLdi2d0eAEQBUNyNiDC7nOCDQRbDE6gz1uZRUJpA2PT8EynrdD91/26l08lJOD y/MOZIJtTzh4xXyhHkgC1CGWdx8+gF2wCVqoVIQJXAGmFwY7bLPCo3Egv0I/vaW05jQV CGMFPk1Rtd5jR4tbblz6Lm5ek8EdOpQn+gBHmueY3waQRlCz1fkmW7ehuJcBYBCcYJZY +YDw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=hp1runAbdQd7C9+DO77cwqbwEDr2QCIxmTa56UZ3hFs=; b=ffxkExgVg2IF0rwDrBq/FCK7IPICucZTBpMKS6RlAqbpNwcP+JG3Urmbc2evUJ6ROV 5DU9WuKQqkod/0ruYKYt31XlqwaeFq5Cot+05I7SdP7wRY6WJh7rRSUtpjvqb3HLA3c9 Qodi1h3rc1qRZuR2HSdJfBCNG9qGuAzpOMMROqYnkNUVW+dk1wv1X2MeorQRuaUepHiv 0p0xCYw9IJExffrnodBfsBmY22Um2aLmRdKRifW2hX8Mr5teybjNmh8+aP6AnyYD8r40 /hAVDuLUrszDf5TBivOC3EE3OSwpiTCnbb7xU0VuVAcs0ldN+pkK+OMw7qY/D45YaVWU jEQQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=AhpuxbrH; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id k17si8579895ejz.93.2019.05.21.05.29.43 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:29:44 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=AhpuxbrH; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52700 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3tm-0005Ei-VX for patch@linaro.org; Tue, 21 May 2019 08:29:43 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45336) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SJ-SH for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005GF-2m for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wr1-x443.google.com ([2a00:1450:4864:20::443]:39691) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-00059K-Ik for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wr1-x443.google.com with SMTP id w8so18400434wrl.6 for ; Tue, 21 May 2019 05:25:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hp1runAbdQd7C9+DO77cwqbwEDr2QCIxmTa56UZ3hFs=; b=AhpuxbrHeNU/Dwg2zygsznoUNE1P7EkyIokpH4Mhd+mn7HR0ZpEXfqmaN8pFrVAtMG z5oWJzU24AM6MfUuNqkTyJja6ggTgDQlu0Rc919EBhi6yNI7u2P9LP000mg2bd7cjH7f m6rKf97vDJDv9XY15nDYr8BliQGE3ekUbmDby3yku3H0V0FFmGmLbWkL7rEiDNmbQ73i zdRrufTYQzM6F0HJ5vQlh8wsaPf2G2f4/ZSXKm25wMN1b0seZy6An7XJDYCZVO0PY1Af 3oV9gp/sQJ8T+enW786Okp5EfA6k0Edp2DG3LYUSDeO4upOKDpwtoUHO0Jy4VH5vwsf5 qmyw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hp1runAbdQd7C9+DO77cwqbwEDr2QCIxmTa56UZ3hFs=; b=Dz8LmJhhT5qUCUl7tEz82OFb+NNy86xWJt+k1s8A3wMXiFrZrFCMrR7p3XDmCxGEU9 KpF2QmXRdIq19tZCoHCWvM25l1YUUgzkFX7lZnuYdj9wZpa1QrT1nkYi8fOfk81l7r2G toxintVEYL+8iakqvde+hMoPJTScUDfOUO7E0HNA5V5u2tcvlf8gfM9TRetY7weKmg3F 6D2PYvVJy7mA/emSK88PnzcyvMG5XIYsrKHB6NIbVcmVAqjVPKdrc+vqzc/0/ecNOYNg 0JDATLD6UFXujsn7FW0eVvd1uupmAp2ljQLf5BcWUIC0OjFRcI3KiAJoU7f+WG95XXHm 2JUw== X-Gm-Message-State: APjAAAXOo/TbyPTcpTK0St7mSxO7NoQtfLfGgj6r8N56jgmpAPhHhV+c 2NyFBJK51xNQlz37ZGBjRuobv17AOuE= X-Received: by 2002:adf:ba43:: with SMTP id t3mr43582893wrg.188.1558441533992; Tue, 21 May 2019 05:25:33 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.32 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:33 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:17 +0100 Message-Id: <20190521122519.12573-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::443 Subject: [Qemu-devel] [RFC 08/10] docs: Add kernel-doc API documentation to memory.rst X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" Add the API documentation as generated by kernel-doc to memory.rst. Signed-off-by: Peter Maydell --- Note that this generates errors that break the build, at least with the 1.7.5 version of Sphinx I'm currently using. --- docs/devel/memory.rst | 5 +++++ 1 file changed, 5 insertions(+) -- 2.20.1 diff --git a/docs/devel/memory.rst b/docs/devel/memory.rst index b6a4c37ea5e..68bc6202797 100644 --- a/docs/devel/memory.rst +++ b/docs/devel/memory.rst @@ -361,3 +361,8 @@ callbacks are called: - .impl.unaligned specifies that the *implementation* supports unaligned accesses; if false, unaligned accesses will be emulated by two aligned accesses. + +Detailed API documentation +-------------------------- + +.. kernel-doc:: include/exec/memory.h From patchwork Tue May 21 12:25:18 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164726 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1545853ili; Tue, 21 May 2019 05:34:57 -0700 (PDT) X-Google-Smtp-Source: APXvYqxyTvqVCl88cFhE3pBY20wH8uYiIO6dwOFXhyi3iDLoST8U4zRWbLqTsqFsAyXaevl5M/IR X-Received: by 2002:a50:b557:: with SMTP id z23mr82322137edd.154.1558442096935; Tue, 21 May 2019 05:34:56 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558442096; cv=none; d=google.com; s=arc-20160816; b=TsBUv0IAqSR/MfafwD/VbbXdQsmocSn0o34McOOIb+S/wByys8izdSa1HMJqGUGjEs fmj9lMQi3oKi2kcXyIr0mG1S3R9Z7ykDOCWxZbAi/IhzVJ06gnhL5bCcO2AH4Vd+sgIK 1TbAKQWVEpMHK3xcS5bG2IlLKI1FAMcd1k0uEKCoNo6Jio8Os1cUFhBH3/1k5p1HElss OOPaCeCOSLnSHtUwPzlC+f2uFWKXPHQylet2CGM6ARsP9Itpe4mRe/oxVEDfSq9TfdWs 8iuunEvEshAVK24OGN0OXAfsLCo0wemPN+AqyW8e4UmCO9YnI5fv6R5fIZuDNE5+Odio 9R7g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=/6fZvTwbiNEGi+N3ZL26FN4PNtHy8EurrYMXN2rAFp0=; b=eAoUkIvC13ayUIqWuuaqq3AOYEntmOTqVvj6CySFd3bTe7U6O4fS5hQOSlooUemSHH yqVHN9fAQhTlhgbFQqtSm8iSbJaJoknjQ+1rEVzwfIpV57e/bkDNusVNlv72faHVI5r3 GL+g8/48I0YQDPOzCjGEjj2CZLQdMNYAjASxxoPlbl6L7VHpnzHnTRPceonIEzOIYeOQ Q427kCHWZMP5g6YzEV7bKOsSl1LGIbcmAm+vzVgL9ST/UnJr2xkkufxZZLu3jN4QapW3 8wD7UBZUGLGErEm2jKufFzCVMTa5M0gFO/nctredv+k/x2RbFQ5V6jNt23gBCKPH0m5U iiYg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=UDj+XYvN; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id f3si7714536edv.9.2019.05.21.05.34.56 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:34:56 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=UDj+XYvN; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52780 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3yn-0000K1-3O for patch@linaro.org; Tue, 21 May 2019 08:34:53 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45343) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SM-Sk for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:53 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3pw-0005G1-W8 for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wr1-x442.google.com ([2a00:1450:4864:20::442]:45951) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3pw-0005A4-NC for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:44 -0400 Received: by mail-wr1-x442.google.com with SMTP id b18so18328012wrq.12 for ; Tue, 21 May 2019 05:25:36 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=/6fZvTwbiNEGi+N3ZL26FN4PNtHy8EurrYMXN2rAFp0=; b=UDj+XYvN3CAPWQnMdjGuz4CBG2eXrGv5r1RTbJ5659Pur1V7x/o2dqcIhR9uJmbk/s AcNGLJg0M6HRtF8iD9VgWFR4VBc2t8smBsx2Cen+BHEy4Bef3cy9FaJy3WlO7ARQXNjz QqTuMTW4f115rdGfd9Ln3ddpA1L4mqDoQ0wTJQoUsX18PISmGT643c/9yS5bOK/glGx8 JzB/3kdwz0a1VSPLrdR9THRrwjoQA72s/WhlhVvYCC00giQLn2kqWOa2W4OMpjaNAdg5 w1CyXIqjn1JVNCKWXVCA1cAHwnlp0Nt7SFjCjZZP5N8raTSx17ERl/bur5EH+pDL4V5V uYJA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=/6fZvTwbiNEGi+N3ZL26FN4PNtHy8EurrYMXN2rAFp0=; b=sJOcm66bDn29Z4/dtKL6MLGrdpKLpjt60kJ2xiUhZrc3wBCAqZl8kOGQb1H95S2PRR G06qhOpsDj2U0B2gWpCjiH3jpH34YPzc8fJCDDsLoYe/dcjG+WJArLqgFgZWWU0fI8pr GVSwuPOc8hj2gUpjSeR9wtcE8rVA1/VNjUASNJEK+3YxPEbHS2lREdgsUI412clmVkW3 wBLAMJNbpOPWbBDHk4eHvilT/jfmcVJba6lGsyi70ahsfvdgM7AmTPcPz/O+En8xqUfq BM7ZyJ5whOKLaUOeSUIv05Za26S5lHioult/rr+9NGY+wDNpjXTY7EeD7yd6rRp0XXGI DTpA== X-Gm-Message-State: APjAAAW8dlLOV/AlthysvC2lrspekKKI1Iz2hAJDq6wqUML7YuoRrpyr NMXNW5nVPzcynI5f7uq9GyBBtRsIg+8= X-Received: by 2002:a05:6000:1284:: with SMTP id f4mr38158764wrx.325.1558441535220; Tue, 21 May 2019 05:25:35 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.34 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:34 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:18 +0100 Message-Id: <20190521122519.12573-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::442 Subject: [Qemu-devel] [RFC 09/10] memory.h: attempted kernel-doc fixes X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" kernel-doc needs the "struct" or it complains that it can't parse a function prototype which is actually a struct definition. Note that this then creates a lot of warnings about undocumented struct fields... --- include/exec/memory.h | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) -- 2.20.1 diff --git a/include/exec/memory.h b/include/exec/memory.h index 8447a16ded1..d0f35be1c3b 100644 --- a/include/exec/memory.h +++ b/include/exec/memory.h @@ -208,7 +208,7 @@ enum IOMMUMemoryRegionAttr { }; /** - * IOMMUMemoryRegionClass: + * struct IOMMUMemoryRegionClass: * * All IOMMU implementations need to subclass TYPE_IOMMU_MEMORY_REGION * and provide an implementation of at least the @translate method here @@ -224,8 +224,10 @@ enum IOMMUMemoryRegionAttr { * attributes and the output TLB entry depends on the transaction * attributes, we represent this using IOMMU indexes. Each index * selects a particular translation table that the IOMMU has: - * @attrs_to_index returns the IOMMU index for a set of transaction attributes - * @translate takes an input address and an IOMMU index + * + * - @attrs_to_index returns the IOMMU index for a set of transaction attributes + * - @translate takes an input address and an IOMMU index + * * and the mapping returned can only depend on the input address and the * IOMMU index. * @@ -398,7 +400,7 @@ struct IOMMUMemoryRegion { QLIST_FOREACH((n), &(mr)->iommu_notify, node) /** - * MemoryListener: callbacks structure for updates to the physical memory map + * struct MemoryListener: callbacks structure for updates to the physical memory map * * Allows a component to adjust to changes in the guest-visible memory map. * Use with memory_listener_register() and memory_listener_unregister(). @@ -432,7 +434,7 @@ struct MemoryListener { }; /** - * AddressSpace: describes a mapping of addresses to #MemoryRegion objects + * struct AddressSpace: describes a mapping of addresses to #MemoryRegion objects */ struct AddressSpace { /* All fields are private. */ @@ -472,7 +474,7 @@ static inline FlatView *address_space_to_flatview(AddressSpace *as) /** - * MemoryRegionSection: describes a fragment of a #MemoryRegion + * struct MemoryRegionSection: describes a fragment of a #MemoryRegion * * @mr: the region, or %NULL if empty * @fv: the flat view of the address space the region is mapped in @@ -1653,8 +1655,8 @@ bool memory_region_is_mapped(MemoryRegion *mr); * Returns a #MemoryRegionSection that describes a contiguous overlap. * It will have the following characteristics: * - * .@size = 0 iff no overlap was found - * .@mr is non-%NULL iff an overlap was found + * - .@size = 0 iff no overlap was found + * - .@mr is non-%NULL iff an overlap was found * * Remember that in the return value the @offset_within_region is * relative to the returned region (in the .@mr field), not to the @@ -1666,8 +1668,8 @@ bool memory_region_is_mapped(MemoryRegion *mr); * has no container (and thus is the root of the address space), the * following will hold: * - * .@offset_within_address_space >= @addr - * .@offset_within_address_space + .@size <= @addr + @size + * - .@offset_within_address_space >= @addr + * - .@offset_within_address_space + .@size <= @addr + @size * * @mr: a MemoryRegion within which @addr is a relative address * @addr: start of the area within @as to be searched From patchwork Tue May 21 12:25:19 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 164723 Delivered-To: patch@linaro.org Received: by 2002:a92:9e1a:0:0:0:0:0 with SMTP id q26csp1543121ili; Tue, 21 May 2019 05:32:31 -0700 (PDT) X-Google-Smtp-Source: APXvYqw6yNxJJCzhr/6aGTMjODnfSAKUUCZm4AG5b8+ILCuPt62WkE/LNo3xDpuI72zehsX77OTl X-Received: by 2002:a50:f9cc:: with SMTP id a12mr82788499edq.272.1558441951199; Tue, 21 May 2019 05:32:31 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558441951; cv=none; d=google.com; s=arc-20160816; b=vDey7CZ2dpkCzPKmPVTf8Lp5M7OUr8CA3Zd/uj9snt0M5eSiadvRcU/zy6Bl0GGaN+ Z2VU2vJWrD1gzO6v+3ckNAwYJhGO7EoHDZNY/HwK73LBf8Brvps5g0UuU711W+1GGCHt KVAweGhcKZhWI31m65idJ+CQS5xh4Pjp1sBvTKQbQSCBdgQSAmhQ2/UHZ6xWqA2iXt2J wNs16Kauz+gPqvvtyuQJ2qt3c9bGOI3Pfe02Be+3TYJOdI3Xyc6pOZurKxue2ldcGQnM MZJY/77EzkOVGAHeC1Q76Je33iKa2gQDY9P9F/vqrxEyEL8q7lFEZ0BlI4pIQx2exxWP PTBA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=tvS0J2CCwmAI9jtVGUfQ7GO5klgsA9PYzQhj1JC24zc=; b=tcFqVDNOgiTrYJGhxC43dQ/gEsD0cWGnUVwW4oFxE6uW0B6jr88PffhHTWMfTuyHOk ZdZHC1LrQ9lkruDIneJPJSVe+aP7d0mN/Pg+3tvWkdXW/PxgtORtmK24suUlYDwitOI0 eMc+4K1ce6DDQnBA00mmVfYS4uhxC87baaPTVjS2nDN3WKGMBu2ZPmWHXns6U0G8KDdN SvZNTfxwM5p/OvSZ0/wvZAeTqIyN7JWUaGFDX/hTN0UYsJxcwrxnS/IMY5Hy+ZX++fLR dspRAXVnjwo8ItF9pehHHYpxsJ7p6idgLasTFNrpnnu42iaa2U1pLDn8Ig9PRu8qE0mW zwsQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=X+NOGgcj; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id l7si15389778eda.21.2019.05.21.05.32.30 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 21 May 2019 05:32:31 -0700 (PDT) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b=X+NOGgcj; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:52763 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3wU-0007Dr-2T for patch@linaro.org; Tue, 21 May 2019 08:32:30 -0400 Received: from eggs.gnu.org ([209.51.188.92]:45337) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hT3q2-0001SK-S6 for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:52 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hT3px-0005Gy-FE for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:48 -0400 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:46306) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1hT3px-0005B2-6a for qemu-devel@nongnu.org; Tue, 21 May 2019 08:25:45 -0400 Received: by mail-wr1-x429.google.com with SMTP id r7so18343869wrr.13 for ; Tue, 21 May 2019 05:25:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=tvS0J2CCwmAI9jtVGUfQ7GO5klgsA9PYzQhj1JC24zc=; b=X+NOGgcjaXldgBS/tExqO4E64kbpEgbQAvgU9otTba+JyKhxqxB4dLmshB1r0Auxw4 PryiKx9CzgQKF6CzfjDu+oVq2xNltjxH5geoKY2/Kem/EtnvpWD6qY4AVgdRcZRcLvHu J2uL1ofVtN+cJZRed+HBolGal9Fe/+Qsao3T1+PHewwoaOpIAiLY76XS5frjOvQWYG+i Gb0SfcNcTLyzfpysxQjd+XTCR+dTiA7Yz1jYq7VUAUpWVn92rpG34naxisEvsSQqWTZi uKzreecXSnfme+hleSj5P2roFD83GJ21FiW8gwREmsFUK8pBcBxp8tYYvJMom3SGdSXZ xLrQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=tvS0J2CCwmAI9jtVGUfQ7GO5klgsA9PYzQhj1JC24zc=; b=czXhYVpNeIPat5MbvXQm/psoynpFZjpofV+1c2WHkRkI5Njwii9vp317XEweSQ9aB2 u2PDaKa9PdgIJIqO0W0s8z4a150wnfwHQFGSDFHanYXR+f2v8aQnoRJgHe4PT1JMpaBu Yh5Aw7daTCaFq1uRUV/j3En0MI1Lm/B+YmEINaVQfh7OyB2ZoxrD2YbFBFEqdrwL6bmC uranViGVtTsaUxFaMGmH4QVIFNyIri4OIfxN29t924xC12o10wZT29cICbPIdizwafzY iYfXtKq7vAkb8RQbOejncLXyyvLloGHt0ZZKi81RGM0HPA3eIqVtCb+kvnXhbkxK/3FE DKoA== X-Gm-Message-State: APjAAAV0J48WpD6lWv+2f7eGpguCTQZgSD1KVhHUPESkT+q1ffot2hoF wqPE3r85ymR89XUGm1YscYH1dSkBw5Q= X-Received: by 2002:adf:8bc5:: with SMTP id w5mr7235335wra.132.1558441536416; Tue, 21 May 2019 05:25:36 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id u11sm12233393wrn.1.2019.05.21.05.25.35 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 21 May 2019 05:25:35 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 21 May 2019 13:25:19 +0100 Message-Id: <20190521122519.12573-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190521122519.12573-1-peter.maydell@linaro.org> References: <20190521122519.12573-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::429 Subject: [Qemu-devel] [RFC 10/10] Makefile: disable Sphinx nitpicking X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: "Daniel P. Berrange" , Eduardo Habkost , Gabriel Barreto , "Emilio G. Cota" , Stefan Hajnoczi , Cleber Rosa , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" Turn off Sphinx nitpicking as a temporary measure so sphinx builds complete even with warnings about missing references. Signed-off-by: Peter Maydell --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) -- 2.20.1 diff --git a/Makefile b/Makefile index 155f066a206..b4be96ce9a6 100644 --- a/Makefile +++ b/Makefile @@ -932,7 +932,7 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html # Canned command to build a single manual -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py