LXR qemu/qapi/trace.json

   1# -*- mode: python -*-
   2# vim: filetype=python
   3#
   4# Copyright (C) 2011-2016 Lluís Vilanova <vilanova@ac.upc.edu>
   5#
   6# This work is licensed under the terms of the GNU GPL, version 2 or later.
   7# See the COPYING file in the top-level directory.
   8
   9##
  10# = Tracing
  11##
  12
  13##
  14# @TraceEventState:
  15#
  16# State of a tracing event.
  17#
  18# @unavailable: The event is statically disabled.
  19#
  20# @disabled: The event is dynamically disabled.
  21#
  22# @enabled: The event is dynamically enabled.
  23#
  24# Since: 2.2
  25##
  26{ 'enum': 'TraceEventState',
  27  'data': ['unavailable', 'disabled', 'enabled'] }
  28
  29##
  30# @TraceEventInfo:
  31#
  32# Information of a tracing event.
  33#
  34# @name: Event name.
  35# @state: Tracing state.
  36# @vcpu: Whether this is a per-vCPU event (since 2.7).
  37#
  38# An event is per-vCPU if it has the "vcpu" property in the "trace-events"
  39# files.
  40#
  41# Since: 2.2
  42##
  43{ 'struct': 'TraceEventInfo',
  44  'data': {'name': 'str', 'state': 'TraceEventState', 'vcpu': 'bool'} }
  45
  46##
  47# @trace-event-get-state:
  48#
  49# Query the state of events.
  50#
  51# @name: Event name pattern (case-sensitive glob).
  52# @vcpu: The vCPU to query (any by default; since 2.7).
  53#
  54# Returns: a list of @TraceEventInfo for the matching events
  55#
  56#          An event is returned if:
  57#
  58#          - its name matches the @name pattern, and
  59#          - if @vcpu is given, the event has the "vcpu" property.
  60#
  61#          Therefore, if @vcpu is given, the operation will only match per-vCPU events,
  62#          returning their state on the specified vCPU. Special case: if @name is an
  63#          exact match, @vcpu is given and the event does not have the "vcpu" property,
  64#          an error is returned.
  65#
  66# Since: 2.2
  67#
  68# Example:
  69#
  70# -> { "execute": "trace-event-get-state",
  71#      "arguments": { "name": "qemu_memalign" } }
  72# <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] }
  73#
  74##
  75{ 'command': 'trace-event-get-state',
  76  'data': {'name': 'str', '*vcpu': 'int'},
  77  'returns': ['TraceEventInfo'] }
  78
  79##
  80# @trace-event-set-state:
  81#
  82# Set the dynamic tracing state of events.
  83#
  84# @name: Event name pattern (case-sensitive glob).
  85# @enable: Whether to enable tracing.
  86# @ignore-unavailable: Do not match unavailable events with @name.
  87# @vcpu: The vCPU to act upon (all by default; since 2.7).
  88#
  89# An event's state is modified if:
  90# - its name matches the @name pattern, and
  91# - if @vcpu is given, the event has the "vcpu" property.
  92#
  93# Therefore, if @vcpu is given, the operation will only match per-vCPU events,
  94# setting their state on the specified vCPU. Special case: if @name is an exact
  95# match, @vcpu is given and the event does not have the "vcpu" property, an
  96# error is returned.
  97#
  98# Since: 2.2
  99#
 100# Example:
 101#
 102# -> { "execute": "trace-event-set-state",
 103#      "arguments": { "name": "qemu_memalign", "enable": true } }
 104# <- { "return": {} }
 105#
 106##
 107{ 'command': 'trace-event-set-state',
 108  'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool',
 109           '*vcpu': 'int'} }
 110