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