1 /* 2 * QTest 3 * 4 * Copyright IBM, Corp. 2012 5 * Copyright Red Hat, Inc. 2012 6 * Copyright SUSE LINUX Products GmbH 2013 7 * 8 * Authors: 9 * Anthony Liguori <aliguori@us.ibm.com> 10 * Paolo Bonzini <pbonzini@redhat.com> 11 * Andreas Färber <afaerber@suse.de> 12 * 13 * This work is licensed under the terms of the GNU GPL, version 2 or later. 14 * See the COPYING file in the top-level directory. 15 * 16 */ 17 #ifndef LIBQTEST_H 18 #define LIBQTEST_H 19 20 #include "qapi/qmp/qobject.h" 21 #include "qapi/qmp/qdict.h" 22 #include "libqmp.h" 23 24 typedef struct QTestState QTestState; 25 26 /** 27 * qtest_initf: 28 * @fmt: Format for creating other arguments to pass to QEMU, formatted 29 * like sprintf(). 30 * 31 * Convenience wrapper around qtest_init(). 32 * 33 * Returns: #QTestState instance. 34 */ 35 QTestState *qtest_initf(const char *fmt, ...) G_GNUC_PRINTF(1, 2); 36 37 /** 38 * qtest_vinitf: 39 * @fmt: Format for creating other arguments to pass to QEMU, formatted 40 * like vsprintf(). 41 * @ap: Format arguments. 42 * 43 * Convenience wrapper around qtest_init(). 44 * 45 * Returns: #QTestState instance. 46 */ 47 QTestState *qtest_vinitf(const char *fmt, va_list ap) G_GNUC_PRINTF(1, 0); 48 49 /** 50 * qtest_init: 51 * @extra_args: other arguments to pass to QEMU. CAUTION: these 52 * arguments are subject to word splitting and shell evaluation. 53 * 54 * Returns: #QTestState instance. 55 */ 56 QTestState *qtest_init(const char *extra_args); 57 58 /** 59 * qtest_init_without_qmp_handshake: 60 * @extra_args: other arguments to pass to QEMU. CAUTION: these 61 * arguments are subject to word splitting and shell evaluation. 62 * 63 * Returns: #QTestState instance. 64 */ 65 QTestState *qtest_init_without_qmp_handshake(const char *extra_args); 66 67 /** 68 * qtest_init_with_serial: 69 * @extra_args: other arguments to pass to QEMU. CAUTION: these 70 * arguments are subject to word splitting and shell evaluation. 71 * @sock_fd: pointer to store the socket file descriptor for 72 * connection with serial. 73 * 74 * Returns: #QTestState instance. 75 */ 76 QTestState *qtest_init_with_serial(const char *extra_args, int *sock_fd); 77 78 /** 79 * qtest_wait_qemu: 80 * @s: #QTestState instance to operate on. 81 * 82 * Wait for the QEMU process to terminate. It is safe to call this function 83 * multiple times. 84 */ 85 void qtest_wait_qemu(QTestState *s); 86 87 /** 88 * qtest_kill_qemu: 89 * @s: #QTestState instance to operate on. 90 * 91 * Kill the QEMU process and wait for it to terminate. It is safe to call this 92 * function multiple times. Normally qtest_quit() is used instead because it 93 * also frees QTestState. Use qtest_kill_qemu() when you just want to kill QEMU 94 * and qtest_quit() will be called later. 95 */ 96 void qtest_kill_qemu(QTestState *s); 97 98 /** 99 * qtest_quit: 100 * @s: #QTestState instance to operate on. 101 * 102 * Shut down the QEMU process associated to @s. 103 */ 104 void qtest_quit(QTestState *s); 105 106 #ifndef _WIN32 107 /** 108 * qtest_qmp_fds: 109 * @s: #QTestState instance to operate on. 110 * @fds: array of file descriptors 111 * @fds_num: number of elements in @fds 112 * @fmt: QMP message to send to qemu, formatted like 113 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 114 * supported after '%'. 115 * 116 * Sends a QMP message to QEMU with fds and returns the response. 117 */ 118 QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num, 119 const char *fmt, ...) 120 G_GNUC_PRINTF(4, 5); 121 #endif /* _WIN32 */ 122 123 /** 124 * qtest_qmp: 125 * @s: #QTestState instance to operate on. 126 * @fmt: QMP message to send to qemu, formatted like 127 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 128 * supported after '%'. 129 * 130 * Sends a QMP message to QEMU and returns the response. 131 */ 132 QDict *qtest_qmp(QTestState *s, const char *fmt, ...) 133 G_GNUC_PRINTF(2, 3); 134 135 /** 136 * qtest_qmp_send: 137 * @s: #QTestState instance to operate on. 138 * @fmt: QMP message to send to qemu, formatted like 139 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 140 * supported after '%'. 141 * 142 * Sends a QMP message to QEMU and leaves the response in the stream. 143 */ 144 void qtest_qmp_send(QTestState *s, const char *fmt, ...) 145 G_GNUC_PRINTF(2, 3); 146 147 /** 148 * qtest_qmp_send_raw: 149 * @s: #QTestState instance to operate on. 150 * @fmt: text to send, formatted like sprintf() 151 * 152 * Sends text to the QMP monitor verbatim. Need not be valid JSON; 153 * this is useful for negative tests. 154 */ 155 void qtest_qmp_send_raw(QTestState *s, const char *fmt, ...) 156 G_GNUC_PRINTF(2, 3); 157 158 /** 159 * qtest_socket_server: 160 * @socket_path: the UNIX domain socket path 161 * 162 * Create and return a listen socket file descriptor, or abort on failure. 163 */ 164 int qtest_socket_server(const char *socket_path); 165 166 #ifndef _WIN32 167 /** 168 * qtest_vqmp_fds: 169 * @s: #QTestState instance to operate on. 170 * @fds: array of file descriptors 171 * @fds_num: number of elements in @fds 172 * @fmt: QMP message to send to QEMU, formatted like 173 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 174 * supported after '%'. 175 * @ap: QMP message arguments 176 * 177 * Sends a QMP message to QEMU with fds and returns the response. 178 */ 179 QDict *qtest_vqmp_fds(QTestState *s, int *fds, size_t fds_num, 180 const char *fmt, va_list ap) 181 G_GNUC_PRINTF(4, 0); 182 #endif /* _WIN32 */ 183 184 /** 185 * qtest_vqmp: 186 * @s: #QTestState instance to operate on. 187 * @fmt: QMP message to send to QEMU, formatted like 188 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 189 * supported after '%'. 190 * @ap: QMP message arguments 191 * 192 * Sends a QMP message to QEMU and returns the response. 193 */ 194 QDict *qtest_vqmp(QTestState *s, const char *fmt, va_list ap) 195 G_GNUC_PRINTF(2, 0); 196 197 #ifndef _WIN32 198 /** 199 * qtest_qmp_vsend_fds: 200 * @s: #QTestState instance to operate on. 201 * @fds: array of file descriptors 202 * @fds_num: number of elements in @fds 203 * @fmt: QMP message to send to QEMU, formatted like 204 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 205 * supported after '%'. 206 * @ap: QMP message arguments 207 * 208 * Sends a QMP message to QEMU and leaves the response in the stream. 209 */ 210 void qtest_qmp_vsend_fds(QTestState *s, int *fds, size_t fds_num, 211 const char *fmt, va_list ap) 212 G_GNUC_PRINTF(4, 0); 213 #endif /* _WIN32 */ 214 215 /** 216 * qtest_qmp_vsend: 217 * @s: #QTestState instance to operate on. 218 * @fmt: QMP message to send to QEMU, formatted like 219 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 220 * supported after '%'. 221 * @ap: QMP message arguments 222 * 223 * Sends a QMP message to QEMU and leaves the response in the stream. 224 */ 225 void qtest_qmp_vsend(QTestState *s, const char *fmt, va_list ap) 226 G_GNUC_PRINTF(2, 0); 227 228 /** 229 * qtest_qmp_receive_dict: 230 * @s: #QTestState instance to operate on. 231 * 232 * Reads a QMP message from QEMU and returns the response. 233 */ 234 QDict *qtest_qmp_receive_dict(QTestState *s); 235 236 /** 237 * qtest_qmp_receive: 238 * @s: #QTestState instance to operate on. 239 * 240 * Reads a QMP message from QEMU and returns the response. 241 * 242 * If a callback is registered with qtest_qmp_set_event_callback, 243 * it will be invoked for every event seen, otherwise events 244 * will be buffered until a call to one of the qtest_qmp_eventwait 245 * family of functions. 246 */ 247 QDict *qtest_qmp_receive(QTestState *s); 248 249 /* 250 * QTestQMPEventCallback: 251 * @s: #QTestState instance event was received on 252 * @name: name of the event type 253 * @event: #QDict for the event details 254 * @opaque: opaque data from time of callback registration 255 * 256 * This callback will be invoked whenever an event is received. 257 * If the callback returns true the event will be consumed, 258 * otherwise it will be put on the list of pending events. 259 * Pending events can be later handled by calling either 260 * qtest_qmp_eventwait or qtest_qmp_eventwait_ref. 261 * 262 * Return: true to consume the event, false to let it be queued 263 */ 264 typedef bool (*QTestQMPEventCallback)(QTestState *s, const char *name, 265 QDict *event, void *opaque); 266 267 /** 268 * qtest_qmp_set_event_callback: 269 * @s: #QTestSTate instance to operate on 270 * @cb: callback to invoke for events 271 * @opaque: data to pass to @cb 272 * 273 * Register a callback to be invoked whenever an event arrives 274 */ 275 void qtest_qmp_set_event_callback(QTestState *s, 276 QTestQMPEventCallback cb, void *opaque); 277 278 /** 279 * qtest_qmp_eventwait: 280 * @s: #QTestState instance to operate on. 281 * @event: event to wait for. 282 * 283 * Continuously polls for QMP responses until it receives the desired event. 284 * 285 * Any callback registered with qtest_qmp_set_event_callback will 286 * be invoked for every event seen. 287 */ 288 void qtest_qmp_eventwait(QTestState *s, const char *event); 289 290 /** 291 * qtest_qmp_eventwait_ref: 292 * @s: #QTestState instance to operate on. 293 * @event: event to wait for. 294 * 295 * Continuously polls for QMP responses until it receives the desired event. 296 * 297 * Any callback registered with qtest_qmp_set_event_callback will 298 * be invoked for every event seen. 299 * 300 * Returns a copy of the event for further investigation. 301 */ 302 QDict *qtest_qmp_eventwait_ref(QTestState *s, const char *event); 303 304 /** 305 * qtest_qmp_event_ref: 306 * @s: #QTestState instance to operate on. 307 * @event: event to return. 308 * 309 * Removes non-matching events from the buffer that was set by 310 * qtest_qmp_receive, until an event bearing the given name is found, 311 * and returns it. 312 * If no event matches, clears the buffer and returns NULL. 313 * 314 */ 315 QDict *qtest_qmp_event_ref(QTestState *s, const char *event); 316 317 /** 318 * qtest_hmp: 319 * @s: #QTestState instance to operate on. 320 * @fmt: HMP command to send to QEMU, formats arguments like sprintf(). 321 * 322 * Send HMP command to QEMU via QMP's human-monitor-command. 323 * QMP events are discarded. 324 * 325 * Returns: the command's output. The caller should g_free() it. 326 */ 327 char *qtest_hmp(QTestState *s, const char *fmt, ...) G_GNUC_PRINTF(2, 3); 328 329 /** 330 * qtest_hmpv: 331 * @s: #QTestState instance to operate on. 332 * @fmt: HMP command to send to QEMU, formats arguments like vsprintf(). 333 * @ap: HMP command arguments 334 * 335 * Send HMP command to QEMU via QMP's human-monitor-command. 336 * QMP events are discarded. 337 * 338 * Returns: the command's output. The caller should g_free() it. 339 */ 340 char *qtest_vhmp(QTestState *s, const char *fmt, va_list ap) 341 G_GNUC_PRINTF(2, 0); 342 343 void qtest_module_load(QTestState *s, const char *prefix, const char *libname); 344 345 /** 346 * qtest_get_irq: 347 * @s: #QTestState instance to operate on. 348 * @num: Interrupt to observe. 349 * 350 * Returns: The level of the @num interrupt. 351 */ 352 bool qtest_get_irq(QTestState *s, int num); 353 354 /** 355 * qtest_irq_intercept_in: 356 * @s: #QTestState instance to operate on. 357 * @string: QOM path of a device. 358 * 359 * Associate qtest irqs with the GPIO-in pins of the device 360 * whose path is specified by @string. 361 */ 362 void qtest_irq_intercept_in(QTestState *s, const char *string); 363 364 /** 365 * qtest_irq_intercept_out: 366 * @s: #QTestState instance to operate on. 367 * @string: QOM path of a device. 368 * 369 * Associate qtest irqs with the GPIO-out pins of the device 370 * whose path is specified by @string. 371 */ 372 void qtest_irq_intercept_out(QTestState *s, const char *string); 373 374 /** 375 * qtest_irq_intercept_out_named: 376 * @s: #QTestState instance to operate on. 377 * @qom_path: QOM path of a device. 378 * @name: Name of the GPIO out pin 379 * 380 * Associate a qtest irq with the named GPIO-out pin of the device 381 * whose path is specified by @string and whose name is @name. 382 */ 383 void qtest_irq_intercept_out_named(QTestState *s, const char *qom_path, const char *name); 384 385 /** 386 * qtest_set_irq_in: 387 * @s: QTestState instance to operate on. 388 * @string: QOM path of a device 389 * @name: IRQ name 390 * @irq: IRQ number 391 * @level: IRQ level 392 * 393 * Force given device/irq GPIO-in pin to the given level. 394 */ 395 void qtest_set_irq_in(QTestState *s, const char *string, const char *name, 396 int irq, int level); 397 398 /** 399 * qtest_outb: 400 * @s: #QTestState instance to operate on. 401 * @addr: I/O port to write to. 402 * @value: Value being written. 403 * 404 * Write an 8-bit value to an I/O port. 405 */ 406 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value); 407 408 /** 409 * qtest_outw: 410 * @s: #QTestState instance to operate on. 411 * @addr: I/O port to write to. 412 * @value: Value being written. 413 * 414 * Write a 16-bit value to an I/O port. 415 */ 416 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value); 417 418 /** 419 * qtest_outl: 420 * @s: #QTestState instance to operate on. 421 * @addr: I/O port to write to. 422 * @value: Value being written. 423 * 424 * Write a 32-bit value to an I/O port. 425 */ 426 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value); 427 428 /** 429 * qtest_inb: 430 * @s: #QTestState instance to operate on. 431 * @addr: I/O port to read from. 432 * 433 * Returns an 8-bit value from an I/O port. 434 */ 435 uint8_t qtest_inb(QTestState *s, uint16_t addr); 436 437 /** 438 * qtest_inw: 439 * @s: #QTestState instance to operate on. 440 * @addr: I/O port to read from. 441 * 442 * Returns a 16-bit value from an I/O port. 443 */ 444 uint16_t qtest_inw(QTestState *s, uint16_t addr); 445 446 /** 447 * qtest_inl: 448 * @s: #QTestState instance to operate on. 449 * @addr: I/O port to read from. 450 * 451 * Returns a 32-bit value from an I/O port. 452 */ 453 uint32_t qtest_inl(QTestState *s, uint16_t addr); 454 455 /** 456 * qtest_writeb: 457 * @s: #QTestState instance to operate on. 458 * @addr: Guest address to write to. 459 * @value: Value being written. 460 * 461 * Writes an 8-bit value to memory. 462 */ 463 void qtest_writeb(QTestState *s, uint64_t addr, uint8_t value); 464 465 /** 466 * qtest_writew: 467 * @s: #QTestState instance to operate on. 468 * @addr: Guest address to write to. 469 * @value: Value being written. 470 * 471 * Writes a 16-bit value to memory. 472 */ 473 void qtest_writew(QTestState *s, uint64_t addr, uint16_t value); 474 475 /** 476 * qtest_writel: 477 * @s: #QTestState instance to operate on. 478 * @addr: Guest address to write to. 479 * @value: Value being written. 480 * 481 * Writes a 32-bit value to memory. 482 */ 483 void qtest_writel(QTestState *s, uint64_t addr, uint32_t value); 484 485 /** 486 * qtest_writeq: 487 * @s: #QTestState instance to operate on. 488 * @addr: Guest address to write to. 489 * @value: Value being written. 490 * 491 * Writes a 64-bit value to memory. 492 */ 493 void qtest_writeq(QTestState *s, uint64_t addr, uint64_t value); 494 495 /** 496 * qtest_readb: 497 * @s: #QTestState instance to operate on. 498 * @addr: Guest address to read from. 499 * 500 * Reads an 8-bit value from memory. 501 * 502 * Returns: Value read. 503 */ 504 uint8_t qtest_readb(QTestState *s, uint64_t addr); 505 506 /** 507 * qtest_readw: 508 * @s: #QTestState instance to operate on. 509 * @addr: Guest address to read from. 510 * 511 * Reads a 16-bit value from memory. 512 * 513 * Returns: Value read. 514 */ 515 uint16_t qtest_readw(QTestState *s, uint64_t addr); 516 517 /** 518 * qtest_readl: 519 * @s: #QTestState instance to operate on. 520 * @addr: Guest address to read from. 521 * 522 * Reads a 32-bit value from memory. 523 * 524 * Returns: Value read. 525 */ 526 uint32_t qtest_readl(QTestState *s, uint64_t addr); 527 528 /** 529 * qtest_readq: 530 * @s: #QTestState instance to operate on. 531 * @addr: Guest address to read from. 532 * 533 * Reads a 64-bit value from memory. 534 * 535 * Returns: Value read. 536 */ 537 uint64_t qtest_readq(QTestState *s, uint64_t addr); 538 539 /** 540 * qtest_memread: 541 * @s: #QTestState instance to operate on. 542 * @addr: Guest address to read from. 543 * @data: Pointer to where memory contents will be stored. 544 * @size: Number of bytes to read. 545 * 546 * Read guest memory into a buffer. 547 */ 548 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size); 549 550 /** 551 * qtest_rtas_call: 552 * @s: #QTestState instance to operate on. 553 * @name: name of the command to call. 554 * @nargs: Number of args. 555 * @args: Guest address to read args from. 556 * @nret: Number of return value. 557 * @ret: Guest address to write return values to. 558 * 559 * Call an RTAS function 560 */ 561 uint64_t qtest_rtas_call(QTestState *s, const char *name, 562 uint32_t nargs, uint64_t args, 563 uint32_t nret, uint64_t ret); 564 565 /** 566 * qtest_bufread: 567 * @s: #QTestState instance to operate on. 568 * @addr: Guest address to read from. 569 * @data: Pointer to where memory contents will be stored. 570 * @size: Number of bytes to read. 571 * 572 * Read guest memory into a buffer and receive using a base64 encoding. 573 */ 574 void qtest_bufread(QTestState *s, uint64_t addr, void *data, size_t size); 575 576 /** 577 * qtest_memwrite: 578 * @s: #QTestState instance to operate on. 579 * @addr: Guest address to write to. 580 * @data: Pointer to the bytes that will be written to guest memory. 581 * @size: Number of bytes to write. 582 * 583 * Write a buffer to guest memory. 584 */ 585 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size); 586 587 /** 588 * qtest_bufwrite: 589 * @s: #QTestState instance to operate on. 590 * @addr: Guest address to write to. 591 * @data: Pointer to the bytes that will be written to guest memory. 592 * @size: Number of bytes to write. 593 * 594 * Write a buffer to guest memory and transmit using a base64 encoding. 595 */ 596 void qtest_bufwrite(QTestState *s, uint64_t addr, 597 const void *data, size_t size); 598 599 /** 600 * qtest_memset: 601 * @s: #QTestState instance to operate on. 602 * @addr: Guest address to write to. 603 * @patt: Byte pattern to fill the guest memory region with. 604 * @size: Number of bytes to write. 605 * 606 * Write a pattern to guest memory. 607 */ 608 void qtest_memset(QTestState *s, uint64_t addr, uint8_t patt, size_t size); 609 610 /** 611 * qtest_clock_step_next: 612 * @s: #QTestState instance to operate on. 613 * 614 * Advance the QEMU_CLOCK_VIRTUAL to the next deadline. 615 * 616 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds. 617 */ 618 int64_t qtest_clock_step_next(QTestState *s); 619 620 /** 621 * qtest_clock_step: 622 * @s: QTestState instance to operate on. 623 * @step: Number of nanoseconds to advance the clock by. 624 * 625 * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds. 626 * 627 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds. 628 */ 629 int64_t qtest_clock_step(QTestState *s, int64_t step); 630 631 /** 632 * qtest_clock_set: 633 * @s: QTestState instance to operate on. 634 * @val: Nanoseconds value to advance the clock to. 635 * 636 * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched. 637 * 638 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds. 639 */ 640 int64_t qtest_clock_set(QTestState *s, int64_t val); 641 642 /** 643 * qtest_big_endian: 644 * @s: QTestState instance to operate on. 645 * 646 * Returns: True if the architecture under test has a big endian configuration. 647 */ 648 bool qtest_big_endian(QTestState *s); 649 650 /** 651 * qtest_get_arch: 652 * 653 * Returns: The architecture for the QEMU executable under test. 654 */ 655 const char *qtest_get_arch(void); 656 657 /** 658 * qtest_has_accel: 659 * @accel_name: Accelerator name to check for. 660 * 661 * Returns: true if the accelerator is built in. 662 */ 663 bool qtest_has_accel(const char *accel_name); 664 665 /** 666 * qtest_add_func: 667 * @str: Test case path. 668 * @fn: Test case function 669 * 670 * Add a GTester testcase with the given name and function. 671 * The path is prefixed with the architecture under test, as 672 * returned by qtest_get_arch(). 673 */ 674 void qtest_add_func(const char *str, void (*fn)(void)); 675 676 /** 677 * qtest_add_data_func: 678 * @str: Test case path. 679 * @data: Test case data 680 * @fn: Test case function 681 * 682 * Add a GTester testcase with the given name, data and function. 683 * The path is prefixed with the architecture under test, as 684 * returned by qtest_get_arch(). 685 */ 686 void qtest_add_data_func(const char *str, const void *data, 687 void (*fn)(const void *)); 688 689 /** 690 * qtest_add_data_func_full: 691 * @str: Test case path. 692 * @data: Test case data 693 * @fn: Test case function 694 * @data_free_func: GDestroyNotify for data 695 * 696 * Add a GTester testcase with the given name, data and function. 697 * The path is prefixed with the architecture under test, as 698 * returned by qtest_get_arch(). 699 * 700 * @data is passed to @data_free_func() on test completion. 701 */ 702 void qtest_add_data_func_full(const char *str, void *data, 703 void (*fn)(const void *), 704 GDestroyNotify data_free_func); 705 706 /** 707 * qtest_add: 708 * @testpath: Test case path 709 * @Fixture: Fixture type 710 * @tdata: Test case data 711 * @fsetup: Test case setup function 712 * @ftest: Test case function 713 * @fteardown: Test case teardown function 714 * 715 * Add a GTester testcase with the given name, data and functions. 716 * The path is prefixed with the architecture under test, as 717 * returned by qtest_get_arch(). 718 */ 719 #define qtest_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \ 720 do { \ 721 char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \ 722 g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \ 723 g_free(path); \ 724 } while (0) 725 726 /** 727 * qtest_add_abrt_handler: 728 * @fn: Handler function 729 * @data: Argument that is passed to the handler 730 * 731 * Add a handler function that is invoked on SIGABRT. This can be used to 732 * terminate processes and perform other cleanup. The handler can be removed 733 * with qtest_remove_abrt_handler(). 734 */ 735 void qtest_add_abrt_handler(GHookFunc fn, const void *data); 736 737 /** 738 * qtest_remove_abrt_handler: 739 * @data: Argument previously passed to qtest_add_abrt_handler() 740 * 741 * Remove an abrt handler that was previously added with 742 * qtest_add_abrt_handler(). 743 */ 744 void qtest_remove_abrt_handler(void *data); 745 746 /** 747 * qtest_vqmp_assert_success_ref: 748 * @qts: QTestState instance to operate on 749 * @fmt: QMP message to send to qemu, formatted like 750 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 751 * supported after '%'. 752 * @args: variable arguments for @fmt 753 * 754 * Sends a QMP message to QEMU, asserts that a 'return' key is present in 755 * the response, and returns the response. 756 */ 757 QDict *qtest_vqmp_assert_success_ref(QTestState *qts, 758 const char *fmt, va_list args) 759 G_GNUC_PRINTF(2, 0); 760 761 /** 762 * qtest_vqmp_assert_success: 763 * @qts: QTestState instance to operate on 764 * @fmt: QMP message to send to qemu, formatted like 765 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 766 * supported after '%'. 767 * @args: variable arguments for @fmt 768 * 769 * Sends a QMP message to QEMU and asserts that a 'return' key is present in 770 * the response. 771 */ 772 void qtest_vqmp_assert_success(QTestState *qts, 773 const char *fmt, va_list args) 774 G_GNUC_PRINTF(2, 0); 775 776 #ifndef _WIN32 777 /** 778 * qtest_vqmp_fds_assert_success_ref: 779 * @qts: QTestState instance to operate on 780 * @fds: the file descriptors to send 781 * @nfds: number of @fds to send 782 * @fmt: QMP message to send to qemu, formatted like 783 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 784 * supported after '%'. 785 * @args: variable arguments for @fmt 786 * 787 * Sends a QMP message with file descriptors to QEMU, 788 * asserts that a 'return' key is present in the response, 789 * and returns the response. 790 */ 791 QDict *qtest_vqmp_fds_assert_success_ref(QTestState *qts, int *fds, size_t nfds, 792 const char *fmt, va_list args) 793 G_GNUC_PRINTF(4, 0); 794 795 /** 796 * qtest_vqmp_fds_assert_success: 797 * @qts: QTestState instance to operate on 798 * @fds: the file descriptors to send 799 * @nfds: number of @fds to send 800 * @fmt: QMP message to send to qemu, formatted like 801 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 802 * supported after '%'. 803 * @args: variable arguments for @fmt 804 * 805 * Sends a QMP message with file descriptors to QEMU and 806 * asserts that a 'return' key is present in the response. 807 */ 808 void qtest_vqmp_fds_assert_success(QTestState *qts, int *fds, size_t nfds, 809 const char *fmt, va_list args) 810 G_GNUC_PRINTF(4, 0); 811 #endif /* !_WIN32 */ 812 813 /** 814 * qtest_qmp_assert_failure_ref: 815 * @qts: QTestState instance to operate on 816 * @fmt: QMP message to send to qemu, formatted like 817 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 818 * supported after '%'. 819 * 820 * Sends a QMP message to QEMU, asserts that an 'error' key is present in 821 * the response, and returns the response. 822 */ 823 QDict *qtest_qmp_assert_failure_ref(QTestState *qts, const char *fmt, ...) 824 G_GNUC_PRINTF(2, 3); 825 826 /** 827 * qtest_vqmp_assert_failure_ref: 828 * @qts: QTestState instance to operate on 829 * @fmt: QMP message to send to qemu, formatted like 830 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 831 * supported after '%'. 832 * @args: variable arguments for @fmt 833 * 834 * Sends a QMP message to QEMU, asserts that an 'error' key is present in 835 * the response, and returns the response. 836 */ 837 QDict *qtest_vqmp_assert_failure_ref(QTestState *qts, 838 const char *fmt, va_list args) 839 G_GNUC_PRINTF(2, 0); 840 841 /** 842 * qtest_qmp_assert_success_ref: 843 * @qts: QTestState instance to operate on 844 * @fmt: QMP message to send to qemu, formatted like 845 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 846 * supported after '%'. 847 * 848 * Sends a QMP message to QEMU, asserts that a 'return' key is present in 849 * the response, and returns the response. 850 */ 851 QDict *qtest_qmp_assert_success_ref(QTestState *qts, const char *fmt, ...) 852 G_GNUC_PRINTF(2, 3); 853 854 /** 855 * qtest_qmp_assert_success: 856 * @qts: QTestState instance to operate on 857 * @fmt: QMP message to send to qemu, formatted like 858 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 859 * supported after '%'. 860 * 861 * Sends a QMP message to QEMU and asserts that a 'return' key is present in 862 * the response. 863 */ 864 void qtest_qmp_assert_success(QTestState *qts, const char *fmt, ...) 865 G_GNUC_PRINTF(2, 3); 866 867 #ifndef _WIN32 868 /** 869 * qtest_qmp_fd_assert_success_ref: 870 * @qts: QTestState instance to operate on 871 * @fds: the file descriptors to send 872 * @nfds: number of @fds to send 873 * @fmt: QMP message to send to qemu, formatted like 874 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 875 * supported after '%'. 876 * 877 * Sends a QMP message with file descriptors to QEMU, 878 * asserts that a 'return' key is present in the response, 879 * and returns the response. 880 */ 881 QDict *qtest_qmp_fds_assert_success_ref(QTestState *qts, int *fds, size_t nfds, 882 const char *fmt, ...) 883 G_GNUC_PRINTF(4, 5); 884 885 /** 886 * qtest_qmp_fd_assert_success: 887 * @qts: QTestState instance to operate on 888 * @fds: the file descriptors to send 889 * @nfds: number of @fds to send 890 * @fmt: QMP message to send to qemu, formatted like 891 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 892 * supported after '%'. 893 * 894 * Sends a QMP message with file descriptors to QEMU and 895 * asserts that a 'return' key is present in the response. 896 */ 897 void qtest_qmp_fds_assert_success(QTestState *qts, int *fds, size_t nfds, 898 const char *fmt, ...) 899 G_GNUC_PRINTF(4, 5); 900 #endif /* !_WIN32 */ 901 902 /** 903 * qtest_cb_for_every_machine: 904 * @cb: Pointer to the callback function 905 * @skip_old_versioned: true if versioned old machine types should be skipped 906 * 907 * Call a callback function for every name of all available machines. 908 */ 909 void qtest_cb_for_every_machine(void (*cb)(const char *machine), 910 bool skip_old_versioned); 911 912 /** 913 * qtest_has_machine: 914 * @machine: The machine to look for 915 * 916 * Returns: true if the machine is available in the target binary. 917 */ 918 bool qtest_has_machine(const char *machine); 919 920 /** 921 * qtest_has_device: 922 * @device: The device to look for 923 * 924 * Returns: true if the device is available in the target binary. 925 */ 926 bool qtest_has_device(const char *device); 927 928 /** 929 * qtest_qmp_device_add_qdict: 930 * @qts: QTestState instance to operate on 931 * @drv: Name of the device that should be added 932 * @arguments: QDict with properties for the device to initialize 933 * 934 * Generic hot-plugging test via the device_add QMP command with properties 935 * supplied in form of QDict. Use NULL for empty properties list. 936 */ 937 void qtest_qmp_device_add_qdict(QTestState *qts, const char *drv, 938 const QDict *arguments); 939 940 /** 941 * qtest_qmp_device_add: 942 * @qts: QTestState instance to operate on 943 * @driver: Name of the device that should be added 944 * @id: Identification string 945 * @fmt: QMP message to send to qemu, formatted like 946 * qobject_from_jsonf_nofail(). See parse_interpolation() for what's 947 * supported after '%'. 948 * 949 * Generic hot-plugging test via the device_add QMP command. 950 */ 951 void qtest_qmp_device_add(QTestState *qts, const char *driver, const char *id, 952 const char *fmt, ...) G_GNUC_PRINTF(4, 5); 953 954 /** 955 * qtest_qmp_add_client: 956 * @qts: QTestState instance to operate on 957 * @protocol: the protocol to add to 958 * @fd: the client file-descriptor 959 * 960 * Call QMP ``getfd`` (on Windows ``get-win32-socket``) followed by 961 * ``add_client`` with the given @fd. 962 */ 963 void qtest_qmp_add_client(QTestState *qts, const char *protocol, int fd); 964 965 /** 966 * qtest_qmp_device_del_send: 967 * @qts: QTestState instance to operate on 968 * @id: Identification string 969 * 970 * Generic hot-unplugging test via the device_del QMP command. 971 */ 972 void qtest_qmp_device_del_send(QTestState *qts, const char *id); 973 974 /** 975 * qtest_qmp_device_del: 976 * @qts: QTestState instance to operate on 977 * @id: Identification string 978 * 979 * Generic hot-unplugging test via the device_del QMP command. 980 * Waiting for command completion event. 981 */ 982 void qtest_qmp_device_del(QTestState *qts, const char *id); 983 984 /** 985 * qtest_probe_child: 986 * @s: QTestState instance to operate on. 987 * 988 * Returns: true if the child is still alive. 989 */ 990 bool qtest_probe_child(QTestState *s); 991 992 /** 993 * qtest_set_expected_status: 994 * @s: QTestState instance to operate on. 995 * @status: an expected exit status. 996 * 997 * Set expected exit status of the child. 998 */ 999 void qtest_set_expected_status(QTestState *s, int status); 1000 1001 QTestState *qtest_inproc_init(QTestState **s, bool log, const char* arch, 1002 void (*send)(void*, const char*)); 1003 1004 void qtest_client_inproc_recv(void *opaque, const char *str); 1005 1006 /** 1007 * qtest_qom_set_bool: 1008 * @s: QTestState instance to operate on. 1009 * @path: Path to the property being set. 1010 * @property: Property being set. 1011 * @value: Value to set the property. 1012 * 1013 * Set the property with passed in value. 1014 */ 1015 void qtest_qom_set_bool(QTestState *s, const char *path, const char *property, 1016 bool value); 1017 1018 /** 1019 * qtest_qom_get_bool: 1020 * @s: QTestState instance to operate on. 1021 * @path: Path to the property being retrieved. 1022 * @property: Property from where the value is being retrieved. 1023 * 1024 * Returns: Value retrieved from property. 1025 */ 1026 bool qtest_qom_get_bool(QTestState *s, const char *path, const char *property); 1027 1028 /** 1029 * qtest_pid: 1030 * @s: QTestState instance to operate on. 1031 * 1032 * Returns: the PID of the QEMU process, or <= 0 1033 */ 1034 pid_t qtest_pid(QTestState *s); 1035 1036 /** 1037 * have_qemu_img: 1038 * 1039 * Returns: true if "qemu-img" is available. 1040 */ 1041 bool have_qemu_img(void); 1042 1043 /** 1044 * mkimg: 1045 * @file: File name of the image that should be created 1046 * @fmt: Format, e.g. "qcow2" or "raw" 1047 * @size_mb: Size of the image in megabytes 1048 * 1049 * Create a disk image with qemu-img. Note that the QTEST_QEMU_IMG 1050 * environment variable must point to the qemu-img file. 1051 * 1052 * Returns: true if the image has been created successfully. 1053 */ 1054 bool mkimg(const char *file, const char *fmt, unsigned size_mb); 1055 1056 #endif 1057