qemu/docs/devel, branch master

docs/devel: update tcg-plugins page

2024-08-16T13:13:07Z

Reflect recent changes on API (inline ops) and new plugins. Signed-off-by: Pierrick Bouvier Message-Id: <20240812231945.169310-1-pierrick.bouvier@linaro.org> Signed-off-by: Alex Bennée Message-Id: <20240813202329.1237572-21-alex.bennee@linaro.org>

docs: Fix some typos (found by typos) and grammar issues

2024-08-16T13:12:59Z

Fix the misspellings of "overriden" also in code comments. Signed-off-by: Stefan Weil Reviewed-by: Peter Maydell Message-Id: <20240813125638.395461-1-sw@weilnetz.de> Reviewed-by: Peter Xu Reviewed-by: Eric Auger Signed-off-by: Alex Bennée Message-Id: <20240813202329.1237572-20-alex.bennee@linaro.org>

docs: split TCG plugin usage from devel section

2024-07-30T10:44:18Z

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 Signed-off-by: Alex Bennée Message-Id: <20240729144414.830369-11-alex.bennee@linaro.org>

docs/devel: document how to run individual TCG tests

2024-07-30T10:44:18Z

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 Signed-off-by: Alex Bennée Message-Id: <20240729144414.830369-8-alex.bennee@linaro.org>

docs/devel: update the testing introduction

2024-07-30T10:44:18Z

Move the mention of "check-help" up to the intro text and also mention the meson test integration. Reviewed-by: Richard Henderson Signed-off-by: Alex Bennée Message-Id: <20240729144414.830369-7-alex.bennee@linaro.org>

docs/devel: Add introduction to LUKS volume with detached header

2024-07-24T09:39:10Z

Signed-off-by: Hyman Huang Signed-off-by: Daniel P. Berrangé

plugins/stoptrigger: TCG plugin to stop execution under conditions

2024-07-22T08:37:56Z

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 Signed-off-by: Simon Hamelin Signed-off-by: Alexandre Iooss Reviewed-by: Pierrick Bouvier Message-Id: <20240715081521.19122-2-simon.hamelin@grenoble-inp.org> Signed-off-by: Alex Bennée Message-Id: <20240718094523.1198645-5-alex.bennee@linaro.org>

qapi: remove "Example" doc section

2024-07-17T08:20:54Z

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 Message-ID: <20240717021312.606116-10-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster

qapi: convert "Note" sections to plain rST

2024-07-06T06:58:24Z

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 Acked-by: Stefan Hajnoczi [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster

qapi: nail down convention that Errors sections are lists

2024-07-06T06:58:24Z

By unstated convention, Errors sections are rST lists. Document the convention, and make the one exception conform. Signed-off-by: John Snow Reviewed-by: Markus Armbruster Message-ID: <20240626222128.406106-10-jsnow@redhat.com> Signed-off-by: Markus Armbruster