Re: [RFC PATCH 5/9] qapi: Implement 'next-machine-phase' command

[Eric Blake]

On Thu, May 13, 2021 at 10:25:45AM +0200, Mirela Grujic wrote:
> This command will be used to control via QMP the advancing of machine
> through initialization phases. The feature is needed to enable the
> machine configuration via QMP.
> 
> The command triggers QEMU to advance the machine to the next init phase,
> i.e. to execute initialization steps required to enter the next phase.
> The command is used in combination with -preconfig command line option.
> 
> Note: advancing the machine to the final phase has the same effect as
> executing 'x-exit-preconfig' command.
> 
> Signed-off-by: Mirela Grujic <mirela.grujic@greensocs.com>
> ---
>  qapi/machine.json          | 24 ++++++++++++++++++++++++
>  include/sysemu/sysemu.h    |  3 +++
>  hw/core/machine-qmp-cmds.c | 12 ++++++++++++
>  softmmu/vl.c               |  3 +--
>  4 files changed, 40 insertions(+), 2 deletions(-)
> 
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 47bdbec817..968d67dd95 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1328,3 +1328,27 @@
>  ##
>  { 'command': 'query-machine-phase', 'returns': 'MachineInitPhaseStatus',
>               'allow-preconfig': true }
> +
> +##
> +# @next-machine-phase:
> +#
> +# Increment machine initialization phase
> +#
> +# Since: #FIXME

You can put 6.1 instead of #FIXME if that's what you're aiming for
(but then you may have to adjust it to 6.2 if it misses soft
freeze...)

> +#
> +# Returns: If successful, nothing

This sentence doesn't add much.

> +#
> +# Notes: This command will trigger QEMU to execute initialization steps
> +#        that are required to enter the next machine initialization phase.
> +#        If by incrementing the initialization phase the machine reaches
> +#        the final phase, the guest will start running immediately unless
> +#        the -S option is used. The command is available only if the
> +#        -preconfig command line option was passed.
> +#
> +# Example:
> +#
> +# -> { "execute": "next-machine-phase" }
> +# <- { "return": {} }

As an API, this command seems awkward.  How do I query what phase I'm
currently in?  How many times do I have to call it?  Do we anticipate
the number of times I need to call it to change in future qemu
releases?

Would it be better to require me to pass an enum parameter stating the
phase I intend to move into (and error out if that is not actually the
next phase), where the introspection of the enum tells me how many
times to use this command?  Should this command return a struct
containing "new-state":"enum-value" telling me what state I moved to
on success?


-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3266
Virtualization:  qemu.org | libvirt.org