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 QDict *qmp(const char *fmt, ...);
 360
 361 /**
 362  * qmp_discard_response:
 363  * @fmt...: QMP message to send to qemu
 364  *
 365  * Sends a QMP message to QEMU and consumes the response.
 366  */
 367 void qmp_discard_response(const char *fmt, ...);
 368
 369 /**
 370  * get_irq:
 371  * @num: Interrupt to observe.
 372  *
 373  * Returns: The level of the @num interrupt.
 374  */
 375 static inline bool get_irq(int num)
 376 {
 377     return qtest_get_irq(global_qtest, num);
 378 }
 379
 380 /**
 381  * irq_intercept_in:
 382  * @string: QOM path of a device.
 383  *
 384  * Associate qtest irqs with the GPIO-in pins of the device
 385  * whose path is specified by @string.
 386  */
 387 static inline void irq_intercept_in(const char *string)
 388 {
 389     qtest_irq_intercept_in(global_qtest, string);
 390 }
 391
 392 /**
 393  * qtest_irq_intercept_out:
 394  * @string: QOM path of a device.
 395  *
 396  * Associate qtest irqs with the GPIO-out pins of the device
 397  * whose path is specified by @string.
 398  */
 399 static inline void irq_intercept_out(const char *string)
 400 {
 401     qtest_irq_intercept_out(global_qtest, string);
 402 }
 403
 404 /**
 405  * outb:
 406  * @addr: I/O port to write to.
 407  * @value: Value being written.
 408  *
 409  * Write an 8-bit value to an I/O port.
 410  */
 411 static inline void outb(uint16_t addr, uint8_t value)
 412 {
 413     qtest_outb(global_qtest, addr, value);
 414 }
 415
 416 /**
 417  * outw:
 418  * @addr: I/O port to write to.
 419  * @value: Value being written.
 420  *
 421  * Write a 16-bit value to an I/O port.
 422  */
 423 static inline void outw(uint16_t addr, uint16_t value)
 424 {
 425     qtest_outw(global_qtest, addr, value);
 426 }
 427
 428 /**
 429  * outl:
 430  * @addr: I/O port to write to.
 431  * @value: Value being written.
 432  *
 433  * Write a 32-bit value to an I/O port.
 434  */
 435 static inline void outl(uint16_t addr, uint32_t value)
 436 {
 437     qtest_outl(global_qtest, addr, value);
 438 }
 439
 440 /**
 441  * inb:
 442  * @addr: I/O port to read from.
 443  *
 444  * Reads an 8-bit value from an I/O port.
 445  *
 446  * Returns: Value read.
 447  */
 448 static inline uint8_t inb(uint16_t addr)
 449 {
 450     return qtest_inb(global_qtest, addr);
 451 }
 452
 453 /**
 454  * inw:
 455  * @addr: I/O port to read from.
 456  *
 457  * Reads a 16-bit value from an I/O port.
 458  *
 459  * Returns: Value read.
 460  */
 461 static inline uint16_t inw(uint16_t addr)
 462 {
 463     return qtest_inw(global_qtest, addr);
 464 }
 465
 466 /**
 467  * inl:
 468  * @addr: I/O port to read from.
 469  *
 470  * Reads a 32-bit value from an I/O port.
 471  *
 472  * Returns: Value read.
 473  */
 474 static inline uint32_t inl(uint16_t addr)
 475 {
 476     return qtest_inl(global_qtest, addr);
 477 }
 478
 479 /**
 480  * writeb:
 481  * @addr: Guest address to write to.
 482  * @value: Value being written.
 483  *
 484  * Writes an 8-bit value to guest memory.
 485  */
 486 static inline void writeb(uint64_t addr, uint8_t value)
 487 {
 488     qtest_writeb(global_qtest, addr, value);
 489 }
 490
 491 /**
 492  * writew:
 493  * @addr: Guest address to write to.
 494  * @value: Value being written.
 495  *
 496  * Writes a 16-bit value to guest memory.
 497  */
 498 static inline void writew(uint64_t addr, uint16_t value)
 499 {
 500     qtest_writew(global_qtest, addr, value);
 501 }
 502
 503 /**
 504  * writel:
 505  * @addr: Guest address to write to.
 506  * @value: Value being written.
 507  *
 508  * Writes a 32-bit value to guest memory.
 509  */
 510 static inline void writel(uint64_t addr, uint32_t value)
 511 {
 512     qtest_writel(global_qtest, addr, value);
 513 }
 514
 515 /**
 516  * writeq:
 517  * @addr: Guest address to write to.
 518  * @value: Value being written.
 519  *
 520  * Writes a 64-bit value to guest memory.
 521  */
 522 static inline void writeq(uint64_t addr, uint64_t value)
 523 {
 524     qtest_writeq(global_qtest, addr, value);
 525 }
 526
 527 /**
 528  * readb:
 529  * @addr: Guest address to read from.
 530  *
 531  * Reads an 8-bit value from guest memory.
 532  *
 533  * Returns: Value read.
 534  */
 535 static inline uint8_t readb(uint64_t addr)
 536 {
 537     return qtest_readb(global_qtest, addr);
 538 }
 539
 540 /**
 541  * readw:
 542  * @addr: Guest address to read from.
 543  *
 544  * Reads a 16-bit value from guest memory.
 545  *
 546  * Returns: Value read.
 547  */
 548 static inline uint16_t readw(uint64_t addr)
 549 {
 550     return qtest_readw(global_qtest, addr);
 551 }
 552
 553 /**
 554  * readl:
 555  * @addr: Guest address to read from.
 556  *
 557  * Reads a 32-bit value from guest memory.
 558  *
 559  * Returns: Value read.
 560  */
 561 static inline uint32_t readl(uint64_t addr)
 562 {
 563     return qtest_readl(global_qtest, addr);
 564 }
 565
 566 /**
 567  * readq:
 568  * @addr: Guest address to read from.
 569  *
 570  * Reads a 64-bit value from guest memory.
 571  *
 572  * Returns: Value read.
 573  */
 574 static inline uint64_t readq(uint64_t addr)
 575 {
 576     return qtest_readq(global_qtest, addr);
 577 }
 578
 579 /**
 580  * memread:
 581  * @addr: Guest address to read from.
 582  * @data: Pointer to where memory contents will be stored.
 583  * @size: Number of bytes to read.
 584  *
 585  * Read guest memory into a buffer.
 586  */
 587 static inline void memread(uint64_t addr, void *data, size_t size)
 588 {
 589     qtest_memread(global_qtest, addr, data, size);
 590 }
 591
 592 /**
 593  * memwrite:
 594  * @addr: Guest address to write to.
 595  * @data: Pointer to the bytes that will be written to guest memory.
 596  * @size: Number of bytes to write.
 597  *
 598  * Write a buffer to guest memory.
 599  */
 600 static inline void memwrite(uint64_t addr, const void *data, size_t size)
 601 {
 602     qtest_memwrite(global_qtest, addr, data, size);
 603 }
 604
 605 /**
 606  * clock_step_next:
 607  *
 608  * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
 609  *
 610  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 611  */
 612 static inline int64_t clock_step_next(void)
 613 {
 614     return qtest_clock_step_next(global_qtest);
 615 }
 616
 617 /**
 618  * clock_step:
 619  * @step: Number of nanoseconds to advance the clock by.
 620  *
 621  * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
 622  *
 623  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 624  */
 625 static inline int64_t clock_step(int64_t step)
 626 {
 627     return qtest_clock_step(global_qtest, step);
 628 }
 629
 630 /**
 631  * clock_set:
 632  * @val: Nanoseconds value to advance the clock to.
 633  *
 634  * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
 635  *
 636  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
 637  */
 638 static inline int64_t clock_set(int64_t val)
 639 {
 640     return qtest_clock_set(global_qtest, val);
 641 }
 642
 643 #endif