xref: /qemu/qapi/yank.json (revision a0e93dd8) 
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#     - @DeviceNotFound error, if any of the YankInstances doesn't exist
84#
85# Example:
86#
87# -> { "execute": "yank",
88#      "arguments": {
89#          "instances": [
90#               { "type": "block-node",
91#                 "node-name": "nbd0" }
92#          ] } }
93# <- { "return": {} }
94#
95# Since: 6.0
96##
97{ 'command': 'yank',
98  'data': { 'instances': ['YankInstance'] },
99  'allow-oob': true }
100
101##
102# @query-yank:
103#
104# Query yank instances.  See @YankInstance for more information.
105#
106# Returns: list of @YankInstance
107#
108# Example:
109#
110# -> { "execute": "query-yank" }
111# <- { "return": [
112#          { "type": "block-node",
113#            "node-name": "nbd0" }
114#      ] }
115#
116# Since: 6.0
117##
118{ 'command': 'query-yank',
119  'returns': ['YankInstance'],
120  'allow-oob': true }
121