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	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
Paolo Bonzini	1de759534d	qapi: document leftover members in qapi/stats.json Suggested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-ID: <20240325104504.1358734-1-pbonzini@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Update qapi/pragma.json] Signed-off-by: Markus Armbruster <armbru@redhat.com>	2 years ago
Markus Armbruster	89a2273b9d	qapi: Add missing union tag documentation Low-hanging fruit, and except for StatsFilter, the only members of these unions lacking documentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240205074709.3613229-16-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@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	94546de1a8	qapi: Format since information the conventional way: (since X.Y) 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-16-armbru@redhat.com>	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
zhenwei pi	f2b901098e	cryptodev: Support query-stats QMP command Now we can use "query-stats" QMP command to query statistics of crypto devices. (Originally this was designed to show statistics by '{"execute": "query-cryptodev"}'. Daniel Berrangé suggested that querying configuration info by "query-cryptodev", and querying runtime performance info by "query-stats". This makes sense!) Example: ~# virsh qemu-monitor-command vm '{"execute": "query-stats", \ "arguments": {"target": "cryptodev"} }' \| jq { "return": [ { "provider": "cryptodev", "stats": [ { "name": "asym-verify-bytes", "value": 7680 }, ... { "name": "asym-decrypt-ops", "value": 32 }, { "name": "asym-encrypt-ops", "value": 48 } ], "qom-path": "/objects/cryptodev0" # support asym only }, { "provider": "cryptodev", "stats": [ { "name": "asym-verify-bytes", "value": 0 }, ... { "name": "sym-decrypt-bytes", "value": 5376 }, ... ], "qom-path": "/objects/cryptodev1" # support asym/sym } ], "id": "libvirt-422" } Suggested-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: zhenwei pi <pizhenwei@bytedance.com> Message-Id: <20230301105847.253084-12-pizhenwei@bytedance.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>	4 years ago
Paolo Bonzini	1ca1a7ec36	monitor: add support for boolean statistics The next version of Linux will introduce boolean statistics, which can only have 0 or 1 values. Support them in the schema and in the HMP command. Suggested-by: Amneesh Singh <natto@weirdnatto.in> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	4 years ago
Paolo Bonzini	cf7405bc02	qmp: add filtering of statistics by name Allow retrieving only a subset of statistics. This can be useful for example in order to plot a subset of the statistics many times a second: KVM publishes ~40 statistics for each vCPU on x86; retrieving and serializing all of them would be useless. Another use will be in HMP in the following patch; implementing the filter in the backend is easy enough that it was deemed okay to make this a public interface. Example: { "execute": "query-stats", "arguments": { "target": "vcpu", "vcpus": [ "/machine/unattached/device[2]", "/machine/unattached/device[4]" ], "providers": [ { "provider": "kvm", "names": [ "l1d_flush", "exits" ] } } } { "return": { "vcpus": [ { "path": "/machine/unattached/device[2]" "providers": [ { "provider": "kvm", "stats": [ { "name": "l1d_flush", "value": 41213 }, { "name": "exits", "value": 74291 } ] } ] }, { "path": "/machine/unattached/device[4]" "providers": [ { "provider": "kvm", "stats": [ { "name": "l1d_flush", "value": 16132 }, { "name": "exits", "value": 57922 } ] } ] } ] } } Extracted from a patch by Mark Kanda. Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	4 years ago
Paolo Bonzini	068cc51d42	qmp: add filtering of statistics by provider Allow retrieving the statistics from a specific provider only. This can be used in the future by HMP commands such as "info sync-profile" or "info profile". The next patch also adds filter-by-provider capabilities to the HMP equivalent of query-stats, "info stats". Example: { "execute": "query-stats", "arguments": { "target": "vm", "providers": [ { "provider": "kvm" } ] } } The QAPI is a bit more verbose than just a list of StatsProvider, so that it can be subsequently extended with filtering of statistics by name. If a provider is specified more than once in the filter, each request will be included separately in the output. Extracted from a patch by Mark Kanda. Reviewed-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Dr. David Alan Gilbert <dgilbert@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	4 years ago
Paolo Bonzini	467ef823d8	qmp: add filtering of statistics by target vCPU Introduce a simple filtering of statistics, that allows to retrieve statistics for a subset of the guest vCPUs. This will be used for example by the HMP monitor, in order to retrieve the statistics for the currently selected CPU. Example: { "execute": "query-stats", "arguments": { "target": "vcpu", "vcpus": [ "/machine/unattached/device[2]", "/machine/unattached/device[4]" ] } } Extracted from a patch by Mark Kanda. Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	4 years ago
Mark Kanda	cc01a3f4ca	kvm: Support for querying fd-based stats Add support for querying fd-based KVM stats - as introduced by Linux kernel commit: cb082bfab59a ("KVM: stats: Add fd-based API to read binary stats data") This allows the user to analyze the behavior of the VM without access to debugfs. Signed-off-by: Mark Kanda <mark.kanda@oracle.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	5 years ago
Mark Kanda	b9f88dc071	qmp: Support for querying stats Gathering statistics is important for development, for monitoring and for performance measurement. There are tools such as kvm_stat that do this and they rely on the _user_ knowing the interesting data points rather than the tool (which can treat them as opaque). The commands introduced in this commit introduce QMP support for querying stats; the goal is to take the capabilities of these tools and making them available throughout the whole virtualization stack, so that one can observe, monitor and measure virtual machines without having shell access + root on the host that runs them. query-stats returns a list of all stats per target type (only VM and vCPU to start); future commits add extra options for specifying stat names, vCPU qom paths, and providers. All these are used by the HMP command "info stats". Because of the development usecases around statistics, a good HMP interface is important. query-stats-schemas returns a list of stats included in each target type, with an option for specifying the provider. The concepts in the schema are based on the KVM binary stats' own introspection data, just translated to QAPI. There are two reasons to have a separate schema that is not tied to the QAPI schema. The first is the contents of the schemas: the new introspection data provides different information than the QAPI data, namely unit of measurement, how the numbers are gathered and change (peak/instant/cumulative/histogram), and histogram bucket sizes. There's really no reason to have this kind of metadata in the QAPI introspection schema (except possibly for the unit of measure, but there's a very weak justification). Another reason is the dynamicity of the schema. The QAPI introspection data is very much static; and while QOM is somewhat more dynamic, generally we consider that to be a bug rather than a feature these days. On the other hand, the statistics that are exposed by QEMU might be passed through from another source, such as KVM, and the disadvantages of manually updating the QAPI schema for outweight the benefits from vetting the statistics and filtering out anything that seems "too unstable". Running old QEMU with new kernel is a supported usecase; if old QEMU cannot expose statistics from a new kernel, or if a kernel developer needs to change QEMU before gathering new info from the new kernel, then that is a poor user interface. The framework provides a method to register callbacks for these QMP commands. Most of the work in fact is done by the callbacks, and a large majority of this patch is new QAPI structs and commands. Examples (with KVM stats): - Query all VM stats: { "execute": "query-stats", "arguments" : { "target": "vm" } } { "return": [ { "provider": "kvm", "stats": [ { "name": "max_mmu_page_hash_collisions", "value": 0 }, { "name": "max_mmu_rmap_size", "value": 0 }, { "name": "nx_lpage_splits", "value": 148 }, ... ] }, { "provider": "xyz", "stats": [ ... ] } ] } - Query all vCPU stats: { "execute": "query-stats", "arguments" : { "target": "vcpu" } } { "return": [ { "provider": "kvm", "qom_path": "/machine/unattached/device[0]" "stats": [ { "name": "guest_mode", "value": 0 }, { "name": "directed_yield_successful", "value": 0 }, { "name": "directed_yield_attempted", "value": 106 }, ... ] }, { "provider": "kvm", "qom_path": "/machine/unattached/device[1]" "stats": [ { "name": "guest_mode", "value": 0 }, { "name": "directed_yield_successful", "value": 0 }, { "name": "directed_yield_attempted", "value": 106 }, ... ] }, ] } - Retrieve the schemas: { "execute": "query-stats-schemas" } { "return": [ { "provider": "kvm", "target": "vcpu", "stats": [ { "name": "guest_mode", "unit": "none", "base": 10, "exponent": 0, "type": "instant" }, { "name": "directed_yield_successful", "unit": "none", "base": 10, "exponent": 0, "type": "cumulative" }, ... ] }, { "provider": "kvm", "target": "vm", "stats": [ { "name": "max_mmu_page_hash_collisions", "unit": "none", "base": 10, "exponent": 0, "type": "peak" }, ... ] }, { "provider": "xyz", "target": "vm", "stats": [ ... ] } ] } Signed-off-by: Mark Kanda <mark.kanda@oracle.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>	5 years ago

18 Commits (1a1cfc0a32b4345d5ef3f643994ae409eac9b164)