docs/devel/writing-monitor-commands.rst

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.
29 1. Define the command and any types it needs in the appropriate QAPI
32 2. Write the QMP command itself, which is a regular C function. Preferably,
33    the command should be exported by some QEMU subsystem. But it can also be
36 3. At this point the command can be tested under the QMP protocol
38 4. Write the HMP command equivalent. This is not required and should only be
39    done if it does make sense to have the functionality in HMP. The HMP command
40    is implemented in terms of the QMP command
81 actually in capabilities negotiation mode. To enter in command mode type::
92 Which is QMP's way of saying "the latest command executed OK and didn't return
97 Writing a simple command: hello-world
100 That's the most simple QMP command that can be written. Usually, this kind of
101 command carries some meaningful action in QEMU but here it will just print
104 Our command will be called "hello-world". It takes no arguments, nor does it
107 The first step is defining the command in the appropriate QAPI schema
116  { 'command': 'hello-world' }
118 The "command" keyword defines a new QMP command. It instructs QAPI to
134 1. QMP command implementation functions must be prefixed with "qmp\_"
136    command doesn't return any data
139    be touched if the command doesn't return errors
142    because it's the easiest way to demonstrate a QMP command
145 and then type the following QMP command::
156 Let's add arguments to our "hello-world" command.
158 The first change we have to do is to modify the command specification in the
170  { 'command': 'hello-world',
203 Time to test our new version of the "hello-world" command. Build QEMU, run it as
229 it does contain it, we want the "hello-world" command to return an error::
249 section, and then issue the following command::
275 Implementing the HMP command
278 Now that the QMP command is in place, we can also make it available in the human
284 Here's the implementation of the "hello-world" HMP command::
304    arguments entered by the user to the command implementation
313 There's one last step to actually make the command available to monitor users,
330 command. It might be instructive to check the command's documentation with
331 HMP's "help" command.
333 Please check the "-monitor" command-line option to know how to open a user
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,
353 command should never need to parse individual returned data fields. If
356 common case for any new QMP command that is intended to be used by
364 to have a command return a simple string that contains formatted data,
365 however, it is mandatory for the command to be marked unstable.
366 This indicates that the command is not guaranteed to be long term
369 command "x-query-registers". This returns a formatted dump of the
379 For this example we will write the query-option-roms command, which
381 more information about it, please check the "-option-rom" command-line
404 Now let's define the query-option-roms command::
415  { 'command': 'query-option-roms',
419 data returned by a command.
464 Time to test the new command. Build QEMU, run it as described in the "Testing"
477 The HMP command
480 Here's the HMP counterpart of the query-option-roms command::
541 The exception to this rule applies when the command is solely intended
543 a query command that report aspects of QEMU's internal state that are
546 In this example we will consider the existing QMP command
557  # @unstable: This command is meant for debugging.
563  { 'command': 'x-query-roms',
571 feature's documentation states why the command is unstable.  We
572 commonly use a ``x-`` command name prefix to make lack of stability
575 Implementing the QMP command
600 Implementing the HMP command
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
607 message. Here's an implementation of the "info roms" HMP command::
622 There's one last step to actually make the command available to
634 command is quite common. To simplify the implementation there is a general
636 a no-parameter QMP query command via HMP is to declare it using the
648 This is how the actual HMP command is done.