tests/qtest/libqtest.h

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