xref: /openbmc/qemu/qapi/trace.json (revision 89fc45d5) 
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'} }
110