| 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 | # **************************** |
| 9 | # Device infrastructure (qdev) |
| 10 | # **************************** |
| 11 | ## |
| 12 | |
| 13 | { 'include': 'qom.json' } |
| 14 | |
| 15 | ## |
| 16 | # @device-list-properties: |
| 17 | # |
| 18 | # List properties associated with a device. |
| 19 | # |
| 20 | # @typename: the type name of a device |
| 21 | # |
| 22 | # Returns: a list describing a devices properties |
| 23 | # |
| 24 | # .. note:: Objects can create properties at runtime, for example to |
| 25 | # describe links between different devices and/or objects. These |
| 26 | # properties are not included in the output of this command. |
| 27 | # |
| 28 | # Since: 1.2 |
| 29 | ## |
| 30 | { 'command': 'device-list-properties', |
| 31 | 'data': { 'typename': 'str'}, |
| 32 | 'returns': [ 'ObjectPropertyInfo' ] } |
| 33 | |
| 34 | ## |
| 35 | # @device_add: |
| 36 | # |
| 37 | # Add a device. |
| 38 | # |
| 39 | # @driver: the name of the new device's driver |
| 40 | # |
| 41 | # @bus: the device's parent bus (device tree path) |
| 42 | # |
| 43 | # @id: the device's ID, must be unique |
| 44 | # |
| 45 | # Features: |
| 46 | # |
| 47 | # @json-cli: If present, the "-device" command line option supports |
| 48 | # JSON syntax with a structure identical to the arguments of this |
| 49 | # command. |
| 50 | # |
| 51 | # @json-cli-hotplug: If present, the "-device" command line option |
| 52 | # supports JSON syntax without the reference counting leak that |
| 53 | # broke hot-unplug |
| 54 | # |
| 55 | # .. admonition:: Notes |
| 56 | # |
| 57 | # 1. Additional arguments depend on the type. |
| 58 | # |
| 59 | # 2. For detailed information about this command, please refer to |
| 60 | # the 'docs/qdev-device-use.txt' file. |
| 61 | # |
| 62 | # 3. It's possible to list device properties by running QEMU with |
| 63 | # the ``-device DEVICE,help`` command-line argument, where |
| 64 | # DEVICE is the device's name. |
| 65 | # |
| 66 | # .. qmp-example:: |
| 67 | # |
| 68 | # -> { "execute": "device_add", |
| 69 | # "arguments": { "driver": "e1000", "id": "net1", |
| 70 | # "bus": "pci.0", |
| 71 | # "mac": "52:54:00:12:34:56" } } |
| 72 | # <- { "return": {} } |
| 73 | # |
| 74 | # TODO: This command effectively bypasses QAPI completely due to its |
| 75 | # "additional arguments" business. It shouldn't have been added |
| 76 | # to the schema in this form. It should be qapified properly, or |
| 77 | # replaced by a properly qapified command. |
| 78 | # |
| 79 | # Since: 0.13 |
| 80 | ## |
| 81 | { 'command': 'device_add', |
| 82 | 'data': {'driver': 'str', '*bus': 'str', '*id': 'str'}, |
| 83 | 'gen': false, # so we can get the additional arguments |
| 84 | 'features': ['json-cli', 'json-cli-hotplug'] } |
| 85 | |
| 86 | ## |
| 87 | # @device_del: |
| 88 | # |
| 89 | # Remove a device from a guest |
| 90 | # |
| 91 | # @id: the device's ID or QOM path |
| 92 | # |
| 93 | # Errors: |
| 94 | # - If @id is not a valid device, DeviceNotFound |
| 95 | # |
| 96 | # .. note:: When this command completes, the device may not be removed |
| 97 | # from the guest. Hot removal is an operation that requires guest |
| 98 | # cooperation. This command merely requests that the guest begin |
| 99 | # the hot removal process. Completion of the device removal |
| 100 | # process is signaled with a `DEVICE_DELETED` event. Guest reset |
| 101 | # will automatically complete removal for all devices. If a |
| 102 | # guest-side error in the hot removal process is detected, the |
| 103 | # device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` |
| 104 | # event is sent. Some errors cannot be detected. |
| 105 | # |
| 106 | # Since: 0.14 |
| 107 | # |
| 108 | # .. qmp-example:: |
| 109 | # |
| 110 | # -> { "execute": "device_del", |
| 111 | # "arguments": { "id": "net1" } } |
| 112 | # <- { "return": {} } |
| 113 | # |
| 114 | # .. qmp-example:: |
| 115 | # |
| 116 | # -> { "execute": "device_del", |
| 117 | # "arguments": { "id": "/machine/peripheral-anon/device[0]" } } |
| 118 | # <- { "return": {} } |
| 119 | ## |
| 120 | { 'command': 'device_del', 'data': {'id': 'str'} } |
| 121 | |
| 122 | ## |
| 123 | # @DEVICE_DELETED: |
| 124 | # |
| 125 | # Emitted whenever the device removal completion is acknowledged by |
| 126 | # the guest. At this point, it's safe to reuse the specified device |
| 127 | # ID. Device removal can be initiated by the guest or by HMP/QMP |
| 128 | # commands. |
| 129 | # |
| 130 | # @device: the device's ID if it has one |
| 131 | # |
| 132 | # @path: the device's QOM path |
| 133 | # |
| 134 | # Since: 1.5 |
| 135 | # |
| 136 | # .. qmp-example:: |
| 137 | # |
| 138 | # <- { "event": "DEVICE_DELETED", |
| 139 | # "data": { "device": "virtio-net-pci-0", |
| 140 | # "path": "/machine/peripheral/virtio-net-pci-0" }, |
| 141 | # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } |
| 142 | ## |
| 143 | { 'event': 'DEVICE_DELETED', |
| 144 | 'data': { '*device': 'str', 'path': 'str' } } |
| 145 | |
| 146 | ## |
| 147 | # @DEVICE_UNPLUG_GUEST_ERROR: |
| 148 | # |
| 149 | # Emitted when a device hot unplug fails due to a guest reported |
| 150 | # error. |
| 151 | # |
| 152 | # @device: the device's ID if it has one |
| 153 | # |
| 154 | # @path: the device's QOM path |
| 155 | # |
| 156 | # Since: 6.2 |
| 157 | # |
| 158 | # .. qmp-example:: |
| 159 | # |
| 160 | # <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", |
| 161 | # "data": { "device": "core1", |
| 162 | # "path": "/machine/peripheral/core1" }, |
| 163 | # "timestamp": { "seconds": 1615570772, "microseconds": 202844 } } |
| 164 | ## |
| 165 | { 'event': 'DEVICE_UNPLUG_GUEST_ERROR', |
| 166 | 'data': { '*device': 'str', 'path': 'str' } } |
| 167 | |
| 168 | ## |
| 169 | # @device-sync-config: |
| 170 | # |
| 171 | # Synchronize device configuration from host to guest part. First, |
| 172 | # copy the configuration from the host part (backend) to the guest |
| 173 | # part (frontend). Then notify guest software that device |
| 174 | # configuration changed. |
| 175 | # |
| 176 | # The command may be used to notify the guest about block device |
| 177 | # capacity change. Currently only vhost-user-blk device supports |
| 178 | # this. |
| 179 | # |
| 180 | # @id: the device's ID or QOM path |
| 181 | # |
| 182 | # Features: |
| 183 | # |
| 184 | # @unstable: The command is experimental. |
| 185 | # |
| 186 | # Since: 9.2 |
| 187 | ## |
| 188 | { 'command': 'device-sync-config', |
| 189 | 'features': [ 'unstable' ], |
| 190 | 'data': {'id': 'str'} } |