summary refs log tree commit diff stats
path: root/docs/devel (follow)
Commit message (Collapse)AuthorAgeFilesLines
* docs/devel: remove dead video link for sourcehut submit processPierrick Bouvier2024-12-281-4/+1
| | | | | | | | Reviewed-by: Thomas Huth <thuth@redhat.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Reviewed-by: Michael Tokarev <mjt@tls.msk.ru> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
* include/hw/qdev-properties: Remove DEFINE_PROP_END_OF_LISTRichard Henderson2024-12-192-2/+0
| | | | | | | | | | | | | | Now that all of the Property arrays are counted, we can remove the terminator object from each array. Update the assertions in device_class_set_props to match. With struct Property being 88 bytes, this was a rather large form of terminator. Saves 30k from qemu-system-aarch64. Signed-off-by: Richard Henderson <richard.henderson@linaro.org> Tested-by: Lei Yang <leiyang@redhat.com> Link: https://lore.kernel.org/r/20241218134251.4724-21-richard.henderson@linaro.org Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* docs: Constify all Property in examplesRichard Henderson2024-12-152-3/+3
| | | | | Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
* docs/devel/testing/functional: Clarify that we have to use the build folderThomas Huth2024-11-271-2/+3
| | | | | | | | | Make it clear that the commands have to be run from the folder with the build, and use the python3 from our pyvenv to make sure that the pycotap module is available. Message-ID: <20241112115302.470527-1-thuth@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* docs: explicitly permit a "commonly known identity" with SoBDaniel P. Berrangé2024-11-251-1/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The docs for submitting a patch describe using your "Real Name" with the Signed-off-by line. Although somewhat ambiguous, this has often been interpreted to mean someone's legal name. In recent times, there's been a general push back[1] against the notion that use of Signed-off-by in a project automatically requires / implies the use of legal ("real") names and greater awareness of the downsides. Full discussion of the problems of such policies is beyond the scope of this commit message, but at a high level they are liable to marginalize, disadvantage, and potentially result in harm, to contributors. TL;DR: there are compelling reasons for a person to choose distinct identities in different contexts & a decision to override that choice should not be taken lightly. A number of key projects have responded to the issues raised by making it clear that a contributor is free to determine the identity used in SoB lines: * Linux has clarified[2] that they merely expect use of the contributor's "known identity", removing the previous explicit rejection of pseudonyms. * CNCF has clarified[3] that the real name is simply the identity the contributor chooses to use in the context of the community and does not have to be a legal name, nor birth name, nor appear on any government ID. Since we have no intention of ever routinely checking any form of ID documents for contributors[4], realistically we have no way of knowing anything about the name they are using, except through chance, or through the contributor volunteering the information. IOW, we almost certainly already have people using pseudonyms for contributions. This proposes to accept that reality and eliminate unnecessary friction, by following Linux & the CNCF in merely asking that a contributors' commonly known identity, of their choosing, be used with the SoB line. [1] Raised in many contexts at many times, but a decent overall summary can be read at https://drewdevault.com/2023/10/31/On-real-names.html [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=d4563201f33a022fc0353033d9dfeb1606a88330 [3] https://github.com/cncf/foundation/blob/659fd32c86dc/dco-guidelines.md [4] Excluding the rare GPG key signing parties for regular maintainers Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Acked-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Richard Henderson <richard.henderson@linaro.org> Message-Id: <20241021190939.1482466-1-berrange@redhat.com> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20241121165806.476008-40-alex.bennee@linaro.org>
* tests/functional: add a QMP backdoor for debugging stalled testsDaniel P. Berrangé2024-11-251-0/+10
| | | | | | | | | | | | | | | | | | | | | Support the QEMU_TEST_QMP_BACKDOOR=backdoor.sock env variable as a way to get a QMP backdoor for debugging a stalled QEMU test. Most typically this would be used if running the tests directly: $ QEMU_TEST_QMP_BACKDOOR=backdoor.sock \ QEMU_TEST_QEMU_BINARY=./build/qemu-system-arm \ PYTHONPATH=./python \ ./tests/functional/test_arm_tuxrun.py And then, when the test stalls, in a second shell run: $ ./scripts/qmp/qmp-shell backdoor.sock Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20241121154218.1423005-18-berrange@redhat.com> Reviewed-by: Thomas Huth <thuth@redhat.com> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20241121165806.476008-18-alex.bennee@linaro.org>
* tests/functional: automatically clean up scratch files after testsDaniel P. Berrangé2024-11-251-0/+6
| | | | | | | | | | | | | | | | The build/tests/functional subdirectories are consuming huge amounts of disk space. Split the location for scratch files into a 'scratch' sub-directory, separate from log files, and delete it upon completion of each test. The new env variable QEMU_TEST_KEEP_SCRATCH can be set to preserve this scratch dir for debugging access if required. Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20241121154218.1423005-3-berrange@redhat.com> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20241121165806.476008-3-alex.bennee@linaro.org>
* docs/devel/reset: Fix minor grammatical errorPeter Maydell2024-10-291-2/+2
| | | | | | | | | | | Fix a minor grammatical error in the reset documentation: a couple of missing words and a singular/plural swap. Signed-off-by: Axel Heider <axel.heider@codasip.com> Message-id: 173006362760.28451.11319467059840843945-1@git.sr.ht [PMM: squashed two patches into one, tweaked commit message] Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
* docs/devel: update tsan build documentationPierrick Bouvier2024-10-241-4/+22
| | | | | | | | | | | Mention it's now possible to build with gcc, instead of clang, and explain how to build a sanitized glib version. Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-Id: <20240910174013.1433331-4-pierrick.bouvier@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20241023113406.1284676-6-alex.bennee@linaro.org>
* docs/devel/lockcnt: Include kernel-doc API documentationPeter Maydell2024-10-151-1/+1
| | | | | | | | | Pull in the kernel-doc API documentation into the lockcnt docs. This requires us to fix one rST markup syntax error in the header file comments. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20240816132212.3602106-8-peter.maydell@linaro.org
* include: Move QemuLockCnt APIs to their own headerPeter Maydell2024-10-151-1/+1
| | | | | | | | | | | | | | | | | | | | | | Currently the QemuLockCnt data structure and associated functions are in the include/qemu/thread.h header. Move them to their own qemu/lockcnt.h. The main reason for doing this is that it means we can autogenerate the documentation comments into the docs/devel documentation. The copyright/author in the new header is drawn from lockcnt.c, since the header changes were added in the same commit as lockcnt.c; since neither thread.h nor lockcnt.c state an explicit license, the standard default of GPL-2-or-later applies. We include the new header (and the .c file, which was accidentally omitted previously) in the "RCU" part of MAINTAINERS, since that is where the lockcnt.rst documentation is categorized. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Acked-by: Paolo Bonzini <pbonzini@redhat.com> Message-id: 20240816132212.3602106-7-peter.maydell@linaro.org
* docs/devel/rcu: Convert to rST formatPeter Maydell2024-10-152-92/+81
| | | | | | | Convert docs/devel/rcu.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20240816132212.3602106-6-peter.maydell@linaro.org
* docs/devel/multiple-iothreads: Convert to rST formatPeter Maydell2024-10-153-130/+140
| | | | | | | Convert docs/devel/multiple-iothreads.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20240816132212.3602106-5-peter.maydell@linaro.org
* docs/devel/lockcnt: Convert to rST formatPeter Maydell2024-10-152-44/+46
| | | | | | | Convert docs/devel/lockcnt.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20240816132212.3602106-4-peter.maydell@linaro.org
* docs/devel/blkverify: Convert to rST formatPeter Maydell2024-10-152-13/+18
| | | | | | | | Convert blkverify.txt to rST format. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-id: 20240816132212.3602106-3-peter.maydell@linaro.org
* docs/devel/blkdebug: Convert to rST formatPeter Maydell2024-10-153-162/+178
| | | | | | | | | | Convert blkdebug.txt to rST format. We put it into index-build.rst because it falls under the "test" part of "QEMU Build and Test System". Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-id: 20240816132212.3602106-2-peter.maydell@linaro.org
* hw/clock: Expose 'qtest-clock-period' QOM property for QTestsInès Varhol2024-10-151-0/+6
| | | | | | | | | | | | | Expose the clock period via the QOM 'qtest-clock-period' property so it can be used in QTests. This property is only accessible in QTests (not via HMP). Signed-off-by: Inès Varhol <ines.varhol@telecom-paris.fr> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Luc Michel <luc@lmichel.fr> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20241003081105.40836-3-ines.varhol@telecom-paris.fr Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
* docs: use consistent markup for footnotesPaolo Bonzini2024-10-115-9/+9
| | | | | | | | | | | | | | Unfortunately, the definition of the footnote syntax requires the author to use the awkward escaped space "\ " in the really common case of "footnote marker at end of word or sentence"; and in fact the rST documentation's examples of footnote syntax contain only artificial examples that do *not* use the syntax. This resulted in ugly rendering of footnotes throughout QEMU's documentation. Ensure the space is escaped whenever the footnote must attach to the preceding word, and also use a named reference for clarity. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* docs: avoid footnotes consisting of just URLsPaolo Bonzini2024-10-111-13/+13
| | | | | | | | | | | | | | Replace the footnotes with inline links whenever the footnote text consists of nothing but the URL. While at it, make the link texts consistent in the surrounding areas, for example avoiding usage of "here" for the link's text. In the case of acpi-bits.rst this fixes a build failure with Sphinx 8.1.0, because the FOSDEM link was duplicated in the paragraph and the new version is a lot stricter about unreferenced footnotes. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* docs: fix invalid footnote syntaxPaolo Bonzini2024-10-112-3/+3
| | | | | | | | | | | | | | All footnotes must come after a separator in reStructuredText. Fix the two files in which this does not happen. This mistake causes the link to be rendered literally: ...from the venv itself[#distlib]_. If no... and is caught by Sphinx 8.1.0 as an unreferenced footnote. Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* docs/devel: Mention post_load hook restrictions where we document the hookPeter Maydell2024-10-042-0/+9
| | | | | | | | | | | | | | | | Accessing another device in a post_load hook is a bad idea, because the order of device save/restore is not fixed, and so this cross-device access makes the save/restore non-deterministic. We previously only flagged up this requirement in the record-and-replay developer docs; repeat it in the main migration documentation, where a developer trying to implement a post_load hook is more likely to see it. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Michael Tokarev <mjt@tls.msk.ru> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
* reset: Add RESET_TYPE_WAKEUPJuraj Marcin2024-09-241-1/+11
| | | | | | | | | | | Some devices need to distinguish cold start reset from waking up from a suspended state. This patch adds new value to the enum, and updates the i386 wakeup method to use this new reset type. Message-ID: <20240904103722.946194-3-jmarcin@redhat.com> Reviewed-by: David Hildenbrand <david@redhat.com> Signed-off-by: Juraj Marcin <jmarcin@redhat.com> Signed-off-by: David Hildenbrand <david@redhat.com>
* docs/devel: Remove nested-papr.txtPeter Maydell2024-09-191-119/+0
| | | | | | | | | | | | | | | | docs/devel/nested-papr.txt is entirely (apart from the initial paragraph) a partial copy of the kernel documentation https://docs.kernel.org/arch/powerpc/kvm-nested.html There's no benefit to the QEMU docs to converting this to rST, so instead delete it. Anybody needing to know the API and protocol for the guest to communicate with the hypervisor to created nested VMs should refer to the authoratitative documentation in the kernel docs. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Daniel Henrique Barboza <danielhb413@gmail.com> Message-id: 20240816133318.3603114-1-peter.maydell@linaro.org
* docs/fuzz: fix outdated mention to enable-sanitizersMatheus Tavares Bernardino2024-09-171-2/+3
| | | | | | | | | | | This options has been removed at cb771ac1f5 (meson: Split --enable-sanitizers to --enable-{asan, ubsan}, 2024-08-13), so let's update its last standing mention in the docs. Signed-off-by: Matheus Tavares Bernardino <quic_mathbern@quicinc.com> Reviewed-by: Brian Cain <bcain@quicinc.com> Message-ID: <0ecf4e1ab26771009d74a2ce61e7c17ddc586ef7.1726226316.git.quic_mathbern@quicinc.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* target/s390: Convert CPU to Resettable interfacePeter Maydell2024-09-131-0/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Convert the s390 CPU to the Resettable interface. This is slightly more involved than the other CPU types were (see commits 9130cade5fc22..d66e64dd006df) because S390 has its own set of different kinds of reset with different behaviours that it needs to trigger. We handle this by adding these reset types to the Resettable ResetType enum. Now instead of having an underlying implementation of reset that is s390-specific and which might be called either directly or via the DeviceClass::reset method, we can implement only the Resettable hold phase method, and have the places that need to trigger an s390-specific reset type do so by calling resettable_reset(). The other option would have been to smuggle in the s390 reset type via, for instance, a field in the CPU state that we set in s390_do_cpu_initial_reset() etc and then examined in the reset method, but doing it this way seems cleaner. The motivation for this change is that this is the last caller of the legacy device_class_set_parent_reset() function, and removing that will let us clean up some glue code that we added for the transition to three-phase reset. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Nina Schoetterl-Glausch <nsg@linux.ibm.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Acked-by: Thomas Huth <thuth@redhat.com> Message-id: 20240830145812.1967042-4-peter.maydell@linaro.org
* Merge tag 'pull-request-2024-09-11' of https://gitlab.com/thuth/qemu into ↵Peter Maydell2024-09-111-2/+2
|\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | staging * Split --enable-sanitizers to --enable-{asan, ubsan} * Build MSYS2 job using multiple CPUs * Fix "make distclean" wrt contrib/plugins/ * Convert more Avocado tests to plain standalone functional tests * Fix bug that breaks "make check-functional" when tesseract is missing * Use builtin hashlib of Python in the functional tests * Update the FreeBSD CI jobs to 14.1 # -----BEGIN PGP SIGNATURE----- # # iQJFBAABCAAvFiEEJ7iIR+7gJQEY8+q5LtnXdP5wLbUFAmbhY4YRHHRodXRoQHJl # ZGhhdC5jb20ACgkQLtnXdP5wLbU/aw/9HXl9H8BUDn8lnoEmxuuQSk8F19n/l5pt # en3L8pMBt4dGFe/9KaGes2GFfid+cp2zlx+qQhA4HW35ntMJorF/qinOH/JGDtoM # 3O6RGZrQPn60zD9P2EbFVCrVYysVYCEu0U3Uglj6tf33bE0L7SJsQxqcbIciyIj5 # aq3Te0yMM2lqzCdMqNpWHGn3VMZRvbRaGBPDU4RLP8V2Bpz1iiRE+6HCH9Kg7HzS # OmleeXtvcyInG+54onjfTcn4/XA27pl1UU04KFv5PrRPB3M2FspHn7oOT2yyQ+ls # 79mqIcd8PvycCT+3ch9p8KhVtbVBgZGmeemALLvk5FxysaWnl4KtSqmQNdqSvvpV # waDDKlLaSnjEHDUse3bCJX0m4d7/vTBY5fOYxqZ4z5dl63csDtgPY4/VF4XR08sP # tR1mW+2qEH9eygsxuKcBjx/j7Etpy+jL9pX2ii1V3ElhjjYuEnpEiURa+TaqPjpZ # jmPtBEszzUdPbrD707tDkW3/ezT7VAnASQeYneJXB/JQG6K6Z//05iX6oCzCbRm3 # ceW/fem3UaeGYpzbMdoZToTuNlXEyS7NDcr39xJjH4LyRTPJAX4zeqUEdzces9g/ # u4Dw6rJ0Yhj4rscKxRvGl3/BH6CTI+8IAsbju2B/CnVLTqaABB0q/MDB90aB44xX # bAVsl4P03Uk= # =5TR0 # -----END PGP SIGNATURE----- # gpg: Signature made Wed 11 Sep 2024 10:31:50 BST # gpg: using RSA key 27B88847EEE0250118F3EAB92ED9D774FE702DB5 # gpg: issuer "thuth@redhat.com" # gpg: Good signature from "Thomas Huth <th.huth@gmx.de>" [full] # gpg: aka "Thomas Huth <thuth@redhat.com>" [full] # gpg: aka "Thomas Huth <huth@tuxfamily.org>" [full] # gpg: aka "Thomas Huth <th.huth@posteo.de>" [unknown] # Primary key fingerprint: 27B8 8847 EEE0 2501 18F3 EAB9 2ED9 D774 FE70 2DB5 * tag 'pull-request-2024-09-11' of https://gitlab.com/thuth/qemu: (24 commits) Update FreeBSD CI jobs FreeBSD 14.1 tests/functional/qemu_test: Use Python hashlib instead of external programs tests/functional: Fix bad usage of has_cmd tests/functional: Convert the multiprocess avocado test into a standalone test tests/functional: Convert the or1k-sim Avocado test tests/functional: Convert the m68k MCF5208EVB Avocado test tests/functional: Convert the Alpha Clipper Avocado test tests/functional: Convert Aarch64 Raspi4 avocado tests tests/functional: Convert Aarch64 Raspi3 avocado tests tests/functional: Convert ARM Raspi2 avocado tests tests/functional: Convert mips32eb 4Kc Malta avocado tests tests/functional: Convert nanomips Malta avocado tests tests/functional: Convert mips32el Malta YAMON avocado test tests/functional: Convert mips64el 5KEc Malta avocado tests tests/functional: Convert mips64el I6400 Malta avocado tests tests/functional: Convert mips64el Fuloong2e avocado test (2/2) tests/functional: Convert the m68k Q800 Avocado test into a functional test tests/functional: Add the LinuxKernelTest for testing the Linux boot process MAINTAINERS: Remove myself from the Meson section MAINTAINERS: Remove myself as reviewer ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
| * meson: Split --enable-sanitizers to --enable-{asan, ubsan}Richard Henderson2024-09-111-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We do not always want both address and undefined behavior sanitizers running at the same time. For the gitlab custom-runners, drop to only --enable-ubsan. These jobs are not run by default, but as will be obvious in the next patch, we don't run ASan on x86 either, and it seems wrong to hold aarch64 and s390x to a different standard. Signed-off-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Thomas Huth <thuth@redhat.com> Message-ID: <20240813095216.306555-2-richard.henderson@linaro.org> Signed-off-by: Thomas Huth <thuth@redhat.com>
* | docs/devel: fix duplicate lineAlex Bennée2024-09-101-6/+0
|/ | | | | | | | | | I guess the same change came in via two patch series. Remove the repetition. Fixes: 2a851fca9f (docs/devel: remind developers to run CI container pipeline when updating images) Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20240910173900.4154726-5-alex.bennee@linaro.org>
* docs/migration: add qatzip compression featureYuan Liu2024-09-092-0/+166
| | | | | | | | | | | | add Intel QATzip compression method introduction Reviewed-by: Nanhai Zou <nanhai.zou@intel.com> Reviewed-by: Peter Xu <peterx@redhat.com> Reviewed-by: Fabiano Rosas <farosas@suse.de> Signed-off-by: Yuan Liu <yuan1.liu@intel.com> Signed-off-by: Yichen Wang <yichen.wang@bytedance.com> Link: https://lore.kernel.org/r/20240830232722.58272-2-yichen.wang@bytedance.com Signed-off-by: Peter Xu <peterx@redhat.com>
* docs/devel/testing: Add documentation for functional testsThomas Huth2024-09-043-0/+351
| | | | | | | | | Document the new functional testing framework. The text is originally based on the Avocado documentation, but heavily modified to match the new framework. Message-ID: <20240830133841.142644-45-thuth@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* docs/devel/testing: Rename avocado_qemu.Test classThomas Huth2024-09-041-16/+16
| | | | | | | | | | The avocado_qemu.Test class has been renamed a while back in commit 2283b627bc ("tests/avocado: Rename avocado_qemu.Test -> QemuSystemTest"), so we should reflect this now in the documentation, too. Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240830133841.142644-44-thuth@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* docs/devel/testing: Split the Avocado documentation into a separate fileThomas Huth2024-09-043-564/+583
| | | | | | | | | The main testing documentation file got very overloaded already. Thus let's split the Avocado information into a separate file. Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-ID: <20240830133841.142644-43-thuth@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* docs/devel: Split testing docs from the build docs and move to separate folderThomas Huth2024-09-0412-10/+19
| | | | | | | | Building and testing are two separate topics, so let's split the testing into a separate category and move the related files into a separate folder. Message-ID: <20240830133841.142644-42-thuth@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* tests/functional: Convert the acpi-bits test into a standalone testThomas Huth2024-09-041-37/+25
| | | | | | | | | | | Mostly a straight-forward conversion. Looks like we can simply drop the avocado datadrainer stuff when not using the avocado framework anymore. Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Tested-by: Philippe Mathieu-Daudé <philmd@linaro.org> Message-ID: <20240830133841.142644-30-thuth@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
* docs/devel: update tcg-plugins pagePierrick Bouvier2024-08-161-5/+8
| | | | | | | | | 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>
* docs: Fix some typos (found by typos) and grammar issuesStefan Weil2024-08-161-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>
* docs: split TCG plugin usage from devel sectionAlex Bennée2024-07-301-505/+0
| | | | | | | | | | | | | | | 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>
* docs/devel: document how to run individual TCG testsAlex Bennée2024-07-301-0/+13
| | | | | | | | | | | 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>
* docs/devel: update the testing introductionAlex Bennée2024-07-301-3/+18
| | | | | | | | | 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>
* docs/devel: Add introduction to LUKS volume with detached headerHyman Huang2024-07-243-0/+193
| | | | | Signed-off-by: Hyman Huang <yong.huang@smartx.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
* plugins/stoptrigger: TCG plugin to stop execution under conditionsSimon Hamelin2024-07-221-0/+22
| | | | | | | | | | | | | | | | | | | 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>
* qapi: remove "Example" doc sectionJohn Snow2024-07-171-9/+49
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: convert "Note" sections to plain rSTJohn Snow2024-07-061-4/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: nail down convention that Errors sections are listsJohn Snow2024-07-061-0/+7
| | | | | | | | | | 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>
* meson: Drop the .fa library suffixPaolo Bonzini2024-07-031-5/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | The non-standard .fa library suffix breaks the link source de-duplication done by Meson so drop it. The lack of link source de-duplication causes AddressSanitizer to complain ODR violations, and makes GNU ld abort when combined with clang's LTO. Fortunately, the non-standard suffix is not necessary anymore for two reasons. First, the non-standard suffix was necessary for fork-fuzzing. Meson wraps all standard-suffixed libraries with --start-group and --end-group. This made a fork-fuzz.ld linker script wrapped as well and broke builds. Commit d2e6f9272d33 ("fuzz: remove fork-fuzzing scaffolding") dropped fork-fuzzing so we can now restore the standard suffix. Second, the libraries are not even built anymore, because it is possible to just use the object files directly via extract_all_objects(). The occurences of the suffix were detected and removed by performing a tree-wide search with 'fa' and .fa (note the quotes and dot). Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com> Message-ID: <20240524-xkb-v4-4-2de564e5c859@daynix.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* meson: Pass objects and dependencies to declare_dependency()Akihiko Odaki2024-07-031-1/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We used to request declare_dependency() to link_whole static libraries. If a static library is a thin archive, GNU ld keeps all object files referenced by the archive open, and sometimes exceeds the open file limit. Another problem with link_whole is that suboptimal handling of nested dependencies. link_whole by itself does not propagate dependencies. In particular, gnutls, a dependency of crypto, is not propagated to its users, and we currently workaround the issue by declaring gnutls as a dependency for each crypto user. On the other hand, if you write something like libfoo = static_library('foo', 'foo.c', dependencies: gnutls) foo = declare_dependency(link_whole: libfoo) libbar = static_library('bar', 'bar.c', dependencies: foo) bar = declare_dependency(link_whole: libbar, dependencies: foo) executable('prog', sources: files('prog.c'), dependencies: [foo, bar]) hoping to propagate the gnutls dependency into bar.c, you'll see a linking failure for "prog", because the foo.c.o object file is included in libbar.a and therefore it is linked twice into "prog": once from libfoo.a and once from libbar.a. Here Meson does not see the duplication, it just asks the linker to link all of libfoo.a and libbar.a into "prog". Instead of using link_whole, extract objects included in static libraries and pass them to declare_dependency(); and then the dependencies can be added as well so that they are propagated, because object files on the linker command line are always deduplicated. This requires Meson 1.1.0 or later. Signed-off-by: Akihiko Odaki <akihiko.odaki@daynix.com> Message-ID: <20240524-objects-v1-1-07cbbe96166b@daynix.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
* docs: add precision about capstone for execlog pluginAlexandre Iooss2024-07-021-1/+3
| | | | | | | | | | | Some people are wondering why they get an empty string as disassembly. Most of the time, they configured QEMU without Capstone support. Let's document this behaviour to help users. Signed-off-by: Alexandre Iooss <erdnaxe@crans.org> Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Message-ID: <20240620135731.977377-1-erdnaxe@crans.org> Signed-off-by: Thomas Huth <thuth@redhat.com>
* migration/docs: Update postcopy recover session for SETUP phasePeter Xu2024-06-211-15/+16
| | | | | | | | | | | | | | Firstly, the "Paused" state was added in the wrong place before. The state machine section was describing PostcopyState, rather than MigrationStatus. Drop the Paused state descriptions. Then in the postcopy recover session, add more information on the state machine for MigrationStatus in the lines. Add the new RECOVER_SETUP phase. Reviewed-by: Fabiano Rosas <farosas@suse.de> Signed-off-by: Peter Xu <peterx@redhat.com> [fix typo s/reconnects/reconnect] Signed-off-by: Fabiano Rosas <farosas@suse.de>
* migration: Add documentation for fdset with multifd + fileFabiano Rosas2024-06-212-6/+24
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | With the last few changes to the fdset infrastructure, we now allow multifd to use an fdset when migrating to a file. This is useful for the scenario where the management layer wants to have control over the migration file. By receiving the file descriptors directly, QEMU can delegate some high level operating system operations to the management layer (such as mandatory access control). The management layer might also want to add its own headers before the migration stream. Document the "file:/dev/fdset/#" syntax for the multifd migration with mapped-ram. The requirements for the fdset mechanism are: - the fdset must contain two fds that are not duplicates between themselves; - if direct-io is to be used, exactly one of the fds must have the O_DIRECT flag set; - the file must be opened with WRONLY on the migration source side; - the file must be opened with RDONLY on the migration destination side. Reviewed-by: Peter Xu <peterx@redhat.com> Signed-off-by: Fabiano Rosas <farosas@suse.de>
* docs/migration: add uadk compression featureShameer Kolothum2024-06-142-0/+145
| | | | | | | | | | Document UADK(User Space Accelerator Development Kit) library details and how to use that for migration. Signed-off-by: Shameer Kolothum <shameerali.kolothum.thodi@huawei.com> Reviewed-by: Zhangfei Gao <zhangfei.gao@linaro.org> [s/Qemu/QEMU in docs] Signed-off-by: Fabiano Rosas <farosas@suse.de>