Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-03-16' into staging
[qemu.git] / 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'} }