The new QAPI code generator creates a cross-reference target for each
definition documentation. Enabled for the QEMU QMP Reference manual
in commit a377f39f38, and for the QEMU Storage Daemon QMP Reference
Manual and the QEMU Guest Agent Protocol Reference in commit
a6af544344. We've put these targets to use since, but neglected to
update doc comment markup documentation. Do that now.
Co-developed-by: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250731054044.4011789-4-armbru@redhat.com>
documentation and test cleanups
- improve clarity of user-mode docs
- remove reference to TAP tarball
- add new hypervisor test for aarch64 EL2
- reduce combinatorial explosion of plugin tests
- make docker-all-test-cross more friendly to non-x86 hosts
- expose unittests to sysv.args for embedded help
# -----BEGIN PGP SIGNATURE-----
#
# iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmiFUdoACgkQ+9DbCVqe
# KkQn+Af/RpTh4XmIcqiLvXrygLWo8hSELS0gjIRZgAA8QyBmojZ+e13los3pzm2Z
# WWlQhh4T0OHgMtZCPPrP+XUc/QDgV3Pt41C1O6SWRwqD4v/7oWNNZz+pFra7x160
# CLBJfcVuRKdFzuR1NZldR8LJufmAMnPnBwE+cV9SpBlGe/lvcLPPvjF0eXQnW1yP
# fWmNgf7VnLBPEQ3NQkliZ23Ku6p4yWDfJLfqgUAXe57Eom1PpDEaPlc+5UaYtAKs
# ee6Gk5CqVFUhIj0v50qBn1giLyaqaXyGn9yWiwiNDL/qVV1v+DK7LNt5B0bTXCfd
# X1KTwpJJdbzmcDftrAq+oacaeXryIA==
# =Sxa/
# -----END PGP SIGNATURE-----
# gpg: Signature made Sat 26 Jul 2025 18:08:26 EDT
# gpg: using RSA key 6685AE99E75167BCAFC8DF35FBD0DB095A9E2A44
# gpg: Good signature from "Alex Bennée (Master Work Key) <alex.bennee@linaro.org>" [unknown]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 6685 AE99 E751 67BC AFC8 DF35 FBD0 DB09 5A9E 2A44
* tag 'pull-10.1-rc1-maintainer-260725-1' of https://gitlab.com/stsquad/qemu:
tests/functional: expose sys.argv to unittest.main
tests/docker: handle host-arch selection for all-test-cross
tests/docker: add --arch-only to qemu deps for all-test-cross
tests/tcg: reduce the number of plugin tests combinations
configure: expose PYTHON to test/tcg/config-host.mak
tests/tcg: don't include multiarch tests if not supported
tests/tcg: remove ADDITIONAL_PLUGINS_TESTS
tests/tcg: skip libsyscall.so on softmmu tests
tests/functional: add hypervisor test for aarch64
docs/user: expand section on threading
docs/user: slightly reword section on system calls
docs/user: clean up headings
docs/system: reword the TAP notes to remove tarball ref
docs/user: clarify user-mode expects the same OS
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Some distros prefer to avoid vendored crate sources, and instead use
local sources from e.g. ``/usr/share/cargo/registry``. Add a
script, inspired by the Mesa spec file(*), that automatically
performs this task. The script is meant to be invoked after unpacking
the QEMU tarball.
(*) This is the hack that Mesa uses:
export MESON_PACKAGE_CACHE_DIR="%{cargo_registry}/"
%define inst_crate_nameversion() %(basename %{cargo_registry}/%{1}-*)
%define rewrite_wrap_file() sed -e "/source.*/d" -e "s/%{1}-.*/%{inst_crate_nameversion %{1}}/" -i subprojects/%{1}.wrap
%rewrite_wrap_file proc-macro2
... more %rewrite_wrap_file invocations follow ...
Reviewed-by: Neal Gompa <ngompa@fedoraproject.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
sphinx 5.3.0 fails with Python 3.13.1:
../docs/meson.build:37: WARNING: /home/me/qemu/build/pyvenv/bin/sphinx-build:
Extension error:
Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr')
../docs/meson.build:39:6: ERROR: Problem encountered: Install a Python 3 version of python-sphinx and the readthedoc theme
Bump sphinx to 6.2.1 and also sphinx_rtd_theme as required for the new
sphinx version.
(jsnow note: this patch bumps the recommended version for Sphinx to
install when it is missing, but allows old versions to be used if they
are present and functional. The version used for building docs on
readthedocs is pinned to the recommended version, 6.2.1.)
Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com>
Tested-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250715212848.171879-2-jsnow@redhat.com>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add missing long options and --help output,
reorder options for consistency.
Use -B for --backing-format, keep -F for
backwards compatibility.
Options added:
--format, --cache - for the image in question
--backing, --backing-format, --backing-cache, --backing-unsafe -
for the new backing file
(was eg CACHE vs SRC_CACHE, which is unclear).
Probably should rename local variables.
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
Message-ID: <20250531171609.197078-19-mjt@tls.msk.ru>
[kwolf: Removed command description from the argument list]
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
When no -l/-a/-c/-d specified, assume -l (list).
Use the same values for SNAPSHOT_LIST/etc constants as the
option chars (lacd), this makes it possible to simplify
option handling a lot, combining cases for 4 options into
one.
Also remove bdrv_oflags handling (only list can use RO mode).
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-ID: <20250531171609.197078-17-mjt@tls.msk.ru>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Add missing long options and --help output.
Reorder options for consistency.
Use -b for --backing, and recognize -B for backwards
compatibility. Unfortunately we can't use -B to
specify backing format.
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
Message-ID: <20250715140702.131321-1-mjt@tls.msk.ru>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Create helper function cmd_help() to display command-specific
help text, and use it to print --help for 'create' subcommand.
Add missing long options (eg --format) in img_create().
Recognize -B option for --backing-format, keep -F for
backward compatibility,
Reorder options for consistency.
Remove usage of missing_argument()/unrecognized_option() in
img_create().
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
Message-ID: <20250531171609.197078-6-mjt@tls.msk.ru>
Reviewed-by: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Kevin Wolf <kwolf@redhat.com>
Allow capping the maximum total size of in-flight VFIO device state buffers
queued at the destination, otherwise a malicious QEMU source could
theoretically cause the target QEMU to allocate unlimited amounts of memory
for buffers-in-flight.
Since this is not expected to be a realistic threat in most of VFIO live
migration use cases and the right value depends on the particular setup
disable this limit by default by setting it to UINT64_MAX.
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Reviewed-by: Avihai Horon <avihaih@nvidia.com>
Signed-off-by: Maciej S. Szmigiero <maciej.szmigiero@oracle.com>
Link: https://lore.kernel.org/qemu-devel/4f7cad490988288f58e36b162d7a888ed7e7fd17.1752589295.git.maciej.szmigiero@oracle.com
Signed-off-by: Cédric Le Goater <clg@redhat.com>
maintainer updates (gitlab, plugins, gdbstub, docs)
- update check-units script to take -n <top> argument
- fix execlog plugin to handle tab separators
- add gdb XML file for alpha
- add gdb XML file for sparc64
- use :kbd: in docs to highlight key sequences
- clean up rst formatting in virtio-net-failover docs
# -----BEGIN PGP SIGNATURE-----
#
# iQEzBAABCgAdFiEEZoWumedRZ7yvyN81+9DbCVqeKkQFAmh0374ACgkQ+9DbCVqe
# KkR0gQf/a9Au455+OWEhG3uLGkMZZaFM6QJv8W3wBBZoRg59LMXkUIhEtyVfdmt5
# SDyA79nw1G0iP2qlKQV02R++CrBHMJILtYOMoLTbkWV9Lft4h+uPC27SE17DkNPS
# 4b4TchlJ3DpOFi0XmYZuIwH/8CPpTdVCLcA5zEXT0Q8nKjk0JsGiOQxoHH+p3ad5
# +mgvlmITDpU88OCilDYgmrD5iSe/WLzwszV9D6JTfQakfM7J9G87sj4iMK+En+iu
# 0rsRBk2gwahy4cfqaiaELTtarqadM1TaNwaRvt6vun+Hp12pypDhogG1Mh5e2eCB
# /nFwjcswRRk+kd26993AiK8Soomwiw==
# =Md3/
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 14 Jul 2025 06:45:18 EDT
# gpg: using RSA key 6685AE99E75167BCAFC8DF35FBD0DB095A9E2A44
# gpg: Good signature from "Alex Bennée (Master Work Key) <alex.bennee@linaro.org>" [unknown]
# gpg: WARNING: This key is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 6685 AE99 E751 67BC AFC8 DF35 FBD0 DB09 5A9E 2A44
* tag 'pull-10.1-rc0-maintainer-140725-1' of https://gitlab.com/stsquad/qemu:
gdbstub: add the GDB register XML files for sparc64.
docs/system: clean-up formatting of virtio-net-failover
docs: use :kbd: role in sphinx docs
plugins: fix inclusion of user-mode APIs
target/alpha: Add GDB XML feature file
contrib/plugins/execlog: Add tab to the separator search of insn_disas
gitlab: add -n option to check-units script
gitlab: use argparse in check-units script
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
* rust: miscellaneous fixes
* rust: qemu-api-macros: cleanup and add unit tests for TryInto
* rust: log: implement io::Write, avoid memory allocations
when logging constant strings
* target/i386: fix usage of properties whenever accelerators
change the default (e.g. vendor)
* target/i386: add support for TDVMCALL_SETUP_EVENT_NOTIFY_INTERRUPT
* target/i386: add support for booting an SEV VM from an IGVM file
* target/i386: unify cache model descriptions between CPUID 2,
CPUID 4 and AMD specific CPUID 0x80000006
* target/i386: introduce cache models for recent Intel CPU models
* target/i386: mark some 0x80000000-0x80000008 bits as reserved on Intel
* target/i386: cleanups
# -----BEGIN PGP SIGNATURE-----
#
# iQFIBAABCgAyFiEE8TM4V0tmI4mGbHaCv/vSX3jHroMFAmh0v+sUHHBib256aW5p
# QHJlZGhhdC5jb20ACgkQv/vSX3jHroOQUQf8CTsCnl2xYrnrkVfSVj6kuAE+JYD6
# oLSXsOEG4yrVknuhwIfVsqNScmleJCdz85ej7CZxy3vzzgjLfmy7nwifKEIKku7E
# XO/Q3HbB898MnzqceQRmwe1AzELoj1Lave215CPhUBo60LCRPwaIZsiHprnNZgXi
# TyHlmywDVRjyFLtKkx3El0dnLAhFqPWeGh81CD5lPLZZJ+Wt2FuAw2zqSOGB2ztM
# FkJmunFJiaTItjyCN/uNvBSbDKecAHgCXvSCVNG3+I4U2R0gK1lcwm3TRo7yKia+
# HUHGa3UEXoIqlRfXdX6zuc8tW1/u6SPv+8WX53t204PAeSWDUrtIe9jZ4A==
# =y4/a
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 14 Jul 2025 04:29:31 EDT
# gpg: using RSA key F13338574B662389866C7682BFFBD25F78C7AE83
# gpg: issuer "pbonzini@redhat.com"
# 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
* tag 'for-upstream' of https://gitlab.com/bonzini/qemu: (77 commits)
i386/cpu: Honor maximum value for CPUID.8000001DH.EAX[25:14]
i386/cpu: Fix overflow of cache topology fields in CPUID.04H
i386/cpu: Fix cpu number overflow in CPUID.01H.EBX[23:16]
i386/cpu: Fix number of addressable IDs field for CPUID.01H.EBX[23:16]
i386/cpu: Reorder CPUID leaves in cpu_x86_cpuid()
tests/vm: bump FreeBSD image to 14.3
tests/functional: test_x86_cpu_model_versions: remove dead tests
i386/cpu: Mark CPUID 0x80000008 ECX bits[0:7] & [12:15] as reserved for Intel/Zhaoxin
i386/cpu: Mark CPUID 0x80000007[EBX] as reserved for Intel
i386/cpu: Mark EBX/ECX/EDX in CPUID 0x80000000 leaf as reserved for Intel
i386/cpu: Enable 0x1f leaf for YongFeng by default
i386/cpu: Enable 0x1f leaf for SapphireRapids by default
i386/cpu: Enable 0x1f leaf for GraniteRapids by default
i386/cpu: Enable 0x1f leaf for SierraForest by default
i386/cpu: Enable 0x1f leaf for SierraForest by default
i386/cpu: Add a "x-force-cpuid-0x1f" property
i386/cpu: Introduce cache model for YongFeng
i386/cpu: Introduce cache model for SapphireRapids
i386/cpu: Introduce cache model for GraniteRapids
i386/cpu: Introduce cache model for SierraForest
...
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
We didn't clean-up the rst formatting when we moved this into the
docs so lets do that now:
- un-indent the usage/hotplug/migration paragraphs
- properly wrap the command line fragments in code-block
- highlight parameters in text with ``double quotes``
No changes to the actual text.
Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
Message-ID: <20250710104531.3099313-8-alex.bennee@linaro.org>
Generated command documentation lacks information on return value in
several cases, e.g. query-tpm.
The obvious fix would be to require a Returns: section when a command
returns something.
However, note that many existing Returns: sections are pretty useless:
the description is basically the return type, which then gets rendered
like "Return: <Type> – <basically the return type>". This suggests
that a description is often not really necessary, and requiring one
isn't useful.
Instead, generate the obvious minimal thing when Returns: is absent:
"Return: <Type>".
This auto-generated Return documentation is placed is as follows:
1. If we have arguments, return goes right after them.
2. Else if we have errors, return goes right before them.
3. Else if we have features, return goes right before them.
4. Else return goes right after the intro
To facilitate this algorithm, a "TODO:" hack line is used to separate
the intro from the remainder of the documentation block in cases where
there are no other sections to separate the intro from e.g. examples and
additional detail meant to appear below the key sections of interest.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-3-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[_insert_near_kind() code replaced by something simpler, commit
message amended to explain why we're doing this]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This form is used to annotate a return type without an accompanying
description, for when there is no "Returns:" information in the source
doc, but we have a return type we want to generate a cross-reference to.
The syntax is:
:return-nodesc: TypeName
It's primarily necessary because Sphinx always expects both a type and a
description for the prior form and will format it accordingly. To have a
reasonable rendering when the body is missing, we need to use a
different info field list entirely.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-2-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
[Long line wrapped]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Remove the QAPI doc section heading syntax, use plain rST section
headings instead.
Tests and documentation are updated to match.
Interestingly, Plain rST headings work fine before this patch, except
for over- and underlining with '=', which the doc parser rejected as
invalid QAPI doc section heading in free-form comments.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-5-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Add more detail to commit message]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Thanks for your service!
Remove the old qapidoc and the option to enable the transmogrifier,
leaving the "transmogrifier" as the ONLY qapi doc generator. This in
effect also converts the QAPI test to use the new documentation
generator, too.
Update doc-good.txt output to match the new doc generator, which I
should've done exactly when we switched over to the transmogrifier, but,
uhh, oops!
Notes on the new format:
1. per-member IFCOND documentation is missing. Known issue.
2. Freeform documentation without a header is now copied through into
the output. This is a bug fix.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-4-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Fixes: b61a4eb3f3 (docs/qapidoc: support header-less freeform sections)
[Tweak commit message to say it's a bug fix, add Fixes:]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Oversight in the new qapidoc transmogrifier: @references in freeform
documentation blocks were not being transformed to literals. This fixes
that, and the next patch ensures that we're testing for this O:-)
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-3-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Without this, the line the new QAPI doc generator chokes on
# Errors: some
in doc-good.json. We still use the old doc generator for the tests,
but we're about to correct that.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250618165353.1980365-2-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Fixes: e9fbf1a0c6 (docs/qapidoc: add visit_errors() method)
[Amend commit message to point to reproducer, and add Fixes:]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit adds support for the vhost-user interface to the passt
network backend, enabling high-performance, accelerated networking for
guests using passt.
The passt backend can now operate in a vhost-user mode, where it
communicates with the guest's virtio-net device over a socket pair
using the vhost-user protocol. This offloads the datapath from the
main QEMU loop, significantly improving network performance.
When the vhost-user=on option is used with -netdev passt, the new
vhost initialization path is taken instead of the standard
stream-based connection.
Signed-off-by: Laurent Vivier <lvivier@redhat.com>
Signed-off-by: Jason Wang <jasowang@redhat.com>
This commit introduces support for passt as a new network backend.
passt is an unprivileged, user-mode networking solution that provides
connectivity for virtual machines by launching an external helper process.
The implementation reuses the generic stream data handling logic. It
launches the passt binary using GSubprocess, passing it a file
descriptor from a socketpair() for communication. QEMU connects to
the other end of the socket pair to establish the network data stream.
The PID of the passt daemon is tracked via a temporary file to
ensure it is terminated when QEMU exits.
Signed-off-by: Laurent Vivier <lvivier@redhat.com>
Signed-off-by: Jason Wang <jasowang@redhat.com>
checkpatch now checks that new files have an SPDX line. If you use the
shell rune in tracing.rst to create a trace.h wrapper header, this
triggers checkpatch to complain.
Although these files are tiny, it's worth having the SPDX line to
avoid having to add extra exception cases to checkpatch.
Update the rune to include creating an SPDX line.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Michael Tokarev <mjt@tls.msk.ru>
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
According to our "Supported build platforms" policy, RHEL 7 is not
supported anymore, so let's remove the related sentence from the x86
documentation.
Signed-off-by: Thomas Huth <thuth@redhat.com>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Reviewed-by: Michael Tokarev <mjt@tls.msk.ru>
Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
Now after merging the precopy and postcopy version of complete() hook,
rename the precopy version from save_live_complete_precopy() to
save_complete().
Dropping the "live" when at it, because it's in most cases not live when
happening (in precopy).
No functional change intended.
Reviewed-by: Juraj Marcin <jmarcin@redhat.com>
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Link: https://lore.kernel.org/r/20250613140801.474264-7-peterx@redhat.com
[peterx: squash the fixup that covers a few more doc spots, per Juraj]
Signed-off-by: Peter Xu <peterx@redhat.com>
Signed-off-by: Fabiano Rosas <farosas@suse.de>
