Re: [PATCH v3 3/5] qapi: add monitor-add, monitor-remove, query-monitors commands

["Daniel P. Berrangé" <berrange@redhat.com>]

On Tue, Apr 07, 2026 at 09:32:47AM +0200, Christian Brauner wrote:
> Add QMP commands for dynamic monitor lifecycle management:
> 
> - monitor-add: Create a QMP monitor on an existing chardev at runtime.
>   The chardev must exist and not already have a frontend attached
>   (enforced by qemu_chr_fe_init()).  The new monitor starts in
>   capability negotiation mode.
> 
> - monitor-remove: Remove a dynamically-added monitor.  CLI-created
>   monitors cannot be removed.  The removal sequence is:

Why should we block removal of statically created monitors ? Our
normal approach is that the creation of objects via the command
line & QMP be indistinguishable.


> diff --git a/qapi/control.json b/qapi/control.json
> index 9a5302193d..fd58b57c31 100644
> --- a/qapi/control.json
> +++ b/qapi/control.json
> @@ -211,3 +211,107 @@
>        '*pretty': 'bool',
>        'chardev': 'str'
>    } }
> +
> +##
> +# @monitor-add:
> +#
> +# Add a QMP monitor on an existing character device backend.
> +#
> +# The chardev must already exist (created via chardev-add or CLI).
> +# The monitor begins in capability negotiation mode -- the first
> +# client to connect receives the QMP greeting.
> +#
> +# @id: Monitor identifier, must be unique among monitors
> +#
> +# @chardev: Name of the character device backend to attach to
> +#
> +# @pretty: Enable pretty-printing of QMP responses (default: false)
> +#
> +# Errors:
> +#     - GenericError if @id is already in use
> +#     - GenericError if @chardev does not exist
> +#
> +# Since: 11.0

We're just about to release 11.0, so 11.1 is the earliest
opportunity to merge anything now.

> +#
> +# .. qmp-example::
> +#
> +#     -> { "execute": "monitor-add",
> +#          "arguments": { "id": "extra-qmp",
> +#                         "chardev": "qmp-extra" } }
> +#     <- { "return": {} }
> +##
> +{ 'command': 'monitor-add',
> +  'data': { 'id': 'str',
> +            'chardev': 'str',
> +            '*pretty': 'bool' } }
> +
> +##
> +# @monitor-remove:
> +#
> +# Remove a dynamically added QMP monitor.
> +#
> +# The monitor must have been created via monitor-add.  Monitors
> +# created via CLI options (-mon, -qmp) cannot be removed.  The
> +# underlying chardev is NOT removed -- use chardev-remove separately
> +# if desired.
> +#
> +# If a client is currently connected, the connection is dropped.
> +#
> +# @id: Monitor identifier as passed to monitor-add
> +#
> +# Errors:
> +#     - GenericError if @id does not exist
> +#     - GenericError if the monitor was not dynamically added

I don't think we need to include "GenericError" in the description.
We've abandoned the idea of error classes in general, so everything
is GenericError  except for a bit of historical cruft.

> +#
> +# Since: 11.0
> +#
> +# .. qmp-example::
> +#
> +#     -> { "execute": "monitor-remove",
> +#          "arguments": { "id": "extra-qmp" } }
> +#     <- { "return": {} }
> +##
> +{ 'command': 'monitor-remove',
> +  'data': { 'id': 'str' } }
> +
> +##
> +# @MonitorInfo:
> +#
> +# Information about a QMP/HMP monitor.
> +#
> +# @id: Monitor identifier (absent for CLI-created monitors without
> +#     an explicit id)

We can't make 'id' mandatory for the existing arg without breaking
compat, but IMHO we should allocate an auto-generated 'id' if the
user omits it.

> +#
> +# @mode: Monitor mode (readline or control)
> +#
> +# @chardev: Name of the attached character device
> +#
> +# @dynamic: true if created via monitor-add (removable), false if
> +#     created via CLI
> +#
> +# Since: 11.0
> +##
> +{ 'struct': 'MonitorInfo',
> +  'data': { '*id': 'str',
> +            'mode': 'MonitorMode',
> +            'chardev': 'str',
> +            'dynamic': 'bool' } }
> +
> +##
> +# @query-monitors:
> +#
> +# Return information about all active monitors.
> +#
> +# Returns: a list of @MonitorInfo for each active monitor
> +#
> +# Since: 11.0
> +#
> +# .. qmp-example::
> +#
> +#     -> { "execute": "query-monitors" }
> +#     <- { "return": [ { "id": "mon0", "mode": "control",
> +#                         "chardev": "compat_monitor0",
> +#                         "dynamic": false } ] }
> +##
> +{ 'command': 'query-monitors',
> +  'returns': ['MonitorInfo'] }

With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|