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 QTestState *qtest_init(const char *extra_args);
  31
  32 /**
  33  * qtest_quit:
  34  * @s: QTestState instance to operate on.
  35  *
  36  * Shut down the QEMU process associated to @s.
  37  */
  38 void qtest_quit(QTestState *s);
  39
  40 /**
  41  * qtest_get_irq:
  42  * @s: QTestState instance to operate on.
  43  * @num: Interrupt to observe.
  44  *
  45  * Return the level of the @num interrupt.
  46  */
  47 bool qtest_get_irq(QTestState *s, int num);
  48
  49 /**
  50  * qtest_irq_intercept_in:
  51  * @s: QTestState instance to operate on.
  52  * @string: QOM path of a device.
  53  *
  54  * Associate qtest irqs with the GPIO-in pins of the device
  55  * whose path is specified by @string.
  56  */
  57 void qtest_irq_intercept_in(QTestState *s, const char *string);
  58
  59 /**
  60  * qtest_irq_intercept_out:
  61  * @s: QTestState instance to operate on.
  62  * @string: QOM path of a device.
  63  *
  64  * Associate qtest irqs with the GPIO-out pins of the device
  65  * whose path is specified by @string.
  66  */
  67 void qtest_irq_intercept_out(QTestState *s, const char *string);
  68
  69 /**
  70  * qtest_outb:
  71  * @s: QTestState instance to operate on.
  72  * @addr: I/O port to write to.
  73  * @value: Value being written.
  74  *
  75  * Write an 8-bit value to an I/O port.
  76  */
  77 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value);
  78
  79 /**
  80  * qtest_outw:
  81  * @s: QTestState instance to operate on.
  82  * @addr: I/O port to write to.
  83  * @value: Value being written.
  84  *
  85  * Write a 16-bit value to an I/O port.
  86  */
  87 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value);
  88
  89 /**
  90  * qtest_outl:
  91  * @s: QTestState instance to operate on.
  92  * @addr: I/O port to write to.
  93  * @value: Value being written.
  94  *
  95  * Write a 32-bit value to an I/O port.
  96  */
  97 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value);
  98
  99 /**
 100  * qtest_inb:
 101  * @s: QTestState instance to operate on.
 102  * @addr: I/O port to read from.
 103  * @value: Value being written.
 104  *
 105  * Returns an 8-bit value from an I/O port.
 106  */
 107 uint8_t qtest_inb(QTestState *s, uint16_t addr);
 108
 109 /**
 110  * qtest_inw:
 111  * @s: QTestState instance to operate on.
 112  * @addr: I/O port to read from.
 113  * @value: Value being written.
 114  *
 115  * Returns a 16-bit value from an I/O port.
 116  */
 117 uint16_t qtest_inw(QTestState *s, uint16_t addr);
 118
 119 /**
 120  * qtest_inl:
 121  * @s: QTestState instance to operate on.
 122  * @addr: I/O port to read from.
 123  * @value: Value being written.
 124  *
 125  * Returns a 32-bit value from an I/O port.
 126  */
 127 uint32_t qtest_inl(QTestState *s, uint16_t addr);
 128
 129 /**
 130  * qtest_memread:
 131  * @s: QTestState instance to operate on.
 132  * @addr: Guest address to read from.
 133  * @data: Pointer to where memory contents will be stored.
 134  * @size: Number of bytes to read.
 135  *
 136  * Read guest memory into a buffer.
 137  */
 138 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size);
 139
 140 /**
 141  * qtest_memwrite:
 142  * @s: QTestState instance to operate on.
 143  * @addr: Guest address to write to.
 144  * @data: Pointer to the bytes that will be written to guest memory.
 145  * @size: Number of bytes to write.
 146  *
 147  * Write a buffer to guest memory.
 148  */
 149 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size);
 150
 151 /**
 152  * qtest_clock_step_next:
 153  * @s: QTestState instance to operate on.
 154  *
 155  * Advance the vm_clock to the next deadline.  Return the current
 156  * value of the vm_clock in nanoseconds.
 157  */
 158 int64_t qtest_clock_step_next(QTestState *s);
 159
 160 /**
 161  * qtest_clock_step:
 162  * @s: QTestState instance to operate on.
 163  * @step: Number of nanoseconds to advance the clock by.
 164  *
 165  * Advance the vm_clock by @step nanoseconds.  Return the current
 166  * value of the vm_clock in nanoseconds.
 167  */
 168 int64_t qtest_clock_step(QTestState *s, int64_t step);
 169
 170 /**
 171  * qtest_clock_set:
 172  * @s: QTestState instance to operate on.
 173  * @val: Nanoseconds value to advance the clock to.
 174  *
 175  * Advance the vm_clock to @val nanoseconds since the VM was launched.
 176  * Return the current value of the vm_clock in nanoseconds.
 177  */
 178 int64_t qtest_clock_set(QTestState *s, int64_t val);
 179
 180 /**
 181  * qtest_get_arch:
 182  *
 183  * Returns the architecture for the QEMU executable under test.
 184  */
 185 const char *qtest_get_arch(void);
 186
 187 /**
 188  * qtest_add_func:
 189  * @str: Test case path.
 190  * @fn: Test case function
 191  *
 192  * Add a GTester testcase with the given name and function.
 193  * The path is prefixed with the architecture under test, as
 194  * returned by qtest_get_arch.
 195  */
 196 void qtest_add_func(const char *str, void (*fn));
 197
 198 /**
 199  * qtest_start:
 200  * @args: other arguments to pass to QEMU
 201  *
 202  * Start QEMU and assign the resulting QTestState to a global variable.
 203  * The global variable is used by "shortcut" macros documented below.
 204  */
 205 #define qtest_start(args) (            \
 206     global_qtest = qtest_init((args)) \
 207         )
 208
 209 /**
 210  * get_irq:
 211  * @num: Interrupt to observe.
 212  *
 213  * Return the level of the @num interrupt.
 214  */
 215 #define get_irq(num) qtest_get_irq(global_qtest, num)
 216
 217 /**
 218  * irq_intercept_in:
 219  * @string: QOM path of a device.
 220  *
 221  * Associate qtest irqs with the GPIO-in pins of the device
 222  * whose path is specified by @string.
 223  */
 224 #define irq_intercept_in(string) qtest_irq_intercept_in(global_qtest, string)
 225
 226 /**
 227  * qtest_irq_intercept_out:
 228  * @string: QOM path of a device.
 229  *
 230  * Associate qtest irqs with the GPIO-out pins of the device
 231  * whose path is specified by @string.
 232  */
 233 #define irq_intercept_out(string) qtest_irq_intercept_out(global_qtest, string)
 234
 235 /**
 236  * outb:
 237  * @addr: I/O port to write to.
 238  * @value: Value being written.
 239  *
 240  * Write an 8-bit value to an I/O port.
 241  */
 242 #define outb(addr, val) qtest_outb(global_qtest, addr, val)
 243
 244 /**
 245  * outw:
 246  * @addr: I/O port to write to.
 247  * @value: Value being written.
 248  *
 249  * Write a 16-bit value to an I/O port.
 250  */
 251 #define outw(addr, val) qtest_outw(global_qtest, addr, val)
 252
 253 /**
 254  * outl:
 255  * @addr: I/O port to write to.
 256  * @value: Value being written.
 257  *
 258  * Write a 32-bit value to an I/O port.
 259  */
 260 #define outl(addr, val) qtest_outl(global_qtest, addr, val)
 261
 262 /**
 263  * inb:
 264  * @addr: I/O port to read from.
 265  * @value: Value being written.
 266  *
 267  * Returns an 8-bit value from an I/O port.
 268  */
 269 #define inb(addr) qtest_inb(global_qtest, addr)
 270
 271 /**
 272  * inw:
 273  * @addr: I/O port to read from.
 274  * @value: Value being written.
 275  *
 276  * Returns a 16-bit value from an I/O port.
 277  */
 278 #define inw(addr) qtest_inw(global_qtest, addr)
 279
 280 /**
 281  * inl:
 282  * @addr: I/O port to read from.
 283  * @value: Value being written.
 284  *
 285  * Returns a 32-bit value from an I/O port.
 286  */
 287 #define inl(addr) qtest_inl(global_qtest, addr)
 288
 289 /**
 290  * memread:
 291  * @addr: Guest address to read from.
 292  * @data: Pointer to where memory contents will be stored.
 293  * @size: Number of bytes to read.
 294  *
 295  * Read guest memory into a buffer.
 296  */
 297 #define memread(addr, data, size) qtest_memread(global_qtest, addr, data, size)
 298
 299 /**
 300  * memwrite:
 301  * @addr: Guest address to write to.
 302  * @data: Pointer to the bytes that will be written to guest memory.
 303  * @size: Number of bytes to write.
 304  *
 305  * Write a buffer to guest memory.
 306  */
 307 #define memwrite(addr, data, size) qtest_memwrite(global_qtest, addr, data, size)
 308
 309 /**
 310  * clock_step_next:
 311  *
 312  * Advance the vm_clock to the next deadline.  Return the current
 313  * value of the vm_clock in nanoseconds.
 314  */
 315 #define clock_step_next() qtest_clock_step_next(global_qtest)
 316
 317 /**
 318  * clock_step:
 319  * @step: Number of nanoseconds to advance the clock by.
 320  *
 321  * Advance the vm_clock by @step nanoseconds.  Return the current
 322  * value of the vm_clock in nanoseconds.
 323  */
 324 #define clock_step(step) qtest_clock_step(global_qtest, step)
 325
 326 /**
 327  * clock_set:
 328  * @val: Nanoseconds value to advance the clock to.
 329  *
 330  * Advance the vm_clock to @val nanoseconds since the VM was launched.
 331  * Return the current value of the vm_clock in nanoseconds.
 332  */
 333 #define clock_set(val) qtest_clock_set(global_qtest, val)
 334
 335 #endif