[PATCH v4 14/16] qapi: deprecate "device" field of DEVICE_* events

[Daniel P. Berrangé]

On Mon, Feb 13, 2023 at 05:01:01PM +0300, Vladimir Sementsov-Ogievskiy wrote:
> The device field is redundant, because QOM path always include device
> ID when this ID exist.

The flipside to that view is that applications configuring QEMU are
specifying the device ID for -device (CLI) / device_add (QMP) and
not the QOM path. IOW, the device ID is the more interesting field
than QOM path, so feels like the wrong one to be dropping.

Is there any real benefit to dropping this ? 

> 
> Signed-off-by: Vladimir Sementsov-Ogievskiy <vsementsov at yandex-team.ru>
> ---
>  docs/about/deprecated.rst |  9 +++++++++
>  qapi/qdev.json            | 12 ++++++++++--
>  2 files changed, 19 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> index da2e6fe63d..b389934691 100644
> --- a/docs/about/deprecated.rst
> +++ b/docs/about/deprecated.rst
> @@ -171,6 +171,15 @@ accepted incorrect commands will return an error. Users should make sure that
>  all arguments passed to ``device_add`` are consistent with the documented
>  property types.
>  
> +QEMU Machine Protocol (QMP) events
> +----------------------------------
> +
> +``DEVICE_DELETED`` & ``DEVICE_UNPLUG_GUEST_ERROR`` field ``device`` (since 8.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +Devices that has ``ID`` always has QOM path `/machine/peripheral/ID`. So, the
> +``device`` field is redundant and deprecated. Use the ``path`` field instead.
> +
>  Host Architectures
>  ------------------
>  
> diff --git a/qapi/qdev.json b/qapi/qdev.json
> index 2708fb4e99..325ef554f9 100644
> --- a/qapi/qdev.json
> +++ b/qapi/qdev.json
> @@ -124,6 +124,9 @@
>  #
>  # @path: the device's QOM path
>  #
> +# Features:
> +# @deprecated: Member @device is deprecated as redundant. Use @path instead.
> +#
>  # Since: 1.5
>  #
>  # Example:
> @@ -135,7 +138,8 @@
>  #
>  ##
>  { 'event': 'DEVICE_DELETED',
> -  'data': { '*device': 'str', 'path': 'str' } }
> +  'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
> +            'path': 'str' } }
>  
>  ##
>  # @DEVICE_UNPLUG_GUEST_ERROR:
> @@ -146,6 +150,9 @@
>  #
>  # @path: the device's QOM path
>  #
> +# Features:
> +# @deprecated: Member @device is deprecated as redundant. Use @path instead.
> +#
>  # Since: 6.2
>  #
>  # Example:
> @@ -157,4 +164,5 @@
>  #
>  ##
>  { 'event': 'DEVICE_UNPLUG_GUEST_ERROR',
> -  'data': { '*device': 'str', 'path': 'str' } }
> +  'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
> +            'path': 'str' } }
> -- 
> 2.34.1
> 

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|