riscv/qemu - qemu - Gitea: Git with a cup of tea

Commit Graph

Author	SHA1	Message	Date
Markus Armbruster	e76ff1ee96	qapi: Refill doc comments to conform to conventions Sweep the entire documentation again. Last done in commit `01bed0ff14` (qapi: Refill doc comments to conform to conventions). To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Message-ID: <20251103082354.3273027-3-armbru@redhat.com>	9 months ago
John Snow	68c0156de2	qapi: add cross-references to misc modules These modules don't have specific maintainers, so they're lumped in together here as miscellaneous. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250711054005.60969-19-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	1 year ago
John Snow	f7296f8de5	qapi: rephrase return docs to avoid type name "Returns: <description>" is rendered like "Return: <Type> – <description>". Mentioning the type in the description again is commonly redundant. Rephrase such descriptions not to. Well, I tried. Maybe not very hard. Sorry! Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250711051045.51110-5-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> [Commit message amended to explain why] Signed-off-by: Markus Armbruster <armbru@redhat.com>	1 year ago
John Snow	6c10778826	docs/sphinx: remove special parsing for freeform sections 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>	1 year ago
Markus Armbruster	6263225492	qapi: Correct spelling of QEMU in doc comments Improve awkward phrasing in migrate-incoming While there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250527073916.1243024-7-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	1 year ago
Markus Armbruster	c1a6aa1d44	qapi: Avoid breaking lines within (since X.Y) Easier on the eyes and for grep. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20250527073916.1243024-5-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	1 year ago
Markus Armbruster	8fdec50a9d	qapi/introspect: Supply missing member documentation Since we neglect to document the members of JSONType, their description in the QEMU QMP Reference manual is "Not documented". Fix that. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-ID: <20240911112545.2248881-5-armbru@redhat.com>	2 years ago
Markus Armbruster	01bed0ff14	qapi: Refill doc comments to conform to conventions Sweep the entire documentation again. Last done in commit `209e64d9ed` (qapi: Refill doc comments to conform to current conventions). To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240729065220.860163-1-armbru@redhat.com> [Straightforward conflict with commit `442110bc6f` resolved]	2 years ago
John Snow	d461c27973	qapi: convert "Note" sections to plain rST 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>	2 years ago
Markus Armbruster	709c5a650e	qapi: Drop redundant documentation of inherited members Documentation generated for SchemaInfo looks like The members of "SchemaInfoBuiltin" when "meta-type" is ""builtin"" The members of "SchemaInfoEnum" when "meta-type" is ""enum"" The members of "SchemaInfoArray" when "meta-type" is ""array"" The members of "SchemaInfoObject" when "meta-type" is ""object"" The members of "SchemaInfoAlternate" when "meta-type" is ""alternate"" The members of "SchemaInfoCommand" when "meta-type" is ""command"" The members of "SchemaInfoEvent" when "meta-type" is ""event"" Additional members depend on the value of "meta-type". The last line became redundant when commit `88f63467c5` (qapi2texi: Generate reference to base type members) added the lines preceding it. Drop it. BlockdevOptions has the same issue. Drop Remaining options are determined by the block driver. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240129115008.674248-2-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	3 years ago
Markus Armbruster	7cbdabb5d6	docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref docs/interop/bitmaps.rst uses references like `qemu-qmp-ref <qemu-qmp-ref.html>`_ `query-block <qemu-qmp-ref.html#index-query_002dblock>`_ to refer to and into docs/interop/qemu-qmp-ref.rst. Clean up the former: use :doc:`qemu-qmp-ref`. I don't know how to clean up the latter. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240120095327.666239-5-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	3 years ago
Markus Armbruster	b0b1313eb2	qapi: Fix dangling references to docs/devel/qapi-code-gen.txt Conversion of docs/devel/qapi-code-gen.txt to ReST left several dangling references behind. Fix them to point to docs/devel/qapi-code-gen.rst. Fixes: `f7aa076dbd` (docs: convert qapi-code-gen.txt to ReST) Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240120095327.666239-4-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	3 years ago
Markus Armbruster	a937b6aa73	qapi: Reformat doc comments to conform to current conventions Change # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. to # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale. Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-18-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Acked-by: Lukas Straub <lukasstraub2@web.de> [Straightforward conflicts in qapi/audio.json qapi/misc-target.json qapi/run-state.json resolved]	3 years ago
Markus Armbruster	b6c18755e4	qapi: Add feature flags to enum members 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>	5 years ago
Markus Armbruster	75ecee7262	qapi: Enable enum member introspection to show more than name 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>	5 years ago
Markus Armbruster	624fa80c8c	monitor: Drop query-qmp-schema 'gen': false hack QMP commands return their response as a generated QAPI type, which the monitor core converts to JSON via QObject. query-qmp-schema's response is the generated introspection data. This is a QLitObject since commit `7d0f982bfb` "qapi: generate a literal qobject for introspection", v2.12). Before, it was a string. Instead of converting QLitObject / string -> QObject -> QAPI type SchemaInfoList -> QObject -> JSON, we take a shortcut: the command is 'gen': false, so it can return the QObject instead of the QAPI type. Slightly simpler and more efficient. The next commit will filter the response for output policy, and this is easier in the SchemaInfoList representation. Drop the shortcut. This replaces the manual command registration by a generated one. The manual registration makes the command available before the machine is built by passing flag QCO_ALLOW_PRECONFIG. To keep it available there, we need need to add 'allow-preconfig': true to its definition in the schema. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20210318155519.1224118-7-armbru@redhat.com>	5 years ago
Andrea Bolognani	f7160f3218	schemas: Add vim modeline The various schemas included in QEMU use a JSON-based format which is, however, strictly speaking not valid JSON. As a consequence, when vim tries to apply syntax highlight rules for JSON (as guessed from the file name), the result is an unreadable mess which mostly consist of red markers pointing out supposed errors in, well, pretty much everything. Using Python syntax highlighting produces much better results, and in fact these files already start with specially-formatted comments that instruct Emacs to process them as if they were Python files. This commit adds the equivalent special comments for vim. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20200729185024.121766-1-abologna@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	6 years ago
Markus Armbruster	84ab008687	qapi: Add feature flags to struct members Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20200317115459.31821-21-armbru@redhat.com>	6 years ago
Markus Armbruster	013b4efc9b	qapi: Add feature flags to remaining definitions In v4.1.0, we added feature flags just to struct types (commit 6a8c0b5102^..f3ed93d545), to satisfy an immediate need (commit `c9d4070991` "file-posix: Add dynamic-auto-read-only QAPI feature"). In v4.2.0, we added them to commands (commit `23394b4c39` "qapi: Add feature flags to commands") to satisfy another immediate need (commit d76744e65e "qapi: Allow introspecting fix for savevm's cooperation with blockdev"). Add them to the remaining definitions: enumeration types, union types, alternate types, and events. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20200317115459.31821-13-armbru@redhat.com>	6 years ago
Peter Maydell	26ec4e53f2	qapi: Fix indent level on doc comments in json files The current doc generation doesn't care much about indentation levels, but we would like to switch to an rST format, and rST does care about indentation. Make the doc comments more strongly consistent about indentation for multiline constructs like: @arg: description line 1 description line 2 Returns: line one line 2 so that there is always exactly one space after the colon, and subsequent lines align with the first. This commit is a purely whitespace change, and it does not alter the generated .texi files (because the texi generation code strips away all the extra whitespace). This does mean that we end up with some over-length lines. Note that when the documentation for an argument fits on a single line like this: @arg: one line only then stray extra spaces after the ':' don't affect the rST output, so I have not attempted to methodically fix them, though the preference is a single space here too. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>	7 years ago
Peter Krempa	23394b4c39	qapi: Add feature flags to commands Similarly to features for struct types introduce the feature flags also for commands. This will allow notifying management layers of fixes and compatible changes in the behaviour of a command which may not be detectable any other way. The changes were heavily inspired by commit `6a8c0b5102`. Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20191018081454.21369-3-armbru@redhat.com>	7 years ago
Kevin Wolf	6a8c0b5102	qapi: Add feature flags to struct types Sometimes, the behaviour of QEMU changes without a change in the QMP syntax (usually by allowing values or operations that previously resulted in an error). QMP clients may still need to know whether they can rely on the changed behavior. Let's add feature flags to the QAPI schema language, so that we can make such changes visible with schema introspection. An example for a schema definition using feature flags looks like this: { 'struct': 'TestType', 'data': { 'number': 'int' }, 'features': [ 'allow-negative-numbers' ] } Introspection information then looks like this: { "name": "TestType", "meta-type": "object", "members": [ { "name": "number", "type": "int" } ], "features": [ "allow-negative-numbers" ] } This patch implements feature flags only for struct types. We'll implement them more widely as needed. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20190606153803.5278-2-armbru@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	7 years ago
Markus Armbruster	37aded92c2	json: Update references to RFC 7159 to RFC 8259 RFC 8259 (December 2017) obsoletes RFC 7159 (March 2014). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180823164025.12553-59-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	8 years ago
Markus Armbruster	25b1ef31db	qapi: Make 'allow-oob' optional in SchemaInfoCommand Making 'allow-oob' optional in SchemaInfoCommand permits omitting it in the common case. Shrinks query-qmp-schema's output from 122.1KiB to 118.6KiB for me. Note that out-of-band execution is still experimental (you have to configure the monitor with x-oob=on to use it). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180718090557.17248-1-armbru@redhat.com> Reviewed-by: Peter Xu <peterx@redhat.com>	8 years ago
Markus Armbruster	1f214ee1b8	qapi: Do not expose "allow-preconfig" in query-qmp-schema According to commit `047f7038f5`, option --preconfig [...] allows pausing QEMU in the new RUN_STATE_PRECONFIG state, allowing the configuration of QEMU from QMP before the machine jumps into board initialization code of machine_run_board_init() The intent is to allow management to query machine state and additionally configure it using previous query results within one QEMU instance (i.e. eliminate the need to start QEMU twice, 1st to query board specific parameters and 2nd for actual VM start using query results for additional parameters). The implementation is a bit of a hack: it splices in an additional main loop before machine creation, in special runstate preconfig. New command exit-preconfig exits that main loop. QEMU continues initializing, creates the machine, and runs the good old main loop. The replacement of the main loop is transparent to monitors. Sadly, some commands expect initialization to be complete. Running them in --preconfig's main loop violates their preconditions. Since we don't really know which commands are safe, we use a whitelist. This drags the concept of run state into the QMP core. The whitelist is done as a command flag in the QAPI schema (commit `d6fe3d02e9`). Drags the concept of run state further into the QAPI language. The command flag is exposed in query-qmp-schema (also commit `d6fe3d02e9`). This makes it ABI. I consider the whole thing an offensively ugly hack, but sometimes an ugly hack is the best we can do to solve a problem people have. The need described by the commit message quote above is genuine. The proper solution would be a main loop that permits complete configuration via QMP. This is out of reach, thus the hack. However, even though the need is genuine, it isn't urgent: libvirt is not going to use this anytime soon. Baking a hack into ABI before it has any users is a bad idea. This commit reverts the parts of commit `d6fe3d02e9` that affect ABI via query-qmp-schema. The commit did the following: (1) Add command flag 'allow-preconfig' to the QAPI schema language (2) Pass it to code generators (3) Have the commands.py code generator pass it to the command registry (so commit `047f7038f5` can use it as whitelist) (4) Add 'allow-preconfig' to SchemaInfoCommand (neglecting to update qapi-code-gen.txt section "Client JSON Protocol introspection") (5) Set 'allow-preconfig': true for commands qmp_capabilities, query-commands, query-command-line-options, query-status Revert exactly (4), plus a bit of documentation added to qemu-tech.info in commit `047f7038f5`. Shrinks query-qmp-schema's output from 126.5KiB to 121.8KiB for me. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180705091402.26244-2-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Acked-by: Eduardo Habkost <ehabkost@redhat.com> Acked-by: Igor Mammedov <imammedo@redhat.com> [Straightforward conflict with commit `d626b6c1ae` resolved]	8 years ago
Igor Mammedov	d6fe3d02e9	qapi: introduce new cmd option "allow-preconfig" New option will be used to allow commands, which are prepared/need to run, during preconfig state. Other commands that should be able to run in preconfig state, should be amended to not expect machine in initialized state or deal with it. For compatibility reasons, commands that don't use new flag 'allow-preconfig' explicitly are not permitted to run in preconfig state but allowed in all other states like they used to be. Within this patch allow following commands in preconfig state: qmp_capabilities query-qmp-schema query-commands query-command-line-options query-status exit-preconfig to allow qmp connection, basic introspection and moving to the next state. PS: set-numa-node and query-hotpluggable-cpus will be enabled later in a separate patches. Signed-off-by: Igor Mammedov <imammedo@redhat.com> Message-Id: <1526057503-39287-1-git-send-email-imammedo@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [ehabkost: Changed "since 2.13" to "since 3.0"] Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>	8 years ago
Peter Xu	876c67512e	qapi: introduce new cmd option "allow-oob" Here "oob" stands for "Out-Of-Band". When "allow-oob" is set, it means the command allows out-of-band execution. The "oob" idea is proposed by Markus Armbruster in following thread: https://lists.gnu.org/archive/html/qemu-devel/2017-09/msg02057.html This new "allow-oob" boolean will be exposed by "query-qmp-schema" as well for command entries, so that QMP clients can know which commands can be used in out-of-band calls. For example the command "migrate" originally looks like: {"name": "migrate", "ret-type": "17", "meta-type": "command", "arg-type": "86"} And it'll be changed into: {"name": "migrate", "ret-type": "17", "allow-oob": false, "meta-type": "command", "arg-type": "86"} This patch only provides the QMP interface level changes. It does not contain the real out-of-band execution implementation yet. Suggested-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Fam Zheng <famz@redhat.com> Signed-off-by: Peter Xu <peterx@redhat.com> Message-Id: <20180309090006.10018-18-peterx@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [eblake: rebase on introspection done by qlit] Signed-off-by: Eric Blake <eblake@redhat.com>	9 years ago
Markus Armbruster	a885cd3915	qapi-schema: Introspection doc is in the wrong section, fix Bug: introspection documentation is in section "Tracing commands". Cause: sub-schema qapi/introspect.json lacks a section header, and therefore goes into whatever section precedes its include. Fix: add a section header. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <1503602048-12268-3-git-send-email-armbru@redhat.com>	9 years ago
Philippe Mathieu-Daudé	b3125e73d4	docs: fix broken paths to docs/devel/qapi-code-gen.txt With the move of some docs to docs/interop on `ac06724a71`, a couple of references were not updated. Signed-off-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>	9 years ago
Markus Armbruster	1d8bda128d	qapi: The #optional tag is redundant, drop We traditionally mark optional members #optional in the doc comment. Before commit `3313b61`, this was entirely manual. Commit `3313b61` added some automation because its qapi2texi.py relied on #optional to determine whether a member is optional. This is no longer the case since the previous commit: the only thing qapi2texi.py still does with #optional is stripping it out. We still reject bogus qapi-schema.json and six places for qga/qapi-schema.json. Thus, you can't actually rely on #optional to see whether something is optional. Yet we still make people add it manually. That's just busy-work. Drop the code to check, fix up and strip out #optional, along with all instances of #optional. To keep it out, add code to reject it, to be dropped again once the dust settles. No change to generated documentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com>	10 years ago
Marc-André Lureau	5807ff88b1	qapi: Reorder doc comments for future doc generator The doc generator we're going to add expects a fairly rigid doc comment structure. Reorder / rephrase some doc comments to please it. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170113144135.5150-8-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message rewritten] Signed-off-by: Markus Armbruster <armbru@redhat.com>	10 years ago
Marc-André Lureau	e22da431a7	qapi: Format TODO comments more consistently Consistently put a colon after TODO. This will make the TODOs stand out in the documentation we're going to generate. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170113144135.5150-4-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message rewritten] Signed-off-by: Markus Armbruster <armbru@redhat.com>	10 years ago
Marc-André Lureau	5072f7b38b	qapi: add missing colon-ending for section name The documentation parser we are going to add expects a section name to end with ':', otherwise the comment is treated as free-form text body. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20161117155504.21843-9-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	10 years ago
Eric Blake	3666a97f78	qapi: Use anonymous bases in QMP flat unions Now that the generator supports it, we might as well use an anonymous base rather than breaking out a single-use Base structure, for all three of our current QMP flat unions. Oddly enough, this change does not affect the resulting introspection output (because we already inline the members of a base type into an object, and had no independent use of the base type reachable from a command). The case_whitelist now has to list the name of an implicit type; which is not too bad (consider it a feature if it makes it harder for developers to make the whitelist grow :) Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-16-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago
Eric Blake	39a65e2c24	qapi: Document introspection stability considerations We are not ready (and might never be ready) to declare introspection stable between releases. Clients written to control multiple versions of qemu, and desiring to know whether a particular member is supported for a given command, must be prepared to locate that member in spite of qapi changes that may affect the member's location or type within the overall object, even though such changes did not break QMP wire back-compatibility. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1447264202-19554-1-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago
Eric Blake	f545504420	qapi-introspect: Document lack of sorting qapi-code-gen.txt already claims that types, commands, and events share a common namespace; set this in stone by further documenting that our introspection output will never have collisions with the same name tied to more than one meta-type. Our largest QMP enum currently has 125 values, our largest object type has 27 members, and the mean for each is less than 10. These sizes are small enough that the per-element overhead of O(log n) binary searching probably outweighs the speed possible with direct O(n) linear searching (a better algorithm with more overhead will only beat a leaner naive algorithm only as you scale to larger input sizes). Arguably, the overall SchemaInfo array could be sorted by name; there, we currently have 531 entities, large enough for a binary search to be faster than linear. However, remember that we have mutually-recursive types, which means there is no topological ordering that will allow clients to learn all information about that type in a single linear pass; thus clients will want to do random access over the data, and they will probably read the introspection output into a hashtable for O(1) lookup rather than O(log n) binary searching, at which point, pre-sorting our introspection output doesn't help the client. It doesn't help that sorting can be subjective if you introduce locales into the mix (I'm not experienced enough with Python to know for sure, but at least it looks like it defaults to sorting in the C locale even when run under a different locale). And while our current introspection output is deterministic (because we visit entities in a sorted order), we may want to change that order in the future (such as using OrderedDict to stick to .json declaration order). For these reasons, we simply document that clients should not rely on any particular order of items in introspection output. And since it is now a documented part of the contract, we have the freedom to later rearrange output if needed, without worrying about breaking well-written clients. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1446791754-23823-13-git-send-email-eblake@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago
Markus Armbruster	1a9a507b2e	qapi-introspect: Hide type names To eliminate the temptation for clients to look up types by name (which are not ABI), replace all type names by meaningless strings. Reduces output of query-schema by 13 out of 85KiB. As a debugging aid, provide option -u to suppress the hiding. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1442401589-24189-27-git-send-email-armbru@redhat.com>	11 years ago
Markus Armbruster	39a1815816	qapi: New QMP command query-qmp-schema for QMP introspection qapi/introspect.json defines the introspection schema. It's designed for QMP introspection, but should do for similar uses, such as QGA. The introspection schema does not reflect all the rules and restrictions that apply to QAPI schemata. A valid QAPI schema has an introspection value conforming to the introspection schema, but the converse is not true. Introspection lowers away a number of schema details, and makes implicit things explicit: * The built-in types are declared with their JSON type. All integer types are mapped to 'int', because how many bits we use internally is an implementation detail. It could be pressed into external interface service as very approximate range information, but that's a bad idea. If we need range information, we better do it properly. * Implicit type definitions are made explicit, and given auto-generated names: - Array types, named by appending "List" to the name of their element type, like in generated C. - The enumeration types implicitly defined by simple union types, named by appending "Kind" to the name of their simple union type, like in generated C. - Types that don't occur in generated C. Their names start with ':' so they don't clash with the user's names. * All type references are by name. * The struct and union types are generalized into an object type. * Base types are flattened. * Commands take a single argument and return a single result. Dictionary argument or list result is an implicit type definition. The empty object type is used when a command takes no arguments or produces no results. The argument is always of object type, but the introspection schema doesn't reflect that. The 'gen': false directive is omitted as implementation detail. The 'success-response' directive is omitted as well for now, even though it's not an implementation detail, because it's not used by QMP. * Events carry a single data value. Implicit type definition and empty object type use, just like for commands. The value is of object type, but the introspection schema doesn't reflect that. * Types not used by commands or events are omitted. Indirect use counts as use. * Optional members have a default, which can only be null right now Instead of a mandatory "optional" flag, we have an optional default. No default means mandatory, default null means optional without default value. Non-null is available for optional with default (possible future extension). * Clients should not look up types by name, because type names are not ABI. Look up the command or event you're interested in, then follow the references. TODO Should we hide the type names to eliminate the temptation? New generator scripts/qapi-introspect.py computes an introspection value for its input, and generates a C variable holding it. It can generate awfully long lines. Marked TODO. A new test-qmp-input-visitor test case feeds its result for both tests/qapi-schema/qapi-schema-test.json and qapi-schema.json to a QmpInputVisitor to verify it actually conforms to the schema. New QMP command query-qmp-schema takes its return value from that variable. Its reply is some 85KiBytes for me right now. If this turns out to be too much, we have a couple of options: * We can use shorter names in the JSON. Not the QMP style. * Optionally return the sub-schema for commands and events given as arguments. Right now qmp_query_schema() sends the string literal computed by qmp-introspect.py. To compute sub-schema at run time, we'd have to duplicate parts of qapi-introspect.py in C. Unattractive. * Let clients cache the output of query-qmp-schema. It changes only on QEMU upgrades, i.e. rarely. Provide a command query-qmp-schema-hash. Clients can have a cache indexed by hash, and re-query the schema only when they don't have it cached. Even simpler: put the hash in the QMP greeting. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	11 years ago

38 Commits (master)