qapi/qdev.json

   1 # -*- Mode: Python -*-
   2 #
   3 # This work is licensed under the terms of the GNU GPL, version 2 or later.
   4 # See the COPYING file in the top-level directory.
   5
   6 ##
   7 # = Device infrastructure (qdev)
   8 ##
   9
  10 { 'include': 'qom.json' }
  11
  12 ##
  13 # @device-list-properties:
  14 #
  15 # List properties associated with a device.
  16 #
  17 # @typename: the type name of a device
  18 #
  19 # Returns: a list of ObjectPropertyInfo describing a devices properties
  20 #
  21 # Note: objects can create properties at runtime, for example to describe
  22 #       links between different devices and/or objects. These properties
  23 #       are not included in the output of this command.
  24 #
  25 # Since: 1.2
  26 ##
  27 { 'command': 'device-list-properties',
  28   'data': { 'typename': 'str'},
  29   'returns': [ 'ObjectPropertyInfo' ] }
  30
  31 ##
  32 # @device_add:
  33 #
  34 # @driver: the name of the new device's driver
  35 #
  36 # @bus: the device's parent bus (device tree path)
  37 #
  38 # @id: the device's ID, must be unique
  39 #
  40 # Additional arguments depend on the type.
  41 #
  42 # Add a device.
  43 #
  44 # Notes:
  45 # 1. For detailed information about this command, please refer to the
  46 #    'docs/qdev-device-use.txt' file.
  47 #
  48 # 2. It's possible to list device properties by running QEMU with the
  49 #    "-device DEVICE,help" command-line argument, where DEVICE is the
  50 #    device's name
  51 #
  52 # Example:
  53 #
  54 # -> { "execute": "device_add",
  55 #      "arguments": { "driver": "e1000", "id": "net1",
  56 #                     "bus": "pci.0",
  57 #                     "mac": "52:54:00:12:34:56" } }
  58 # <- { "return": {} }
  59 #
  60 # TODO: This command effectively bypasses QAPI completely due to its
  61 #       "additional arguments" business.  It shouldn't have been added to
  62 #       the schema in this form.  It should be qapified properly, or
  63 #       replaced by a properly qapified command.
  64 #
  65 # Since: 0.13
  66 ##
  67 { 'command': 'device_add',
  68   'data': {'driver': 'str', '*bus': 'str', '*id': 'str'},
  69   'gen': false } # so we can get the additional arguments
  70
  71 ##
  72 # @device_del:
  73 #
  74 # Remove a device from a guest
  75 #
  76 # @id: the device's ID or QOM path
  77 #
  78 # Returns: Nothing on success
  79 #          If @id is not a valid device, DeviceNotFound
  80 #
  81 # Notes: When this command completes, the device may not be removed from the
  82 #        guest.  Hot removal is an operation that requires guest cooperation.
  83 #        This command merely requests that the guest begin the hot removal
  84 #        process.  Completion of the device removal process is signaled with a
  85 #        DEVICE_DELETED event. Guest reset will automatically complete removal
  86 #        for all devices.
  87 #
  88 # Since: 0.14.0
  89 #
  90 # Example:
  91 #
  92 # -> { "execute": "device_del",
  93 #      "arguments": { "id": "net1" } }
  94 # <- { "return": {} }
  95 #
  96 # -> { "execute": "device_del",
  97 #      "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
  98 # <- { "return": {} }
  99 #
 100 ##
 101 { 'command': 'device_del', 'data': {'id': 'str'} }
 102
 103 ##
 104 # @DEVICE_DELETED:
 105 #
 106 # Emitted whenever the device removal completion is acknowledged by the guest.
 107 # At this point, it's safe to reuse the specified device ID. Device removal can
 108 # be initiated by the guest or by HMP/QMP commands.
 109 #
 110 # @device: device name
 111 #
 112 # @path: device path
 113 #
 114 # Since: 1.5
 115 #
 116 # Example:
 117 #
 118 # <- { "event": "DEVICE_DELETED",
 119 #      "data": { "device": "virtio-net-pci-0",
 120 #                "path": "/machine/peripheral/virtio-net-pci-0" },
 121 #      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
 122 #
 123 ##
 124 { 'event': 'DEVICE_DELETED',
 125   'data': { '*device': 'str', 'path': 'str' } }