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
  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 # 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 # Examples:
 108 #
 109 #     -> { "execute": "device_del",
 110 #          "arguments": { "id": "net1" } }
 111 #     <- { "return": {} }
 112 #
 113 #     -> { "execute": "device_del",
 114 #          "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 115 #     <- { "return": {} }
 116 ##
 117 { 'command': 'device_del', 'data': {'id': 'str'} }
 118
 119 ##
 120 # @DEVICE_DELETED:
 121 #
 122 # Emitted whenever the device removal completion is acknowledged by
 123 # the guest.  At this point, it's safe to reuse the specified device
 124 # ID. Device removal can be initiated by the guest or by HMP/QMP
 125 # commands.
 126 #
 127 # @device: the device's ID if it has one
 128 #
 129 # @path: the device's QOM path
 130 #
 131 # Since: 1.5
 132 #
 133 # Example:
 134 #
 135 #     <- { "event": "DEVICE_DELETED",
 136 #          "data": { "device": "virtio-net-pci-0",
 137 #                    "path": "/machine/peripheral/virtio-net-pci-0" },
 138 #          "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 139 ##
 140 { 'event': 'DEVICE_DELETED',
 141   'data': { '*device': 'str', 'path': 'str' } }
 142
 143 ##
 144 # @DEVICE_UNPLUG_GUEST_ERROR:
 145 #
 146 # Emitted when a device hot unplug fails due to a guest reported
 147 # error.
 148 #
 149 # @device: the device's ID if it has one
 150 #
 151 # @path: the device's QOM path
 152 #
 153 # Since: 6.2
 154 #
 155 # Example:
 156 #
 157 #     <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
 158 #          "data": { "device": "core1",
 159 #                    "path": "/machine/peripheral/core1" },
 160 #          "timestamp": { "seconds": 1615570772, "microseconds": 202844 } }
 161 ##
 162 { 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
 163   'data': { '*device': 'str', 'path': 'str' } }