summaryrefslogtreecommitdiffstats
path: root/qapi/qdev.json
blob: 2708fb4e993059a77a704a1376b32bcbbf4d84e5 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# -*- Mode: Python -*-
# vim: filetype=python
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.

##
# = Device infrastructure (qdev)
##

{ 'include': 'qom.json' }

##
# @device-list-properties:
#
# List properties associated with a device.
#
# @typename: the type name of a device
#
# Returns: a list of ObjectPropertyInfo describing a devices properties
#
# Note: objects can create properties at runtime, for example to describe
#       links between different devices and/or objects. These properties
#       are not included in the output of this command.
#
# Since: 1.2
##
{ 'command': 'device-list-properties',
  'data': { 'typename': 'str'},
  'returns': [ 'ObjectPropertyInfo' ] }

##
# @device_add:
#
# Add a device.
#
# @driver: the name of the new device's driver
#
# @bus: the device's parent bus (device tree path)
#
# @id: the device's ID, must be unique
#
# Features:
# @json-cli: If present, the "-device" command line option supports JSON
#            syntax with a structure identical to the arguments of this
#            command.
# @json-cli-hotplug: If present, the "-device" command line option supports JSON
#                    syntax without the reference counting leak that broke
#                    hot-unplug
#
# Notes:
#
# Additional arguments depend on the type.
#
# 1. For detailed information about this command, please refer to the
#    'docs/qdev-device-use.txt' file.
#
# 2. It's possible to list device properties by running QEMU with the
#    "-device DEVICE,help" command-line argument, where DEVICE is the
#    device's name
#
# Example:
#
# -> { "execute": "device_add",
#      "arguments": { "driver": "e1000", "id": "net1",
#                     "bus": "pci.0",
#                     "mac": "52:54:00:12:34:56" } }
# <- { "return": {} }
#
# TODO: This command effectively bypasses QAPI completely due to its
#       "additional arguments" business.  It shouldn't have been added to
#       the schema in this form.  It should be qapified properly, or
#       replaced by a properly qapified command.
#
# Since: 0.13
##
{ 'command': 'device_add',
  'data': {'driver': 'str', '*bus': 'str', '*id': 'str'},
  'gen': false, # so we can get the additional arguments
  'features': ['json-cli', 'json-cli-hotplug'] }

##
# @device_del:
#
# Remove a device from a guest
#
# @id: the device's ID or QOM path
#
# Returns: Nothing on success
#          If @id is not a valid device, DeviceNotFound
#
# Notes: When this command completes, the device may not be removed from the
#        guest.  Hot removal is an operation that requires guest cooperation.
#        This command merely requests that the guest begin the hot removal
#        process.  Completion of the device removal process is signaled with a
#        DEVICE_DELETED event. Guest reset will automatically complete removal
#        for all devices.  If a guest-side error in the hot removal process is
#        detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR
#        event is sent.  Some errors cannot be detected.
#
# Since: 0.14
#
# Example:
#
# -> { "execute": "device_del",
#      "arguments": { "id": "net1" } }
# <- { "return": {} }
#
# -> { "execute": "device_del",
#      "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
# <- { "return": {} }
#
##
{ 'command': 'device_del', 'data': {'id': 'str'} }

##
# @DEVICE_DELETED:
#
# Emitted whenever the device removal completion is acknowledged by the guest.
# At this point, it's safe to reuse the specified device ID. Device removal can
# be initiated by the guest or by HMP/QMP commands.
#
# @device: the device's ID if it has one
#
# @path: the device's QOM path
#
# Since: 1.5
#
# Example:
#
# <- { "event": "DEVICE_DELETED",
#      "data": { "device": "virtio-net-pci-0",
#                "path": "/machine/peripheral/virtio-net-pci-0" },
#      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
#
##
{ 'event': 'DEVICE_DELETED',
  'data': { '*device': 'str', 'path': 'str' } }

##
# @DEVICE_UNPLUG_GUEST_ERROR:
#
# Emitted when a device hot unplug fails due to a guest reported error.
#
# @device: the device's ID if it has one
#
# @path: the device's QOM path
#
# Since: 6.2
#
# Example:
#
# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
#      "data": { "device": "core1",
#                "path": "/machine/peripheral/core1" },
#      "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
#
##
{ 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
  'data': { '*device': 'str', 'path': 'str' } }