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