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