# How to write monitor commands

This document is a step-by-step guide on how to write new QMP commands using the QAPI framework and HMP commands.

This document doesn’t discuss QMP protocol level details, nor does it dive into the QAPI framework implementation.

For an in-depth introduction to the QAPI framework, please refer to How to use the QAPI code generator. For the QMP protocol, see the QEMU Machine Protocol Specification.

New commands may be implemented in QMP only. New HMP commands should be implemented on top of QMP. The typical HMP command wraps around an equivalent QMP command, but HMP convenience commands built from QMP building blocks are also fine. The long term goal is to make all existing HMP commands conform to this, to fully isolate HMP from the internals of QEMU. Refer to the Writing a debugging aid returning unstructured text section for further guidance on commands that would have traditionally been HMP only.

## Overview

Generally speaking, the following steps should be taken in order to write a new QMP command.

1. Define the command and any types it needs in the appropriate QAPI schema module.

2. Write the QMP command itself, which is a regular C function. Preferably, the command should be exported by some QEMU subsystem. But it can also be added to the monitor/qmp-cmds.c file

3. At this point the command can be tested under the QMP protocol

4. Write the HMP command equivalent. This is not required and should only be done if it does make sense to have the functionality in HMP. The HMP command is implemented in terms of the QMP command

The following sections will demonstrate each of the steps above. We will start very simple and get more complex as we progress.

## Testing

For all the examples in the next sections, the test setup is the same and is shown here.

First, QEMU should be started like this:

    # qemu-system-TARGET [...] \
        -chardev socket,id=qmp,port=4444,host=localhost,server=on \
        -mon chardev=qmp,mode=control,pretty=on

Then, in a different terminal:

    $ telnet localhost 4444
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    {
        "QMP": {
            "version": {
                "qemu": {
                    "micro": 50,
                    "minor": 2,
                    "major": 8
                },
                "package": ...
            },
            "capabilities": [
                "oob"
            ]
        }
    }

The above output is the QMP server saying you’re connected. The server is actually in capabilities negotiation mode. To enter in command mode type:

    { "execute": "qmp_capabilities" }

Then the server should respond:

    {
        "return": {
        }
    }

Which is QMP’s way of saying “the latest command executed OK and didn’t return any data”. Now you’re ready to enter the QMP example commands as explained in the following sections.

## Writing a simple command: hello-world

That’s the most simple QMP command that can be written. Usually, this kind of command carries some meaningful action in QEMU but here it will just print “Hello, world” to the standard output.

Our command will be called “hello-world”. It takes no arguments, nor does it return any data.

The first step is defining the command in the appropriate QAPI schema module. We pick module qapi/misc.json, and add the following line at the bottom:

    ##
    # @hello-world:
    #
    # Since: 9.0
    ##
    { 'command': 'hello-world' }

The “command” keyword defines a new QMP command. It instructs QAPI to generate any prototypes and the necessary code to marshal and unmarshal protocol data.

The next step is to write the “hello-world” implementation. As explained earlier, it’s preferable for commands to live in QEMU subsystems. But “hello-world” doesn’t pertain to any, so we put its implementation in monitor/qmp-cmds.c:

    void qmp_hello_world(Error **errp)
    {
        printf("Hello, world!\n");
    }

There are a few things to be noticed:

1. QMP command implementation functions must be prefixed with “qmp_”

2. qmp_hello_world() returns void, this is in accordance with the fact that the command doesn’t return any data

3. It takes an “Error **” argument. This is required. Later we will see how to return errors and take additional arguments. The Error argument should not be touched if the command doesn’t return errors

4. We won’t add the function’s prototype. That’s automatically done by QAPI

5. Printing to the terminal is discouraged for QMP commands, we do it here because it’s the easiest way to demonstrate a QMP command

You’re done. Now build QEMU, run it as suggested in the “Testing” section, and then type the following QMP command:

    { "execute": "hello-world" }

Then check the terminal running QEMU and look for the “Hello, world” string. If you don’t see it then something went wrong.

### Arguments

Let’s add arguments to our “hello-world” command.

The first change we have to do is to modify the command specification in the schema file to the following:

    ##
    # @hello-world:
    #
    # @message: message to be printed (default: "Hello, world!")
    #
    # @times: how many times to print the message (default: 1)
    #
    # Since: 9.0
    ##
    { 'command': 'hello-world',
      'data': { '*message': 'str', '*times': 'int' } }

Notice the new ‘data’ member in the schema. It specifies an argument ‘message’ of QAPI type ‘str’, and an argument ‘times’ of QAPI type ‘int’. Also notice the asterisk, it’s used to mark the argument optional.

Now, let’s update our C implementation in monitor/qmp-cmds.c:

    void qmp_hello_world(const char *message, bool has_times, int64_t times,
                         Error **errp)
    {
        if (!message) {
            message = "Hello, world";
        }
        if (!has_times) {
            times = 1;
        }

        for (int i = 0; i < times; i++) {
            printf("%s\n", message);
        }
    }

There are two important details to be noticed:

1. Optional arguments other than pointers are accompanied by a ‘has_’ boolean, which is set if the optional argument is present or false otherwise

2. The C implementation signature must follow the schema’s argument ordering, which is defined by the “data” member

Time to test our new version of the “hello-world” command. Build QEMU, run it as described in the “Testing” section and then send two commands:

    { "execute": "hello-world" }
    {
        "return": {
        }
    }

    { "execute": "hello-world", "arguments": { "message": "We love QEMU" } }
    {
        "return": {
        }
    }

You should see “Hello, world” and “We love QEMU” in the terminal running QEMU, if you don’t see these strings, then something went wrong.

### Errors

QMP commands should use the error interface exported by the error.h header file. Basically, most errors are set by calling the error_setg() function.

Let’s say we don’t accept the string “message” to contain the word “love”. If it does contain it, we want the “hello-world” command to return an error:

    void qmp_hello_world(const char *message, Error **errp)
    {
        if (message) {
            if (strstr(message, "love")) {
                error_setg(errp, "the word 'love' is not allowed");
                return;
            }
            printf("%s\n", message);
        } else {
            printf("Hello, world\n");
        }
    }

The first argument to the error_setg() function is the Error pointer to pointer, which is passed to all QMP functions. The next argument is a human description of the error, this is a free-form printf-like string.

Let’s test the example above. Build QEMU, run it as defined in the “Testing” section, and then issue the following command:

    { "execute": "hello-world", "arguments": { "message": "all you need is love" } }

The QMP server’s response should be:

    {
        "error": {
            "class": "GenericError",
            "desc": "the word 'love' is not allowed"
        }
    }

Note that error_setg() produces a “GenericError” class. In general, all QMP errors should have that error class. There are two exceptions to this rule:

> 1. To support a management application’s need to recognize a specific error for special handling

> 2. Backward compatibility

If the failure you want to report falls into one of the two cases above, use error_set() with a second argument of an ErrorClass value.

### Implementing the HMP command

Now that the QMP command is in place, we can also make it available in the human monitor (HMP).

With the introduction of QAPI, HMP commands make QMP calls. Most of the time HMP commands are simple wrappers.

Here’s the implementation of the “hello-world” HMP command:

    void hmp_hello_world(Monitor *mon, const QDict *qdict)
    {
        const char *message = qdict_get_try_str(qdict, "message");
        Error *err = NULL;

        qmp_hello_world(!!message, message, &err);
        if (hmp_handle_error(mon, err)) {
            return;
        }
    }

Add it to monitor/hmp-cmds.c. Also, add its prototype to include/monitor/hmp.h.

There are four important points to be noticed:

1. The “mon” and “qdict” arguments are mandatory for all HMP functions. The former is the monitor object. The latter is how the monitor passes arguments entered by the user to the command implementation

2. We chose not to support the “times” argument in HMP

3. hmp_hello_world() performs error checking. In this example we just call hmp_handle_error() which prints a message to the user, but we could do more, like taking different actions depending on the error qmp_hello_world() returns

4. The “err” variable must be initialized to NULL before performing the QMP call

There’s one last step to actually make the command available to monitor users, we should add it to the hmp-commands.hx file:

       {
           .name       = "hello-world",
           .args_type  = "message:s?",
           .params     = "hello-world [message]",
           .help       = "Print message to the standard output",
           .cmd        = hmp_hello_world,
       },

    SRST
    ``hello_world`` *message*
      Print message to the standard output
    ERST

To test this you have to open a user monitor and issue the “hello-world” command. It might be instructive to check the command’s documentation with HMP’s “help” command.

Please check the “-monitor” command-line option to know how to open a user monitor.

## Writing more complex commands

A QMP command is capable of returning any data QAPI supports like integers, strings, booleans, enumerations and user defined types.

In this section we will focus on user defined types. Please check the QAPI documentation for information about the other types.

### Modelling data in QAPI

For a QMP command that to be considered stable and supported long term, there is a requirement returned data should be explicitly modelled using fine-grained QAPI types. As a general guide, a caller of the QMP command should never need to parse individual returned data fields. If a field appears to need parsing, then it should be split into separate fields corresponding to each distinct data item. This should be the common case for any new QMP command that is intended to be used by machines, as opposed to exclusively human operators.

Some QMP commands, however, are only intended as ad hoc debugging aids for human operators. While they may return large amounts of formatted data, it is not expected that machines will need to parse the result. The overhead of defining a fine grained QAPI type for the data may not be justified by the potential benefit. In such cases, it is permitted to have a command return a simple string that contains formatted data, however, it is mandatory for the command to be marked unstable. This indicates that the command is not guaranteed to be long term stable / liable to change in future and is not following QAPI design best practices. An example where this approach is taken is the QMP command “x-query-registers”. This returns a formatted dump of the architecture specific CPU state. The way the data is formatted varies across QEMU targets, is liable to change over time, and is only intended to be consumed as an opaque string by machines. Refer to the Writing a debugging aid returning unstructured text section for an illustration.

### User Defined Types

For this example we will write the query-option-roms command, which returns information about ROMs loaded into the option ROM space. For more information about it, please check the “-option-rom” command-line option.

For each option ROM, we want to return two pieces of information: the ROM image’s file name, and its bootindex, if any. We need to create a new QAPI type for that, as shown below:

    ##
    # @OptionRomInfo:
    #
    # @filename: option ROM image file name
    #
    # @bootindex: option ROM's bootindex
    #
    # Since: 9.0
    ##
    { 'struct': 'OptionRomInfo',
      'data': { 'filename': 'str', '*bootindex': 'int' } }

The “struct” keyword defines a new QAPI type. Its “data” member contains the type’s members. In this example our members are “filename” and “bootindex”. The latter is optional.

Now let’s define the query-option-roms command:

    ##
    # @query-option-roms:
    #
    # Query information on ROMs loaded into the option ROM space.
    #
    # Returns: OptionRomInfo
    #
    # Since: 9.0
    ##
    { 'command': 'query-option-roms',
      'returns': ['OptionRomInfo'] }

Notice the “returns” keyword. As its name suggests, it’s used to define the data returned by a command.

Notice the syntax [‘OptionRomInfo’]”. This should be read as “returns a list of OptionRomInfo”.

It’s time to implement the qmp_query_option_roms() function. Add to monitor/qmp-cmds.c:

    OptionRomInfoList *qmp_query_option_roms(Error **errp)
    {
        OptionRomInfoList *info_list = NULL;
        OptionRomInfoList **tailp = &info_list;
        OptionRomInfo *info;

        for (int i = 0; i < nb_option_roms; i++) {
            info = g_malloc0(sizeof(*info));
            info->filename = g_strdup(option_rom[i].name);
            info->has_bootindex = option_rom[i].bootindex >= 0;
            if (info->has_bootindex) {
                info->bootindex = option_rom[i].bootindex;
            }
            QAPI_LIST_APPEND(tailp, info);
        }

        return info_list;
    }

There are a number of things to be noticed:

1. Type OptionRomInfo is automatically generated by the QAPI framework, its members correspond to the type’s specification in the schema file

2. Type OptionRomInfoList is also generated. It’s a singly linked list.

3. As specified in the schema file, the function returns a OptionRomInfoList, and takes no arguments (besides the “errp” one, which is mandatory for all QMP functions)

4. The returned object is dynamically allocated

5. All strings are dynamically allocated. This is so because QAPI also generates a function to free its types and it cannot distinguish between dynamically or statically allocated strings

6. Remember that “bootindex” is optional? As a non-pointer optional member, it comes with a ‘has_bootindex’ member that needs to be set by the implementation, as shown above

Time to test the new command. Build QEMU, run it as described in the “Testing” section and try this:

    { "execute": "query-option-rom" }
    {
        "return": [
            {
                "filename": "kvmvapic.bin"
            }
        ]
    }

### The HMP command

Here’s the HMP counterpart of the query-option-roms command:

    void hmp_info_option_roms(Monitor *mon, const QDict *qdict)
    {
        Error *err = NULL;
        OptionRomInfoList *info_list, *tail;
        OptionRomInfo *info;

        info_list = qmp_query_option_roms(&err);
        if (hmp_handle_error(mon, err)) {
            return;
        }

        for (tail = info_list; tail; tail = tail->next) {
            info = tail->value;
            monitor_printf(mon, "%s", info->filename);
            if (info->has_bootindex) {
                monitor_printf(mon, " %" PRId64, info->bootindex);
            }
            monitor_printf(mon, "\n");
        }

        qapi_free_OptionRomInfoList(info_list);
    }

It’s important to notice that hmp_info_option_roms() calls qapi_free_OptionRomInfoList() to free the data returned by qmp_query_option_roms(). For user defined types, QAPI will generate a qapi_free_QAPI_TYPE_NAME() function, and that’s what you have to use to free the types you define and qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section). If the QMP function returns a string, then you should g_free() to free it.

Also note that hmp_info_option_roms() performs error handling. That’s not strictly required when you’re sure the QMP function doesn’t return errors; you could instead pass it &error_abort then.

Another important detail is that HMP’s “info” commands go into hmp-commands-info.hx, not hmp-commands.hx. The entry for the “info option-roms” follows:

        {
            .name       = "option-roms",
            .args_type  = "",
            .params     = "",
            .help       = "show roms",
            .cmd        = hmp_info_option_roms,
        },
    SRST
    ``info option-roms``
      Show the option ROMs.
    ERST

To test this, run QEMU and type “info option-roms” in the user monitor.

## Writing a debugging aid returning unstructured text

As discussed in section Modelling data in QAPI, it is required that commands expecting machine usage be using fine-grained QAPI data types. The exception to this rule applies when the command is solely intended as a debugging aid and allows for returning unstructured text, such as a query command that report aspects of QEMU’s internal state that are useful only to human operators.

In this example we will consider the existing QMP command `x-query-roms` in qapi/machine.json. It has no parameters and returns a `HumanReadableText`:

    ##
    # @x-query-roms:
    #
    # Query information on the registered ROMS
    #
    # Features:
    #
    # @unstable: This command is meant for debugging.
    #
    # Returns: registered ROMs
    #
    # Since: 6.2
    ##
    { 'command': 'x-query-roms',
      'returns': 'HumanReadableText',
      'features': [ 'unstable' ] }

The `HumanReadableText` struct is defined in qapi/common.json as a struct with a string member. It is intended to be used for all commands that are returning unstructured text targeted at humans. These should all have feature ‘unstable’. Note that the feature’s documentation states why the command is unstable. We commonly use a `x-` command name prefix to make lack of stability obvious to human users.

### Implementing the QMP command

The QMP implementation will typically involve creating a `GString` object and printing formatted data into it, like this:

    HumanReadableText *qmp_x_query_roms(Error **errp)
    {
        g_autoptr(GString) buf = g_string_new("");
        Rom *rom;

        QTAILQ_FOREACH(rom, &roms, next) {
           g_string_append_printf("%s size=0x%06zx name=\"%s\"\n",
                                  memory_region_name(rom->mr),
                                  rom->romsize,
                                  rom->name);
        }

        return human_readable_text_from_str(buf);
    }

The actual implementation emits more information. You can find it in hw/core/loader.c.

### Implementing the HMP command

Now that the QMP command is in place, we can also make it available in the human monitor (HMP) as shown in previous examples. The HMP implementations will all look fairly similar, as all they need do is invoke the QMP command and then print the resulting text or error message. Here’s an implementation of the “info roms” HMP command:

    void hmp_info_roms(Monitor *mon, const QDict *qdict)
    {
        Error err = NULL;
        g_autoptr(HumanReadableText) info = qmp_x_query_roms(&err);

        if (hmp_handle_error(mon, err)) {
            return;
        }
        monitor_puts(mon, info->human_readable_text);
    }

Also, you have to add the function’s prototype to the hmp.h file.

There’s one last step to actually make the command available to monitor users, we should add it to the hmp-commands-info.hx file:

    {
        .name       = "roms",
        .args_type  = "",
        .params     = "",
        .help       = "show roms",
        .cmd        = hmp_info_roms,
    },

The case of writing a HMP info handler that calls a no-parameter QMP query command is quite common. To simplify the implementation there is a general purpose HMP info handler for this scenario. All that is required to expose a no-parameter QMP query command via HMP is to declare it using the ‘.cmd_info_hrt’ field to point to the QMP handler, and leave the ‘.cmd’ field NULL:

    {
        .name         = "roms",
        .args_type    = "",
        .params       = "",
        .help         = "show roms",
        .cmd_info_hrt = qmp_x_query_roms,
    },

This is how the actual HMP command is done.