mirror of
https://gitlab.com/qemu-project/qemu
synced 2024-09-06 01:43:39 +00:00
![Markus Armbruster](/assets/img/avatar_default.png)
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]
272 lines
6.4 KiB
Python
272 lines
6.4 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Copyright (c) 2022 Oracle and/or its affiliates.
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2 or later.
|
|
# See the COPYING file in the top-level directory.
|
|
#
|
|
# SPDX-License-Identifier: GPL-2.0-or-later
|
|
|
|
##
|
|
# = Statistics
|
|
##
|
|
|
|
##
|
|
# @StatsType:
|
|
#
|
|
# Enumeration of statistics types
|
|
#
|
|
# @cumulative: stat is cumulative; value can only increase.
|
|
#
|
|
# @instant: stat is instantaneous; value can increase or decrease.
|
|
#
|
|
# @peak: stat is the peak value; value can only increase.
|
|
#
|
|
# @linear-histogram: stat is a linear histogram.
|
|
#
|
|
# @log2-histogram: stat is a logarithmic histogram, with one bucket
|
|
# for each power of two.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'enum' : 'StatsType',
|
|
'data' : [ 'cumulative', 'instant', 'peak', 'linear-histogram',
|
|
'log2-histogram' ] }
|
|
|
|
##
|
|
# @StatsUnit:
|
|
#
|
|
# Enumeration of unit of measurement for statistics
|
|
#
|
|
# @bytes: stat reported in bytes.
|
|
#
|
|
# @seconds: stat reported in seconds.
|
|
#
|
|
# @cycles: stat reported in clock cycles.
|
|
#
|
|
# @boolean: stat is a boolean value.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'enum' : 'StatsUnit',
|
|
'data' : [ 'bytes', 'seconds', 'cycles', 'boolean' ] }
|
|
|
|
##
|
|
# @StatsProvider:
|
|
#
|
|
# Enumeration of statistics providers.
|
|
#
|
|
# @kvm: since 7.1
|
|
#
|
|
# @cryptodev: since 8.0
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'enum': 'StatsProvider',
|
|
'data': [ 'kvm', 'cryptodev' ] }
|
|
|
|
##
|
|
# @StatsTarget:
|
|
#
|
|
# The kinds of objects on which one can request statistics.
|
|
#
|
|
# @vm: statistics that apply to the entire virtual machine or the
|
|
# entire QEMU process.
|
|
#
|
|
# @vcpu: statistics that apply to a single virtual CPU.
|
|
#
|
|
# @cryptodev: statistics that apply to a crypto device (since 8.0)
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'enum': 'StatsTarget',
|
|
'data': [ 'vm', 'vcpu', 'cryptodev' ] }
|
|
|
|
##
|
|
# @StatsRequest:
|
|
#
|
|
# Indicates a set of statistics that should be returned by
|
|
# query-stats.
|
|
#
|
|
# @provider: provider for which to return statistics.
|
|
#
|
|
# @names: statistics to be returned (all if omitted).
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'struct': 'StatsRequest',
|
|
'data': { 'provider': 'StatsProvider',
|
|
'*names': [ 'str' ] } }
|
|
|
|
##
|
|
# @StatsVCPUFilter:
|
|
#
|
|
# @vcpus: list of QOM paths for the desired vCPU objects.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'struct': 'StatsVCPUFilter',
|
|
'data': { '*vcpus': [ 'str' ] } }
|
|
|
|
##
|
|
# @StatsFilter:
|
|
#
|
|
# The arguments to the query-stats command; specifies a target for
|
|
# which to request statistics and optionally the required subset of
|
|
# information for that target:
|
|
#
|
|
# - which vCPUs to request statistics for
|
|
# - which providers to request statistics from
|
|
# - which named values to return within each provider
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'union': 'StatsFilter',
|
|
'base': {
|
|
'target': 'StatsTarget',
|
|
'*providers': [ 'StatsRequest' ] },
|
|
'discriminator': 'target',
|
|
'data': { 'vcpu': 'StatsVCPUFilter' } }
|
|
|
|
##
|
|
# @StatsValue:
|
|
#
|
|
# @scalar: single unsigned 64-bit integers.
|
|
#
|
|
# @list: list of unsigned 64-bit integers (used for histograms).
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'alternate': 'StatsValue',
|
|
'data': { 'scalar': 'uint64',
|
|
'boolean': 'bool',
|
|
'list': [ 'uint64' ] } }
|
|
|
|
##
|
|
# @Stats:
|
|
#
|
|
# @name: name of stat.
|
|
#
|
|
# @value: stat value.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'struct': 'Stats',
|
|
'data': { 'name': 'str',
|
|
'value' : 'StatsValue' } }
|
|
|
|
##
|
|
# @StatsResult:
|
|
#
|
|
# @provider: provider for this set of statistics.
|
|
#
|
|
# @qom-path: Path to the object for which the statistics are returned,
|
|
# if the object is exposed in the QOM tree
|
|
#
|
|
# @stats: list of statistics.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'struct': 'StatsResult',
|
|
'data': { 'provider': 'StatsProvider',
|
|
'*qom-path': 'str',
|
|
'stats': [ 'Stats' ] } }
|
|
|
|
##
|
|
# @query-stats:
|
|
#
|
|
# Return runtime-collected statistics for objects such as the VM or
|
|
# its vCPUs.
|
|
#
|
|
# The arguments are a StatsFilter and specify the provider and objects
|
|
# to return statistics about.
|
|
#
|
|
# Returns: a list of StatsResult, one for each provider and object
|
|
# (e.g., for each vCPU).
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'command': 'query-stats',
|
|
'data': 'StatsFilter',
|
|
'boxed': true,
|
|
'returns': [ 'StatsResult' ] }
|
|
|
|
##
|
|
# @StatsSchemaValue:
|
|
#
|
|
# Schema for a single statistic.
|
|
#
|
|
# @name: name of the statistic; each element of the schema is uniquely
|
|
# identified by a target, a provider (both available in
|
|
# @StatsSchema) and the name.
|
|
#
|
|
# @type: kind of statistic.
|
|
#
|
|
# @unit: basic unit of measure for the statistic; if missing, the
|
|
# statistic is a simple number or counter.
|
|
#
|
|
# @base: base for the multiple of @unit in which the statistic is
|
|
# measured. Only present if @exponent is non-zero; @base and
|
|
# @exponent together form a SI prefix (e.g., _nano-_ for
|
|
# ``base=10`` and ``exponent=-9``) or IEC binary prefix (e.g.
|
|
# _kibi-_ for ``base=2`` and ``exponent=10``)
|
|
#
|
|
# @exponent: exponent for the multiple of @unit in which the statistic
|
|
# is expressed, or 0 for the basic unit
|
|
#
|
|
# @bucket-size: Present when @type is "linear-histogram", contains the
|
|
# width of each bucket of the histogram.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'struct': 'StatsSchemaValue',
|
|
'data': { 'name': 'str',
|
|
'type': 'StatsType',
|
|
'*unit': 'StatsUnit',
|
|
'*base': 'int8',
|
|
'exponent': 'int16',
|
|
'*bucket-size': 'uint32' } }
|
|
|
|
##
|
|
# @StatsSchema:
|
|
#
|
|
# Schema for all available statistics for a provider and target.
|
|
#
|
|
# @provider: provider for this set of statistics.
|
|
#
|
|
# @target: the kind of object that can be queried through the
|
|
# provider.
|
|
#
|
|
# @stats: list of statistics.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'struct': 'StatsSchema',
|
|
'data': { 'provider': 'StatsProvider',
|
|
'target': 'StatsTarget',
|
|
'stats': [ 'StatsSchemaValue' ] } }
|
|
|
|
##
|
|
# @query-stats-schemas:
|
|
#
|
|
# Return the schema for all available runtime-collected statistics.
|
|
#
|
|
# Note: runtime-collected statistics and their names fall outside
|
|
# QEMU's usual deprecation policies. QEMU will try to keep the
|
|
# set of available data stable, together with their names, but
|
|
# will not guarantee stability at all costs; the same is true of
|
|
# providers that source statistics externally, e.g. from Linux.
|
|
# For example, if the same value is being tracked with different
|
|
# names on different architectures or by different providers, one
|
|
# of them might be renamed. A statistic might go away if an
|
|
# algorithm is changed or some code is removed; changing a default
|
|
# might cause previously useful statistics to always report 0.
|
|
# Such changes, however, are expected to be rare.
|
|
#
|
|
# Since: 7.1
|
|
##
|
|
{ 'command': 'query-stats-schemas',
|
|
'data': { '*provider': 'StatsProvider' },
|
|
'returns': [ 'StatsSchema' ] }
|