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 <stddef.h>
  21 #include <stdint.h>
  22 #include <stdbool.h>
  23 #include <stdarg.h>
  24 #include <sys/types.h>
  25 #include "qapi/qmp/qdict.h"
  26 #include "glib-compat.h"
  27
  28 typedef struct QTestState QTestState;
  29
  30 extern QTestState *global_qtest;
  31
  32 /**
  33  * qtest_init:
  34  * @extra_args: other arguments to pass to QEMU.
  35  *
  36  * Returns: #QTestState instance.
  37  */
  38 QTestState *qtest_init(const char *extra_args);
  39
  40 /**
  41  * qtest_quit:
  42  * @s: #QTestState instance to operate on.
  43  *
  44  * Shut down the QEMU process associated to @s.
  45  */
  46 void qtest_quit(QTestState *s);
  47
  48 /**
  49  * qtest_qmp_discard_response:
  50  * @s: #QTestState instance to operate on.
  51  * @fmt...: QMP message to send to qemu
  52  *
  53  * Sends a QMP message to QEMU and consumes the response.
  54  */
  55 void qtest_qmp_discard_response(QTestState *s, const char *fmt, ...);
  56
  57 /**
  58  * qtest_qmp:
  59  * @s: #QTestState instance to operate on.
  60  * @fmt...: QMP message to send to qemu
  61  *
  62  * Sends a QMP message to QEMU and returns the response.
  63  */
  64 QDict *qtest_qmp(QTestState *s, const char *fmt, ...);
  65
  66 /**
  67  * qtest_async_qmp:
  68  * @s: #QTestState instance to operate on.
  69  * @fmt...: QMP message to send to qemu
  70  *
  71  * Sends a QMP message to QEMU and leaves the response in the stream.
  72  */
  73 void qtest_async_qmp(QTestState *s, const char *fmt, ...);
  74
  75 /**
  76  * qtest_qmpv_discard_response:
  77  * @s: #QTestState instance to operate on.
  78  * @fmt: QMP message to send to QEMU
  79  * @ap: QMP message arguments
  80  *
  81  * Sends a QMP message to QEMU and consumes the response.
  82  */
  83 void qtest_qmpv_discard_response(QTestState *s, const char *fmt, va_list ap);
  84
  85 /**
  86  * qtest_qmpv:
  87  * @s: #QTestState instance to operate on.
  88  * @fmt: QMP message to send to QEMU
  89  * @ap: QMP message arguments
  90  *
  91  * Sends a QMP message to QEMU and returns the response.
  92  */
  93 QDict *qtest_qmpv(QTestState *s, const char *fmt, va_list ap);
  94
  95 /**
  96  * qtest_async_qmpv:
  97  * @s: #QTestState instance to operate on.
  98  * @fmt: QMP message to send to QEMU
  99  * @ap: QMP message arguments
 100  *
 101  * Sends a QMP message to QEMU and leaves the response in the stream.
 102  */
 103 void qtest_async_qmpv(QTestState *s, const char *fmt, va_list ap);
 104
 105 /**
 106  * qtest_receive:
 107  * @s: #QTestState instance to operate on.
 108  *
 109  * Reads a QMP message from QEMU and returns the response.
 110  */
 111 QDict *qtest_qmp_receive(QTestState *s);
 112
 113 /**
 114  * qtest_qmp_eventwait:
 115  * @s: #QTestState instance to operate on.
 116  * @s: #event event to wait for.
 117  *
 118  * Continuosly polls for QMP responses until it receives the desired event.
 119  */
 120 void qtest_qmp_eventwait(QTestState *s, const char *event);
 121
 122 /**
 123  * qtest_get_irq:
 124  * @s: #QTestState instance to operate on.
 125  * @num: Interrupt to observe.
 126  *
 127  * Returns: The level of the @num interrupt.
 128  */
 129 bool qtest_get_irq(QTestState *s, int num);
 130
 131 /**
 132  * qtest_irq_intercept_in:
 133  * @s: #QTestState instance to operate on.
 134  * @string: QOM path of a device.
 135  *
 136  * Associate qtest irqs with the GPIO-in pins of the device
 137  * whose path is specified by @string.
 138  */
 139 void qtest_irq_intercept_in(QTestState *s, const char *string);
 140
 141 /**
 142  * qtest_irq_intercept_out:
 143  * @s: #QTestState instance to operate on.
 144  * @string: QOM path of a device.
 145  *
 146  * Associate qtest irqs with the GPIO-out pins of the device
 147  * whose path is specified by @string.
 148  */
 149 void qtest_irq_intercept_out(QTestState *s, const char *string);
 150
 151 /**
 152  * qtest_outb:
 153  * @s: #QTestState instance to operate on.
 154  * @addr: I/O port to write to.
 155  * @value: Value being written.
 156  *
 157  * Write an 8-bit value to an I/O port.
 158  */
 159 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value);
 160
 161 /**
 162  * qtest_outw:
 163  * @s: #QTestState instance to operate on.
 164  * @addr: I/O port to write to.
 165  * @value: Value being written.
 166  *
 167  * Write a 16-bit value to an I/O port.
 168  */
 169 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value);
 170
 171 /**
 172  * qtest_outl:
 173  * @s: #QTestState instance to operate on.
 174  * @addr: I/O port to write to.
 175  * @value: Value being written.
 176  *
 177  * Write a 32-bit value to an I/O port.
 178  */
 179 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value);
 180
 181 /**
 182  * qtest_inb:
 183  * @s: #QTestState instance to operate on.
 184  * @addr: I/O port to read from.
 185  *
 186  * Returns an 8-bit value from an I/O port.
 187  */
 188 uint8_t qtest_inb(QTestState *s, uint16_t addr);
 189
 190 /**
 191  * qtest_inw:
 192  * @s: #QTestState instance to operate on.
 193  * @addr: I/O port to read from.
 194  *
 195  * Returns a 16-bit value from an I/O port.
 196  */
 197 uint16_t qtest_inw(QTestState *s, uint16_t addr);
 198
 199 /**
 200  * qtest_inl:
 201  * @s: #QTestState instance to operate on.
 202  * @addr: I/O port to read from.
 203  *
 204  * Returns a 32-bit value from an I/O port.
 205  */
 206 uint32_t qtest_inl(QTestState *s, uint16_t addr);
 207
 208 /**
 209  * qtest_writeb:
 210  * @s: #QTestState instance to operate on.
 211  * @addr: Guest address to write to.
 212  * @value: Value being written.
 213  *
 214  * Writes an 8-bit value to memory.
 215  */
 216 void qtest_writeb(QTestState *s, uint64_t addr, uint8_t value);
 217
 218 /**
 219  * qtest_writew:
 220  * @s: #QTestState instance to operate on.
 221  * @addr: Guest address to write to.
 222  * @value: Value being written.
 223  *
 224  * Writes a 16-bit value to memory.
 225  */
 226 void qtest_writew(QTestState *s, uint64_t addr, uint16_t value);
 227
 228 /**
 229  * qtest_writel:
 230  * @s: #QTestState instance to operate on.
 231  * @addr: Guest address to write to.
 232  * @value: Value being written.
 233  *
 234  * Writes a 32-bit value to memory.
 235  */
 236 void qtest_writel(QTestState *s, uint64_t addr, uint32_t value);
 237
 238 /**
 239  * qtest_writeq:
 240  * @s: #QTestState instance to operate on.
 241  * @addr: Guest address to write to.
 242  * @value: Value being written.
 243  *
 244  * Writes a 64-bit value to memory.
 245  */
 246 void qtest_writeq(QTestState *s, uint64_t addr, uint64_t value);
 247
 248 /**
 249  * qtest_readb:
 250  * @s: #QTestState instance to operate on.
 251  * @addr: Guest address to read from.
 252  *
 253  * Reads an 8-bit value from memory.
 254  *
 255  * Returns: Value read.
 256  */
 257 uint8_t qtest_readb(QTestState *s, uint64_t addr);
 258
 259 /**
 260  * qtest_readw:
 261  * @s: #QTestState instance to operate on.
 262  * @addr: Guest address to read from.
 263  *
 264  * Reads a 16-bit value from memory.
 265  *
 266  * Returns: Value read.
 267  */
 268 uint16_t qtest_readw(QTestState *s, uint64_t addr);
 269
 270 /**
 271  * qtest_readl:
 272  * @s: #QTestState instance to operate on.
 273  * @addr: Guest address to read from.
 274  *
 275  * Reads a 32-bit value from memory.
 276  *
 277  * Returns: Value read.
 278  */
 279 uint32_t qtest_readl(QTestState *s, uint64_t addr);
 280
 281 /**
 282  * qtest_readq:
 283  * @s: #QTestState instance to operate on.
 284  * @addr: Guest address to read from.
 285  *
 286  * Reads a 64-bit value from memory.
 287  *
 288  * Returns: Value read.
 289  */
 290 uint64_t qtest_readq(QTestState *s, uint64_t addr);
 291
 292 /**
 293  * qtest_memread:
 294  * @s: #QTestState instance to operate on.
 295  * @addr: Guest address to read from.
 296  * @data: Pointer to where memory contents will be stored.
 297  * @size: Number of bytes to read.
 298  *
 299  * Read guest memory into a buffer.
 300  */
 301 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size);
 302
 303 /**
 304  * qtest_memwrite:
 305  * @s: #QTestState instance to operate on.
 306  * @addr: Guest address to write to.
 307  * @data: Pointer to the bytes that will be written to guest memory.
 308  * @size: Number of bytes to write.
 309  *
 310  * Write a buffer to guest memory.
 311  */
 312 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size);
 313
 314 /**
 315  * qtest_memset:
 316  * @s: #QTestState instance to operate on.
 317  * @addr: Guest address to write to.
 318  * @patt: Byte pattern to fill the guest memory region with.
 319  * @size: Number of bytes to write.
 320  *
 321  * Write a pattern to guest memory.
 322  */
 323 void qtest_memset(QTestState *s, uint64_t addr, uint8_t patt, size_t size);
 324
 325 /**
 326  * qtest_clock_step_next:
 327  * @s: #QTestState instance to operate on.
 328  *
 329  * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
 330  *
 331  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 332  */
 333 int64_t qtest_clock_step_next(QTestState *s);
 334
 335 /**
 336  * qtest_clock_step:
 337  * @s: QTestState instance to operate on.
 338  * @step: Number of nanoseconds to advance the clock by.
 339  *
 340  * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
 341  *
 342  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 343  */
 344 int64_t qtest_clock_step(QTestState *s, int64_t step);
 345
 346 /**
 347  * qtest_clock_set:
 348  * @s: QTestState instance to operate on.
 349  * @val: Nanoseconds value to advance the clock to.
 350  *
 351  * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
 352  *
 353  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 354  */
 355 int64_t qtest_clock_set(QTestState *s, int64_t val);
 356
 357 /**
 358  * qtest_get_arch:
 359  *
 360  * Returns: The architecture for the QEMU executable under test.
 361  */
 362 const char *qtest_get_arch(void);
 363
 364 /**
 365  * qtest_add_func:
 366  * @str: Test case path.
 367  * @fn: Test case function
 368  *
 369  * Add a GTester testcase with the given name and function.
 370  * The path is prefixed with the architecture under test, as
 371  * returned by qtest_get_arch().
 372  */
 373 void qtest_add_func(const char *str, void (*fn));
 374
 375 /**
 376  * qtest_add_data_func:
 377  * @str: Test case path.
 378  * @data: Test case data
 379  * @fn: Test case function
 380  *
 381  * Add a GTester testcase with the given name, data and function.
 382  * The path is prefixed with the architecture under test, as
 383  * returned by qtest_get_arch().
 384  */
 385 void qtest_add_data_func(const char *str, const void *data, void (*fn));
 386
 387 /**
 388  * qtest_add:
 389  * @testpath: Test case path
 390  * @Fixture: Fixture type
 391  * @tdata: Test case data
 392  * @fsetup: Test case setup function
 393  * @ftest: Test case function
 394  * @fteardown: Test case teardown function
 395  *
 396  * Add a GTester testcase with the given name, data and functions.
 397  * The path is prefixed with the architecture under test, as
 398  * returned by qtest_get_arch().
 399  */
 400 #define qtest_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
 401     do { \
 402         char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \
 403         g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \
 404         g_free(path); \
 405     } while (0)
 406
 407 /**
 408  * qtest_start:
 409  * @args: other arguments to pass to QEMU
 410  *
 411  * Start QEMU and assign the resulting #QTestState to a global variable.
 412  * The global variable is used by "shortcut" functions documented below.
 413  *
 414  * Returns: #QTestState instance.
 415  */
 416 static inline QTestState *qtest_start(const char *args)
 417 {
 418     global_qtest = qtest_init(args);
 419     return global_qtest;
 420 }
 421
 422 /**
 423  * qtest_end:
 424  *
 425  * Shut down the QEMU process started by qtest_start().
 426  */
 427 static inline void qtest_end(void)
 428 {
 429     qtest_quit(global_qtest);
 430     global_qtest = NULL;
 431 }
 432
 433 /**
 434  * qmp:
 435  * @fmt...: QMP message to send to qemu
 436  *
 437  * Sends a QMP message to QEMU and returns the response.
 438  */
 439 QDict *qmp(const char *fmt, ...);
 440
 441 /**
 442  * qmp_async:
 443  * @fmt...: QMP message to send to qemu
 444  *
 445  * Sends a QMP message to QEMU and leaves the response in the stream.
 446  */
 447 void qmp_async(const char *fmt, ...);
 448
 449 /**
 450  * qmp_discard_response:
 451  * @fmt...: QMP message to send to qemu
 452  *
 453  * Sends a QMP message to QEMU and consumes the response.
 454  */
 455 void qmp_discard_response(const char *fmt, ...);
 456
 457 /**
 458  * qmp_receive:
 459  *
 460  * Reads a QMP message from QEMU and returns the response.
 461  */
 462 static inline QDict *qmp_receive(void)
 463 {
 464     return qtest_qmp_receive(global_qtest);
 465 }
 466
 467 /**
 468  * qmp_eventwait:
 469  * @s: #event event to wait for.
 470  *
 471  * Continuosly polls for QMP responses until it receives the desired event.
 472  */
 473 static inline void qmp_eventwait(const char *event)
 474 {
 475     return qtest_qmp_eventwait(global_qtest, event);
 476 }
 477
 478 /**
 479  * get_irq:
 480  * @num: Interrupt to observe.
 481  *
 482  * Returns: The level of the @num interrupt.
 483  */
 484 static inline bool get_irq(int num)
 485 {
 486     return qtest_get_irq(global_qtest, num);
 487 }
 488
 489 /**
 490  * irq_intercept_in:
 491  * @string: QOM path of a device.
 492  *
 493  * Associate qtest irqs with the GPIO-in pins of the device
 494  * whose path is specified by @string.
 495  */
 496 static inline void irq_intercept_in(const char *string)
 497 {
 498     qtest_irq_intercept_in(global_qtest, string);
 499 }
 500
 501 /**
 502  * qtest_irq_intercept_out:
 503  * @string: QOM path of a device.
 504  *
 505  * Associate qtest irqs with the GPIO-out pins of the device
 506  * whose path is specified by @string.
 507  */
 508 static inline void irq_intercept_out(const char *string)
 509 {
 510     qtest_irq_intercept_out(global_qtest, string);
 511 }
 512
 513 /**
 514  * outb:
 515  * @addr: I/O port to write to.
 516  * @value: Value being written.
 517  *
 518  * Write an 8-bit value to an I/O port.
 519  */
 520 static inline void outb(uint16_t addr, uint8_t value)
 521 {
 522     qtest_outb(global_qtest, addr, value);
 523 }
 524
 525 /**
 526  * outw:
 527  * @addr: I/O port to write to.
 528  * @value: Value being written.
 529  *
 530  * Write a 16-bit value to an I/O port.
 531  */
 532 static inline void outw(uint16_t addr, uint16_t value)
 533 {
 534     qtest_outw(global_qtest, addr, value);
 535 }
 536
 537 /**
 538  * outl:
 539  * @addr: I/O port to write to.
 540  * @value: Value being written.
 541  *
 542  * Write a 32-bit value to an I/O port.
 543  */
 544 static inline void outl(uint16_t addr, uint32_t value)
 545 {
 546     qtest_outl(global_qtest, addr, value);
 547 }
 548
 549 /**
 550  * inb:
 551  * @addr: I/O port to read from.
 552  *
 553  * Reads an 8-bit value from an I/O port.
 554  *
 555  * Returns: Value read.
 556  */
 557 static inline uint8_t inb(uint16_t addr)
 558 {
 559     return qtest_inb(global_qtest, addr);
 560 }
 561
 562 /**
 563  * inw:
 564  * @addr: I/O port to read from.
 565  *
 566  * Reads a 16-bit value from an I/O port.
 567  *
 568  * Returns: Value read.
 569  */
 570 static inline uint16_t inw(uint16_t addr)
 571 {
 572     return qtest_inw(global_qtest, addr);
 573 }
 574
 575 /**
 576  * inl:
 577  * @addr: I/O port to read from.
 578  *
 579  * Reads a 32-bit value from an I/O port.
 580  *
 581  * Returns: Value read.
 582  */
 583 static inline uint32_t inl(uint16_t addr)
 584 {
 585     return qtest_inl(global_qtest, addr);
 586 }
 587
 588 /**
 589  * writeb:
 590  * @addr: Guest address to write to.
 591  * @value: Value being written.
 592  *
 593  * Writes an 8-bit value to guest memory.
 594  */
 595 static inline void writeb(uint64_t addr, uint8_t value)
 596 {
 597     qtest_writeb(global_qtest, addr, value);
 598 }
 599
 600 /**
 601  * writew:
 602  * @addr: Guest address to write to.
 603  * @value: Value being written.
 604  *
 605  * Writes a 16-bit value to guest memory.
 606  */
 607 static inline void writew(uint64_t addr, uint16_t value)
 608 {
 609     qtest_writew(global_qtest, addr, value);
 610 }
 611
 612 /**
 613  * writel:
 614  * @addr: Guest address to write to.
 615  * @value: Value being written.
 616  *
 617  * Writes a 32-bit value to guest memory.
 618  */
 619 static inline void writel(uint64_t addr, uint32_t value)
 620 {
 621     qtest_writel(global_qtest, addr, value);
 622 }
 623
 624 /**
 625  * writeq:
 626  * @addr: Guest address to write to.
 627  * @value: Value being written.
 628  *
 629  * Writes a 64-bit value to guest memory.
 630  */
 631 static inline void writeq(uint64_t addr, uint64_t value)
 632 {
 633     qtest_writeq(global_qtest, addr, value);
 634 }
 635
 636 /**
 637  * readb:
 638  * @addr: Guest address to read from.
 639  *
 640  * Reads an 8-bit value from guest memory.
 641  *
 642  * Returns: Value read.
 643  */
 644 static inline uint8_t readb(uint64_t addr)
 645 {
 646     return qtest_readb(global_qtest, addr);
 647 }
 648
 649 /**
 650  * readw:
 651  * @addr: Guest address to read from.
 652  *
 653  * Reads a 16-bit value from guest memory.
 654  *
 655  * Returns: Value read.
 656  */
 657 static inline uint16_t readw(uint64_t addr)
 658 {
 659     return qtest_readw(global_qtest, addr);
 660 }
 661
 662 /**
 663  * readl:
 664  * @addr: Guest address to read from.
 665  *
 666  * Reads a 32-bit value from guest memory.
 667  *
 668  * Returns: Value read.
 669  */
 670 static inline uint32_t readl(uint64_t addr)
 671 {
 672     return qtest_readl(global_qtest, addr);
 673 }
 674
 675 /**
 676  * readq:
 677  * @addr: Guest address to read from.
 678  *
 679  * Reads a 64-bit value from guest memory.
 680  *
 681  * Returns: Value read.
 682  */
 683 static inline uint64_t readq(uint64_t addr)
 684 {
 685     return qtest_readq(global_qtest, addr);
 686 }
 687
 688 /**
 689  * memread:
 690  * @addr: Guest address to read from.
 691  * @data: Pointer to where memory contents will be stored.
 692  * @size: Number of bytes to read.
 693  *
 694  * Read guest memory into a buffer.
 695  */
 696 static inline void memread(uint64_t addr, void *data, size_t size)
 697 {
 698     qtest_memread(global_qtest, addr, data, size);
 699 }
 700
 701 /**
 702  * memwrite:
 703  * @addr: Guest address to write to.
 704  * @data: Pointer to the bytes that will be written to guest memory.
 705  * @size: Number of bytes to write.
 706  *
 707  * Write a buffer to guest memory.
 708  */
 709 static inline void memwrite(uint64_t addr, const void *data, size_t size)
 710 {
 711     qtest_memwrite(global_qtest, addr, data, size);
 712 }
 713
 714 /**
 715  * qmemset:
 716  * @addr: Guest address to write to.
 717  * @patt: Byte pattern to fill the guest memory region with.
 718  * @size: Number of bytes to write.
 719  *
 720  * Write a pattern to guest memory.
 721  */
 722 static inline void qmemset(uint64_t addr, uint8_t patt, size_t size)
 723 {
 724     qtest_memset(global_qtest, addr, patt, size);
 725 }
 726
 727 /**
 728  * clock_step_next:
 729  *
 730  * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
 731  *
 732  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 733  */
 734 static inline int64_t clock_step_next(void)
 735 {
 736     return qtest_clock_step_next(global_qtest);
 737 }
 738
 739 /**
 740  * clock_step:
 741  * @step: Number of nanoseconds to advance the clock by.
 742  *
 743  * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
 744  *
 745  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 746  */
 747 static inline int64_t clock_step(int64_t step)
 748 {
 749     return qtest_clock_step(global_qtest, step);
 750 }
 751
 752 /**
 753  * clock_set:
 754  * @val: Nanoseconds value to advance the clock to.
 755  *
 756  * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
 757  *
 758  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 759  */
 760 static inline int64_t clock_set(int64_t val)
 761 {
 762     return qtest_clock_set(global_qtest, val);
 763 }
 764
 765 /**
 766  * qtest_big_endian:
 767  *
 768  * Returns: True if the architecture under test has a big endian configuration.
 769  */
 770 bool qtest_big_endian(void);
 771
 772 #endif