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