aboutsummaryrefslogtreecommitdiff
path: root/qapi
AgeCommit message (Collapse)AuthorFilesLines
2024-09-13system: Remove support for CRIS targetPhilippe Mathieu-Daudé1-1/+1
We are about to remove the CRIS target, so remove the sysemu part. This remove the CRIS 'none' machine. Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Acked-by: Edgar E. Iglesias <edgar.iglesias@amd.com> Message-ID: <20240904143603.52934-13-philmd@linaro.org>
2024-09-10Merge tag 'pull-qapi-2024-09-10' of https://repo.or.cz/qemu/armbru into stagingPeter Maydell10-62/+47
QAPI patches patches for 2024-09-10 # -----BEGIN PGP SIGNATURE----- # # iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmbgS0ASHGFybWJydUBy # ZWRoYXQuY29tAAoJEDhwtADrkYZTm+sP/1kEuGdbjjVLQC7U+gCClhALpYUtIMHQ # qNZWmnxFyW9Jx6Lk8+FZBRJegNlmA9AJ2ZzD/2I/WoNtcrNiE53rIRG71Lcy8I6U # CRjekLPn0jhFuYhmRfwz6ilcLkyMJ15Yi7iG6ssFsO1joBtU5Q1qpzQmFUl9UbV9 # 9iBe7mE99VzNwi3hMELEM9YuSgAs8st4Itnn8SiHkJ3s6hlmF8N4HwNKfQrseGfb # FuJNN4p8Gcu0aF/dkGE8ADJBvtgzkFnavXt0GQPC7SjGOF7rUXxnUQlszNZM0OcK # UAfWU06sIyiOholQQt8H8jawT+rGCLomfgPUBVq5K8WByd21IeQeS0upSPeTjxS+ # d/C8wzpcbhdNOECwC/wDtgZHvCC95cHNrxuC4+4/Q1KIVVr+1cWqe8hQzFvm3TIg # dduEFTQDIxhpE0GO1ZWNf90upzBYBWwIsh4bqsMZS7SpaYIZ6QV45yViZ1w2WfbH # m3/F34Z3yqgFuZQrZv4OPo7xHK0+y7uZ60RrhSJtE0X080syRJKBbGmNBRidoVyu # JOONWH44I/XN5enZV8StJnqJr9MCV0DBZUCi9ZhP/kAhBjLc5cQ6NByEa9/rebYX # 1bLTiA1JDLzDVIan+A8dz0riWmHBvTyBwhLnEXvXb9lcB3ozgHTb7axE5RnZSYLI # YQgBOBMFuQKM # =YO/Q # -----END PGP SIGNATURE----- # gpg: Signature made Tue 10 Sep 2024 14:36:00 BST # gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653 # gpg: issuer "armbru@redhat.com" # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full] # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full] # Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867 4E5F 3870 B400 EB91 8653 * tag 'pull-qapi-2024-09-10' of https://repo.or.cz/qemu/armbru: qapi/vfio: Rename VfioMigrationState to Qapi*, and drop prefix qapi/cryptodev: Rename QCryptodevBackendAlgType to *Algo, and drop prefix qapi/cryptodev: Drop unwanted 'prefix' qapi/crypto: Rename QCryptoAFAlg to QCryptoAFAlgo qapi/crypto: Rename QCryptoRSAPaddingAlgorithm to *Algo, and drop prefix qapi/crypto: Rename QCryptoAkCipherAlgorithm to *Algo, and drop prefix qapi/crypto: Rename QCryptoIVGenAlgorithm to *Algo, and drop prefix qapi/crypto: Rename QCryptoCipherAlgorithm to *Algo, and drop prefix qapi/crypto: Rename QCryptoHashAlgorithm to *Algo, and drop prefix qapi/crypto: Drop unwanted 'prefix' qapi/machine: Rename CpuS390* to S390Cpu*, and drop 'prefix' qapi/ui: Drop temporary 'prefix' qapi/machine: Drop temporary 'prefix' qapi/ebpf: Drop temporary 'prefix' qapi/crypto: Drop temporary 'prefix' qapi/common: Drop temporary 'prefix' qapi/block-core: Drop temporary 'prefix' tests/qapi-schema: Drop temporary 'prefix' qapi: Smarter camel_to_upper() to reduce need for 'prefix' Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2024-09-10qapi/vfio: Rename VfioMigrationState to Qapi*, and drop prefixMarkus Armbruster1-5/+4
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. VfioMigrationState has a 'prefix' that overrides the generated enumeration constants' prefix to QAPI_VFIO_MIGRATION_STATE. We could simply drop 'prefix', but then the enumeration constants would look as if they came from kernel header linux/vfio.h. Rename the type to QapiVfioMigrationState instead, so that 'prefix' is not needed. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240904111836.3273842-20-armbru@redhat.com> Reviewed-by: Cédric Le Goater <clg@redhat.com>
2024-09-10qapi/cryptodev: Rename QCryptodevBackendAlgType to *Algo, and drop prefixMarkus Armbruster1-3/+2
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptodevBackendAlgType has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTODEV_BACKEND_ALG. We could simply drop 'prefix', but I think the abbreviation "alg" is less than clear. Additionally rename the type to QCryptodevBackendAlgoType. The prefix becomes QCRYPTODEV_BACKEND_ALGO_TYPE. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-19-armbru@redhat.com>
2024-09-10qapi/cryptodev: Drop unwanted 'prefix'Markus Armbruster1-1/+0
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptodevBackendServiceType has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTODEV_BACKEND_SERVICE. Drop it. The prefix becomes QCRYPTODEV_BACKEND_SERVICE_TYPE. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-18-armbru@redhat.com>
2024-09-10qapi/crypto: Rename QCryptoRSAPaddingAlgorithm to *Algo, and drop prefixMarkus Armbruster1-5/+4
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptoRSAPaddingAlgorithm has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTO_RSA_PADDING_ALG. We could simply drop 'prefix', but then the prefix becomes QCRYPTO_RSA_PADDING_ALGORITHM, which is rather long. We could additionally rename the type to QCryptoRSAPaddingAlg, but I think the abbreviation "alg" is less than clear. Rename the type to QCryptoRSAPaddingAlgo instead. The prefix becomes QCRYPTO_RSA_PADDING_ALGO. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-16-armbru@redhat.com>
2024-09-10qapi/crypto: Rename QCryptoAkCipherAlgorithm to *Algo, and drop prefixMarkus Armbruster1-4/+3
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptoAkCipherAlgorithm has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTO_AKCIPHER_ALG. We could simply drop 'prefix', but then the prefix becomes QCRYPTO_AK_CIPHER_ALGORITHM, which is rather long. We could additionally rename the type to QCryptoAkCipherAlg, but I think the abbreviation "alg" is less than clear. Rename the type to QCryptoAkCipherAlgo instead. The prefix becomes QCRYPTO_AK_CIPHER_ALGO. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-15-armbru@redhat.com>
2024-09-10qapi/crypto: Rename QCryptoIVGenAlgorithm to *Algo, and drop prefixMarkus Armbruster1-5/+4
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptoIVGenAlgorithm has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTO_IVGEN_ALG. We could simply drop 'prefix', but then the prefix becomes QCRYPTO_IV_GEN_ALGORITHM, which is rather long. We could additionally rename the type to QCryptoIVGenAlg, but I think the abbreviation "alg" is less than clear. Rename the type to QCryptoIVGenAlgo instead. The prefix becomes QCRYPTO_IV_GEN_ALGO. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-14-armbru@redhat.com>
2024-09-10qapi/crypto: Rename QCryptoCipherAlgorithm to *Algo, and drop prefixMarkus Armbruster2-6/+5
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptoCipherAlgorithm has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTO_CIPHER_ALG. We could simply drop 'prefix', but then the prefix becomes QCRYPTO_CIPHER_ALGORITHM, which is rather long. We could additionally rename the type to QCryptoCipherAlg, but I think the abbreviation "alg" is less than clear. Rename the type to QCryptoCipherAlgo instead. The prefix becomes QCRYPTO_CIPHER_ALGO. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-13-armbru@redhat.com>
2024-09-10qapi/crypto: Rename QCryptoHashAlgorithm to *Algo, and drop prefixMarkus Armbruster1-9/+8
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptoHashAlgorithm has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTO_HASH_ALG. We could simply drop 'prefix', but then the prefix becomes QCRYPTO_HASH_ALGORITHM, which is rather long. We could additionally rename the type to QCryptoHashAlg, but I think the abbreviation "alg" is less than clear. Rename the type to QCryptoHashAlgo instead. The prefix becomes to QCRYPTO_HASH_ALGO. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-12-armbru@redhat.com> [Conflicts with merge commit 7bbadc60b58b resolved]
2024-09-10qapi/crypto: Drop unwanted 'prefix'Markus Armbruster1-1/+0
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. QCryptoAkCipherKeyType has a 'prefix' that overrides the generated enumeration constants' prefix to QCRYPTO_AKCIPHER_KEY_TYPE. Drop it. The prefix becomes QCRYPTO_AK_CIPHER_KEY_TYPE. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-11-armbru@redhat.com>
2024-09-10qapi/machine: Rename CpuS390* to S390Cpu*, and drop 'prefix'Markus Armbruster4-17/+14
QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. CpuS390Entitlement has a 'prefix' to change the generated enumeration constants' prefix from CPU_S390_ENTITLEMENT to S390_CPU_ENTITLEMENT. Rename the type to S390CpuEntitlement, so that 'prefix' is not needed. Likewise change CpuS390Polarization to S390CpuPolarization, and CpuS390State to S390CpuState. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Zhao Liu <zhao1.liu@intel.com> Acked-by: Thomas Huth <thuth@redhat.com> Message-ID: <20240904111836.3273842-10-armbru@redhat.com>
2024-09-10qapi/ui: Drop temporary 'prefix'Markus Armbruster1-1/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added a temporary 'prefix' to delay changing the generated code. Revert it. This improves DisplayGLMode's generated enumeration constant prefix from DISPLAYGL_MODE to DISPLAY_GL_MODE. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240904111836.3273842-9-armbru@redhat.com>
2024-09-10qapi/machine: Drop temporary 'prefix'Markus Armbruster1-2/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added a temporary 'prefix' to delay changing the generated code. Revert it. This improves HmatLBDataType's generated enumeration constant prefix from HMATLB_DATA_TYPE to HMAT_LB_DATA_TYPE, and HmatLBMemoryHierarchy's from HMATLB_MEMORY_HIERARCHY to HMAT_LB_MEMORY_HIERARCHY. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Zhao Liu <zhao1.liu@intel.com> Message-ID: <20240904111836.3273842-8-armbru@redhat.com>
2024-09-10qapi/ebpf: Drop temporary 'prefix'Markus Armbruster1-1/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added a temporary 'prefix' to delay changing the generated code. Revert it. This improves EbpfProgramID's generated enumeration constant prefix from EBPF_PROGRAMID to EBPF_PROGRAM_ID. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240904111836.3273842-7-armbru@redhat.com>
2024-09-10qapi/crypto: Drop temporary 'prefix'Markus Armbruster1-2/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added two temporary 'prefix' to delay changing the generated code. Revert them. This improves QCryptoBlockFormat's generated enumeration constant prefix from Q_CRYPTO_BLOCK_FORMAT to QCRYPTO_BLOCK_FORMAT, and QCryptoBlockLUKSKeyslotState's from Q_CRYPTO_BLOCKLUKS_KEYSLOT_STATE to QCRYPTO_BLOCK_LUKS_KEYSLOT_STATE. Signed-off-by: Markus Armbruster <armbru@redhat.com> Acked-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-6-armbru@redhat.com>
2024-09-10qapi/common: Drop temporary 'prefix'Markus Armbruster1-1/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added a temporary 'prefix' to delay changing the generated code. Revert it. This improves OffAutoPCIBAR's generated enumeration constant prefix from OFF_AUTOPCIBAR to OFF_AUTO_PCIBAR. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Cédric Le Goater <clg@redhat.com> Message-ID: <20240904111836.3273842-5-armbru@redhat.com>
2024-09-10qapi/block-core: Drop temporary 'prefix'Markus Armbruster1-1/+0
Recent commit "qapi: Smarter camel_to_upper() to reduce need for 'prefix'" added a temporary 'prefix' to delay changing the generated code. Revert it. This improves XDbgBlockGraphNodeType's generated enumeration constant prefix from X_DBG_BLOCK_GRAPH_NODE_TYPE_BLOCK_BACKEND to XDBG_BLOCK_GRAPH_NODE_TYPE_BLOCK_BACKEND. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240904111836.3273842-4-armbru@redhat.com>
2024-09-10qapi: Smarter camel_to_upper() to reduce need for 'prefix'Markus Armbruster8-6/+11
camel_to_upper() converts its argument from camel case to upper case with '_' between words. Used for generated enumeration constant prefixes. When some of the words are spelled all caps, where exactly to insert '_' is guesswork. camel_to_upper()'s guesses are bad enough in places to make people override them with a 'prefix' in the schema. Rewrite it to guess better: 1. Insert '_' after a non-upper case character followed by an upper case character: OneTwo -> ONE_TWO One2Three -> ONE2_THREE 2. Insert '_' before the last upper case character followed by a non-upper case character: ACRONYMWord -> ACRONYM_Word Except at the beginning (as in OneTwo above), or when there is already one: AbCd -> AB_CD This changes the default enumeration constant prefix for a number of enums. Generated enumeration constants change only where the default is not overridden with 'prefix'. The following enumerations without a 'prefix' change: enum old camel_to_upper() new camel_to_upper() ------------------------------------------------------------------ DisplayGLMode DISPLAYGL_MODE DISPLAY_GL_MODE EbpfProgramID EBPF_PROGRAMID EBPF_PROGRAM_ID HmatLBDataType HMATLB_DATA_TYPE HMAT_LB_DATA_TYPE HmatLBMemoryHierarchy HMATLB_MEMORY_HIERARCHY HMAT_LB_MEMORY_HIERARCHY MultiFDCompression MULTIFD_COMPRESSION MULTI_FD_COMPRESSION OffAutoPCIBAR OFF_AUTOPCIBAR OFF_AUTO_PCIBAR QCryptoBlockFormat Q_CRYPTO_BLOCK_FORMAT QCRYPTO_BLOCK_FORMAT QCryptoBlockLUKSKeyslotState Q_CRYPTO_BLOCKLUKS_KEYSLOT_STATE QCRYPTO_BLOCK_LUKS_KEYSLOT_STATE QKeyCode Q_KEY_CODE QKEY_CODE XDbgBlockGraphNodeType X_DBG_BLOCK_GRAPH_NODE_TYPE XDBG_BLOCK_GRAPH_NODE_TYPE TestUnionEnumA TEST_UNION_ENUMA TEST_UNION_ENUM_A Add a 'prefix' so generated code doesn't change now. Subsequent commits will remove most of them again. Two will remain: MULTIFD_COMPRESSION, because migration code generally spells "multifd" that way, and Q_KEY_CODE, because that one is baked into subprojects/keycodemapdb/tools/keymap-gen. The following enumerations with a 'prefix' change so that the prefix is now superfluous: enum old camel_to_upper() new camel_to_upper() [equal to prefix] ------------------------------------------------------------------ BlkdebugIOType BLKDEBUGIO_TYPE BLKDEBUG_IO_TYPE QCryptoTLSCredsEndpoint Q_CRYPTOTLS_CREDS_ENDPOINT QCRYPTO_TLS_CREDS_ENDPOINT QCryptoSecretFormat Q_CRYPTO_SECRET_FORMAT QCRYPTO_SECRET_FORMAT QCryptoCipherMode Q_CRYPTO_CIPHER_MODE QCRYPTO_CIPHER_MODE QCryptodevBackendType Q_CRYPTODEV_BACKEND_TYPE QCRYPTODEV_BACKEND_TYPE QType [builtin] Q_TYPE QTYPE Drop these prefixes. The following enumerations with a 'prefix' change without making the 'prefix' superfluous: enum old camel_to_upper() new camel_to_upper() [equal to prefix] prefix ------------------------------------------------------------------ CpuS390Entitlement CPUS390_ENTITLEMENT CPU_S390_ENTITLEMENT S390_CPU_ENTITLEMENT CpuS390Polarization CPUS390_POLARIZATION CPU_S390_POLARIZATION S390_CPU_POLARIZATION CpuS390State CPUS390_STATE CPU_S390_STATE S390_CPU_STATE QAuthZListFormat Q_AUTHZ_LIST_FORMAT QAUTH_Z_LIST_FORMAT QAUTHZ_LIST_FORMAT QAuthZListPolicy Q_AUTHZ_LIST_POLICY QAUTH_Z_LIST_POLICY QAUTHZ_LIST_POLICY QCryptoAkCipherAlgorithm Q_CRYPTO_AK_CIPHER_ALGORITHM QCRYPTO_AK_CIPHER_ALGORITHM QCRYPTO_AKCIPHER_ALG QCryptoAkCipherKeyType Q_CRYPTO_AK_CIPHER_KEY_TYPE QCRYPTO_AK_CIPHER_KEY_TYPE QCRYPTO_AKCIPHER_KEY_TYPE QCryptoCipherAlgorithm Q_CRYPTO_CIPHER_ALGORITHM QCRYPTO_CIPHER_ALGORITHM QCRYPTO_CIPHER_ALG QCryptoHashAlgorithm Q_CRYPTO_HASH_ALGORITHM QCRYPTO_HASH_ALGORITHM QCRYPTO_HASH_ALG QCryptoIVGenAlgorithm Q_CRYPTOIV_GEN_ALGORITHM QCRYPTO_IV_GEN_ALGORITHM QCRYPTO_IVGEN_ALG QCryptoRSAPaddingAlgorithm Q_CRYPTORSA_PADDING_ALGORITHM QCRYPTO_RSA_PADDING_ALGORITHM QCRYPTO_RSA_PADDING_ALG QCryptodevBackendAlgType Q_CRYPTODEV_BACKEND_ALG_TYPE QCRYPTODEV_BACKEND_ALG_TYPE QCRYPTODEV_BACKEND_ALG QCryptodevBackendServiceType Q_CRYPTODEV_BACKEND_SERVICE_TYPE QCRYPTODEV_BACKEND_SERVICE_TYPE QCRYPTODEV_BACKEND_SERVICE Subsequent commits will tweak things to remove most of these prefixes. Only QAUTHZ_LIST_FORMAT and QAUTHZ_LIST_POLICY will remain. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240904111836.3273842-2-armbru@redhat.com>
2024-09-09migration: Introduce 'qatzip' compression methodBryan Zhang1-0/+3
Adds support for 'qatzip' as an option for the multifd compression method parameter, and implements using QAT for 'qatzip' compression and decompression. Acked-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Fabiano Rosas <farosas@suse.de> Reviewed-by: Prasad Pandit <pjp@fedoraproject.org> Signed-off-by: Bryan Zhang <bryan.zhang@bytedance.com> Signed-off-by: Hao Xiang <hao.xiang@linux.dev> Signed-off-by: Yichen Wang <yichen.wang@bytedance.com> Link: https://lore.kernel.org/r/20240830232722.58272-5-yichen.wang@bytedance.com Signed-off-by: Peter Xu <peterx@redhat.com>
2024-09-09migration: Add migration parameters for QATzipBryan Zhang1-0/+18
Adds support for migration parameters to control QATzip compression level. Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Bryan Zhang <bryan.zhang@bytedance.com> Signed-off-by: Hao Xiang <hao.xiang@linux.dev> Signed-off-by: Yichen Wang <yichen.wang@bytedance.com> Reviewed-by: Fabiano Rosas <farosas@suse.de> Reviewed-by: Prasad Pandit <pjp@fedoraproject.org> Link: https://lore.kernel.org/r/20240830232722.58272-4-yichen.wang@bytedance.com Signed-off-by: Peter Xu <peterx@redhat.com>
2024-08-16docs: Fix some typos (found by typos) and grammar issuesStefan Weil1-2/+2
Fix the misspellings of "overriden" also in code comments. Signed-off-by: Stefan Weil <sw@weilnetz.de> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20240813125638.395461-1-sw@weilnetz.de> Reviewed-by: Peter Xu <peterx@redhat.com> Reviewed-by: Eric Auger <eric.auger@redhat.com> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240813202329.1237572-20-alex.bennee@linaro.org>
2024-08-08nbd/server: CVE-2024-7409: Cap default max-connections to 100Eric Blake1-2/+2
Allowing an unlimited number of clients to any web service is a recipe for a rudimentary denial of service attack: the client merely needs to open lots of sockets without closing them, until qemu no longer has any more fds available to allocate. For qemu-nbd, we default to allowing only 1 connection unless more are explicitly asked for (-e or --shared); this was historically picked as a nice default (without an explicit -t, a non-persistent qemu-nbd goes away after a client disconnects, without needing any additional follow-up commands), and we are not going to change that interface now (besides, someday we want to point people towards qemu-storage-daemon instead of qemu-nbd). But for qemu proper, and the newer qemu-storage-daemon, the QMP nbd-server-start command has historically had a default of unlimited number of connections, in part because unlike qemu-nbd it is inherently persistent until nbd-server-stop. Allowing multiple client sockets is particularly useful for clients that can take advantage of MULTI_CONN (creating parallel sockets to increase throughput), although known clients that do so (such as libnbd's nbdcopy) typically use only 8 or 16 connections (the benefits of scaling diminish once more sockets are competing for kernel attention). Picking a number large enough for typical use cases, but not unlimited, makes it slightly harder for a malicious client to perform a denial of service merely by opening lots of connections withot progressing through the handshake. This change does not eliminate CVE-2024-7409 on its own, but reduces the chance for fd exhaustion or unlimited memory usage as an attack surface. On the other hand, by itself, it makes it more obvious that with a finite limit, we have the problem of an unauthenticated client holding 100 fds opened as a way to block out a legitimate client from being able to connect; thus, later patches will further add timeouts to reject clients that are not making progress. This is an INTENTIONAL change in behavior, and will break any client of nbd-server-start that was not passing an explicit max-connections parameter, yet expects more than 100 simultaneous connections. We are not aware of any such client (as stated above, most clients aware of MULTI_CONN get by just fine on 8 or 16 connections, and probably cope with later connections failing by relying on the earlier connections; libvirt has not yet been passing max-connections, but generally creates NBD servers with the intent for a single client for the sake of live storage migration; meanwhile, the KubeSAN project anticipates a large cluster sharing multiple clients [up to 8 per node, and up to 100 nodes in a cluster], but it currently uses qemu-nbd with an explicit --shared=0 rather than qemu-storage-daemon with nbd-server-start). We considered using a deprecation period (declare that omitting max-parameters is deprecated, and make it mandatory in 3 releases - then we don't need to pick an arbitrary default); that has zero risk of breaking any apps that accidentally depended on more than 100 connections, and where such breakage might not be noticed under unit testing but only under the larger loads of production usage. But it does not close the denial-of-service hole until far into the future, and requires all apps to change to add the parameter even if 100 was good enough. It also has a drawback that any app (like libvirt) that is accidentally relying on an unlimited default should seriously consider their own CVE now, at which point they are going to change to pass explicit max-connections sooner than waiting for 3 qemu releases. Finally, if our changed default breaks an app, that app can always pass in an explicit max-parameters with a larger value. It is also intentional that the HMP interface to nbd-server-start is not changed to expose max-connections (any client needing to fine-tune things should be using QMP). Suggested-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com> Message-ID: <20240807174943.771624-12-eblake@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> [ericb: Expand commit message to summarize Dan's argument for why we break corner-case back-compat behavior without a deprecation period] Signed-off-by: Eric Blake <eblake@redhat.com>
2024-08-06qapi-block-core: Clean up blockdev-snapshot-internal-sync docMarkus Armbruster1-4/+3
BlockdevSnapshotInternal is the arguments type of command blockdev-snapshot-internal-sync. Its doc comment contains this note: # .. note:: In a transaction, if @name is empty or any snapshot matching # @name exists, the operation will fail. Only some image formats # support it; for example, qcow2, and rbd. "In a transaction" is misleading, and "if @name is empty or any snapshot matching @name exists, the operation will fail" is redundant with the command's Errors documentation. Drop. The remainder is fine. Move it to the command's doc comment, where it is more prominently visible, with a slight rephrasing for clarity. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240718123609.3063055-1-armbru@redhat.com> Reviewed-by: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
2024-08-05qmp: Fix higher half vaddrs for [p]memsaveJosh Junon1-2/+9
Fixes higher-half address parsing for QMP commands `[p]memsave`. Signed-off-by: Josh Junon <junon@oro.sh> Message-ID: <20240802140704.13591-1-junon@oro.sh> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Subject tweaked, and one PRId64 updated to PRIu64] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-08-05qapi: Refill doc comments to conform to conventionsMarkus Armbruster27-250/+262
Sweep the entire documentation again. Last done in commit 209e64d9edf (qapi: Refill doc comments to conform to current conventions). To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240729065220.860163-1-armbru@redhat.com> [Straightforward conflict with commit 442110bc6f3 resolved]
2024-07-30Merge tag 's390x-20240730' of https://github.com/davidhildenbrand/qemu into ↵Richard Henderson1-8/+11
staging s390x updates: - fixup for a s390x-only query-cpu-model-expansion extension # -----BEGIN PGP SIGNATURE----- # # iQJFBAABCAAvFiEEG9nKrXNcTDpGDfzKTd4Q9wD/g1oFAmaonmkRHGRhdmlkQHJl # ZGhhdC5jb20ACgkQTd4Q9wD/g1pCQBAAiHHoKssyl5xdEWid92OnpEK499xngBBS # zRJAZVmidnuTRbaAd0bB4rfwO13KKCwvWwKCjFG9tkH4QFTdXKnDzoLWTjy9Ytg3 # jB6L91sbMgySPBlXEqVkFh8WIkpVhcd9FVfSddw4QTnunyGAxTVNIhZFgBdVLXH3 # 2MLOd33FgkwiK+9gBKPccI/VBTmE2UX2EYrJ7gJOdB3AA5dSQxgQ4dxJEHaN/CcV # jHXLJ6Mcu6sz/qBxiiFcQvbepLSG3odBcuETL/pKcrk/H2YPKT6hIiWPNGFcVD0H # P36+rYo5Sr5KWOFbK4p8PPPnyDqYoOzmhwKTf+uO7sEHSSwiPexYJp6um6onTD3m # MNXl+5jahTePWdKXlJ6+j1DG0uKJnFobaj6P1HM3f37Douq/7fyxrcDuySLEdrSD # CutaQkdhr55WAlVPtmO3EuUc8eYxEGN4aEWSwtw9KWewF/vgq63Zos+p02Fi1mfN # gP8Fmz29gLAMkq57Y85zyMM2rYjfmE9Nt8Zzmnod2O9xuohwg7liqvVDfLo88g7X # czHSG0+O8TwXaanWIGAA4jgpfsNjxu7Qkx+jiB1uqLafj/wok/dOu5Teq3WU5t+i # vEHyI3CCfCH5q+ifNwe5vPQi4b1rZ0sT/cnYBpOhIs4Jroys1D3XXc0pHMJFJ7mz # CKka4wDf6aM= # =wSbp # -----END PGP SIGNATURE----- # gpg: Signature made Tue 30 Jul 2024 06:03:53 PM AEST # gpg: using RSA key 1BD9CAAD735C4C3A460DFCCA4DDE10F700FF835A # gpg: issuer "david@redhat.com" # gpg: Good signature from "David Hildenbrand <david@redhat.com>" [undefined] # gpg: aka "David Hildenbrand <davidhildenbrand@gmail.com>" [full] # gpg: aka "David Hildenbrand <hildenbr@in.tum.de>" [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: 1BD9 CAAD 735C 4C3A 460D FCCA 4DDE 10F7 00FF 835A * tag 's390x-20240730' of https://github.com/davidhildenbrand/qemu: target/s390x: move @deprecated-props to CpuModelExpansion Info Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-29target/s390x: move @deprecated-props to CpuModelExpansion InfoCollin Walling1-8/+11
CpuModelInfo is used both as command argument and in command returns. Its @deprecated-props array does not make any sense in arguments, and is silently ignored. We actually want it only as return value of query-cpu-model-expansion. Move it from CpuModelInfo to CpuModelExpansionType, and document its dependence on expansion type property. This was identified late during review [1] and we have to fix it up while it's not part of an official QEMU release yet. [1] https://lore.kernel.org/qemu-devel/20240719181741.35146-1-walling@linux.ibm.com/ Message-ID: <20240726203646.20279-1-walling@linux.ibm.com> Fixes: eed0e8ffa38f ("target/s390x: filter deprecated properties based on model expansion type") Signed-off-by: Collin Walling <walling@linux.ibm.com> [ david: - add "Fixes", adjust description, reference v3 instead - make property s390x-only and non-optional - fixup "populate" vs. "populated" ] Signed-off-by: David Hildenbrand <david@redhat.com>
2024-07-29qapi/machine: Belatedly document target loongarch64 is since 7.1Markus Armbruster1-0/+2
Fixes: a8a506c39070 (hw/loongarch: Add support loongson3 virt machine type.) Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240718141001.3077709-1-armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Song Gao <gaosong@loongson.cn>
2024-07-29qapi/qom: make some QOM properties depend on the build settingsStefano Garzarella2-8/+16
Some QOM properties are associated with ObjectTypes that already depend on CONFIG_* switches. So to avoid generating dead code, let's also make the definition of those properties dependent on the corresponding CONFIG_*. Suggested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Stefano Garzarella <sgarzare@redhat.com> Message-ID: <20240604135931.311709-1-sgarzare@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Make SecretKeyringProperties conditional, too] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-24qapi: drop unused QCryptoBlockCreateOptionsLUKS.detached-headerDaniel P. Berrangé1-4/+1
The 'detached-header' field in QCryptoBlockCreateOptionsLUKS was left over from earlier patch iterations. Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2024-07-22target/s390x: filter deprecated properties based on model expansion typeCollin Walling1-2/+3
Currently, there is no way to execute the query-cpu-model-expansion command to retrieve a comprehenisve list of deprecated properties, as the result is dependent per-model. To enable this, the expansion output is modified as such: When reporting a "full" CPU model, show the *entire* list of deprecated properties regardless if they are supported on the model. A full expansion outputs all known CPU model properties anyway, so it makes sense to report all deprecated properties here too. This allows management apps to query a single model (e.g. host) to acquire the full list of deprecated properties. Additionally, when reporting a "static" CPU model, the command will only show deprecated properties that are a subset of the model's *enabled* properties. This is more accurate than how the query was handled before, which blindly reported deprecated properties that were never otherwise introduced for certain models. Acked-by: David Hildenbrand <david@redhat.com> Suggested-by: Jiri Denemark <jdenemar@redhat.com> Signed-off-by: Collin Walling <walling@linux.ibm.com> Message-ID: <20240719181741.35146-1-walling@linux.ibm.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
2024-07-18Merge tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru into stagingRichard Henderson26-299/+346
QAPI patches patches for 2024-07-17 # -----BEGIN PGP SIGNATURE----- # # iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaXoUESHGFybWJydUBy # ZWRoYXQuY29tAAoJEDhwtADrkYZTatYP/jPlsmx8S6X397COQf6Wd4oEFQEMo/FS # tWFiHWenPUZ56U3O3lDNIw+5URbhF4aUpxhLGg6cmkrOwK0zPjARI2UNnUnZvPtN # EHf//KJOpYLsSdkIlIW2nYzB27ps0DRf5PgOGdOOdW32Nuq93FLx7ChDgbpmrijc # HzByyJIn1QEv/G0aOMLCuTPA7LpGjCAd2a/LjWYpSXB3WGizrS2Rrat7oJYUl8Rz # mAPgdiE0aH2yWHOTcWabKfN4AsIHCnv7qNOZkumoWpZ0XULbgyK1OO05ju3jRSrB # 0WiwiE8pEhHz7qstKGcjS1c7pPuId64ubm3RAZ1RUqVvA5TZGucwuYiuQHUVX6jH # BGzpfojISFzIfTiKemyfqBb1gjXjxT6OIlCtmlJSUCJohb70f0fhX3vniyhzyl1d # fFTM0jMbmBX89e/o3j6ZXa7anafYNDh5TjTK4BYeAXRqe+jZpvDJUrwu1OZIq1cd # Wr1RR8qaawpfjD5r9SXu1mX5MPCX4SmNVNoQ7N4ruWjpVojQNmuCRW9yLPIv3yTH # c5ESND4zdvceW5EF9f5GSIFwnIdGqnUwJyBMcULGoCxz1HougQmGR4bhqSkEl6RD # GRK+bj3pLdj9f/en62mE6+f5rkEJye3Y5fJ5dn9+Ld09PeUtY59YKnJGg896g55V # /pGOUWf3L4iY # =E0F5 # -----END PGP SIGNATURE----- # gpg: Signature made Wed 17 Jul 2024 08:47:29 PM AEST # gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653 # gpg: issuer "armbru@redhat.com" # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full] # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full] * tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru: qapi: remove "Example" doc section qapi: convert "Example" sections with longer prose qapi: convert "Example" sections with titles qapi: convert "Example" sections without titles docs/sphinx: add CSS styling for qmp-example directive docs/qapidoc: add QMP highlighting to annotated qmp-example blocks docs/qapidoc: create qmp-example directive docs/qapidoc: factor out do_parse() qapi/ui: Drop note on naming of SpiceQueryMouseMode qapi/sockets: Move deprecation note out of SocketAddress doc comment qapi/machine: Clarify query-uuid value when none has been specified qapi/machine: Clean up documentation around CpuInstanceProperties qapi/pci: Clean up documentation around PciDeviceClass qapi/qom: Document feature unstable of @x-vfio-user-server Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-17qapi: convert "Example" sections with longer proseJohn Snow4-29/+62
These examples require longer explanations or have explanations that require markup to look reasonable when rendered and so use the longer form of the ".. qmp-example::" directive. By using the :annotated: option, the content in the example block is assumed *not* to be a code block literal and is instead parsed as normal rST - with the exception that any code literal blocks after `::` will assumed to be a QMP code literal block. Note: There's one title-less conversion in this patch that comes along for the ride because it's part of a larger "Examples" block that was better to convert all at once. See commit-5: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+1: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-9-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17qapi: convert "Example" sections with titlesJohn Snow6-48/+52
When an Example section has a brief explanation, convert it to a qmp-example:: section using the :title: option. Rule of thumb: If the title can fit on a single line and requires no rST markup, it's a good candidate for using the :title: option of qmp-example. In this patch, trailing punctuation is removed from the title section for consistent headline aesthetics. In just one case, specifics of the example are removed to make the title read better. See commit-4: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+2: "qapi: remove "Example" doc section" for a detailed explanation of why. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-8-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17qapi: convert "Example" sections without titlesJohn Snow25-203/+219
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples. See commit-3: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+3: "qapi: remove "Example" doc section" for a detailed explanation of why. Note: an empty "TODO" line was added to announce-self to keep the example from floating up into the body; this will be addressed more rigorously in the new qapidoc generator. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Markup fixed in one place] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17qapi/ui: Drop note on naming of SpiceQueryMouseModeMarkus Armbruster1-2/+0
Doc comments are reference documentation for users of QMP. SpiceQueryMouseMode's doc comment contains a note explaining why it's not named SpiceMouseMode: spice/enums.h has it already. Irrelevant for users of QMP; delete the note. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240711112228.2140606-6-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
2024-07-17qapi/sockets: Move deprecation note out of SocketAddress doc commentMarkus Armbruster1-4/+3
Doc comments are reference documentation for users of QMP. SocketAddress's doc comment contains a deprecation note advising developers to use SocketAddress for new code. Irrelevant for users of QMP. Move the note out of the doc comment. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240711112228.2140606-5-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-17qapi/machine: Clarify query-uuid value when none has been specifiedMarkus Armbruster1-3/+2
When no UUID has been specified, query-uuid returns {"UUID": "00000000-0000-0000-0000-000000000000"} The doc comment calls this "a null UUID", which I find less than clear. RFC 9562 calls it "the nil UUID (all zeroes)", so use that instead. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240711112228.2140606-4-armbru@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> [Wording improved, commit message adjusted] Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-17qapi/machine: Clean up documentation around CpuInstancePropertiesMarkus Armbruster1-7/+6
CpuInstanceProperties' doc comment describes its members as properties to be passed to device_add when hot-plugging a CPU. This was in fact the initial use of this type, with query-hotpluggable-cpus: letting management applications find out what properties need to be passed with device_add to hot-plug a CPU. We've since added other uses: set-numa-node (commit 419fcdec3c1 and f3be67812c2), and query-cpus-fast (commit ce74ee3dea6). These are not about device-add. query-hotpluggable-cpus uses CpuInstanceProperties within HotpluggableCPU. Lift the documentation related to device-add from CpuInstanceProperties to HotpluggableCPU. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240711112228.2140606-3-armbru@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
2024-07-17qapi/pci: Clean up documentation around PciDeviceClassMarkus Armbruster1-4/+2
PciDeviceInfo's doc comment has a note on PciDeviceClass member @desc. Since the note applies always, not just within PciDeviceInfo, merge it into PciDeviceClass's description of member @desc. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240711112228.2140606-2-armbru@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
2024-07-17qapi/qom: Document feature unstable of @x-vfio-user-serverMarkus Armbruster1-1/+2
Commit 8f9a9259d32c added ObjectType member @x-vfio-user-server with feature unstable, but neglected to explain why it is unstable. Do that now. Fixes: 8f9a9259d32c (vfio-user: define vfio-user-server object) Cc: Elena Ufimtseva <elena.ufimtseva@oracle.com> Cc: John G Johnson <john.g.johnson@oracle.com> Cc: Jagannathan Raman <jag.raman@oracle.com> Cc: qemu-stable@nongnu.org Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240703095310.1242102-1-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> [Indentation fixed]
2024-07-16i386/sev: Don't allow automatic fallback to legacy KVM_SEV*_INITMichael Roth1-7/+11
Currently if the 'legacy-vm-type' property of the sev-guest object is 'on', QEMU will attempt to use the newer KVM_SEV_INIT2 kernel interface in conjunction with the newer KVM_X86_SEV_VM and KVM_X86_SEV_ES_VM KVM VM types. This can lead to measurement changes if, for instance, an SEV guest was created on a host that originally had an older kernel that didn't support KVM_SEV_INIT2, but is booted on the same host later on after the host kernel was upgraded. Instead, if legacy-vm-type is 'off', QEMU should fail if the KVM_SEV_INIT2 interface is not provided by the current host kernel. Modify the fallback handling accordingly. In the future, VMSA features and other flags might be added to QEMU which will require legacy-vm-type to be 'off' because they will rely on the newer KVM_SEV_INIT2 interface. It may be difficult to convey to users what values of legacy-vm-type are compatible with which features/options, so as part of this rework, switch legacy-vm-type to a tri-state OnOffAuto option. 'auto' in this case will automatically switch to using the newer KVM_SEV_INIT2, but only if it is required to make use of new VMSA features or other options only available via KVM_SEV_INIT2. Defining 'auto' in this way would avoid inadvertantly breaking compatibility with older kernels since it would only be used in cases where users opt into newer features that are only available via KVM_SEV_INIT2 and newer kernels, and provide better default behavior than the legacy-vm-type=off behavior that was previously in place, so make it the default for 9.1+ machine types. Cc: Daniel P. Berrangé <berrange@redhat.com> Cc: Paolo Bonzini <pbonzini@redhat.com> cc: kvm@vger.kernel.org Signed-off-by: Michael Roth <michael.roth@amd.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Link: https://lore.kernel.org/r/20240710041005.83720-1-michael.roth@amd.com Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2024-07-06sphinx/qapidoc: Fix to generate doc for explicit, unboxed argumentsMarkus Armbruster1-7/+0
When a command's arguments are specified as an explicit type T, generated documentation points to the members of T. Example: ## # @announce-self: # # Trigger generation of broadcast RARP frames to update network [...] ## { 'command': 'announce-self', 'boxed': true, 'data' : 'AnnounceParameters'} generates "announce-self" (Command) ------------------------- Trigger generation of broadcast RARP frames to update network [...] Arguments ~~~~~~~~~ The members of "AnnounceParameters" Except when the command takes its arguments unboxed , i.e. it doesn't have 'boxed': true, we generate *nothing*. A few commands have a reference in their doc comment to compensate, but most don't. Example: ## # @blockdev-snapshot-sync: # # Takes a synchronous snapshot of a block device. # # For the arguments, see the documentation of BlockdevSnapshotSync. [...] ## { 'command': 'blockdev-snapshot-sync', 'data': 'BlockdevSnapshotSync', 'allow-preconfig': true } generates "blockdev-snapshot-sync" (Command) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Takes a synchronous snapshot of a block device. For the arguments, see the documentation of BlockdevSnapshotSync. [...] Same for event data. Fix qapidoc.py to generate the reference regardless of boxing. Delete now redundant references in the doc comments. Fixes: 4078ee5469e5 (docs/sphinx: Add new qapi-doc Sphinx extension) Cc: qemu-stable@nongnu.org Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240628112756.794237-1-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
2024-07-06qapi: add markup to note blocksJohn Snow6-10/+10
Generally, surround command-line options with ``literal`` markup to help it stand out from prose in rendered HTML, and add cross-references to replace "see also" messages. References to types, values, and other QAPI definitions are not yet adjusted here; they will be converted en masse in a subsequent patch after the new QAPI doc generator is merged. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-13-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: update prose in note blocksJohn Snow1-2/+2
Where I've noticed, rephrase the note to read more fluently. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-12-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: convert "Note" sections to plain rSTJohn Snow21-210/+206
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly. Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation. Markup is also re-aligned to the de-facto standard of 3 spaces for directives. Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply: .. note:: lorem ipsum ... ... dolor sit amet ... ... consectetur adipiscing elit ... ... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol () in the title bar for rendered HTML docs. See https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions for examples of each directive/admonition in use. These are rendered in orange: .. Attention:: ... .. Caution:: ... .. WARNING:: ... These are rendered in red: .. DANGER:: ... .. Error:: ... These are rendered in green: .. Hint:: ... .. Important:: ... .. Tip:: ... These are rendered in blue: .. Note:: ... .. admonition:: custom title admonition body text This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example. NOTE: Because qapidoc.py does not attempt to preserve source ordering of sections, the conversion of Notes from a "tagged section" to an "untagged section" means that rendering order for some notes *may change* as a result of this patch. The forthcoming qapidoc.py rewrite strictly preserves source ordering in the rendered documentation, so this issue will be rectified in the new generator. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: nail down convention that Errors sections are listsJohn Snow1-1/+1
By unstated convention, Errors sections are rST lists. Document the convention, and make the one exception conform. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-10-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-06qapi: fix non-compliant JSON examplesJohn Snow7-9/+11
The new QMP documentation generator wants to parse all examples as "QMP". We have an existing QMP lexer in docs/sphinx/qmp_lexer.py (Seen in-use here: https://qemu-project.gitlab.io/qemu/interop/bitmaps.html) that allows the use of "->", "<-" and "..." tokens to denote QMP protocol flow with elisions, but otherwise defers to the JSON lexer. To utilize this lexer for the existing QAPI documentation, we need them to conform to a standard so that they lex and render correctly. Once the QMP lexer is active for examples, errant QMP/JSON will produce warning messages and fail the build. Fix any invalid JSON found in QAPI documentation (identified by attempting to lex all examples as QMP; see subsequent commits). Additionally, elisions must be standardized for the QMP lexer; they must be represented as the value "...", so three examples have been adjusted to support that format here. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-9-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-03hw/cxl/events: Mark cxl-add-dynamic-capacity and cxl-release-dynamic-capcity ↵Jonathan Cameron1-2/+12
unstable Markus suggested that we make the unstable. I don't expect these interfaces to change because of their tight coupling to the Compute Express Link (CXL) Specification, Revision 3.1 Fabric Management API definitions which can only be extended in backwards compatible way. However, there seems little disadvantage in taking a cautious path for now and marking them as unstable interfaces. Suggested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Message-Id: <20240625170805.359278-3-Jonathan.Cameron@huawei.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
generated by cgit v1.1 at 2025-02-15 02:19:24 +0000