diff options
| author | Markus Armbruster <armbru@redhat.com> | 2025-03-11 14:17:15 +0100 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2025-03-14 07:29:06 +0100 |
| commit | cbb698a2ba568f9746dee00ed59c442787103674 (patch) | |
| tree | e45ce260472b18691313d71b503974569849b412 /qapi | |
| parent | 0462a32b4f63b2448b4a196381138afd50719dc4 (diff) | |
| download | qemu-cbb698a2ba568f9746dee00ed59c442787103674.zip qemu-cbb698a2ba568f9746dee00ed59c442787103674.tar.gz qemu-cbb698a2ba568f9746dee00ed59c442787103674.tar.bz2 | |
qapi/block-core: Improve x-blockdev-change documentation
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>
Diffstat (limited to 'qapi')
| -rw-r--r-- | qapi/block-core.json | 28 |
1 files changed, 12 insertions, 16 deletions
diff --git a/qapi/block-core.json b/qapi/block-core.json index ee6eccc..b193778 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -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:: |