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