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

Commit Graph

Author	SHA1	Message	Date
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
Philippe Mathieu-Daudé	7ffc4894a6	trace: Remove deprecated 'vcpu' field from QMP trace events 'vcpu' fields are deprecated since commit `5485e52a33` ("qapi: make the vcpu parameters deprecated for 8.1"), time to remove them. Signed-off-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20240530071548.20074-3-philmd@linaro.org>	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
Markus Armbruster	9e272073e1	qapi: Reformat recent doc comments to conform to current conventions Since commit `a937b6aa73` (qapi: Reformat doc comments to conform to current conventions), a number of comments not conforming to the current formatting conventions were added. No problem, just sweep the entire documentation once more. 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: <20230720071610.1096458-7-armbru@redhat.com>	3 years ago
Markus Armbruster	e27a9d628d	qapi/trace: Tidy up trace-event-get-state, -set-state documentation trace-event-set-state's explanation of how events are selected is under "Features". Doesn't belong there. Simply delete it, as it feels redundant with documentation of member @name. trace-event-get-state's explanation is under "Returns". Tolerable, but similarly redundant. Delete it, too. Cc: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20230720071610.1096458-5-armbru@redhat.com>	3 years ago
Alex Bennée	5485e52a33	qapi: make the vcpu parameters deprecated for 8.1 I don't think I can remove the parameters directly but certainly mark them as deprecated. Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-id: 20230526165401.574474-7-alex.bennee@linaro.org Message-Id: <20230524133952.3971948-6-alex.bennee@linaro.org> Signed-off-by: Stefan Hajnoczi <stefanha@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	c110102898	qapi: Fix bullet list markup in documentation Peter Maydell's commit `100cc4fe0f` 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: `100cc4fe0f` (qapi: Add blank lines before bulleted lists) Fixes: `467ef823d8` (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]	3 years ago
Victor Toso	6352c81b24	qapi: fix example of trace-event-get-state command The example output is missing the mandatory member @vcpu. Fix it. Signed-off-by: Victor Toso <victortoso@redhat.com> Message-Id: <20220331190633.121077-8-victortoso@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Victor Toso	7e7237cd2b	schemas: add missing vim modeline Similar to `f7160f3218` "schemas: Add vim modeline" Signed-off-by: Victor Toso <victortoso@redhat.com> Message-Id: <20211220145624.52801-1-victortoso@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	4 years ago
Guoyi Tu	3e038d7d7a	qapi: Set boolean value correctly in examples Signed-off-by: Guoyi Tu <tugy@chinatelecom.cn> Message-Id: <a21a2b61-2653-a2c9-4478-715e5fb19120@chinatelecom.cn> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	5 years ago
Peter Maydell	100cc4fe0f	qapi: Add blank lines before bulleted lists We would like to switch the doc comments to rST format. rST insists on a blank line before and after a bulleted list, but our Texinfo doc generator did not. Add some extra blank lines in the doc comments so they're acceptable rST input. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20200213175647.17628-17-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <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>	6 years ago
Markus Armbruster	f5cf31c575	qapi-schema: Improve section headings The generated QEMU QMP reference is now structured as follows: 1.1 Introduction 1.2 Stability Considerations 1.3 Common data types 1.4 Socket data types 1.5 VM run state 1.6 Cryptography 1.7 Block devices 1.7.1 Block core (VM unrelated) 1.7.2 QAPI block definitions (vm unrelated) 1.8 Character devices 1.9 Net devices 1.10 Rocker switch device 1.11 TPM (trusted platform module) devices 1.12 Remote desktop 1.12.1 Spice 1.12.2 VNC 1.13 Input 1.14 Migration 1.15 Transactions 1.16 Tracing 1.17 QMP introspection 1.18 Miscellanea Section "1.18 Miscellanea" is still too big: it documents 134 symbols. Section "1.7.1 Block core (VM unrelated)" is also rather big: 128 symbols. All the others are of reasonable size. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503602048-12268-17-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>	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>	9 years ago
Marc-André Lureau	8a9b273e57	qmp-commands: move 'trace-event-set-state' doc to schema Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	10 years ago
Marc-André Lureau	a93b9ba76f	qmp-commands: move 'trace-event-get-state' doc to schema Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	10 years ago
Marc-André Lureau	d3a48372a4	qapi: add some sections in docs Add some more section titles to organize the documentation we're going to generate. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20170113144135.5150-10-marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	9 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
Lluís Vilanova	77e2b17272	trace: Add QAPI/QMP interfaces to query and control per-vCPU tracing state Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>	10 years ago
Eric Blake	895a2a80e0	qapi: Use 'struct' instead of 'type' in schema Referring to "type" as both a meta-type (built-in, enum, union, alternate, or struct) and a specific type (the name that the schema uses for declaring structs) is confusing. Do the bulk of the conversion to "struct" in qapi schema, with a fairly mechanical: for f in `find -name '*.json'; do sed -i "s/'type'/'struct'/"; done followed by manually filtering out the places where we have a 'type' embedded in 'data'. Then tweak a couple of tests whose output changes slightly due to longer lines. I also verified that the generated files for QMP and QGA (such as qmp-commands.h) are the same before and after, as assurance that I didn't leave in any accidental member name changes. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago
Lluís Vilanova	1dde0f48d5	trace: [qmp] Add commands to query and control event tracing state Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu> Message-id: 20140825111957.31112.31733.stgit@fimbulvetr.bsc.es Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>	12 years ago

22 Commits (40ab4ed107757e1c5bdccc906e8a44cb4e2cb7a4)