Re: Modern HMP

[Markus Armbruster <armbru@redhat.com>]

"Dr. David Alan Gilbert" <dave@treblig.org> writes:

> * Daniel P. Berrangé (berrange@redhat.com) wrote:
>> On Thu, Jan 22, 2026 at 12:47:47PM -0300, Fabiano Rosas wrote:
>> > One question I have is what exactly gets (eventually) removed from QEMU
>> > and what benefits we expect from it. Is it the entire "manual"
>> > interaction that's undesirable? Or just that to maintain HMP there is a
>> > certain amount of duplication? Or even the less-than-perfect
>> > readline/completion aspects?
>> 
>> Over time we've been gradually separating our human targetted code from
>> our machine targetted code, whether that's command line argument parsing,
>> or monitor parsing. Maintaining two ways todo the same thing is always
>> going to be a maint burden, and in QEMU it has been especially burdensome
>> as they were parallel impls in many cases, rather than one being exclusively
>> built on top of the other.
>> 
>> Even today we still get contributors sending patches which only impl
>> HMP code and not QMP code. Separating HMP fully from QMP so that it
>> was mandatory to create QMP first gets contributors going down the
>> right path, and should reduce the burden on maint.
>
> Having a separate HMP isn't a bad idea - but it does need some idea of
> how to make it easy for contributors to add stuff that's just for debug
> or for the dev.   For HMP the bar is very low; if it's useful to the
> dev, why not (unless it's copying something that's already in the QMP interface
> in a different way);  but although the x- stuff in theory lets
> you add something via QMP, in practice it's quite hard to get it through
> review without a lot of QMP design bikeshedding.

I think this description has become less accurate than it used to be :)

A long time ago, we started with "QMP is a stable, structured interface
for machines, HMP is a plain text interface for humans, and layered on
top of QMP."  Layered on top means HMP commands wrap around QMP
commands.  Ensures that QMP is obviously complete.  Without such a
layering, we'd have to verify completeness by inspection.  Impractical
given the size and complexity of the interfaces involved.

Trouble is there are things in HMP that make no sense in QMP.  For
instance, HMP command 'cpu' sets the monitor's default CPU, which
certain HMP commands use.  To wrap 'cpu' around a QMP command, we'd have
to drag the concept "default CPU" into QMP where it's not wanted.

So we retreated from "all", and permitted exceptions for commands that
make no sense in QMP.

We then found out the hard & expensive way that designing a QMP command
with its stable, structured interface is often a lot harder than
cobbling together an HMP command.  It's not just avoidable social
problems ("bikeshedding"); designing stable interfaces is just hard.
Sometimes the extra effort is worthwhile.  Sometimes it's not, e.g. when
all we really want is print something to aid a human with debugging.

So we retreated from "all" some more, and permitted exceptions for
commands meant exclusively for human use, typically debugging and
development aids.

This effectifely redefined the meaning of "complete": instead of "QMP
can do everything HMP can do and more", it's now "... except for certain
development and debugging aids and maybe other stuff".

To keep "maybe other stuff" under control, we required (and still
require) an *argument* for adding functionality just to HMP.

This turned out to be differently bothersome.  Having to review HMP
changes for QMP bypasses is bothersome, and bound to miss things at
least occasionally.  Having to ask for an argument is bothersome.
Constructing one is bothersome.

To reduce the bother, we retreated from another QMP ideal: the
structured interface.  Permit QMP commands to return just text when the
command is meant just for humans.  Such commands must be unstable.
Possible because we had retreated from "all of QMP is stable" meanwhile.

How does this work?  Instead of adding an HMP-only command, add a QMP
command that returns QAPI type HumanReadableText, and a trivial HMP
command that wraps around it.  Slightly more work, but no interface
design.

The QMP command addition is much more visible to the QAPI/QMP
maintainers than an HMP-only command would be.  This helps avoid missing
things.

We still want an argument why a structured interface isn't needed.  But
we can be much more lenient there: if it turns out to be needed, we can
just add it, and drop the unstructured interface.  Remember, it's
unstable.

Hope this helps.