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

[Daniel P . Berrangé]

On Mon, Sep 20, 2021 at 10:06:35AM +0200, Markus Armbruster wrote:
> 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.

That's good with me. I'll just add the final sentance linking to the
later illustration for debugging aids.

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 :|