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: 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 # Example:
  67 #
  68 # -> { "execute": "trace-event-get-state",
  69 #      "arguments": { "name": "qemu_memalign" } }
  70 # <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
  71 #
  72 ##
  73 { 'command': 'trace-event-get-state',
  74   'data': {'name': 'str', '*vcpu': 'int'},
  75   'returns': ['TraceEventInfo'] }
  76
  77 ##
  78 # @trace-event-set-state:
  79 #
  80 # Set the dynamic tracing state of events.
  81 #
  82 # @name: Event name pattern (case-sensitive glob).
  83 # @enable: Whether to enable tracing.
  84 # @ignore-unavailable: Do not match unavailable events with @name.
  85 # @vcpu: The vCPU to act upon (all by default; since 2.7).
  86 #
  87 # An event's state is modified if:
  88 # - its name matches the @name pattern, and
  89 # - if @vcpu is given, the event has the "vcpu" property.
  90 #
  91 # Therefore, if @vcpu is given, the operation will only match per-vCPU events,
  92 # setting their state on the specified vCPU. Special case: if @name is an exact
  93 # match, @vcpu is given and the event does not have the "vcpu" property, an
  94 # error is returned.
  95 #
  96 # Since: 2.2
  97 #
  98 # Example:
  99 #
 100 # -> { "execute": "trace-event-set-state",
 101 #      "arguments": { "name": "qemu_memalign", "enable": "true" } }
 102 # <- { "return": {} }
 103 #
 104 ##
 105 { 'command': 'trace-event-set-state',
 106   'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool',
 107            '*vcpu': 'int'} }