tests/libqtest.h

   1 /*
   2  * QTest
   3  *
   4  * Copyright IBM, Corp. 2012
   5  * Copyright Red Hat, Inc. 2012
   6  *
   7  * Authors:
   8  *  Anthony Liguori   <aliguori@us.ibm.com>
   9  *  Paolo Bonzini     <pbonzini@redhat.com>
  10  *
  11  * This work is licensed under the terms of the GNU GPL, version 2 or later.
  12  * See the COPYING file in the top-level directory.
  13  *
  14  */
  15 #ifndef LIBQTEST_H
  16 #define LIBQTEST_H
  17
  18 #include <stdint.h>
  19 #include <stdbool.h>
  20 #include <sys/types.h>
  21
  22 typedef struct QTestState QTestState;
  23
  24 extern QTestState *global_qtest;
  25
  26 /**
  27  * qtest_init:
  28  * @extra_args: other arguments to pass to QEMU.
  29  *
  30  * Returns: #QTestState instance.
  31  */
  32 QTestState *qtest_init(const char *extra_args);
  33
  34 /**
  35  * qtest_quit:
  36  * @s: #QTestState instance to operate on.
  37  *
  38  * Shut down the QEMU process associated to @s.
  39  */
  40 void qtest_quit(QTestState *s);
  41
  42 /**
  43  * qtest_qmp:
  44  * @s: #QTestState instance to operate on.
  45  * @fmt...: QMP message to send to qemu
  46  *
  47  * Sends a QMP message to QEMU
  48  */
  49 void qtest_qmp(QTestState *s, const char *fmt, ...);
  50
  51 /**
  52  * qtest_get_irq:
  53  * @s: #QTestState instance to operate on.
  54  * @num: Interrupt to observe.
  55  *
  56  * Returns: The level of the @num interrupt.
  57  */
  58 bool qtest_get_irq(QTestState *s, int num);
  59
  60 /**
  61  * qtest_irq_intercept_in:
  62  * @s: #QTestState instance to operate on.
  63  * @string: QOM path of a device.
  64  *
  65  * Associate qtest irqs with the GPIO-in pins of the device
  66  * whose path is specified by @string.
  67  */
  68 void qtest_irq_intercept_in(QTestState *s, const char *string);
  69
  70 /**
  71  * qtest_irq_intercept_out:
  72  * @s: #QTestState instance to operate on.
  73  * @string: QOM path of a device.
  74  *
  75  * Associate qtest irqs with the GPIO-out pins of the device
  76  * whose path is specified by @string.
  77  */
  78 void qtest_irq_intercept_out(QTestState *s, const char *string);
  79
  80 /**
  81  * qtest_outb:
  82  * @s: #QTestState instance to operate on.
  83  * @addr: I/O port to write to.
  84  * @value: Value being written.
  85  *
  86  * Write an 8-bit value to an I/O port.
  87  */
  88 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value);
  89
  90 /**
  91  * qtest_outw:
  92  * @s: #QTestState instance to operate on.
  93  * @addr: I/O port to write to.
  94  * @value: Value being written.
  95  *
  96  * Write a 16-bit value to an I/O port.
  97  */
  98 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value);
  99
 100 /**
 101  * qtest_outl:
 102  * @s: #QTestState instance to operate on.
 103  * @addr: I/O port to write to.
 104  * @value: Value being written.
 105  *
 106  * Write a 32-bit value to an I/O port.
 107  */
 108 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value);
 109
 110 /**
 111  * qtest_inb:
 112  * @s: #QTestState instance to operate on.
 113  * @addr: I/O port to read from.
 114  *
 115  * Returns an 8-bit value from an I/O port.
 116  */
 117 uint8_t qtest_inb(QTestState *s, uint16_t addr);
 118
 119 /**
 120  * qtest_inw:
 121  * @s: #QTestState instance to operate on.
 122  * @addr: I/O port to read from.
 123  *
 124  * Returns a 16-bit value from an I/O port.
 125  */
 126 uint16_t qtest_inw(QTestState *s, uint16_t addr);
 127
 128 /**
 129  * qtest_inl:
 130  * @s: #QTestState instance to operate on.
 131  * @addr: I/O port to read from.
 132  *
 133  * Returns a 32-bit value from an I/O port.
 134  */
 135 uint32_t qtest_inl(QTestState *s, uint16_t addr);
 136
 137 /**
 138  * qtest_memread:
 139  * @s: #QTestState instance to operate on.
 140  * @addr: Guest address to read from.
 141  * @data: Pointer to where memory contents will be stored.
 142  * @size: Number of bytes to read.
 143  *
 144  * Read guest memory into a buffer.
 145  */
 146 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size);
 147
 148 /**
 149  * qtest_memwrite:
 150  * @s: #QTestState instance to operate on.
 151  * @addr: Guest address to write to.
 152  * @data: Pointer to the bytes that will be written to guest memory.
 153  * @size: Number of bytes to write.
 154  *
 155  * Write a buffer to guest memory.
 156  */
 157 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size);
 158
 159 /**
 160  * qtest_clock_step_next:
 161  * @s: #QTestState instance to operate on.
 162  *
 163  * Advance the vm_clock to the next deadline.
 164  *
 165  * Returns: The current value of the vm_clock in nanoseconds.
 166  */
 167 int64_t qtest_clock_step_next(QTestState *s);
 168
 169 /**
 170  * qtest_clock_step:
 171  * @s: QTestState instance to operate on.
 172  * @step: Number of nanoseconds to advance the clock by.
 173  *
 174  * Advance the vm_clock by @step nanoseconds.
 175  *
 176  * Returns: The current value of the vm_clock in nanoseconds.
 177  */
 178 int64_t qtest_clock_step(QTestState *s, int64_t step);
 179
 180 /**
 181  * qtest_clock_set:
 182  * @s: QTestState instance to operate on.
 183  * @val: Nanoseconds value to advance the clock to.
 184  *
 185  * Advance the vm_clock to @val nanoseconds since the VM was launched.
 186  *
 187  * Returns: The current value of the vm_clock in nanoseconds.
 188  */
 189 int64_t qtest_clock_set(QTestState *s, int64_t val);
 190
 191 /**
 192  * qtest_get_arch:
 193  *
 194  * Returns: The architecture for the QEMU executable under test.
 195  */
 196 const char *qtest_get_arch(void);
 197
 198 /**
 199  * qtest_add_func:
 200  * @str: Test case path.
 201  * @fn: Test case function
 202  *
 203  * Add a GTester testcase with the given name and function.
 204  * The path is prefixed with the architecture under test, as
 205  * returned by qtest_get_arch().
 206  */
 207 void qtest_add_func(const char *str, void (*fn));
 208
 209 /**
 210  * qtest_start:
 211  * @args: other arguments to pass to QEMU
 212  *
 213  * Start QEMU and assign the resulting #QTestState to a global variable.
 214  * The global variable is used by "shortcut" functions documented below.
 215  *
 216  * Returns: #QTestState instance.
 217  */
 218 static inline QTestState *qtest_start(const char *args)
 219 {
 220     global_qtest = qtest_init(args);
 221     return global_qtest;
 222 }
 223
 224 /**
 225  * qmp:
 226  * @fmt...: QMP message to send to qemu
 227  *
 228  * Sends a QMP message to QEMU
 229  */
 230 #define qmp(fmt, ...) qtest_qmp(global_qtest, fmt, ## __VA_ARGS__)
 231
 232 /**
 233  * get_irq:
 234  * @num: Interrupt to observe.
 235  *
 236  * Returns: The level of the @num interrupt.
 237  */
 238 static inline bool get_irq(int num)
 239 {
 240     return qtest_get_irq(global_qtest, num);
 241 }
 242
 243 /**
 244  * irq_intercept_in:
 245  * @string: QOM path of a device.
 246  *
 247  * Associate qtest irqs with the GPIO-in pins of the device
 248  * whose path is specified by @string.
 249  */
 250 static inline void irq_intercept_in(const char *string)
 251 {
 252     qtest_irq_intercept_in(global_qtest, string);
 253 }
 254
 255 /**
 256  * qtest_irq_intercept_out:
 257  * @string: QOM path of a device.
 258  *
 259  * Associate qtest irqs with the GPIO-out pins of the device
 260  * whose path is specified by @string.
 261  */
 262 static inline void irq_intercept_out(const char *string)
 263 {
 264     qtest_irq_intercept_out(global_qtest, string);
 265 }
 266
 267 /**
 268  * outb:
 269  * @addr: I/O port to write to.
 270  * @value: Value being written.
 271  *
 272  * Write an 8-bit value to an I/O port.
 273  */
 274 static inline void outb(uint16_t addr, uint8_t value)
 275 {
 276     qtest_outb(global_qtest, addr, value);
 277 }
 278
 279 /**
 280  * outw:
 281  * @addr: I/O port to write to.
 282  * @value: Value being written.
 283  *
 284  * Write a 16-bit value to an I/O port.
 285  */
 286 static inline void outw(uint16_t addr, uint16_t value)
 287 {
 288     qtest_outw(global_qtest, addr, value);
 289 }
 290
 291 /**
 292  * outl:
 293  * @addr: I/O port to write to.
 294  * @value: Value being written.
 295  *
 296  * Write a 32-bit value to an I/O port.
 297  */
 298 static inline void outl(uint16_t addr, uint32_t value)
 299 {
 300     qtest_outl(global_qtest, addr, value);
 301 }
 302
 303 /**
 304  * inb:
 305  * @addr: I/O port to read from.
 306  *
 307  * Reads an 8-bit value from an I/O port.
 308  *
 309  * Returns: Value read.
 310  */
 311 static inline uint8_t inb(uint16_t addr)
 312 {
 313     return qtest_inb(global_qtest, addr);
 314 }
 315
 316 /**
 317  * inw:
 318  * @addr: I/O port to read from.
 319  *
 320  * Reads a 16-bit value from an I/O port.
 321  *
 322  * Returns: Value read.
 323  */
 324 static inline uint16_t inw(uint16_t addr)
 325 {
 326     return qtest_inw(global_qtest, addr);
 327 }
 328
 329 /**
 330  * inl:
 331  * @addr: I/O port to read from.
 332  *
 333  * Reads a 32-bit value from an I/O port.
 334  *
 335  * Returns: Value read.
 336  */
 337 static inline uint32_t inl(uint16_t addr)
 338 {
 339     return qtest_inl(global_qtest, addr);
 340 }
 341
 342 /**
 343  * memread:
 344  * @addr: Guest address to read from.
 345  * @data: Pointer to where memory contents will be stored.
 346  * @size: Number of bytes to read.
 347  *
 348  * Read guest memory into a buffer.
 349  */
 350 static inline void memread(uint64_t addr, void *data, size_t size)
 351 {
 352     qtest_memread(global_qtest, addr, data, size);
 353 }
 354
 355 /**
 356  * memwrite:
 357  * @addr: Guest address to write to.
 358  * @data: Pointer to the bytes that will be written to guest memory.
 359  * @size: Number of bytes to write.
 360  *
 361  * Write a buffer to guest memory.
 362  */
 363 static inline void memwrite(uint64_t addr, const void *data, size_t size)
 364 {
 365     qtest_memwrite(global_qtest, addr, data, size);
 366 }
 367
 368 /**
 369  * clock_step_next:
 370  *
 371  * Advance the vm_clock to the next deadline.
 372  *
 373  * Returns: The current value of the vm_clock in nanoseconds.
 374  */
 375 static inline int64_t clock_step_next(void)
 376 {
 377     return qtest_clock_step_next(global_qtest);
 378 }
 379
 380 /**
 381  * clock_step:
 382  * @step: Number of nanoseconds to advance the clock by.
 383  *
 384  * Advance the vm_clock by @step nanoseconds.
 385  *
 386  * Returns: The current value of the vm_clock in nanoseconds.
 387  */
 388 static inline int64_t clock_step(int64_t step)
 389 {
 390     return qtest_clock_step(global_qtest, step);
 391 }
 392
 393 /**
 394  * clock_set:
 395  * @val: Nanoseconds value to advance the clock to.
 396  *
 397  * Advance the vm_clock to @val nanoseconds since the VM was launched.
 398  *
 399  * Returns: The current value of the vm_clock in nanoseconds.
 400  */
 401 static inline int64_t clock_set(int64_t val)
 402 {
 403     return qtest_clock_set(global_qtest, val);
 404 }
 405
 406 #endif