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