scripts/kernel-doc: optionally treat warnings as errors

The kbuild bot recently added the W=1 option, which triggered
documentation cleanups to squelch hundreds of kernel-doc warnings.

To make sure

scripts/kernel-doc: optionally treat warnings as errors

The kbuild bot recently added the W=1 option, which triggered
documentation cleanups to squelch hundreds of kernel-doc warnings.

To make sure new kernel contributions don't add regressions to
kernel-doc descriptors, this patch suggests an option to treat
warnings as errors in CI/automated tests.

A -Werror command-line option is added to the kernel-doc script. When
this option is set, the script will return the number of warnings
found. The caller can then treat this positive return value as an
error and stop the build.

Using this command line option is however not straightforward when the
kernel-doc script is called from other scripts. To align with typical
kernel compilation or documentation generation, the Werror option is
also set by checking the KCFLAGS environment variable, or if
KDOC_WERROR is defined, as in the following examples:

KCFLAGS="-Wall -Werror" make W=1 sound/
KCFLAGS="-Wall -Werror" make W=1 drivers/soundwire/
KDOC_WERROR=1 make htmldocs

Note that in the last example the documentation build does not stop,
only an additional log is provided.

Credits to Randy Dunlap for suggesting the use of environment variables.

Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Pierre-Louis Bossart <pierre-louis.bossart@linux.intel.com>
Link: https://lore.kernel.org/r/20200728162040.92467-1-pierre-louis.bossart@linux.intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-11-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

scripts/kernel-doc: handle function pointer prototypes

There are some function pointer prototypes inside the net
includes, like this one:

int (*pcs_config)(struct phylink_config *config, unsigned

scripts/kernel-doc: handle function pointer prototypes

There are some function pointer prototypes inside the net
includes, like this one:

int (*pcs_config)(struct phylink_config *config, unsigned int mode,
phy_interface_t interface, const unsigned long *advertising);

There's nothing wrong using it with kernel-doc, but we need to
add a rule for it to parse such kind of prototype.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/fec520dd731a273013ae06b7653a19c7d15b9562.1592895969.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-10-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK

The __ETHTOOL_DECLARE_LINK_MODE_MASK macro is a variant of
DECLARE_BITMAP(), used by phylink.h. As we have already a
parser for DECLARE_BIT

scripts/kernel-doc: parse __ETHTOOL_DECLARE_LINK_MODE_MASK

The __ETHTOOL_DECLARE_LINK_MODE_MASK macro is a variant of
DECLARE_BITMAP(), used by phylink.h. As we have already a
parser for DECLARE_BITMAP(), let's add one for this macro,
in order to avoid such warnings:

./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(advertising' not described in 'phylink_link_state'
./include/linux/phylink.h:54: warning: Function parameter or member '__ETHTOOL_DECLARE_LINK_MODE_MASK(lp_advertising' not described in 'phylink_link_state'

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d1d1dea67a28117c0b0c33271b139c4455fef287.1592895969.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-9-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

Replace HTTP links with HTTPS ones: documentation

Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic algorithm:

Replace HTTP links with HTTPS ones: documentation

Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.

Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.

Signed-off-by: Alexander A. Klimov <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-8-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

scripts: kernel-doc: accept blank lines on parameter description

Sphinx is very pedantic with respect to blank lines. Sometimes,
in order to make it to properly handle something, we need to
add a bl

scripts: kernel-doc: accept blank lines on parameter description

Sphinx is very pedantic with respect to blank lines. Sometimes,
in order to make it to properly handle something, we need to
add a blank line. However, currently, any blank line inside a
kernel-doc comment like:

/*
* @foo: bar
*
* foobar
*
* some description

will be considered as if "foobar" was part of the description.

This patch changes kernel-doc behavior. After it, foobar will
be considered as part of the parameter text. The description
will only be considered as such if it starts with:

zero spaces after asterisk:

*foo

one space after asterisk:
* foo

or have a explicit Description section:

* Description:

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-7-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

scripts: kernel-doc: accept negation like !@var

On a few places, it sometimes need to indicate a negation of a
parameter, like:

!@fshared

This pattern happens, for example, at:

kernel/futex.c

scripts: kernel-doc: accept negation like !@var

On a few places, it sometimes need to indicate a negation of a
parameter, like:

!@fshared

This pattern happens, for example, at:

kernel/futex.c

and it is perfectly valid. However, kernel-doc currently
transforms it into:

!**fshared**

This won't do what it would be expected.

Fortunately, fixing the script is a simple matter of storing
the "!" before "@" and adding it after the bold markup, like:

**!fshared**

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-6-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

scripts: kernel-doc: proper handle @foo->bar()

The pattern @foo->bar() is valid, as it can be used by a
function pointer inside a struct passed as a parameter.

Right now, it causes a warning:

./d

scripts: kernel-doc: proper handle @foo->bar()

The pattern @foo->bar() is valid, as it can be used by a
function pointer inside a struct passed as a parameter.

Right now, it causes a warning:

./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string.

In this specific case, the kernel-doc markup is:

/**
* fw_core_remove_address_handler() - unregister an address handler
* @handler: callback
*
* To be called in process context.
*
* When fw_core_remove_address_handler() returns, @handler->callback() is
* guaranteed to not run on any CPU anymore.
*/

With seems valid on my eyes. So, instead of trying to hack
the kernel-doc markup, let's teach it about how to handle
such things. This should likely remove lots of other similar
warnings as well.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-5-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

scripts/kernel-doc: Add support for named variable macro arguments

Currently, when kernel-doc encounters a macro with a named variable
argument[1], such as this:

#define hlist_for_each_entry_rcu

scripts/kernel-doc: Add support for named variable macro arguments

Currently, when kernel-doc encounters a macro with a named variable
argument[1], such as this:

#define hlist_for_each_entry_rcu(pos, head, member, cond...)

... it expects the variable argument to be documented as `cond...`,
rather than `cond`. This is semantically wrong, because the name (as
used in the macro body) is actually `cond`.

With this patch, kernel-doc will accept the name without dots (`cond`
in the example above) in doc comments, and warn if the name with dots
(`cond...`) is used and verbose mode[2] is enabled.

The support for the `cond...` syntax can be removed later, when the
documentation of all such macros has been switched to the new syntax.

Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few
changes in log output and HTML output:

1) The following warnings[3] are eliminated:

./include/linux/rculist.h:374: warning:
Excess function parameter 'cond' description in 'list_for_each_entry_rcu'
./include/linux/rculist.h:651: warning:
Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu'

2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the
correct description is shown

3) Named variable arguments are shown without dots

[1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html
[2]: scripts/kernel-doc -v
[3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3c

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Tested-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-4-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

kernel-doc: add support for ____cacheline_aligned_in_smp attribute

Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it

kernel-doc: add support for ____cacheline_aligned_in_smp attribute

Subroutine dump_struct uses type attributes to check if the struct
syntax is valid. Then, it removes all attributes before using it for
output. `____cacheline_aligned_in_smp` is an attribute that is
not included in both steps. Add it, since it is used by kernel structs.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-3-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

kernel-doc: fix processing nested structs with attributes

The current regular expression for strip attributes of structs (and
for nested ones as well) also removes all whitespaces that may
surround

kernel-doc: fix processing nested structs with attributes

The current regular expression for strip attributes of structs (and
for nested ones as well) also removes all whitespaces that may
surround the attribute. After that, the code will split structs and
iterate for each symbol separated by comma at the end of struct
definition (e.g. "} alias1, alias2;"). However, if the nested struct
does not have any alias and has an attribute, it will result in a
empty string at the closing bracket (e.g "};"). This will make the
split return nothing and $newmember will keep uninitialized. Fix
that, by ensuring that the attribute substitution will leave at least
one whitespace.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-2-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20201102' into staging

target-arm queue:
* target/arm: Fix Neon emulation bugs on big-endian hosts
* target/arm: fix handling of

Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20201102' into staging

target-arm queue:
* target/arm: Fix Neon emulation bugs on big-endian hosts
* target/arm: fix handling of HCR.FB
* target/arm: fix LORID_EL1 access check
* disas/capstone: Fix monitor disassembly of >32 bytes
* hw/arm/smmuv3: Fix potential integer overflow (CID 1432363)
* hw/arm/boot: fix SVE for EL3 direct kernel boot
* hw/display/omap_lcdc: Fix potential NULL pointer dereference
* hw/display/exynos4210_fimd: Fix potential NULL pointer dereference
* target/arm: Get correct MMU index for other-security-state
* configure: Test that gio libs from pkg-config work
* hw/intc/arm_gicv3_cpuif: Make GIC maintenance interrupts work
* docs: Fix building with Sphinx 3
* tests/qtest/npcm7xx_rng-test: Disable randomness tests

# gpg: Signature made Mon 02 Nov 2020 17:09:00 GMT
# gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg: issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-target-arm-20201102: (26 commits)
tests/qtest/npcm7xx_rng-test: Disable randomness tests
qemu-option-trace.rst.inc: Don't use option:: markup
scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments
hw/intc/arm_gicv3_cpuif: Make GIC maintenance interrupts work
configure: Test that gio libs from pkg-config work
target/arm: Get correct MMU index for other-security-state
hw/display/exynos4210_fimd: Fix potential NULL pointer dereference
hw/display/omap_lcdc: Fix potential NULL pointer dereference
hw/arm/boot: fix SVE for EL3 direct kernel boot
hw/arm/smmuv3: Fix potential integer overflow (CID 1432363)
disas/capstone: Fix monitor disassembly of >32 bytes
target/arm: fix LORID_EL1 access check
target/arm: fix handling of HCR.FB
target/arm: Fix VUDOT/VSDOT (scalar) on big-endian hosts
target/arm: Fix float16 pairwise Neon ops on big-endian hosts
target/arm: Improve do_prewiden_3d
target/arm: Simplify do_long_3d and do_2scalar_long
target/arm: Rename neon_load_reg64 to vfp_load_reg64
target/arm: Add read/write_neon_element64
target/arm: Rename neon_load_reg32 to vfp_load_reg32
...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments

The kerneldoc script currently emits Sphinx markup for a macro with
arguments that uses the c:function directive. This is correc

scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments

The kerneldoc script currently emits Sphinx markup for a macro with
arguments that uses the c:function directive. This is correct for
Sphinx versions earlier than Sphinx 3, where c:macro doesn't allow
documentation of macros with arguments and c:function is not picky
about the syntax of what it is passed. However, in Sphinx 3 the
c:macro directive was enhanced to support macros with arguments,
and c:function was made more picky about what syntax it accepted.

When kerneldoc is told that it needs to produce output for Sphinx
3 or later, make it emit c:function only for functions and c:macro
for macros with arguments. We assume that anything with a return
type is a function and anything without is a macro.

This fixes the Sphinx error:

/home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/qom/object.h:155:Error in declarator
If declarator-id with parameters (e.g., 'void f(int arg)'):
Invalid C declaration: Expected identifier in nested name. [error at 25]
DECLARE_INSTANCE_CHECKER ( InstanceType, OBJ_NAME, TYPENAME)
-------------------------^
If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'):
Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 39]
DECLARE_INSTANCE_CHECKER ( InstanceType, OBJ_NAME, TYPENAME)
---------------------------------------^

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Tested-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-id: 20201030174700.7204-2-peter.maydell@linaro.org

show more ...

Merge remote-tracking branch 'remotes/ehabkost/tags/machine-next-pull-request' into staging

machine + QOM queue, 2020-10-06

* QOM documentation fixes and cleanups (Eduardo Habkost)
* user-mode: Pru

Merge remote-tracking branch 'remotes/ehabkost/tags/machine-next-pull-request' into staging

machine + QOM queue, 2020-10-06

* QOM documentation fixes and cleanups (Eduardo Habkost)
* user-mode: Prune build dependencies (Philippe Mathieu-Daudé)
* qom: Improve error message (Philippe Mathieu-Daudé)
* numa: hmat: require parent cache description before the next
level one (Igor Mammedov)

# gpg: Signature made Tue 06 Oct 2020 23:09:03 BST
# gpg: using RSA key 5A322FD5ABC4D3DBACCFD1AA2807936F984DC5A6
# gpg: issuer "ehabkost@redhat.com"
# gpg: Good signature from "Eduardo Habkost <ehabkost@redhat.com>" [full]
# Primary key fingerprint: 5A32 2FD5 ABC4 D3DB ACCF D1AA 2807 936F 984D C5A6

* remotes/ehabkost/tags/machine-next-pull-request: (21 commits)
numa: hmat: require parent cache description before the next level one
kernel-doc: Remove $decl_type='type name' hack
memory: Explicitly tag doc comments for structs
qom: Explicitly tag doc comments for typedefs and structs
kernel-doc: Handle function typedefs without asterisks
kernel-doc: Handle function typedefs that return pointers
docs/devel/qom: Avoid long lines
docs/devel/qom: Remove usage of <code>
docs/devel/qom: Use *emphasis* for emphasis
docs/devel/qom: Fix indentation of code blocks
docs/devel/qom: Fix indentation of bulleted list
qom: Fix DECLARE_*CHECKER documentation
qom: Improve error message displayed with missing object properties
hw/core/cpu: Add missing 'exec/cpu-common.h' include
hw/core/qdev-properties: Extract system-mode specific properties
hw/core/qdev-properties: Export some integer-related functions
hw/core/qdev-properties: Export qdev_prop_enum
hw/core/qdev-properties: Export enum-related functions
hw/core/qdev-properties: Fix code style
hw/core/qdev-properties: Use qemu_strtoul() in set_pci_host_devaddr()
...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

kernel-doc: Remove $decl_type='type name' hack

The $decl_type='type name' hack makes it impossible to document
macros with uppercase names (e.g. most of the macros in
object.h).

Now that we have ex

kernel-doc: Remove $decl_type='type name' hack

The $decl_type='type name' hack makes it impossible to document
macros with uppercase names (e.g. most of the macros in
object.h).

Now that we have explicitly tagged the struct and typedef doc
comments in memory.h and object.h, we don't need that hack
anymore. This will make the documentation for the macros in
object.h finally be rendered as expected.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003024123.193840-6-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>

show more ...

kernel-doc: Handle function typedefs without asterisks

Example of typedef that was not parsed by kernel-doc:

typedef void (ObjectUnparent)(Object *obj);

Signed-off-by: Eduardo Habkost <ehabkost@

kernel-doc: Handle function typedefs without asterisks

Example of typedef that was not parsed by kernel-doc:

typedef void (ObjectUnparent)(Object *obj);

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003024123.193840-3-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>

show more ...

kernel-doc: Handle function typedefs that return pointers

One example that was not being parsed correctly by kernel-doc is:

typedef Object *(ObjectPropertyResolve)(Object *obj,

kernel-doc: Handle function typedefs that return pointers

One example that was not being parsed correctly by kernel-doc is:

typedef Object *(ObjectPropertyResolve)(Object *obj,
void *opaque,
const char *part);

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003024123.193840-2-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/stefanha/tags/block-pull-request' into staging

Pull request

This includes the atomic_ -> qatomic_ rename that touches many files and is
prone to conflicts.

#

Merge remote-tracking branch 'remotes/stefanha/tags/block-pull-request' into staging

Pull request

This includes the atomic_ -> qatomic_ rename that touches many files and is
prone to conflicts.

# gpg: Signature made Wed 23 Sep 2020 17:08:43 BST
# gpg: using RSA key 8695A8BFD3F97CDAAC35775A9CA4ABB381AB73C8
# gpg: Good signature from "Stefan Hajnoczi <stefanha@redhat.com>" [full]
# gpg: aka "Stefan Hajnoczi <stefanha@gmail.com>" [full]
# Primary key fingerprint: 8695 A8BF D3F9 7CDA AC35 775A 9CA4 ABB3 81AB 73C8

* remotes/stefanha/tags/block-pull-request:
qemu/atomic.h: rename atomic_ to qatomic_
tests: add test-fdmon-epoll
fdmon-poll: reset npfd when upgrading to fdmon-epoll
gitmodules: add qemu.org vbootrom submodule
gitmodules: switch to qemu.org meson mirror
gitmodules: switch to qemu.org qboot mirror
docs/system: clarify deprecation schedule
virtio-crypto: don't modify elem->in/out_sg
virtio-blk: undo destructive iov_discard_*() operations
util/iov: add iov_discard_undo()
virtio: add vhost-user-fs-ccw device
libvhost-user: handle endianness as mandated by the spec
MAINTAINERS: add Stefan Hajnoczi as block/nvme.c maintainer

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

qemu/atomic.h: rename atomic_ to qatomic_

clang's C11 atomic_fetch_*() functions only take a C11 atomic type
pointer argument. QEMU uses direct types (int, etc) and this causes a
compiler error when

qemu/atomic.h: rename atomic_ to qatomic_

clang's C11 atomic_fetch_*() functions only take a C11 atomic type
pointer argument. QEMU uses direct types (int, etc) and this causes a
compiler error when a QEMU code calls these functions in a source file
that also included <stdatomic.h> via a system header file:

$ CC=clang CXX=clang++ ./configure ... && make
../util/async.c:79:17: error: address argument to atomic operation must be a pointer to _Atomic type ('unsigned int *' invalid)

Avoid using atomic_*() names in QEMU's atomic.h since that namespace is
used by <stdatomic.h>. Prefix QEMU's APIs with 'q' so that atomic.h
and <stdatomic.h> can co-exist. I checked /usr/include on my machine and
searched GitHub for existing "qatomic_" users but there seem to be none.

This patch was generated using:

$ git grep -h -o '\<atomic\(64\)\?_[a-z0-9_]\+' include/qemu/atomic.h | \
sort -u >/tmp/changed_identifiers
$ for identifier in $(</tmp/changed_identifiers); do
sed -i "s%\<$identifier\>%q$identifier%g" \
$(git grep -I -l "\<$identifier\>")
done

I manually fixed line-wrap issues and misaligned rST tables.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Acked-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20200923105646.47864-1-stefanha@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20200414' into staging

patch queue:
* Fix some problems that trip up Coverity's scanner
* run-coverity-scan: New script automati

Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20200414' into staging

patch queue:
* Fix some problems that trip up Coverity's scanner
* run-coverity-scan: New script automating the scan-and-upload process
* docs: Improve our gdbstub documentation
* configure: Honour --disable-werror for Sphinx
* docs: Fix errors produced when building with Sphinx 3.0
* docs: Require Sphinx 1.6 or better
* Add deprecation notice for KVM support on AArch32 hosts

# gpg: Signature made Tue 14 Apr 2020 17:25:22 BST
# gpg: using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg: issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg: aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83 15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-target-arm-20200414:
Deprecate KVM support for AArch32
docs: Require Sphinx 1.6 or better
kernel-doc: Use c:struct for Sphinx 3.0 and later
scripts/kernel-doc: Add missing close-paren in c:function directives
configure: Honour --disable-werror for Sphinx
docs: Improve our gdbstub documentation
scripts/coverity-scan: Add Docker support
scripts/run-coverity-scan: Script to run Coverity Scan build
linux-user/flatload.c: Use "" for include of QEMU header target_flat.h
thread.h: Remove trailing semicolons from Coverity qemu_mutex_lock() etc
thread.h: Fix Coverity version of qemu_cond_timedwait()
osdep.h: Drop no-longer-needed Coverity workarounds

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

kernel-doc: Use c:struct for Sphinx 3.0 and later

The kernel-doc Sphinx plugin and associated script currently emit
'c:type' directives for "struct foo" documentation.

Sphinx 3.0 warns about this:

kernel-doc: Use c:struct for Sphinx 3.0 and later

The kernel-doc Sphinx plugin and associated script currently emit
'c:type' directives for "struct foo" documentation.

Sphinx 3.0 warns about this:
/home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:3: WARNING: Type must be either just a name or a typedef-like declaration.
If just a name:
Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6]
struct MemoryListener
------^
If typedef-like declaration:
Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 21]
struct MemoryListener
---------------------^

because it wants us to use the new-in-3.0 'c:struct' instead.

Plumb the Sphinx version through to the kernel-doc script
and use it to select 'c:struct' for newer versions than 3.0.

Fixes: LP:1872113
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

show more ...

scripts/kernel-doc: Add missing close-paren in c:function directives

When kernel-doc generates a 'c:function' directive for a function
one of whose arguments is a function pointer, it fails to print

scripts/kernel-doc: Add missing close-paren in c:function directives

When kernel-doc generates a 'c:function' directive for a function
one of whose arguments is a function pointer, it fails to print
the close-paren after the argument list of the function pointer
argument, for instance in the memory API documentation:
.. c:function:: void memory_region_init_resizeable_ram (MemoryRegion * mr, struct Object * owner, const char * name, uint64_t size, uint64_t max_size, void (*resized) (const char*, uint64_t length, void *host, Error ** errp)

which should have a ')' after the 'void *host' which is the
last argument to 'resized'.

Older versions of Sphinx don't try to parse the argumnet
to c:function, but Sphinx 3.0 does do this and will complain:

/home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:834: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "," or ")" in parameters, got "EOF". [error at 208]
void memory_region_init_resizeable_ram (MemoryRegion * mr, struct Object * owner, const char * name, uint64_t size, uint64_t max_size, void (*resized) (const char*, uint64_t length, void *host, Error ** errp)
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------^

Add the missing close-paren.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200411182934.28678-3-peter.maydell@linaro.org
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

show more ...

Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

* More uses of RCU_READ_LOCK_GUARD (Dave, myself)
* QOM doc improvments (Greg)
* Cleanups from the Meson conversion (Mar

Merge remote-tracking branch 'remotes/bonzini/tags/for-upstream' into staging

* More uses of RCU_READ_LOCK_GUARD (Dave, myself)
* QOM doc improvments (Greg)
* Cleanups from the Meson conversion (Marc-André)
* Support for multiple -accel options (myself)
* Many x86 machine cleanup (Philippe, myself)
* tests/migration-test cleanup (Juan)
* PC machine removal and next round of deprecation (Thomas)
* kernel-doc integration (Peter, myself)

# gpg: Signature made Wed 18 Dec 2019 01:35:02 GMT
# gpg: using RSA key BFFBD25F78C7AE83
# gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" [full]
# gpg: aka "Paolo Bonzini <pbonzini@redhat.com>" [full]
# Primary key fingerprint: 46F5 9FBD 57D6 12E7 BFD4 E2F7 7E15 100C CD36 69B1
# Subkey fingerprint: F133 3857 4B66 2389 866C 7682 BFFB D25F 78C7 AE83

* remotes/bonzini/tags/for-upstream: (87 commits)
vga: cleanup mapping of VRAM for non-PCI VGA
hw/display: Remove "rombar" hack from vga-pci and vmware_vga
hw/pci: Remove the "command_serr_enable" property
hw/audio: Remove the "use_broken_id" hack from the AC97 device
hw/i386: Remove the deprecated machines 0.12 up to 0.15
hw/pci-host: Add Kconfig entry to select the IGD Passthrough Host Bridge
hw/pci-host/i440fx: Extract the IGD passthrough host bridge device
hw/pci-host/i440fx: Use definitions instead of magic values
hw/pci-host/i440fx: Use size_t to iterate over ARRAY_SIZE()
hw/pci-host/i440fx: Extract PCII440FXState to "hw/pci-host/i440fx.h"
hw/pci-host/i440fx: Correct the header description
Fix some comment spelling errors.
target/i386: remove unused pci-assign codes
WHPX: refactor load library
migration: check length directly to make sure the range is aligned
memory: include MemoryListener documentation and some missing function parameters
docs: add memory API reference
memory.h: Silence kernel-doc complaints
docs: Create bitops.rst as example of kernel-docs
bitops.h: Silence kernel-doc complaints
...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

show more ...

docs: tweak kernel-doc for QEMU coding standards

Surprisingly, QEMU does have a pretty consistent doc comment style and
it is not very different from the Linux kernel's. Of the documentation
"sigil

docs: tweak kernel-doc for QEMU coding standards

Surprisingly, QEMU does have a pretty consistent doc comment style and
it is not very different from the Linux kernel's. Of the documentation
"sigils", only "#" separates the QEMU doc comment style from Linux's,
and it has 200+ instances vs. 6 for the kernel's '&struct foo' (all in
accel/tcg/translate-all.c), so it's clear that the two standards are
different in this respect. In addition, our structs are typedefed and
recognized by CamelCase names.

Adjust kernel-doc's parser for these two aspects of the QEMU coding
standards. The patch has been valid, with hardly any change, for over
two years, so it should not be an issue to keep kernel-doc in sync with
the Linux copy.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

docs: import Linux kernel-doc script and extension

Import Linux's kernel-doc script as of commit 15e2544ed38a1e, as well
as the Sphinx extension to call kernel-doc according to the arguments
and par

docs: import Linux kernel-doc script and extension

Import Linux's kernel-doc script as of commit 15e2544ed38a1e, as well
as the Sphinx extension to call kernel-doc according to the arguments
and parameters given to a reStructuredText directive.

The kernel-doc extension accepts a filename, which is relative to
the QEMU source tree root. The extension also notifies Sphinx about the
document dependency on the file, causing the document to be rebuilt when
the file has been changed.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...