SYS-OSS/FRET-qemu
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

qapi/block-core: Improve x-blockdev-change documentation

Browse Source 
The description of feature @unstable is three paragraphs.  The second
and third became part of the description by accident in commit
9fb49daabfb (qapi: Mark unstable QMP parts with feature 'unstable').

The second paragraph describes a defect in terms of the
implementation.  Fine, but doesn't belong into user-facing
documentation.  Turn it into a TODO section.

Rewrite everything else for clarity and completeness.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250311131715.1296101-1-armbru@redhat.com>
Acked-by: Alberto Garcia <berto@igalia.com>
This commit is contained in:
Markus Armbruster 2025-03-11 14:17:15 +01:00
parent 0462a32b4f
commit cbb698a2ba
1 changed files with 12 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
qapi/block-core.json
View File

@ -5913,35 +5913,31 @@
##
# @x-blockdev-change:
#
# Dynamically reconfigure the block driver state graph. It can be
# used to add, remove, insert or replace a graph node. Currently only
# the Quorum driver implements this feature to add or remove its
# child. This is useful to fix a broken quorum child.
# Dynamically reconfigure the block driver state graph.
#
# If @node is specified, it will be inserted under @parent. @child
# may not be specified in this case. If both @parent and @child are
# specified but @node is not, @child will be detached from @parent.
# Currently only supports adding and deleting quorum children. A
# child will be added at the end of the list of children. Its
# contents *must* be consistent with the other childrens' contents.
# Deleting a child that is not last in the list of children is
# problematic, because it "renumbers" the children following it.
#
# @parent: the id or name of the parent node.
#
# @child: the name of a child under the given parent node.
# @child: the name of a child to be deleted. Mutually exclusive with
# @node.
#
# @node: the name of the node that will be added.
# @node: the name of the node to be added. Mutually exclusive with
# @child.
#
# Features:
#
# @unstable: This command is experimental, and its API is not stable.
# It does not support all kinds of operations, all kinds of
# children, nor all block drivers.
# @unstable: This command is experimental.
#
# FIXME Removing children from a quorum node means introducing
# TODO: Removing children from a quorum node means introducing
# gaps in the child indices. This cannot be represented in the
# 'children' list of BlockdevOptionsQuorum, as returned by
# .bdrv_refresh_filename().
#
# Warning: The data in a new quorum child MUST be consistent with
# that of the rest of the array.
#
# Since: 2.7
#
# .. qmp-example::