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