Modern HMP (was: Call for GSoC internship project ideas)

[Markus Armbruster <armbru@redhat.com>]

Marc-André Lureau <marcandre.lureau@redhat.com> writes:

> Hi
>
> On Tue, Jan 6, 2026 at 1:47 AM Stefan Hajnoczi <stefanha@gmail.com> wrote:
>
>> Dear QEMU and KVM communities,
>> QEMU will apply for the Google Summer of Code internship
>> program again this year. Regular contributors can submit project
>> ideas that they'd like to mentor by replying to this email by
>> January 30th.

[...]

>> How to propose your idea
>> ------------------------------
>> Reply to this email with the following project idea template filled in:
>>
>
> Rather than replying to this mail, I sketched some ideas of things I have
> in mind on the wiki directly:

[...]

> https://wiki.qemu.org/Internships/ProjectIdeas/ModernHMP

[...]

Let's start the discussion with your nicely written Wiki page:

    === External HMP Implementation via QMP ===

    '''Summary:''' Implement a standalone HMP-compatible monitor as an
    external binary (Python or Rust) that communicates with QEMU
    exclusively through QMP, enabling future decoupling of the built-in
    HMP from QEMU core.

    QEMU provides two monitor interfaces:
    * '''QMP''' (QEMU Machine Protocol): A JSON-based machine-readable
      protocol for programmatic control
    * '''HMP''' (Human Monitor Protocol): A text-based interactive
      interface for human operators

    Currently, HMP is tightly integrated into QEMU, with commands
    defined in `hmp-commands.hx` and `hmp-commands-info.hx`. Most HMP
    commands already delegate to QMP internally (e.g., `hmp_quit()`
    calls `qmp_quit()`), but HMP parsing, formatting, and command
    dispatch are compiled into the QEMU binary.

Also line editing and completion.

Most HMP commands cleanly wrap around QMP command handlers such as
qmp_quit().  Wrapping them around QMP commands instead is a
straightforward problem.  I'm more concerned about HMP stuff that uses
other internal interfaces.  Replacing them may require new QMP
interfaces, or maybe a careful culling of inessential HMP features.
Known such stuff: completion does not wrap around QMP command handlers.
It is provided by the HMP core.

Risk: this can easily become the 10% that take the other 90% of the
time, or even the 5% that sink the project.

Risk: serious code duplication until we can get rid of built-in HMP.
Fine if the goal is to explore and learn by building a prototype, and we
simply throw away the prototype afterwards.

    This project aims to externalize HMP functionality, providing a
    standalone tool that offers the same user experience while
    communicating with QEMU purely through QMP.

Potential for a better editing experience, because our readline
reimplementation is lacking compared to the real thing.

    '''Add `CONFIG_HMP` build option''':
    * Create a new Meson configuration option to disable built-in HMP
    * Allow QEMU to be built without HMP
    * Facilitate testing of external HMP as a replacement

    '''Create an external HMP implementation''' in Python or Rust that:
    * Connects to QEMU via QMP socket
    * Parses HMP command syntax and translates to QMP calls
    * Formats QMP responses as human-readable HMP output
    * Supports command completion and help text

    '''Use `hmp-commands.hx` for code generation''':
    * Parse the existing `.hx` files to extract command definitions
    * Generate boilerplate code (command tables, argument parsing, help
      text)
    * Produce a report of implemented vs. unimplemented commands
    * Enable tracking of HMP/QMP parity

.hx is C source code with ReST snippets.  scripts/hxtool strips out the
ReST.  docs/sphinx/hxtool.py ignores the C source code, and processes
the ReST.  It works.  Not a fan.

If we succeed in replacing built-in HMP by an external one, and the
external one isn't written in C, then having C source code in .hx no
longer makes sense.  Parsing it will be wasted effort.  It may still
make sense initially.

    '''Identify and address QMP gaps''':
    * Audit all HMP commands for QMP equivalents

Also audit the HMP core.  Known problem: completion.

    * For critical missing commands, propose QAPI schema additions
    * Document commands that cannot be externalized
    * Provide patches or RFCs for missing QMP functionality

    '''Future Work''' (out of scope):

    * Seamless replacement of built-in HMP

    '''Links:'''
    * https://wiki.qemu.org/Documentation/QMP - QMP documentation
    * https://wiki.qemu.org/Features/QAPI - QAPI schema system
    * https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html - QMP
      reference
    * https://www.qemu.org/docs/master/system/monitor.html - HMP
      documentation

    '''Details:'''
    * Skill level: intermediate
    * Language: Python or Rust (student choice), with C for QMP gap
      patches
    
    * Mentor: Marc-André Lureau <marcandre.lureau@redhat.com> (elmarco
      on IRC)
    * Markus?

Makes sense.

    * Suggested by: Marc-André Lureau