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