| Message ID | 20171110221329.24176-4-mreitz@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On 11/10/2017 04:13 PM, Max Reitz wrote: > We have a clear replacement, so let's deprecate it. > > Signed-off-by: Max Reitz <mreitz@redhat.com> > --- > qapi/block-core.json | 4 ++-- > block.c | 4 ++++ > qemu-doc.texi | 7 +++++++ > qemu-options.hx | 4 ++-- > 4 files changed, 15 insertions(+), 4 deletions(-) Dan has more details on the proper documentation to tweak when declaring something deprecated. So this patch is incomplete, but what you have makes sense.
On Fri, Nov 10, 2017 at 04:21:05PM -0600, Eric Blake wrote: > On 11/10/2017 04:13 PM, Max Reitz wrote: > > We have a clear replacement, so let's deprecate it. > > > > Signed-off-by: Max Reitz <mreitz@redhat.com> > > --- > > qapi/block-core.json | 4 ++-- > > block.c | 4 ++++ > > qemu-doc.texi | 7 +++++++ > > qemu-options.hx | 4 ++-- > > 4 files changed, 15 insertions(+), 4 deletions(-) > > Dan has more details on the proper documentation to tweak when declaring > something deprecated. So this patch is incomplete, but what you have > makes sense. Its ok, Max has added to the relevant appendix in qemu-doc.texi Regards, Daniel
Max Reitz <mreitz@redhat.com> writes: > We have a clear replacement, so let's deprecate it. > > Signed-off-by: Max Reitz <mreitz@redhat.com> > --- > qapi/block-core.json | 4 ++-- > block.c | 4 ++++ > qemu-doc.texi | 7 +++++++ > qemu-options.hx | 4 ++-- > 4 files changed, 15 insertions(+), 4 deletions(-) > > diff --git a/qapi/block-core.json b/qapi/block-core.json > index 76bf50f813..dfe4d3650c 100644 > --- a/qapi/block-core.json > +++ b/qapi/block-core.json > @@ -1090,7 +1090,7 @@ > # @overlay: reference to the existing block device that will become > # the overlay of @node, as part of creating the snapshot. > # It must not have a current backing file (this can be > -# achieved by passing "backing": "" to blockdev-add). > +# achieved by passing "backing": null to blockdev-add). > # > # Since: 2.5 > ## > @@ -1238,7 +1238,7 @@ > # "node-name": "node1534", > # "file": { "driver": "file", > # "filename": "hd1.qcow2" }, > -# "backing": "" } } > +# "backing": null } } > # > # <- { "return": {} } > # > diff --git a/block.c b/block.c > index bc92ddd5a0..463c4de25b 100644 > --- a/block.c > +++ b/block.c > @@ -2559,6 +2559,10 @@ static BlockDriverState *bdrv_open_inherit(const char *filename, > /* See cautionary note on accessing @options above */ > backing = qdict_get_try_str(options, "backing"); > if (qdict_is_qnull(options, "backing") || (backing && *backing == '\0')) { > + if (backing) { > + warn_report("Use of \"backing\": \"\" is deprecated; " > + "use \"backing\": null instead"); > + } > flags |= BDRV_O_NO_BACKING; > qdict_del(options, "backing"); > } > diff --git a/qemu-doc.texi b/qemu-doc.texi > index 8c10956a66..8f57d9ad21 100644 > --- a/qemu-doc.texi > +++ b/qemu-doc.texi > @@ -2537,6 +2537,13 @@ or ``ivshmem-doorbell`` device types. > The ``spapr-pci-vfio-host-bridge'' device type is replaced by > the ``spapr-pci-host-bridge'' device type. > > +@section Block device options > + > +@subsection "backing": "" (since 2.12.0) > + > +In order to prevent QEMU from automatically opening an image's backing > +chain, use ``"backing": null'' instead. > + > @node License > @appendix License > > diff --git a/qemu-options.hx b/qemu-options.hx > index 3728e9b4dd..0ee1a04d00 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -731,8 +731,8 @@ Reference to or definition of the data source block driver node > > @item backing > Reference to or definition of the backing file block device (default is taken > -from the image file). It is allowed to pass an empty string here in order to > -disable the default backing file. > +from the image file). It is allowed to pass @code{null} here in order to disable > +the default backing file. > > @item lazy-refcounts > Whether to enable the lazy refcounts feature (on/off; default is taken from the Missed in commit c42e8742f, I guess. Reviewed-by: Markus Armbruster <armbru@redhat.com>
diff --git a/qapi/block-core.json b/qapi/block-core.json index 76bf50f813..dfe4d3650c 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1090,7 +1090,7 @@ # @overlay: reference to the existing block device that will become # the overlay of @node, as part of creating the snapshot. # It must not have a current backing file (this can be -# achieved by passing "backing": "" to blockdev-add). +# achieved by passing "backing": null to blockdev-add). # # Since: 2.5 ## @@ -1238,7 +1238,7 @@ # "node-name": "node1534", # "file": { "driver": "file", # "filename": "hd1.qcow2" }, -# "backing": "" } } +# "backing": null } } # # <- { "return": {} } # diff --git a/block.c b/block.c index bc92ddd5a0..463c4de25b 100644 --- a/block.c +++ b/block.c @@ -2559,6 +2559,10 @@ static BlockDriverState *bdrv_open_inherit(const char *filename, /* See cautionary note on accessing @options above */ backing = qdict_get_try_str(options, "backing"); if (qdict_is_qnull(options, "backing") || (backing && *backing == '\0')) { + if (backing) { + warn_report("Use of \"backing\": \"\" is deprecated; " + "use \"backing\": null instead"); + } flags |= BDRV_O_NO_BACKING; qdict_del(options, "backing"); } diff --git a/qemu-doc.texi b/qemu-doc.texi index 8c10956a66..8f57d9ad21 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -2537,6 +2537,13 @@ or ``ivshmem-doorbell`` device types. The ``spapr-pci-vfio-host-bridge'' device type is replaced by the ``spapr-pci-host-bridge'' device type. +@section Block device options + +@subsection "backing": "" (since 2.12.0) + +In order to prevent QEMU from automatically opening an image's backing +chain, use ``"backing": null'' instead. + @node License @appendix License diff --git a/qemu-options.hx b/qemu-options.hx index 3728e9b4dd..0ee1a04d00 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -731,8 +731,8 @@ Reference to or definition of the data source block driver node @item backing Reference to or definition of the backing file block device (default is taken -from the image file). It is allowed to pass an empty string here in order to -disable the default backing file. +from the image file). It is allowed to pass @code{null} here in order to disable +the default backing file. @item lazy-refcounts Whether to enable the lazy refcounts feature (on/off; default is taken from the
We have a clear replacement, so let's deprecate it. Signed-off-by: Max Reitz <mreitz@redhat.com> --- qapi/block-core.json | 4 ++-- block.c | 4 ++++ qemu-doc.texi | 7 +++++++ qemu-options.hx | 4 ++-- 4 files changed, 15 insertions(+), 4 deletions(-)