docs/devel/writing-monitor-commands.rst

4 This document is a step-by-step guide on how to write new QMP commands using
8 into the QAPI framework implementation.
10 For an in-depth introduction to the QAPI framework, please refer to
11 :doc:`qapi-code-gen`.  For the QMP protocol, see the
12 :doc:`/interop/qmp-spec`.
24 --------
34    added to the monitor/qmp-cmds.c file
47 -------
54  # qemu-system-TARGET [...] \
55      -chardev socket,id=qmp,port=4444,host=localhost,server=on \
56      -mon chardev=qmp,mode=control,pretty=on
97 Writing a simple command: hello-world
98 -------------------------------------
104 Our command will be called "hello-world". It takes no arguments, nor does it
112  # @hello-world:
116  { 'command': 'hello-world' }
122 The next step is to write the "hello-world" implementation. As explained
124 "hello-world" doesn't pertain to any, so we put its implementation in
125 monitor/qmp-cmds.c::
134 1. QMP command implementation functions must be prefixed with "qmp\_"
147  { "execute": "hello-world" }
156 Let's add arguments to our "hello-world" command.
162  # @hello-world:
170  { 'command': 'hello-world',
178 Now, let's update our C implementation in monitor/qmp-cmds.c::
200 2. The C implementation signature must follow the schema's argument ordering,
201    which is defined by the "data" member
203 Time to test our new version of the "hello-world" command. Build QEMU, run it as
206  { "execute": "hello-world" }
212  { "execute": "hello-world", "arguments": { "message": "We love QEMU" } }
229 it does contain it, we want the "hello-world" command to return an error::
246 description of the error, this is a free-form printf-like string.
248 Let's test the example above. Build QEMU, run it as defined in the "Testing"
251  { "execute": "hello-world", "arguments": { "message": "all you need is love" } }
284 Here's the implementation of the "hello-world" HMP command::
297 Add it to monitor/hmp-cmds.c.  Also, add its prototype to
304    arguments entered by the user to the command implementation
314 we should add it to the hmp-commands.hx file::
317         .name       = "hello-world",
319         .params     = "hello-world [message]",
329 To test this you have to open a user monitor and issue the "hello-world"
333 Please check the "-monitor" command-line option to know how to open a user
338 -----------------------------
341 strings, booleans, enumerations and user defined types.
343 In this section we will focus on user defined types. Please check the QAPI
352 using fine-grained QAPI types. As a general guide, a caller of the QMP
369 command "x-query-registers". This returns a formatted dump of the
376 User Defined Types
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::
407  # @query-option-roms:
415  { 'command': 'query-option-roms',
425 monitor/qmp-cmds.c::
435          info->filename = g_strdup(option_rom[i].name);
436          info->has_bootindex = option_rom[i].bootindex >= 0;
437          if (info->has_bootindex) {
438              info->bootindex = option_rom[i].bootindex;
460 6. Remember that "bootindex" is optional? As a non-pointer optional
462    by the implementation, as shown above
467  { "execute": "query-option-rom" }
480 Here's the HMP counterpart of the query-option-roms command::
493      for (tail = info_list; tail; tail = tail->next) {
494          info = tail->value;
495          monitor_printf(mon, "%s", info->filename);
496          if (info->has_bootindex) {
497              monitor_printf(mon, " %" PRId64, info->bootindex);
507 qmp_query_option_roms().  For user defined types, QAPI will generate a
518 hmp-commands-info.hx, not hmp-commands.hx. The entry for the "info
519 option-roms" follows::
522          .name       = "option-roms",
529  ``info option-roms``
533 To test this, run QEMU and type "info option-roms" in the user monitor.
537 ---------------------------------------------------
540 commands expecting machine usage be using fine-grained QAPI data types.
547 ``x-query-roms`` in qapi/machine.json.  It has no parameters and
551  # @x-query-roms:
563  { 'command': 'x-query-roms',
567 The ``HumanReadableText`` struct is defined in qapi/common.json as a
572 commonly use a ``x-`` command name prefix to make lack of stability
578 The QMP implementation will typically involve creating a ``GString``
588                                memory_region_name(rom->mr),
589                                rom->romsize,
590                                rom->name);
596 The actual implementation emits more information.  You can find it in
607 message. Here's an implementation of the "info roms" HMP command::
617      monitor_puts(mon, info->human_readable_text);
623 monitor users, we should add it to the hmp-commands-info.hx file::
633 The case of writing a HMP info handler that calls a no-parameter QMP query
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