xref: /qemu/qapi/qdev.json (revision abff1abf) 
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.
88#
89# Since: 0.14.0
90#
91# Example:
92#
93# -> { "execute": "device_del",
94#      "arguments": { "id": "net1" } }
95# <- { "return": {} }
96#
97# -> { "execute": "device_del",
98#      "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
99# <- { "return": {} }
100#
101##
102{ 'command': 'device_del', 'data': {'id': 'str'} }
103
104##
105# @DEVICE_DELETED:
106#
107# Emitted whenever the device removal completion is acknowledged by the guest.
108# At this point, it's safe to reuse the specified device ID. Device removal can
109# be initiated by the guest or by HMP/QMP commands.
110#
111# @device: device name
112#
113# @path: device path
114#
115# Since: 1.5
116#
117# Example:
118#
119# <- { "event": "DEVICE_DELETED",
120#      "data": { "device": "virtio-net-pci-0",
121#                "path": "/machine/peripheral/virtio-net-pci-0" },
122#      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
123#
124##
125{ 'event': 'DEVICE_DELETED',
126  'data': { '*device': 'str', 'path': 'str' } }
127