Commit Graph

278 Commits

Author SHA1 Message Date
Alexander Bulekov
f3a0208f24 docs/fuzz: rST-ify the fuzzing documentation
Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20201106180600.360110-2-alxndr@bu.edu>
Signed-off-by: Thomas Huth <thuth@redhat.com>
2020-11-10 08:51:29 +01:00
Markus Armbruster
c4cdf54cff docs/devel/qapi-code-gen: Fix up examples
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20201027121026.3025930-1-armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2020-11-09 09:07:59 +01:00
Paolo Bonzini
2eba427eb1 docs: expand sourceset documentation
Expand on the usage of sourcesets and describe the CONFIG_ALL
symbol.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-11-03 09:42:52 -05:00
Philippe Mathieu-Daudé
4c9ac67230 docs/devel/testing.rst: Update outdated Avocado URLs
Avocado documentation referred returns 404 error.
Update the broken links.

Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Cleber Rosa <crosa@redhat.com>
Message-Id: <20201010080741.2932406-1-philmd@redhat.com>
2020-10-26 18:20:51 +01:00
Alexander Bulekov
2f2e036ca6 fuzz: Add instructions for using generic-fuzz
Reviewed-by: Darren Kenny <darren.kenny@oracle.com>
Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20201023150746.107063-13-alxndr@bu.edu>
Signed-off-by: Thomas Huth <thuth@redhat.com>
2020-10-26 09:53:53 +01:00
Emanuele Giuseppe Esposito
a0c0c9f8b4 loads-stores.rst: add footnote that clarifies GETPC usage
Current documentation is not too clear on the GETPC usage.
In particular, when used outside the top level helper function
it causes unexpected behavior.

Signed-off-by: Emanuele Giuseppe Esposito <e.emanuelegiuseppe@gmail.com>
Message-id: 20201015095147.1691-1-e.emanuelegiuseppe@gmail.com
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-10-20 16:12:00 +01:00
Paolo Bonzini
09e93326e4 build: replace ninjatool with ninja
Now that the build is done entirely by Meson, there is no need
to keep the Makefile conversion.  Instead, we can ask Ninja about
the targets it exposes and forward them.

The main advantages are, from smallest to largest:

- reducing the possible namespace pollution within the Makefile

- removal of a relatively large Python program

- faster build because parsing Makefile.ninja is slower than
parsing build.ninja; and faster build after Meson runs because
we do not have to generate Makefile.ninja.

- tracking of command lines, which provides more accurate rebuilds

In addition the change removes the requirement for GNU make 3.82, which
was annoying on Mac, and avoids bugs on Windows due to ninjatool not
knowing how to convert Windows escapes to POSIX escapes.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-17 10:45:51 -04:00
Paolo Bonzini
bab88ead6f docs/devel: update instruction on how to add new unit tests
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-12 11:50:23 -04:00
Eduardo Habkost
51c778edd3 docs/devel/qtest: Include libqtest API reference
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Acked-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20201005205228.697463-4-ehabkost@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-12 11:50:23 -04:00
Eduardo Habkost
f59c6de7f0 docs/devel/qtest: Include protocol spec in document
Include the QTest Protocol doc string in docs/devel/qtest.rst,
after converting it to use Sphinx syntax.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Acked-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20201005205228.697463-3-ehabkost@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-12 11:50:22 -04:00
Eduardo Habkost
a738a50e62 docs: Move QTest documentation to its own document
The qtest and libqtest doc comments will be parsed to generate
API documentation, so move QTest documentation to its own
document where the API and format documentation and will be
included.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Acked-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20201005205228.697463-2-ehabkost@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-12 11:50:22 -04:00
John Snow
1ec43ca42e docs: repair broken references
In two different places, we are not making a cross-reference to some
resource correctly.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-Id: <20201009161558.107041-2-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-10-10 11:37:46 +02:00
Kevin Wolf
bb4b9ead95 hmp: Add support for coroutine command handlers
Often, QMP command handlers are not only called to handle QMP commands,
but also from a corresponding HMP command handler. In order to give them
a consistent environment, optionally run HMP command handlers in a
coroutine, too.

The implementation is a lot simpler than in QMP because for HMP, we
still block the VM while the coroutine is running.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Message-Id: <20201005155855.256490-11-kwolf@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-10-09 07:08:20 +02:00
Kevin Wolf
04f22362f1 qapi: Add a 'coroutine' flag for commands
This patch adds a new 'coroutine' flag to QMP command definitions that
tells the QMP dispatcher that the command handler is safe to be run in a
coroutine.

The documentation of the new flag pretends that this flag is already
used as intended, which it isn't yet after this patch. We'll implement
this in another patch in this series.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Message-Id: <20201005155855.256490-9-kwolf@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-10-09 07:08:19 +02:00
Eduardo Habkost
38a0d5bcde docs/devel/qom: Avoid long lines
Long code lines don't look good in the rendered documents, make
them shorter.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003025424.199291-7-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2020-10-06 11:09:35 -04:00
Eduardo Habkost
acc34c2144 docs/devel/qom: Use *emphasis* for emphasis
<emphasis> is not valid reST syntax.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003025424.199291-5-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2020-10-06 11:09:35 -04:00
Eduardo Habkost
671b3db056 docs/devel/qom: Fix indentation of code blocks
Some code blocks had one extra space, fix that.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003025424.199291-4-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2020-10-06 11:09:35 -04:00
Eduardo Habkost
258c732769 docs/devel/qom: Fix indentation of bulleted list
The list was incorrectly parsed as a literal block due to
indentation.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201003025424.199291-3-ehabkost@redhat.com>
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2020-10-06 11:09:35 -04:00
Vladimir Sementsov-Ogievskiy
aaaa20b69b scripts: add block-coroutine-wrapper.py
We have a very frequent pattern of creating a coroutine from a function
with several arguments:

  - create a structure to pack parameters
  - create _entry function to call original function taking parameters
    from struct
  - do different magic to handle completion: set ret to NOT_DONE or
    EINPROGRESS or use separate bool field
  - fill the struct and create coroutine from _entry function with this
    struct as a parameter
  - do coroutine enter and BDRV_POLL_WHILE loop

Let's reduce code duplication by generating coroutine wrappers.

This patch adds scripts/block-coroutine-wrapper.py together with some
friends, which will generate functions with declared prototypes marked
by the 'generated_co_wrapper' specifier.

The usage of new code generation is as follows:

    1. define the coroutine function somewhere

        int coroutine_fn bdrv_co_NAME(...) {...}

    2. declare in some header file

        int generated_co_wrapper bdrv_NAME(...);

       with same list of parameters (generated_co_wrapper is
       defined in "include/block/block.h").

    3. Make sure the block_gen_c declaration in block/meson.build
       mentions the file with your marker function.

Still, no function is now marked, this work is for the following
commit.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200924185414.28642-5-vsementsov@virtuozzo.com>
[Added encoding='utf-8' to open() calls as requested by Vladimir. Fixed
typo and grammar issues pointed out by Eric Blake. Removed clang-format
dependency that caused build test issues.
--Stefan]
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2020-10-05 10:59:06 +01:00
Paolo Bonzini
9cb54b18e8 docs: Move object.h overview doc comment to qom.rst
Move the whole contents of the overview doc comment from object.h
to qom.rst.

This makes the documentation source easier to read and edit, and
also solves the backslash escaping issue at the typecasting macro
examples.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Message-Id: <20200910221526.10041-10-ehabkost@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-30 19:11:36 +02:00
Eduardo Habkost
cd442a45db docs: Create docs/devel/qom.rst
Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
Message-Id: <20200910221526.10041-9-ehabkost@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-30 19:11:36 +02:00
Paolo Bonzini
27d551c00d meson: clean up build_by_default
Build all executables by default except for the known-broken ones.

This also allows running qemu-iotests without manually building
socket_scm_helper.

Reported-by: Max Reitz <mreitz@redhat.com>
Tested-by: Max Reitz <mreitz@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-30 19:09:19 +02:00
Peter Maydell
55ec69f8b1 docs/devel/qapi-code-gen.txt: Update to new rST backend conventions
Update the documentation of QAPI document comment syntax to match
the new rST backend requirements. The principal changes are:
 * whitespace is now significant, and multiline definitions
   must have their second and subsequent lines indented to
   match the first line
 * general rST format markup is permitted, not just the small
   set of markup the old texinfo generator handled. For most
   things (notably bulleted and itemized lists) the old format
   was the same as rST is.
 * Specific things that might trip people up:
   - instead of *bold* and _italic_ rST has **bold** and *italic*
   - lists need a preceding and following blank line
   - a lone literal '*' will need to be backslash-escaped to
     avoid a rST syntax error
 * the old leading '|' for example (literal text) blocks is
   replaced by the standard rST '::' literal block.
 * we support arbitrary levels of sub- and sub-sub-heading, not
   just a main and sub-heading like the old texinfo generator
 * lists can now be nested

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-18-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message improved slightly]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Peter Maydell
a69a6d4b4d scripts/qapi/parser.py: improve doc comment indent handling
Make the handling of indentation in doc comments more sophisticated,
so that when we see a section like:

Notes: some text
       some more text
          indented line 3

we save it for the doc-comment processing code as:

some text
some more text
   indented line 3

and when we see a section with the heading on its own line:

Notes:

some text
some more text
   indented text

we also accept that and save it in the same form.

If we detect that the comment document text is not indented as much
as we expect it to be, we throw a parse error.  (We don't complain
about over-indented sections, because for rST this can be legitimate
markup.)

The golden reference for the doc comment text is updated to remove
the two 'wrong' indents; these now form a test case that we correctly
stripped leading whitespace from an indented multi-line argument
definition.

We update the documentation in docs/devel/qapi-code-gen.txt to
describe the new indentation rules.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-6-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Whitespace between sentences tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29 17:55:39 +02:00
Stefan Hajnoczi
d73415a315 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>
2020-09-23 16:07:44 +01:00
zhaolichang
76ca4b58c2 docs/: fix some comment spelling errors
I found that there are many spelling errors in the comments of qemu,
so I used the spellcheck tool to check the spelling errors
and finally found some spelling errors in the docs folder.

Signed-off-by: zhaolichang <zhaolichang@huawei.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200917075029.313-4-zhaolichang@huawei.com>
Signed-off-by: Laurent Vivier <laurent@vivier.eu>
2020-09-17 20:37:13 +02:00
Alex Bennée
c17a386b6a plugins: move the more involved plugins to contrib
We have an exploding complexity problem in the testing so lets just
move the more involved plugins into contrib. tests/plugins still exist
for the basic plugins that exercise the API. We restore the old
pre-meson style Makefile for contrib as it also doubles as a guide for
out-of-tree plugin builds.

While we are at it add some examples to the documentation and a
specific plugins build target.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20200909112742.25730-11-alex.bennee@linaro.org>
2020-09-10 10:47:03 +01:00
Peter Maydell
6779038537 QAPI patches patches for 2020-09-08
-----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAl9XH3wSHGFybWJydUBy
 ZWRoYXQuY29tAAoJEDhwtADrkYZT2GwP/3nJIqiVF4QLp2RdZkCqiuIc4pSCJLjc
 4x75sOIsuAhNpiARvjEtsP+mlNeK+FND7Naem9ERHYVqrz8r+3jJf1EVw/sZhkg8
 f0mOism4bHji8SmpZihYiB/clgDgMpw2wc+Q6zwgSzzj81FR3HANC0gsaTXBAs8F
 B7oZ0ytpcfQNvWoXLvYSpr/5cm8mtnsLbbXoj70RfLpCqTdB1Tl8fYEfVFT8XDUd
 jIZr2UmsTTUnNI9CrIAgVTe14awRMSUnM2f8HKNWm7MFUeV3x/I1G6p2IE8Fvg+X
 k0LZkD3YSBSP2cMupwdHZ0/1WuoHV+gFOoDgPfy/wW70rpmoXpttwhJdWMya/CRt
 Ovcnj5MNUiPIlIY7qHa5E7M8Bc+ctfkXI6zsvsyzewEZxJn2YYO6wKZj6Ac4/Ztf
 7ggccRk5doc/GNXRWdPSF1dQnIvZm6vHk0AcPvHZmHM/AgwG+1g8j0aoOxLnluBf
 HFfo2+0qosYg9yTCHnWuoY9SS/NCpt7SbdqBytLYgcCXPTNMdNax492nZoO8qlcA
 dFRl7OBg9ANxiA/0GhJg3J8SwMwKEURMArkvxJhFY+MQ5AMPhjyMYxyawCA4Hq4W
 mMQgyjXk7EBZjz3dvgiAM8f4c66YfpLATObAKdk035z3ci/oih8guLnZBjtC/oNo
 LgwmoSPg+lc2
 =59S5
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-09-08' into staging

QAPI patches patches for 2020-09-08

# gpg: Signature made Tue 08 Sep 2020 07:06:52 BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2020-09-08:
  qapi/block-core.json: Fix nbd-server-start docs
  qapi: Fix indentation, again
  qapi/migration.json: Fix indentation
  qapi: Make section headings start a new doc comment block
  qapi: Reject section markup in definition documentation

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-09-08 17:23:31 +01:00
Paolo Bonzini
ef6a0d6e39 docs: update build system documentation
Most of the Makefile bits are obsolete and can be removed.

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-08 11:43:16 +02:00
Paolo Bonzini
738aa60624 docs: suggest Meson replacements for various configure functions
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-08 11:43:16 +02:00
Paolo Bonzini
b6daf4d369 configure: do not look for install(1)
It is not used anymore, so there is no Solaris-specific check to
perform.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-08 11:43:16 +02:00
Paolo Bonzini
660f793093 Makefile: inline the relevant parts of rules.mak
Most of rules.mak is not used anymore, just inline what's needed.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-08 11:43:16 +02:00
Markus Armbruster
d98884b75d qapi: Reject section markup in definition documentation
Section markup in definition documentation makes no sense and can
produce invalid Texinfo.  Reject.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200320091805.5585-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-09-07 16:35:16 +02:00
Daniel P. Berrangé
221db5daf6 qapi: enable use of g_autoptr with QAPI types
Currently QAPI generates a type and function for free'ing it:

  typedef struct QCryptoBlockCreateOptions QCryptoBlockCreateOptions;
  void qapi_free_QCryptoBlockCreateOptions(QCryptoBlockCreateOptions *obj);

This is used in the traditional manner:

  QCryptoBlockCreateOptions *opts = NULL;

  opts = g_new0(QCryptoBlockCreateOptions, 1);

  ....do stuff with opts...

  qapi_free_QCryptoBlockCreateOptions(opts);

Since bumping the min glib to 2.48, QEMU has incrementally adopted the
use of g_auto/g_autoptr. This allows the compiler to run a function to
free a variable when it goes out of scope, the benefit being the
compiler can guarantee it is freed in all possible code ptahs.

This benefit is applicable to QAPI types too, and given the seriously
long method names for some qapi_free_XXXX() functions, is much less
typing. This change thus makes the code generator emit:

 G_DEFINE_AUTOPTR_CLEANUP_FUNC(QCryptoBlockCreateOptions,
                              qapi_free_QCryptoBlockCreateOptions)

The above code example now becomes

  g_autoptr(QCryptoBlockCreateOptions) opts = NULL;

  opts = g_new0(QCryptoBlockCreateOptions, 1);

  ....do stuff with opts...

Note, if the local pointer needs to live beyond the scope holding the
variable, then g_steal_pointer can be used. This is useful to return the
pointer to the caller in the success codepath, while letting it be freed
in all error codepaths.

  return g_steal_pointer(&opts);

The crypto/block.h header needs updating to avoid symbol clash now that
the g_autoptr support is a standard QAPI feature.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20200723153845.2934357-1-berrange@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-03 09:38:36 +02:00
Paolo Bonzini
1a94933fcc meson: use pkg-config method to find dependencies
We do not need to ask cmake for the dependencies, so just use the
pkg-config mechanism.  Keep "auto" for SDL so that it tries using
sdl-config too.

The documentation is adjusted to use SDL2_image as the example,
rather than SDL which does not use the "pkg-config" method.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-09-01 08:51:35 -04:00
Paolo Bonzini
a14f0bf165 docs: convert build system documentation to rST
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:45 -04:00
Paolo Bonzini
77d27b9271 meson: update build-system documentation
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:45 -04:00
Paolo Bonzini
484e2cc730 rules.mak: drop unneeded macros
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:42 -04:00
Paolo Bonzini
64ed6f92ff meson: link emulators without Makefile.target
The binaries move to the root directory, e.g. qemu-system-i386 or
qemu-arm.  This requires changes to qtests, CI, etc.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:40 -04:00
Paolo Bonzini
a81df1b68b libqemuutil, qapi, trace: convert to meson
This shows how to do some "computations" in meson.build using its array
and dictionary data structures, and also a basic usage of the sourceset
module for conditional compilation.

Notice the new "if have_system" part of util/meson.build, which fixes
a bug in the old build system was buggy: util/dbus.c was built even for
non-softmmu builds, but the dependency on -lgio was lost when the linking
was done through libqemuutil.a.  Because all of its users required gio
otherwise, the bug was hidden.  Meson instead propagates libqemuutil's
dependencies down to its users, and shows the problem.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:08 -04:00
Marc-André Lureau
bf0e56a3ca meson: use coverage option
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-08-21 06:30:07 -04:00
Richard Henderson
ffdfca6fac docs/devel: Document decodetree no-overlap groups
When support for this feature went in, the update to the
documentation was forgotten.

Fixes: 067e8b0f45
Reported-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200803205708.315829-1-richard.henderson@linaro.org
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-08-04 16:33:47 +01:00
Alexander Bulekov
09a14f586c docs/fuzz: add instructions for generating a coverage report
Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20200706195534.14962-5-alxndr@bu.edu>
[thuth: Replaced --enable-sanitizers with --enable-fuzzing]
Signed-off-by: Thomas Huth <thuth@redhat.com>
2020-07-21 07:29:18 +02:00
Alexander Bulekov
19a91e4af8 docs/fuzz: add information about useful libFuzzer flags
Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20200706195534.14962-4-alxndr@bu.edu>
Signed-off-by: Thomas Huth <thuth@redhat.com>
2020-07-21 07:27:28 +02:00
Alexander Bulekov
ee16da12d7 docs/fuzz: describe building fuzzers with enable-sanitizers
Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20200706195534.14962-3-alxndr@bu.edu>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
2020-07-21 07:27:28 +02:00
Alex Bennée
93154e767f docs/devel: fix grammar in multi-thread-tcg
Review comment came just too late ;-)

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org>
Message-Id: <20200713200415.26214-9-alex.bennee@linaro.org>
2020-07-15 11:52:39 +01:00
Thomas Huth
590246ead7 docs/devel/fuzzing: Fix bugs in documentation
Fix typo - the option is called "--fuzz-target" and not "--fuzz_taget".
Also use a different fuzzer in the example, since "virtio-net-fork-fuzz"
does not seem to be a valid fuzzer target (anymore?).

Signed-off-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20200709084059.22539-1-thuth@redhat.com>
2020-07-13 11:40:52 +02:00
Alex Bennée
4d7fe02be3 docs/devel: add some notes on tcg-icount for developers
This attempts to bring together my understanding of the requirements
for icount behaviour into one reference document for our developer
notes.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Cc: Paolo Bonzini <pbonzini@redhat.com>
Cc: Pavel Dovgalyuk <dovgaluk@ispras.ru>
Cc: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200709141327.14631-3-alex.bennee@linaro.org>
2020-07-11 15:53:00 +01:00
Alex Bennée
c8c06e520d docs/devel: convert and update MTTCG design document
Do a light conversion to .rst and clean-up some of the language at the
start now MTTCG has been merged for a while.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-Id: <20200709141327.14631-2-alex.bennee@linaro.org>
2020-07-11 15:53:00 +01:00
Markus Armbruster
cdd2b228b9 qapi: Smooth visitor error checking in generated code
Use visitor functions' return values to check for failure.  Eliminate
error_propagate() that are now unnecessary.  Delete @err that are now
unused.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200707160613.848843-41-armbru@redhat.com>
2020-07-10 15:18:08 +02:00
Markus Armbruster
012d4c96e2 qapi: Make visitor functions taking Error ** return bool, not void
See recent commit "error: Document Error API usage rules" for
rationale.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
Message-Id: <20200707160613.848843-18-armbru@redhat.com>
2020-07-10 15:18:08 +02:00
Robert Foley
3b6882bd96 docs: Added details on TSan to testing.rst
Adds TSan details to testing.rst.
This includes background and reference details on TSan,
and details on how to build and test with TSan
both with and without docker.

Signed-off-by: Robert Foley <robert.foley@linaro.org>
Reviewed-by: Emilio G. Cota <cota@braap.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20200609200738.445-13-robert.foley@linaro.org>
Message-Id: <20200612190237.30436-16-alex.bennee@linaro.org>
2020-06-16 14:49:05 +01:00
Richard Henderson
b9e60257c1 accel/tcg: Add endian-specific cpu_{ld, st}* operations
We currently have target-endian versions of these operations,
but no easy way to force a specific endianness.  This can be
helpful if the target has endian-specific operations, or a mode
that swaps endianness.

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200508154359.7494-7-richard.henderson@linaro.org
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-05-11 11:22:06 +01:00
Marc-André Lureau
979da8b357 docs/devel/migration: start a debugging section
Explain how to use analyze-migration.py, this may help.

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20200330174852.456148-1-marcandre.lureau@redhat.com>
Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
2020-05-07 17:40:24 +01:00
Peter Maydell
126eeee6c7 target-arm queue:
* xlnx-zdma: Fix endianness handling of descriptor loading
  * nrf51: Fix last GPIO CNF address
  * gicv3: Use gicr_typer in arm_gicv3_icc_reset
  * msf2: Add EMAC block to SmartFusion2 SoC
  * New clock modelling framework
  * hw/arm: versal: Setup the ADMA with 128bit bus-width
  * Cadence: gem: fix wraparound in 64bit descriptors
  * cadence_gem: clear RX control descriptor
  * target/arm: Vectorize integer comparison vs zero
  * hw/arm/virt: dt: add kaslr-seed property
  * hw/arm: xlnx-zcu102: Disable unsupported FDT firmware nodes
 -----BEGIN PGP SIGNATURE-----
 
 iQJNBAABCAA3FiEE4aXFk81BneKOgxXPPCUl7RQ2DN4FAl6q5CoZHHBldGVyLm1h
 eWRlbGxAbGluYXJvLm9yZwAKCRA8JSXtFDYM3pWPD/9zjcV3TlOUWg/2aRQOYWB1
 I/h2AGTI09Y/nGMmwvHEyQKyAg6mL8KfJwCUDHr1pE3DeTt4Z7dA+3rhk1uy+gKA
 Ot/7e4IVSMiNh28xkBiSPviBXjYtgmVjvSlgKn4fty6g+30wdGV8ymNz1wXO8II0
 5cuGlaz0VQ4N+W4qz9kuaJNEAsMSnmrJ9fUzZDllRsNy4li3aSR4sQ9CymsJ23+3
 9CdStk/ibA7tExDX5qkj4lKozENEAU/jethA91CQCMLnK/7aGfHbLqVyWu6xDuQ7
 oTdyXr7nrGIUjod+Cx7mLyUQKXVfsiw0x4kmjvOnaVZHh5oIgDj83vWXQ28nC6P4
 wVYCRWpg68GPuaEru8VeocdoATMa1ONjrv5/gFGOxlma4AjD07WQ53hTp2pL0HT2
 +uYPwm2iSYgYKX7QV/rbNzWHK1nYq6/3LDeVQc6nr/3jVewpZngnf2pMxChRUUoT
 qtdLwJL/om9hqV4lsU7cxHKSNnkocfDhjkwRy6wg0L/iXDftt1sKbZO+G78vvsow
 S+NqjpAo4m+P7ExS8DGiSsgvQIQIHvcjjpeym4fWmBxPaXep6oUIewzBuExcYWK8
 XogFZEnW6PNyr/CKLh7GYH9C0F6FI36+yPUZFxvdBpz4w5QBADYKyyG0/53P0uKa
 ez3ixFfplzcx8RIiy+nIsQ==
 =9plU
 -----END PGP SIGNATURE-----

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

target-arm queue:
 * xlnx-zdma: Fix endianness handling of descriptor loading
 * nrf51: Fix last GPIO CNF address
 * gicv3: Use gicr_typer in arm_gicv3_icc_reset
 * msf2: Add EMAC block to SmartFusion2 SoC
 * New clock modelling framework
 * hw/arm: versal: Setup the ADMA with 128bit bus-width
 * Cadence: gem: fix wraparound in 64bit descriptors
 * cadence_gem: clear RX control descriptor
 * target/arm: Vectorize integer comparison vs zero
 * hw/arm/virt: dt: add kaslr-seed property
 * hw/arm: xlnx-zcu102: Disable unsupported FDT firmware nodes

# gpg: Signature made Thu 30 Apr 2020 15:43:54 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-20200430-1: (30 commits)
  hw/arm: xlnx-zcu102: Disable unsupported FDT firmware nodes
  hw/arm: xlnx-zcu102: Move arm_boot_info into XlnxZCU102
  device_tree: Constify compat in qemu_fdt_node_path()
  device_tree: Allow name wildcards in qemu_fdt_node_path()
  target/arm/cpu: Update coding style to make checkpatch.pl happy
  target/arm: Make cpu_register() available for other files
  target/arm: Restrict the Address Translate write operation to TCG accel
  hw/arm/virt: dt: add kaslr-seed property
  hw/arm/virt: dt: move creation of /secure-chosen to create_fdt()
  target/arm: Vectorize integer comparison vs zero
  net: cadence_gem: clear RX control descriptor
  Cadence: gem: fix wraparound in 64bit descriptors
  hw/arm: versal: Setup the ADMA with 128bit bus-width
  qdev-monitor: print the device's clock with info qtree
  hw/arm/xilinx_zynq: connect uart clocks to slcr
  hw/char/cadence_uart: add clock support
  hw/misc/zynq_slcr: add clock generation for uarts
  docs/clocks: add device's clock documentation
  qdev-clock: introduce an init array to ease the device construction
  qdev: add clock input&output support to devices.
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-04-30 15:45:34 +01:00
Peter Maydell
31e5784a0d docs/clocks: add device's clock documentation
Add the documentation about the clock inputs and outputs in devices.

This is based on the original work of Frederic Konrad.

Signed-off-by: Damien Hedde <damien.hedde@greensocs.com>
Reviewed-by: Alistair Francis <alistair.francis@wdc.com>
Reviewed-by: Edgar E. Iglesias <edgar.iglesias@xilinx.com>
Message-id: 20200406135251.157596-6-damien.hedde@greensocs.com
[PMM: Editing pass for minor grammar, style and Sphinx
 formatting fixes]
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-04-30 15:35:40 +01:00
Markus Armbruster
2061487bdb qapi: Disallow qmp_marshal_FOO(NULL, ...)
For QMP commands without arguments, gen_marshal() laboriously
generates a qmp_marshal_FOO() that copes with null @args.  Turns
there's just one caller that passes null instead of an empty QDict.
Adjust that caller, and simplify gen_marshal().

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200424084338.26803-15-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-04-30 07:26:41 +02:00
Markus Armbruster
8e08bf4ea2 qapi: Assert incomplete object occurs only in dealloc visitor
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200424084338.26803-7-armbru@redhat.com>
2020-04-30 06:51:15 +02:00
Paolo Bonzini
fb8a9677b1 rcu: do not mention atomic_mb_read/set in documentation
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-04-13 02:56:18 -04:00
Paolo Bonzini
de99dab06f atomics: update documentation
Some of the constraints on operand sizes have been relaxed, so adjust the
documentation.

Deprecate atomic_mb_read and atomic_mb_set; it is not really possible to
use them correctly because they do not interoperate with sequentially-consistent
RMW operations.

Finally, extend the memory barrier pairing section to cover acquire and
release semantics in general, roughly based on the KVM Forum 2016 talk,
"<atomic.h> weapons".

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-04-13 02:56:03 -04:00
Paolo Bonzini
15e8699f00 atomics: convert to reStructuredText
No attempts to fix or update the text; these are left for the next
patch in the series.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-04-11 08:49:25 -04:00
Markus Armbruster
f965e8fea6 qapi: New special feature flag "deprecated"
Unlike regular feature flags, the new special feature flag
"deprecated" is recognized by the QAPI generator.  For now, it's only
permitted with commands, events, and struct members.  It will be put
to use shortly.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200317115459.31821-26-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
[Doc typo fixed]
2020-03-17 21:42:47 +01:00
Markus Armbruster
84ab008687 qapi: Add feature flags to struct members
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20200317115459.31821-21-armbru@redhat.com>
2020-03-17 21:25:47 +01:00
Markus Armbruster
013b4efc9b qapi: Add feature flags to remaining definitions
In v4.1.0, we added feature flags just to struct types (commit
6a8c0b5102^..f3ed93d545), to satisfy an immediate need (commit
c9d4070991 "file-posix: Add dynamic-auto-read-only QAPI feature").  In
v4.2.0, we added them to commands (commit 23394b4c39 "qapi: Add
feature flags to commands") to satisfy another immediate need (commit
d76744e65e "qapi: Allow introspecting fix for savevm's cooperation
with blockdev").

Add them to the remaining definitions: enumeration types, union types,
alternate types, and events.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200317115459.31821-13-armbru@redhat.com>
2020-03-17 19:58:34 +01:00
Markus Armbruster
86014c64f9 docs/devel/qapi-code-gen: Document 'features' introspection
Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected
to update section "Client JSON Protocol introspection", and commit
23394b4c39 "qapi: Add feature flags to commands" didn't either.  Make
up for that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200317115459.31821-5-armbru@redhat.com>
2020-03-17 19:58:34 +01:00
Markus Armbruster
ad52292ea1 docs/devel/qapi-code-gen: Clarify allow-oob introspection
Mention SchemaInfo variant member "allow-oob" defaults to false.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20200317115459.31821-4-armbru@redhat.com>
2020-03-17 19:58:34 +01:00
Markus Armbruster
942ab6865a docs/devel/qapi-code-gen: Fix typo in grammar
An ALTERNATIVE's value can only be a type name.  Arrays are not
supported, yet.  The text gets it right: "The form STRING is shorthand
for { 'type': STRING }."  The grammar doesn't.  Fix it.

Fixes: b6c37ebaaf
Reported-by: John Snow <jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200309142638.19988-1-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
2020-03-17 17:34:21 +01:00
Peter Maydell
6fe6d6c9a9 docs: Be consistent about capitalization of 'Arm'
The company 'Arm' went through a rebranding some years back
involving a recapitalization from 'ARM' to 'Arm'. As a result
our documentation is a bit inconsistent between the two forms.
It's not worth trying to update everywhere in QEMU, but it's
easy enough to make docs/ consistent.

Note that "ARMv8" and similar architecture names, and
older CPU names like "ARM926" still retain all-caps.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Niek Linnenbank <nieklinnenbank@gmail.com>
Message-id: 20200309215818.2021-6-peter.maydell@linaro.org
2020-03-12 11:20:20 +00:00
Peter Maydell
430f63e250 Includes a headers update against 5.6-current.
- add missing vcpu reset functionality
 - rstfy some s390 documentation
 - fixes and enhancements
 -----BEGIN PGP SIGNATURE-----
 
 iQJGBAABCAAwFiEEw9DWbcNiT/aowBjO3s9rk8bwL68FAl5XrPASHGNvaHVja0By
 ZWRoYXQuY29tAAoJEN7Pa5PG8C+vbLwP/jCxQfhEbiGFs3M7Xz6FNXmGQ3Zmw2j2
 6YNSK7Qpe9GPYlmU4UyhG83buGX1pTF4YgvmpIlMgm33fGRL7FKVDHCXv8qYRvUF
 QB/SV/YfoFwVSBtE7uiHLg0/5YtvbK7dwZiWA1bKSOUp4NsZJofL2qqQnP2m9ecA
 ZRiJxQ2KJjeQ6rLkPHwVkoTut3Xd55HHdKqEo8BVsq1XFKc7nFpE9o4QpuHbODi8
 CzGxJSpUImmsk39obY5jYbW8xiVm6xkVbp+bXGBHSOoCOCFeXqE7MjnF7xE7xeVF
 ST9Jtd/8dFI4v5qVhhfdy/K6EvUoiZ/aUTF1J2PRzg9nueDzYNdJTVVvC/DgCfQn
 joSVjlvawHKzmVkEWcmj3NxQsT1m9pq77HD3du8miYs48IUmE7qsBmKNp8ToaBSV
 L99EwujOFXfrqyCPnfycZzVFWG48+ppmF43gKhthKk7EuacdB8NPr6ePuDkZf9DM
 l6sfjwRGSvZdmgsenvavk12ug433gO2VNxH4AarWNtXq8ADBCtvgQCtEGZMbV+Js
 dm3uPtVF5RKxoHeuXv7wTgt6TybzPEb0+WSEYEfDyquwKFFAAckFmk6giccusXiA
 umXvXXmIab/xa2VVRRNUS4Rq4mJ+kXFKpXVgdt633ZwWFc9vQMFowzUo99+1BUfi
 JX0Bkb4zFbox
 =zN7w
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/cohuck/tags/s390x-20200227' into staging

Includes a headers update against 5.6-current.
- add missing vcpu reset functionality
- rstfy some s390 documentation
- fixes and enhancements

# gpg: Signature made Thu 27 Feb 2020 11:50:08 GMT
# gpg:                using RSA key C3D0D66DC3624FF6A8C018CEDECF6B93C6F02FAF
# gpg:                issuer "cohuck@redhat.com"
# gpg: Good signature from "Cornelia Huck <conny@cornelia-huck.de>" [marginal]
# gpg:                 aka "Cornelia Huck <huckc@linux.vnet.ibm.com>" [full]
# gpg:                 aka "Cornelia Huck <cornelia.huck@de.ibm.com>" [full]
# gpg:                 aka "Cornelia Huck <cohuck@kernel.org>" [marginal]
# gpg:                 aka "Cornelia Huck <cohuck@redhat.com>" [marginal]
# Primary key fingerprint: C3D0 D66D C362 4FF6 A8C0  18CE DECF 6B93 C6F0 2FAF

* remotes/cohuck/tags/s390x-20200227:
  s390x: Rename and use constants for short PSW address and mask
  docs: rstfy vfio-ap documentation
  docs: rstfy s390 dasd ipl documentation
  s390/sclp: improve special wait psw logic
  s390x: Add missing vcpu reset functions
  linux-headers: update
  target/s390x/translate: Fix RNSBG instruction

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-27 19:56:37 +00:00
Cornelia Huck
cc3d15a5ea docs: rstfy s390 dasd ipl documentation
While at it, also fix the numbering in 'What QEMU does'.

Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20200213162942.14177-2-cohuck@redhat.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>
2020-02-26 18:57:07 +01:00
Alex Bennée
9675a9c6e8 docs/devel: document query handle lifetimes
I forgot to document the lifetime of handles in the developer
documentation. Do so now.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Robert Foley <robert.foley@linaro.org>
Reviewed-by: Robert Foley <robert.foley@linaro.org>
Message-Id: <20200225124710.14152-11-alex.bennee@linaro.org>
2020-02-25 20:20:23 +00:00
Alexander Bulekov
e5c59355ae fuzz: add documentation to docs/devel/
Signed-off-by: Alexander Bulekov <alxndr@bu.edu>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Darren Kenny <darren.kenny@oracle.com>
Message-id: 20200220041118.23264-23-alxndr@bu.edu
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2020-02-22 08:26:48 +00:00
Thomas Huth
316082b119 docs/devel: Fix qtest paths and info about check-block in testing.rst
The qtests have recently been moved to a separate subdirectory, so
the paths that are mentioned in the documentation have to be adjusted
accordingly. And some of the iotests are now always run as part of
"make check", so this information has to be adjusted here, too.

Message-Id: <20200122134511.23806-1-thuth@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
2020-02-04 09:00:57 +01:00
Peter Maydell
1aa6430dbe docs/devel/tracing.txt: Recommend only trace_event_get_state_backends()
Instead of recommending checking the TRACE_FOO_ENABLED macro to
skip expensive computations needed only for tracing, recommend
only using trace_event_get_state_backends(). This works for both
compile-time and run-time disabling of events, and has no extra
performance impact if the event is compile-time disabled.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20200120151142.18954-2-peter.maydell@linaro.org
Message-Id: <20200120151142.18954-2-peter.maydell@linaro.org>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
2020-01-30 21:33:50 +00:00
Damien Hedde
d66cc84cd1 docs/devel/reset.rst: add doc about Resettable interface
Signed-off-by: Damien Hedde <damien.hedde@greensocs.com>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-id: 20200123132823.1117486-10-damien.hedde@greensocs.com
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-01-30 16:02:05 +00:00
Cornelia Huck
174b72aa38 docs/devel: fix stable process doc formatting
Enumeration of stable criteria needs proper bullet points.

Message-Id: <20200113103023.31255-1-cohuck@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Cornelia Huck <cohuck@redhat.com>
2020-01-27 12:13:09 +01:00
Peter Maydell
cbf01142b2 Add cpu_{ld,st}*_mmuidx_ra
Remove MMU_MODE*_SUFFIX
 Move tcg headers under include/
 -----BEGIN PGP SIGNATURE-----
 
 iQFRBAABCgA7FiEEekgeeIaLTbaoWgXAZN846K9+IV8FAl4fvikdHHJpY2hhcmQu
 aGVuZGVyc29uQGxpbmFyby5vcmcACgkQZN846K9+IV+R3gf8CITIUCoUyvAJFDp/
 5aSaArVP/3IlO37BSDYL1qu4uwJYmlGpdjNNZ5MaqhnQ9FbnaZxtIqDPIYOcUeOd
 MYFoD7G/uTfQqGNRtrDN88QEN0SVJVPis5/IGy9SpHSgopHwdbEeu8EmBb54Mwu6
 drWsUnLCYqDKg8bqn3bliIhh+T3vL+KROPJB2rxhnOUm4YelRvDLvCFFDHaNYf9f
 fYSAyjxqdjES8qX106SKU96zgaWOQy38GChKrYKgg9LECbZ/3SVUYHwQMsusMwg5
 DZZ1OlLPVdUtbkUt6nB2X5pFrNQf3oDUDeyFAH7D6C6nki42EqjEou4n5McFlZPF
 LS93ag==
 =NaTS
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20200115' into staging

Add cpu_{ld,st}*_mmuidx_ra
Remove MMU_MODE*_SUFFIX
Move tcg headers under include/

# gpg: Signature made Thu 16 Jan 2020 01:36:41 GMT
# gpg:                using RSA key 7A481E78868B4DB6A85A05C064DF38E8AF7E215F
# gpg:                issuer "richard.henderson@linaro.org"
# gpg: Good signature from "Richard Henderson <richard.henderson@linaro.org>" [full]
# Primary key fingerprint: 7A48 1E78 868B 4DB6 A85A  05C0 64DF 38E8 AF7E 215F

* remotes/rth/tags/pull-tcg-20200115: (34 commits)
  MAINTAINERS: Replace Claudio Fontana for tcg/aarch64
  configure: Remove tcg/ from the preprocessor include search list
  tcg: Move TCG headers to include/tcg/
  tcg: Search includes in the parent source directory
  tcg: Search includes from the project root source directory
  cputlb: Expand cpu_ldst_template.h in cputlb.c
  cputlb: Remove support for MMU_MODE*_SUFFIX
  target/ppc: Use cpu_*_mmuidx_ra instead of MMU_MODE*_SUFFIX
  target/s390x: Use cpu_*_mmuidx_ra instead of MMU_MODE*_SUFFIX
  target/mips: Use cpu_*_mmuidx_ra instead of MMU_MODE*_SUFFIX
  target/m68k: Use cpu_*_mmuidx_ra instead of MMU_MODE{0,1}_SUFFIX
  target/xtensa: Remove MMU_MODE{0,1,2,3}_SUFFIX
  target/unicore32: Remove MMU_MODE{0,1}_SUFFIX
  target/sh4: Remove MMU_MODE{0,1}_SUFFIX
  target/microblaze: Remove MMU_MODE{0,1,2}_SUFFIX
  target/i386: Remove MMU_MODE{0,1,2}_SUFFIX
  target/cris: Remove MMU_MODE{0,1}_SUFFIX
  target/alpha: Remove MMU_MODE{0,1}_SUFFIX
  target/nios2: Remove MMU_MODE{0,1}_SUFFIX
  cputlb: Expand cpu_ldst_useronly_template.h in user-exec.c
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-01-17 12:13:17 +00:00
Richard Henderson
f4e1bae259 cputlb: Provide cpu_(ld,st}*_mmuidx_ra for user-only
This finishes the new interface began with the previous patch.
Document the interface and deprecate MMU_MODE<N>_SUFFIX.

Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2020-01-15 15:13:10 -10:00
Richard Henderson
fc4120a378 cputlb: Rename helper_ret_ld*_cmmu to cpu_ld*_code
There are no uses of the *_cmmu names other than the bare wrapping
within the *_code inlines.  Therefore rename the functions so we
can drop the inlines.

Use abi_ptr instead of target_ulong in preparation for user-only;
the two types are identical for softmmu.

Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Aleksandar Markovic <amarkovic@wavecomp.com>
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2020-01-15 15:13:10 -10:00
Markus Armbruster
00ca24ff9e qapi: Generate command registration stuff into separate files
Having to include qapi-commands.h just for qmp_init_marshal() is
suboptimal.  Generate it into separate files.  This lets
monitor/misc.c, qga/main.c, and the generated qapi-commands-FOO.h
include less.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20191120182551.23795-4-armbru@redhat.com>
[Typos in docs/devel/qapi-code-gen.txt fixed]
Reviewed-by: Eric Blake <eblake@redhat.com>
2020-01-14 11:01:58 +01:00
Peter Maydell
f59b31e6d0 Various testing and logging updates
- test tci with Travis
   - enable multiarch testing in Travis
   - default to out-of-tree builds
   - make changing logfile safe via RCU
   - remove redundant tests
   - remove gtester test from docker
   - convert DEBUG_MMAP to tracepoints
   - remove hand rolled glob function
   - trigger tcg re-configure when needed
 -----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAl37M6gACgkQ+9DbCVqe
 KkQ0Rwf/d0lGDPQN1Uf0zqZRQQmDCqWVuqHhZJ5xWDjbyVT2eUwR07TvNZeUKEWX
 iO+u6S7Tv91oLjZN5WjhaiuSjtJaEzCdcpkIJAWXLP/lzse37HEwvLBsdg71y+46
 LNvBrJRPpQotdb7fjr8RgCwc1qg2Bz15ekSn7XIA175zTMmUsshLJBVhLbGNqrVm
 F2UmjB9oFJ0+nzrcEnpFmWw7xvVrX1dImZXv5C2pvuHF7efSjGwiFviTRZgDjOGs
 V7HiWRV1QcgTigncncxTMbhMTKTVKK+e7O+y0DZWt/NSrT/yLDy5rcwySpmvu6C+
 cRmh/0tMo1KAhiz8Xy8LookhVj6hdA==
 =OAkV
 -----END PGP SIGNATURE-----

Merge remote-tracking branch 'remotes/stsquad/tags/pull-tesing-and-misc-191219-1' into staging

Various testing and logging updates

  - test tci with Travis
  - enable multiarch testing in Travis
  - default to out-of-tree builds
  - make changing logfile safe via RCU
  - remove redundant tests
  - remove gtester test from docker
  - convert DEBUG_MMAP to tracepoints
  - remove hand rolled glob function
  - trigger tcg re-configure when needed

# gpg: Signature made Thu 19 Dec 2019 08:24:08 GMT
# gpg:                using RSA key 6685AE99E75167BCAFC8DF35FBD0DB095A9E2A44
# gpg: Good signature from "Alex Bennée (Master Work Key) <alex.bennee@linaro.org>" [full]
# Primary key fingerprint: 6685 AE99 E751 67BC AFC8  DF35 FBD0 DB09 5A9E 2A44

* remotes/stsquad/tags/pull-tesing-and-misc-191219-1: (25 commits)
  tests/tcg: ensure we re-configure if configure.sh is updated
  trace: replace hand-crafted pattern_glob with g_pattern_match_simple
  linux-user: convert target_munmap debug to a tracepoint
  linux-user: log page table changes under -d page
  linux-user: add target_mmap_complete tracepoint
  linux-user: convert target_mmap debug to tracepoint
  linux-user: convert target_mprotect debug to tracepoint
  travis.yml: Remove the redundant clang-with-MAIN_SOFTMMU_TARGETS entry
  docker: gtester is no longer used
  Added tests for close and change of logfile.
  Add use of RCU for qemu_logfile.
  qemu_log_lock/unlock now preserves the qemu_logfile handle.
  Add a mutex to guarantee single writer to qemu_logfile handle.
  Cleaned up flow of code in qemu_set_log(), to simplify and clarify.
  Fix double free issue in qemu_set_log_filename().
  ci: build out-of-tree
  travis.yml: Enable builds on arm64, ppc64le and s390x
  tests/test-util-filemonitor: Skip test on non-x86 Travis containers
  tests/hd-geo-test: Skip test when images can not be created
  iotests: Skip test 079 if it is not possible to create large files
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2019-12-20 14:00:49 +00:00
Wainer dos Santos Moschetta
1e48931c0c tests/vm: Allow to set qemu-img path
By default VM build test use qemu-img from system's PATH to
create the image disk. Due the lack of qemu-img on the system
or the desire to simply use a version built with QEMU, it would
be nice to allow one to set its path. So this patch makes that
possible by reading the path to qemu-img from QEMU_IMG if set,
otherwise it fallback to default behavior.

Signed-off-by: Wainer dos Santos Moschetta <wainersm@redhat.com>
Message-Id: <20191114134246.12073-2-wainersm@redhat.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
2019-12-18 20:17:33 +00:00
Paolo Bonzini
f3224c5285 docs: add memory API reference
Add kernel-doc directive to parse and include doc comments from
include/exec/memory.h.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2019-12-17 19:36:58 +01:00
Peter Maydell
f298bb45dc docs: Create bitops.rst as example of kernel-docs
Create a bitops.rst which is just a container for the
kernel-doc comments in qemu/bitops.h.

This is mostly a test of the kernel-doc extension machinery.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20190521122519.12573-7-peter.maydell@linaro.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2019-12-17 19:36:57 +01:00
Cleber Rosa
ba21bde930 Acceptance tests: use avocado tags for machine type
The same way the arch tag is being used as a fallback for the arch
parameter, let's do the same for QEMU's machine and avoid some boiler
plate code.

This is now possible because, since Avocado 72.0, it's possible to use
tags with names that match the machine types on QEMU.

Signed-off-by: Cleber Rosa <crosa@redhat.com>
Message-Id: <20191104151323.9883-4-crosa@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Cleber Rosa <crosa@redhat.com>
2019-12-16 11:23:19 -05:00
Alex Bennée
5c6ecbdc83 docs/devel: update tcg-plugins.rst with API versioning details
While we are at it fix up the quoted code sections with the inline ::
approach.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Robert Foley <robert.foley@linaro.org>
2019-11-20 10:53:31 +00:00
Alex Bennée
8ea6abf0d0 docs/devel: rename plugins.rst to tcg-plugins.rst
This makes it a bit clearer what this is about.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
2019-11-20 10:53:31 +00:00
Alex Bennée
027e3332b8 docs/devel: add plugins.rst design document
This is mostly extracted from Emilio's more verbose commit comments
with some additional verbiage from me.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
2019-10-28 15:12:38 +00:00
Peter Krempa
23394b4c39 qapi: Add feature flags to commands
Similarly to features for struct types introduce the feature flags also
for commands. This will allow notifying management layers of fixes and
compatible changes in the behaviour of a command which may not be
detectable any other way.

The changes were heavily inspired by commit 6a8c0b5102.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20191018081454.21369-3-armbru@redhat.com>
2019-10-22 13:54:13 +02:00
Peter Maydell
9020e9526c Pull request
v2:
  * Replaced "Launchpad:" tag with "Buglink:" as documented on the SubmitAPatch wiki page [Philippe]
 -----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCAAdFiEEhpWov9P5fNqsNXdanKSrs4Grc8gFAl2liAEACgkQnKSrs4Gr
 c8jrBwf8DrT1i2jGS9VXtpUDKp9NTIW251d8opAyQ7MJlw0PO5VpK/ThGv7upWW1
 kmqU06+3axh2Dv7IJxD0bLmZ3Jyt4jSTLwEpbuV1A4yN8R9NN3mmDhX7I05RIL1C
 Bjh3T6BB72/7CkZJA5QdaqCZjVTeFmIZgAaOtYivVSJGqo8leWQ8r3ShWG+AQTta
 CXg/XKwGkjCYawgVs305zEYhN3WkM3xbOM3jm+LlklK56Evf0TlsJuViec1fm3Nw
 tBinvuYZrRt19E0fzbZzNgrhorzIEEJd7dN2bSwJVVpynEbGWuTQ2NNf1Bc5+0pT
 4UaKYeY7qjosWAa2l9/dhgyrarrVlA==
 =ODk9
 -----END PGP SIGNATURE-----

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

Pull request

v2:
 * Replaced "Launchpad:" tag with "Buglink:" as documented on the SubmitAPatch wiki page [Philippe]

# gpg: Signature made Tue 15 Oct 2019 09:49:05 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/tracing-pull-request:
  trace: avoid "is" with a literal Python 3.8 warnings
  trace: add --group=all to tracing.txt

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2019-10-15 12:00:33 +01:00
Stefan Hajnoczi
bd200384c5 trace: add --group=all to tracing.txt
tracetool needs to know the group name ("all", "root", or a specific
subdirectory).  Also remove the stdin redirection because tracetool.py
needs the path to the trace-events file.  Update the documentation.

Fixes: 2098c56a9b
       ("trace: move setting of group name into Makefiles")
Buglink: https://bugs.launchpad.net/bugs/1844814
Reported-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-Id: <20191009135154.10970-1-stefanha@redhat.com>
2019-10-15 09:46:21 +01:00
Dr. David Alan Gilbert
5626f8c6d4 rcu: Add automatically released rcu_read_lock variants
RCU_READ_LOCK_GUARD() takes the rcu_read_lock and then uses glib's
g_auto infrastructure (and thus whatever the compiler's hooks are) to
release it on all exits of the block.

WITH_RCU_READ_LOCK_GUARD() is similar but is used as a wrapper for the
lock, i.e.:

   WITH_RCU_READ_LOCK_GUARD() {
       stuff under lock
   }

Note the 'unused' attribute is needed to work around clang bug:
  https://bugs.llvm.org/show_bug.cgi?id=43482

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Acked-by: Paolo Bonzini <pbonzini@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-Id: <20191007143642.301445-2-dgilbert@redhat.com>
Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
2019-10-11 14:19:49 +01:00
Alex Bennée
f8ed349e6d docs/devel: add "check-tcg" to testing.rst
It was pointed out we haven't documented the check-tcg part of the
build system. Attempt to rectify that now.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
2019-09-26 19:00:53 +01:00
Markus Armbruster
9d55380b5a qapi: Remove null from schema language
We represent the parse tree as OrderedDict.  We fetch optional dict
members with .get().  So far, so good.

We represent null literals as None.  .get() returns None both for
"absent" and for "present, value is the null literal".  Uh-oh.

Test features-if-invalid exposes this bug: "'if': null" is
misinterpreted as absent "if".

We added null to the schema language to "allow [...] an explicit
default value" (commit e53188ada5 "qapi: Allow true, false and null in
schema json", v2.4.0).  Hasn't happened; null is still unused except
as generic invalid value in tests/.

To fix, we'd have to replace .get() by something more careful, or
represent null differently.  Feasible, but we got more and bigger fish
to fry right now.  Remove the null literal from the schema language.
Replace null in tests by another invalid value.

Test features-if-invalid now behaves as it should.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20190914153506.2151-10-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
2019-09-24 14:07:23 +02:00
Markus Armbruster
b6c37ebaaf docs/devel/qapi-code-gen: Improve QAPI schema language doc
We document the language by giving patterns of valid JSON objects.
The patterns contain placeholders we don't define anywhere; their
names have to speak for themselves.  I guess they do, but I'd prefer a
bit more rigor.  Provide a grammar instead, and rework the text
accordingly.

Documentation for QAPI schema conditionals (commit 967c885108,
6cc32b0e14, 87adbbffd4..3e270dcacc) and feature flags (commit
6a8c0b5102) was bolted on.  The sections documenting types, commands
and events don't mention them.  Section "Features" and "Configuring
the schema" then provide additional syntax for types, commands and
events.  I hate that.  Fix the sections documenting types, commands
and events to provide accurate syntax, and point to "Features" and
"Configuring the schema" for details.

We talk about "(top-level) expressions other than include and pragma".
Adopt more convenient terminology: a (top-level) expression is either
a directive (include or pragma) or a definition (anything else).

Avoid the terms "dictionary" and "key".  Stick to JSON terminology
"object" and "member name" instead.

While there, make spacing more consistent.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-16-armbru@redhat.com>
2019-09-24 14:07:22 +02:00
Markus Armbruster
634c82c163 docs/devel/qapi-code-gen: Rewrite introduction to schema
The introduction to the QAPI schema is somewhat rambling.  Rewrite for
clarity.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-15-armbru@redhat.com>
2019-09-24 14:07:22 +02:00
Markus Armbruster
ab76bc2794 docs/devel/qapi-code-gen: Rewrite compatibility considerations
We have some compatibility advice buried in sections "Enumeration
types" and "Struct types".  Compatibility is actually about commands
and events.  It devolves to the types used there.  All kinds of types,
not just enumerations and structs.

Replace the existing advice by a new section "Compatibility
considerations".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-14-armbru@redhat.com>
[Squash in paragraph on invisible schema changes, as per Eric's review]
2019-09-24 14:07:22 +02:00
Markus Armbruster
f5821f5262 docs/devel/qapi-code-gen: Reorder sections for readability
Section "QMP/Guest agent schema" starts with a brief introduction,
then subsection "Comments", then subsection "Schema overview" (more
elaborate introduction), and only then talks about schema entities
like types, commands, and so forth.

Subsection "Comments" is long and tiring: almost 500 words, mostly
about doc comments.  Move the doc comment part to its own subsection
"Documentation comments" at the very end of "QMP/Guest agent schema".

Subsection "Schema overview" explains naming rules at considerable
length: 250 words.  Move this part to its own subsection "Naming rules
and reserved names" right after the subsections on schema entities.

Subsection "Enumeration types" is wedged between "Struct types" and
"Union types".  Move it before "Struct types".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-13-armbru@redhat.com>
2019-09-24 14:07:22 +02:00
Markus Armbruster
0ced9531f1 qapi: Permit omitting all flat union branches
Absent flat union branches default to the empty struct (since commit
800877bb16 "qapi: allow empty branches in flat unions").  But an
attempt to omit all of them is rejected with "Union 'FOO' has no
branches".  Harmless oddity, but it's easy to avoid, so do that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-11-armbru@redhat.com>
[Commit message typo fixed]
2019-09-24 14:07:22 +02:00
Markus Armbruster
e24fe238e2 docs/devel/qapi-code-gen: Minor specification fixes
The specification claims "Each expression that isn't an include
directive may be preceded by a documentation block", but the code also
rejects them for pragma directives.  The code is correct.  Fix the
specification.

The specification reserves member names starting with 'has_', but the
code also reserves name 'u'.  Fix the specification.

The specification claims "The string 'max' is not allowed as an enum
value".  Untrue.  Fix the specification.  While there, delete the
naming advice, because it's redundant with the naming rules in section
"Schema overview"

The specification claims "No branch of the union can be named 'max',
as this would collide with the implicit enum".  Untrue.  Fix the
specification.

The specification claims "It is not allowed to name an event 'MAX',
since the generator also produces a C enumeration of all event names
with a generated _MAX value at the end."  Untrue.  Fix the
specification.

The specification claims "All branches of the union must be complex
types", but the code permits only struct types.  The code is correct.
Fix the specification.

The specification claims a command's return type "must be the string
name of a complex or built-in type, a one-element array containing the
name of a complex or built-in type" unless the command is in pragma
'returns-whitelist'.  The code does not permit built-in types.  Fix
the specification.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190913201349.24332-5-armbru@redhat.com>
2019-09-24 14:07:22 +02:00