Sphinx < 4.1 handles cross-references ... differently. Factor out and
isolate the compatibility goop we need to make cross references work
properly in old versions of Sphinx.
Yes, it's ugly. Yes, it works. No, I don't want to talk about
it.
Understand that this patch exists because of the overflowing love in my
heart.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-30-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Improve the general look and feel of generated QAPI docs.
Attempt to limit line lengths to offer a more comfortable measure on
maximized windows, and improve some margin and spacing for field lists.
Signed-off-by: Harmonie Snow <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-29-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit, finally, adds cross-referencing support to various field
lists; modeled tightly after Sphinx's own Python domain code.
Cross-referencing support is added to type names provided to :arg:,
:memb:, :returns: and :choice:.
:feat:, :error: and :value:, which do not take type names, do not
support this syntax.
The general syntax is simple:
:arg TypeName ArgName: Lorem Ipsum ...
The domain will transform TypeName into :qapi:type:`TypeName` in this
basic case, and also apply the ``literal`` decoration to indicate that
this is a type cross-reference.
For optional arguments, the special "?" suffix is used. Because "*" has
special meaning in rST that would cause parsing errors, we elect to use
"?" instead. The special syntax processing strips this character from
the end of any type name argument and will append ", optional" to the
rendered output, applying the cross-reference only to the actual type
name.
The intent here is that the actual syntax in doc-blocks need not change;
but e.g. qapidoc.py will need to process and transform "@arg foo lorem
ipsum" into ":arg type? foo: lorem ipsum" based on the schema
information. Therefore, nobody should ever actually witness this
intermediate syntax unless they are writing manual documentation or the
doc transmogrifier breaks.
For array arguments, type names can similarly be surrounded by "[]",
which are stripped off and then re-appended outside of the
cross-reference.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-28-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Normally, Sphinx will silently fall back to its standard field list
processing if it doesn't match one of your defined fields. A lot of the
time, that's not what we want - we want to be warned if we goof
something up.
For instance, the canonical argument field list form is:
:arg type name: descr
This form is captured by Sphinx and transformed so that the field label
will become "Arguments:". It's possible to omit the type name and descr
and still have it be processed correctly. However, if you omit the type
name, Sphinx no longer recognizes it:
:arg: this is not recognized.
This will turn into an arbitrary field list entry whose label is "Arg:",
and it otherwise silently fails. You may also see failures for doing
things like using :values: instead of :value:, or :errors: instead of
:error:, and so on. It's also case sensitive, and easy to trip up.
Add a validator that guarantees all field list entries that are the
direct child of an ObjectDescription use only recognized forms of field
lists, and emit a warning (treated as error by default in most build
configurations) whenever we detect one that is goofed up.
However, there's still benefit to allowing arbitrary fields -- they are
after all not a Sphinx invention, but perfectly normal docutils
syntax. Create an allow list for known spellings we don't mind letting
through, but warn against anything else.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-27-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add a special :ifcond: option that allows us to annotate the
definition-level conditionals.
The syntax of the argument is currently undefined, but it's possible we
can apply better formatting in the future. Currently, we just display
the ifcond string as preformatted text.
Signed-off-by: Harmonie Snow <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-26-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Although "unstable" is a feature (and *will* appear in the features
list), add a special :unstable: option to generate an eye-catch that
makes this information very hard to miss.
The forthcoming Transmogrifier in qapidoc.py will add this option
whenever it detects that the features list attached to a definition
contains the "unstable" entry.
Signed-off-by: Harmonie Snow <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-25-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Although "deprecated" is a feature (and *will* appear in the features
list), add a special :deprecated: option to generate an eye-catch that
makes this information very hard to miss.
The forthcoming Transmogrifier in qapidoc.py will add this option
whenever it detects that the features list attached to a definition
contains the "deprecated" entry.
P.S., I outsourced the CSS ;)
Signed-off-by: Harmonie Snow <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-24-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Adds the .. qapi:object:: directive, object, and :qapi:obj:`name`
cross-referencing role. This directive is meant to document both structs
and unions.
As per usual, QAPI cross-referencing for types in the member field list
will be added in a forthcoming commit.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-23-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Adds the .. qapi:event:: directive, object, and :qapi:event:`name`
cross-referencing role.
Adds the :memb type name: field list syntax for documenting event data
members. As this syntax and phrasing will be shared with Structs and
Unions as well, add the field list definition to a shared abstract
class.
As per usual, QAPI cross-referencing for types in the member field list
will be added in a forthcoming commit.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-22-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add the .. qapi:alternate:: directive, object, and qapi:alt:`name`
cross-reference role.
Add the "Alternatives:" field list for describing alternate choices. Like
other field lists that reference QAPI types, a forthcoming commit will
add cross-referencing support to this field.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-21-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add the .. qapi:enum:: directive, object, and :qapi:enum:`name`
cross-reference role.
Add the :value name: field list for documenting Enum values.
Of note, also introduce a new "type" role that is intended to be used by
other QAPI object directives to cross-reference arbitrary QAPI type
names, but will exclude commands, events, and modules from
consideration.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-20-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add "Return:" field list syntax to QAPI Commands.
Like "Arguments:" and "Errors:", the type name isn't currently processed
for cross-referencing, but this will be addressed in a forthcoming
commit.
The syntax of the new field is:
:return TypeName: description
description cont'd
This patch adds "Return" as a GroupedField, which means that multiple
return values can be annotated - this is only done because Sphinx does
not support mandatory type arguments to Ungrouped fields. Because we
want to cross-reference this type information later, we want to make the
type argument mandatory. As a result, you can technically add multiple
:return: fields, though I'm not aware of any circumstance in which you'd
need or want to. Recommendation: "Don't do that, then." The forthcoming
QAPIDoc transmogrifier does not, in fact, ever "do that".
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-19-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
``:error: descr`` can now be used to document error conditions. The
format of the description is not defined here; so the ability to name
specific types is left to the document writer.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-18-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add support for Features field lists. There is no QAPI-specific
functionality here, but this could be changed if desired (if we wanted
the feature names to link somewhere, for instance.)
This feature list doesn't have any restrictions, so it can be used to
document object-wide features or per-member features as deemed
appropriate. It's essentially free-form text.
The syntax for this field is:
:feat name: description
description cont'd
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-17-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This adds special rendering for Sphinx's typed info field lists.
This patch does not add any QAPI-aware markup, rendering, or
cross-referencing for the type names, yet. That feature requires a
subclass to TypedField which will happen in its own commit quite a bit
later in this series; after all the basic fields and objects have been
established first.
The syntax for this field is:
:arg type name: description
description cont'd
You can omit the type or the description. You should not omit the name;
if you do so, it degenerates into a "normal field list" entry, and
probably isn't what you want.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-16-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add a little special markup for registering "Since:" information. Adding
it as an option instead of generic content lets us hoist the information
into the Signature bar, optionally put it in the index, etc.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-15-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit adds a stubbed version of QAPICommand that utilizes the
QAPIObject class, the qapi:command directive, the :qapi:cmd:
cross-reference role, and the "command" object type in the QAPI object
registry.
They don't do anything *particularly* interesting yet, but that will
come in forthcoming commits.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-14-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This patch adds another abstract class that describes "a QAPI
thingie". The main difference here is that this class will be generating
visible documentation, unlike the QAPIDescription class.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-13-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This adds the qapi:module directive, which just notes the current module
being documented and performs a nested parse of the content block, if
present.
This code is based pretty heavily on Sphinx's PyModule directive, but
with unnecessary features excised.
For example:
.. qapi:module:: block-core
Hello, and welcome to block-core!
=================================
lorem ipsum, dolor sit amet ...
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-12-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This class is a generic, top-level directive for documenting some kind
of QAPI thingamajig that we expect to go into the Index. This class
doesn't do much by itself, and it isn't yet associated with any
particular directive.
handle_signature(), _object_hierarchy_parts() and _toc_entry_name() are
defined in the base class. get_index_text() and add_target_and_index()
are new methods defined here; they are based heavily on the layout and
format of the Python domain's general object class.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-11-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Sphinx prior to v4.0 uses different classes for rendering elements of
documentation objects; add some compatibility classes to use the right
node classes conditionally.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-10-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add domain-specific cross-reference syntax. As of this commit, that
means new :qapi:any:`block-core` referencing syntax.
The :any: role will find anything registered to the QAPI domain,
including modules, commands, events, etc.
Creating the cross-references is powered by the QAPIXRefRole class;
resolving them is handled by QAPIDomain.resolve_xref().
QAPIXrefRole is based heavily on Sphinx's own PyXrefRole, with
modifications necessary for QAPI features.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-9-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Add the ability to resolve cross-references using the `any`
cross-reference syntax. Adding QAPI-specific cross-reference roles will
be added in a forthcoming commit, and will share the same find_obj()
helper.
(There's less code needed for the generic cross-reference resolver, so
it comes first in this series.)
Once again, this code is based very heavily on sphinx.domains.python.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-8-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Use the QAPI object registry to generate a special index just for QAPI
definitions. The index can show entries both by definition type and all
together, alphabetically.
The index can be linked from anywhere in the QEMU manual by using the
reference `qapi-index`.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-7-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This is the first step towards QAPI domain cross-references and a QAPI
reference index.
This patch just creates the object registry, and updates the
merge_domaindata stub method now that we have actual data we may need to
merge.
Note that how to handle merge conflict resolution is unhandled, as the
Sphinx python domain itself does not handle it either. I do not know how
to intentionally trigger it, so I've left an assertion instead if it
should ever come up ...
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-6-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Create a compat module that handles sphinx cross-version compatibility
issues. For the inaugural function, add a nested_parse_with_titles()
helper that handles differences in line number tracking for nested
directive body parsing.
Spoilers: there are more cross-version hacks to come throughout the
series.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-5-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
A Sphinx domain is a collection of directive and role extensions meant
to facilitate the documentation of a specific language. For instance,
Sphinx ships with "python" and "cpp" domains. This patch introduces a
stub for the "qapi" language domain.
Please see https://www.sphinx-doc.org/en/master/usage/domains/index.html
for more information.
This stub doesn't really do anything yet, we'll get to it brick-by-brick
in the forthcoming commits to keep the series breezy and the git history
informative.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-4-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
* Updated Aspeed OpenBMC functional test images
* Introduced functional tests for witherspoon and bletchley machines
* Added support for Non-maskable Interrupt on AST2700 SoC
* Fixed HW strapping on AST2700 SoC
* Added AST2700 HACE support
* Added AST2700 A1 SoC support
* Intoduced new ast2700a1-evb machine
-----BEGIN PGP SIGNATURE-----
iQIzBAABCAAdFiEEoPZlSPBIlev+awtgUaNDx8/77KEFAmfNnIUACgkQUaNDx8/7
7KFMGQ//YHvJV30PkI9CHO6Gbk3CmWftI9Dbjn7goghV/hArVThiq9fve3n2GxYJ
aKrpQZ3BK5SOvcp1zzSc2HrCxmzhy98TZfH2vqwqx3T7uqLDTGgo6xGRYT7+fuVn
SzQaxFJ5hG8LdR4GqDcuUlUVyjVM3ZGR8E/Guj6s6Um1gctZsjy7Z+CdAWDlXFWM
uJoI9EwbhdIWYWF6jJw3myOjMhXHNZs0IobvS7yzZ3DGX0o/P3jRxFYeS6P9lQDl
+TmZ/IRuZDMgA3N+jAyQfMjmlvtA0BygLUbrKTJXb6Bz0BhUjUVahOv6Mnq86yZh
glKCg9LB4BVZneTw5VSd3Tj6Lt/qNhhJjRlV+UYxWzZ0zmFNdkq08RRxKCmMbtYi
t4DsT7xGqfMK9JXEOIWa5REyP4i5llzKe173ml4wSi1Nro9hzZz5cgAKS+7Eabni
nCLhOi26hwkBUCqCKN2eTyRKqOtyftOiKGYog1EV4YtwbnfQS072h0FJz8H6Ibkt
n+twrO8NY31Y0JMzj0GksZ0JSlV/04mtuIpNMSqPizMN/VZPznqwCiaGADtips4f
DoJRtJyDaI/n0IlbtcRpcsrax0uQQEdClvFlcfOkSvkm1aZU2q7wwSKbyOkcnWgd
qnxkUqjHnQTlUSEOqjhtEcw7Bv6J7Mn5IwN0zKROIZp9ia+LZwI=
=O5Kv
-----END PGP SIGNATURE-----
Merge tag 'pull-aspeed-20250309' of https://github.com/legoater/qemu into staging
aspeed queue:
* Updated Aspeed OpenBMC functional test images
* Introduced functional tests for witherspoon and bletchley machines
* Added support for Non-maskable Interrupt on AST2700 SoC
* Fixed HW strapping on AST2700 SoC
* Added AST2700 HACE support
* Added AST2700 A1 SoC support
* Intoduced new ast2700a1-evb machine
# -----BEGIN PGP SIGNATURE-----
#
# iQIzBAABCAAdFiEEoPZlSPBIlev+awtgUaNDx8/77KEFAmfNnIUACgkQUaNDx8/7
# 7KFMGQ//YHvJV30PkI9CHO6Gbk3CmWftI9Dbjn7goghV/hArVThiq9fve3n2GxYJ
# aKrpQZ3BK5SOvcp1zzSc2HrCxmzhy98TZfH2vqwqx3T7uqLDTGgo6xGRYT7+fuVn
# SzQaxFJ5hG8LdR4GqDcuUlUVyjVM3ZGR8E/Guj6s6Um1gctZsjy7Z+CdAWDlXFWM
# uJoI9EwbhdIWYWF6jJw3myOjMhXHNZs0IobvS7yzZ3DGX0o/P3jRxFYeS6P9lQDl
# +TmZ/IRuZDMgA3N+jAyQfMjmlvtA0BygLUbrKTJXb6Bz0BhUjUVahOv6Mnq86yZh
# glKCg9LB4BVZneTw5VSd3Tj6Lt/qNhhJjRlV+UYxWzZ0zmFNdkq08RRxKCmMbtYi
# t4DsT7xGqfMK9JXEOIWa5REyP4i5llzKe173ml4wSi1Nro9hzZz5cgAKS+7Eabni
# nCLhOi26hwkBUCqCKN2eTyRKqOtyftOiKGYog1EV4YtwbnfQS072h0FJz8H6Ibkt
# n+twrO8NY31Y0JMzj0GksZ0JSlV/04mtuIpNMSqPizMN/VZPznqwCiaGADtips4f
# DoJRtJyDaI/n0IlbtcRpcsrax0uQQEdClvFlcfOkSvkm1aZU2q7wwSKbyOkcnWgd
# qnxkUqjHnQTlUSEOqjhtEcw7Bv6J7Mn5IwN0zKROIZp9ia+LZwI=
# =O5Kv
# -----END PGP SIGNATURE-----
# gpg: Signature made Sun 09 Mar 2025 21:49:57 HKT
# gpg: using RSA key A0F66548F04895EBFE6B0B6051A343C7CFFBECA1
# gpg: Good signature from "Cédric Le Goater <clg@redhat.com>" [full]
# gpg: aka "Cédric Le Goater <clg@kaod.org>" [full]
# Primary key fingerprint: A0F6 6548 F048 95EB FE6B 0B60 51A3 43C7 CFFB ECA1
* tag 'pull-aspeed-20250309' of https://github.com/legoater/qemu: (46 commits)
docs/specs: Add aspeed-intc
tests/functional/aspeed: Add test case for AST2700 A1
tests/functional/aspeed: Update test ASPEED SDK v09.05
tests/functional/aspeed: Update temperature hwmon path
tests/functional/aspeed: Introduce start_ast2700_test API
hw/arm/aspeed_ast27x0: Sort the memmap table by mapping address
hw/arm/aspeed: Add Machine Support for AST2700 A1
hw/arm/aspeed_ast27x0: Add SoC Support for AST2700 A1
hw/arm/aspeed_ast27x0: Support two levels of INTC controllers for AST2700 A1
hw/arm/aspeed_ast27x0: Define an Array of AspeedINTCState with Two Instances
hw/arm/aspeed_ast27x0.c Support AST2700 A1 GIC Interrupt Mapping
hw/misc/aspeed_scu: Add Support for AST2700/AST2750 A1 Silicon Revisions
hw/intc/aspeed: Add Support for AST2700 INTCIO Controller
hw/intc/aspeed: Add Support for Multi-Output IRQ Handling
hw/intc/aspeed: Introduce IRQ handler function to reduce code duplication
hw/intc/aspeed: Introduce AspeedINTCIRQ structure to save the irq index and register address
hw/intc/aspeed: Refactor INTC to support separate input and output pin indices
hw/intc/aspeed: Add support for multiple output pins in INTC
hw/intc/aspeed: Rename num_ints to num_inpins for clarity
hw/intc/aspeed: Support different memory region ops
...
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
* Improve performance of s390x PCI passthrough devices with relaxed translation
-----BEGIN PGP SIGNATURE-----
iQJFBAABCAAvFiEEJ7iIR+7gJQEY8+q5LtnXdP5wLbUFAmfK3dsRHHRodXRoQHJl
ZGhhdC5jb20ACgkQLtnXdP5wLbUfDQ/8CopnzCKGKFhyM5skrHbhDbUVbul6yV4L
kIOo7N8OlrNcQB90bj+Udy+mUANHjkmSiBa5lJ/78ej4DFS6CxeVgrl1fSEl36xn
GjWDwSUiN8pG1O4YtnDqWVTBieGSzbkQr1jHgpeAnvv08s+TtmudP1T8IznWU2v9
FqD78SdebZ0Kua+ksBgMxwkHd6VMw13vsu6KuT9VBhie40LcDrFOuG8RDz/qo4IO
Yg9s1Bqcy7Wa4+0ldMXS1plSdIqJBtVc/HDTg1QwH994b4Lvr7ffrFZmuVcd2dbE
XKQ5jAMOYZqWdlXszkyd8moYGhmevCkQlALhpnbHixnfakfFYX0wTiJB6oCthFQ0
It0J/ntNsCmJiIHNbPLzsJ1pE5+ureRnGbxVe05n+zfm8MaXL6s4nSdZzHyp8n43
UZQqVzK55Q34K9O0qoUdCdBCjMKS9v5u95jjJo8+nc8sJoeQTssOoiixwB/E4y21
9qSh7CbDjQK4zwuzQ7jKD603zAJH6ivvsHXlMBMXJFBiSMCAoQQ1vyou6yRHswRr
gLHDwiWUx8SX8ckbbJ/+Zo9+T8JBMvC5hNYG8VoAtlTQusG4bHSbKdPNNH0eHsEp
f7RlZPRizkcK3w0Nj+u4kXdnnex3QLLSgnyAYq7zEl6V+mho8KqaBezkO7wQDHZy
+GW5ignQ1Gs=
=CyiZ
-----END PGP SIGNATURE-----
Merge tag 'pull-request-2025-03-07' of https://gitlab.com/thuth/qemu into staging
* Bug fixes and some small improvements for functional tests
* Improve performance of s390x PCI passthrough devices with relaxed translation
# -----BEGIN PGP SIGNATURE-----
#
# iQJFBAABCAAvFiEEJ7iIR+7gJQEY8+q5LtnXdP5wLbUFAmfK3dsRHHRodXRoQHJl
# ZGhhdC5jb20ACgkQLtnXdP5wLbUfDQ/8CopnzCKGKFhyM5skrHbhDbUVbul6yV4L
# kIOo7N8OlrNcQB90bj+Udy+mUANHjkmSiBa5lJ/78ej4DFS6CxeVgrl1fSEl36xn
# GjWDwSUiN8pG1O4YtnDqWVTBieGSzbkQr1jHgpeAnvv08s+TtmudP1T8IznWU2v9
# FqD78SdebZ0Kua+ksBgMxwkHd6VMw13vsu6KuT9VBhie40LcDrFOuG8RDz/qo4IO
# Yg9s1Bqcy7Wa4+0ldMXS1plSdIqJBtVc/HDTg1QwH994b4Lvr7ffrFZmuVcd2dbE
# XKQ5jAMOYZqWdlXszkyd8moYGhmevCkQlALhpnbHixnfakfFYX0wTiJB6oCthFQ0
# It0J/ntNsCmJiIHNbPLzsJ1pE5+ureRnGbxVe05n+zfm8MaXL6s4nSdZzHyp8n43
# UZQqVzK55Q34K9O0qoUdCdBCjMKS9v5u95jjJo8+nc8sJoeQTssOoiixwB/E4y21
# 9qSh7CbDjQK4zwuzQ7jKD603zAJH6ivvsHXlMBMXJFBiSMCAoQQ1vyou6yRHswRr
# gLHDwiWUx8SX8ckbbJ/+Zo9+T8JBMvC5hNYG8VoAtlTQusG4bHSbKdPNNH0eHsEp
# f7RlZPRizkcK3w0Nj+u4kXdnnex3QLLSgnyAYq7zEl6V+mho8KqaBezkO7wQDHZy
# +GW5ignQ1Gs=
# =CyiZ
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 07 Mar 2025 19:51:55 HKT
# gpg: using RSA key 27B88847EEE0250118F3EAB92ED9D774FE702DB5
# gpg: issuer "thuth@redhat.com"
# gpg: Good signature from "Thomas Huth <th.huth@gmx.de>" [full]
# gpg: aka "Thomas Huth <thuth@redhat.com>" [full]
# gpg: aka "Thomas Huth <huth@tuxfamily.org>" [full]
# gpg: aka "Thomas Huth <th.huth@posteo.de>" [unknown]
# Primary key fingerprint: 27B8 8847 EEE0 2501 18F3 EAB9 2ED9 D774 FE70 2DB5
* tag 'pull-request-2025-03-07' of https://gitlab.com/thuth/qemu:
s390x/pci: indicate QEMU supports relaxed translation for passthrough
s390x/pci: add support for guests that request direct mapping
MAINTAINERS: Add docs/devel/testing/functional.rst to the functional section
doc: add missing 'Asset' type in function test doc
tests/functional/test_virtio_balloon: Only use KVM for running this test
tests/functional: fix race in virtio balloon test
tests/functional: Increase the timeout of the mips64el_replay test
tests/functional/test_mips_malta: Add a network test via the pcnet NIC
tests/functional: Move the code for testing HTTP downloads to a common function
tests/functional: stop output from zstd command when uncompressing
tests/functional: drop unused 'get_tag' method
tests/functional: skip memaddr tests on 32-bit builds
tests/functional: reduce tuxrun maxmem to work on 32-bit hosts
tests/functional: set 'qemu_bin' as an object level field
tests/functional: remove unused 'bin_prefix' variable
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Seems 'Asset' got missed in the documentation by mistake.
Also fix the one spellcheck issue pointed by spellcheck
Signed-off-by: Aditya Gupta <adityag@linux.ibm.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Message-ID: <20250306060706.1982992-1-adityag@linux.ibm.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
Add a derive macro that makes it easy to peel off all the layers of
specialness (UnsafeCell, MaybeUninit, etc.) and just get a pointer
to the wrapped type; and likewise add them back starting from a
*mut.
Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Inspired by the same-named type in Linux. This type provides the compiler
with a correct view of what goes on with FFI types. In addition, it
separates the glue code from the bindgen-generated code, allowing
traits such as Send, Sync or Zeroable to be specified independently
for C and Rust structs.
Reviewed-by: Zhao Liu <zhao1.liu@intel.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
QAPI's 'prefix' feature can make the connection between enumeration
type and its constants less than obvious. It's best used with
restraint. Commit 7bbadc60b5..64f5e9db77 eliminated most uses.
Discourage new ones.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250228134335.132278-1-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Fixes: ca056f4499 (Python: Drop support for Python 3.7)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250227080757.3978333-2-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
The 'qemu_bin' field is currently set on the class, despite being
accessed as if it were an object instance field with 'self.qemu_bin'.
This is no obvious need to have it as a class field, so move it into
the object instance.
Reviewed-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Message-ID: <20250228102738.3064045-3-berrange@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
This property allows configuring whether to transfer the particular device
state via multifd channels when live migrating that device.
It defaults to AUTO, which means that VFIO device state transfer via
multifd channels is attempted in configurations that otherwise support it.
Signed-off-by: Maciej S. Szmigiero <maciej.szmigiero@oracle.com>
Reviewed-by: Cédric Le Goater <clg@redhat.com>
Link: https://lore.kernel.org/qemu-devel/d6dbb326e3d53c7104d62c96c9e3dd64e1c7b940.1741124640.git.maciej.szmigiero@oracle.com
[ clg: Added documentation ]
Signed-off-by: Cédric Le Goater <clg@redhat.com>
Implement the multifd device state transfer via additional per-device
thread inside save_live_complete_precopy_thread handler.
Switch between doing the data transfer in the new handler and doing it
in the old save_state handler depending if VFIO multifd transfer is enabled
or not.
Signed-off-by: Maciej S. Szmigiero <maciej.szmigiero@oracle.com>
Reviewed-by: Cédric Le Goater <clg@redhat.com>
Link: https://lore.kernel.org/qemu-devel/4d727e2e0435e0022d50004e474077632830e08d.1741124640.git.maciej.szmigiero@oracle.com
[ clg: - Reordered savevm_vfio_handlers
- Updated save_live_complete_precopy* documentation ]
Signed-off-by: Cédric Le Goater <clg@redhat.com>
Add a thread which loads the VFIO device state buffers that were received
via multifd.
Each VFIO device that has multifd device state transfer enabled has one
such thread, which is created using migration core API
qemu_loadvm_start_load_thread().
Since it's important to finish loading device state transferred via the
main migration channel (via save_live_iterate SaveVMHandler) before
starting loading the data asynchronously transferred via multifd the thread
doing the actual loading of the multifd transferred data is only started
from switchover_start SaveVMHandler.
switchover_start handler is called when MIG_CMD_SWITCHOVER_START
sub-command of QEMU_VM_COMMAND is received via the main migration channel.
This sub-command is only sent after all save_live_iterate data have already
been posted so it is safe to commence loading of the multifd-transferred
device state upon receiving it - loading of save_live_iterate data happens
synchronously in the main migration thread (much like the processing of
MIG_CMD_SWITCHOVER_START) so by the time MIG_CMD_SWITCHOVER_START is
processed all the proceeding data must have already been loaded.
Signed-off-by: Maciej S. Szmigiero <maciej.szmigiero@oracle.com>
Reviewed-by: Cédric Le Goater <clg@redhat.com>
Link: https://lore.kernel.org/qemu-devel/9abe612d775aaf42e31646796acd2363c723a57a.1741124640.git.maciej.szmigiero@oracle.com
[ clg: - Reordered savevm_vfio_handlers
- Added switchover_start documentation ]
Signed-off-by: Cédric Le Goater <clg@redhat.com>
The multifd received data needs to be reassembled since device state
packets sent via different multifd channels can arrive out-of-order.
Therefore, each VFIO device state packet carries a header indicating its
position in the stream.
The raw device state data is saved into a VFIOStateBuffer for later
in-order loading into the device.
The last such VFIO device state packet should have
VFIO_DEVICE_STATE_CONFIG_STATE flag set and carry the device config state.
Signed-off-by: Maciej S. Szmigiero <maciej.szmigiero@oracle.com>
Reviewed-by: Cédric Le Goater <clg@redhat.com>
Link: https://lore.kernel.org/qemu-devel/e3bff515a8d61c582b94b409eb12a45b1a143a69.1741124640.git.maciej.szmigiero@oracle.com
[ clg: - Reordered savevm_vfio_handlers
- Added load_state_buffer documentation ]
Signed-off-by: Cédric Le Goater <clg@redhat.com>
As an outcome of KVM forum 2024 "vfio-platform: live and let die?"
talk, let's deprecate vfio-platform devices.
Signed-off-by: Eric Auger <eric.auger@redhat.com>
Reviewed-by: Cédric Le Goater <clg@redhat.com>
Link: https://lore.kernel.org/qemu-devel/20250305124225.952791-1-eric.auger@redhat.com
[ clg: Fixed spelling in vfio-amd-xgbe section ]
Signed-off-by: Cédric Le Goater <clg@redhat.com>
* CSR coverity fixes
* Fix unexpected behavior of vector reduction instructions when vl is 0
* Fix incorrect vlen comparison in prop_vlen_set
* Throw debug exception before page fault
* Remove redundant "hart_idx" masking from APLIC
* Add support for Control Transfer Records Ext
* Remove redundant struct members from the IOMMU
* Remove duplicate definitions from the IOMMU
* Fix tick_offset migration for Goldfish RTC
* Add serial alias in virt machine DTB
* Remove Bin Meng from RISC-V maintainers
* Add support for Control Transfer Records Ext
* Log guest errors when reserved bits are set in PTEs
* Add missing Sdtrig disas CSRs
* Correct the hpmevent sscofpmf mask
* Mask upper sscofpmf bits during validation
* Remove warnings about Smdbltrp/Smrnmi being disabled
* Respect mseccfg.RLB bit for TOR mode PMP entry
* Update KVM support to Linux 6.14-rc3
* IOMMU HPM support
* Support Sscofpmf/Svade/Svadu/Smnpm/Ssnpm extensions in KVM
* Add --ignore-family option to binfmt
* Refinement for AIA with KVM acceleration
* Reset time changes for KVM
-----BEGIN PGP SIGNATURE-----
iQIzBAABCAAdFiEEaukCtqfKh31tZZKWr3yVEwxTgBMFAmfHrkEACgkQr3yVEwxT
gBNGTA/+N9nBPZt5cv0E/0EDZMQS8RQrQvz1yHRgAXOq8RnOdcL72v8wovGAfnVu
l0BXDoVBvw4f2Xm9Q4ptlfH8HAefCeQ4E/K9j5Lwxr8OqZHFg6e+JQIyZOt6wBWI
hJbz1/laJIbXq3cGgwcE/l0aGfb2UAAsA4dsZVt/MnjAV8GS7BF9RCkgCPxD4FZA
0PLiq9dF+4o4q7PxnxAbUVz/uhLzqmcnQemQFHbf9Wms3tZEDKmPSoKP/v+01Rkw
tm+cgy7OocpgygbMc0nykYG50P+raUBSesk/jFGeKj8cU4IeMuzDsVPWcd4rG+0X
Z+nENfOY7vOqMCXgaQCW2r4vEQx2Gj0yQG6xmVAemRWzFHJdz5W01/uUSHzJSB+L
+VbAH55HYKr6sbgecqInQ/rsHKyw6D5QFcj/guz+kvhsH9rJ5q60uywrWL5OEuaK
vKv7cSZghlf9bwy6soassXxk8z+j4psJ7WnnVpynNKMew9yFFDhayuIFbo9952gH
3+NCm2cQrkTYJOXAJwkxBD+I4AXxNSuxNjaVANk9q80uqbT9JiHM7pcvbJI00Fji
OutJSPYtVXEin9Ev3sJ05YQHsIcZ/Noi3O5IdaRI0AMk/8gyGyhFCVgSpV52dH59
HguPK05e5cW/xgElGUPHrU+UtzE05p18HnSoVPclF/B5rc8QXN0=
=dobk
-----END PGP SIGNATURE-----
Merge tag 'pull-riscv-to-apply-20250305-1' of https://github.com/alistair23/qemu into staging
Third RISC-V PR for 10.0
* CSR coverity fixes
* Fix unexpected behavior of vector reduction instructions when vl is 0
* Fix incorrect vlen comparison in prop_vlen_set
* Throw debug exception before page fault
* Remove redundant "hart_idx" masking from APLIC
* Add support for Control Transfer Records Ext
* Remove redundant struct members from the IOMMU
* Remove duplicate definitions from the IOMMU
* Fix tick_offset migration for Goldfish RTC
* Add serial alias in virt machine DTB
* Remove Bin Meng from RISC-V maintainers
* Add support for Control Transfer Records Ext
* Log guest errors when reserved bits are set in PTEs
* Add missing Sdtrig disas CSRs
* Correct the hpmevent sscofpmf mask
* Mask upper sscofpmf bits during validation
* Remove warnings about Smdbltrp/Smrnmi being disabled
* Respect mseccfg.RLB bit for TOR mode PMP entry
* Update KVM support to Linux 6.14-rc3
* IOMMU HPM support
* Support Sscofpmf/Svade/Svadu/Smnpm/Ssnpm extensions in KVM
* Add --ignore-family option to binfmt
* Refinement for AIA with KVM acceleration
* Reset time changes for KVM
# -----BEGIN PGP SIGNATURE-----
#
# iQIzBAABCAAdFiEEaukCtqfKh31tZZKWr3yVEwxTgBMFAmfHrkEACgkQr3yVEwxT
# gBNGTA/+N9nBPZt5cv0E/0EDZMQS8RQrQvz1yHRgAXOq8RnOdcL72v8wovGAfnVu
# l0BXDoVBvw4f2Xm9Q4ptlfH8HAefCeQ4E/K9j5Lwxr8OqZHFg6e+JQIyZOt6wBWI
# hJbz1/laJIbXq3cGgwcE/l0aGfb2UAAsA4dsZVt/MnjAV8GS7BF9RCkgCPxD4FZA
# 0PLiq9dF+4o4q7PxnxAbUVz/uhLzqmcnQemQFHbf9Wms3tZEDKmPSoKP/v+01Rkw
# tm+cgy7OocpgygbMc0nykYG50P+raUBSesk/jFGeKj8cU4IeMuzDsVPWcd4rG+0X
# Z+nENfOY7vOqMCXgaQCW2r4vEQx2Gj0yQG6xmVAemRWzFHJdz5W01/uUSHzJSB+L
# +VbAH55HYKr6sbgecqInQ/rsHKyw6D5QFcj/guz+kvhsH9rJ5q60uywrWL5OEuaK
# vKv7cSZghlf9bwy6soassXxk8z+j4psJ7WnnVpynNKMew9yFFDhayuIFbo9952gH
# 3+NCm2cQrkTYJOXAJwkxBD+I4AXxNSuxNjaVANk9q80uqbT9JiHM7pcvbJI00Fji
# OutJSPYtVXEin9Ev3sJ05YQHsIcZ/Noi3O5IdaRI0AMk/8gyGyhFCVgSpV52dH59
# HguPK05e5cW/xgElGUPHrU+UtzE05p18HnSoVPclF/B5rc8QXN0=
# =dobk
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 05 Mar 2025 09:52:01 HKT
# gpg: using RSA key 6AE902B6A7CA877D6D659296AF7C95130C538013
# gpg: Good signature from "Alistair Francis <alistair@alistair23.me>" [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: 6AE9 02B6 A7CA 877D 6D65 9296 AF7C 9513 0C53 8013
* tag 'pull-riscv-to-apply-20250305-1' of https://github.com/alistair23/qemu: (59 commits)
target/riscv/kvm: add missing KVM CSRs
target/riscv/kvm: add kvm_riscv_reset_regs_csr()
target/riscv/cpu: remove unneeded !kvm_enabled() check
hw/intc/aplic: refine kvm_msicfgaddr
hw/intc/aplic: refine the APLIC realize
hw/intc/imsic: refine the IMSIC realize
binfmt: Add --ignore-family option
binfmt: Normalize host CPU architecture
binfmt: Shuffle things around
target/riscv/kvm: Add some exts support
docs/specs/riscv-iommu.rst: add HPM support info
hw/riscv: add IOMMU HPM trace events
hw/riscv/riscv-iommu.c: add RISCV_IOMMU_CAP_HPM cap
hw/riscv/riscv-iommu: add hpm events mmio write
hw/riscv/riscv-iommu: add IOHPMCYCLES mmio write
hw/riscv/riscv-iommu: add IOCOUNTINH mmio writes
hw/riscv/riscv-iommu: instantiate hpm_timer
hw/riscv/riscv-iommu: add riscv_iommu_hpm_incr_ctr()
hw/riscv/riscv-iommu: add riscv-iommu-hpm file
hw/riscv/riscv-iommu-bits.h: HPM bits
...
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Apple defines a new "vmapple" machine type as part of its proprietary
macOS Virtualization.Framework vmm. This machine type is similar to the
virt one, but with subtle differences in base devices, a few special
vmapple device additions and a vastly different boot chain.
This patch reimplements this machine type in QEMU. To use it, you
have to have a readily installed version of macOS for VMApple,
run on macOS with -accel hvf, pass the Virtualization.Framework
boot rom (AVPBooter) in via -bios, pass the aux and root volume as pflash
and pass aux and root volume as virtio drives. In addition, you also
need to find the machine UUID and pass that as -M vmapple,uuid= parameter:
$ qemu-system-aarch64 -accel hvf -M vmapple,uuid=0x1234 -m 4G \
-bios /System/Library/Frameworks/Virtualization.framework/Versions/A/Resources/AVPBooter.vmapple2.bin
-drive file=aux,if=pflash,format=raw \
-drive file=root,if=pflash,format=raw \
-drive file=aux,if=none,id=aux,format=raw \
-device vmapple-virtio-blk-pci,variant=aux,drive=aux \
-drive file=root,if=none,id=root,format=raw \
-device vmapple-virtio-blk-pci,variant=root,drive=root
With all these in place, you should be able to see macOS booting
successfully.
Known issues:
- Currently only macOS 12 guests are supported. The boot process for
13+ will need further investigation and adjustment.
Signed-off-by: Alexander Graf <graf@amazon.com>
Co-authored-by: Phil Dennis-Jordan <phil@philjordan.eu>
Signed-off-by: Phil Dennis-Jordan <phil@philjordan.eu>
Reviewed-by: Akihiko Odaki <akihiko.odaki@daynix.com>
Tested-by: Akihiko Odaki <akihiko.odaki@daynix.com>
Message-ID: <20241223221645.29911-15-phil@philjordan.eu>
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
Since commit 3c5f6114 (qapi: remove "Example" doc section), Example
sections no longer exist, so this support in qapidoc is now dead code.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250224033741.222749-7-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
