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