Merge remote-tracking branch 'remotes/bonzini-gitlab/tags/for-upstream' 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
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'} }