xref: /qemu/qapi/qdev.json (revision 654d6b04) 
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4# This work is licensed under the terms of the GNU GPL, version 2 or later.
5# See the COPYING file in the top-level directory.
6
7##
8# = Device infrastructure (qdev)
9##
10
11{ 'include': 'qom.json' }
12
13##
14# @device-list-properties:
15#
16# List properties associated with a device.
17#
18# @typename: the type name of a device
19#
20# Returns: a list of ObjectPropertyInfo describing a devices properties
21#
22# Note: objects can create properties at runtime, for example to describe
23#       links between different devices and/or objects. These properties
24#       are not included in the output of this command.
25#
26# Since: 1.2
27##
28{ 'command': 'device-list-properties',
29  'data': { 'typename': 'str'},
30  'returns': [ 'ObjectPropertyInfo' ] }
31
32##
33# @device_add:
34#
35# @driver: the name of the new device's driver
36#
37# @bus: the device's parent bus (device tree path)
38#
39# @id: the device's ID, must be unique
40#
41# Additional arguments depend on the type.
42#
43# Add a device.
44#
45# Notes:
46# 1. For detailed information about this command, please refer to the
47#    'docs/qdev-device-use.txt' file.
48#
49# 2. It's possible to list device properties by running QEMU with the
50#    "-device DEVICE,help" command-line argument, where DEVICE is the
51#    device's name
52#
53# Example:
54#
55# -> { "execute": "device_add",
56#      "arguments": { "driver": "e1000", "id": "net1",
57#                     "bus": "pci.0",
58#                     "mac": "52:54:00:12:34:56" } }
59# <- { "return": {} }
60#
61# TODO: This command effectively bypasses QAPI completely due to its
62#       "additional arguments" business.  It shouldn't have been added to
63#       the schema in this form.  It should be qapified properly, or
64#       replaced by a properly qapified command.
65#
66# Since: 0.13
67##
68{ 'command': 'device_add',
69  'data': {'driver': 'str', '*bus': 'str', '*id': 'str'},
70  'gen': false } # so we can get the additional arguments
71
72##
73# @device_del:
74#
75# Remove a device from a guest
76#
77# @id: the device's ID or QOM path
78#
79# Returns: Nothing on success
80#          If @id is not a valid device, DeviceNotFound
81#
82# Notes: When this command completes, the device may not be removed from the
83#        guest.  Hot removal is an operation that requires guest cooperation.
84#        This command merely requests that the guest begin the hot removal
85#        process.  Completion of the device removal process is signaled with a
86#        DEVICE_DELETED event. Guest reset will automatically complete removal
87#        for all devices.  If a guest-side error in the hot removal process is
88#        detected, the device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR
89#        event is sent.  Some errors cannot be detected.
90#
91# Since: 0.14
92#
93# Example:
94#
95# -> { "execute": "device_del",
96#      "arguments": { "id": "net1" } }
97# <- { "return": {} }
98#
99# -> { "execute": "device_del",
100#      "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
101# <- { "return": {} }
102#
103##
104{ 'command': 'device_del', 'data': {'id': 'str'} }
105
106##
107# @DEVICE_DELETED:
108#
109# Emitted whenever the device removal completion is acknowledged by the guest.
110# At this point, it's safe to reuse the specified device ID. Device removal can
111# be initiated by the guest or by HMP/QMP commands.
112#
113# @device: the device's ID if it has one
114#
115# @path: the device's QOM path
116#
117# Since: 1.5
118#
119# Example:
120#
121# <- { "event": "DEVICE_DELETED",
122#      "data": { "device": "virtio-net-pci-0",
123#                "path": "/machine/peripheral/virtio-net-pci-0" },
124#      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
125#
126##
127{ 'event': 'DEVICE_DELETED',
128  'data': { '*device': 'str', 'path': 'str' } }
129
130##
131# @DEVICE_UNPLUG_GUEST_ERROR:
132#
133# Emitted when a device hot unplug fails due to a guest reported error.
134#
135# @device: the device's ID if it has one
136#
137# @path: the device's QOM path
138#
139# Since: 6.2
140#
141# Example:
142#
143# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR"
144#      "data": { "device": "core1",
145#                "path": "/machine/peripheral/core1" },
146#      },
147#      "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
148#
149##
150{ 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
151  'data': { '*device': 'str', 'path': 'str' } }
152