linux-user: add SO_PEERCRED support for getsockopt
[qemu.git] / docs / writing-qmp-commands.txt
1 = How to write QMP commands using the QAPI framework =
2
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.
5
6 This document doesn't discuss QMP protocol level details, nor does it dive
7 into the QAPI framework implementation.
8
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/.
12
13 == Overview ==
14
15 Generally speaking, the following steps should be taken in order to write a
16 new QMP command.
17
18 1. Write the command's and type(s) specification in the QAPI schema file
19    (qapi-schema.json in the root source directory)
20
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
24
25 3. At this point the command can be tested under the QMP protocol
26
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
30
31 The following sections will demonstrate each of the steps above. We will start
32 very simple and get more complex as we progress.
33
34 === Testing ===
35
36 For all the examples in the next sections, the test setup is the same and is
37 shown here.
38
39 First, QEMU should be started as:
40
41 # /path/to/your/source/qemu [...] \
42     -chardev socket,id=qmp,port=4444,host=localhost,server \
43     -mon chardev=qmp,mode=control,pretty=on
44
45 Then, in a different terminal:
46
47 $ telnet localhost 4444
48 Trying 127.0.0.1...
49 Connected to localhost.
50 Escape character is '^]'.
51 {
52     "QMP": {
53         "version": {
54             "qemu": {
55                 "micro": 50, 
56                 "minor": 15, 
57                 "major": 0
58             }, 
59             "package": ""
60         }, 
61         "capabilities": [
62         ]
63     }
64 }
65
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:
68
69 { "execute": "qmp_capabilities" }
70
71 Then the server should respond:
72
73 {
74     "return": {
75     }
76 }
77
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.
81
82 == Writing a command that doesn't return data ==
83
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.
87
88 Our command will be called "hello-world". It takes no arguments, nor does it
89 return any data.
90
91 The first step is to add the following line to the bottom of the
92 qapi-schema.json file:
93
94 { 'command': 'hello-world' }
95
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.
100
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:
104
105 void qmp_hello_world(Error **errp)
106 {
107     printf("Hello, world!\n");
108 }
109
110 There are a few things to be noticed:
111
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
121
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 in the botton:
126
127     {
128         .name       = "hello-world",
129         .args_type  = "",
130         .mhandler.cmd_new = qmp_marshal_input_hello_world,
131     },
132
133 You're done. Now build qemu, run it as suggested in the "Testing" section,
134 and then type the following QMP command:
135
136 { "execute": "hello-world" }
137
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.
140
141 === Arguments ===
142
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.
146
147 The first change we have to do is to modify the command specification in the
148 schema file to the following:
149
150 { 'command': 'hello-world', 'data': { '*message': 'str' } }
151
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.
158
159 Now, let's update our C implementation in qmp.c:
160
161 void qmp_hello_world(bool has_message, const char *message, Error **errp)
162 {
163     if (has_message) {
164         printf("%s\n", message);
165     } else {
166         printf("Hello, world\n");
167     }
168 }
169
170 There are two important details to be noticed:
171
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
176
177 The last step is to update the qmp-commands.hx file:
178
179     {
180         .name       = "hello-world",
181         .args_type  = "message:s?",
182         .mhandler.cmd_new = qmp_marshal_input_hello_world,
183     },
184
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.
189
190 Again, this step won't be required in the future.
191
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:
194
195 { "execute": "hello-world" }
196 {
197     "return": {
198     }
199 }
200
201 { "execute": "hello-world", "arguments": { "message": "We love qemu" } }
202 {
203     "return": {
204     }
205 }
206
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.
209
210 === Errors ===
211
212 QMP commands should use the error interface exported by the error.h header
213 file. The basic function used to set an error is the error_set() one.
214
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 the return the
217 InvalidParameter error.
218
219 Only one change is required, and it's in the C implementation:
220
221 void qmp_hello_world(bool has_message, const char *message, Error **errp)
222 {
223     if (has_message) {
224         if (strstr(message, "love")) {
225             error_set(errp, QERR_INVALID_PARAMETER, "message");
226             return;
227         }
228         printf("%s\n", message);
229     } else {
230         printf("Hello, world\n");
231     }
232 }
233
234 Let's test it. Build qemu, run it as defined in the "Testing" section, and
235 then issue the following command:
236
237 { "execute": "hello-world", "arguments": { "message": "we love qemu" } }
238
239 The QMP server's response should be:
240
241 {
242     "error": {
243         "class": "InvalidParameter",
244         "desc": "Invalid parameter 'message'",
245         "data": {
246             "name": "message"
247         }
248     }
249 }
250
251 Which is the InvalidParameter error.
252
253 When you have to return an error but you're unsure what error to return or
254 which arguments an error takes, you should look at the qerror.h file. Note
255 that you might be required to add new errors if needed.
256
257 FIXME: describe better the error API and how to add new errors.
258
259 === Command Documentation ===
260
261 There's only one step missing to make "hello-world"'s implementation complete,
262 and that's its documentation in the schema file.
263
264 This is very important. No QMP command will be accepted in QEMU without proper
265 documentation.
266
267 There are many examples of such documentation in the schema file already, but
268 here goes "hello-world"'s new entry for the qapi-schema.json file:
269
270 ##
271 # @hello-world
272 #
273 # Print a client provided string to the standard output stream.
274 #
275 # @message: #optional string to be printed
276 #
277 # Returns: Nothing on success.
278 #          If @message contains "love", InvalidParameter
279 #
280 # Notes: if @message is not provided, the "Hello, world" string will
281 #        be printed instead
282 #
283 # Since: <next qemu stable release, eg. 1.0>
284 ##
285 { 'command': 'hello-world', 'data': { '*message': 'str' } }
286
287 Please, note that the "Returns" clause is optional if a command doesn't return
288 any data nor any errors.
289
290 === Implementing the HMP command ===
291
292 Now that the QMP command is in place, we can also make it available in the human
293 monitor (HMP).
294
295 With the introduction of the QAPI, HMP commands make QMP calls. Most of the
296 time HMP commands are simple wrappers. All HMP commands implementation exist in
297 the hmp.c file.
298
299 Here's the implementation of the "hello-world" HMP command:
300
301 void hmp_hello_world(Monitor *mon, const QDict *qdict)
302 {
303     const char *message = qdict_get_try_str(qdict, "message");
304     Error *errp = NULL;
305
306     qmp_hello_world(!!message, message, &errp);
307     if (error_is_set(&errp)) {
308         monitor_printf(mon, "%s\n", error_get_pretty(errp));
309         error_free(errp);
310         return;
311     }
312 }
313
314 Also, you have to add the function's prototype to the hmp.h file.
315
316 There are three important points to be noticed:
317
318 1. The "mon" and "qdict" arguments are mandatory for all HMP functions. The
319    former is the monitor object. The latter is how the monitor passes
320    arguments entered by the user to the command implementation
321 2. hmp_hello_world() performs error checking. In this example we just print
322    the error description to the user, but we could do more, like taking
323    different actions depending on the error qmp_hello_world() returns
324 3. The "errp" variable must be initialized to NULL before performing the
325    QMP call
326
327 There's one last step to actually make the command available to monitor users,
328 we should add it to the hmp-commands.hx file:
329
330     {
331         .name       = "hello-world",
332         .args_type  = "message:s?",
333         .params     = "hello-world [message]",
334         .help       = "Print message to the standard output",
335         .mhandler.cmd = hmp_hello_world,
336     },
337
338 STEXI
339 @item hello_world @var{message}
340 @findex hello_world
341 Print message to the standard output
342 ETEXI
343
344 To test this you have to open a user monitor and issue the "hello-world"
345 command. It might be instructive to check the command's documentation with
346 HMP's "help" command.
347
348 Please, check the "-monitor" command-line option to know how to open a user
349 monitor.
350
351 == Writing a command that returns data ==
352
353 A QMP command is capable of returning any data the QAPI supports like integers,
354 strings, booleans, enumerations and user defined types.
355
356 In this section we will focus on user defined types. Please, check the QAPI
357 documentation for information about the other types.
358
359 === User Defined Types ===
360
361 For this example we will write the query-alarm-clock command, which returns
362 information about QEMU's timer alarm. For more information about it, please
363 check the "-clock" command-line option.
364
365 We want to return two pieces of information. The first one is the alarm clock's
366 name. The second one is when the next alarm will fire. The former information is
367 returned as a string, the latter is an integer in nanoseconds (which is not
368 very useful in practice, as the timer has probably already fired when the
369 information reaches the client).
370
371 The best way to return that data is to create a new QAPI type, as shown below:
372
373 ##
374 # @QemuAlarmClock
375 #
376 # QEMU alarm clock information.
377 #
378 # @clock-name: The alarm clock method's name.
379 #
380 # @next-deadline: #optional The time (in nanoseconds) the next alarm will fire.
381 #
382 # Since: 1.0
383 ##
384 { 'type': 'QemuAlarmClock',
385   'data': { 'clock-name': 'str', '*next-deadline': 'int' } }
386
387 The "type" keyword defines a new QAPI type. Its "data" member contains the
388 type's members. In this example our members are the "clock-name" and the
389 "next-deadline" one, which is optional.
390
391 Now let's define the query-alarm-clock command:
392
393 ##
394 # @query-alarm-clock
395 #
396 # Return information about QEMU's alarm clock.
397 #
398 # Returns a @QemuAlarmClock instance describing the alarm clock method
399 # being currently used by QEMU (this is usually set by the '-clock'
400 # command-line option).
401 #
402 # Since: 1.0
403 ##
404 { 'command': 'query-alarm-clock', 'returns': 'QemuAlarmClock' }
405
406 Notice the "returns" keyword. As its name suggests, it's used to define the
407 data returned by a command.
408
409 It's time to implement the qmp_query_alarm_clock() function, you can put it
410 in the qemu-timer.c file:
411
412 QemuAlarmClock *qmp_query_alarm_clock(Error **errp)
413 {
414     QemuAlarmClock *clock;
415     int64_t deadline;
416
417     clock = g_malloc0(sizeof(*clock));
418
419     deadline = qemu_next_alarm_deadline();
420     if (deadline > 0) {
421         clock->has_next_deadline = true;
422         clock->next_deadline = deadline;
423     }
424     clock->clock_name = g_strdup(alarm_timer->name);
425
426     return clock;
427 }
428
429 There are a number of things to be noticed:
430
431 1. The QemuAlarmClock type is automatically generated by the QAPI framework,
432    its members correspond to the type's specification in the schema file
433 2. As specified in the schema file, the function returns a QemuAlarmClock
434    instance and takes no arguments (besides the "errp" one, which is mandatory
435    for all QMP functions)
436 3. The "clock" variable (which will point to our QAPI type instance) is
437    allocated by the regular g_malloc0() function. Note that we chose to
438    initialize the memory to zero. This is recommended for all QAPI types, as
439    it helps avoiding bad surprises (specially with booleans)
440 4. Remember that "next_deadline" is optional? All optional members have a
441    'has_TYPE_NAME' member that should be properly set by the implementation,
442    as shown above
443 5. Even static strings, such as "alarm_timer->name", should be dynamically
444    allocated by the implementation. This is so because the QAPI also generates
445    a function to free its types and it cannot distinguish between dynamically
446    or statically allocated strings
447 6. You have to include the "qmp-commands.h" header file in qemu-timer.c,
448    otherwise qemu won't build
449
450 The last step is to add the correspoding entry in the qmp-commands.hx file:
451
452     {
453         .name       = "query-alarm-clock",
454         .args_type  = "",
455         .mhandler.cmd_new = qmp_marshal_input_query_alarm_clock,
456     },
457
458 Time to test the new command. Build qemu, run it as described in the "Testing"
459 section and try this:
460
461 { "execute": "query-alarm-clock" }
462 {
463     "return": {
464         "next-deadline": 2368219,
465         "clock-name": "dynticks"
466     }
467 }
468
469 ==== The HMP command ====
470
471 Here's the HMP counterpart of the query-alarm-clock command:
472
473 void hmp_info_alarm_clock(Monitor *mon)
474 {
475     QemuAlarmClock *clock;
476     Error *errp = NULL;
477
478     clock = qmp_query_alarm_clock(&errp);
479     if (error_is_set(&errp)) {
480         monitor_printf(mon, "Could not query alarm clock information\n");
481         error_free(errp);
482         return;
483     }
484
485     monitor_printf(mon, "Alarm clock method in use: '%s'\n", clock->clock_name);
486     if (clock->has_next_deadline) {
487         monitor_printf(mon, "Next alarm will fire in %" PRId64 " nanoseconds\n",
488                        clock->next_deadline);
489     }
490
491    qapi_free_QemuAlarmClock(clock); 
492 }
493
494 It's important to notice that hmp_info_alarm_clock() calls
495 qapi_free_QemuAlarmClock() to free the data returned by qmp_query_alarm_clock().
496 For user defined types, the QAPI will generate a qapi_free_QAPI_TYPE_NAME()
497 function and that's what you have to use to free the types you define and
498 qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section).
499 If the QMP call returns a string, then you should g_free() to free it.
500
501 Also note that hmp_info_alarm_clock() performs error handling. That's not
502 strictly required if you're sure the QMP function doesn't return errors, but
503 it's good practice to always check for errors.
504
505 Another important detail is that HMP's "info" commands don't go into the
506 hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined
507 in the monitor.c file. The entry for the "info alarmclock" follows:
508
509     {
510         .name       = "alarmclock",
511         .args_type  = "",
512         .params     = "",
513         .help       = "show information about the alarm clock",
514         .mhandler.info = hmp_info_alarm_clock,
515     },
516
517 To test this, run qemu and type "info alarmclock" in the user monitor.
518
519 === Returning Lists ===
520
521 For this example, we're going to return all available methods for the timer
522 alarm, which is pretty much what the command-line option "-clock ?" does,
523 except that we're also going to inform which method is in use.
524
525 This first step is to define a new type:
526
527 ##
528 # @TimerAlarmMethod
529 #
530 # Timer alarm method information.
531 #
532 # @method-name: The method's name.
533 #
534 # @current: true if this alarm method is currently in use, false otherwise
535 #
536 # Since: 1.0
537 ##
538 { 'type': 'TimerAlarmMethod',
539   'data': { 'method-name': 'str', 'current': 'bool' } }
540
541 The command will be called "query-alarm-methods", here is its schema
542 specification:
543
544 ##
545 # @query-alarm-methods
546 #
547 # Returns information about available alarm methods.
548 #
549 # Returns: a list of @TimerAlarmMethod for each method
550 #
551 # Since: 1.0
552 ##
553 { 'command': 'query-alarm-methods', 'returns': ['TimerAlarmMethod'] }
554
555 Notice the syntax for returning lists "'returns': ['TimerAlarmMethod']", this
556 should be read as "returns a list of TimerAlarmMethod instances".
557
558 The C implementation follows:
559
560 TimerAlarmMethodList *qmp_query_alarm_methods(Error **errp)
561 {
562     TimerAlarmMethodList *method_list = NULL;
563     const struct qemu_alarm_timer *p;
564     bool current = true;
565
566     for (p = alarm_timers; p->name; p++) {
567         TimerAlarmMethodList *info = g_malloc0(sizeof(*info));
568         info->value = g_malloc0(sizeof(*info->value));
569         info->value->method_name = g_strdup(p->name);
570         info->value->current = current;
571
572         current = false;
573
574         info->next = method_list;
575         method_list = info;
576     }
577
578     return method_list;
579 }
580
581 The most important difference from the previous examples is the
582 TimerAlarmMethodList type, which is automatically generated by the QAPI from
583 the TimerAlarmMethod type.
584
585 Each list node is represented by a TimerAlarmMethodList instance. We have to
586 allocate it, and that's done inside the for loop: the "info" pointer points to
587 an allocated node. We also have to allocate the node's contents, which is
588 stored in its "value" member. In our example, the "value" member is a pointer
589 to an TimerAlarmMethod instance.
590
591 Notice that the "current" variable is used as "true" only in the first
592 interation of the loop. That's because the alarm timer method in use is the
593 first element of the alarm_timers array. Also notice that QAPI lists are handled
594 by hand and we return the head of the list.
595
596 To test this you have to add the corresponding qmp-commands.hx entry:
597
598     {
599         .name       = "query-alarm-methods",
600         .args_type  = "",
601         .mhandler.cmd_new = qmp_marshal_input_query_alarm_methods,
602     },
603
604 Now Build qemu, run it as explained in the "Testing" section and try our new
605 command:
606
607 { "execute": "query-alarm-methods" }
608 {
609     "return": [
610         {
611             "current": false, 
612             "method-name": "unix"
613         }, 
614         {
615             "current": true, 
616             "method-name": "dynticks"
617         }
618     ]
619 }
620
621 The HMP counterpart is a bit more complex than previous examples because it
622 has to traverse the list, it's shown below for reference:
623
624 void hmp_info_alarm_methods(Monitor *mon)
625 {
626     TimerAlarmMethodList *method_list, *method;
627     Error *errp = NULL;
628
629     method_list = qmp_query_alarm_methods(&errp);
630     if (error_is_set(&errp)) {
631         monitor_printf(mon, "Could not query alarm methods\n");
632         error_free(errp);
633         return;
634     }
635
636     for (method = method_list; method; method = method->next) {
637         monitor_printf(mon, "%c %s\n", method->value->current ? '*' : ' ',
638                                        method->value->method_name);
639     }
640
641     qapi_free_TimerAlarmMethodList(method_list);
642 }