[Qemu-devel] Review of ways to reopen BDSes (was: Review of monitor commands identifying BDS / BB by name)

[Markus Armbruster <armbru@redhat.com>]

= Introduction =

Kevin asked for all the ways you can reopen BDSes with different options
or flags.  This memo only covers all the ways you can reopen, but it
doesn't attempt to fully analyze how options or flags change in each
case.

This is a systematic review of all the ways you can reopen BDSes in qemu
proper, i.e. not in qemu-{img,io,nbd}.  I tracked them down by following
the call chains leading to bdrv_reopen_multiple().


= QMP commands =

* block-commit

  Two separate code paths, depending on whether we're it's an active
  layer commit or not.

  - If active, we reopen the base with the root's flags.  If we fail
    later during start, we try to restore the flags by reopening again.
    In theory, restoring can fail, and then we mess up the flags.
    Avoiding that would be nice.

    The actual commit is done by code shared with drive-mirror, covered
    below.

  - Else, we reopen both the base and the overlay read/write.  The
    overlay is the BDS that has the top as backing file.  If we fail
    later during start, we don't attempt to undo a change to read/write,
    as far as I can tell.  Looks like a bug.

    On completion, we do attempt to undo, by reopening them again with
    their original flags.

* blockdev-snapshot-sync

  Creating an external snapshot of a node means splicing in a new
  snapshot BDS with the node as backing file.  We then try to reopen the
  node readonly, because it's now a backing file.  Failure is ignored,
  i.e. the node simply remains as writable as before.

* change-backing-file

  This updates the backing file in the image.  If the BDS is read-only,
  we reopen read/write before, and reopen read-only after.  If the first
  reopen fails, the command fails without doing anything.  If the update
  fails, we try the second reopen before failing the command with the
  failed update's error.  If the second reopen fails (unlikely), the
  command fails in an ugly way: the BDS is left writable.  Avoiding that
  would be nice.

* drive-mirror

  On successful completion, we do some BDS rewiring I don't fully
  understand.  The mirror target BDS gets swapped into another BDS.  If
  the two have different flags, we reopen the target to make them the
  same before we swap.  An explanation of what happens here is welcome.

* transaction

  This is a wrapper around a list of transaction-capable commands.
  Thus, nothing new here.


= Other user interfaces =

* HMP command commit

  Less capable cousin of QMP command block-commit.  Should be
  implemented on top of QMP, but isn't.  Instead, we a separate,
  specialized duplicate of the general commit code: bdrv_commit().

* Console escape key 's'

  Like HMP command "commit all".  See mux_proc_byte().

  Public service announcement: don't name your block backends "all".

* HMP command drive_mirror

  Implemented on top of QMP, so nothing new here.


= Generic block layer =

bdrv_reopen_queue() collects BDSes for atomic reopen,
bdrv_reopen_multiple() actually does it, in two stages,
bdrv_reopen_prepare() and bdrv_reopen_commit() / bdrv_reopen_abort().
All three call block driver methods with the same name.

bdrv_reopen() is a convenience wrapper for reopening a single BDS.


= Block driver methods =

Only one of them recurses:

* vmdk_reopen_prepare()

  Queues the extents.  Necessary, because the block driver hides them
  from the generic block layer.  Needs work, see also "Review of ways to
  create BDSes".