tests/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
  23 typedef struct QTestState QTestState;
  24
  25 extern QTestState *global_qtest;
  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, ...) GCC_FMT_ATTR(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) GCC_FMT_ATTR(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_without_qmp_handshake:
  61  * @extra_args: other arguments to pass to QEMU.  CAUTION: these
  62  * arguments are subject to word splitting and shell evaluation.
  63  *
  64  * Returns: #QTestState instance.
  65  */
  66 QTestState *qtest_init_without_qmp_handshake(const char *extra_args);
  67
  68 /**
  69  * qtest_init_with_serial:
  70  * @extra_args: other arguments to pass to QEMU.  CAUTION: these
  71  * arguments are subject to word splitting and shell evaluation.
  72  * @sock_fd: pointer to store the socket file descriptor for
  73  * connection with serial.
  74  *
  75  * Returns: #QTestState instance.
  76  */
  77 QTestState *qtest_init_with_serial(const char *extra_args, int *sock_fd);
  78
  79 /**
  80  * qtest_quit:
  81  * @s: #QTestState instance to operate on.
  82  *
  83  * Shut down the QEMU process associated to @s.
  84  */
  85 void qtest_quit(QTestState *s);
  86
  87 /**
  88  * qtest_qmp_fds:
  89  * @s: #QTestState instance to operate on.
  90  * @fds: array of file descriptors
  91  * @fds_num: number of elements in @fds
  92  * @fmt...: QMP message to send to qemu, formatted like
  93  * qobject_from_jsonf_nofail().  See parse_escape() for what's
  94  * supported after '%'.
  95  *
  96  * Sends a QMP message to QEMU with fds and returns the response.
  97  */
  98 QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num,
  99                      const char *fmt, ...)
 100     GCC_FMT_ATTR(4, 5);
 101
 102 /**
 103  * qtest_qmp:
 104  * @s: #QTestState instance to operate on.
 105  * @fmt...: QMP message to send to qemu, formatted like
 106  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 107  * supported after '%'.
 108  *
 109  * Sends a QMP message to QEMU and returns the response.
 110  */
 111 QDict *qtest_qmp(QTestState *s, const char *fmt, ...)
 112     GCC_FMT_ATTR(2, 3);
 113
 114 /**
 115  * qtest_qmp_send:
 116  * @s: #QTestState instance to operate on.
 117  * @fmt...: QMP message to send to qemu, formatted like
 118  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 119  * supported after '%'.
 120  *
 121  * Sends a QMP message to QEMU and leaves the response in the stream.
 122  */
 123 void qtest_qmp_send(QTestState *s, const char *fmt, ...)
 124     GCC_FMT_ATTR(2, 3);
 125
 126 /**
 127  * qtest_qmp_send_raw:
 128  * @s: #QTestState instance to operate on.
 129  * @fmt...: text to send, formatted like sprintf()
 130  *
 131  * Sends text to the QMP monitor verbatim.  Need not be valid JSON;
 132  * this is useful for negative tests.
 133  */
 134 void qtest_qmp_send_raw(QTestState *s, const char *fmt, ...)
 135     GCC_FMT_ATTR(2, 3);
 136
 137 /**
 138  * qtest_vqmp_fds:
 139  * @s: #QTestState instance to operate on.
 140  * @fds: array of file descriptors
 141  * @fds_num: number of elements in @fds
 142  * @fmt: QMP message to send to QEMU, formatted like
 143  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 144  * supported after '%'.
 145  * @ap: QMP message arguments
 146  *
 147  * Sends a QMP message to QEMU with fds and returns the response.
 148  */
 149 QDict *qtest_vqmp_fds(QTestState *s, int *fds, size_t fds_num,
 150                       const char *fmt, va_list ap)
 151     GCC_FMT_ATTR(4, 0);
 152
 153 /**
 154  * qtest_vqmp:
 155  * @s: #QTestState instance to operate on.
 156  * @fmt: QMP message to send to QEMU, formatted like
 157  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 158  * supported after '%'.
 159  * @ap: QMP message arguments
 160  *
 161  * Sends a QMP message to QEMU and returns the response.
 162  */
 163 QDict *qtest_vqmp(QTestState *s, const char *fmt, va_list ap)
 164     GCC_FMT_ATTR(2, 0);
 165
 166 /**
 167  * qtest_qmp_vsend_fds:
 168  * @s: #QTestState instance to operate on.
 169  * @fds: array of file descriptors
 170  * @fds_num: number of elements in @fds
 171  * @fmt: QMP message to send to QEMU, formatted like
 172  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 173  * supported after '%'.
 174  * @ap: QMP message arguments
 175  *
 176  * Sends a QMP message to QEMU and leaves the response in the stream.
 177  */
 178 void qtest_qmp_vsend_fds(QTestState *s, int *fds, size_t fds_num,
 179                          const char *fmt, va_list ap)
 180     GCC_FMT_ATTR(4, 0);
 181
 182 /**
 183  * qtest_qmp_vsend:
 184  * @s: #QTestState instance to operate on.
 185  * @fmt: QMP message to send to QEMU, formatted like
 186  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 187  * supported after '%'.
 188  * @ap: QMP message arguments
 189  *
 190  * Sends a QMP message to QEMU and leaves the response in the stream.
 191  */
 192 void qtest_qmp_vsend(QTestState *s, const char *fmt, va_list ap)
 193     GCC_FMT_ATTR(2, 0);
 194
 195 /**
 196  * qtest_receive:
 197  * @s: #QTestState instance to operate on.
 198  *
 199  * Reads a QMP message from QEMU and returns the response.
 200  */
 201 QDict *qtest_qmp_receive(QTestState *s);
 202
 203 /**
 204  * qtest_qmp_eventwait:
 205  * @s: #QTestState instance to operate on.
 206  * @s: #event event to wait for.
 207  *
 208  * Continuously polls for QMP responses until it receives the desired event.
 209  */
 210 void qtest_qmp_eventwait(QTestState *s, const char *event);
 211
 212 /**
 213  * qtest_qmp_eventwait_ref:
 214  * @s: #QTestState instance to operate on.
 215  * @s: #event event to wait for.
 216  *
 217  * Continuously polls for QMP responses until it receives the desired event.
 218  * Returns a copy of the event for further investigation.
 219  */
 220 QDict *qtest_qmp_eventwait_ref(QTestState *s, const char *event);
 221
 222 /**
 223  * qtest_qmp_receive_success:
 224  * @s: #QTestState instance to operate on
 225  * @event_cb: Event callback
 226  * @opaque: Argument for @event_cb
 227  *
 228  * Poll QMP messages until a command success response is received.
 229  * If @event_cb, call it for each event received, passing @opaque,
 230  * the event's name and data.
 231  * Return the success response's "return" member.
 232  */
 233 QDict *qtest_qmp_receive_success(QTestState *s,
 234                                  void (*event_cb)(void *opaque,
 235                                                   const char *name,
 236                                                   QDict *data),
 237                                  void *opaque);
 238
 239 /**
 240  * qtest_hmp:
 241  * @s: #QTestState instance to operate on.
 242  * @fmt...: HMP command to send to QEMU, formats arguments like sprintf().
 243  *
 244  * Send HMP command to QEMU via QMP's human-monitor-command.
 245  * QMP events are discarded.
 246  *
 247  * Returns: the command's output.  The caller should g_free() it.
 248  */
 249 char *qtest_hmp(QTestState *s, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
 250
 251 /**
 252  * qtest_hmpv:
 253  * @s: #QTestState instance to operate on.
 254  * @fmt: HMP command to send to QEMU, formats arguments like vsprintf().
 255  * @ap: HMP command arguments
 256  *
 257  * Send HMP command to QEMU via QMP's human-monitor-command.
 258  * QMP events are discarded.
 259  *
 260  * Returns: the command's output.  The caller should g_free() it.
 261  */
 262 char *qtest_vhmp(QTestState *s, const char *fmt, va_list ap)
 263     GCC_FMT_ATTR(2, 0);
 264
 265 /**
 266  * qtest_get_irq:
 267  * @s: #QTestState instance to operate on.
 268  * @num: Interrupt to observe.
 269  *
 270  * Returns: The level of the @num interrupt.
 271  */
 272 bool qtest_get_irq(QTestState *s, int num);
 273
 274 /**
 275  * qtest_irq_intercept_in:
 276  * @s: #QTestState instance to operate on.
 277  * @string: QOM path of a device.
 278  *
 279  * Associate qtest irqs with the GPIO-in pins of the device
 280  * whose path is specified by @string.
 281  */
 282 void qtest_irq_intercept_in(QTestState *s, const char *string);
 283
 284 /**
 285  * qtest_irq_intercept_out:
 286  * @s: #QTestState instance to operate on.
 287  * @string: QOM path of a device.
 288  *
 289  * Associate qtest irqs with the GPIO-out pins of the device
 290  * whose path is specified by @string.
 291  */
 292 void qtest_irq_intercept_out(QTestState *s, const char *string);
 293
 294 /**
 295  * qtest_set_irq_in:
 296  * @s: QTestState instance to operate on.
 297  * @string: QOM path of a device
 298  * @name: IRQ name
 299  * @irq: IRQ number
 300  * @level: IRQ level
 301  *
 302  * Force given device/irq GPIO-in pin to the given level.
 303  */
 304 void qtest_set_irq_in(QTestState *s, const char *string, const char *name,
 305                       int irq, int level);
 306
 307 /**
 308  * qtest_outb:
 309  * @s: #QTestState instance to operate on.
 310  * @addr: I/O port to write to.
 311  * @value: Value being written.
 312  *
 313  * Write an 8-bit value to an I/O port.
 314  */
 315 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value);
 316
 317 /**
 318  * qtest_outw:
 319  * @s: #QTestState instance to operate on.
 320  * @addr: I/O port to write to.
 321  * @value: Value being written.
 322  *
 323  * Write a 16-bit value to an I/O port.
 324  */
 325 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value);
 326
 327 /**
 328  * qtest_outl:
 329  * @s: #QTestState instance to operate on.
 330  * @addr: I/O port to write to.
 331  * @value: Value being written.
 332  *
 333  * Write a 32-bit value to an I/O port.
 334  */
 335 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value);
 336
 337 /**
 338  * qtest_inb:
 339  * @s: #QTestState instance to operate on.
 340  * @addr: I/O port to read from.
 341  *
 342  * Returns an 8-bit value from an I/O port.
 343  */
 344 uint8_t qtest_inb(QTestState *s, uint16_t addr);
 345
 346 /**
 347  * qtest_inw:
 348  * @s: #QTestState instance to operate on.
 349  * @addr: I/O port to read from.
 350  *
 351  * Returns a 16-bit value from an I/O port.
 352  */
 353 uint16_t qtest_inw(QTestState *s, uint16_t addr);
 354
 355 /**
 356  * qtest_inl:
 357  * @s: #QTestState instance to operate on.
 358  * @addr: I/O port to read from.
 359  *
 360  * Returns a 32-bit value from an I/O port.
 361  */
 362 uint32_t qtest_inl(QTestState *s, uint16_t addr);
 363
 364 /**
 365  * qtest_writeb:
 366  * @s: #QTestState instance to operate on.
 367  * @addr: Guest address to write to.
 368  * @value: Value being written.
 369  *
 370  * Writes an 8-bit value to memory.
 371  */
 372 void qtest_writeb(QTestState *s, uint64_t addr, uint8_t value);
 373
 374 /**
 375  * qtest_writew:
 376  * @s: #QTestState instance to operate on.
 377  * @addr: Guest address to write to.
 378  * @value: Value being written.
 379  *
 380  * Writes a 16-bit value to memory.
 381  */
 382 void qtest_writew(QTestState *s, uint64_t addr, uint16_t value);
 383
 384 /**
 385  * qtest_writel:
 386  * @s: #QTestState instance to operate on.
 387  * @addr: Guest address to write to.
 388  * @value: Value being written.
 389  *
 390  * Writes a 32-bit value to memory.
 391  */
 392 void qtest_writel(QTestState *s, uint64_t addr, uint32_t value);
 393
 394 /**
 395  * qtest_writeq:
 396  * @s: #QTestState instance to operate on.
 397  * @addr: Guest address to write to.
 398  * @value: Value being written.
 399  *
 400  * Writes a 64-bit value to memory.
 401  */
 402 void qtest_writeq(QTestState *s, uint64_t addr, uint64_t value);
 403
 404 /**
 405  * qtest_readb:
 406  * @s: #QTestState instance to operate on.
 407  * @addr: Guest address to read from.
 408  *
 409  * Reads an 8-bit value from memory.
 410  *
 411  * Returns: Value read.
 412  */
 413 uint8_t qtest_readb(QTestState *s, uint64_t addr);
 414
 415 /**
 416  * qtest_readw:
 417  * @s: #QTestState instance to operate on.
 418  * @addr: Guest address to read from.
 419  *
 420  * Reads a 16-bit value from memory.
 421  *
 422  * Returns: Value read.
 423  */
 424 uint16_t qtest_readw(QTestState *s, uint64_t addr);
 425
 426 /**
 427  * qtest_readl:
 428  * @s: #QTestState instance to operate on.
 429  * @addr: Guest address to read from.
 430  *
 431  * Reads a 32-bit value from memory.
 432  *
 433  * Returns: Value read.
 434  */
 435 uint32_t qtest_readl(QTestState *s, uint64_t addr);
 436
 437 /**
 438  * qtest_readq:
 439  * @s: #QTestState instance to operate on.
 440  * @addr: Guest address to read from.
 441  *
 442  * Reads a 64-bit value from memory.
 443  *
 444  * Returns: Value read.
 445  */
 446 uint64_t qtest_readq(QTestState *s, uint64_t addr);
 447
 448 /**
 449  * qtest_memread:
 450  * @s: #QTestState instance to operate on.
 451  * @addr: Guest address to read from.
 452  * @data: Pointer to where memory contents will be stored.
 453  * @size: Number of bytes to read.
 454  *
 455  * Read guest memory into a buffer.
 456  */
 457 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size);
 458
 459 /**
 460  * qtest_rtas_call:
 461  * @s: #QTestState instance to operate on.
 462  * @name: name of the command to call.
 463  * @nargs: Number of args.
 464  * @args: Guest address to read args from.
 465  * @nret: Number of return value.
 466  * @ret: Guest address to write return values to.
 467  *
 468  * Call an RTAS function
 469  */
 470 uint64_t qtest_rtas_call(QTestState *s, const char *name,
 471                          uint32_t nargs, uint64_t args,
 472                          uint32_t nret, uint64_t ret);
 473
 474 /**
 475  * qtest_bufread:
 476  * @s: #QTestState instance to operate on.
 477  * @addr: Guest address to read from.
 478  * @data: Pointer to where memory contents will be stored.
 479  * @size: Number of bytes to read.
 480  *
 481  * Read guest memory into a buffer and receive using a base64 encoding.
 482  */
 483 void qtest_bufread(QTestState *s, uint64_t addr, void *data, size_t size);
 484
 485 /**
 486  * qtest_memwrite:
 487  * @s: #QTestState instance to operate on.
 488  * @addr: Guest address to write to.
 489  * @data: Pointer to the bytes that will be written to guest memory.
 490  * @size: Number of bytes to write.
 491  *
 492  * Write a buffer to guest memory.
 493  */
 494 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size);
 495
 496 /**
 497  * qtest_bufwrite:
 498  * @s: #QTestState instance to operate on.
 499  * @addr: Guest address to write to.
 500  * @data: Pointer to the bytes that will be written to guest memory.
 501  * @size: Number of bytes to write.
 502  *
 503  * Write a buffer to guest memory and transmit using a base64 encoding.
 504  */
 505 void qtest_bufwrite(QTestState *s, uint64_t addr,
 506                     const void *data, size_t size);
 507
 508 /**
 509  * qtest_memset:
 510  * @s: #QTestState instance to operate on.
 511  * @addr: Guest address to write to.
 512  * @patt: Byte pattern to fill the guest memory region with.
 513  * @size: Number of bytes to write.
 514  *
 515  * Write a pattern to guest memory.
 516  */
 517 void qtest_memset(QTestState *s, uint64_t addr, uint8_t patt, size_t size);
 518
 519 /**
 520  * qtest_clock_step_next:
 521  * @s: #QTestState instance to operate on.
 522  *
 523  * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
 524  *
 525  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 526  */
 527 int64_t qtest_clock_step_next(QTestState *s);
 528
 529 /**
 530  * qtest_clock_step:
 531  * @s: QTestState instance to operate on.
 532  * @step: Number of nanoseconds to advance the clock by.
 533  *
 534  * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
 535  *
 536  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 537  */
 538 int64_t qtest_clock_step(QTestState *s, int64_t step);
 539
 540 /**
 541  * qtest_clock_set:
 542  * @s: QTestState instance to operate on.
 543  * @val: Nanoseconds value to advance the clock to.
 544  *
 545  * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
 546  *
 547  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 548  */
 549 int64_t qtest_clock_set(QTestState *s, int64_t val);
 550
 551 /**
 552  * qtest_big_endian:
 553  * @s: QTestState instance to operate on.
 554  *
 555  * Returns: True if the architecture under test has a big endian configuration.
 556  */
 557 bool qtest_big_endian(QTestState *s);
 558
 559 /**
 560  * qtest_get_arch:
 561  *
 562  * Returns: The architecture for the QEMU executable under test.
 563  */
 564 const char *qtest_get_arch(void);
 565
 566 /**
 567  * qtest_add_func:
 568  * @str: Test case path.
 569  * @fn: Test case function
 570  *
 571  * Add a GTester testcase with the given name and function.
 572  * The path is prefixed with the architecture under test, as
 573  * returned by qtest_get_arch().
 574  */
 575 void qtest_add_func(const char *str, void (*fn)(void));
 576
 577 /**
 578  * qtest_add_data_func:
 579  * @str: Test case path.
 580  * @data: Test case data
 581  * @fn: Test case function
 582  *
 583  * Add a GTester testcase with the given name, data and function.
 584  * The path is prefixed with the architecture under test, as
 585  * returned by qtest_get_arch().
 586  */
 587 void qtest_add_data_func(const char *str, const void *data,
 588                          void (*fn)(const void *));
 589
 590 /**
 591  * qtest_add_data_func_full:
 592  * @str: Test case path.
 593  * @data: Test case data
 594  * @fn: Test case function
 595  * @data_free_func: GDestroyNotify for data
 596  *
 597  * Add a GTester testcase with the given name, data and function.
 598  * The path is prefixed with the architecture under test, as
 599  * returned by qtest_get_arch().
 600  *
 601  * @data is passed to @data_free_func() on test completion.
 602  */
 603 void qtest_add_data_func_full(const char *str, void *data,
 604                               void (*fn)(const void *),
 605                               GDestroyNotify data_free_func);
 606
 607 /**
 608  * qtest_add:
 609  * @testpath: Test case path
 610  * @Fixture: Fixture type
 611  * @tdata: Test case data
 612  * @fsetup: Test case setup function
 613  * @ftest: Test case function
 614  * @fteardown: Test case teardown function
 615  *
 616  * Add a GTester testcase with the given name, data and functions.
 617  * The path is prefixed with the architecture under test, as
 618  * returned by qtest_get_arch().
 619  */
 620 #define qtest_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
 621     do { \
 622         char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \
 623         g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \
 624         g_free(path); \
 625     } while (0)
 626
 627 void qtest_add_abrt_handler(GHookFunc fn, const void *data);
 628
 629 /**
 630  * qtest_start:
 631  * @args: other arguments to pass to QEMU
 632  *
 633  * Start QEMU and assign the resulting #QTestState to a global variable.
 634  * The global variable is used by "shortcut" functions documented below.
 635  *
 636  * Returns: #QTestState instance.
 637  */
 638 static inline QTestState *qtest_start(const char *args)
 639 {
 640     global_qtest = qtest_init(args);
 641     return global_qtest;
 642 }
 643
 644 /**
 645  * qtest_end:
 646  *
 647  * Shut down the QEMU process started by qtest_start().
 648  */
 649 static inline void qtest_end(void)
 650 {
 651     if (!global_qtest) {
 652         return;
 653     }
 654     qtest_quit(global_qtest);
 655     global_qtest = NULL;
 656 }
 657
 658 /**
 659  * qmp:
 660  * @fmt...: QMP message to send to qemu, formatted like
 661  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 662  * supported after '%'.
 663  *
 664  * Sends a QMP message to QEMU and returns the response.
 665  */
 666 QDict *qmp(const char *fmt, ...) GCC_FMT_ATTR(1, 2);
 667
 668 /**
 669  * qmp_assert_success:
 670  * @fmt...: QMP message to send to qemu, formatted like
 671  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 672  * supported after '%'.
 673  *
 674  * Sends a QMP message to QEMU and asserts that a 'return' key is present in
 675  * the response.
 676  */
 677 void qmp_assert_success(const char *fmt, ...) GCC_FMT_ATTR(1, 2);
 678
 679 /*
 680  * qmp_eventwait:
 681  * @s: #event event to wait for.
 682  *
 683  * Continuously polls for QMP responses until it receives the desired event.
 684  */
 685 static inline void qmp_eventwait(const char *event)
 686 {
 687     return qtest_qmp_eventwait(global_qtest, event);
 688 }
 689
 690 /**
 691  * hmp:
 692  * @fmt...: HMP command to send to QEMU, formats arguments like sprintf().
 693  *
 694  * Send HMP command to QEMU via QMP's human-monitor-command.
 695  *
 696  * Returns: the command's output.  The caller should g_free() it.
 697  */
 698 char *hmp(const char *fmt, ...) GCC_FMT_ATTR(1, 2);
 699
 700 /**
 701  * get_irq:
 702  * @num: Interrupt to observe.
 703  *
 704  * Returns: The level of the @num interrupt.
 705  */
 706 static inline bool get_irq(int num)
 707 {
 708     return qtest_get_irq(global_qtest, num);
 709 }
 710
 711 /**
 712  * outb:
 713  * @addr: I/O port to write to.
 714  * @value: Value being written.
 715  *
 716  * Write an 8-bit value to an I/O port.
 717  */
 718 static inline void outb(uint16_t addr, uint8_t value)
 719 {
 720     qtest_outb(global_qtest, addr, value);
 721 }
 722
 723 /**
 724  * outw:
 725  * @addr: I/O port to write to.
 726  * @value: Value being written.
 727  *
 728  * Write a 16-bit value to an I/O port.
 729  */
 730 static inline void outw(uint16_t addr, uint16_t value)
 731 {
 732     qtest_outw(global_qtest, addr, value);
 733 }
 734
 735 /**
 736  * outl:
 737  * @addr: I/O port to write to.
 738  * @value: Value being written.
 739  *
 740  * Write a 32-bit value to an I/O port.
 741  */
 742 static inline void outl(uint16_t addr, uint32_t value)
 743 {
 744     qtest_outl(global_qtest, addr, value);
 745 }
 746
 747 /**
 748  * inb:
 749  * @addr: I/O port to read from.
 750  *
 751  * Reads an 8-bit value from an I/O port.
 752  *
 753  * Returns: Value read.
 754  */
 755 static inline uint8_t inb(uint16_t addr)
 756 {
 757     return qtest_inb(global_qtest, addr);
 758 }
 759
 760 /**
 761  * inw:
 762  * @addr: I/O port to read from.
 763  *
 764  * Reads a 16-bit value from an I/O port.
 765  *
 766  * Returns: Value read.
 767  */
 768 static inline uint16_t inw(uint16_t addr)
 769 {
 770     return qtest_inw(global_qtest, addr);
 771 }
 772
 773 /**
 774  * inl:
 775  * @addr: I/O port to read from.
 776  *
 777  * Reads a 32-bit value from an I/O port.
 778  *
 779  * Returns: Value read.
 780  */
 781 static inline uint32_t inl(uint16_t addr)
 782 {
 783     return qtest_inl(global_qtest, addr);
 784 }
 785
 786 /**
 787  * writeb:
 788  * @addr: Guest address to write to.
 789  * @value: Value being written.
 790  *
 791  * Writes an 8-bit value to guest memory.
 792  */
 793 static inline void writeb(uint64_t addr, uint8_t value)
 794 {
 795     qtest_writeb(global_qtest, addr, value);
 796 }
 797
 798 /**
 799  * writew:
 800  * @addr: Guest address to write to.
 801  * @value: Value being written.
 802  *
 803  * Writes a 16-bit value to guest memory.
 804  */
 805 static inline void writew(uint64_t addr, uint16_t value)
 806 {
 807     qtest_writew(global_qtest, addr, value);
 808 }
 809
 810 /**
 811  * writel:
 812  * @addr: Guest address to write to.
 813  * @value: Value being written.
 814  *
 815  * Writes a 32-bit value to guest memory.
 816  */
 817 static inline void writel(uint64_t addr, uint32_t value)
 818 {
 819     qtest_writel(global_qtest, addr, value);
 820 }
 821
 822 /**
 823  * writeq:
 824  * @addr: Guest address to write to.
 825  * @value: Value being written.
 826  *
 827  * Writes a 64-bit value to guest memory.
 828  */
 829 static inline void writeq(uint64_t addr, uint64_t value)
 830 {
 831     qtest_writeq(global_qtest, addr, value);
 832 }
 833
 834 /**
 835  * readb:
 836  * @addr: Guest address to read from.
 837  *
 838  * Reads an 8-bit value from guest memory.
 839  *
 840  * Returns: Value read.
 841  */
 842 static inline uint8_t readb(uint64_t addr)
 843 {
 844     return qtest_readb(global_qtest, addr);
 845 }
 846
 847 /**
 848  * readw:
 849  * @addr: Guest address to read from.
 850  *
 851  * Reads a 16-bit value from guest memory.
 852  *
 853  * Returns: Value read.
 854  */
 855 static inline uint16_t readw(uint64_t addr)
 856 {
 857     return qtest_readw(global_qtest, addr);
 858 }
 859
 860 /**
 861  * readl:
 862  * @addr: Guest address to read from.
 863  *
 864  * Reads a 32-bit value from guest memory.
 865  *
 866  * Returns: Value read.
 867  */
 868 static inline uint32_t readl(uint64_t addr)
 869 {
 870     return qtest_readl(global_qtest, addr);
 871 }
 872
 873 /**
 874  * readq:
 875  * @addr: Guest address to read from.
 876  *
 877  * Reads a 64-bit value from guest memory.
 878  *
 879  * Returns: Value read.
 880  */
 881 static inline uint64_t readq(uint64_t addr)
 882 {
 883     return qtest_readq(global_qtest, addr);
 884 }
 885
 886 /**
 887  * memread:
 888  * @addr: Guest address to read from.
 889  * @data: Pointer to where memory contents will be stored.
 890  * @size: Number of bytes to read.
 891  *
 892  * Read guest memory into a buffer.
 893  */
 894 static inline void memread(uint64_t addr, void *data, size_t size)
 895 {
 896     qtest_memread(global_qtest, addr, data, size);
 897 }
 898
 899 /**
 900  * memwrite:
 901  * @addr: Guest address to write to.
 902  * @data: Pointer to the bytes that will be written to guest memory.
 903  * @size: Number of bytes to write.
 904  *
 905  * Write a buffer to guest memory.
 906  */
 907 static inline void memwrite(uint64_t addr, const void *data, size_t size)
 908 {
 909     qtest_memwrite(global_qtest, addr, data, size);
 910 }
 911
 912 /**
 913  * clock_step_next:
 914  *
 915  * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
 916  *
 917  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 918  */
 919 static inline int64_t clock_step_next(void)
 920 {
 921     return qtest_clock_step_next(global_qtest);
 922 }
 923
 924 /**
 925  * clock_step:
 926  * @step: Number of nanoseconds to advance the clock by.
 927  *
 928  * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
 929  *
 930  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 931  */
 932 static inline int64_t clock_step(int64_t step)
 933 {
 934     return qtest_clock_step(global_qtest, step);
 935 }
 936
 937 QDict *qmp_fd_receive(int fd);
 938 void qmp_fd_vsend_fds(int fd, int *fds, size_t fds_num,
 939                       const char *fmt, va_list ap) GCC_FMT_ATTR(4, 0);
 940 void qmp_fd_vsend(int fd, const char *fmt, va_list ap) GCC_FMT_ATTR(2, 0);
 941 void qmp_fd_send(int fd, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
 942 void qmp_fd_send_raw(int fd, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
 943 void qmp_fd_vsend_raw(int fd, const char *fmt, va_list ap) GCC_FMT_ATTR(2, 0);
 944 QDict *qmp_fdv(int fd, const char *fmt, va_list ap) GCC_FMT_ATTR(2, 0);
 945 QDict *qmp_fd(int fd, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
 946
 947 /**
 948  * qtest_cb_for_every_machine:
 949  * @cb: Pointer to the callback function
 950  * @skip_old_versioned: true if versioned old machine types should be skipped
 951  *
 952  *  Call a callback function for every name of all available machines.
 953  */
 954 void qtest_cb_for_every_machine(void (*cb)(const char *machine),
 955                                 bool skip_old_versioned);
 956
 957 /**
 958  * qtest_qmp_device_add:
 959  * @driver: Name of the device that should be added
 960  * @id: Identification string
 961  * @fmt...: QMP message to send to qemu, formatted like
 962  * qobject_from_jsonf_nofail().  See parse_escape() for what's
 963  * supported after '%'.
 964  *
 965  * Generic hot-plugging test via the device_add QMP command.
 966  */
 967 void qtest_qmp_device_add(const char *driver, const char *id, const char *fmt,
 968                           ...) GCC_FMT_ATTR(3, 4);
 969
 970 /**
 971  * qtest_qmp_device_del:
 972  * @id: Identification string
 973  *
 974  * Generic hot-unplugging test via the device_del QMP command.
 975  */
 976 void qtest_qmp_device_del(const char *id);
 977
 978 /**
 979  * qmp_rsp_is_err:
 980  * @rsp: QMP response to check for error
 981  *
 982  * Test @rsp for error and discard @rsp.
 983  * Returns 'true' if there is error in @rsp and 'false' otherwise.
 984  */
 985 bool qmp_rsp_is_err(QDict *rsp);
 986
 987 /**
 988  * qmp_assert_error_class:
 989  * @rsp: QMP response to check for error
 990  * @class: an error class
 991  *
 992  * Assert the response has the given error class and discard @rsp.
 993  */
 994 void qmp_assert_error_class(QDict *rsp, const char *class);
 995
 996 /**
 997  * qtest_probe_child:
 998  * @s: QTestState instance to operate on.
 999  *
1000  * Returns: true if the child is still alive.
1001  */
1002 bool qtest_probe_child(QTestState *s);
1003
1004 #endif