qapi/yank.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4
   5 ##
   6 # = Yank feature
   7 ##
   8
   9 ##
  10 # @YankInstanceType:
  11 #
  12 # An enumeration of yank instance types.  See @YankInstance for more
  13 # information.
  14 #
  15 # Since: 6.0
  16 ##
  17 { 'enum': 'YankInstanceType',
  18   'data': [ 'block-node', 'chardev', 'migration' ] }
  19
  20 ##
  21 # @YankInstanceBlockNode:
  22 #
  23 # Specifies which block graph node to yank.  See @YankInstance for
  24 # more information.
  25 #
  26 # @node-name: the name of the block graph node
  27 #
  28 # Since: 6.0
  29 ##
  30 { 'struct': 'YankInstanceBlockNode',
  31   'data': { 'node-name': 'str' } }
  32
  33 ##
  34 # @YankInstanceChardev:
  35 #
  36 # Specifies which character device to yank.  See @YankInstance for
  37 # more information.
  38 #
  39 # @id: the chardev's ID
  40 #
  41 # Since: 6.0
  42 ##
  43 { 'struct': 'YankInstanceChardev',
  44   'data': { 'id': 'str' } }
  45
  46 ##
  47 # @YankInstance:
  48 #
  49 # A yank instance can be yanked with the @yank qmp command to recover
  50 # from a hanging QEMU.
  51 #
  52 # @type: yank instance type
  53 #
  54 # Currently implemented yank instances:
  55 #
  56 # - nbd block device: Yanking it will shut down the connection to the
  57 #   nbd server without attempting to reconnect.
  58 # - socket chardev: Yanking it will shut down the connected socket.
  59 # - migration: Yanking it will shut down all migration connections.
  60 #   Unlike @migrate_cancel, it will not notify the migration process,
  61 #   so migration will go into @failed state, instead of @cancelled
  62 #   state.  @yank should be used to recover from hangs.
  63 #
  64 # Since: 6.0
  65 ##
  66 { 'union': 'YankInstance',
  67   'base': { 'type': 'YankInstanceType' },
  68   'discriminator': 'type',
  69   'data': {
  70       'block-node': 'YankInstanceBlockNode',
  71       'chardev': 'YankInstanceChardev' } }
  72
  73 ##
  74 # @yank:
  75 #
  76 # Try to recover from hanging QEMU by yanking the specified instances.
  77 # See @YankInstance for more information.
  78 #
  79 # @instances: the instances to be yanked
  80 #
  81 # Returns:
  82 #     - Nothing on success
  83 #
  84 # Errors:
  85 #     - @DeviceNotFound error, if any of the YankInstances doesn't exist
  86 #
  87 # Example:
  88 #
  89 #     -> { "execute": "yank",
  90 #          "arguments": {
  91 #              "instances": [
  92 #                   { "type": "block-node",
  93 #                     "node-name": "nbd0" }
  94 #              ] } }
  95 #     <- { "return": {} }
  96 #
  97 # Since: 6.0
  98 ##
  99 { 'command': 'yank',
 100   'data': { 'instances': ['YankInstance'] },
 101   'allow-oob': true }
 102
 103 ##
 104 # @query-yank:
 105 #
 106 # Query yank instances.  See @YankInstance for more information.
 107 #
 108 # Returns: list of @YankInstance
 109 #
 110 # Example:
 111 #
 112 #     -> { "execute": "query-yank" }
 113 #     <- { "return": [
 114 #              { "type": "block-node",
 115 #                "node-name": "nbd0" }
 116 #          ] }
 117 #
 118 # Since: 6.0
 119 ##
 120 { 'command': 'query-yank',
 121   'returns': ['YankInstance'],
 122   'allow-oob': true }