This wasn't run because the automatic trigger is fickle. We don't want
to expose all the tcg-test-cross-cc options to help as we already have
processing via --cross-cc-ARCH so we tweak the CONFIGURE_HELP filter
in the update script.
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Message-ID: <20260917185322.3457036-1-alex.bennee@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
- Fix minor issues in next-cube machine and mark it as deprecated
- Add a configure option to disable tests
- Remove stamp files when deleting assets from the functional cache
- Make sure that pyling version is not too old
- Keep USB autoscan enabled for bus+addr selector
# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEEJ7iIR+7gJQEY8+q5LtnXdP5wLbUFAmqilnUSHHRoLmh1dGhA
# cG9zdGVvLmV1AAoJEC7Z13T+cC21GtYP/2JRtwlyJdiyl5TVRtiWE38Ezu0pzXDi
# Snz+/KK3nIDIs6EJvg2rSHyfpE+0+iHT9brzAks4g/jEbsywOeTtn/HPP1PzCB58
# Sjy68IyVFh7TaEg9R5dEuHQYE1D4sJnQlCinMMMXWfxw/rArsdkMWxl1onwQKOOt
# Te1NsvCb16dC7ItT/VcpQB71TChIEYoJXHC/FZ2jhzDc+Th8l4rkWKAR1x8QljtR
# h8Z+7xuE00cRxTUALEnmxqP7oYk/2tE2ZOe/wSByvm2umBUR4/DQD6iKKmX4Qew+
# rHQbAaWBqVDK2L69f/1B9v43XPhRykZRe3E58LNfCvM39xG6VaRd1UHdg1X1IiiL
# aHV20Y27oaOVub3zPsiJKiOAghQsq6Dg3dgWQQRStJv5XZEyeMiFjjk+oOoQ3UBd
# +0pyzrOhobNQcYOvz6RJMehby/Oc8qzQinShrQnh6CjPtAObxx5Mq48PZicbAEGj
# xrgH4vSfchm4p7YhVJ1zj4aIEx4r23XChhhszzDnchjuWcl/1r7Khw0ZTlITupXL
# yj/v9sJKRghoG3Ie7WlYXocbdmOn8WE53Cb13XHwwFPryB6gMlG4IR5Jf5eMM8w4
# Tdp1hMw4WXLZ4AEE+XM44932lkrfgcssG0Odt5ECQjhlBWuSwe9mXIia5++X6H8w
# +b0Ed+6xrP8q
# =jcK+
# -----END PGP SIGNATURE-----
# gpg: Signature made Thu 10 Sep 2026 01:37:25 AM HST
# gpg: using RSA key 27B88847EEE0250118F3EAB92ED9D774FE702DB5
# gpg: issuer "th.huth@posteo.eu"
# gpg: Good signature from "Thomas Huth <th.huth@gmx.de>" [unknown]
# gpg: aka "Thomas Huth <thuth@redhat.com>" [unknown]
# gpg: aka "Thomas Huth <th.huth@posteo.de>" [unknown]
# gpg: aka "Thomas Huth <huth@tuxfamily.org>" [unknown]
# gpg: aka "Thomas Huth <th.huth@posteo.eu>" [unknown]
# gpg: WARNING: The key's User ID is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 27B8 8847 EEE0 2501 18F3 EAB9 2ED9 D774 FE70 2DB5
* tag 'pull-request-2026-09-10' of https://gitlab.com/huth/qemu:
hw/usb/host-libusb: keep autoscan enabled for bus+addr selector
Add option to disable building tests
tests: install pylint for functional linters
scripts/clean_functional_cache: Remove also .stamp files
MAINTAINERS: Mark the next-cube machine as "Orphan"
docs/about: Deprecate the 'next-cube' m68k machine
hw/m68k/next-cube: Replace assert()s and abort()s with logging functions
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
There are situations in which you might want to build QEMU without
building the full test suite, which in some configurations can take a
considerable amount of time to build. This is especially true when using
LTO with clang. For example:
$ ../configure --cc=clang '--extra-ldflags=-flto=thin -ffat-lto-objects' '--extra-cflags=-flto=thin -ffat-lto-objects' --target-list=x86_64-softmmu
[...]
$ time make -j8
[...]
[3078/3078] Linking target tests/qtest/qos-test
real 6m43.250s
user 101m15.967s
sys 4m3.813s
$ ../configure --cc=clang '--extra-ldflags=-flto=thin -ffat-lto-objects' '--extra-cflags=-flto=thin -ffat-lto-objects' --target-list=x86_64-softmmu --disable-tests
[...]
$ time make -j8
[...]
[2024/2024] Linking target qemu-system-x86_64
real 3m14.277s
user 33m13.174s
sys 1m36.642s
Add a toggle to optionally disable building tests.
Signed-off-by: Florian Schmidt <flosch@nutanix.com>
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Tested-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Message-ID: <20260724135413.1716872-1-flosch@nutanix.com>
Signed-off-by: Thomas Huth <th.huth@posteo.eu>
The cache cleanup script already successfully removes the assets
that are unused since more than 6 months, but it forgot to delete
the corresponding timestamp files, too.
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-ID: <20260814122643.312129-1-thuth@redhat.com>
Signed-off-by: Thomas Huth <th.huth@posteo.eu>
* AGENTS.md: basic bare minimal guide
* target/i386: TCG fixes
* scripts/checkpatch: warn on duplicate trailers, self-review, crediting AI
* docs: link to website for IRC and mailing list
* rust: qemu-macros: remove redundant clone()
* rust: qemu-macros: silence more warnings for bindgen crates
# -----BEGIN PGP SIGNATURE-----
#
# iQFIBAABCgAyFiEE8TM4V0tmI4mGbHaCv/vSX3jHroMFAmqhgPcUHHBib256aW5p
# QHJlZGhhdC5jb20ACgkQv/vSX3jHroMHGgf9HhS9YkSidGB00Xg843Duhms1GwCy
# hXP1G+wZisFk63ypd7k9ZSMh6jCJrHA+A4LoRiVP2W+mfWgWRMh1c3oUf9u7fjzO
# CsBV/JejM6GruSPjcCtFIBvKZbdZxlGoPWLpedvLDFQdoWZk2TLqIHFw+XJjK8uI
# ESYQuiWUqEaj+Vk0NerGL8nvMwOkYL8X7L89GJirXfZio2U+VmtSRrIhQ5W0SpK8
# jV7Oi5PJiKCm7gss4z0psaIXW/4ep6QGmWtx3lA6+uh1G2DCTkNoeo2JU10BQEZU
# fZsNy6B/mqG66jPwHHXziaC/omXf1XZ/p+0zER3m2VtWi7Zg4W0fDrQGVA==
# =04kq
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed Sep 9 16:53:27 2026 BST
# 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:
rust: bindings: disable more clippy warnings
rust: qemu-macros: remove redundant clone()
AGENTS.md: basic bare minimal guide
scripts/checkpatch: warn on duplicate trailers and self-review
checkpatch: reject trailers that credit an AI agent
docs: link to website for IRC and mailing list
target/i386: Mark MOVNTI as not valid with prefixes 0x66, 0xF2, 0xF3
target/i386: Update FPU tag word for FXCH
target/i386: Update FPU tag word for FSTP
target/i386: Update FPU tag word for FXTRACT's old ST(0)
target/i386: clear C1 for all x87 compare instructions
target/i386: Fix FXCH to unconditionally clear C1
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Detect two common trailer mistakes:
- Duplicate trailers: any trailer (Signed-off-by, Fixes, Resolves,
Cc, etc.) appearing more than once with the same value in a commit
message.
- Self-review: a Reviewed-by, Tested-by, or Acked-by tag from the
same person as the patch author, which provides no independent
review value.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Link: https://lore.kernel.org/r/20260727161157.2112984-1-marcandre.lureau@redhat.com
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
The QEMU community has broad consensus to not accept assisted-by and similar
trailers, and much less fake co-authored-bys, independent of any AI policy.
Implement this in checkpatch.pl already, so that there is another way for
contributors to discover the AI policy.
Suggested-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Update libvirt-ci to current origin/master for the primary sake of
grabbing new mappings for FreeBSD, which has upgraded from Python 3.11
to 3.12 and along with it changed the name of their python ecosystem
packages.
Refresh the lcitool generated files to fix our FreeBSD tests.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Message-ID: <20260825215851.1780608-3-jsnow@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
.wrap files and Cargo.lock contain pretty much the same information.
QEMU uses the former to make it easier for distros to use a local
registry, and also because Meson <1.13 does not use Cargo.lock for
the "meson subprojects" command. This however introduces an
inconvenience when running "cargo update", in that the wrap
files have to be updated by hand.
Add the possibility to get new versions from Cargo.lock and not
just from a local registry, thus automating the update.
For now, only existing wrap files are modified. This means
that semver-breaking updates need to be done (at least partly)
by hand; it is enough to rename the wrap file prior to running
the script.
While the need for this script is a lot smaller with Meson 1.13, it
would still remain useful for packages that have a patch directory.
Perhaps a bit overengineered, but since we have it...
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Until now, the new version of the crate was always there in
the registry. This will be different when crates are downloaded
from Cargo.lock, so delay the comparison of build.rs until a
point at which both source directories have been extracted.
Since the .wrap file at this point points to the new directory,
delete the old one "by hand" with shutil.rmtree instead of asking
Meson to do it before the .wrap file is changed.
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
The bilge crate is heavily reliant on traits and, because trait functions
are never const, bilge and const mix about as well as water and oil.
In addition, it has support for the zerocopy crate that only works for an
older version, and is hard to update because the implementation doesn't
like that zerocopy::FromBits and bilge::FromBits are the same name.
zerocopy is definitely something that QEMU could use in the future.
The bitfield-struct crate, instead, is built from the ground up to
support const. Its use is pretty much the same (device code does not
change at all, only register declarations do), with some things being
more verbose and others being simpler. The code for the crate itself
is much smaller, too.
It does have two disadvantages: it does not let you annotate enums
as bitfields, and it does not integrate with arbitrary-int. Thus, it
requires manual size annotations for anything that is not a bool, iNN
or uNN. Lack of support for arbitrary-int is a very small deal, while
enums are a bit more annoying because they require some repetition
and an implementation of two functions from_bits() and into_bits().
However, the latter is already provided by the "bits!" and
"#[derive(common::TryInto)]" utilities, and thus is not manual
in QEMU's case.
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
The logic to parse the [lints] section has been integrated
into Meson and can be removed.
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Meson can automatically generate most of the build rules for
subprojects, based on the contents of their Cargo.toml. Handwritten
snippets can be placed in meson/meson.build to replace build.rs.
Disable Meson's use of the nightly-only option "--env-set". It is
buggy and anyway it should not be there in future version.
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Make our CI containers smaller, by removing a handful of packages that
were only included as dependencies of Avocado.
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
With the GitLab mapping files from the previous commit, the
get_manitainer.pl script is now able to report the gitlab
handle for each maintainer/reviewer when displaying output.
For example:
$ ./scripts/get_maintainer.pl -f hw/scsi/lsi53c895a.c
Paolo Bonzini <pbonzini@redhat.com> (supporter:SCSI, gitlab:@bonzini)
Fam Zheng <fam@euphon.net> (reviewer:SCSI, gitlab:@famzheng)
qemu-devel@nongnu.org (open list:All patches CC here)
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
It is desirable to be able to discover the GitLab account handle
assocaited with a real name in the MAINTAINERS file.
Rather that duplicating the same account handle multiple times,
inline with the MAINTAINERS file entries, this introduces mapping
files:
* .gitlab-map-auto - data automatically queried from GitLab
using the 'glab' tool and REST API
* .gitlab-map-manual - manual overrides/augmentation for
cases where the MAINTAINERS real name does not match the
GitLab account real name
The former would need refreshing when we add new MAINTAINERS
entries, if the person had to be added as a GitLab account
member. For this purpose scripts/gitlab-map-update can be
used, assuming the user has the 'glab' client tool present
and configured with an access token.
To audit how many maintainers have GitLab handles present/missing
scripts/gitlab-map-check can run a report.
$ ./scripts/gitlab-map-check
Missing GitLab handle for maintainer 'Akihiko Odaki'
Missing GitLab handle for maintainer 'Albert Esteve'
....
Missing GitLab handle for maintainer 'Zhenzhong Duan'
Missing GitLab handle for maintainer 'Zhuoying Cai'
GitLab handles missing: 158 / present: 68
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
SPICE resources were never freed on shutdown. Add per-subsystem
cleanup (display, input, core) and call it from qemu_cleanup().
Move spice-module.c into libui so the qemu_spice ops table links
with the rest of the UI code. Add an LSan suppression for a known
spice-server leak.
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-ID: <20260623-b4-ui-v4-14-4656aec3398d@redhat.com>
qemu_irq_intercept_in() saves original IRQ handlers by allocating
new QOM objects, which are never freed. On a PC machine, this leaks
IRQ objects (one per IOAPIC pin) on every qtest run.
Rather than tracking allocations to free later, avoid them: add an
"observer" field to IRQState, called by qemu_set_irq() after the
real handler. Interception sets the observer instead of rewriting
handlers, so there's nothing to save and nothing to leak.
Fix qemu_notirq() to route through qemu_set_irq() so inverted IRQs
trigger observers too. Drop the LSan suppression.
Reviewed-by: Fabiano Rosas <farosas@suse.de>
Reviewed-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>
Reviewed-by: Akihiko Odaki <odaki@rsg.ci.i.u-tokyo.ac.jp>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-ID: <20260623-b4-ui-v4-3-4656aec3398d@redhat.com>
The following cpu_physical_memory_*() methods do not involve any
vCPU but only access physical memory:
- cpu_physical_memory_read()
- cpu_physical_memory_write()
- cpu_physical_memory_map()
- cpu_physical_memory_unmap()
Rename them removing the 'cpu_' prefix, and move then to the
"system/physmem.h" header with the other methods involved in
global physical address space.
Mechanical change using sed, then adding missing headers manually.
No logical change intended.
Signed-off-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-Id: <20260616020839.19104-7-philmd@oss.qualcomm.com>
Changes:
- [PATCH v2 00/26] plugins: refactor API to maintain state through (Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>)
Link: https://lore.kernel.org/qemu-devel/20260615193526.2883349-1-pierrick.bouvier@oss.qualcomm.com
# -----BEGIN PGP SIGNATURE-----
#
# iQHWBAABCgBAFiEEN8FWlNi6l2Sxlz/btEQ30ZwoYt8FAmoxmRAiHHBpZXJyaWNr
# LmJvdXZpZXJAb3NzLnF1YWxjb21tLmNvbQAKCRC0RDfRnChi3ztKC/45bQ+YlttE
# d2Zdt/N57raaZ8cumzTfpsmnN3Yd+ilIzJizW2OUgdrKrsXsZ73nEwsy9oV2XAGN
# XEaXBlVmLrIXnWRcVYyeKeTr0pJpjhglbLMwXHotgCpCZn77wOkIhTsJlEL83G0/
# F0Vt0o1FbvOepwZXr0jCU9JT/kewT0BptXClfQpyJcGeggj6x/rUsk32Lj7c5kZH
# 6T64T5tJZ5hxndJ/MQCHbsPkUksZT2WD44EYNb3QpVIvPBeoD/02WBfqC+U0fXQ3
# +O/JSfNacgjLWskaPiykft8t9GsRX3DgR5IJJ/WG4y3h9rxpbQKVdn5aKhmNavYK
# QplhS47OashPPbRWBYmKPipQO30sga5dPBt43mU0y1OfKBJR240r5CnFDNtU+XPM
# fwrcdmogleAKAU5rMqvP7fp2usBX0VAzTwtHF6PtswYX46uon/qIQ7E4VYh8mOeV
# DULhi38wKXUKHDwv00pXOvk2n6SOUdoro6XYaJoyArSK+vVFptV6nd4=
# =gcF/
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 16 Jun 2026 14:42:24 EDT
# gpg: using RSA key 37C15694D8BA9764B1973FDBB44437D19C2862DF
# gpg: issuer "pierrick.bouvier@oss.qualcomm.com"
# gpg: Good signature from "Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>" [unknown]
# gpg: WARNING: The key's User ID is not certified with a trusted signature!
# gpg: There is no indication that the signature belongs to the owner.
# Primary key fingerprint: 37C1 5694 D8BA 9764 B197 3FDB B444 37D1 9C28 62DF
* tag 'pbouvier/pr/plugins-20260616' of https://gitlab.com/p-b-o/qemu: (26 commits)
plugins/cpp: register callbacks using captureless lambda
scripts/checkpatch: remove check on forbidden space before '[' in C++
scripts/checkpatch: ignore spaces required around some operators in C++
plugins: use consistent parameter documentation for userdata
plugins: add userdata to qemu_plugin_register_vcpu_syscall_ret_cb
plugins: remove qemu_plugin_id from qemu_plugin_vcpu_syscall_ret_cb_t
plugins: add userdata to qemu_plugin_register_vcpu_syscall_filter_cb
plugins: remove qemu_plugin_id from qemu_plugin_vcpu_syscall_filter_cb_t
plugins: add userdata to qemu_plugin_register_vcpu_syscall_cb
plugins: remove qemu_plugin_id from qemu_plugin_vcpu_syscall_cb_t
plugins: add userdata to qemu_plugin_vcpu_tb_trans_cb_t
plugins: remove qemu_plugin_id from qemu_plugin_vcpu_tb_trans_cb_t
plugins: remove qemu_plugin_id from qemu_plugin_vcpu_discon_cb_t
plugins: add userdata to qemu_plugin_register_vcpu_discon_cb
plugins: remove type qemu_plugin_vcpu_simple_cb_t
plugins: add userdata to qemu_plugin_vcpu_for_each
plugins: add userdata to qemu_plugin_register_vcpu_resume_cb
plugins: add userdata to qemu_plugin_register_vcpu_idle_cb
plugins: add userdata to qemu_plugin_register_vcpu_exit_cb
plugins: add userdata to qemu_plugin_register_vcpu_init_cb
...
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
C++ has a different style when it comes to space around references,
dereferences, so don't report it.
Also, closing templates with >> gets wrongly confused with >> operator,
so just relax this check.
Some examples:
ERROR: spaces required around that '&' (ctx:WxV)
+ auto &[counter, p] = *static_cast<TbData*>(udata);
^
ERROR: spaces required around that '*' (ctx:VxO)
+ auto &[counter, p] = *static_cast<TbData*>(udata);
^
ERROR: spaces required around that '>>' (ctx:VxW)
+ std::vector<std::pair<Vaddr, uint64_t>> v; ^
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Manos Pitsidianakis <manos.pitsidianakis@linaro.org>
Link: https://lore.kernel.org/qemu-devel/20260615193526.2883349-25-pierrick.bouvier@oss.qualcomm.com
Signed-off-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Add parsing for explicit Intro section syntax.
A side effect of this patch is that we will (currently) always create
an empty Intro section, similar to how we used to have an empty Plain
section. The tests are adjusted accordingly, rendered document output
does not change at all.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-14-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Prior to this patch, we always create an empty Plain section. Removing
this allows us to gradually phase out the "Plain" section in favor of
"Intro" and "Details" sections while keeping "Plain" around for the
interim churn during the series - meaning that we don't actually know
at __init__ time which type of section we'll have first.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-12-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
A forthcoming patch removes the implicit PLAIN section that always
starts a QAPIDoc section list. Further future changes begin converting
"PLAIN" sections to "INTRO" sections.
This will affect the code that inserts "Not documented" descriptions
for undocumented members ("stub sections") and the dummy section that
marks the spot for "The members of ..." references.
Adjust the algorithm to cope with not only the finished state, but
temporary intermediate states while the series is merged.
This algorithm can handle zero-or-more PLAIN *or* INTRO sections at
the beginning of a QAPIDoc object, in contrast to the previous
algorithm which assumed and relied upon there being always one PLAIN
section at the beginning of every QAPIDoc section list.
In other words: (PLAIN | INTRO)* <EverythingElse>
This does not impact what the parser itself will actually produce. As
of this patch, the parser will still always generate QAPIDoc section
lists that start with precisely one PLAIN section (whether or not it
is empty), followed by the remaining sections. Those remaining
sections may or may not include additional PLAIN sections, but never
two such sections contiguously as the parser will always treat that
layout as one PLAIN section consisting of multiple paragraph(s).
In other other words: This insertion algorithm is more lenient than
the parser, but this is on purpose for flexibility mid-stream as we
convert QAPI to using explicit introductory sections. The allowed
order of sections will eventually become strictly enforced in the
parser, which will in turn allow dramatic simplifications to the
insertion algorithm. This only exists as transitory code until we are
able to enforce that order.
Fear not: the intermediate ReST output before and after this patch
are byte identical, so failing all else, we at least know it doesn't
make anything worse.
Lastly, because we have three places in the code that need to insert
stub/dummy sections, we take the opportunity to consolidate this code
to handle all three cases with one function. This winds up
necessitating the qapidoc.py generator actually modify the section
list to insert a "dummy" member that acts as a placeholder for "The
members of ..." text. While it looks like a code smell to modify the
caller's argument, it is ultimately safe because the QAPI Schema
object is re-parsed and re-constructed in memory for each individual
process that needs to operate on it. In other words, the Sphinx
document generator already does have "its own copy" of the section
lists, so it is "safe" to modify here without regards to other
consumers of the QAPIDoc objects. It only *looks* like it smells
bad. Ultimately, this code will also be removed once the inliner is
merged, so it is only a temporary aesthetic issue regardless.
That's my story and I'm sticking to it.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
These algorithms are quite a mess currently, but they are temporary
until we add the inliner which will address these issues more
holistically. For now, add the "mea culpa".
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Move this function out from underneath `ensure_returns` and make it
available for general purpose use as an object method instead. This is
purely a scope-level patch with no functional changes.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-9-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This patch adds an "Intro" doc section, intended to eventually replace
the "Plain" doc section alongside a forthcoming "Details" section.
For now, this section is not actually instantiated or used, but
subsequent patches will slowly convert the leading introductory sections
of QAPIDoc documentation to use this new section.
A main motivation of this series of changes is to more explicitly
delineate the "Introductory" documentation for each QAPI definition for
the sake of the inliner. When inlining members, examples, and details
from multiple QAPIDoc sections, we will want to omit the "Introductory"
text from inlined definitions while keeping notes, caution boxes,
examples, and so on. This new section facilitates that.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-8-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
These fields are used to provide error checking and internal logistics
and should not be used by a user of the library to directly access
documentation sections, so make them private.
The "since" field alone is left public, as the qapidoc generator does
use this field to pull that section out of the regular flow of the
document.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260611042332.482979-6-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
All users of the QAPIDoc object should be iterating over all_sections
and not grabbing arbitrary subsections, if possible. Remove the 'body'
and 'sections' members, as they are no longer used.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20260611042332.482979-4-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
