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