aboutsummaryrefslogtreecommitdiff
path: root/docs
AgeCommit message (Collapse)Author
2024-08-16docs/devel: update tcg-plugins pagePierrick Bouvier
Reflect recent changes on API (inline ops) and new plugins. Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Message-Id: <20240812231945.169310-1-pierrick.bouvier@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240813202329.1237572-21-alex.bennee@linaro.org>
2024-08-16docs: Fix some typos (found by typos) and grammar issuesStefan Weil
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-09docs: Typo fix in live disk backupEric Blake
Add in the missing space in the section header. Fixes: 1084159b31 ("qapi: deprecate drive-backup", v6.2.0) Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2024-08-09docs/interop/prl-xml.rst: Fix minor grammar nitsPeter Maydell
Fix some minor grammar nits in the prl-xml documentation. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20240801170131.3977807-6-peter.maydell@linaro.org
2024-08-09docs/interop/prl-xml.txt: Convert to rSTPeter Maydell
Convert prl-xml.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20240801170131.3977807-5-peter.maydell@linaro.org
2024-08-09docs/interop/parallels.txt: Convert to rSTPeter Maydell
Convert parallels.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20240801170131.3977807-4-peter.maydell@linaro.org
2024-08-09docs/interop/nbd.txt: Convert to rSTPeter Maydell
Convert nbd.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20240801170131.3977807-3-peter.maydell@linaro.org
2024-08-09docs/specs/rocker.txt: Convert to rSTPeter Maydell
Convert the rocker.txt specification document to rST format. We make extensive use of the :: marker to introduce a literal block for all the tables and ASCII art, rather than trying to convert the tables to rST table syntax. This produces a valid rST document without needing a huge diff. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20240801170131.3977807-2-peter.maydell@linaro.org
2024-08-06docs/specs/pci-ids: Fix markupGeorge Matsumura
This fixes the markup of the PCI and PCIe Expander Bridge entries to be consistent with the rest of the file. Signed-off-by: George Matsumura <gorg@gorgnet.net> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Message-ID: <20240805031012.16547-4-gorg@gorgnet.net> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-08-06docs/specs/pci-ids: Add missing devicesGeorge Matsumura
Add the missing devices 1b36:000c (PCIe root port) and 1b36:000e (PCIe-to-PCI bridge). Signed-off-by: George Matsumura <gorg@gorgnet.net> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Message-ID: <20240805031012.16547-2-gorg@gorgnet.net> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-08-01Revert "pcie_sriov: Ensure VF function number does not overflow"Michael S. Tsirkin
This reverts commit 77718701157f6ca77ea7a57b536fa0a22f676082. Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
2024-08-01Revert "docs: Document composable SR-IOV device"Michael S. Tsirkin
This reverts commit d6f40c95b35bd380340b698e4306704fe22a5d68. Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
2024-07-31Merge tag 'docs-testing-20240731' of https://github.com/philmd/qemu into stagingRichard Henderson
Docs & testing patch queue - Test QAPI firmware.json schema (Thomas) - Handle new env.doc2path() return value (Peter) - Improve how assets are used by some Avocado tests (Cleber) - Remove obsolete check for macOS 10 (Peter) # -----BEGIN PGP SIGNATURE----- # # iQIzBAABCAAdFiEE+qvnXhKRciHc/Wuy4+MsLN6twN4FAmapZuUACgkQ4+MsLN6t # wN7oRw//epjJF7PP4e02RqThHWvk92aL6IJiJz6dx8jAVEPWjtY8Pk1jRMhf5ff1 # 50ICdd3gZVTGENM7gO4arOM61pt1NEXs0Xrh3zDlq+RrRMVhef4LfJh3O3BRqZ7K # eVLwo8ismivOJZ2fp+rPY2TT0h4g6zjvJOw7jvXIFM6UFK2C22ff669aa8jhLOVt # kI1eRv3yaYbAzWCN7Z4VOZ/VitEk4b50cg0Gbk4ZgpfmYQxn5+ijy0Mekzkh6JE4 # G1NzaUnBreqx3dTeE5zUJll42RxwtY6By//NH3r8MLf3twvL61p8DNCkCdRzKOpt # SS5GVPyGiESCWY84oVjaSnS0S1Ys/CiNB1a92xvofj1MBIJNSOOmqKl9L7gpom8U # D16cmOwK6WQqvzxXhH+Q5tN/cT76de7s1MBSmU4avoxvDWA/4q618TdRXf7I9f0j # mEz3K1egX6wz1dd8xquKFoKRkHzPi6h12Rx8D87cRE4E1qbrwulwtkrUCTCNi/cQ # nNNfMviyVcWVB7Gx991Bc1JVI1/44TH3O43fm4ZmRFb3JuBiFWxsdNdSrASJNDCq # ofW0ZkSgMxgWN7EOpiLBUgTdf7PKS7ITvdUKjKAvY3qlx1Ql491iq050iwPZ336J # Byi32D3+yjB9nbWuUW8h9ULgUZ5+3O85SfNEtgiG+YERI0jBWeA= # =g7fB # -----END PGP SIGNATURE----- # gpg: Signature made Wed 31 Jul 2024 08:19:17 AM AEST # gpg: using RSA key FAABE75E12917221DCFD6BB2E3E32C2CDEADC0DE # gpg: Good signature from "Philippe Mathieu-Daudé (F4BUG) <f4bug@amsat.org>" [full] * tag 'docs-testing-20240731' of https://github.com/philmd/qemu: osdep.h: Clean up no-longer-needed back-compat for macOS 10 tests/avocado: test_arm_emcraft_sf2: handle RW requirements for asset tests/avocado: mips: add hint for fetchasset plugin tests/avocado: mips: fallback to HTTP given certificate expiration docs/sphinx/depfile.py: Handle env.doc2path() returning a Path not a str docs: add test for firmware.json QAPI Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-31docs/sphinx/depfile.py: Handle env.doc2path() returning a Path not a strPeter Maydell
In newer versions of Sphinx the env.doc2path() API is going to change to return a Path object rather than a str. This was originally visible in Sphinx 8.0.0rc1, but has been rolled back for the final 8.0.0 release. However it will probably emit a deprecation warning and is likely to change for good in 9.0: https://github.com/sphinx-doc/sphinx/issues/12686 Our use in depfile.py assumes a str, and if it is passed a Path it will fall over: Handler <function write_depfile at 0x77a1775ff560> for event 'build-finished' threw an exception (exception: unsupported operand type(s) for +: 'PosixPath' and 'str') Wrapping the env.doc2path() call in str() will coerce a Path object to the str we expect, and have no effect in older Sphinx versions that do return a str. Cc: qemu-stable@nongnu.org Resolves: https://gitlab.com/qemu-project/qemu/-/issues/2458 Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Message-ID: <20240729120533.2486427-1-peter.maydell@linaro.org> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-31docs: add test for firmware.json QAPIThomas Weißschuh
To make sure that the QAPI description stays valid, add a testcase. Suggested-by: Philippe Mathieu-Daudé <philmd@linaro.org> Link: https://lore.kernel.org/qemu-devel/d9ce0234-4beb-4b90-b14c-76810d3b81d7@linaro.org/ Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de> Tested-by: Philippe Mathieu-Daudé <philmd@linaro.org> Message-ID: <20240724-qapi-firmware-json-v7-1-12341f7e362d@linutronix.de> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-30docs: split TCG plugin usage from devel sectionAlex Bennée
The devel section is getting quite messy with the breakdown of the example plugins which should be usable by users. As we mention plugins in the emulation section along with semihosting move the overview there leaving the development section about the details of writing plugins. While we are at make the headings nicer and convert the option lists into nicely formatted tables. Acked-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240729144414.830369-11-alex.bennee@linaro.org>
2024-07-30docs/devel: document how to run individual TCG testsAlex Bennée
Since 6f6ca067d2 (tests/tcg: add some help output for running individual tests) we made it easier to run individual tests for a given architecture. Lets reference that in the developer documentation. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240729144414.830369-8-alex.bennee@linaro.org>
2024-07-30docs/devel: update the testing introductionAlex Bennée
Move the mention of "check-help" up to the intro text and also mention the meson test integration. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240729144414.830369-7-alex.bennee@linaro.org>
2024-07-24docs/devel: Add introduction to LUKS volume with detached headerHyman Huang
Signed-off-by: Hyman Huang <yong.huang@smartx.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
2024-07-24Merge tag 'hw-misc-20240723' of https://github.com/philmd/qemu into stagingRichard Henderson
Misc HW patch queue - Restrict probe_access*() functions to TCG (Phil) - Extract do_invalidate_device_tlb from vtd_process_device_iotlb_desc (Clément) - Fixes in Loongson IPI model (Bibo & Phil) - Make docs/interop/firmware.json compatible with qapi-gen.py script (Thomas) - Correct MPC I2C MMIO region size (Zoltan) - Remove useless cast in Loongson3 Virt machine (Yao) - Various uses of range overlap API (Yao) - Use ERRP_GUARD macro in nubus_virtio_mmio_realize (Zhao) - Use DMA memory API in Goldfish UART model (Phil) - Expose fifo8_pop_buf and introduce fifo8_drop (Phil) - MAINTAINERS updates (Zhao, Phil) # -----BEGIN PGP SIGNATURE----- # # iQIzBAABCAAdFiEE+qvnXhKRciHc/Wuy4+MsLN6twN4FAmagFF8ACgkQ4+MsLN6t # wN5bKg//f5TwUhsy2ff0FJpHheDOj/9Gc2nZ1U/Fp0E5N3sz3A7MGp91wye6Xwi3 # XG34YN9LK1AVzuCdrEEs5Uaxs1ZS1R2mV+fZaGHwYYxPDdnXxGyp/2Q0eyRxzbcN # zxE2hWscYSZbPVEru4HvZJKfp4XnE1cqA78fJKMAdtq0IPq38tmQNRlJ+gWD9dC6 # ZUHXPFf3DnucvVuwqb0JYO/E+uJpcTtgR6pc09Xtv/HFgMiS0vKZ1I/6LChqAUw9 # eLMpD/5V2naemVadJe98/dL7gIUnhB8GTjsb4ioblG59AO/uojutwjBSQvFxBUUw # U5lX9OSn20ouwcGiqimsz+5ziwhCG0R6r1zeQJFqUxrpZSscq7NQp9ygbvirm+wS # edLc8yTPf4MtYOihzPP9jLPcXPZjEV64gSnJISDDFYWANCrysX3suaFEOuVYPl+s # ZgQYRVSSYOYHgNqBSRkPKKVUxskSQiqLY3SfGJG4EA9Ktt5lD1cLCXQxhdsqphFm # Ws3zkrVVL0EKl4v/4MtCgITIIctN1ZJE9u3oPJjASqSvK6EebFqAJkc2SidzKHz0 # F3iYX2AheWNHCQ3HFu023EvFryjlxYk95fs2f6Uj2a9yVbi813qsvd3gcZ8t0kTT # +dmQwpu1MxjzZnA6838R6OCMnC+UpMPqQh3dPkU/5AF2fc3NnN8= # =J/I2 # -----END PGP SIGNATURE----- # gpg: Signature made Wed 24 Jul 2024 06:36:47 AM AEST # gpg: using RSA key FAABE75E12917221DCFD6BB2E3E32C2CDEADC0DE # gpg: Good signature from "Philippe Mathieu-Daudé (F4BUG) <f4bug@amsat.org>" [full] * tag 'hw-misc-20240723' of https://github.com/philmd/qemu: (28 commits) MAINTAINERS: Add myself as a reviewer of machine core MAINTAINERS: Cover guest-agent in QAPI schema util/fifo8: Introduce fifo8_drop() util/fifo8: Expose fifo8_pop_buf() util/fifo8: Rename fifo8_pop_buf() -> fifo8_pop_bufptr() util/fifo8: Rename fifo8_peek_buf() -> fifo8_peek_bufptr() util/fifo8: Use fifo8_reset() in fifo8_create() util/fifo8: Fix style chardev/char-fe: Document returned value on error hw/char/goldfish: Use DMA memory API hw/nubus/virtio-mmio: Fix missing ERRP_GUARD() in realize handler dump: make range overlap check more readable crypto/block-luks: make range overlap check more readable system/memory_mapping: make range overlap check more readable sparc/ldst_helper: make range overlap check more readable cxl/mailbox: make range overlap check more readable util/range: Make ranges_overlap() return bool hw/mips/loongson3_virt: remove useless type cast hw/i2c/mpc_i2c: Fix mmio region size docs/interop/firmware.json: convert "Example" section ... Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-24Merge tag 'for-upstream' of https://gitlab.com/bonzini/qemu into stagingRichard Henderson
* target/i386/kvm: support for reading RAPL MSRs using a helper program * hpet: emulation improvements # -----BEGIN PGP SIGNATURE----- # # iQFIBAABCAAyFiEE8TM4V0tmI4mGbHaCv/vSX3jHroMFAmaelL4UHHBib256aW5p # QHJlZGhhdC5jb20ACgkQv/vSX3jHroMXoQf+K77lNlHLETSgeeP3dr7yZPOmXjjN # qFY/18jiyLw7MK1rZC09fF+n9SoaTH8JDKupt0z9M1R10HKHLIO04f8zDE+dOxaE # Rou3yKnlTgFPGSoPPFr1n1JJfxtYlLZRoUzaAcHUaa4W7JR/OHJX90n1Rb9MXeDk # jV6P0v1FWtIDdM6ERm9qBGoQdYhj6Ra2T4/NZKJFXwIhKEkxgu4yO7WXv8l0dxQz # jE4fKotqAvrkYW1EsiVZm30lw/19duhvGiYeQXoYhk8KKXXjAbJMblLITSNWsCio # 3l6Uud/lOxekkJDAq5nH3H9hCBm0WwvwL+0vRf3Mkr+/xRGvrhtmUdp8NQ== # =00mB # -----END PGP SIGNATURE----- # gpg: Signature made Tue 23 Jul 2024 03:19:58 AM AEST # 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] * tag 'for-upstream' of https://gitlab.com/bonzini/qemu: hpet: avoid timer storms on periodic timers hpet: store full 64-bit target value of the counter hpet: accept 64-bit reads and writes hpet: place read-only bits directly in "new_val" hpet: remove unnecessary variable "index" hpet: ignore high bits of comparator in 32-bit mode hpet: fix and cleanup persistence of interrupt status Add support for RAPL MSRs in KVM/Qemu tools: build qemu-vmsr-helper qio: add support for SO_PEERCRED for socket channel target/i386: do not crash if microvm guest uses SGX CPUID leaves Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-24Merge tag 'for_upstream' of https://git.kernel.org/pub/scm/virt/kvm/mst/qemu ↵Richard Henderson
into staging virtio,pci,pc: features,fixes pci: Initial support for SPDM Responders cxl: Add support for scan media, feature commands, device patrol scrub control, DDR5 ECS control, firmware updates virtio: in-order support virtio-net: support for SR-IOV emulation (note: known issues on s390, might get reverted if not fixed) smbios: memory device size is now configurable per Machine cpu: architecture agnostic code to support vCPU Hotplug Fixes, cleanups all over the place. Signed-off-by: Michael S. Tsirkin <mst@redhat.com> # -----BEGIN PGP SIGNATURE----- # # iQFDBAABCAAtFiEEXQn9CHHI+FuUyooNKB8NuNKNVGkFAmae9l8PHG1zdEByZWRo # YXQuY29tAAoJECgfDbjSjVRp8fYH/impBH9nViO/WK48io4mLSkl0EUL8Y/xrMvH # zKFCKaXq8D96VTt1Z4EGKYgwG0voBKZaCEKYU/0ARGnSlSwxINQ8ROCnBWMfn2sx # yQt08EXVMznNLtXjc6U5zCoCi6SaV85GH40No3MUFXBQt29ZSlFqO/fuHGZHYBwS # wuVKvTjjNF4EsGt3rS4Qsv6BwZWMM+dE6yXpKWk68kR8IGp+6QGxkMbWt9uEX2Md # VuemKVnFYw0XGCGy5K+ZkvoA2DGpEw0QxVSOMs8CI55Oc9SkTKz5fUSzXXGo1if+ # M1CTjOPJu6pMym6gy6XpFa8/QioDA/jE2vBQvfJ64TwhJDV159s= # =k8e9 # -----END PGP SIGNATURE----- # gpg: Signature made Tue 23 Jul 2024 10:16:31 AM AEST # gpg: using RSA key 5D09FD0871C8F85B94CA8A0D281F0DB8D28D5469 # gpg: issuer "mst@redhat.com" # gpg: Good signature from "Michael S. Tsirkin <mst@kernel.org>" [undefined] # gpg: aka "Michael S. Tsirkin <mst@redhat.com>" [undefined] # 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: 0270 606B 6F3C DF3D 0B17 0970 C350 3912 AFBE 8E67 # Subkey fingerprint: 5D09 FD08 71C8 F85B 94CA 8A0D 281F 0DB8 D28D 5469 * tag 'for_upstream' of https://git.kernel.org/pub/scm/virt/kvm/mst/qemu: (61 commits) hw/nvme: Add SPDM over DOE support backends: Initial support for SPDM socket support hw/pci: Add all Data Object Types defined in PCIe r6.0 tests/acpi: Add expected ACPI AML files for RISC-V tests/qtest/bios-tables-test.c: Enable basic testing for RISC-V tests/acpi: Add empty ACPI data files for RISC-V tests/qtest/bios-tables-test.c: Remove the fall back path tests/acpi: update expected DSDT blob for aarch64 and microvm acpi/gpex: Create PCI link devices outside PCI root bridge tests/acpi: Allow DSDT acpi table changes for aarch64 hw/riscv/virt-acpi-build.c: Update the HID of RISC-V UART hw/riscv/virt-acpi-build.c: Add namespace devices for PLIC and APLIC virtio-iommu: Add trace point on virtio_iommu_detach_endpoint_from_domain hw/vfio/common: Add vfio_listener_region_del_iommu trace event virtio-iommu: Remove the end point on detach virtio-iommu: Free [host_]resv_ranges on unset_iommu_devices virtio-iommu: Remove probe_done Revert "virtio-iommu: Clear IOMMUDevice when VFIO device is unplugged" gdbstub: Add helper function to unregister GDB register space physmem: Add helper function to destroy CPU AddressSpace ... Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-23docs/interop/firmware.json: convert "Example" sectionThomas Weißschuh
Since commit 3c5f6114d9ff ("qapi: remove "Example" doc section") the "Example" section is not valid anymore. It has been replaced by the "qmp-example" directive. This was not detected earlier as firmware.json was not validated. As this validation is about to be added, adapt firmware.json. Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de> Message-ID: <20240719-qapi-firmware-json-v6-3-c2e3de390b58@linutronix.de> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-23docs/interop/firmware.json: add new enum FirmwareArchitectureThomas Weißschuh
Only a small subset of all architectures supported by qemu make use of firmware files. Introduce and use a new enum to represent this. This also removes the dependency to machine.json from the global qapi definitions. Claim "Since: 3.0" for the new enum, because that's correct for most of its members, and the members are what matters in the interface. Suggested-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240719-qapi-firmware-json-v6-2-c2e3de390b58@linutronix.de> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-23docs/interop/firmware.json: add new enum FirmwareFormatThomas Weißschuh
Only a small subset of all blockdev drivers make sense for firmware images. Introduce and use a new enum to represent this. This also reduces the dependency on firmware.json from the global qapi definitions. Claim "Since: 3.0" for the new enum, because that's correct for its members, and the members are what matters in the interface. Suggested-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240719-qapi-firmware-json-v6-1-c2e3de390b58@linutronix.de> Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-23docs: Correct Loongarch -> LoongArchPhilippe Mathieu-Daudé
Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Jiaxun Yang <jiaxun.yang@flygoat.com> Tested-by: Jiaxun Yang <jiaxun.yang@flygoat.com> Message-Id: <20240718133312.10324-20-philmd@linaro.org>
2024-07-24Merge tag 'qga-pull-2024-07-23' of https://github.com/kostyanf14/qemu into ↵Richard Henderson
staging qga-pull-2024-07-23 # -----BEGIN PGP SIGNATURE----- # # iQIzBAABCAAdFiEEwsLBCepDxjwUI+uE711egWG6hOcFAmafUs0ACgkQ711egWG6 # hOffwQ/+PMFMOq3jwV11Na0GnrFHT0SLlcxNWYGQjE0Q/nwuYWMTKdo2iB9rVC7T # qxaT6PLtTZPgRsJudJ5kkvLFw88Nr6BuWl31tCVeALUO7C0oTg/oRDfYVeH4/jfG # PS5TiM6ie27SvI5lhGZhd9sRAy8N6NGgT6Fh+pS2tVVfftcfVYKVmnzgtvk314A+ # MpeW8ukVruSW+9G+suXaE750g/drZJAoepC5pW1HXdHE+IuzXNdMWZqwMqBZSM5T # X8VcLvMjFrFrfLOP2el6mloriw67aJyKe9Uwsp548HdXfZKrLCmaR7cZK5zKVQDK # Rzolyuw19wNNi0TZAwmP+MBioDiIHcM4nNhVDCHIVCbXzQHa4BhAr/cr8uucyfM5 # hdCWmaTl4Tksk4q4ooHurDWshV26QNRbLRD1Vx1Rhrwz42MmU2VG13PsSWqLj00I # fj1LzhQOmr26cewgayIL7ODwHDXiwKi+6lKS1OyTjXXubucScgxSyTNC785T6Rvk # T58KAnBRD3vDhE7Dn/4KdRClRFY+7R2/jcHdFnA4vfvOVV8ZXp/m0O0wfLEikH6/ # dGDDVBLNG5gqV477++0wdqkYFq6MmON3PH/EA6rgZYc4At5kS+HFNASBvnFRYMGf # dgtyj8jV5uoffqYOqyXxClP6eTgV1EZ0/wKZ8uJipivB7azjnkE= # =xzjT # -----END PGP SIGNATURE----- # gpg: Signature made Tue 23 Jul 2024 04:50:53 PM AEST # gpg: using RSA key C2C2C109EA43C63C1423EB84EF5D5E8161BA84E7 # gpg: Good signature from "Kostiantyn Kostiuk (Upstream PR sign) <kkostiuk@redhat.com>" [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: C2C2 C109 EA43 C63C 1423 EB84 EF5D 5E81 61BA 84E7 * tag 'qga-pull-2024-07-23' of https://github.com/kostyanf14/qemu: (25 commits) qga/linux: Add new api 'guest-network-get-route' guest-agent: document allow-rpcs in config file section qga/commands-posix: Make ga_wait_child() return boolean qga: centralize logic for disabling/enabling commands qga: allow configuration file path via the cli qga: remove pointless 'blockrpcs_key' variable qga: move declare of QGAConfig struct to top of file qga: don't disable fsfreeze commands if vss_init fails qga: conditionalize schema for commands not supported on other UNIX qga: conditionalize schema for commands requiring utmpx qga: conditionalize schema for commands requiring libudev qga: conditionalize schema for commands requiring fstrim qga: conditionalize schema for commands requiring fsfreeze qga: conditionalize schema for commands only supported on Windows qga: conditionalize schema for commands requiring linux/win32 qga: conditionalize schema for commands requiring getifaddrs qga: conditionalize schema for commands unsupported on non-Linux POSIX qga: conditionalize schema for commands unsupported on Windows qga: move CONFIG_FSFREEZE/TRIM to be meson defined options qga: move linux memory block command impls to commands-linux.c ... Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-22hw/nvme: Add SPDM over DOE supportWilfred Mallawa
Setup Data Object Exchange (DOE) as an extended capability for the NVME controller and connect SPDM to it (CMA) to it. Signed-off-by: Wilfred Mallawa <wilfred.mallawa@wdc.com> Signed-off-by: Alistair Francis <alistair.francis@wdc.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Acked-by: Klaus Jensen <k.jensen@samsung.com> Message-Id: <20240703092027.644758-4-alistair.francis@wdc.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
2024-07-22hw/acpi: Update ACPI GED framework to support vCPU HotplugSalil Mehta
ACPI GED (as described in the ACPI 6.4 spec) uses an interrupt listed in the _CRS object of GED to intimate OSPM about an event. Later then demultiplexes the notified event by evaluating ACPI _EVT method to know the type of event. Use ACPI GED to also notify the guest kernel about any CPU hot(un)plug events. Note, GED interface is used by many hotplug events like memory hotplug, NVDIMM hotplug and non-hotplug events like system power down event. Each of these can be selected using a bit in the 32 bit GED IO interface. A bit has been reserved for the CPU hotplug event. ACPI CPU hotplug related initialization should only happen if ACPI_CPU_HOTPLUG support has been enabled for particular architecture. Add cpu_hotplug_hw_init() stub to avoid compilation break. Co-developed-by: Keqian Zhu <zhukeqian1@huawei.com> Signed-off-by: Keqian Zhu <zhukeqian1@huawei.com> Signed-off-by: Salil Mehta <salil.mehta@huawei.com> Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Reviewed-by: Gavin Shan <gshan@redhat.com> Reviewed-by: David Hildenbrand <david@redhat.com> Reviewed-by: Shaoqin Huang <shahuang@redhat.com> Tested-by: Vishnu Pajjuri <vishnu@os.amperecomputing.com> Tested-by: Xianglai Li <lixianglai@loongson.cn> Tested-by: Miguel Luis <miguel.luis@oracle.com> Reviewed-by: Vishnu Pajjuri <vishnu@os.amperecomputing.com> Tested-by: Zhao Liu <zhao1.liu@intel.com> Reviewed-by: Zhao Liu <zhao1.liu@intel.com> Message-Id: <20240716111502.202344-4-salil.mehta@huawei.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Acked-by: Igor Mammedov <imammedo@redhat.com>
2024-07-22docs: Document composable SR-IOV deviceAkihiko Odaki
Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com> Message-Id: <20240715-sriov-v5-8-3f5539093ffc@daynix.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
2024-07-22Add support for RAPL MSRs in KVM/QemuAnthony Harivel
Starting with the "Sandy Bridge" generation, Intel CPUs provide a RAPL interface (Running Average Power Limit) for advertising the accumulated energy consumption of various power domains (e.g. CPU packages, DRAM, etc.). The consumption is reported via MSRs (model specific registers) like MSR_PKG_ENERGY_STATUS for the CPU package power domain. These MSRs are 64 bits registers that represent the accumulated energy consumption in micro Joules. They are updated by microcode every ~1ms. For now, KVM always returns 0 when the guest requests the value of these MSRs. Use the KVM MSR filtering mechanism to allow QEMU handle these MSRs dynamically in userspace. To limit the amount of system calls for every MSR call, create a new thread in QEMU that updates the "virtual" MSR values asynchronously. Each vCPU has its own vMSR to reflect the independence of vCPUs. The thread updates the vMSR values with the ratio of energy consumed of the whole physical CPU package the vCPU thread runs on and the thread's utime and stime values. All other non-vCPU threads are also taken into account. Their energy consumption is evenly distributed among all vCPUs threads running on the same physical CPU package. To overcome the problem that reading the RAPL MSR requires priviliged access, a socket communication between QEMU and the qemu-vmsr-helper is mandatory. You can specified the socket path in the parameter. This feature is activated with -accel kvm,rapl=true,path=/path/sock.sock Actual limitation: - Works only on Intel host CPU because AMD CPUs are using different MSR adresses. - Only the Package Power-Plane (MSR_PKG_ENERGY_STATUS) is reported at the moment. Signed-off-by: Anthony Harivel <aharivel@redhat.com> Link: https://lore.kernel.org/r/20240522153453.1230389-4-aharivel@redhat.com Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2024-07-22tools: build qemu-vmsr-helperAnthony Harivel
Introduce a privileged helper to access RAPL MSR. The privileged helper tool, qemu-vmsr-helper, is designed to provide virtual machines with the ability to read specific RAPL (Running Average Power Limit) MSRs without requiring CAP_SYS_RAWIO privileges or relying on external, out-of-tree patches. The helper tool leverages Unix permissions and SO_PEERCRED socket options to enforce access control, ensuring that only processes explicitly requesting read access via readmsr() from a valid Thread ID can access these MSRs. The list of RAPL MSRs that are allowed to be read by the helper tool is defined in rapl-msr-index.h. This list corresponds to the RAPL MSRs that will be supported in the next commit titled "Add support for RAPL MSRs in KVM/QEMU." The tool is intentionally designed to run on the Linux x86 platform. This initial implementation is tailored for Intel CPUs but can be extended to support AMD CPUs in the future. Signed-off-by: Anthony Harivel <aharivel@redhat.com> Link: https://lore.kernel.org/r/20240522153453.1230389-3-aharivel@redhat.com Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2024-07-22plugins/stoptrigger: TCG plugin to stop execution under conditionsSimon Hamelin
This new plugin allows to stop emulation using conditions on the emulation state. By setting this plugin arguments, it is possible to set an instruction count limit and/or trigger address(es) to stop at. The code returned at emulation exit can be customized. This plugin demonstrates how someone could stop QEMU execution. It could be used for research purposes to launch some code and deterministically stop it and understand where its execution flow went. Co-authored-by: Alexandre Iooss <erdnaxe@crans.org> Signed-off-by: Simon Hamelin <simon.hamelin@grenoble-inp.org> Signed-off-by: Alexandre Iooss <erdnaxe@crans.org> Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Message-Id: <20240715081521.19122-2-simon.hamelin@grenoble-inp.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240718094523.1198645-5-alex.bennee@linaro.org>
2024-07-21aspeed: Introduce a 'boot-emmc' machine optionCédric Le Goater
The default behavior of some Aspeed machines is to boot from the eMMC device, like the rainier-bmc. Others like ast2600-evb could also boot from eMMC if the HW strapping boot-from-eMMC bit was set. Add a property to set or unset this bit. This is useful to test boot images. For now, only activate this property on the ast2600-evb and rainier-bmc machines for which eMMC images are available or can be built. Signed-off-by: Cédric Le Goater <clg@kaod.org> Reviewed-by: Andrew Jeffery <andrew@codeconstruct.com.au> Tested-by: Andrew Jeffery <andrew@codeconstruct.com.au> Tested-by: Philippe Mathieu-Daudé <philmd@linaro.org>
2024-07-19guest-agent: document allow-rpcs in config file sectionThomas Lamprecht
While the `allow-rpcs` option is documented in the CLI options section, it was missing in the section about the configuration file syntax. And while it's mentioned that "the list of keys follows the command line options", having `block-rpcs` there but not `allow-rpcs` seems like being a potential source of confusion; and as it's cheap to add let's just do so. Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com> Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com> Message-ID: <20240718140407.444160-1-t.lamprecht@proxmox.com> Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2024-07-19qga: centralize logic for disabling/enabling commandsDaniel P. Berrangé
It is confusing having many different pieces of code enabling and disabling commands, and it is not clear that they all have the same semantics, especially wrt prioritization of the block/allow lists. The code attempted to prevent the user from setting both the block and allow lists concurrently, however, the logic was flawed as it checked settings in the configuration file separately from the command line arguments. Thus it was possible to set a block list in the config file and an allow list via a command line argument. The --dump-conf option also creates a configuration file with both keys present, even if unset, which means it is creating a config that cannot actually be loaded again. Centralizing the code in a single method "ga_apply_command_filters" will provide a strong guarantee of consistency and clarify the intended behaviour. With this there is no compelling technical reason to prevent concurrent setting of both the allow and block lists, so this flawed restriction is removed. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com> Message-ID: <20240712132459.3974109-23-berrange@redhat.com> Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2024-07-19qga: allow configuration file path via the cliDaniel P. Berrangé
Allowing the user to set the QGA_CONF environment variable to change the default configuration file path is very unusual practice, made more obscure since this ability is not documented. This introduces the more normal '-c PATH' / '--config=PATH' command line argument approach. This requires that we parse the comamnd line twice, since we want the command line arguments to take priority over the configuration file settings in general. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com> Message-ID: <20240712132459.3974109-22-berrange@redhat.com> Signed-off-by: Konstantin Kostiuk <kkostiuk@redhat.com>
2024-07-18Merge tag 'pull-riscv-to-apply-20240718-1' of ↵Richard Henderson
https://github.com/alistair23/qemu into staging RISC-V PR for 9.1 * Support the zimop, zcmop, zama16b and zabha extensions * Validate the mode when setting vstvec CSR * Add decode support for Zawrs extension * Update the KVM regs to Linux 6.10-rc5 * Add smcntrpmf extension support * Raise an exception when CSRRS/CSRRC writes a read-only CSR * Re-insert and deprecate 'riscv,delegate' in virt machine device tree * roms/opensbi: Update to v1.5 # -----BEGIN PGP SIGNATURE----- # # iQIzBAABCAAdFiEEaukCtqfKh31tZZKWr3yVEwxTgBMFAmaYeUcACgkQr3yVEwxT # gBMtdw//U2NbmnmECa0uXuE7fdFul0tUkl2oHb9Cr8g5Se5g/HVFqexAKOFZ8Lcm # DvTl94zJ2dms4RntcmJHwTIusa+oU6qqOekediotjgpeH4BHZNCOHe0E9hIAHn9F # uoJ1P186L7VeVr7OFAAgSCE7F6egCk7iC0h8L8/vuL4xcuyfbZ2r7ybiTl1+45N2 # YBBv5/00wsYnyMeqRYYtyqgX9QR017JRqNSfTJSbKxhQM/L1GA1xxisUvIGeyDqc # Pn8E3dMN6sscR6bPs4RP+SBi0JIlRCgth/jteSUkbYf42osw3/5sl4oK/e6Xiogo # SjELOF7QJNxE8H6EUIScDaCVB5ZhvELZcuOL2NRdUuVDkjhWXM633HwfEcXkZdFK # W/H9wOvNxPAJIOGXOpv10+MLmhdyIOZwE0uk6evHvdcTn3FP9DurdUCc1se0zKOA # Qg/H6usTbLGNQ7KKTNQ6GpQ6u89iE1CIyZqYVvB1YuF5t7vtAmxvNk3SVZ6aq3VL # lPJW2Zd1eO09Q+kRnBVDV7MV4OJrRNsU+ryd91NrSVo9aLADtyiNC28dCSkjU3Gn # 6YQZt65zHuhH5IBB/PGIPo7dLRT8KNWOiYVoy3c6p6DC6oXsKIibh0ue1nrVnnVQ # NRqyxPYaj6P8zzqwTk+iJj36UXZZVtqPIhtRu9MrO6Opl2AbsXI= # =pM6B # -----END PGP SIGNATURE----- # gpg: Signature made Thu 18 Jul 2024 12:09:11 PM AEST # 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-20240718-1' of https://github.com/alistair23/qemu: (30 commits) roms/opensbi: Update to v1.5 hw/riscv/virt.c: re-insert and deprecate 'riscv,delegate' target/riscv: raise an exception when CSRRS/CSRRC writes a read-only CSR target/riscv: Expose the Smcntrpmf config target/riscv: Do not setup pmu timer if OF is disabled target/riscv: More accurately model priv mode filtering. target/riscv: Start counters from both mhpmcounter and mcountinhibit target/riscv: Enforce WARL behavior for scounteren/hcounteren target/riscv: Save counter values during countinhibit update target/riscv: Implement privilege mode filtering for cycle/instret target/riscv: Only set INH fields if priv mode is available target/riscv: Add cycle & instret privilege mode filtering support target/riscv: Add cycle & instret privilege mode filtering definitions target/riscv: Add cycle & instret privilege mode filtering properties target/riscv: Fix the predicate functions for mhpmeventhX CSRs target/riscv: Combine set_mode and set_virt functions. target/riscv/kvm: update KVM regs to Linux 6.10-rc5 disas/riscv: Add decode for Zawrs extension target/riscv: Validate the mode in write_vstvec disas/riscv: Support zabha disassemble ... Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
2024-07-18hw/riscv/virt.c: re-insert and deprecate 'riscv,delegate'Daniel Henrique Barboza
Commit b1f1e9dcfa renamed 'riscv,delegate' to 'riscv,delegation' since it is the correct name as per dt-bindings, and the absence of the correct name will result in validation fails when dumping the dtb and using dt-validate. But this change has a side-effect: every other firmware available that is AIA capable is using 'riscv,delegate', and it will fault/misbehave if this property isn't present. The property was added back in QEMU 7.0, meaning we have 2 years of firmware development using the wrong property. Re-introducing 'riscv,delegate' while keeping 'riscv,delegation' allows older firmwares to keep booting with the 'virt' machine. 'riscv,delegate' is then marked for future deprecation with its use being discouraged from now on. Cc: Conor Dooley <conor@kernel.org> Cc: Anup Patel <apatel@ventanamicro.com> Fixes: b1f1e9dcfa ("hw/riscv/virt.c: aplic DT: rename prop to 'riscv, delegation'") Signed-off-by: Daniel Henrique Barboza <dbarboza@ventanamicro.com> Reviewed-by: Alistair Francis <alistair.francis@wdc.com> Message-ID: <20240715090455.145888-1-dbarboza@ventanamicro.com> Signed-off-by: Alistair Francis <alistair.francis@wdc.com>
2024-07-17qapi: remove "Example" doc sectionJohn Snow
Fully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match. Migrating to the new syntax --------------------------- The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block. ('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.) Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired. Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive. Why? ---- This patch has several benefits: 1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired. 2. Example sections can now use fully arbitrary rST. 3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets. (To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.) 4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator. (i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.) NOTE: As with the "Notes" conversion (d461c279737), this patch (and the three preceding) may change the rendering order for Examples in the current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-10-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17docs/sphinx: add CSS styling for qmp-example directiveHarmonie Snow
Add CSS styling for qmp-example directives to increase readability and consistently style all example blocks. Signed-off-by: Harmonie Snow <harmonie@gmail.com> Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-6-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17docs/qapidoc: add QMP highlighting to annotated qmp-example blocksJohn Snow
For any code literal blocks inside of a qmp-example directive, apply and enforce the QMP lexer/highlighter to those blocks. This way, you won't need to write: ``` .. qmp-example:: :annotated: Blah blah .. code-block:: QMP -> { "lorem": "ipsum" } ``` But instead, simply: ``` .. qmp-example:: :annotated: Blah blah:: -> { "lorem": "ipsum" } ``` Once the directive block is exited, whatever the previous default highlight language was will be restored; localizing the forced QMP lexing to exclusively this directive. Note, if the default language is *already* QMP, this directive will not generate and restore redundant highlight configuration nodes. We may well decide that the default language ought to be QMP for any QAPI reference pages, but this way the directive behaves consistently no matter where it is used. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-5-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17docs/qapidoc: create qmp-example directiveJohn Snow
This is a directive that creates a syntactic sugar for creating "Example" boxes very similar to the ones already used in the bitmaps.rst document, please see e.g. https://www.qemu.org/docs/master/interop/bitmaps.html#creation-block-dirty-bitmap-add In its simplest form, when a custom title is not needed or wanted, and the example body is *solely* a QMP example: ``` .. qmp-example:: {body} ``` is syntactic sugar for: ``` .. admonition:: Example: .. code-block:: QMP {body} ``` When a custom, plaintext title that describes the example is desired, this form: ``` .. qmp-example:: :title: Defrobnification {body} ``` Is syntactic sugar for: ``` .. admonition:: Example: Defrobnification .. code-block:: QMP {body} ``` Lastly, when Examples are multi-step processes that require non-QMP exposition, have lengthy titles, or otherwise involve prose with rST markup (lists, cross-references, etc), the most complex form: ``` .. qmp-example:: :annotated: This example shows how to use `foo-command`:: {body} For more information, please see `frobnozz`. ``` Is desugared to: ``` .. admonition:: Example: This example shows how to use `foo-command`:: {body} For more information, please see `frobnozz`. ``` Note that :annotated: and :title: options can be combined together, if desired. The primary benefit here being documentation source consistently using the same directive for all forms of examples to ensure consistent visual styling, and ensuring all relevant prose is visually grouped alongside the code literal block. Note that as of this commit, the code-block rST syntax "::" does not apply QMP highlighting; you would need to use ".. code-block:: QMP". The very next commit changes this behavior to assume all "::" code blocks within this directive are QMP blocks. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-4-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17docs/qapidoc: factor out do_parse()John Snow
Factor out the compatibility parser helper into a base class, so it can be shared by other directives. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240717021312.606116-3-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-12docs: remove Sphinx 1.x compatibility codeJohn Snow
In general, the Use_SSI workaround is no longer needed, and neither is the pre-1.6 logging shim for kerneldoc. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-id: 20240703175235.239004-3-jsnow@redhat.com [rebased on top of origin/master. --js] Signed-off-by: John Snow <jsnow@redhat.com>
2024-07-12Python: bump minimum sphinx version to 3.4.3John Snow
With RHEL 8 support retired (It's been two years since RHEL9 released), our very oldest build platform version of Sphinx is now 3.4.3; and keeping backwards compatibility for versions as old as v1.6 when using domain extensions is a lot of work we don't need to do. This patch is motivated by my work creating a new QAPI domain, which unlike the dbus documentation, cannot be allowed to regress by creating a "dummy" doc when operating under older sphinx versions. Easier is to raise our minimum version as far as we can push it forwards, reducing my burden in creating cross-compatibility hacks and patches. A sampling of sphinx versions from various distributions, courtesy https://repology.org/project/python:sphinx/versions Alpine 3.16: v4.3.0 (QEMU support ended 2024-05-23) Alpine 3.17: v5.3.0 Alpine 3.18: v6.1.3 Alpine 3.19: v6.2.1 Ubuntu 20.04 LTS: EOL Ubuntu 22.04 LTS: v4.3.2 Ubuntu 22.10: EOL Ubuntu 23.04: EOL Ubuntu 23.10: v5.3.0 Ubuntu 24.04 LTS: v7.2.6 Debian 11: v3.4.3 (QEMU support ends 2024-07-xx) Debian 12: v5.3.0 Fedora 38: EOL Fedora 39: v6.2.1 Fedora 40: v7.2.6 CentOS Stream 8: v1.7.6 (QEMU support ended 2024-05-17) CentOS Stream 9: v3.4.3 OpenSUSE Leap 15.4: EOL OpenSUSE Leap 15.5: 2.3.1, 4.2.0 and 7.2.6 RHEL9 / CentOS Stream 9 becomes the new defining factor in staying at Sphinx 3.4.3 due to downstream offline build requirements that force us to use platform Sphinx instead of newer packages from PyPI. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Paolo Bonzini <pbonzini@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-id: 20240703175235.239004-2-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
2024-07-06sphinx/qapidoc: Fix to generate doc for explicit, unboxed argumentsMarkus Armbruster
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: convert "Note" sections to plain rSTJohn Snow
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 Snow
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-06docs/qapidoc: fix nested parsing under untagged sectionsJohn Snow
Sphinx does not like sections without titles, because it wants to convert every section into a reference. When there is no title, it struggles to do this and transforms the tree inproperly. Depending on the rST used, this may result in an assertion error deep in the docutils HTMLWriter. (Observed when using ".. admonition:: Notes" under such a section - When this is transformed with its own <title> element, Sphinx is fooled into believing this title belongs to the section and incorrect mutates the docutils tree, leading to errors during rendering time.) When parsing an untagged section (free paragraphs), skip making a hollow section and instead append the parse results to the prior section. Many Bothans died to bring us this information. The resulting output changes are basically invisible. Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-8-jsnow@redhat.com> [Mention output changes in commit message] Signed-off-by: Markus Armbruster <armbru@redhat.com>
generated by cgit v1.2.3 (git 2.26.2) at 2024-12-19 03:13:38 +0000