docs: (further) remove non-reference uses of single backticks

The series rotted already. Here's the new changes.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Damien Hedde <damien.hedde@

docs: (further) remove non-reference uses of single backticks

The series rotted already. Here's the new changes.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Damien Hedde <damien.hedde@greensocs.com>
[ extra backticks fixes ]
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20211004215238.1523082-3-jsnow@redhat.com>

show more ...

docs: remove non-reference uses of single backticks

The single backtick markup in ReST is the "default role". Currently,
Sphinx's default role is called "content". Sphinx suggests you can use
the "A

docs: remove non-reference uses of single backticks

The single backtick markup in ReST is the "default role". Currently,
Sphinx's default role is called "content". Sphinx suggests you can use
the "Any" role instead to turn any single-backtick enclosed item into a
cross-reference.

This is useful for things like autodoc for Python docstrings, where it's
often nicer to reference other types with `foo` instead of the more
laborious :py:meth:`foo`. It's also useful in multi-domain cases to
easily reference definitions from other Sphinx domains, such as
referencing C code definitions from outside of kerneldoc comments.

Before we do that, though, we'll need to turn all existing usages of the
"content" role to inline verbatim markup wherever it does not correctly
resolve into a cross-refernece by using double backticks instead.

Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Alexander Bulekov <alxndr@bu.edu>
Message-Id: <20211004215238.1523082-2-jsnow@redhat.com>

show more ...

docs/tcg-plugins: add L2 arguments to cache docs

cache plugin now allows optional L2 per-core cache emulation that can be
configured through plugin arguments, this commit adds this functionality
to

docs/tcg-plugins: add L2 arguments to cache docs

cache plugin now allows optional L2 per-core cache emulation that can be
configured through plugin arguments, this commit adds this functionality
to the docs.

While I'm at it, I editted the bullet point for cache plugin to say:
contrib/plugins/cache.c
instead of
contrib/plugins/cache
to match other plugins.

Signed-off-by: Mahmoud Mandour <ma.mandourr@gmail.com>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-Id: <20210810134844.166490-6-ma.mandourr@gmail.com>
Message-Id: <20211026102234.3961636-18-alex.bennee@linaro.org>

show more ...

docs/devel: document expectations for HMP commands in the future

We no longer wish to have commands implemented in HMP only. All commands
should start with a QMP implementation and the HMP merely be

docs/devel: document expectations for HMP commands in the future

We no longer wish to have commands implemented in HMP only. All commands
should start with a QMP implementation and the HMP merely be a shim
around this. To reduce the burden of implementing QMP commands where
there is low expectation of machine usage, requirements for QAPI
modelling are relaxed provided the command is under the "x-" name
prefix.

Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: add example of command returning unstructured text

This illustrates how to add a QMP command returning unstructured text,
following the guidelines added in the previous patch. The exampl

docs/devel: add example of command returning unstructured text

This illustrates how to add a QMP command returning unstructured text,
following the guidelines added in the previous patch. The example uses
a simplified version of 'info roms'.

Reviewed-by: Eric Blake <eblake@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: document expectations for QAPI data modelling for QMP

Traditionally we have required that newly added QMP commands will model
any returned data using fine grained QAPI types. This is goo

docs/devel: document expectations for QAPI data modelling for QMP

Traditionally we have required that newly added QMP commands will model
any returned data using fine grained QAPI types. This is good for
commands that are intended to be consumed by machines, where clear data
representation is very important. Commands that don't satisfy this have
generally been added to HMP only.

In effect the decision of whether to add a new command to QMP vs HMP has
been used as a proxy for the decision of whether the cost of designing a
fine grained QAPI type is justified by the potential benefits.

As a result the commands present in QMP and HMP are non-overlapping
sets, although HMP comamnds can be accessed indirectly via the QMP
command 'human-monitor-command'.

One of the downsides of 'human-monitor-command' is that the QEMU monitor
APIs remain tied into various internal parts of the QEMU code. For
example any exclusively HMP command will need to use 'monitor_printf'
to get data out. It would be desirable to be able to fully isolate the
monitor implementation from QEMU internals, however, this is only
possible if all commands are exclusively based on QAPI with direct
QMP exposure.

The way to achieve this desired end goal is to finese the requirements
for QMP command design. For cases where the output of a command is only
intended for human consumption, it is reasonable to want to simplify
the implementation by returning a plain string containing formatted
data instead of designing a fine grained QAPI data type. This can be
permitted if-and-only-if the command is exposed under the 'x-' name
prefix. This indicates that the command data format is liable to
future change and that it is not following QAPI design best practice.

The poster child example for this would be the 'info registers' HMP
command which returns printf formatted data representing CPU state.
This information varies enourmously across target architectures and
changes relatively frequently as new CPU features are implemented.
It is there as debugging data for human operators, and any machine
usage would treat it as an opaque blob. It is thus reasonable to
expose this in QMP as 'x-query-registers' returning a 'str' field.

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: update error handling guidance for HMP commands

Best practice is to use the 'hmp_handle_error' function, not
'monitor_printf' or 'error_report_err'. This ensures that the
message always

docs/devel: update error handling guidance for HMP commands

Best practice is to use the 'hmp_handle_error' function, not
'monitor_printf' or 'error_report_err'. This ensures that the
message always gets an 'Error: ' prefix, distinguishing it
from normal command output.

Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: tweak headings in monitor command docs

The new headings reflect the intended structure of the document and will
better suit additions that follow.

Reviewed-by: Markus Armbruster <armbru

docs/devel: tweak headings in monitor command docs

The new headings reflect the intended structure of the document and will
better suit additions that follow.

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

docs/devel: rename file for writing monitor commands

The file already covers writing HMP commands, in addition to
the QMP commands, so it deserves a more general name.

Reviewed-by: Eric Blake <ebla

docs/devel: rename file for writing monitor commands

The file already covers writing HMP commands, in addition to
the QMP commands, so it deserves a more general name.

Reviewed-by: Eric Blake <eblake@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

show more ...

qapi: New special feature flag "unstable"

By convention, names starting with "x-" are experimental. The parts
of external interfaces so named may be withdrawn or changed
incompatibly in future rele

qapi: New special feature flag "unstable"

By convention, names starting with "x-" are experimental. The parts
of external interfaces so named may be withdrawn or changed
incompatibly in future releases.

The naming convention makes unstable interfaces easy to recognize.
Promoting something from experimental to stable involves a name
change. Client code needs to be updated. Occasionally bothersome.

Worse, the convention is not universally observed:

* QOM type "input-barrier" has properties "x-origin", "y-origin".
Looks accidental, but it's ABI since 4.2.

* QOM types "memory-backend-file", "memory-backend-memfd",
"memory-backend-ram", and "memory-backend-epc" have a property
"x-use-canonical-path-for-ramblock-id" that is documented to be
stable despite its name.

We could document these exceptions, but documentation helps only
humans. We want to recognize "unstable" in code, like "deprecated".

So support recognizing it the same way: introduce new special feature
flag "unstable". It will be treated specially by the QAPI generator,
like the existing feature flag "deprecated", and unlike regular
feature flags.

This commit updates documentation and prepares tests. The next commit
updates the QAPI schema. The remaining patches update the QAPI
generator and wire up -compat policy checking.

Management applications can then use query-qmp-schema and -compat to
manage or guard against use of unstable interfaces the same way as for
deprecated interfaces.

docs/devel/qapi-code-gen.txt no longer mandates the naming convention.
Using it anyway might help writers of programs that aren't
full-fledged management applications. Not using it can save us
bothersome renames. We'll see how that shakes out.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Message-Id: <20211028102520.747396-2-armbru@redhat.com>

show more ...

qapi: Add feature flags to enum members

This is quite similar to commit 84ab008687 "qapi: Add feature flags to
struct members", only for enums instead of structs.

Special feature flag 'deprecated'

qapi: Add feature flags to enum members

This is quite similar to commit 84ab008687 "qapi: Add feature flags to
struct members", only for enums instead of structs.

Special feature flag 'deprecated' is silently ignored there. This is
okay only because it will be implemented shortly.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20211025042405.3762351-3-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>

show more ...

qapi: Enable enum member introspection to show more than name

The next commit will add feature flags to enum members. There's a
problem, though: query-qmp-schema shows an enum type's members as an

qapi: Enable enum member introspection to show more than name

The next commit will add feature flags to enum members. There's a
problem, though: query-qmp-schema shows an enum type's members as an
array of member names (SchemaInfoEnum member @values). If it showed
an array of objects with a name member, we could simply add more
members to these objects. Since it's just strings, we can't.

I can see three ways to correct this design mistake:

1. Do it the way we should have done it, plus compatibility goo.

We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum. Since
changing @values would be a compatibility break, add a new member
@members instead.

@values is now redundant. In my testing, output of
qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB).

We can deprecate @values now and drop it later. This will break
outmoded clients. Well-behaved clients such as libvirt are
expected to break cleanly.

2. Like 1, but omit "boring" elements of @member, and empty @member.

@values does not become redundant. @members augments it. Somewhat
cumbersome, but output of query-qmp-schema grows only as we make
enum members non-boring.

There is nothing to deprecate here.

3. Versioned query-qmp-schema.

query-qmp-schema provides either @values or @members. The QMP
client can select which version it wants. There is no redundant
output.

We can deprecate old versions and eventually drop them. This will
break outmoded clients. Breaking cleanly is easier than for 1.

While 1 and 2 operate within the common rules for compatible
evolution apply (section "Compatibility considerations" in
docs/devel/qapi-code-gen.rst), 3 bypasses them. Attractive when
operating within the rules is just too awkward. Not the case here.

This commit implements 1. Libvirt developers prefer it.

Deprecate @values in favour of @members. Since query-qmp-schema
compatibility is pretty fundamental for management applications, an
extended grace period is advised.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Tested-by: Peter Krempa <pkrempa@redhat.com>
Acked-by: Peter Krempa <pkrempa@redhat.com>
Message-Id: <20211025042405.3762351-2-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>

show more ...

configure: automatically parse command line for meson -D options

Right now meson_options.txt lists about 90 options. Each option
needs code in configure to parse it and pass the option down to Meso

configure: automatically parse command line for meson -D options

Right now meson_options.txt lists about 90 options. Each option
needs code in configure to parse it and pass the option down to Meson as
a -D command-line argument; in addition the default must be duplicated
between configure and meson_options.txt. This series tries to remove
the code duplication by generating the case statement for those --enable
and --disable options, as well as the corresponding help text.

About 80% of the options can be handled completely by the new mechanism.
Eight meson options are not of the --enable/--disable kind. Six more need
to be parsed in configure for various reasons documented in the patch,
but they still have their help automatically generated.

The advantages are:

- less code in configure

- parsing and help is more consistent (for example --enable-blobs was
not supported)

- options are described entirely in one place, meson_options.txt.
This make it more attractive to use Meson options instead of
hand-crafted configure options and config-host.mak

A few options change name: --enable-tcmalloc and --enable-jemalloc
become --enable-malloc={tcmalloc,jemalloc}; --disable-blobs becomes
--disable-install-blobs; --enable-trace-backend becomes
--enable-trace-backends. However, the old names are allowed
for backwards compatibility.

Message-Id: <20211007130829.632254-19-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

show more ...

accel/tcg: Add cpu_{ld,st}*_mmu interfaces

These functions are much closer to the softmmu helper
functions, in that they take the complete MemOpIdx,
and from that they may enforce required alignment

accel/tcg: Add cpu_{ld,st}*_mmu interfaces

These functions are much closer to the softmmu helper
functions, in that they take the complete MemOpIdx,
and from that they may enforce required alignment.

The previous cpu_ldst.h functions did not have alignment info,
and so did not enforce it. Retain this by adding MO_UNALN to
the MemOp that we create in calling the new functions.

Note that we are not yet enforcing alignment for user-only,
but we now have the information with which to do so.

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

show more ...

docs: reorganize testing.rst

Clean up the heading levels to use === --- ~~~ ^^^ '''. Reorganize the
outline for the Avocado part, and always include headings for the
class names.

Signed-off-by: Pa

docs: reorganize testing.rst

Clean up the heading levels to use === --- ~~~ ^^^ '''. Reorganize the
outline for the Avocado part, and always include headings for the
class names.

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

show more ...

docs: move gcov section at the end of testing.rst

gcov testing applies to all tests, not just make check. Move it
out of the make check section.

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

docs: reorganize tcg-plugins.rst

Clean up the heading levels to use === --- ~~~, and create a new "writing
plugins" section.

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

docs: reorganize qgraph.rst

Clean up the heading levels to use === --- ~~~, and move the command line
building near to the other execution steps.

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

docs: put "make" information together in build-system.rst

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

docs: move notes inside the body of the document

Make all documents start with a heading.

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

docs: name included files ".rst.inc"

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

tests/Makefile: add AVOCADO_TESTS option to make check-acceptance

Add the possibility of running all the tests from a single file, or
multiple files, running a single test within a file or multiple

tests/Makefile: add AVOCADO_TESTS option to make check-acceptance

Add the possibility of running all the tests from a single file, or
multiple files, running a single test within a file or multiple tests
within multiple files using `make check-acceptance` and the
AVOCADO_TESTS environment variable.

Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Willian Rampazzo <willianr@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20210923161141.232208-4-willianr@redhat.com>

show more ...

docs/devel/testing: add instruction to run a single acceptance test

Add instructions to the Acceptance tests section about running a
single test file or a test within the test file.

Signed-off-by:

docs/devel/testing: add instruction to run a single acceptance test

Add instructions to the Acceptance tests section about running a
single test file or a test within the test file.

Signed-off-by: Willian Rampazzo <willianr@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20210923161141.232208-3-willianr@redhat.com>

show more ...

tests/Makefile: allow control over tags during check-acceptance

Although it is possible to run a specific test using the avocado
command-line, a user may want to use a specific tag while running the

tests/Makefile: allow control over tags during check-acceptance

Although it is possible to run a specific test using the avocado
command-line, a user may want to use a specific tag while running the
``make check-acceptance`` during the development or debugging.

This allows using the AVOCADO_TAGS environment variable where the user
takes total control of which tests should run based on the tags defined.

This also makes the check-acceptance command flexible to restrict tests
based on tags while running on CI.

e.g.:

AVOCADO_TAGS="foo bar baz" make check-acceptance

Signed-off-by: Willian Rampazzo <willianr@redhat.com>
Tested-by: Wainer dos Santos Moschetta <wainersm@redhat.com>
Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20210923161141.232208-2-willianr@redhat.com>

show more ...

qapi: Drop simple unions

Simple unions predate flat unions. Having both complicates the QAPI
schema language and the QAPI generator. We haven't been using simple
unions in new code for a long time

qapi: Drop simple unions

Simple unions predate flat unions. Having both complicates the QAPI
schema language and the QAPI generator. We haven't been using simple
unions in new code for a long time, because they are less flexible and
somewhat awkward on the wire.

The previous commits eliminated simple union from the tree. Now drop
them from the QAPI schema language entirely, and update mentions of
"flat union" to just "union".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20210917143134.412106-22-armbru@redhat.com>

show more ...