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