0462da9d6b
The new qapidoc.py can generate "Returns" statements with type information just fine, so we can remove it from the source where it doesn't add anything particularly novel or helpful and just repeats the type info. This patch is fairly "gentle" and doesn't aggressively touch other "Returns" lines that could be rephrased to omit repeating type information; it only removes lines that appear appropriate to wholly remove. To help facilitate auto-generated placement, a few doc blocks have a "TODO:" line inserted to help the placement algorithm differentiate the introductory paragraph(s) from the rest of the documentation. The auto-generated returns are in the exact same spot, except for query-migrationthreads, query-machines, and x-query-virtio-queue-element. These auto-generation moves to a better spot. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250711051045.51110-4-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Two more Returns: removed, commit message amended to explain auto-generated returns generated into a different spot] Signed-off-by: Markus Armbruster <armbru@redhat.com>
121 lines
2.6 KiB
Python
121 lines
2.6 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
|
|
##
|
|
# ************
|
|
# Yank feature
|
|
# ************
|
|
##
|
|
|
|
##
|
|
# @YankInstanceType:
|
|
#
|
|
# An enumeration of yank instance types. See @YankInstance for more
|
|
# information.
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'enum': 'YankInstanceType',
|
|
'data': [ 'block-node', 'chardev', 'migration' ] }
|
|
|
|
##
|
|
# @YankInstanceBlockNode:
|
|
#
|
|
# Specifies which block graph node to yank. See @YankInstance for
|
|
# more information.
|
|
#
|
|
# @node-name: the name of the block graph node
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'struct': 'YankInstanceBlockNode',
|
|
'data': { 'node-name': 'str' } }
|
|
|
|
##
|
|
# @YankInstanceChardev:
|
|
#
|
|
# Specifies which character device to yank. See @YankInstance for
|
|
# more information.
|
|
#
|
|
# @id: the chardev's ID
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'struct': 'YankInstanceChardev',
|
|
'data': { 'id': 'str' } }
|
|
|
|
##
|
|
# @YankInstance:
|
|
#
|
|
# A yank instance can be yanked with the @yank qmp command to recover
|
|
# from a hanging QEMU.
|
|
#
|
|
# @type: yank instance type
|
|
#
|
|
# Currently implemented yank instances:
|
|
#
|
|
# - nbd block device: Yanking it will shut down the connection to the
|
|
# nbd server without attempting to reconnect.
|
|
# - socket chardev: Yanking it will shut down the connected socket.
|
|
# - migration: Yanking it will shut down all migration connections.
|
|
# Unlike @migrate_cancel, it will not notify the migration process,
|
|
# so migration will go into @failed state, instead of @cancelled
|
|
# state. @yank should be used to recover from hangs.
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'union': 'YankInstance',
|
|
'base': { 'type': 'YankInstanceType' },
|
|
'discriminator': 'type',
|
|
'data': {
|
|
'block-node': 'YankInstanceBlockNode',
|
|
'chardev': 'YankInstanceChardev' } }
|
|
|
|
##
|
|
# @yank:
|
|
#
|
|
# Try to recover from hanging QEMU by yanking the specified instances.
|
|
# See @YankInstance for more information.
|
|
#
|
|
# @instances: the instances to be yanked
|
|
#
|
|
# Errors:
|
|
# - If any of the YankInstances doesn't exist, DeviceNotFound
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "yank",
|
|
# "arguments": {
|
|
# "instances": [
|
|
# { "type": "block-node",
|
|
# "node-name": "nbd0" }
|
|
# ] } }
|
|
# <- { "return": {} }
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'command': 'yank',
|
|
'data': { 'instances': ['YankInstance'] },
|
|
'allow-oob': true }
|
|
|
|
##
|
|
# @query-yank:
|
|
#
|
|
# Query yank instances. See @YankInstance for more information.
|
|
#
|
|
# TODO: This line is a hack to separate the example from the body
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> { "execute": "query-yank" }
|
|
# <- { "return": [
|
|
# { "type": "block-node",
|
|
# "node-name": "nbd0" }
|
|
# ] }
|
|
#
|
|
# Since: 6.0
|
|
##
|
|
{ 'command': 'query-yank',
|
|
'returns': ['YankInstance'],
|
|
'allow-oob': true }
|