Merge tag 'pull-request-2022-12-04' of https://gitlab.com/thuth/qemu into staging
[qemu.git] / 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'} }