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'} }