1= How to write QMP commands using the QAPI framework = 2 3This document is a step-by-step guide on how to write new QMP commands using 4the QAPI framework. It also shows how to implement new style HMP commands. 5 6This document doesn't discuss QMP protocol level details, nor does it dive 7into the QAPI framework implementation. 8 9For an in-depth introduction to the QAPI framework, please refer to 10docs/qapi-code-gen.txt. For documentation about the QMP protocol, please 11check the files in QMP/. 12 13== Overview == 14 15Generally speaking, the following steps should be taken in order to write a 16new QMP command. 17 181. Write the command's and type(s) specification in the QAPI schema file 19 (qapi-schema.json in the root source directory) 20 212. 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 253. At this point the command can be tested under the QMP protocol 26 274. 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 31The following sections will demonstrate each of the steps above. We will start 32very simple and get more complex as we progress. 33 34=== Testing === 35 36For all the examples in the next sections, the test setup is the same and is 37shown here. 38 39First, 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 45Then, in a different terminal: 46 47$ telnet localhost 4444 48Trying 127.0.0.1... 49Connected to localhost. 50Escape 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 66The above output is the QMP server saying you're connected. The server is 67actually in capabilities negotiation mode. To enter in command mode type: 68 69{ "execute": "qmp_capabilities" } 70 71Then the server should respond: 72 73{ 74 "return": { 75 } 76} 77 78Which is QMP's way of saying "the latest command executed OK and didn't return 79any data". Now you're ready to enter the QMP example commands as explained in 80the following sections. 81 82== Writing a command that doesn't return data == 83 84That's the most simple QMP command that can be written. Usually, this kind of 85command carries some meaningful action in QEMU but here it will just print 86"Hello, world" to the standard output. 87 88Our command will be called "hello-world". It takes no arguments, nor does it 89return any data. 90 91The first step is to add the following line to the bottom of the 92qapi-schema.json file: 93 94{ 'command': 'hello-world' } 95 96The "command" keyword defines a new QMP command. It's an JSON object. All 97schema entries are JSON objects. The line above will instruct the QAPI to 98generate any prototypes and the necessary code to marshal and unmarshal 99protocol data. 100 101The next step is to write the "hello-world" implementation. As explained 102earlier, 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 105void qmp_hello_world(Error **errp) 106{ 107 printf("Hello, world!\n"); 108} 109 110There are a few things to be noticed: 111 1121. QMP command implementation functions must be prefixed with "qmp_" 1132. qmp_hello_world() returns void, this is in accordance with the fact that the 114 command doesn't return any data 1153. 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 1184. We won't add the function's prototype. That's automatically done by the QAPI 1195. 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 122Now a little hack is needed. As we're still using the old QMP server we need 123to add the new command to its internal dispatch table. This step won't be 124required in the near future. Open the qmp-commands.hx file and add the 125following at the bottom: 126 127 { 128 .name = "hello-world", 129 .args_type = "", 130 .mhandler.cmd_new = qmp_marshal_hello_world, 131 }, 132 133You're done. Now build qemu, run it as suggested in the "Testing" section, 134and then type the following QMP command: 135 136{ "execute": "hello-world" } 137 138Then check the terminal running qemu and look for the "Hello, world" string. If 139you don't see it then something went wrong. 140 141=== Arguments === 142 143Let's add an argument called "message" to our "hello-world" command. The new 144argument will contain the string to be printed to stdout. It's an optional 145argument, if it's not present we print our default "Hello, World" string. 146 147The first change we have to do is to modify the command specification in the 148schema file to the following: 149 150{ 'command': 'hello-world', 'data': { '*message': 'str' } } 151 152Notice the new 'data' member in the schema. It's an JSON object whose each 153element is an argument to the command in question. Also notice the asterisk, 154it's used to mark the argument optional (that means that you shouldn't use it 155for mandatory arguments). Finally, 'str' is the argument's type, which 156stands for "string". The QAPI also supports integers, booleans, enumerations 157and user defined types. 158 159Now, let's update our C implementation in qmp.c: 160 161void 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 170There are two important details to be noticed: 171 1721. All optional arguments are accompanied by a 'has_' boolean, which is set 173 if the optional argument is present or false otherwise 1742. The C implementation signature must follow the schema's argument ordering, 175 which is defined by the "data" member 176 177The 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_hello_world, 183 }, 184 185Notice 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 187according to the C implementation and schema file. You can look for more 188examples in the qmp-commands.hx file if you need to define more arguments. 189 190Again, this step won't be required in the future. 191 192Time to test our new version of the "hello-world" command. Build qemu, run it as 193described 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 207You should see "Hello, world" and "we love qemu" in the terminal running qemu, 208if you don't see these strings, then something went wrong. 209 210=== Errors === 211 212QMP commands should use the error interface exported by the error.h header 213file. Basically, most errors are set by calling the error_setg() function. 214 215Let's say we don't accept the string "message" to contain the word "love". If 216it does contain it, we want the "hello-world" command to return an error: 217 218void qmp_hello_world(bool has_message, const char *message, Error **errp) 219{ 220 if (has_message) { 221 if (strstr(message, "love")) { 222 error_setg(errp, "the word 'love' is not allowed"); 223 return; 224 } 225 printf("%s\n", message); 226 } else { 227 printf("Hello, world\n"); 228 } 229} 230 231The first argument to the error_setg() function is the Error pointer 232to pointer, which is passed to all QMP functions. The next argument is a human 233description of the error, this is a free-form printf-like string. 234 235Let's test the example above. Build qemu, run it as defined in the "Testing" 236section, and then issue the following command: 237 238{ "execute": "hello-world", "arguments": { "message": "all you need is love" } } 239 240The QMP server's response should be: 241 242{ 243 "error": { 244 "class": "GenericError", 245 "desc": "the word 'love' is not allowed" 246 } 247} 248 249As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR 250(done by default when using error_setg()). There are two exceptions to 251this rule: 252 253 1. A non-generic ErrorClass value exists* for the failure you want to report 254 (eg. DeviceNotFound) 255 256 2. Management applications have to take special action on the failure you 257 want to report, hence you have to add a new ErrorClass value so that they 258 can check for it 259 260If the failure you want to report falls into one of the two cases above, 261use error_set() with a second argument of an ErrorClass value. 262 263 * All existing ErrorClass values are defined in the qapi-schema.json file 264 265=== Command Documentation === 266 267There's only one step missing to make "hello-world"'s implementation complete, 268and that's its documentation in the schema file. 269 270This is very important. No QMP command will be accepted in QEMU without proper 271documentation. 272 273There are many examples of such documentation in the schema file already, but 274here goes "hello-world"'s new entry for the qapi-schema.json file: 275 276## 277# @hello-world 278# 279# Print a client provided string to the standard output stream. 280# 281# @message: #optional string to be printed 282# 283# Returns: Nothing on success. 284# 285# Notes: if @message is not provided, the "Hello, world" string will 286# be printed instead 287# 288# Since: <next qemu stable release, eg. 1.0> 289## 290{ 'command': 'hello-world', 'data': { '*message': 'str' } } 291 292Please, note that the "Returns" clause is optional if a command doesn't return 293any data nor any errors. 294 295=== Implementing the HMP command === 296 297Now that the QMP command is in place, we can also make it available in the human 298monitor (HMP). 299 300With the introduction of the QAPI, HMP commands make QMP calls. Most of the 301time HMP commands are simple wrappers. All HMP commands implementation exist in 302the hmp.c file. 303 304Here's the implementation of the "hello-world" HMP command: 305 306void hmp_hello_world(Monitor *mon, const QDict *qdict) 307{ 308 const char *message = qdict_get_try_str(qdict, "message"); 309 Error *err = NULL; 310 311 qmp_hello_world(!!message, message, &err); 312 if (err) { 313 monitor_printf(mon, "%s\n", error_get_pretty(err)); 314 error_free(err); 315 return; 316 } 317} 318 319Also, you have to add the function's prototype to the hmp.h file. 320 321There are three important points to be noticed: 322 3231. The "mon" and "qdict" arguments are mandatory for all HMP functions. The 324 former is the monitor object. The latter is how the monitor passes 325 arguments entered by the user to the command implementation 3262. hmp_hello_world() performs error checking. In this example we just print 327 the error description to the user, but we could do more, like taking 328 different actions depending on the error qmp_hello_world() returns 3293. The "err" variable must be initialized to NULL before performing the 330 QMP call 331 332There's one last step to actually make the command available to monitor users, 333we should add it to the hmp-commands.hx file: 334 335 { 336 .name = "hello-world", 337 .args_type = "message:s?", 338 .params = "hello-world [message]", 339 .help = "Print message to the standard output", 340 .mhandler.cmd = hmp_hello_world, 341 }, 342 343STEXI 344@item hello_world @var{message} 345@findex hello_world 346Print message to the standard output 347ETEXI 348 349To test this you have to open a user monitor and issue the "hello-world" 350command. It might be instructive to check the command's documentation with 351HMP's "help" command. 352 353Please, check the "-monitor" command-line option to know how to open a user 354monitor. 355 356== Writing a command that returns data == 357 358A QMP command is capable of returning any data the QAPI supports like integers, 359strings, booleans, enumerations and user defined types. 360 361In this section we will focus on user defined types. Please, check the QAPI 362documentation for information about the other types. 363 364=== User Defined Types === 365 366FIXME This example needs to be redone after commit 6d32717 367 368For this example we will write the query-alarm-clock command, which returns 369information about QEMU's timer alarm. For more information about it, please 370check the "-clock" command-line option. 371 372We want to return two pieces of information. The first one is the alarm clock's 373name. The second one is when the next alarm will fire. The former information is 374returned as a string, the latter is an integer in nanoseconds (which is not 375very useful in practice, as the timer has probably already fired when the 376information reaches the client). 377 378The best way to return that data is to create a new QAPI type, as shown below: 379 380## 381# @QemuAlarmClock 382# 383# QEMU alarm clock information. 384# 385# @clock-name: The alarm clock method's name. 386# 387# @next-deadline: #optional The time (in nanoseconds) the next alarm will fire. 388# 389# Since: 1.0 390## 391{ 'type': 'QemuAlarmClock', 392 'data': { 'clock-name': 'str', '*next-deadline': 'int' } } 393 394The "type" keyword defines a new QAPI type. Its "data" member contains the 395type's members. In this example our members are the "clock-name" and the 396"next-deadline" one, which is optional. 397 398Now let's define the query-alarm-clock command: 399 400## 401# @query-alarm-clock 402# 403# Return information about QEMU's alarm clock. 404# 405# Returns a @QemuAlarmClock instance describing the alarm clock method 406# being currently used by QEMU (this is usually set by the '-clock' 407# command-line option). 408# 409# Since: 1.0 410## 411{ 'command': 'query-alarm-clock', 'returns': 'QemuAlarmClock' } 412 413Notice the "returns" keyword. As its name suggests, it's used to define the 414data returned by a command. 415 416It's time to implement the qmp_query_alarm_clock() function, you can put it 417in the qemu-timer.c file: 418 419QemuAlarmClock *qmp_query_alarm_clock(Error **errp) 420{ 421 QemuAlarmClock *clock; 422 int64_t deadline; 423 424 clock = g_malloc0(sizeof(*clock)); 425 426 deadline = qemu_next_alarm_deadline(); 427 if (deadline > 0) { 428 clock->has_next_deadline = true; 429 clock->next_deadline = deadline; 430 } 431 clock->clock_name = g_strdup(alarm_timer->name); 432 433 return clock; 434} 435 436There are a number of things to be noticed: 437 4381. The QemuAlarmClock type is automatically generated by the QAPI framework, 439 its members correspond to the type's specification in the schema file 4402. As specified in the schema file, the function returns a QemuAlarmClock 441 instance and takes no arguments (besides the "errp" one, which is mandatory 442 for all QMP functions) 4433. The "clock" variable (which will point to our QAPI type instance) is 444 allocated by the regular g_malloc0() function. Note that we chose to 445 initialize the memory to zero. This is recommended for all QAPI types, as 446 it helps avoiding bad surprises (specially with booleans) 4474. Remember that "next_deadline" is optional? All optional members have a 448 'has_TYPE_NAME' member that should be properly set by the implementation, 449 as shown above 4505. Even static strings, such as "alarm_timer->name", should be dynamically 451 allocated by the implementation. This is so because the QAPI also generates 452 a function to free its types and it cannot distinguish between dynamically 453 or statically allocated strings 4546. You have to include the "qmp-commands.h" header file in qemu-timer.c, 455 otherwise qemu won't build 456 457The last step is to add the correspoding entry in the qmp-commands.hx file: 458 459 { 460 .name = "query-alarm-clock", 461 .args_type = "", 462 .mhandler.cmd_new = qmp_marshal_query_alarm_clock, 463 }, 464 465Time to test the new command. Build qemu, run it as described in the "Testing" 466section and try this: 467 468{ "execute": "query-alarm-clock" } 469{ 470 "return": { 471 "next-deadline": 2368219, 472 "clock-name": "dynticks" 473 } 474} 475 476==== The HMP command ==== 477 478Here's the HMP counterpart of the query-alarm-clock command: 479 480void hmp_info_alarm_clock(Monitor *mon) 481{ 482 QemuAlarmClock *clock; 483 Error *err = NULL; 484 485 clock = qmp_query_alarm_clock(&err); 486 if (err) { 487 monitor_printf(mon, "Could not query alarm clock information\n"); 488 error_free(err); 489 return; 490 } 491 492 monitor_printf(mon, "Alarm clock method in use: '%s'\n", clock->clock_name); 493 if (clock->has_next_deadline) { 494 monitor_printf(mon, "Next alarm will fire in %" PRId64 " nanoseconds\n", 495 clock->next_deadline); 496 } 497 498 qapi_free_QemuAlarmClock(clock); 499} 500 501It's important to notice that hmp_info_alarm_clock() calls 502qapi_free_QemuAlarmClock() to free the data returned by qmp_query_alarm_clock(). 503For user defined types, the QAPI will generate a qapi_free_QAPI_TYPE_NAME() 504function and that's what you have to use to free the types you define and 505qapi_free_QAPI_TYPE_NAMEList() for list types (explained in the next section). 506If the QMP call returns a string, then you should g_free() to free it. 507 508Also note that hmp_info_alarm_clock() performs error handling. That's not 509strictly required if you're sure the QMP function doesn't return errors, but 510it's good practice to always check for errors. 511 512Another important detail is that HMP's "info" commands don't go into the 513hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined 514in the monitor.c file. The entry for the "info alarmclock" follows: 515 516 { 517 .name = "alarmclock", 518 .args_type = "", 519 .params = "", 520 .help = "show information about the alarm clock", 521 .mhandler.info = hmp_info_alarm_clock, 522 }, 523 524To test this, run qemu and type "info alarmclock" in the user monitor. 525 526=== Returning Lists === 527 528For this example, we're going to return all available methods for the timer 529alarm, which is pretty much what the command-line option "-clock ?" does, 530except that we're also going to inform which method is in use. 531 532This first step is to define a new type: 533 534## 535# @TimerAlarmMethod 536# 537# Timer alarm method information. 538# 539# @method-name: The method's name. 540# 541# @current: true if this alarm method is currently in use, false otherwise 542# 543# Since: 1.0 544## 545{ 'type': 'TimerAlarmMethod', 546 'data': { 'method-name': 'str', 'current': 'bool' } } 547 548The command will be called "query-alarm-methods", here is its schema 549specification: 550 551## 552# @query-alarm-methods 553# 554# Returns information about available alarm methods. 555# 556# Returns: a list of @TimerAlarmMethod for each method 557# 558# Since: 1.0 559## 560{ 'command': 'query-alarm-methods', 'returns': ['TimerAlarmMethod'] } 561 562Notice the syntax for returning lists "'returns': ['TimerAlarmMethod']", this 563should be read as "returns a list of TimerAlarmMethod instances". 564 565The C implementation follows: 566 567TimerAlarmMethodList *qmp_query_alarm_methods(Error **errp) 568{ 569 TimerAlarmMethodList *method_list = NULL; 570 const struct qemu_alarm_timer *p; 571 bool current = true; 572 573 for (p = alarm_timers; p->name; p++) { 574 TimerAlarmMethodList *info = g_malloc0(sizeof(*info)); 575 info->value = g_malloc0(sizeof(*info->value)); 576 info->value->method_name = g_strdup(p->name); 577 info->value->current = current; 578 579 current = false; 580 581 info->next = method_list; 582 method_list = info; 583 } 584 585 return method_list; 586} 587 588The most important difference from the previous examples is the 589TimerAlarmMethodList type, which is automatically generated by the QAPI from 590the TimerAlarmMethod type. 591 592Each list node is represented by a TimerAlarmMethodList instance. We have to 593allocate it, and that's done inside the for loop: the "info" pointer points to 594an allocated node. We also have to allocate the node's contents, which is 595stored in its "value" member. In our example, the "value" member is a pointer 596to an TimerAlarmMethod instance. 597 598Notice that the "current" variable is used as "true" only in the first 599iteration of the loop. That's because the alarm timer method in use is the 600first element of the alarm_timers array. Also notice that QAPI lists are handled 601by hand and we return the head of the list. 602 603To test this you have to add the corresponding qmp-commands.hx entry: 604 605 { 606 .name = "query-alarm-methods", 607 .args_type = "", 608 .mhandler.cmd_new = qmp_marshal_query_alarm_methods, 609 }, 610 611Now Build qemu, run it as explained in the "Testing" section and try our new 612command: 613 614{ "execute": "query-alarm-methods" } 615{ 616 "return": [ 617 { 618 "current": false, 619 "method-name": "unix" 620 }, 621 { 622 "current": true, 623 "method-name": "dynticks" 624 } 625 ] 626} 627 628The HMP counterpart is a bit more complex than previous examples because it 629has to traverse the list, it's shown below for reference: 630 631void hmp_info_alarm_methods(Monitor *mon) 632{ 633 TimerAlarmMethodList *method_list, *method; 634 Error *err = NULL; 635 636 method_list = qmp_query_alarm_methods(&err); 637 if (err) { 638 monitor_printf(mon, "Could not query alarm methods\n"); 639 error_free(err); 640 return; 641 } 642 643 for (method = method_list; method; method = method->next) { 644 monitor_printf(mon, "%c %s\n", method->value->current ? '*' : ' ', 645 method->value->method_name); 646 } 647 648 qapi_free_TimerAlarmMethodList(method_list); 649} 650