Re: [PATCH v2 05/53] docs/devel: document expectations for HMP commands in the future

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> We no longer wish to have commands implemented in HMP only. All commands
> should start with a QMP implementation and the HMP merely be a shim
> around this. To reduce the burden of implementing QMP commands where
> there is low expectation of machine usage, requirements for QAPI
> modelling are relaxed provided the command is under the "x-" name
> prefix.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  docs/devel/writing-monitor-commands.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst
> index 4cf51ab557..983130a793 100644
> --- a/docs/devel/writing-monitor-commands.rst
> +++ b/docs/devel/writing-monitor-commands.rst
> @@ -11,6 +11,16 @@ For an in-depth introduction to the QAPI framework, please refer to
>  docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol,
>  start with docs/interop/qmp-intro.txt.
>  
> +Historically QEMU has permitted new monitor commands to be implemented in HMP
> +only, QMP only, or both, depending on whether they needed to be accessible to
> +human operators, machines, or both. When both QMP and HMP are implemented it
> +is expected the HMP implementation is a shim around the QMP implementation.
> +Going forward, the expectation is that new commands are implemented in QMP
> +only, or both QMP and HMP. No further commands are to be added to HMP only.
> +The long term goal is that all HMP commands will be implemented in terms of
> +their QMP equivalent, enabling internals of QEMU to be fully isolated from

This feels a bit too tight.  Most HMP commands are going to wrap around
their equivalent QMP command.  However, high-level HMP commands built
from low-level QMP building blocks remain permissble.

> +the HMP implementation. Refer to the later topic on modelling data in QAPI

Suggest to use the exact section name for easy searching, or even
better, make it a link.

> +for further guidance on commands that would have traditionally been HMP only.
>  
>  Overview
>  --------

Discussing history is quite valuable in commit messages, but less so in
a "how to do stuff" document.  Consider cutting this down some.  What
about:

    New commands may be implemented in QMP only.  New HMP commands should be
    implemented on top of QMP.  The typical HMP command wraps around an
    equivalent QMP command, but HMP convenience commands built from QMP
    building blocks are also fine.  The long term goal is to make all
    existing HMP commands conform to this, to fully isolate HMP from the
    internals of QEMU.