summary refs log tree commit diff stats
path: root/docs/devel/qapi-code-gen.rst (follow)
Commit message (Collapse)AuthorAgeFilesLines
* docs/devel/qapi-code-gen: Update cross-reference syntaxMarkus Armbruster2025-08-091-3/+8
| | | | | | | | | | | | | | The new QAPI code generator creates a cross-reference target for each definition documentation. Enabled for the QEMU QMP Reference manual in commit a377f39f38f, and for the QEMU Storage Daemon QMP Reference Manual and the QEMU Guest Agent Protocol Reference in commit a6af5443440. We've put these targets to use since, but neglected to update doc comment markup documentation. Do that now. Co-developed-by: John Snow <jsnow@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250731054044.4011789-4-armbru@redhat.com>
* docs/devel/qapi-code-gen: Fix typos in QAPI schema language grammarMarkus Armbruster2025-08-091-2/+2
| | | | | | | Fixes: 3248c1aaf2db (docs: update the documentation upfront about schema configuration) Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250731054044.4011789-3-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* docs/devel/qapi-code-gen: Add two cross-references we missedMarkus Armbruster2025-08-091-2/+2
| | | | | | | | | Missed in commit 9c66762a601 (docs/qapi-code-gen: add cross-references). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250731054044.4011789-2-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* docs/sphinx: remove special parsing for freeform sectionsJohn Snow2025-07-141-9/+19
| | | | | | | | | | | | | | | | | Remove the QAPI doc section heading syntax, use plain rST section headings instead. Tests and documentation are updated to match. Interestingly, Plain rST headings work fine before this patch, except for over- and underlining with '=', which the doc parser rejected as invalid QAPI doc section heading in free-form comments. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250618165353.1980365-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Add more detail to commit message] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* docs/sphinx/qmp_lexer: Generalize elision syntaxMarkus Armbruster2025-04-081-2/+4
| | | | | | | | Accept "... lorem ipsum ..." in addition to "...". Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250404121413.1743790-7-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* docs/devel/qapi-code-gen: Improve the part on qmp-example directiveMarkus Armbruster2025-04-081-9/+14
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250404121413.1743790-6-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* docs/devel/qapi-code-gen: Tidy up whitespaceMarkus Armbruster2025-04-081-12/+14
| | | | | | | | | | Consistently use two spaces to separate sentences. Put "::" on a line of its own when it's preceded by whitespace. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250404121413.1743790-2-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* docs/devel/qapi-code-gen: Discourage use of 'prefix'Markus Armbruster2025-03-061-1/+2
| | | | | | | | | | | QAPI's 'prefix' feature can make the connection between enumeration type and its constants less than obvious. It's best used with restraint. Commit 7bbadc60b5..64f5e9db77 eliminated most uses. Discourage new ones. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250228134335.132278-1-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
* qapi: Move and rename qapi/qmp/dispatch.h to qapi/qmp-registry.hDaniel P. Berrangé2025-02-101-1/+1
| | | | | | | | | | | | | | | | | | The general expectation is that header files should follow the same file/path naming scheme as the corresponding source file. There are various historical exceptions to this practice in QEMU, with one of the most notable being the include/qapi/qmp/ directory. include/qapi/qmp/dispatch.h corresponds mostly to qapi/qmp-registry.c. Move and rename it to include/qapi/qmp-registry.h. Now just qerror.h is left in include/qapi/qmp/. Since it's deprecated & (slowly) getting eliminated anyway, it isn't worth moving. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Zhao Liu <zhao1.liu@intel.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20241118151235.2665921-3-armbru@redhat.com>
* qapi: Move include/qapi/qmp/ to include/qobject/Daniel P. Berrangé2025-02-101-1/+1
| | | | | | | | | | | | | | | | | | | | | | The general expectation is that header files should follow the same file/path naming scheme as the corresponding source file. There are various historical exceptions to this practice in QEMU, with one of the most notable being the include/qapi/qmp/ directory. Most of the headers there correspond to source files in qobject/. This patch corrects most of that inconsistency by creating include/qobject/ and moving the headers for qobject/ there. This also fixes MAINTAINERS for include/qapi/qmp/dispatch.h: scripts/get_maintainer.pl now reports "QAPI" instead of "No maintainers found". Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Zhao Liu <zhao1.liu@intel.com> Acked-by: Halil Pasic <pasic@linux.ibm.com> #s390x Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20241118151235.2665921-2-armbru@redhat.com> [Rebased]
* docs/devel: add a codebase sectionPierrick Bouvier2025-01-171-0/+1
| | | | | | | | | | | Present the various parts of QEMU and organization of codebase. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Message-Id: <20241209183104.365796-6-pierrick.bouvier@linaro.org> [AJB: tweak commit summary, update MAINTAINERS] Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20250116160306.1709518-36-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>
* qapi: New documentation section tag "Errors"Markus Armbruster2024-03-041-1/+5
| | | | | | | | | | | | | | We use section "Returns" for documenting both success and error response of commands. I intend to generate better command success response documentation. Easier when "Returns" documents just he success response. Create new section tag "Errors". The next two commits will move error response documentation from "Returns" sections to "Errors" sections. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240227113921.236097-4-armbru@redhat.com>
* qapi: Recognize section tags and 'Features:' only after blank lineMarkus Armbruster2024-02-261-6/+9
| | | | | | | | | Putting a blank line before section tags and 'Features:' is good, existing practice. Enforce it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-12-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
* qapi: Require descriptions and tagged sections to be indentedMarkus Armbruster2024-02-261-8/+7
| | | | | | | | | | | | By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples. Turn this into a hard rule, and apply it to examples, too. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-11-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> [Straightforward conflicts in qapi/migration.json resolved]
* qapi: Require member documentation (with loophole)Markus Armbruster2024-02-121-0/+5
| | | | | | | | | | | | | | | | | | | | | | | The QAPI generator forces you to document your stuff. Except for command arguments, event data, and members of enum and object types: these the generator silently "documents" as "Not documented". We can't require proper documentation there without first fixing all the offenders. We've always had too many offenders to pull that off. Right now, we have more than 500. Worse, we seem to fix old ones no faster than we add new ones: in the past year, we fixed 22 ones, but added 26 new ones. To help arrest the backsliding, make missing documentation an error unless the command, type, or event is in listed in new pragma documentation-exceptions. List all the current offenders: 117 commands and types in qapi/, and 9 in qga/. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-7-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
* docs/devel/qapi-code-gen: Tweak doc comment whitespaceMarkus Armbruster2024-02-121-2/+3
| | | | | | | | | Missed in commit a937b6aa739 (qapi: Reformat doc comments to conform to current conventions). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
* docs/devel/qapi-code-gen: Normalize version refs x.y.0 to just x.yMarkus Armbruster2024-02-121-2/+2
| | | | | | | | | Missed in commit 9bc6e893b72 (qapi: Normalize version references x.y.0 to just x.y). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-2-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
* docs/devel/qapi-code-gen: Fix missing ':' in tagged section docsMarkus Armbruster2024-01-261-2/+2
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240120095327.666239-2-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* docs/devel/qapi-code-gen: Don't reserve types ending with 'Kind'Markus Armbruster2024-01-261-3/+2
| | | | | | | | | | | | We reserved type names ending with 'Kind' because a simple union 'SomeSimpleUnion' generated both a struct type SomeSimpleUnion and an enum type SomeSimpleUnionKind. Gone since commit 4e99f4b12c0 (qapi: Drop simple unions). The commit neglected to update the documentation not to reserve type names ending with 'Kind'. Do that now. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20231221145727.835905-1-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* Rename "QEMU global mutex" to "BQL" in comments and docsStefan Hajnoczi2024-01-081-1/+1
| | | | | | | | | | | | | | | | The term "QEMU global mutex" is identical to the more widely used Big QEMU Lock ("BQL"). Update the code comments and documentation to use "BQL" instead of "QEMU global mutex". Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Paul Durrant <paul@xen.org> Reviewed-by: Akihiko Odaki <akihiko.odaki@daynix.com> Reviewed-by: Cédric Le Goater <clg@kaod.org> Reviewed-by: Harsh Prateek Bora <harshpb@linux.ibm.com> Message-id: 20240102153529.486531-6-stefanha@redhat.com Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
* docs/interop: Convert qmp-spec.txt to rSTPeter Maydell2023-05-221-1/+2
| | | | | | | | | | | | | | | | | | Convert the qmp-spec.txt document to restructuredText. Notable points about the conversion: * numbers at the start of section headings are removed, to match the style of the rest of the manual * cross-references to other sections or documents are hyperlinked * various formatting tweaks (notably the examples, which need the -> and <- prefixed so the QMP code-block lexer will accept them) * English prose fixed in a few places Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20230515162245.3964307-2-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> [.. code-block:: dumbed down to :: to work around CI failure]
* docs/devel/qapi-code-gen: Update doc comment conventionsMarkus Armbruster2023-05-101-25/+23
| | | | | | | | | | | The commit before previous relaxed the indentation rules to let us improve the doc comment conventions. This commit changes the written conventions. The next commits will update QAPI schemas to conform to them. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-16-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
* qapi: Relax doc string @name: description indentation rulesMarkus Armbruster2023-05-101-3/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches, enumeration values, and features: descriptions starting with "@name:". By convention, we format them like this: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, # sed do eiusmod tempor incididunt ut labore et dolore # magna aliqua. Okay for names as short as "name", but we have much longer ones. Their description gets squeezed against the right margin, like this: # @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization could # not avoid copying dirty pages. This is between # 0 and @dirty-sync-count * @multifd-channels. # (since 7.1) The description text is effectively just 50 characters wide. Easy enough to read, but can be cumbersome to write. The awkward squeeze against the right margin makes people go beyond it, which produces two undesirables: arguments about style, and descriptions that are unnecessarily hard to read, like this one: # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is # only present when the postcopy-blocktime migration capability # is enabled. (Since 3.0) We could instead format it like # @postcopy-vcpu-blocktime: # list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0) or, since the commit before previous, like # @postcopy-vcpu-blocktime: # list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0) However, I'd rather have # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. # This is only present when the postcopy-blocktime migration # capability is enabled. (Since 3.0) because this is how rST field and option lists work. To get this, we need to let the first non-blank line after the "@name:" line determine expected indentation. This fills up the indentation pitfall mentioned in docs/devel/qapi-code-gen.rst. A related pitfall still exists. Update the text to show it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-14-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> [Work around lack of walrus operator in Python 3.7 and older]
* sphinx/qapidoc: Do not emit TODO sections into user manualsMarkus Armbruster2023-05-091-2/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | QAPI doc comments are for QMP users: they go into the "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual". The doc comment TODO sections are for somebody else, namely for the people who can do: developers. Do not emit them into the user manuals. This elides the following TODOs: * SchemaInfoCommand # TODO: @success-response (currently irrelevant, because it's QGA, not QMP) This is a note to developers adding introspection to the guest agent. It makes no sense to users. * @query-hotpluggable-cpus # TODO: Better documentation; currently there is none. This is a reminder for developers. It doesn't help users. * @device_add # TODO: This command effectively bypasses QAPI completely due to its # "additional arguments" business. It shouldn't have been added to # the schema in this form. It should be qapified properly, or # replaced by a properly qapified command. Likewise. Eliding them is an improvement. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-7-armbru@redhat.com> Reviewed-by: Ani Sinha <anisinha@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
* docs/devel/qapi-code-gen: Turn FIXME admonitions into commentsMarkus Armbruster2023-05-091-7/+2
| | | | | | | | | | | | | | | We have two FIXME notes. These FIXMEs are for QAPI developers. They are not useful for QAPI schema developers. They are marked up as admonitions, which makes them look important in generated HTML. Turn them into comments. QAPI developers will still see them (they read and write the .rst). QAPI schema developers may still see them (if they read the .rst instead of the generated .html), but "this is just for QAPI developers" should be more obvious. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-3-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
* docs/devel/qapi-code-gen: Clean up use of quotes a bitMarkus Armbruster2023-05-091-6/+6
| | | | | | | | | Section "Definition documentation" uses both single and double quotes around doc text snippets. Stick to double quotes. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-2-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
* docs/devel/qapi-code-gen: Describe some doc markup pitfallsMarkus Armbruster2023-04-281-0/+53
| | | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230427095346.1238913-1-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
* qapi: Fix bullet list markup in documentationMarkus Armbruster2023-04-281-0/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Peter Maydell's commit 100cc4fe0f08 explains: rST insists on a blank line before and after a bulleted list [...] Add some extra blank lines in the doc comments so they're acceptable rST input. It missed one in qapi/trace.json. Paolo Bonzini later added another instance in qapi/stats.json, providing further, if unintended, evidence for his quip that rST is the Perl of ASCII-based markups. Both are parsed as ordinary paragraph, resulting in garbled output. John Snow missed the need for a blank line when converting docs/devel/qapi-code-gen.txt to rST. Add the blank lines we need to get the bullet lists recognized as such. Kevin Wolf and Lukas Straub added two more, but indented. Sphinx recognizes them as (indented) bullet lists. The indentation looks slightly off. Insert a blank line and delete the extra indentation. Fixes: 100cc4fe0f0827f8da1a5c05f9c65e2aaa40e03d (qapi: Add blank lines before bulleted lists) Fixes: 467ef823d83e (qmp: add filtering of statistics by target vCPU) Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20230425064223.820979-10-armbru@redhat.com> [Fix of docs/devel/qapi-code-gen.rst squashed, commit message adjusted]
* qapi: @foo should be used to reference, not ``foo``Markus Armbruster2023-04-281-3/+5
| | | | | | | | | | | | | | | Documentation suggests @foo is merely shorthand for ``foo``. It's not, it carries additional meaning: it's a reference to a QAPI schema name. Reword the documentation to spell that out. Fix up the few ``foo`` that should be @foo. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20230425064223.820979-7-armbru@redhat.com>
* qapi: Require boxed for conditional command and event argumentsMarkus Armbruster2023-04-241-3/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The C code generator fails to honor 'if' conditions of command and event arguments. For instance, tests/qapi-schema/qapi-schema-test.json has { 'event': 'TEST_IF_EVENT', 'data': { 'foo': 'TestIfStruct', 'bar': { 'type': ['str'], 'if': 'TEST_IF_EVT_ARG' } }, 'if': { 'all': ['TEST_IF_EVT', 'TEST_IF_STRUCT'] } } Generated tests/test-qapi-events.h fails to honor the TEST_IF_EVT_ARG condition: #if defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) void qapi_event_send_test_if_event(TestIfStruct *foo, strList *bar); #endif /* defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) */ Only uses so far are in tests/. We could fix the generator to emit something like #if defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) void qapi_event_send_test_if_event(TestIfStruct *foo #if defined(TEST_IF_EVT_ARG) , strList *bar #endif ); #endif /* defined(TEST_IF_EVT) && defined(TEST_IF_STRUCT) */ Ugly. Calls become similarly ugly. Not worth fixing. Conditional arguments work fine with 'boxed': true, simply because complex types with conditional members work fine. Not worth breaking. Reject conditional arguments unless boxed. Move the tests cases covering unboxed conditional arguments out of tests/qapi-schema/qapi-schema-test.json. Cover boxed conditional arguments there instead. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230316071325.492471-15-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* docs/devel/qapi-code-gen: Fix a missing 'may', clarify SchemaInfoMarkus Armbruster2023-02-231-5/+4
| | | | | | | | | | | | Documentation of enumeration value conditions lacks a 'may'. Fix that. Clarify SchemaInfo documentation for struct and union types. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230213132009.918801-3-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* docs/devel/qapi-code-gen: Belatedly update features documentationMarkus Armbruster2023-02-231-3/+4
| | | | | | | | | | | | | Commit 013b4efc9be "qapi: Add feature flags to remaining definitions" (v5.0.0), commit 84ab0086879 "qapi: Add feature flags to struct members" (v5.0.0), and commit b6c18755e41 "qapi: Add feature flags to enum members" (v6.2.0) neglected to update section "Features". Make up for that. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230213132009.918801-2-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* qapi: Start to elide redundant has_FOO in generated CMarkus Armbruster2022-12-131-2/+3
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | In QAPI, absent optional members are distinct from any present value. We thus represent an optional schema member FOO as two C members: a FOO with the member's type, and a bool has_FOO. Likewise for function arguments. However, has_FOO is actually redundant for a pointer-valued FOO, which can be null only when has_FOO is false, i.e. has_FOO == !!FOO. Except for arrays, where we a null FOO can also be a present empty array. The redundant has_FOO are a nuisance to work with. Improve the generator to elide them. Uses of has_FOO need to be replaced as follows. Tests of has_FOO become the equivalent comparison of FOO with null. For brevity, this is commonly done by implicit conversion to bool. Assignments to has_FOO get dropped. Likewise for arguments to has_FOO parameters. Beware: code may violate the invariant has_FOO == !!FOO before the transformation, and get away with it. The above transformation can then break things. Two cases: * Absent: if code ignores FOO entirely when !has_FOO (except for freeing it if necessary), even non-null / uninitialized FOO works. Such code is known to exist. * Present: if code ignores FOO entirely when has_FOO, even null FOO works. Such code should not exist. In both cases, replacing tests of has_FOO by FOO reverts their sense. We have to fix the value of FOO then. To facilitate review of the necessary updates to handwritten code, add means to opt out of this change, and opt out for all QAPI schema modules where the change requires updates to handwritten code. The next few commits will remove these opt-outs in reviewable chunks, then drop the means to opt out. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20221104160712.3005652-5-armbru@redhat.com>
* docs/devel/qapi-code-gen: Extend example for next commit's changeMarkus Armbruster2022-12-131-1/+20
| | | | | | | | | | The next commit will change the code generated for some optional members. The example schema contains an optional member affected by the change. Add one that is not affected. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20221104160712.3005652-4-armbru@redhat.com>
* qapi: Tidy up whitespace in generated codeMarkus Armbruster2022-12-131-1/+0
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20221104160712.3005652-3-armbru@redhat.com>
* docs/devel/qapi-code-gen: Update example to match current codeMarkus Armbruster2022-12-131-1/+1
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20221104160712.3005652-2-armbru@redhat.com>
* docs/devel/qapi-code-gen: Belatedly document feature naming rulesMarkus Armbruster2022-05-161-4/+5
| | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20220510061645.3209195-3-armbru@redhat.com>
* docs: qapi: Remove outdated reference to simple unionsAndrea Bolognani2022-04-211-2/+2
| | | | | | | | | | | Commit 4e99f4b12c0e dropped simple unions and updated most documentation accordingly, but in one case we still claim that there are "two flavors of unions". Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20220420153408.243584-2-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* docs/qapi-code-gen: update to cover trace events code generationVladimir Sementsov-Ogievskiy2022-01-271-0/+23
| | | | | | | | | | | | Previous commits enabled trace events generation for most of QAPI generated code (except for tests/ and qga/). Let's update documentation to illustrate it. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Message-Id: <20220126161130.3240892-6-vsementsov@virtuozzo.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi/commands: refactor error handling codeVladimir Sementsov-Ogievskiy2022-01-271-1/+1
| | | | | | | | | | | | Move error_propagate() to if (err) and make "if (err)" block mandatory. This is to simplify further commit, which will bring trace events generation for QMP commands. Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Message-Id: <20220126161130.3240892-3-vsementsov@virtuozzo.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* docs/devel/qapi-code-gen: Belatedly document feature documentationMarkus Armbruster2021-11-101-8/+15
| | | | | | | | | | Commit 6a8c0b5102 "qapi: Add feature flags to struct types" neglected to document how to document feature flags. Make up for that. Cc: Kevin Wolf <kwolf@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20211026111023.76937-3-armbru@redhat.com> [Editing accident fixed]
* docs/devel/qapi-code-gen: Drop a duplicate paragraphMarkus Armbruster2021-11-101-6/+0
| | | | | | | | | | Commit 55ec69f8b1 "docs/devel/qapi-code-gen.txt: Update to new rST backend conventions" accidentally duplicated a paragraph. Drop it. Cc: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20211026111023.76937-2-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* qapi: New special feature flag "unstable"Markus Armbruster2021-10-291-3/+6
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | By convention, names starting with "x-" are experimental. The parts of external interfaces so named may be withdrawn or changed incompatibly in future releases. The naming convention makes unstable interfaces easy to recognize. Promoting something from experimental to stable involves a name change. Client code needs to be updated. Occasionally bothersome. Worse, the convention is not universally observed: * QOM type "input-barrier" has properties "x-origin", "y-origin". Looks accidental, but it's ABI since 4.2. * QOM types "memory-backend-file", "memory-backend-memfd", "memory-backend-ram", and "memory-backend-epc" have a property "x-use-canonical-path-for-ramblock-id" that is documented to be stable despite its name. We could document these exceptions, but documentation helps only humans. We want to recognize "unstable" in code, like "deprecated". So support recognizing it the same way: introduce new special feature flag "unstable". It will be treated specially by the QAPI generator, like the existing feature flag "deprecated", and unlike regular feature flags. This commit updates documentation and prepares tests. The next commit updates the QAPI schema. The remaining patches update the QAPI generator and wire up -compat policy checking. Management applications can then use query-qmp-schema and -compat to manage or guard against use of unstable interfaces the same way as for deprecated interfaces. docs/devel/qapi-code-gen.txt no longer mandates the naming convention. Using it anyway might help writers of programs that aren't full-fledged management applications. Not using it can save us bothersome renames. We'll see how that shakes out. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Message-Id: <20211028102520.747396-2-armbru@redhat.com>
* qapi: Add feature flags to enum membersMarkus Armbruster2021-10-271-5/+11
| | | | | | | | | | | | | This is quite similar to commit 84ab008687 "qapi: Add feature flags to struct members", only for enums instead of structs. Special feature flag 'deprecated' is silently ignored there. This is okay only because it will be implemented shortly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20211025042405.3762351-3-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* qapi: Enable enum member introspection to show more than nameMarkus Armbruster2021-10-271-4/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The next commit will add feature flags to enum members. There's a problem, though: query-qmp-schema shows an enum type's members as an array of member names (SchemaInfoEnum member @values). If it showed an array of objects with a name member, we could simply add more members to these objects. Since it's just strings, we can't. I can see three ways to correct this design mistake: 1. Do it the way we should have done it, plus compatibility goo. We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum. Since changing @values would be a compatibility break, add a new member @members instead. @values is now redundant. In my testing, output of qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB). We can deprecate @values now and drop it later. This will break outmoded clients. Well-behaved clients such as libvirt are expected to break cleanly. 2. Like 1, but omit "boring" elements of @member, and empty @member. @values does not become redundant. @members augments it. Somewhat cumbersome, but output of query-qmp-schema grows only as we make enum members non-boring. There is nothing to deprecate here. 3. Versioned query-qmp-schema. query-qmp-schema provides either @values or @members. The QMP client can select which version it wants. There is no redundant output. We can deprecate old versions and eventually drop them. This will break outmoded clients. Breaking cleanly is easier than for 1. While 1 and 2 operate within the common rules for compatible evolution apply (section "Compatibility considerations" in docs/devel/qapi-code-gen.rst), 3 bypasses them. Attractive when operating within the rules is just too awkward. Not the case here. This commit implements 1. Libvirt developers prefer it. Deprecate @values in favour of @members. Since query-qmp-schema compatibility is pretty fundamental for management applications, an extended grace period is advised. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Peter Krempa <pkrempa@redhat.com> Acked-by: Peter Krempa <pkrempa@redhat.com> Message-Id: <20211025042405.3762351-2-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
* qapi: Drop simple unionsMarkus Armbruster2021-09-271-100/+23
| | | | | | | | | | | | | | | Simple unions predate flat unions. Having both complicates the QAPI schema language and the QAPI generator. We haven't been using simple unions in new code for a long time, because they are less flexible and somewhat awkward on the wire. The previous commits eliminated simple union from the tree. Now drop them from the QAPI schema language entirely, and update mentions of "flat union" to just "union". Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20210917143134.412106-22-armbru@redhat.com>
* qapi: Tidy up unusual line breaksMarkus Armbruster2021-09-251-6/+6
| | | | | | | | Break lines between members instead of within members. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20210917143134.412106-2-armbru@redhat.com>