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