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