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