# -*- 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.
#
# Since: 7.1
##
{ 'enum': 'StatsProvider',
  'data': [ 'kvm' ] }

##
# @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.
#
# Since: 7.1
##
{ 'enum': 'StatsTarget',
  'data': [ 'vm', 'vcpu' ] }

##
# @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' ] }