block: support passing 'backing': '' to 'blockdev-add'
[qemu.git] / docs / writing-qmp-commands.txt
blob8647cac4e715879e069dca489a8227131fdeb3cf
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/.
13 == Overview ==
15 Generally speaking, the following steps should be taken in order to write a
16 new QMP command.
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.
34 === Testing ===
36 For all the examples in the next sections, the test setup is the same and is
37 shown here.
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
48 Trying 127.0.0.1...
49 Connected to localhost.
50 Escape character is '^]'.
52     "QMP": {
53         "version": {
54             "qemu": {
55                 "micro": 50, 
56                 "minor": 15, 
57                 "major": 0
58             }, 
59             "package": ""
60         }, 
61         "capabilities": [
62         ]
63     }
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:
74     "return": {
75     }
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
89 return any data.
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
99 protocol data.
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:
127     {
128         .name       = "hello-world",
129         .args_type  = "",
130         .mhandler.cmd_new = qmp_marshal_hello_world,
131     },
133 You're done. Now build qemu, run it as suggested in the "Testing" section,
134 and then type the following QMP command:
136 { "execute": "hello-world" }
138 Then check the terminal running qemu and look for the "Hello, world" string. If
139 you don't see it then something went wrong.
141 === Arguments ===
143 Let's add an argument called "message" to our "hello-world" command. The new
144 argument will contain the string to be printed to stdout. It's an optional
145 argument, if it's not present we print our default "Hello, World" string.
147 The first change we have to do is to modify the command specification in the
148 schema file to the following:
150 { 'command': 'hello-world', 'data': { '*message': 'str' } }
152 Notice the new 'data' member in the schema. It's an JSON object whose each
153 element is an argument to the command in question. Also notice the asterisk,
154 it's used to mark the argument optional (that means that you shouldn't use it
155 for mandatory arguments). Finally, 'str' is the argument's type, which
156 stands for "string". The QAPI also supports integers, booleans, enumerations
157 and user defined types.
159 Now, let's update our C implementation in qmp.c:
161 void qmp_hello_world(bool has_message, const char *message, Error **errp)
163     if (has_message) {
164         printf("%s\n", message);
165     } else {
166         printf("Hello, world\n");
167     }
170 There are two important details to be noticed:
172 1. All optional arguments are accompanied by a 'has_' boolean, which is set
173    if the optional argument is present or false otherwise
174 2. The C implementation signature must follow the schema's argument ordering,
175    which is defined by the "data" member
177 The last step is to update the qmp-commands.hx file:
179     {
180         .name       = "hello-world",
181         .args_type  = "message:s?",
182         .mhandler.cmd_new = qmp_marshal_hello_world,
183     },
185 Notice that the "args_type" member got our "message" argument. The character
186 "s" stands for "string" and "?" means it's optional. This too must be ordered
187 according to the C implementation and schema file. You can look for more
188 examples in the qmp-commands.hx file if you need to define more arguments.
190 Again, this step won't be required in the future.
192 Time to test our new version of the "hello-world" command. Build qemu, run it as
193 described in the "Testing" section and then send two commands:
195 { "execute": "hello-world" }
197     "return": {
198     }
201 { "execute": "hello-world", "arguments": { "message": "We love qemu" } }
203     "return": {
204     }
207 You should see "Hello, world" and "we love qemu" in the terminal running qemu,
208 if you don't see these strings, then something went wrong.
210 === Errors ===
212 QMP commands should use the error interface exported by the error.h header
213 file. Basically, errors are set by calling the error_set() function.
215 Let's say we don't accept the string "message" to contain the word "love". If
216 it does contain it, we want the "hello-world" command to return an error:
218 void qmp_hello_world(bool has_message, const char *message, Error **errp)
220     if (has_message) {
221         if (strstr(message, "love")) {
222             error_set(errp, ERROR_CLASS_GENERIC_ERROR,
223                       "the word 'love' is not allowed");
224             return;
225         }
226         printf("%s\n", message);
227     } else {
228         printf("Hello, world\n");
229     }
232 The first argument to the error_set() function is the Error pointer to pointer,
233 which is passed to all QMP functions. The second argument is a ErrorClass
234 value, which should be ERROR_CLASS_GENERIC_ERROR most of the time (more
235 details about error classes are given below). The third argument is a human
236 description of the error, this is a free-form printf-like string.
238 Let's test the example above. Build qemu, run it as defined in the "Testing"
239 section, and then issue the following command:
241 { "execute": "hello-world", "arguments": { "message": "all you need is love" } }
243 The QMP server's response should be:
246     "error": {
247         "class": "GenericError",
248         "desc": "the word 'love' is not allowed"
249     }
252 As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR. There
253 are two exceptions to this rule:
255  1. A non-generic ErrorClass value exists* for the failure you want to report
256     (eg. DeviceNotFound)
258  2. Management applications have to take special action on the failure you
259     want to report, hence you have to add a new ErrorClass value so that they
260     can check for it
262 If the failure you want to report doesn't fall in one of the two cases above,
263 just report ERROR_CLASS_GENERIC_ERROR.
265  * All existing ErrorClass values are defined in the qapi-schema.json file
267 === Command Documentation ===
269 There's only one step missing to make "hello-world"'s implementation complete,
270 and that's its documentation in the schema file.
272 This is very important. No QMP command will be accepted in QEMU without proper
273 documentation.
275 There are many examples of such documentation in the schema file already, but
276 here goes "hello-world"'s new entry for the qapi-schema.json file:
279 # @hello-world
281 # Print a client provided string to the standard output stream.
283 # @message: #optional string to be printed
285 # Returns: Nothing on success.
287 # Notes: if @message is not provided, the "Hello, world" string will
288 #        be printed instead
290 # Since: <next qemu stable release, eg. 1.0>
292 { 'command': 'hello-world', 'data': { '*message': 'str' } }
294 Please, note that the "Returns" clause is optional if a command doesn't return
295 any data nor any errors.
297 === Implementing the HMP command ===
299 Now that the QMP command is in place, we can also make it available in the human
300 monitor (HMP).
302 With the introduction of the QAPI, HMP commands make QMP calls. Most of the
303 time HMP commands are simple wrappers. All HMP commands implementation exist in
304 the hmp.c file.
306 Here's the implementation of the "hello-world" HMP command:
308 void hmp_hello_world(Monitor *mon, const QDict *qdict)
310     const char *message = qdict_get_try_str(qdict, "message");
311     Error *err = NULL;
313     qmp_hello_world(!!message, message, &err);
314     if (err) {
315         monitor_printf(mon, "%s\n", error_get_pretty(err));
316         error_free(err);
317         return;
318     }
321 Also, you have to add the function's prototype to the hmp.h file.
323 There are three important points to be noticed:
325 1. The "mon" and "qdict" arguments are mandatory for all HMP functions. The
326    former is the monitor object. The latter is how the monitor passes
327    arguments entered by the user to the command implementation
328 2. hmp_hello_world() performs error checking. In this example we just print
329    the error description to the user, but we could do more, like taking
330    different actions depending on the error qmp_hello_world() returns
331 3. The "err" variable must be initialized to NULL before performing the
332    QMP call
334 There's one last step to actually make the command available to monitor users,
335 we should add it to the hmp-commands.hx file:
337     {
338         .name       = "hello-world",
339         .args_type  = "message:s?",
340         .params     = "hello-world [message]",
341         .help       = "Print message to the standard output",
342         .mhandler.cmd = hmp_hello_world,
343     },
345 STEXI
346 @item hello_world @var{message}
347 @findex hello_world
348 Print message to the standard output
349 ETEXI
351 To test this you have to open a user monitor and issue the "hello-world"
352 command. It might be instructive to check the command's documentation with
353 HMP's "help" command.
355 Please, check the "-monitor" command-line option to know how to open a user
356 monitor.
358 == Writing a command that returns data ==
360 A QMP command is capable of returning any data the QAPI supports like integers,
361 strings, booleans, enumerations and user defined types.
363 In this section we will focus on user defined types. Please, check the QAPI
364 documentation for information about the other types.
366 === User Defined Types ===
368 FIXME This example needs to be redone after commit 6d32717
370 For this example we will write the query-alarm-clock command, which returns
371 information about QEMU's timer alarm. For more information about it, please
372 check the "-clock" command-line option.
374 We want to return two pieces of information. The first one is the alarm clock's
375 name. The second one is when the next alarm will fire. The former information is
376 returned as a string, the latter is an integer in nanoseconds (which is not
377 very useful in practice, as the timer has probably already fired when the
378 information reaches the client).
380 The best way to return that data is to create a new QAPI type, as shown below:
383 # @QemuAlarmClock
385 # QEMU alarm clock information.
387 # @clock-name: The alarm clock method's name.
389 # @next-deadline: #optional The time (in nanoseconds) the next alarm will fire.
391 # Since: 1.0
393 { 'type': 'QemuAlarmClock',
394   'data': { 'clock-name': 'str', '*next-deadline': 'int' } }
396 The "type" keyword defines a new QAPI type. Its "data" member contains the
397 type's members. In this example our members are the "clock-name" and the
398 "next-deadline" one, which is optional.
400 Now let's define the query-alarm-clock command:
403 # @query-alarm-clock
405 # Return information about QEMU's alarm clock.
407 # Returns a @QemuAlarmClock instance describing the alarm clock method
408 # being currently used by QEMU (this is usually set by the '-clock'
409 # command-line option).
411 # Since: 1.0
413 { 'command': 'query-alarm-clock', 'returns': 'QemuAlarmClock' }
415 Notice the "returns" keyword. As its name suggests, it's used to define the
416 data returned by a command.
418 It's time to implement the qmp_query_alarm_clock() function, you can put it
419 in the qemu-timer.c file:
421 QemuAlarmClock *qmp_query_alarm_clock(Error **errp)
423     QemuAlarmClock *clock;
424     int64_t deadline;
426     clock = g_malloc0(sizeof(*clock));
428     deadline = qemu_next_alarm_deadline();
429     if (deadline > 0) {
430         clock->has_next_deadline = true;
431         clock->next_deadline = deadline;
432     }
433     clock->clock_name = g_strdup(alarm_timer->name);
435     return clock;
438 There are a number of things to be noticed:
440 1. The QemuAlarmClock type is automatically generated by the QAPI framework,
441    its members correspond to the type's specification in the schema file
442 2. As specified in the schema file, the function returns a QemuAlarmClock
443    instance and takes no arguments (besides the "errp" one, which is mandatory
444    for all QMP functions)
445 3. The "clock" variable (which will point to our QAPI type instance) is
446    allocated by the regular g_malloc0() function. Note that we chose to
447    initialize the memory to zero. This is recommended for all QAPI types, as
448    it helps avoiding bad surprises (specially with booleans)
449 4. Remember that "next_deadline" is optional? All optional members have a
450    'has_TYPE_NAME' member that should be properly set by the implementation,
451    as shown above
452 5. Even static strings, such as "alarm_timer->name", should be dynamically
453    allocated by the implementation. This is so because the QAPI also generates
454    a function to free its types and it cannot distinguish between dynamically
455    or statically allocated strings
456 6. You have to include the "qmp-commands.h" header file in qemu-timer.c,
457    otherwise qemu won't build
459 The last step is to add the correspoding entry in the qmp-commands.hx file:
461     {
462         .name       = "query-alarm-clock",
463         .args_type  = "",
464         .mhandler.cmd_new = qmp_marshal_query_alarm_clock,
465     },
467 Time to test the new command. Build qemu, run it as described in the "Testing"
468 section and try this:
470 { "execute": "query-alarm-clock" }
472     "return": {
473         "next-deadline": 2368219,
474         "clock-name": "dynticks"
475     }
478 ==== The HMP command ====
480 Here's the HMP counterpart of the query-alarm-clock command:
482 void hmp_info_alarm_clock(Monitor *mon)
484     QemuAlarmClock *clock;
485     Error *err = NULL;
487     clock = qmp_query_alarm_clock(&err);
488     if (err) {
489         monitor_printf(mon, "Could not query alarm clock information\n");
490         error_free(err);
491         return;
492     }
494     monitor_printf(mon, "Alarm clock method in use: '%s'\n", clock->clock_name);
495     if (clock->has_next_deadline) {
496         monitor_printf(mon, "Next alarm will fire in %" PRId64 " nanoseconds\n",
497                        clock->next_deadline);
498     }
500    qapi_free_QemuAlarmClock(clock); 
503 It's important to notice that hmp_info_alarm_clock() calls
504 qapi_free_QemuAlarmClock() to free the data returned by qmp_query_alarm_clock().
505 For user defined types, the QAPI will generate a qapi_free_QAPI_TYPE_NAME()
506 function and that's what you have to use to free the types you define and
507 qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section).
508 If the QMP call returns a string, then you should g_free() to free it.
510 Also note that hmp_info_alarm_clock() performs error handling. That's not
511 strictly required if you're sure the QMP function doesn't return errors, but
512 it's good practice to always check for errors.
514 Another important detail is that HMP's "info" commands don't go into the
515 hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined
516 in the monitor.c file. The entry for the "info alarmclock" follows:
518     {
519         .name       = "alarmclock",
520         .args_type  = "",
521         .params     = "",
522         .help       = "show information about the alarm clock",
523         .mhandler.info = hmp_info_alarm_clock,
524     },
526 To test this, run qemu and type "info alarmclock" in the user monitor.
528 === Returning Lists ===
530 For this example, we're going to return all available methods for the timer
531 alarm, which is pretty much what the command-line option "-clock ?" does,
532 except that we're also going to inform which method is in use.
534 This first step is to define a new type:
537 # @TimerAlarmMethod
539 # Timer alarm method information.
541 # @method-name: The method's name.
543 # @current: true if this alarm method is currently in use, false otherwise
545 # Since: 1.0
547 { 'type': 'TimerAlarmMethod',
548   'data': { 'method-name': 'str', 'current': 'bool' } }
550 The command will be called "query-alarm-methods", here is its schema
551 specification:
554 # @query-alarm-methods
556 # Returns information about available alarm methods.
558 # Returns: a list of @TimerAlarmMethod for each method
560 # Since: 1.0
562 { 'command': 'query-alarm-methods', 'returns': ['TimerAlarmMethod'] }
564 Notice the syntax for returning lists "'returns': ['TimerAlarmMethod']", this
565 should be read as "returns a list of TimerAlarmMethod instances".
567 The C implementation follows:
569 TimerAlarmMethodList *qmp_query_alarm_methods(Error **errp)
571     TimerAlarmMethodList *method_list = NULL;
572     const struct qemu_alarm_timer *p;
573     bool current = true;
575     for (p = alarm_timers; p->name; p++) {
576         TimerAlarmMethodList *info = g_malloc0(sizeof(*info));
577         info->value = g_malloc0(sizeof(*info->value));
578         info->value->method_name = g_strdup(p->name);
579         info->value->current = current;
581         current = false;
583         info->next = method_list;
584         method_list = info;
585     }
587     return method_list;
590 The most important difference from the previous examples is the
591 TimerAlarmMethodList type, which is automatically generated by the QAPI from
592 the TimerAlarmMethod type.
594 Each list node is represented by a TimerAlarmMethodList instance. We have to
595 allocate it, and that's done inside the for loop: the "info" pointer points to
596 an allocated node. We also have to allocate the node's contents, which is
597 stored in its "value" member. In our example, the "value" member is a pointer
598 to an TimerAlarmMethod instance.
600 Notice that the "current" variable is used as "true" only in the first
601 iteration of the loop. That's because the alarm timer method in use is the
602 first element of the alarm_timers array. Also notice that QAPI lists are handled
603 by hand and we return the head of the list.
605 To test this you have to add the corresponding qmp-commands.hx entry:
607     {
608         .name       = "query-alarm-methods",
609         .args_type  = "",
610         .mhandler.cmd_new = qmp_marshal_query_alarm_methods,
611     },
613 Now Build qemu, run it as explained in the "Testing" section and try our new
614 command:
616 { "execute": "query-alarm-methods" }
618     "return": [
619         {
620             "current": false, 
621             "method-name": "unix"
622         }, 
623         {
624             "current": true, 
625             "method-name": "dynticks"
626         }
627     ]
630 The HMP counterpart is a bit more complex than previous examples because it
631 has to traverse the list, it's shown below for reference:
633 void hmp_info_alarm_methods(Monitor *mon)
635     TimerAlarmMethodList *method_list, *method;
636     Error *err = NULL;
638     method_list = qmp_query_alarm_methods(&err);
639     if (err) {
640         monitor_printf(mon, "Could not query alarm methods\n");
641         error_free(err);
642         return;
643     }
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     }
650     qapi_free_TimerAlarmMethodList(method_list);