qapi/trace.json

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