[PATCH v2 0/3] qapi & doc: deprecate drive-backup

[PATCH v2 0/3] qapi & doc: deprecate drive-backup

[Vladimir Sementsov-Ogievskiy]

Hi all!

See 03 commit message for details. 01-02 are preparation docs update.

v2: add a lot of documentation changes

v1 was "[PATCH] qapi: deprecate drive-backup"
Supersedes: <20210423125900.3640-1-vsementsov@virtuozzo.com>

Vladimir Sementsov-Ogievskiy (3):
  docs/block-replication: use blockdev-backup
  docs/interop/bitmaps: use blockdev-backup
  qapi: deprecate drive-backup

 docs/block-replication.txt             |   4 +-
 docs/interop/bitmaps.rst               | 285 +++++++++++++++++++------
 docs/interop/live-block-operations.rst |  47 ++--
 docs/system/deprecated.rst             |  11 +
 qapi/block-core.json                   |   5 +-
 5 files changed, 263 insertions(+), 89 deletions(-)

-- 
2.29.2

[PATCH v2 1/3] docs/block-replication: use blockdev-backup

[Vladimir Sementsov-Ogievskiy]

We are going to deprecate drive-backup, so don't mention it here.
Moreover, blockdev-backup seems more correct in the context.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
---
 docs/block-replication.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/block-replication.txt b/docs/block-replication.txt
index 108e9166a8..59eb2b33b3 100644
--- a/docs/block-replication.txt
+++ b/docs/block-replication.txt
@@ -79,7 +79,7 @@ Primary |                 ||  Secondary disk <--------- hidden-disk 5 <---------
                           ||        |                         |
                           ||        |                         |
                           ||        '-------------------------'
-                          ||           drive-backup sync=none 6
+                          ||         blockdev-backup sync=none 6
 
 1) The disk on the primary is represented by a block device with two
 children, providing replication between a primary disk and the host that
@@ -101,7 +101,7 @@ should support bdrv_make_empty() and backing file.
 that is modified by the primary VM. It should also start as an empty disk,
 and the driver supports bdrv_make_empty() and backing file.
 
-6) The drive-backup job (sync=none) is run to allow hidden-disk to buffer
+6) The blockdev-backup job (sync=none) is run to allow hidden-disk to buffer
 any state that would otherwise be lost by the speculative write-through
 of the NBD server into the secondary disk. So before block replication,
 the primary disk and secondary disk should contain the same data.
-- 
2.29.2

Re: [PATCH v2 1/3] docs/block-replication: use blockdev-backup

[John Snow]

On 5/5/21 9:58 AM, Vladimir Sementsov-Ogievskiy wrote:
> We are going to deprecate drive-backup, so don't mention it here.
> Moreover, blockdev-backup seems more correct in the context.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

Reviewed-by: John Snow <jsnow@redhat.com>

> ---
>   docs/block-replication.txt | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/block-replication.txt b/docs/block-replication.txt
> index 108e9166a8..59eb2b33b3 100644
> --- a/docs/block-replication.txt
> +++ b/docs/block-replication.txt
> @@ -79,7 +79,7 @@ Primary |                 ||  Secondary disk <--------- hidden-disk 5 <---------
>                             ||        |                         |
>                             ||        |                         |
>                             ||        '-------------------------'
> -                          ||           drive-backup sync=none 6
> +                          ||         blockdev-backup sync=none 6
>   
>   1) The disk on the primary is represented by a block device with two
>   children, providing replication between a primary disk and the host that
> @@ -101,7 +101,7 @@ should support bdrv_make_empty() and backing file.
>   that is modified by the primary VM. It should also start as an empty disk,
>   and the driver supports bdrv_make_empty() and backing file.
>   
> -6) The drive-backup job (sync=none) is run to allow hidden-disk to buffer
> +6) The blockdev-backup job (sync=none) is run to allow hidden-disk to buffer
>   any state that would otherwise be lost by the speculative write-through
>   of the NBD server into the secondary disk. So before block replication,
>   the primary disk and secondary disk should contain the same data.
> 

[PATCH v2 2/3] docs/interop/bitmaps: use blockdev-backup

[Vladimir Sementsov-Ogievskiy]

We are going to deprecate drive-backup, so use modern interface here.
In examples where target image creation is shown, show blockdev-add as
well. If target creation omitted, omit blockdev-add as well.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
---
 docs/interop/bitmaps.rst | 285 +++++++++++++++++++++++++++++----------
 1 file changed, 215 insertions(+), 70 deletions(-)

diff --git a/docs/interop/bitmaps.rst b/docs/interop/bitmaps.rst
index 059ad67929..ef95090c81 100644
--- a/docs/interop/bitmaps.rst
+++ b/docs/interop/bitmaps.rst
@@ -539,12 +539,11 @@ other partial disk images on top of a base image to reconstruct a full backup
 from the point in time at which the incremental backup was issued.
 
 The "Push Model" here references the fact that QEMU is "pushing" the modified
-blocks out to a destination. We will be using the `drive-backup
-<qemu-qmp-ref.html#index-drive_002dbackup>`_ and `blockdev-backup
-<qemu-qmp-ref.html#index-blockdev_002dbackup>`_ QMP commands to create both
+blocks out to a destination. We will be using the  `blockdev-backup
+<qemu-qmp-ref.html#index-blockdev_002dbackup>`_ QMP command to create both
 full and incremental backups.
 
-Both of these commands are jobs, which have their own QMP API for querying and
+The command is a job, which has its own QMP API for querying and
 management documented in `Background jobs
 <qemu-qmp-ref.html#Background-jobs>`_.
 
@@ -557,6 +556,10 @@ create a new incremental backup chain attached to a drive.
 This example creates a new, full backup of "drive0" and accompanies it with a
 new, empty bitmap that records writes from this point in time forward.
 
+The target may be created with help of `blockdev-add
+<qemu-qmp-ref.html#index-blockdev_002dadd>`_ or `blockdev-create
+<qemu-qmp-ref.html#index-blockdev_002dcreate>`_ command.
+
 .. note:: Any new writes that happen after this command is issued, even while
           the backup job runs, will be written locally and not to the backup
           destination. These writes will be recorded in the bitmap
@@ -576,12 +579,11 @@ new, empty bitmap that records writes from this point in time forward.
              }
            },
            {
-             "type": "drive-backup",
+             "type": "blockdev-backup",
              "data": {
                "device": "drive0",
-               "target": "/path/to/drive0.full.qcow2",
-               "sync": "full",
-               "format": "qcow2"
+               "target": "target0",
+               "sync": "full"
              }
            }
          ]
@@ -664,12 +666,11 @@ use a transaction to reset the bitmap while making a new full backup:
            }
          },
          {
-           "type": "drive-backup",
+           "type": "blockdev-backup",
            "data": {
              "device": "drive0",
-             "target": "/path/to/drive0.new_full.qcow2",
-             "sync": "full",
-             "format": "qcow2"
+             "target": "target0",
+             "sync": "full"
            }
          }
        ]
@@ -728,19 +729,35 @@ Example: First Incremental Backup
        $ qemu-img create -f qcow2 drive0.inc0.qcow2 \
          -b drive0.full.qcow2 -F qcow2
 
+#. Add target block node:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.inc0.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Issue an incremental backup command:
 
    .. code-block:: QMP
 
     -> {
-         "execute": "drive-backup",
+         "execute": "blockdev-backup",
          "arguments": {
            "device": "drive0",
            "bitmap": "bitmap0",
-           "target": "drive0.inc0.qcow2",
-           "format": "qcow2",
-           "sync": "incremental",
-           "mode": "existing"
+           "target": "target0",
+           "sync": "incremental"
          }
        }
 
@@ -785,20 +802,36 @@ Example: Second Incremental Backup
        $ qemu-img create -f qcow2 drive0.inc1.qcow2 \
          -b drive0.inc0.qcow2 -F qcow2
 
+#. Add target block node:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.inc1.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Issue a new incremental backup command. The only difference here is that we
    have changed the target image below.
 
    .. code-block:: QMP
 
     -> {
-         "execute": "drive-backup",
+         "execute": "blockdev-backup",
          "arguments": {
            "device": "drive0",
            "bitmap": "bitmap0",
-           "target": "drive0.inc1.qcow2",
-           "format": "qcow2",
-           "sync": "incremental",
-           "mode": "existing"
+           "target": "target0",
+           "sync": "incremental"
          }
        }
 
@@ -866,20 +899,36 @@ image:
              file for you, but you lose control over format options like
              compatibility and preallocation presets.
 
+#. Add target block node:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.inc2.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Issue a new incremental backup command. Apart from the new destination
    image, there is no difference from the last two examples.
 
    .. code-block:: QMP
 
     -> {
-         "execute": "drive-backup",
+         "execute": "blockdev-backup",
          "arguments": {
            "device": "drive0",
            "bitmap": "bitmap0",
-           "target": "drive0.inc2.qcow2",
-           "format": "qcow2",
-           "sync": "incremental",
-           "mode": "existing"
+           "target": "target0",
+           "sync": "incremental"
          }
        }
 
@@ -930,6 +979,38 @@ point in time.
     $ qemu-img create -f qcow2 drive0.full.qcow2 64G
     $ qemu-img create -f qcow2 drive1.full.qcow2 64G
 
+#. Add target block nodes:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.full.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target1",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive1.full.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Create a full (anchor) backup for each drive, with accompanying bitmaps:
 
    .. code-block:: QMP
@@ -953,21 +1034,19 @@ point in time.
                }
              },
              {
-               "type": "drive-backup",
+               "type": "blockdev-backup",
                "data": {
                  "device": "drive0",
-                 "target": "/path/to/drive0.full.qcow2",
-                 "sync": "full",
-                 "format": "qcow2"
+                 "target": "target0",
+                 "sync": "full"
                }
              },
              {
-               "type": "drive-backup",
+               "type": "blockdev-backup",
                "data": {
                  "device": "drive1",
-                 "target": "/path/to/drive1.full.qcow2",
-                 "sync": "full",
-                 "format": "qcow2"
+                 "target": "target1",
+                 "sync": "full"
                }
              }
            ]
@@ -1016,6 +1095,38 @@ point in time.
      $ qemu-img create -f qcow2 drive1.inc0.qcow2 \
        -b drive1.full.qcow2 -F qcow2
 
+#. Add target block nodes:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.inc0.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target1",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive1.inc0.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Issue a multi-drive incremental push backup transaction:
 
    .. code-block:: QMP
@@ -1025,25 +1136,21 @@ point in time.
          "arguments": {
            "actions": [
              {
-               "type": "drive-backup",
+               "type": "blockev-backup",
                "data": {
                  "device": "drive0",
                  "bitmap": "bitmap0",
-                 "format": "qcow2",
-                 "mode": "existing",
                  "sync": "incremental",
-                 "target": "drive0.inc0.qcow2"
+                 "target": "target0"
                }
              },
              {
-               "type": "drive-backup",
+               "type": "blockdev-backup",
                "data": {
                  "device": "drive1",
                  "bitmap": "bitmap0",
-                 "format": "qcow2",
-                 "mode": "existing",
                  "sync": "incremental",
-                 "target": "drive1.inc0.qcow2"
+                 "target": "target1"
                }
              },
            ]
@@ -1119,19 +1226,35 @@ described above. This example demonstrates the single-job failure case:
        $ qemu-img create -f qcow2 drive0.inc0.qcow2 \
          -b drive0.full.qcow2 -F qcow2
 
+#. Add target block node:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.inc0.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Attempt to create an incremental backup via QMP:
 
    .. code-block:: QMP
 
     -> {
-         "execute": "drive-backup",
+         "execute": "blockdev-backup",
          "arguments": {
            "device": "drive0",
            "bitmap": "bitmap0",
-           "target": "drive0.inc0.qcow2",
-           "format": "qcow2",
-           "sync": "incremental",
-           "mode": "existing"
+           "target": "target0",
+           "sync": "incremental"
          }
        }
 
@@ -1164,6 +1287,19 @@ described above. This example demonstrates the single-job failure case:
          "event": "BLOCK_JOB_COMPLETED"
        }
 
+#. Remove target node:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-del",
+         "arguments": {
+           "node-name": "target0",
+         }
+       }
+
+    <- { "return": {} }
+
 #. Delete the failed image, and re-create it.
 
    .. code:: bash
@@ -1172,20 +1308,36 @@ described above. This example demonstrates the single-job failure case:
        $ qemu-img create -f qcow2 drive0.inc0.qcow2 \
          -b drive0.full.qcow2 -F qcow2
 
+#. Add target block node:
+
+   .. code-block:: QMP
+
+    -> {
+         "execute": "blockdev-add",
+         "arguments": {
+           "node-name": "target0",
+           "driver": "qcow2",
+           "file": {
+             "driver": "file",
+             "filename": "drive0.inc0.qcow2"
+           }
+         }
+       }
+
+    <- { "return": {} }
+
 #. Retry the command after fixing the underlying problem, such as
    freeing up space on the backup volume:
 
    .. code-block:: QMP
 
     -> {
-         "execute": "drive-backup",
+         "execute": "blockdev-backup",
          "arguments": {
            "device": "drive0",
            "bitmap": "bitmap0",
-           "target": "drive0.inc0.qcow2",
-           "format": "qcow2",
-           "sync": "incremental",
-           "mode": "existing"
+           "target": "target0",
+           "sync": "incremental"
          }
        }
 
@@ -1210,7 +1362,8 @@ described above. This example demonstrates the single-job failure case:
 Example: Partial Transactional Failures
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-QMP commands like `drive-backup <qemu-qmp-ref.html#index-drive_002dbackup>`_
+QMP commands like `blockdev-backup
+<qemu-qmp-ref.html#index-blockdev_002dbackup>`_
 conceptually only start a job, and so transactions containing these commands
 may succeed even if the job it created later fails. This might have surprising
 interactions with notions of how a "transaction" ought to behave.
@@ -1240,25 +1393,21 @@ and one succeeds:
          "arguments": {
            "actions": [
            {
-             "type": "drive-backup",
+             "type": "blockdev-backup",
              "data": {
                "device": "drive0",
                "bitmap": "bitmap0",
-               "format": "qcow2",
-               "mode": "existing",
                "sync": "incremental",
-               "target": "drive0.inc0.qcow2"
+               "target": "target0"
              }
            },
            {
-             "type": "drive-backup",
+             "type": "blockdev-backup",
              "data": {
                "device": "drive1",
                "bitmap": "bitmap0",
-               "format": "qcow2",
-               "mode": "existing",
                "sync": "incremental",
-               "target": "drive1.inc0.qcow2"
+               "target": "target1"
              }
            }]
          }
@@ -1375,25 +1524,21 @@ applied:
            },
            "actions": [
            {
-             "type": "drive-backup",
+             "type": "blockdev-backup",
              "data": {
                "device": "drive0",
                "bitmap": "bitmap0",
-               "format": "qcow2",
-               "mode": "existing",
                "sync": "incremental",
-               "target": "drive0.inc0.qcow2"
+               "target": "target0"
              }
            },
            {
-             "type": "drive-backup",
+             "type": "blockdev-backup",
              "data": {
                "device": "drive1",
                "bitmap": "bitmap0",
-               "format": "qcow2",
-               "mode": "existing",
                "sync": "incremental",
-               "target": "drive1.inc0.qcow2"
+               "target": "target1"
              }
            }]
          }
-- 
2.29.2

Re: [PATCH v2 2/3] docs/interop/bitmaps: use blockdev-backup

[Kashyap Chamarthy]

On Wed, May 05, 2021 at 04:58:02PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> We are going to deprecate drive-backup, so use modern interface here.
> In examples where target image creation is shown, show blockdev-add as
> well. If target creation omitted, omit blockdev-add as well.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> ---
>  docs/interop/bitmaps.rst | 285 +++++++++++++++++++++++++++++----------
>  1 file changed, 215 insertions(+), 70 deletions(-)

Looks fine to me.  I have a couple of nits below, perhaps whoever is
applying the patch can tweak them.  FWIW:

Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>    

> diff --git a/docs/interop/bitmaps.rst b/docs/interop/bitmaps.rst
> index 059ad67929..ef95090c81 100644
> --- a/docs/interop/bitmaps.rst
> +++ b/docs/interop/bitmaps.rst
> @@ -539,12 +539,11 @@ other partial disk images on top of a base image to reconstruct a full backup
>  from the point in time at which the incremental backup was issued.
>  
>  The "Push Model" here references the fact that QEMU is "pushing" the modified
> -blocks out to a destination. We will be using the `drive-backup
> -<qemu-qmp-ref.html#index-drive_002dbackup>`_ and `blockdev-backup
> -<qemu-qmp-ref.html#index-blockdev_002dbackup>`_ QMP commands to create both
> +blocks out to a destination. We will be using the  `blockdev-backup
> +<qemu-qmp-ref.html#index-blockdev_002dbackup>`_ QMP command to create both
>  full and incremental backups.
>  
> -Both of these commands are jobs, which have their own QMP API for querying and
> +The command is a job, which has its own QMP API for querying and

nit: s/job/background job/

>  management documented in `Background jobs
>  <qemu-qmp-ref.html#Background-jobs>`_.
>  
> @@ -557,6 +556,10 @@ create a new incremental backup chain attached to a drive.
>  This example creates a new, full backup of "drive0" and accompanies it with a
>  new, empty bitmap that records writes from this point in time forward.
>  
> +The target may be created with help of `blockdev-add

It is less ambiguous (at least to my eyes) to replace "may" with "can".

nit: s/with help of/with the help of/

> +<qemu-qmp-ref.html#index-blockdev_002dadd>`_ or `blockdev-create
> +<qemu-qmp-ref.html#index-blockdev_002dcreate>`_ command.
> +
>  .. note:: Any new writes that happen after this command is issued, even while
>            the backup job runs, will be written locally and not to the backup
>            destination. These writes will be recorded in the bitmap
  
[...]

-- 
/kashyap

Re: [PATCH v2 2/3] docs/interop/bitmaps: use blockdev-backup

[John Snow]

On 5/5/21 9:58 AM, Vladimir Sementsov-Ogievskiy wrote:
> We are going to deprecate drive-backup, so use modern interface here.
> In examples where target image creation is shown, show blockdev-add as
> well. If target creation omitted, omit blockdev-add as well.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

Seems good, thanks!


(aside: I really need to push forward with the QMP cross-references work 
...)

[PATCH v2 3/3] qapi: deprecate drive-backup

[Vladimir Sementsov-Ogievskiy]

Modern way is using blockdev-add + blockdev-backup, which provides a
lot more control on how target is opened.

As example of drive-backup problems consider the following:

User of drive-backup expects that target will be opened in the same
cache and aio mode as source. Corresponding logic is in
drive_backup_prepare(), where we take bs->open_flags of source.

It works rather bad if source was added by blockdev-add. Assume source
is qcow2 image. On blockdev-add we should specify aio and cache options
for file child of qcow2 node. What happens next:

drive_backup_prepare() looks at bs->open_flags of qcow2 source node.
But there no BDRV_O_NOCAHE neither BDRV_O_NATIVE_AIO: BDRV_O_NOCAHE is
places in bs->file->bs->open_flags, and BDRV_O_NATIVE_AIO is nowhere,
as file-posix parse options and simply set s->use_linux_aio.

The documentation is updated in a minimal way, so that drive-backup is
noted only as a deprecated command, and blockdev-backup used in most of
places.

Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
---

TODO: We also need to deprecate drive-backup transaction action..
But union members in QAPI doesn't support 'deprecated' feature. I tried
to dig a bit, but failed :/ Markus, could you please help with it? At
least by advice?

 docs/interop/live-block-operations.rst | 47 +++++++++++++++++---------
 docs/system/deprecated.rst             | 11 ++++++
 qapi/block-core.json                   |  5 ++-
 3 files changed, 46 insertions(+), 17 deletions(-)

diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst
index 1073b930dc..f71f79ae2a 100644
--- a/docs/interop/live-block-operations.rst
+++ b/docs/interop/live-block-operations.rst
@@ -116,8 +116,8 @@ QEMU block layer supports.
 (3) ``drive-mirror`` (and ``blockdev-mirror``): Synchronize a running
     disk to another image.
 
-(4) ``drive-backup`` (and ``blockdev-backup``): Point-in-time (live) copy
-    of a block device to a destination.
+(4) ``blockdev-backup`` (and deprecated ``drive-backup``): Point-in-time
+    (live) copy of a block device to a destination.
 
 
 .. _`Interacting with a QEMU instance`:
@@ -553,13 +553,14 @@ Currently, there are four different kinds:
 
 (3) ``none`` -- Synchronize only the new writes from this point on.
 
-    .. note:: In the case of ``drive-backup`` (or ``blockdev-backup``),
-              the behavior of ``none`` synchronization mode is different.
-              Normally, a ``backup`` job consists of two parts: Anything
-              that is overwritten by the guest is first copied out to
-              the backup, and in the background the whole image is
-              copied from start to end. With ``sync=none``, it's only
-              the first part.
+    .. note:: In the case of ``blockdev-backup`` (or deprecated
+              ``drive-backup``), the behavior of ``none``
+              synchronization mode is different.  Normally, a
+              ``backup`` job consists of two parts: Anything that is
+              overwritten by the guest is first copied out to the
+              backup, and in the background the whole image is copied
+              from start to end. With ``sync=none``, it's only the
+              first part.
 
 (4) ``incremental`` -- Synchronize content that is described by the
     dirty bitmap
@@ -924,19 +925,22 @@ Shutdown the guest, by issuing the ``quit`` QMP command::
     }
 
 
-Live disk backup --- ``drive-backup`` and ``blockdev-backup``
--------------------------------------------------------------
+Live disk backup --- ``blockdev-backup`` and deprecated``drive-backup``
+-----------------------------------------------------------------------
 
-The ``drive-backup`` (and its newer equivalent ``blockdev-backup``) allows
+The ``blockdev-backup`` (and deprecated ``drive-backup``) allows
 you to create a point-in-time snapshot.
 
-In this case, the point-in-time is when you *start* the ``drive-backup``
-(or its newer equivalent ``blockdev-backup``) command.
+In this case, the point-in-time is when you *start* the
+``blockdev-backup`` (or deprecated ``drive-backup``) command.
 
 
 QMP invocation for ``drive-backup``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Note that ``drive-backup`` command is deprecated since Qemu 6.1 and
+will be removed in future.
+
 Yet again, starting afresh with our example disk image chain::
 
     [A] <-- [B] <-- [C] <-- [D]
@@ -961,11 +965,22 @@ will be issued, indicating the live block device job operation has
 completed, and no further action is required.
 
 
+Moving from deprecated ``drive-backup`` to newer ``blockdev-backup``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``blockdev-backup`` differs in a way of specifying backup target.
+With ``blockdev-backup`` you can't specify filename as a target.
+Instead you use node-name of existing block node, which you may add
+by ``blockdev-add`` or ``blockdev-create`` commands. Correspondingly,
+``blockdev-backup`` doesn't have ``mode`` and  ``format`` arguments
+which don't apply to existing block node. See following sections for
+details and examples.
+
+
 Notes on ``blockdev-backup``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``blockdev-backup`` command is equivalent in functionality to
-``drive-backup``, except that it operates at node-level in a Block Driver
+The ``blockdev-backup`` operates at node-level in a Block Driver
 State (BDS) graph.
 
 E.g. the sequence of actions to create a point-in-time backup
diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index 80cae86252..676d72a1ed 100644
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -186,6 +186,17 @@ Use the more generic commands ``block-export-add`` and ``block-export-del``
 instead.  As part of this deprecation, where ``nbd-server-add`` used a
 single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
 
+``drive-backup`` (since 6.1)
+''''''''''''''''''''''''''''
+
+Use ``blockdev-backup`` in pair with ``blockdev-add`` instead.
+This change primarily separates the creation/opening process of the backup
+target with explicit, separate steps. ``blockdev-backup`` uses mostly the
+same arguments as ``drive-backup``, except the ``format`` and ``mode``
+options are removed in favor of using explicit ``blockdev-create`` and
+``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
+details.
+
 System accelerators
 -------------------
 
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 6d227924d0..8e2c6e1622 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1642,6 +1642,9 @@
 # The operation can be stopped before it has completed using the
 # block-job-cancel command.
 #
+# Features:
+# @deprecated: This command is deprecated. Use @blockdev-backup instead.
+#
 # Returns: - nothing on success
 #          - If @device is not a valid block device, GenericError
 #
@@ -1657,7 +1660,7 @@
 #
 ##
 { 'command': 'drive-backup', 'boxed': true,
-  'data': 'DriveBackup' }
+  'data': 'DriveBackup', 'features': ['deprecated'] }
 
 ##
 # @blockdev-backup:
-- 
2.29.2

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Kashyap Chamarthy]

On Wed, May 05, 2021 at 04:58:03PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> Modern way is using blockdev-add + blockdev-backup, which provides a
> lot more control on how target is opened.
> 
> As example of drive-backup problems consider the following:
> 
> User of drive-backup expects that target will be opened in the same
> cache and aio mode as source. Corresponding logic is in
> drive_backup_prepare(), where we take bs->open_flags of source.
> 
> It works rather bad if source was added by blockdev-add. Assume source
> is qcow2 image. On blockdev-add we should specify aio and cache options
> for file child of qcow2 node. What happens next:
> 
> drive_backup_prepare() looks at bs->open_flags of qcow2 source node.
> But there no BDRV_O_NOCAHE neither BDRV_O_NATIVE_AIO: BDRV_O_NOCAHE is
> places in bs->file->bs->open_flags, and BDRV_O_NATIVE_AIO is nowhere,
> as file-posix parse options and simply set s->use_linux_aio.
> 
> The documentation is updated in a minimal way, so that drive-backup is
> noted only as a deprecated command, and blockdev-backup used in most of
> places.
> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> ---
> 
> TODO: We also need to deprecate drive-backup transaction action..
> But union members in QAPI doesn't support 'deprecated' feature. I tried
> to dig a bit, but failed :/ Markus, could you please help with it? At
> least by advice?
> 
>  docs/interop/live-block-operations.rst | 47 +++++++++++++++++---------
>  docs/system/deprecated.rst             | 11 ++++++
>  qapi/block-core.json                   |  5 ++-

The core changes itself looks good; I have some minor nit-picks below,
hope that's not annoying. :-)

With those addressed:

    Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>    

>  3 files changed, 46 insertions(+), 17 deletions(-)
> 
> diff --git a/docs/interop/live-block-operations.rst b/docs/interop/live-block-operations.rst
> index 1073b930dc..f71f79ae2a 100644
> --- a/docs/interop/live-block-operations.rst
> +++ b/docs/interop/live-block-operations.rst
> @@ -116,8 +116,8 @@ QEMU block layer supports.
>  (3) ``drive-mirror`` (and ``blockdev-mirror``): Synchronize a running
>      disk to another image.
>  
> -(4) ``drive-backup`` (and ``blockdev-backup``): Point-in-time (live) copy
> -    of a block device to a destination.
> +(4) ``blockdev-backup`` (and deprecated ``drive-backup``): Point-in-time
> +    (live) copy of a block device to a destination.

nit: s/deprecated ``drive-backup``/the deprecated ``drive-backup``/  

>  
>  .. _`Interacting with a QEMU instance`:
> @@ -553,13 +553,14 @@ Currently, there are four different kinds:
>  
>  (3) ``none`` -- Synchronize only the new writes from this point on.
>  
> -    .. note:: In the case of ``drive-backup`` (or ``blockdev-backup``),
> -              the behavior of ``none`` synchronization mode is different.
> -              Normally, a ``backup`` job consists of two parts: Anything
> -              that is overwritten by the guest is first copied out to
> -              the backup, and in the background the whole image is
> -              copied from start to end. With ``sync=none``, it's only
> -              the first part.
> +    .. note:: In the case of ``blockdev-backup`` (or deprecated
> +              ``drive-backup``), the behavior of ``none``
> +              synchronization mode is different.  Normally, a
> +              ``backup`` job consists of two parts: Anything that is
> +              overwritten by the guest is first copied out to the
> +              backup, and in the background the whole image is copied
> +              from start to end. With ``sync=none``, it's only the
> +              first part.
>  
>  (4) ``incremental`` -- Synchronize content that is described by the
>      dirty bitmap
> @@ -924,19 +925,22 @@ Shutdown the guest, by issuing the ``quit`` QMP command::
>      }
>  
>  
> -Live disk backup --- ``drive-backup`` and ``blockdev-backup``
> --------------------------------------------------------------
> +Live disk backup --- ``blockdev-backup`` and deprecated``drive-backup``
> +-----------------------------------------------------------------------

Here too, missing the article "the": "the deprecated".

> -The ``drive-backup`` (and its newer equivalent ``blockdev-backup``) allows
> +The ``blockdev-backup`` (and deprecated ``drive-backup``) allows
>  you to create a point-in-time snapshot.
>  
> -In this case, the point-in-time is when you *start* the ``drive-backup``
> -(or its newer equivalent ``blockdev-backup``) command.
> +In this case, the point-in-time is when you *start* the
> +``blockdev-backup`` (or deprecated ``drive-backup``) command.
>  
>  
>  QMP invocation for ``drive-backup``
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> +Note that ``drive-backup`` command is deprecated since Qemu 6.1 and
> +will be removed in future.

nit: Let's consistently spell QEMU in all caps, please: s/Qemu/QEMU/

>  Yet again, starting afresh with our example disk image chain::
>  
>      [A] <-- [B] <-- [C] <-- [D]
> @@ -961,11 +965,22 @@ will be issued, indicating the live block device job operation has
>  completed, and no further action is required.
>  
>  
> +Moving from deprecated ``drive-backup`` to newer ``blockdev-backup``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

s/from/from the/

> +``blockdev-backup`` differs in a way of specifying backup target.

I might slightly rephrase it this way:

    ``blockdev-backup`` differs from ``drive-backup`` in how you specify
    the backup target.

> +With ``blockdev-backup`` you can't specify filename as a target.
> +Instead you use node-name of existing block node, which you may add

Can use literals also for node-name: s/node-name/``node-name``

> +by ``blockdev-add`` or ``blockdev-create`` commands. Correspondingly,
> +``blockdev-backup`` doesn't have ``mode`` and  ``format`` arguments
> +which don't apply to existing block node. See following sections for

s/to/to an/

> +details and examples.
> +
> +
>  Notes on ``blockdev-backup``
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -The ``blockdev-backup`` command is equivalent in functionality to
> -``drive-backup``, except that it operates at node-level in a Block Driver
> +The ``blockdev-backup`` operates at node-level in a Block Driver
>  State (BDS) graph.

s/``blockdev-backup``/``blockdev-backup`` command/

>  E.g. the sequence of actions to create a point-in-time backup
> diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> index 80cae86252..676d72a1ed 100644
> --- a/docs/system/deprecated.rst
> +++ b/docs/system/deprecated.rst
> @@ -186,6 +186,17 @@ Use the more generic commands ``block-export-add`` and ``block-export-del``
>  instead.  As part of this deprecation, where ``nbd-server-add`` used a
>  single ``bitmap``, the new ``block-export-add`` uses a list of ``bitmaps``.
>  
> +``drive-backup`` (since 6.1)
> +''''''''''''''''''''''''''''
> +
> +Use ``blockdev-backup`` in pair with ``blockdev-add`` instead.

nit: s/in pair/in combination/

> +This change primarily separates the creation/opening process of the backup
> +target with explicit, separate steps. ``blockdev-backup`` uses mostly the
> +same arguments as ``drive-backup``, except the ``format`` and ``mode``
> +options are removed in favor of using explicit ``blockdev-create`` and
> +``blockdev-add`` calls. See :doc:`/interop/live-block-operations` for
> +details.

The rest reads good to me.  Thanks for fixing this.  

[...] 

-- 
/kashyap

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[John Snow]

On 5/6/21 5:57 AM, Kashyap Chamarthy wrote:
> TODO: We also need to deprecate drive-backup transaction action..
> But union members in QAPI doesn't support 'deprecated' feature. I tried
> to dig a bit, but failed :/ Markus, could you please help with it? At
> least by advice?

Oho, I see.

OK, I'm not Markus, but I've been getting into lots of trouble in the 
QAPI generator lately, so let me see if I can help get you started...

https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/

Here's a quick hack that might expose that feature. I suppose we can 
discuss this with Markus and turn these into real patches if that's the 
direction we wanna head.

--js

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Vladimir Sementsov-Ogievskiy]

15.05.2021 01:38, John Snow wrote:
> On 5/6/21 5:57 AM, Kashyap Chamarthy wrote:
>> TODO: We also need to deprecate drive-backup transaction action..
>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>> to dig a bit, but failed :/ Markus, could you please help with it? At
>> least by advice?
> 
> Oho, I see.
> 
> OK, I'm not Markus, but I've been getting into lots of trouble in the QAPI generator lately, so let me see if I can help get you started...
> 
> https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/
> 
> Here's a quick hack that might expose that feature. I suppose we can discuss this with Markus and turn these into real patches if that's the direction we wanna head.
> 

Hi! Markus is silent.. Maybe, you'll send patches ? )


-- 
Best regards,
Vladimir

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[John Snow]

On 5/24/21 10:06 AM, Vladimir Sementsov-Ogievskiy wrote:
> 15.05.2021 01:38, John Snow wrote:
>> On 5/6/21 5:57 AM, Kashyap Chamarthy wrote:
>>> TODO: We also need to deprecate drive-backup transaction action..
>>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>>> to dig a bit, but failed :/ Markus, could you please help with it? At
>>> least by advice?
>>
>> Oho, I see.
>>
>> OK, I'm not Markus, but I've been getting into lots of trouble in the 
>> QAPI generator lately, so let me see if I can help get you started...
>>
>> https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/
>>
>> Here's a quick hack that might expose that feature. I suppose we can 
>> discuss this with Markus and turn these into real patches if that's 
>> the direction we wanna head.
>>
> 
> Hi! Markus is silent.. Maybe, you'll send patches ? )
> 
> 

He just went on PTO for 2 weeks :')

It's going to have to wait, I'm afraid ...

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Vladimir Sementsov-Ogievskiy]

24.05.2021 21:37, John Snow wrote:
> On 5/24/21 10:06 AM, Vladimir Sementsov-Ogievskiy wrote:
>> 15.05.2021 01:38, John Snow wrote:
>>> On 5/6/21 5:57 AM, Kashyap Chamarthy wrote:
>>>> TODO: We also need to deprecate drive-backup transaction action..
>>>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>>>> to dig a bit, but failed :/ Markus, could you please help with it? At
>>>> least by advice?
>>>
>>> Oho, I see.
>>>
>>> OK, I'm not Markus, but I've been getting into lots of trouble in the QAPI generator lately, so let me see if I can help get you started...
>>>
>>> https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/
>>>
>>> Here's a quick hack that might expose that feature. I suppose we can discuss this with Markus and turn these into real patches if that's the direction we wanna head.
>>>
>>
>> Hi! Markus is silent.. Maybe, you'll send patches ? )
>>
>>
> 
> He just went on PTO for 2 weeks :')
> 
> It's going to have to wait, I'm afraid ...
> 

Hi!

Any plans or updates? John, may be you just send your patches?


-- 
Best regards,
Vladimir

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:

> 24.05.2021 21:37, John Snow wrote:
>> On 5/24/21 10:06 AM, Vladimir Sementsov-Ogievskiy wrote:
>>> 15.05.2021 01:38, John Snow wrote:
>>>> On 5/6/21 5:57 AM, Kashyap Chamarthy wrote:
>>>>> TODO: We also need to deprecate drive-backup transaction action..
>>>>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>>>>> to dig a bit, but failed :/ Markus, could you please help with it? At
>>>>> least by advice?
>>>>
>>>> Oho, I see.
>>>>
>>>> OK, I'm not Markus, but I've been getting into lots of trouble in the QAPI generator lately, so let me see if I can help get you started...
>>>>
>>>> https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/
>>>>
>>>> Here's a quick hack that might expose that feature. I suppose we can discuss this with Markus and turn these into real patches if that's the direction we wanna head.
>>>>
>>>
>>> Hi! Markus is silent.. Maybe, you'll send patches ? )
>>>
>>>
>> He just went on PTO for 2 weeks :')
>> It's going to have to wait, I'm afraid ...
>> 
>
> Hi!
>
> Any plans or updates? John, may be you just send your patches?

Yes, please!

I intend to resume working on feature flags next week.

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:

[...]

> TODO: We also need to deprecate drive-backup transaction action..
> But union members in QAPI doesn't support 'deprecated' feature. I tried
> to dig a bit, but failed :/ Markus, could you please help with it? At
> least by advice?

There are two closely related things in play here: the union branch and
the corresponding enum value.

So far, the QAPI schema language doesn't support tacking feature flags
to either.

If an enum value is deprecated, any union branches corresponding to it
must also be deprecated (because their use requires using the deprecated
enum value).

The converse is not true, but I can't see a use for deprecating a union
branch without also deprecating the enum member.

I think we can implement feature flags just for enum members, then
document that 'deprecated' enum value implies corresponding union
branches are also deprecated.

I have unfinished patches implementing feature flags for enum members.

Since TransactionAction is a simple union, the corresponding enum is
implicit.  We can make it explicit by converting to a flat union.
Simple unions need to die anyway.

Does this make sense?

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Vladimir Sementsov-Ogievskiy]

08.06.2021 14:12, Markus Armbruster wrote:
> Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:
> 
> [...]
> 
>> TODO: We also need to deprecate drive-backup transaction action..
>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>> to dig a bit, but failed :/ Markus, could you please help with it? At
>> least by advice?
> 
> There are two closely related things in play here: the union branch and
> the corresponding enum value.
> 
> So far, the QAPI schema language doesn't support tacking feature flags
> to either.
> 
> If an enum value is deprecated, any union branches corresponding to it
> must also be deprecated (because their use requires using the deprecated
> enum value).
> 
> The converse is not true, but I can't see a use for deprecating a union
> branch without also deprecating the enum member.
> 
> I think we can implement feature flags just for enum members, then
> document that 'deprecated' enum value implies corresponding union
> branches are also deprecated.
> 
> I have unfinished patches implementing feature flags for enum members.
> 
> Since TransactionAction is a simple union, the corresponding enum is
> implicit.  We can make it explicit by converting to a flat union.
> Simple unions need to die anyway.


Does BlockStatsSpecific from qapi/block-core.json a correct example of flat union you mean? I can make patch to convert TransactionAction to be similar if that helps (discriminator field should be called "type", yes?).


> 
> Does this make sense?
> 

Yes if it helps)

Did you also look at John's https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/ ?

I hope you and John will send patches that you have, I'll help with reviewing (keep me in CC), and finally we'll get the feature.

-- 
Best regards,
Vladimir

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:

> 08.06.2021 14:12, Markus Armbruster wrote:
>> Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:
>> 
>> [...]
>> 
>>> TODO: We also need to deprecate drive-backup transaction action..
>>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>>> to dig a bit, but failed :/ Markus, could you please help with it? At
>>> least by advice?
>> 
>> There are two closely related things in play here: the union branch and
>> the corresponding enum value.
>> 
>> So far, the QAPI schema language doesn't support tacking feature flags
>> to either.
>> 
>> If an enum value is deprecated, any union branches corresponding to it
>> must also be deprecated (because their use requires using the deprecated
>> enum value).
>> 
>> The converse is not true, but I can't see a use for deprecating a union
>> branch without also deprecating the enum member.
>> 
>> I think we can implement feature flags just for enum members, then
>> document that 'deprecated' enum value implies corresponding union
>> branches are also deprecated.
>> 
>> I have unfinished patches implementing feature flags for enum members.
>> 
>> Since TransactionAction is a simple union, the corresponding enum is
>> implicit.  We can make it explicit by converting to a flat union.
>> Simple unions need to die anyway.
>
>
> Does BlockStatsSpecific from qapi/block-core.json a correct example of flat union you mean? I can make patch to convert TransactionAction to be similar if that helps (discriminator field should be called "type", yes?).

From docs/devel/qapi-code-gen.txt:

    A simple union can always be re-written as a flat union where the base
    class has a single member named 'type', and where each branch of the
    union has a struct with a single member named 'data'.  That is,

     { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }

    is identical on the wire to:

     { 'enum': 'Enum', 'data': ['one', 'two'] }
     { 'struct': 'Branch1', 'data': { 'data': 'str' } }
     { 'struct': 'Branch2', 'data': { 'data': 'int' } }
     { 'union': 'Flat', 'base': { 'type': 'Enum' }, 'discriminator': 'type',
       'data': { 'one': 'Branch1', 'two': 'Branch2' } }

The generated C isn't identical, but adjusting the code using it should
be straightforward.

>> Does this make sense?
>> 
>
> Yes if it helps)
>
> Did you also look at John's https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/ ?

Not yet.

> I hope you and John will send patches that you have, I'll help with reviewing (keep me in CC), and finally we'll get the feature.

Sounds like a plan.  I need to get my post-vacation e-mail pileup under
control first.

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Vladimir Sementsov-Ogievskiy]

09.06.2021 13:49, Markus Armbruster wrote:
> Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:
> 
>> 08.06.2021 14:12, Markus Armbruster wrote:
>>> Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:
>>>
>>> [...]
>>>
>>>> TODO: We also need to deprecate drive-backup transaction action..
>>>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>>>> to dig a bit, but failed :/ Markus, could you please help with it? At
>>>> least by advice?
>>>
>>> There are two closely related things in play here: the union branch and
>>> the corresponding enum value.
>>>
>>> So far, the QAPI schema language doesn't support tacking feature flags
>>> to either.
>>>
>>> If an enum value is deprecated, any union branches corresponding to it
>>> must also be deprecated (because their use requires using the deprecated
>>> enum value).
>>>
>>> The converse is not true, but I can't see a use for deprecating a union
>>> branch without also deprecating the enum member.
>>>
>>> I think we can implement feature flags just for enum members, then
>>> document that 'deprecated' enum value implies corresponding union
>>> branches are also deprecated.
>>>
>>> I have unfinished patches implementing feature flags for enum members.
>>>
>>> Since TransactionAction is a simple union, the corresponding enum is
>>> implicit.  We can make it explicit by converting to a flat union.
>>> Simple unions need to die anyway.
>>
>>
>> Does BlockStatsSpecific from qapi/block-core.json a correct example of flat union you mean? I can make patch to convert TransactionAction to be similar if that helps (discriminator field should be called "type", yes?).
> 
>  From docs/devel/qapi-code-gen.txt:
> 
>      A simple union can always be re-written as a flat union where the base
>      class has a single member named 'type', and where each branch of the
>      union has a struct with a single member named 'data'.  That is,
> 
>       { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
> 
>      is identical on the wire to:
> 
>       { 'enum': 'Enum', 'data': ['one', 'two'] }
>       { 'struct': 'Branch1', 'data': { 'data': 'str' } }
>       { 'struct': 'Branch2', 'data': { 'data': 'int' } }
>       { 'union': 'Flat', 'base': { 'type': 'Enum' }, 'discriminator': 'type',
>         'data': { 'one': 'Branch1', 'two': 'Branch2' } }
> 
> The generated C isn't identical, but adjusting the code using it should
> be straightforward.
> 
>>> Does this make sense?
>>>
>>
>> Yes if it helps)
>>
>> Did you also look at John's https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/ ?
> 
> Not yet.
> 
>> I hope you and John will send patches that you have, I'll help with reviewing (keep me in CC), and finally we'll get the feature.
> 
> Sounds like a plan.  I need to get my post-vacation e-mail pileup under
> control first.
> 

Hi!

Kindly remind in the case you forget :) Or may be I miss some patches?

-- 
Best regards,
Vladimir

Re: [PATCH v2 3/3] qapi: deprecate drive-backup

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:
>
>> 08.06.2021 14:12, Markus Armbruster wrote:
>>> Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com> writes:
>>> 
>>> [...]
>>> 
>>>> TODO: We also need to deprecate drive-backup transaction action..
>>>> But union members in QAPI doesn't support 'deprecated' feature. I tried
>>>> to dig a bit, but failed :/ Markus, could you please help with it? At
>>>> least by advice?
>>> 
>>> There are two closely related things in play here: the union branch and
>>> the corresponding enum value.
>>> 
>>> So far, the QAPI schema language doesn't support tacking feature flags
>>> to either.
>>> 
>>> If an enum value is deprecated, any union branches corresponding to it
>>> must also be deprecated (because their use requires using the deprecated
>>> enum value).
>>> 
>>> The converse is not true, but I can't see a use for deprecating a union
>>> branch without also deprecating the enum member.
>>> 
>>> I think we can implement feature flags just for enum members, then
>>> document that 'deprecated' enum value implies corresponding union
>>> branches are also deprecated.
>>> 
>>> I have unfinished patches implementing feature flags for enum members.
>>> 
>>> Since TransactionAction is a simple union, the corresponding enum is
>>> implicit.  We can make it explicit by converting to a flat union.
>>> Simple unions need to die anyway.
>>
>>
>> Does BlockStatsSpecific from qapi/block-core.json a correct example of flat union you mean? I can make patch to convert TransactionAction to be similar if that helps (discriminator field should be called "type", yes?).
>
> From docs/devel/qapi-code-gen.txt:
>
>     A simple union can always be re-written as a flat union where the base
>     class has a single member named 'type', and where each branch of the
>     union has a struct with a single member named 'data'.  That is,
>
>      { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } }
>
>     is identical on the wire to:
>
>      { 'enum': 'Enum', 'data': ['one', 'two'] }
>      { 'struct': 'Branch1', 'data': { 'data': 'str' } }
>      { 'struct': 'Branch2', 'data': { 'data': 'int' } }
>      { 'union': 'Flat', 'base': { 'type': 'Enum' }, 'discriminator': 'type',
>        'data': { 'one': 'Branch1', 'two': 'Branch2' } }
>
> The generated C isn't identical, but adjusting the code using it should
> be straightforward.
>
>>> Does this make sense?
>>> 
>>
>> Yes if it helps)
>>
>> Did you also look at John's https://gitlab.com/jsnow/qemu/-/commits/hack-deprecate-union-branches/ ?
>
> Not yet.
>
>> I hope you and John will send patches that you have, I'll help with reviewing (keep me in CC), and finally we'll get the feature.
>
> Sounds like a plan.  I need to get my post-vacation e-mail pileup under
> control first.

Just sent:

Subject: [PATCH RFC 0/5] Subject: [PATCH RFC 0/5] qapi: Add feature flags to enum members
Message-Id: <20210915192425.4104210-1-armbru@redhat.com>

Yes, I mangled the subject %-/