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