docs/devel/writing-monitor-commands.rst

4 This document is a step-by-step guide on how to write new QMP commands using
7 This document doesn't discuss QMP protocol level details, nor does it dive
11 :doc:`qapi-code-gen`.  For the QMP protocol, see the
12 :doc:`/interop/qmp-spec`.
14 New commands may be implemented in QMP only.  New HMP commands should be
15 implemented on top of QMP.  The typical HMP command wraps around an
16 equivalent QMP command, but HMP convenience commands built from QMP
27 new QMP command.
32 2. Write the QMP command itself, which is a regular C function. Preferably,
34    added to the monitor/qmp-cmds.c file
36 3. At this point the command can be tested under the QMP protocol
40    is implemented in terms of the QMP command
55      -chardev socket,id=qmp,port=4444,host=localhost,server=on \
56      -mon chardev=qmp,mode=control,pretty=on
65      "QMP": {
80 The above output is the QMP server saying you're connected. The server is
92 Which is QMP's way of saying "the latest command executed OK and didn't return
93 any data". Now you're ready to enter the QMP example commands as explained in
100 That's the most simple QMP command that can be written. Usually, this kind of
118 The "command" keyword defines a new QMP command. It instructs QAPI to
125 monitor/qmp-cmds.c::
134 1. QMP command implementation functions must be prefixed with "qmp\_"
141 5. Printing to the terminal is discouraged for QMP commands, we do it here
142    because it's the easiest way to demonstrate a QMP command
145 and then type the following QMP command::
178 Now, let's update our C implementation in monitor/qmp-cmds.c::
225 QMP commands should use the error interface exported by the error.h header
245 to pointer, which is passed to all QMP functions. The next argument is a human
253 The QMP server's response should be::
263 all QMP errors should have that error class.  There are two exceptions
278 Now that the QMP command is in place, we can also make it available in the human
281 With the introduction of QAPI, HMP commands make QMP calls. Most of the
311    QMP call
340 A QMP command is capable of returning any data QAPI supports like integers,
350 For a QMP command that to be considered stable and supported long term,
352 using fine-grained QAPI types. As a general guide, a caller of the QMP
356 common case for any new QMP command that is intended to be used by
359 Some QMP commands, however, are only intended as ad hoc debugging aids
368 best practices. An example where this approach is taken is the QMP
425 monitor/qmp-cmds.c::
455    which is mandatory for all QMP functions)
510 types (explained in the next section). If the QMP function returns a
514 not strictly required when you're sure the QMP function doesn't return
546 In this example we will consider the existing QMP command
575 Implementing the QMP command
578 The QMP implementation will typically involve creating a ``GString``
603 Now that the QMP command is in place, we can also make it available in
606 invoke the QMP command and then print the resulting text or error
633 The case of writing a HMP info handler that calls a no-parameter QMP query
636 a no-parameter QMP query command via HMP is to declare it using the
637 '.cmd_info_hrt' field to point to the QMP handler, and leave the '.cmd'