qemu-e2k/qapi/yank.json
Markus Armbruster a937b6aa73 qapi: Reformat doc comments to conform to current conventions
Change

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #        do eiusmod tempor incididunt ut labore et dolore magna aliqua.

to

    # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
    #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.

See recent commit "qapi: Relax doc string @name: description
indentation rules" for rationale.

Reflow paragraphs to 70 columns width, and consistently use two spaces
to separate sentences.

To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3".  Finds no
differences.  Comparing with diff is not useful, as the reflown
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-18-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Acked-by: Lukas Straub <lukasstraub2@web.de>
[Straightforward conflicts in qapi/audio.json qapi/misc-target.json
qapi/run-state.json resolved]
2023-05-10 10:01:01 +02:00

119 lines
2.5 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.
#
# 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.
#
# Takes a list of @YankInstance as argument.
#
# Returns:
# - Nothing on success
# - @DeviceNotFound error, if any of the YankInstances doesn't exist
#
# 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.
#
# Returns: list of @YankInstance
#
# Example:
#
# -> { "execute": "query-yank" }
# <- { "return": [
# { "type": "block-node",
# "node-name": "nbd0" }
# ] }
#
# Since: 6.0
##
{ 'command': 'query-yank',
'returns': ['YankInstance'],
'allow-oob': true }