docs/devel/writing-monitor-commands.rst

4 This document is a step-by-step guide on how to write new QMP commands using
17 building blocks are also fine.  The long term goal is to make all
32 2. Write the QMP command itself, which is a regular C function. Preferably,
38 4. Write the HMP command equivalent. This is not required and should only be
40    is implemented in terms of the QMP command
49 For all the examples in the next sections, the test setup is the same and is
63  Escape character is '^]'.
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
107 The first step is defining the command in the appropriate QAPI schema
122 The next step is to write the "hello-world" implementation. As explained
135 2. qmp_hello_world() returns void, this is in accordance with the fact that the
137 3. It takes an "Error \*\*" argument. This is required. Later we will see how to
141 5. Printing to the terminal is discouraged for QMP commands, we do it here
158 The first change we have to do is to modify the command specification in the
198    boolean, which is set if the optional argument is present or false
201    which is defined by the "data" member
235              error_setg(errp, "the word 'love' is not allowed");
244 The first argument to the error_setg() function is the Error pointer
245 to pointer, which is passed to all QMP functions. The next argument is a human
246 description of the error, this is a free-form printf-like string.
251  { "execute": "hello-world", "arguments": { "message": "all you need is love" } }
258          "desc": "the word 'love' is not allowed"
278 Now that the QMP command is in place, we can also make it available in the human
303    former is the monitor object. The latter is how the monitor passes
340 A QMP command is capable of returning any data QAPI supports like integers,
351 there is a requirement returned data should be explicitly modelled
356 common case for any new QMP command that is intended to be used by
361 data, it is not expected that machines will need to parse the result.
363 be justified by the potential benefit. In such cases, it is permitted
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
367 stable / liable to change in future and is not following QAPI design
368 best practices. An example where this approach is taken is the QMP
370 architecture specific CPU state. The way the data is formatted varies
371 across QEMU targets, is liable to change over time, and is only
402 "filename" and "bootindex". The latter is optional.
448 1. Type OptionRomInfo is automatically generated by the QAPI framework,
451 2. Type OptionRomInfoList is also generated.  It's a singly linked
455    which is mandatory for all QMP functions)
456 4. The returned object is dynamically allocated
457 5. All strings are dynamically allocated. This is so because QAPI also
460 6. Remember that "bootindex" is optional? As a non-pointer optional
517 Another important detail is that HMP's "info" commands go into
539 As discussed in section `Modelling data in QAPI`_, it is required that
541 The exception to this rule applies when the command is solely intended
557  # @unstable: This command is meant for debugging.
567 The ``HumanReadableText`` struct is defined in qapi/common.json as a
568 struct with a string member. It is intended to be used for all
571 feature's documentation states why the command is unstable.  We
603 Now that the QMP command is in place, we can also make it available in
605 implementations will all look fairly similar, as all they need do is
634 command is quite common. To simplify the implementation there is a general
635 purpose HMP info handler for this scenario. All that is required to expose
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.