1How to write monitor commands
2=============================
3
4This document is a step-by-step guide on how to write new QMP commands using
5the QAPI framework and HMP commands.
6
7This document doesn't discuss QMP protocol level details, nor does it dive
8into the QAPI framework implementation.
9
10For an in-depth introduction to the QAPI framework, please refer to
11docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol,
12start with docs/interop/qmp-intro.txt.
13
14New commands may be implemented in QMP only.  New HMP commands should be
15implemented on top of QMP.  The typical HMP command wraps around an
16equivalent QMP command, but HMP convenience commands built from QMP
17building blocks are also fine.  The long term goal is to make all
18existing HMP commands conform to this, to fully isolate HMP from the
19internals of QEMU. Refer to the `Writing a debugging aid returning
20unstructured text`_ section for further guidance on commands that
21would have traditionally been HMP only.
22
23Overview
24--------
25
26Generally speaking, the following steps should be taken in order to write a
27new QMP command.
28
291. Define the command and any types it needs in the appropriate QAPI
30   schema module.
31
322. 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
34   added to the monitor/qmp-cmds.c file
35
363. At this point the command can be tested under the QMP protocol
37
384. 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
41
42The following sections will demonstrate each of the steps above. We will start
43very simple and get more complex as we progress.
44
45
46Testing
47-------
48
49For all the examples in the next sections, the test setup is the same and is
50shown here.
51
52First, QEMU should be started like this::
53
54 # qemu-system-TARGET [...] \
55     -chardev socket,id=qmp,port=4444,host=localhost,server=on \
56     -mon chardev=qmp,mode=control,pretty=on
57
58Then, in a different terminal::
59
60 $ telnet localhost 4444
61 Trying 127.0.0.1...
62 Connected to localhost.
63 Escape character is '^]'.
64 {
65     "QMP": {
66         "version": {
67             "qemu": {
68                 "micro": 50,
69                 "minor": 15,
70                 "major": 0
71             },
72             "package": ""
73         },
74         "capabilities": [
75         ]
76     }
77 }
78
79The above output is the QMP server saying you're connected. The server is
80actually in capabilities negotiation mode. To enter in command mode type::
81
82 { "execute": "qmp_capabilities" }
83
84Then the server should respond::
85
86 {
87     "return": {
88     }
89 }
90
91Which is QMP's way of saying "the latest command executed OK and didn't return
92any data". Now you're ready to enter the QMP example commands as explained in
93the following sections.
94
95
96Writing a simple command: hello-world
97-------------------------------------
98
99That's the most simple QMP command that can be written. Usually, this kind of
100command carries some meaningful action in QEMU but here it will just print
101"Hello, world" to the standard output.
102
103Our command will be called "hello-world". It takes no arguments, nor does it
104return any data.
105
106The first step is defining the command in the appropriate QAPI schema
107module.  We pick module qapi/misc.json, and add the following line at
108the bottom::
109
110 { 'command': 'hello-world' }
111
112The "command" keyword defines a new QMP command. It's an JSON object. All
113schema entries are JSON objects. The line above will instruct the QAPI to
114generate any prototypes and the necessary code to marshal and unmarshal
115protocol data.
116
117The next step is to write the "hello-world" implementation. As explained
118earlier, it's preferable for commands to live in QEMU subsystems. But
119"hello-world" doesn't pertain to any, so we put its implementation in
120monitor/qmp-cmds.c::
121
122 void qmp_hello_world(Error **errp)
123 {
124     printf("Hello, world!\n");
125 }
126
127There are a few things to be noticed:
128
1291. QMP command implementation functions must be prefixed with "qmp\_"
1302. qmp_hello_world() returns void, this is in accordance with the fact that the
131   command doesn't return any data
1323. It takes an "Error \*\*" argument. This is required. Later we will see how to
133   return errors and take additional arguments. The Error argument should not
134   be touched if the command doesn't return errors
1354. We won't add the function's prototype. That's automatically done by the QAPI
1365. Printing to the terminal is discouraged for QMP commands, we do it here
137   because it's the easiest way to demonstrate a QMP command
138
139You're done. Now build qemu, run it as suggested in the "Testing" section,
140and then type the following QMP command::
141
142 { "execute": "hello-world" }
143
144Then check the terminal running qemu and look for the "Hello, world" string. If
145you don't see it then something went wrong.
146
147
148Arguments
149~~~~~~~~~
150
151Let's add an argument called "message" to our "hello-world" command. The new
152argument will contain the string to be printed to stdout. It's an optional
153argument, if it's not present we print our default "Hello, World" string.
154
155The first change we have to do is to modify the command specification in the
156schema file to the following::
157
158 { 'command': 'hello-world', 'data': { '*message': 'str' } }
159
160Notice the new 'data' member in the schema. It's an JSON object whose each
161element is an argument to the command in question. Also notice the asterisk,
162it's used to mark the argument optional (that means that you shouldn't use it
163for mandatory arguments). Finally, 'str' is the argument's type, which
164stands for "string". The QAPI also supports integers, booleans, enumerations
165and user defined types.
166
167Now, let's update our C implementation in monitor/qmp-cmds.c::
168
169 void qmp_hello_world(bool has_message, const char *message, Error **errp)
170 {
171     if (has_message) {
172         printf("%s\n", message);
173     } else {
174         printf("Hello, world\n");
175     }
176 }
177
178There are two important details to be noticed:
179
1801. All optional arguments are accompanied by a 'has\_' boolean, which is set
181   if the optional argument is present or false otherwise
1822. The C implementation signature must follow the schema's argument ordering,
183   which is defined by the "data" member
184
185Time to test our new version of the "hello-world" command. Build qemu, run it as
186described in the "Testing" section and then send two commands::
187
188 { "execute": "hello-world" }
189 {
190     "return": {
191     }
192 }
193
194 { "execute": "hello-world", "arguments": { "message": "We love qemu" } }
195 {
196     "return": {
197     }
198 }
199
200You should see "Hello, world" and "We love qemu" in the terminal running qemu,
201if you don't see these strings, then something went wrong.
202
203
204Errors
205~~~~~~
206
207QMP commands should use the error interface exported by the error.h header
208file. Basically, most errors are set by calling the error_setg() function.
209
210Let's say we don't accept the string "message" to contain the word "love". If
211it does contain it, we want the "hello-world" command to return an error::
212
213 void qmp_hello_world(bool has_message, const char *message, Error **errp)
214 {
215     if (has_message) {
216         if (strstr(message, "love")) {
217             error_setg(errp, "the word 'love' is not allowed");
218             return;
219         }
220         printf("%s\n", message);
221     } else {
222         printf("Hello, world\n");
223     }
224 }
225
226The first argument to the error_setg() function is the Error pointer
227to pointer, which is passed to all QMP functions. The next argument is a human
228description of the error, this is a free-form printf-like string.
229
230Let's test the example above. Build qemu, run it as defined in the "Testing"
231section, and then issue the following command::
232
233 { "execute": "hello-world", "arguments": { "message": "all you need is love" } }
234
235The QMP server's response should be::
236
237 {
238     "error": {
239         "class": "GenericError",
240         "desc": "the word 'love' is not allowed"
241     }
242 }
243
244Note that error_setg() produces a "GenericError" class.  In general,
245all QMP errors should have that error class.  There are two exceptions
246to this rule:
247
248 1. To support a management application's need to recognize a specific
249    error for special handling
250
251 2. Backward compatibility
252
253If the failure you want to report falls into one of the two cases above,
254use error_set() with a second argument of an ErrorClass value.
255
256
257Command Documentation
258~~~~~~~~~~~~~~~~~~~~~
259
260There's only one step missing to make "hello-world"'s implementation complete,
261and that's its documentation in the schema file.
262
263There are many examples of such documentation in the schema file already, but
264here goes "hello-world"'s new entry for qapi/misc.json::
265
266 ##
267 # @hello-world:
268 #
269 # Print a client provided string to the standard output stream.
270 #
271 # @message: string to be printed
272 #
273 # Returns: Nothing on success.
274 #
275 # Notes: if @message is not provided, the "Hello, world" string will
276 #        be printed instead
277 #
278 # Since: <next qemu stable release, eg. 1.0>
279 ##
280 { 'command': 'hello-world', 'data': { '*message': 'str' } }
281
282Please, note that the "Returns" clause is optional if a command doesn't return
283any data nor any errors.
284
285
286Implementing the HMP command
287~~~~~~~~~~~~~~~~~~~~~~~~~~~~
288
289Now that the QMP command is in place, we can also make it available in the human
290monitor (HMP).
291
292With the introduction of the QAPI, HMP commands make QMP calls. Most of the
293time HMP commands are simple wrappers. All HMP commands implementation exist in
294the monitor/hmp-cmds.c file.
295
296Here's the implementation of the "hello-world" HMP command::
297
298 void hmp_hello_world(Monitor *mon, const QDict *qdict)
299 {
300     const char *message = qdict_get_try_str(qdict, "message");
301     Error *err = NULL;
302
303     qmp_hello_world(!!message, message, &err);
304     if (hmp_handle_error(mon, err)) {
305         return;
306     }
307 }
308
309Also, you have to add the function's prototype to the hmp.h file.
310
311There are three important points to be noticed:
312
3131. The "mon" and "qdict" arguments are mandatory for all HMP functions. The
314   former is the monitor object. The latter is how the monitor passes
315   arguments entered by the user to the command implementation
3162. hmp_hello_world() performs error checking. In this example we just call
317   hmp_handle_error() which prints a message to the user, but we could do
318   more, like taking different actions depending on the error
319   qmp_hello_world() returns
3203. The "err" variable must be initialized to NULL before performing the
321   QMP call
322
323There's one last step to actually make the command available to monitor users,
324we should add it to the hmp-commands.hx file::
325
326    {
327        .name       = "hello-world",
328        .args_type  = "message:s?",
329        .params     = "hello-world [message]",
330        .help       = "Print message to the standard output",
331        .cmd        = hmp_hello_world,
332    },
333
334 SRST
335 ``hello_world`` *message*
336   Print message to the standard output
337 ERST
338
339To test this you have to open a user monitor and issue the "hello-world"
340command. It might be instructive to check the command's documentation with
341HMP's "help" command.
342
343Please, check the "-monitor" command-line option to know how to open a user
344monitor.
345
346
347Writing more complex commands
348-----------------------------
349
350A QMP command is capable of returning any data the QAPI supports like integers,
351strings, booleans, enumerations and user defined types.
352
353In this section we will focus on user defined types. Please, check the QAPI
354documentation for information about the other types.
355
356
357Modelling data in QAPI
358~~~~~~~~~~~~~~~~~~~~~~
359
360For a QMP command that to be considered stable and supported long term,
361there is a requirement returned data should be explicitly modelled
362using fine-grained QAPI types. As a general guide, a caller of the QMP
363command should never need to parse individual returned data fields. If
364a field appears to need parsing, then it should be split into separate
365fields corresponding to each distinct data item. This should be the
366common case for any new QMP command that is intended to be used by
367machines, as opposed to exclusively human operators.
368
369Some QMP commands, however, are only intended as ad hoc debugging aids
370for human operators. While they may return large amounts of formatted
371data, it is not expected that machines will need to parse the result.
372The overhead of defining a fine grained QAPI type for the data may not
373be justified by the potential benefit. In such cases, it is permitted
374to have a command return a simple string that contains formatted data,
375however, it is mandatory for the command to use the 'x-' name prefix.
376This indicates that the command is not guaranteed to be long term
377stable / liable to change in future and is not following QAPI design
378best practices. An example where this approach is taken is the QMP
379command "x-query-registers". This returns a formatted dump of the
380architecture specific CPU state. The way the data is formatted varies
381across QEMU targets, is liable to change over time, and is only
382intended to be consumed as an opaque string by machines. Refer to the
383`Writing a debugging aid returning unstructured text`_ section for
384an illustration.
385
386User Defined Types
387~~~~~~~~~~~~~~~~~~
388
389FIXME This example needs to be redone after commit 6d32717
390
391For this example we will write the query-alarm-clock command, which returns
392information about QEMU's timer alarm. For more information about it, please
393check the "-clock" command-line option.
394
395We want to return two pieces of information. The first one is the alarm clock's
396name. The second one is when the next alarm will fire. The former information is
397returned as a string, the latter is an integer in nanoseconds (which is not
398very useful in practice, as the timer has probably already fired when the
399information reaches the client).
400
401The best way to return that data is to create a new QAPI type, as shown below::
402
403 ##
404 # @QemuAlarmClock
405 #
406 # QEMU alarm clock information.
407 #
408 # @clock-name: The alarm clock method's name.
409 #
410 # @next-deadline: The time (in nanoseconds) the next alarm will fire.
411 #
412 # Since: 1.0
413 ##
414 { 'type': 'QemuAlarmClock',
415   'data': { 'clock-name': 'str', '*next-deadline': 'int' } }
416
417The "type" keyword defines a new QAPI type. Its "data" member contains the
418type's members. In this example our members are the "clock-name" and the
419"next-deadline" one, which is optional.
420
421Now let's define the query-alarm-clock command::
422
423 ##
424 # @query-alarm-clock
425 #
426 # Return information about QEMU's alarm clock.
427 #
428 # Returns a @QemuAlarmClock instance describing the alarm clock method
429 # being currently used by QEMU (this is usually set by the '-clock'
430 # command-line option).
431 #
432 # Since: 1.0
433 ##
434 { 'command': 'query-alarm-clock', 'returns': 'QemuAlarmClock' }
435
436Notice the "returns" keyword. As its name suggests, it's used to define the
437data returned by a command.
438
439It's time to implement the qmp_query_alarm_clock() function, you can put it
440in the qemu-timer.c file::
441
442 QemuAlarmClock *qmp_query_alarm_clock(Error **errp)
443 {
444     QemuAlarmClock *clock;
445     int64_t deadline;
446
447     clock = g_malloc0(sizeof(*clock));
448
449     deadline = qemu_next_alarm_deadline();
450     if (deadline > 0) {
451         clock->has_next_deadline = true;
452         clock->next_deadline = deadline;
453     }
454     clock->clock_name = g_strdup(alarm_timer->name);
455
456     return clock;
457 }
458
459There are a number of things to be noticed:
460
4611. The QemuAlarmClock type is automatically generated by the QAPI framework,
462   its members correspond to the type's specification in the schema file
4632. As specified in the schema file, the function returns a QemuAlarmClock
464   instance and takes no arguments (besides the "errp" one, which is mandatory
465   for all QMP functions)
4663. The "clock" variable (which will point to our QAPI type instance) is
467   allocated by the regular g_malloc0() function. Note that we chose to
468   initialize the memory to zero. This is recommended for all QAPI types, as
469   it helps avoiding bad surprises (specially with booleans)
4704. Remember that "next_deadline" is optional? All optional members have a
471   'has_TYPE_NAME' member that should be properly set by the implementation,
472   as shown above
4735. Even static strings, such as "alarm_timer->name", should be dynamically
474   allocated by the implementation. This is so because the QAPI also generates
475   a function to free its types and it cannot distinguish between dynamically
476   or statically allocated strings
4776. You have to include "qapi/qapi-commands-misc.h" in qemu-timer.c
478
479Time to test the new command. Build qemu, run it as described in the "Testing"
480section and try this::
481
482 { "execute": "query-alarm-clock" }
483 {
484     "return": {
485         "next-deadline": 2368219,
486         "clock-name": "dynticks"
487     }
488 }
489
490
491The HMP command
492~~~~~~~~~~~~~~~
493
494Here's the HMP counterpart of the query-alarm-clock command::
495
496 void hmp_info_alarm_clock(Monitor *mon)
497 {
498     QemuAlarmClock *clock;
499     Error *err = NULL;
500
501     clock = qmp_query_alarm_clock(&err);
502     if (hmp_handle_error(mon, err)) {
503         return;
504     }
505
506     monitor_printf(mon, "Alarm clock method in use: '%s'\n", clock->clock_name);
507     if (clock->has_next_deadline) {
508         monitor_printf(mon, "Next alarm will fire in %" PRId64 " nanoseconds\n",
509                        clock->next_deadline);
510     }
511
512    qapi_free_QemuAlarmClock(clock);
513 }
514
515It's important to notice that hmp_info_alarm_clock() calls
516qapi_free_QemuAlarmClock() to free the data returned by qmp_query_alarm_clock().
517For user defined types, the QAPI will generate a qapi_free_QAPI_TYPE_NAME()
518function and that's what you have to use to free the types you define and
519qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section).
520If the QMP call returns a string, then you should g_free() to free it.
521
522Also note that hmp_info_alarm_clock() performs error handling. That's not
523strictly required if you're sure the QMP function doesn't return errors, but
524it's good practice to always check for errors.
525
526Another important detail is that HMP's "info" commands don't go into the
527hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined
528in the monitor/misc.c file. The entry for the "info alarmclock" follows::
529
530    {
531        .name       = "alarmclock",
532        .args_type  = "",
533        .params     = "",
534        .help       = "show information about the alarm clock",
535        .cmd        = hmp_info_alarm_clock,
536    },
537
538To test this, run qemu and type "info alarmclock" in the user monitor.
539
540
541Returning Lists
542~~~~~~~~~~~~~~~
543
544For this example, we're going to return all available methods for the timer
545alarm, which is pretty much what the command-line option "-clock ?" does,
546except that we're also going to inform which method is in use.
547
548This first step is to define a new type::
549
550 ##
551 # @TimerAlarmMethod
552 #
553 # Timer alarm method information.
554 #
555 # @method-name: The method's name.
556 #
557 # @current: true if this alarm method is currently in use, false otherwise
558 #
559 # Since: 1.0
560 ##
561 { 'type': 'TimerAlarmMethod',
562   'data': { 'method-name': 'str', 'current': 'bool' } }
563
564The command will be called "query-alarm-methods", here is its schema
565specification::
566
567 ##
568 # @query-alarm-methods
569 #
570 # Returns information about available alarm methods.
571 #
572 # Returns: a list of @TimerAlarmMethod for each method
573 #
574 # Since: 1.0
575 ##
576 { 'command': 'query-alarm-methods', 'returns': ['TimerAlarmMethod'] }
577
578Notice the syntax for returning lists "'returns': ['TimerAlarmMethod']", this
579should be read as "returns a list of TimerAlarmMethod instances".
580
581The C implementation follows::
582
583 TimerAlarmMethodList *qmp_query_alarm_methods(Error **errp)
584 {
585     TimerAlarmMethodList *method_list = NULL;
586     const struct qemu_alarm_timer *p;
587     bool current = true;
588
589     for (p = alarm_timers; p->name; p++) {
590         TimerAlarmMethod *value = g_malloc0(*value);
591         value->method_name = g_strdup(p->name);
592         value->current = current;
593         QAPI_LIST_PREPEND(method_list, value);
594         current = false;
595     }
596
597     return method_list;
598 }
599
600The most important difference from the previous examples is the
601TimerAlarmMethodList type, which is automatically generated by the QAPI from
602the TimerAlarmMethod type.
603
604Each list node is represented by a TimerAlarmMethodList instance. We have to
605allocate it, and that's done inside the for loop: the "info" pointer points to
606an allocated node. We also have to allocate the node's contents, which is
607stored in its "value" member. In our example, the "value" member is a pointer
608to an TimerAlarmMethod instance.
609
610Notice that the "current" variable is used as "true" only in the first
611iteration of the loop. That's because the alarm timer method in use is the
612first element of the alarm_timers array. Also notice that QAPI lists are handled
613by hand and we return the head of the list.
614
615Now Build qemu, run it as explained in the "Testing" section and try our new
616command::
617
618 { "execute": "query-alarm-methods" }
619 {
620     "return": [
621         {
622             "current": false,
623             "method-name": "unix"
624         },
625         {
626             "current": true,
627             "method-name": "dynticks"
628         }
629     ]
630 }
631
632The HMP counterpart is a bit more complex than previous examples because it
633has to traverse the list, it's shown below for reference::
634
635 void hmp_info_alarm_methods(Monitor *mon)
636 {
637     TimerAlarmMethodList *method_list, *method;
638     Error *err = NULL;
639
640     method_list = qmp_query_alarm_methods(&err);
641     if (hmp_handle_error(mon, err)) {
642         return;
643     }
644
645     for (method = method_list; method; method = method->next) {
646         monitor_printf(mon, "%c %s\n", method->value->current ? '*' : ' ',
647                                        method->value->method_name);
648     }
649
650     qapi_free_TimerAlarmMethodList(method_list);
651 }
652
653Writing a debugging aid returning unstructured text
654---------------------------------------------------
655
656As discussed in section `Modelling data in QAPI`_, it is required that
657commands expecting machine usage be using fine-grained QAPI data types.
658The exception to this rule applies when the command is solely intended
659as a debugging aid and allows for returning unstructured text. This is
660commonly needed for query commands that report aspects of QEMU's
661internal state that are useful to human operators.
662
663In this example we will consider a simplified variant of the HMP
664command ``info roms``. Following the earlier rules, this command will
665need to live under the ``x-`` name prefix, so its QMP implementation
666will be called ``x-query-roms``. It will have no parameters and will
667return a single text string::
668
669 { 'struct': 'HumanReadableText',
670   'data': { 'human-readable-text': 'str' } }
671
672 { 'command': 'x-query-roms',
673   'returns': 'HumanReadableText' }
674
675The ``HumanReadableText`` struct is intended to be used for all
676commands, under the ``x-`` name prefix that are returning unstructured
677text targeted at humans. It should never be used for commands outside
678the ``x-`` name prefix, as those should be using structured QAPI types.
679
680Implementing the QMP command
681~~~~~~~~~~~~~~~~~~~~~~~~~~~~
682
683The QMP implementation will typically involve creating a ``GString``
684object and printing formatted data into it::
685
686 HumanReadableText *qmp_x_query_roms(Error **errp)
687 {
688     g_autoptr(GString) buf = g_string_new("");
689     Rom *rom;
690
691     QTAILQ_FOREACH(rom, &roms, next) {
692        g_string_append_printf("%s size=0x%06zx name=\"%s\"\n",
693                               memory_region_name(rom->mr),
694                               rom->romsize,
695                               rom->name);
696     }
697
698     return human_readable_text_from_str(buf);
699 }
700
701
702Implementing the HMP command
703~~~~~~~~~~~~~~~~~~~~~~~~~~~~
704
705Now that the QMP command is in place, we can also make it available in
706the human monitor (HMP) as shown in previous examples. The HMP
707implementations will all look fairly similar, as all they need do is
708invoke the QMP command and then print the resulting text or error
709message. Here's the implementation of the "info roms" HMP command::
710
711 void hmp_info_roms(Monitor *mon, const QDict *qdict)
712 {
713     Error err = NULL;
714     g_autoptr(HumanReadableText) info = qmp_x_query_roms(&err);
715
716     if (hmp_handle_error(mon, err)) {
717         return;
718     }
719     monitor_printf(mon, "%s", info->human_readable_text);
720 }
721
722Also, you have to add the function's prototype to the hmp.h file.
723
724There's one last step to actually make the command available to
725monitor users, we should add it to the hmp-commands-info.hx file::
726
727    {
728        .name       = "roms",
729        .args_type  = "",
730        .params     = "",
731        .help       = "show roms",
732        .cmd        = hmp_info_roms,
733    },
734
735The case of writing a HMP info handler that calls a no-parameter QMP query
736command is quite common. To simplify the implementation there is a general
737purpose HMP info handler for this scenario. All that is required to expose
738a no-parameter QMP query command via HMP is to declare it using the
739'.cmd_info_hrt' field to point to the QMP handler, and leave the '.cmd'
740field NULL::
741
742    {
743        .name         = "roms",
744        .args_type    = "",
745        .params       = "",
746        .help         = "show roms",
747        .cmd_info_hrt = qmp_x_query_roms,
748    },
749