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

Commit Graph

Author	SHA1	Message	Date
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	14b48aaab9	qapi: convert "Example" sections without titles Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples. See commit-3: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax. See commit+3: "qapi: remove "Example" doc section" for a detailed explanation of why. Note: an empty "TODO" line was added to announce-self to keep the example from floating up into the body; this will be addressed more rigorously in the new qapidoc generator. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Markup fixed in one place] Signed-off-by: Markus Armbruster <armbru@redhat.com>	2 years ago
John Snow	543ff13a20	qapi: add markup to note blocks Generally, surround command-line options with ``literal`` markup to help it stand out from prose in rendered HTML, and add cross-references to replace "see also" messages. References to types, values, and other QAPI definitions are not yet adjusted here; they will be converted en masse in a subsequent patch after the new QAPI doc generator is merged. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-13-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	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
John Snow	9f2b848857	qapi: fix non-compliant JSON examples The new QMP documentation generator wants to parse all examples as "QMP". We have an existing QMP lexer in docs/sphinx/qmp_lexer.py (Seen in-use here: https://qemu-project.gitlab.io/qemu/interop/bitmaps.html) that allows the use of "->", "<-" and "..." tokens to denote QMP protocol flow with elisions, but otherwise defers to the JSON lexer. To utilize this lexer for the existing QAPI documentation, we need them to conform to a standard so that they lex and render correctly. Once the QMP lexer is active for examples, errant QMP/JSON will produce warning messages and fail the build. Fix any invalid JSON found in QAPI documentation (identified by attempting to lex all examples as QMP; see subsequent commits). Additionally, elisions must be standardized for the QMP lexer; they must be represented as the value "...", so three examples have been adjusted to support that format here. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240626222128.406106-9-jsnow@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	2 years ago
Markus Armbruster	c15fbc66e2	qapi: Drop stray Arguments: line from qmp_capabilities docs Reported-by: John Snow <jsnow@redhat.com> Fixes: `119ebac1fe` (qapi-schema: use generated marshaller for 'qmp_capabilities') Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240322140910.328840-2-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>	2 years ago
Markus Armbruster	d23055b8db	qapi: Require descriptions and tagged sections to be indented 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]	2 years ago
Peter Maydell	d56572584d	docs/interop: Convert qmp-spec.txt to rST 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]	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	f2de3b926c	qapi: Fix unintended definition lists in documentation rST parses something like first line second line as a definition list item, where "first line" is the term being defined by "second line". This bites us in a couple of places. Here's one: # @bps_max: total throughput limit during bursts, # in bytes (Since 1.7) scripts/qapi/parser.py parses this into an "argument section" with name "bps_max" and text total throughput limit during bursts, in bytes (Since 1.7) docs/sphinx/qapidoc.py duly passes the text to the rST parser, which parses it as another definition list. Comes out as nested definitions: term "bps_max: int (optional)" defined as term "total throughput limit during bursts," defined as "in bytes (Since 1.7)". rST truly is the Perl of ASCII-based markups. Fix by deleting the extra indentation. Fixes: `26ec4e53f2` (qapi: Fix indent level on doc comments in json files) Fixes: `c0ac533b6f` (qapi: Stop using whitespace for alignment in comments) Fixes: `81ad2964e9` (net/vmnet: add vmnet backends to qapi/net) Reported-by: Peter Maydell <peter.maydell@linaro.org> 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> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20230425064223.820979-11-armbru@redhat.com>	3 years ago
Andrea Bolognani	c0ac533b6f	qapi: Stop using whitespace for alignment in comments Perfectly aligned things look pretty, but keeping them that way as the schema evolves requires churn, and in some cases newly-added lines are not aligned properly. Overall, trying to align things is just not worth the trouble. Signed-off-by: Andrea Bolognani <abologna@redhat.com> Message-Id: <20220503073737.84223-8-abologna@redhat.com> Message-Id: <20220503073737.84223-9-abologna@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Two patches squashed together] Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Andrea Bolognani	15cc783cfb	qapi: Drop unnecessary empty lines outside of comments Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20220503073737.84223-6-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Andrea Bolognani	c6487a8887	qapi: Drop unnecessary empty lines in comments Signed-off-by: Andrea Bolognani <abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20220503073737.84223-5-abologna@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Daniel P. Berrangé	8becb36063	monitor: remove 'query-events' QMP command The code comment suggests removing QAPIEvent_(str\|lookup) symbols too, however, these are both auto-generated as standard for any enum in QAPI. As such it they'll exist whether we use them or not. Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Thomas Huth <thuth@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>	5 years ago
Paolo Bonzini	ebe3444468	monitor: allow quitting while in preconfig state Reviewed-by: Igor Mammedov <imammedo@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	6 years ago
Markus Armbruster	9bc6e893b7	qapi: Normalize version references x.y.0 to just x.y We use x.y most of the time, and x.y.0 sometimes. Normalize for consistency. Reported-by: Eduardo Habkost <ehabkost@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20201118064158.3359056-1-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	5 years ago
Peter Maydell	b2f1c13c31	qapi: Fix indentation, again In commit `26ec4e53f2` and similar commits we fixed the indentation for doc comments in our qapi json files to follow a new stricter standard for indentation, which permits only: @arg: description line 1 description line 2 or: @arg: line 1 line 2 Unfortunately since we didn't manage to get the script changes that enforced the new style in, a variety of commits (eg `df4097aeaf`, `2e44570321`) introduced new doc text which doesn't follow the new stricter rules for indentation on multi-line doc comments. Bring those into line with the new rules. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200810195019.25427-3-peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com>	6 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	df4097aeaf	qapi: Mark deprecated QMP parts with feature 'deprecated' Add feature 'deprecated' to the deprecated QMP commands, so their deprecation becomes visible in output of query-qmp-schema. Looks like this: {"name": "query-cpus", "ret-type": "[164]", "meta-type": "command", "arg-type": "0", ---> "features": ["deprecated"]} Management applications could conceivably use this for static checking. The deprecated commands are change, cpu-add, migrate-set-cache-size, migrate_set_downtime, migrate_set_speed, query-cpus, query-events, query-migrate-cache-size. The deprecated command arguments are block-commit arguments @base and @top, and block_set_io_throttle, blockdev-change-medium, blockdev-close-tray, blockdev-open-tray, eject argument @device. The deprecated command results are query-cpus-fast result @arch, query-block result @dirty-bitmaps, query-named-block-nodes result @encryption_key_missing and result @dirty-bitmaps's member @status. Same for query-block result @inserted, which mirrors query-named-block-nodes. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200317115459.31821-27-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>	6 years ago
Kevin Wolf	a2f411c467	monitor: Add allow_hmp parameter to monitor_init() Add a new parameter allow_hmp to monitor_init() so that the storage daemon can disable HMP. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20200224143008.13362-20-kwolf@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>	6 years ago
Kevin Wolf	f2098725aa	monitor: Create QAPIfied monitor_init() This adds a new QAPI-based monitor_init() function. The existing monitor_init_opts() is rewritten to simply put its QemuOpts parameter into a visitor and pass the resulting QAPI object to monitor_init(). This will cause some change in those error messages for the monitor options in the system emulator that are now generated by the visitor rather than explicitly checked in monitor_init_opts(). Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20200224143008.13362-17-kwolf@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Kevin Wolf <kwolf@redhat.com>	6 years ago
Kevin Wolf	fa4dcf577e	qapi: Split control.json off misc.json misc.json contains definitions that are related to the system emulator, so it can't be used for other tools like the storage daemon. This patch moves basic functionality that is shared between all tools (and mostly related to the monitor itself) into a new control.json, which could be used in tools as well. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200129102239.31435-3-kwolf@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>	6 years ago

22 Commits (5357ef823a1f53673eae3e0a9a0d626bc104f8a7)