# -*- 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.
#
# @target: the kind of objects to query.  Note that each possible
#     target may enable additional filtering options
#
# @providers: which providers to request statistics from, and
#     optionally 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.
#
# @boolean: single boolean value.
#
# @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 statistics, 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.
#
# @provider: a provider to restrict the query to.
#
# .. 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' ] }