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