qapi/qdev.json

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