1 = How to write QMP commands using the QAPI framework =
3 This document is a step-by-step guide on how to write new QMP commands using
4 the QAPI framework. It also shows how to implement new style HMP commands.
6 This document doesn't discuss QMP protocol level details, nor does it dive
7 into the QAPI framework implementation.
9 For an in-depth introduction to the QAPI framework, please refer to
10 docs/qapi-code-gen.txt. For documentation about the QMP protocol, please
11 check the files in QMP/.
15 Generally speaking, the following steps should be taken in order to write a
18 1. Write the command's and type(s) specification in the QAPI schema file
19 (qapi-schema.json in the root source directory)
21 2. Write the QMP command itself, which is a regular C function. Preferably,
22 the command should be exported by some QEMU subsystem. But it can also be
23 added to the qmp.c file
25 3. At this point the command can be tested under the QMP protocol
27 4. Write the HMP command equivalent. This is not required and should only be
28 done if it does make sense to have the functionality in HMP. The HMP command
29 is implemented in terms of the QMP command
31 The following sections will demonstrate each of the steps above. We will start
32 very simple and get more complex as we progress.
36 For all the examples in the next sections, the test setup is the same and is
39 First, QEMU should be started as:
41 # /path/to/your/source/qemu [...] \
42 -chardev socket,id=qmp,port=4444,host=localhost,server \
43 -mon chardev=qmp,mode=control,pretty=on
45 Then, in a different terminal:
47 $ telnet localhost 4444
49 Connected to localhost.
50 Escape character is '^]'.
66 The above output is the QMP server saying you're connected. The server is
67 actually in capabilities negotiation mode. To enter in command mode type:
69 { "execute": "qmp_capabilities" }
71 Then the server should respond:
78 Which is QMP's way of saying "the latest command executed OK and didn't return
79 any data". Now you're ready to enter the QMP example commands as explained in
80 the following sections.
82 == Writing a command that doesn't return data ==
84 That's the most simple QMP command that can be written. Usually, this kind of
85 command carries some meaningful action in QEMU but here it will just print
86 "Hello, world" to the standard output.
88 Our command will be called "hello-world". It takes no arguments, nor does it
91 The first step is to add the following line to the bottom of the
92 qapi-schema.json file:
94 { 'command': 'hello-world' }
96 The "command" keyword defines a new QMP command. It's an JSON object. All
97 schema entries are JSON objects. The line above will instruct the QAPI to
98 generate any prototypes and the necessary code to marshal and unmarshal
101 The next step is to write the "hello-world" implementation. As explained
102 earlier, it's preferable for commands to live in QEMU subsystems. But
103 "hello-world" doesn't pertain to any, so we put its implementation in qmp.c:
105 void qmp_hello_world(Error **errp)
107 printf("Hello, world!\n");
110 There are a few things to be noticed:
112 1. QMP command implementation functions must be prefixed with "qmp_"
113 2. qmp_hello_world() returns void, this is in accordance with the fact that the
114 command doesn't return any data
115 3. It takes an "Error **" argument. This is required. Later we will see how to
116 return errors and take additional arguments. The Error argument should not
117 be touched if the command doesn't return errors
118 4. We won't add the function's prototype. That's automatically done by the QAPI
119 5. Printing to the terminal is discouraged for QMP commands, we do it here
120 because it's the easiest way to demonstrate a QMP command
122 Now a little hack is needed. As we're still using the old QMP server we need
123 to add the new command to its internal dispatch table. This step won't be
124 required in the near future. Open the qmp-commands.hx file and add the
125 following at the bottom:
128 .name = "hello-world",
132 You're done. Now build qemu, run it as suggested in the "Testing" section,
133 and then type the following QMP command:
135 { "execute": "hello-world" }
137 Then check the terminal running qemu and look for the "Hello, world" string. If
138 you don't see it then something went wrong.
142 Let's add an argument called "message" to our "hello-world" command. The new
143 argument will contain the string to be printed to stdout. It's an optional
144 argument, if it's not present we print our default "Hello, World" string.
146 The first change we have to do is to modify the command specification in the
147 schema file to the following:
149 { 'command': 'hello-world', 'data': { '*message': 'str' } }
151 Notice the new 'data' member in the schema. It's an JSON object whose each
152 element is an argument to the command in question. Also notice the asterisk,
153 it's used to mark the argument optional (that means that you shouldn't use it
154 for mandatory arguments). Finally, 'str' is the argument's type, which
155 stands for "string". The QAPI also supports integers, booleans, enumerations
156 and user defined types.
158 Now, let's update our C implementation in qmp.c:
160 void qmp_hello_world(bool has_message, const char *message, Error **errp)
163 printf("%s\n", message);
165 printf("Hello, world\n");
169 There are two important details to be noticed:
171 1. All optional arguments are accompanied by a 'has_' boolean, which is set
172 if the optional argument is present or false otherwise
173 2. The C implementation signature must follow the schema's argument ordering,
174 which is defined by the "data" member
176 The last step is to update the qmp-commands.hx file:
179 .name = "hello-world",
180 .args_type = "message:s?",
183 Notice that the "args_type" member got our "message" argument. The character
184 "s" stands for "string" and "?" means it's optional. This too must be ordered
185 according to the C implementation and schema file. You can look for more
186 examples in the qmp-commands.hx file if you need to define more arguments.
188 Again, this step won't be required in the future.
190 Time to test our new version of the "hello-world" command. Build qemu, run it as
191 described in the "Testing" section and then send two commands:
193 { "execute": "hello-world" }
199 { "execute": "hello-world", "arguments": { "message": "We love qemu" } }
205 You should see "Hello, world" and "we love qemu" in the terminal running qemu,
206 if you don't see these strings, then something went wrong.
210 QMP commands should use the error interface exported by the error.h header
211 file. Basically, most errors are set by calling the error_setg() function.
213 Let's say we don't accept the string "message" to contain the word "love". If
214 it does contain it, we want the "hello-world" command to return an error:
216 void qmp_hello_world(bool has_message, const char *message, Error **errp)
219 if (strstr(message, "love")) {
220 error_setg(errp, "the word 'love' is not allowed");
223 printf("%s\n", message);
225 printf("Hello, world\n");
229 The first argument to the error_setg() function is the Error pointer
230 to pointer, which is passed to all QMP functions. The next argument is a human
231 description of the error, this is a free-form printf-like string.
233 Let's test the example above. Build qemu, run it as defined in the "Testing"
234 section, and then issue the following command:
236 { "execute": "hello-world", "arguments": { "message": "all you need is love" } }
238 The QMP server's response should be:
242 "class": "GenericError",
243 "desc": "the word 'love' is not allowed"
247 As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR
248 (done by default when using error_setg()). There are two exceptions to
251 1. A non-generic ErrorClass value exists* for the failure you want to report
254 2. Management applications have to take special action on the failure you
255 want to report, hence you have to add a new ErrorClass value so that they
258 If the failure you want to report falls into one of the two cases above,
259 use error_set() with a second argument of an ErrorClass value.
261 * All existing ErrorClass values are defined in the qapi-schema.json file
263 === Command Documentation ===
265 There's only one step missing to make "hello-world"'s implementation complete,
266 and that's its documentation in the schema file.
268 This is very important. No QMP command will be accepted in QEMU without proper
271 There are many examples of such documentation in the schema file already, but
272 here goes "hello-world"'s new entry for the qapi-schema.json file:
277 # Print a client provided string to the standard output stream.
279 # @message: #optional string to be printed
281 # Returns: Nothing on success.
283 # Notes: if @message is not provided, the "Hello, world" string will
286 # Since: <next qemu stable release, eg. 1.0>
288 { 'command': 'hello-world', 'data': { '*message': 'str' } }
290 Please, note that the "Returns" clause is optional if a command doesn't return
291 any data nor any errors.
293 === Implementing the HMP command ===
295 Now that the QMP command is in place, we can also make it available in the human
298 With the introduction of the QAPI, HMP commands make QMP calls. Most of the
299 time HMP commands are simple wrappers. All HMP commands implementation exist in
302 Here's the implementation of the "hello-world" HMP command:
304 void hmp_hello_world(Monitor *mon, const QDict *qdict)
306 const char *message = qdict_get_try_str(qdict, "message");
309 qmp_hello_world(!!message, message, &err);
311 monitor_printf(mon, "%s\n", error_get_pretty(err));
317 Also, you have to add the function's prototype to the hmp.h file.
319 There are three important points to be noticed:
321 1. The "mon" and "qdict" arguments are mandatory for all HMP functions. The
322 former is the monitor object. The latter is how the monitor passes
323 arguments entered by the user to the command implementation
324 2. hmp_hello_world() performs error checking. In this example we just print
325 the error description to the user, but we could do more, like taking
326 different actions depending on the error qmp_hello_world() returns
327 3. The "err" variable must be initialized to NULL before performing the
330 There's one last step to actually make the command available to monitor users,
331 we should add it to the hmp-commands.hx file:
334 .name = "hello-world",
335 .args_type = "message:s?",
336 .params = "hello-world [message]",
337 .help = "Print message to the standard output",
338 .mhandler.cmd = hmp_hello_world,
342 @item hello_world @var{message}
344 Print message to the standard output
347 To test this you have to open a user monitor and issue the "hello-world"
348 command. It might be instructive to check the command's documentation with
349 HMP's "help" command.
351 Please, check the "-monitor" command-line option to know how to open a user
354 == Writing a command that returns data ==
356 A QMP command is capable of returning any data the QAPI supports like integers,
357 strings, booleans, enumerations and user defined types.
359 In this section we will focus on user defined types. Please, check the QAPI
360 documentation for information about the other types.
362 === User Defined Types ===
364 FIXME This example needs to be redone after commit 6d32717
366 For this example we will write the query-alarm-clock command, which returns
367 information about QEMU's timer alarm. For more information about it, please
368 check the "-clock" command-line option.
370 We want to return two pieces of information. The first one is the alarm clock's
371 name. The second one is when the next alarm will fire. The former information is
372 returned as a string, the latter is an integer in nanoseconds (which is not
373 very useful in practice, as the timer has probably already fired when the
374 information reaches the client).
376 The best way to return that data is to create a new QAPI type, as shown below:
381 # QEMU alarm clock information.
383 # @clock-name: The alarm clock method's name.
385 # @next-deadline: #optional The time (in nanoseconds) the next alarm will fire.
389 { 'type': 'QemuAlarmClock',
390 'data': { 'clock-name': 'str', '*next-deadline': 'int' } }
392 The "type" keyword defines a new QAPI type. Its "data" member contains the
393 type's members. In this example our members are the "clock-name" and the
394 "next-deadline" one, which is optional.
396 Now let's define the query-alarm-clock command:
401 # Return information about QEMU's alarm clock.
403 # Returns a @QemuAlarmClock instance describing the alarm clock method
404 # being currently used by QEMU (this is usually set by the '-clock'
405 # command-line option).
409 { 'command': 'query-alarm-clock', 'returns': 'QemuAlarmClock' }
411 Notice the "returns" keyword. As its name suggests, it's used to define the
412 data returned by a command.
414 It's time to implement the qmp_query_alarm_clock() function, you can put it
415 in the qemu-timer.c file:
417 QemuAlarmClock *qmp_query_alarm_clock(Error **errp)
419 QemuAlarmClock *clock;
422 clock = g_malloc0(sizeof(*clock));
424 deadline = qemu_next_alarm_deadline();
426 clock->has_next_deadline = true;
427 clock->next_deadline = deadline;
429 clock->clock_name = g_strdup(alarm_timer->name);
434 There are a number of things to be noticed:
436 1. The QemuAlarmClock type is automatically generated by the QAPI framework,
437 its members correspond to the type's specification in the schema file
438 2. As specified in the schema file, the function returns a QemuAlarmClock
439 instance and takes no arguments (besides the "errp" one, which is mandatory
440 for all QMP functions)
441 3. The "clock" variable (which will point to our QAPI type instance) is
442 allocated by the regular g_malloc0() function. Note that we chose to
443 initialize the memory to zero. This is recommended for all QAPI types, as
444 it helps avoiding bad surprises (specially with booleans)
445 4. Remember that "next_deadline" is optional? All optional members have a
446 'has_TYPE_NAME' member that should be properly set by the implementation,
448 5. Even static strings, such as "alarm_timer->name", should be dynamically
449 allocated by the implementation. This is so because the QAPI also generates
450 a function to free its types and it cannot distinguish between dynamically
451 or statically allocated strings
452 6. You have to include the "qmp-commands.h" header file in qemu-timer.c,
453 otherwise qemu won't build
455 The last step is to add the corresponding entry in the qmp-commands.hx file:
458 .name = "query-alarm-clock",
462 Time to test the new command. Build qemu, run it as described in the "Testing"
463 section and try this:
465 { "execute": "query-alarm-clock" }
468 "next-deadline": 2368219,
469 "clock-name": "dynticks"
473 ==== The HMP command ====
475 Here's the HMP counterpart of the query-alarm-clock command:
477 void hmp_info_alarm_clock(Monitor *mon)
479 QemuAlarmClock *clock;
482 clock = qmp_query_alarm_clock(&err);
484 monitor_printf(mon, "Could not query alarm clock information\n");
489 monitor_printf(mon, "Alarm clock method in use: '%s'\n", clock->clock_name);
490 if (clock->has_next_deadline) {
491 monitor_printf(mon, "Next alarm will fire in %" PRId64 " nanoseconds\n",
492 clock->next_deadline);
495 qapi_free_QemuAlarmClock(clock);
498 It's important to notice that hmp_info_alarm_clock() calls
499 qapi_free_QemuAlarmClock() to free the data returned by qmp_query_alarm_clock().
500 For user defined types, the QAPI will generate a qapi_free_QAPI_TYPE_NAME()
501 function and that's what you have to use to free the types you define and
502 qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section).
503 If the QMP call returns a string, then you should g_free() to free it.
505 Also note that hmp_info_alarm_clock() performs error handling. That's not
506 strictly required if you're sure the QMP function doesn't return errors, but
507 it's good practice to always check for errors.
509 Another important detail is that HMP's "info" commands don't go into the
510 hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined
511 in the monitor.c file. The entry for the "info alarmclock" follows:
514 .name = "alarmclock",
517 .help = "show information about the alarm clock",
518 .mhandler.cmd = hmp_info_alarm_clock,
521 To test this, run qemu and type "info alarmclock" in the user monitor.
523 === Returning Lists ===
525 For this example, we're going to return all available methods for the timer
526 alarm, which is pretty much what the command-line option "-clock ?" does,
527 except that we're also going to inform which method is in use.
529 This first step is to define a new type:
534 # Timer alarm method information.
536 # @method-name: The method's name.
538 # @current: true if this alarm method is currently in use, false otherwise
542 { 'type': 'TimerAlarmMethod',
543 'data': { 'method-name': 'str', 'current': 'bool' } }
545 The command will be called "query-alarm-methods", here is its schema
549 # @query-alarm-methods
551 # Returns information about available alarm methods.
553 # Returns: a list of @TimerAlarmMethod for each method
557 { 'command': 'query-alarm-methods', 'returns': ['TimerAlarmMethod'] }
559 Notice the syntax for returning lists "'returns': ['TimerAlarmMethod']", this
560 should be read as "returns a list of TimerAlarmMethod instances".
562 The C implementation follows:
564 TimerAlarmMethodList *qmp_query_alarm_methods(Error **errp)
566 TimerAlarmMethodList *method_list = NULL;
567 const struct qemu_alarm_timer *p;
570 for (p = alarm_timers; p->name; p++) {
571 TimerAlarmMethodList *info = g_malloc0(sizeof(*info));
572 info->value = g_malloc0(sizeof(*info->value));
573 info->value->method_name = g_strdup(p->name);
574 info->value->current = current;
578 info->next = method_list;
585 The most important difference from the previous examples is the
586 TimerAlarmMethodList type, which is automatically generated by the QAPI from
587 the TimerAlarmMethod type.
589 Each list node is represented by a TimerAlarmMethodList instance. We have to
590 allocate it, and that's done inside the for loop: the "info" pointer points to
591 an allocated node. We also have to allocate the node's contents, which is
592 stored in its "value" member. In our example, the "value" member is a pointer
593 to an TimerAlarmMethod instance.
595 Notice that the "current" variable is used as "true" only in the first
596 iteration of the loop. That's because the alarm timer method in use is the
597 first element of the alarm_timers array. Also notice that QAPI lists are handled
598 by hand and we return the head of the list.
600 To test this you have to add the corresponding qmp-commands.hx entry:
603 .name = "query-alarm-methods",
607 Now Build qemu, run it as explained in the "Testing" section and try our new
610 { "execute": "query-alarm-methods" }
615 "method-name": "unix"
619 "method-name": "dynticks"
624 The HMP counterpart is a bit more complex than previous examples because it
625 has to traverse the list, it's shown below for reference:
627 void hmp_info_alarm_methods(Monitor *mon)
629 TimerAlarmMethodList *method_list, *method;
632 method_list = qmp_query_alarm_methods(&err);
634 monitor_printf(mon, "Could not query alarm methods\n");
639 for (method = method_list; method; method = method->next) {
640 monitor_printf(mon, "%c %s\n", method->value->current ? '*' : ' ',
641 method->value->method_name);
644 qapi_free_TimerAlarmMethodList(method_list);