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: # @x-blockdev-change:
# #
# Dynamically reconfigure the block driver state graph. It can be # Dynamically reconfigure the block driver state graph.
# 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.
# #
# If @node is specified, it will be inserted under @parent. @child # Currently only supports adding and deleting quorum children. A
# may not be specified in this case. If both @parent and @child are # child will be added at the end of the list of children. Its
# specified but @node is not, @child will be detached from @parent. # 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. # @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: # Features:
# #
# @unstable: This command is experimental, and its API is not stable. # @unstable: This command is experimental.
# It does not support all kinds of operations, all kinds of
# children, nor all block drivers.
# #
# 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 # gaps in the child indices. This cannot be represented in the
# 'children' list of BlockdevOptionsQuorum, as returned by # 'children' list of BlockdevOptionsQuorum, as returned by
# .bdrv_refresh_filename(). # .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 # Since: 2.7
# #
# .. qmp-example:: # .. qmp-example::