Merge remote-tracking branch 'remotes/rth/tags/pull-tcg-20210921' into staging
[qemu.git] / 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 more
24 # 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 more
37 # 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 from a
50 # hanging QEMU.
51 #
52 # Currently implemented yank instances:
53 #  - nbd block device:
54 #    Yanking it will shut down the connection to the nbd server without
55 #    attempting to reconnect.
56 #  - socket chardev:
57 #    Yanking it will shut down the connected socket.
58 #  - migration:
59 #    Yanking it will shut down all migration connections. Unlike
60 #    @migrate_cancel, it will not notify the migration process, so migration
61 #    will go into @failed state, instead of @cancelled state. @yank should be
62 #    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. See
77 # @YankInstance for more information.
78 #
79 # Takes a list of @YankInstance as argument.
80 #
81 # Returns: - Nothing on success
82 #          - @DeviceNotFound error, if any of the YankInstances doesn't exist
83 #
84 # Example:
85 #
86 # -> { "execute": "yank",
87 #      "arguments": {
88 #          "instances": [
89 #               { "type": "block-node",
90 #                 "node-name": "nbd0" }
91 #          ] } }
92 # <- { "return": {} }
93 #
94 # Since: 6.0
95 ##
96 { 'command': 'yank',
97   'data': { 'instances': ['YankInstance'] },
98   'allow-oob': true }
99
100 ##
101 # @query-yank:
102 #
103 # Query yank instances. See @YankInstance for more information.
104 #
105 # Returns: list of @YankInstance
106 #
107 # Example:
108 #
109 # -> { "execute": "query-yank" }
110 # <- { "return": [
111 #          { "type": "block-node",
112 #            "node-name": "nbd0" }
113 #      ] }
114 #
115 # Since: 6.0
116 ##
117 { 'command': 'query-yank',
118   'returns': ['YankInstance'],
119   'allow-oob': true }