linux-user: Rename cpu_clone_regs to cpu_clone_regs_child
[qemu/kevin.git] / tests / libqtest.h
blobc9e21e05b37a0efe65ee31f9d66a0729309c82cc
1 /*
2 * QTest
4 * Copyright IBM, Corp. 2012
5 * Copyright Red Hat, Inc. 2012
6 * Copyright SUSE LINUX Products GmbH 2013
8 * Authors:
9 * Anthony Liguori <aliguori@us.ibm.com>
10 * Paolo Bonzini <pbonzini@redhat.com>
11 * Andreas Färber <afaerber@suse.de>
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.
17 #ifndef LIBQTEST_H
18 #define LIBQTEST_H
20 #include "qapi/qmp/qobject.h"
21 #include "qapi/qmp/qdict.h"
23 typedef struct QTestState QTestState;
25 /**
26 * qtest_initf:
27 * @fmt...: Format for creating other arguments to pass to QEMU, formatted
28 * like sprintf().
30 * Convenience wrapper around qtest_init().
32 * Returns: #QTestState instance.
34 QTestState *qtest_initf(const char *fmt, ...) GCC_FMT_ATTR(1, 2);
36 /**
37 * qtest_vinitf:
38 * @fmt: Format for creating other arguments to pass to QEMU, formatted
39 * like vsprintf().
40 * @ap: Format arguments.
42 * Convenience wrapper around qtest_init().
44 * Returns: #QTestState instance.
46 QTestState *qtest_vinitf(const char *fmt, va_list ap) GCC_FMT_ATTR(1, 0);
48 /**
49 * qtest_init:
50 * @extra_args: other arguments to pass to QEMU. CAUTION: these
51 * arguments are subject to word splitting and shell evaluation.
53 * Returns: #QTestState instance.
55 QTestState *qtest_init(const char *extra_args);
57 /**
58 * qtest_init_without_qmp_handshake:
59 * @extra_args: other arguments to pass to QEMU. CAUTION: these
60 * arguments are subject to word splitting and shell evaluation.
62 * Returns: #QTestState instance.
64 QTestState *qtest_init_without_qmp_handshake(const char *extra_args);
66 /**
67 * qtest_init_with_serial:
68 * @extra_args: other arguments to pass to QEMU. CAUTION: these
69 * arguments are subject to word splitting and shell evaluation.
70 * @sock_fd: pointer to store the socket file descriptor for
71 * connection with serial.
73 * Returns: #QTestState instance.
75 QTestState *qtest_init_with_serial(const char *extra_args, int *sock_fd);
77 /**
78 * qtest_quit:
79 * @s: #QTestState instance to operate on.
81 * Shut down the QEMU process associated to @s.
83 void qtest_quit(QTestState *s);
85 /**
86 * qtest_qmp_fds:
87 * @s: #QTestState instance to operate on.
88 * @fds: array of file descriptors
89 * @fds_num: number of elements in @fds
90 * @fmt...: QMP message to send to qemu, formatted like
91 * qobject_from_jsonf_nofail(). See parse_escape() for what's
92 * supported after '%'.
94 * Sends a QMP message to QEMU with fds and returns the response.
96 QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num,
97 const char *fmt, ...)
98 GCC_FMT_ATTR(4, 5);
101 * qtest_qmp:
102 * @s: #QTestState instance to operate on.
103 * @fmt...: QMP message to send to qemu, formatted like
104 * qobject_from_jsonf_nofail(). See parse_escape() for what's
105 * supported after '%'.
107 * Sends a QMP message to QEMU and returns the response.
109 QDict *qtest_qmp(QTestState *s, const char *fmt, ...)
110 GCC_FMT_ATTR(2, 3);
113 * qtest_qmp_send:
114 * @s: #QTestState instance to operate on.
115 * @fmt...: QMP message to send to qemu, formatted like
116 * qobject_from_jsonf_nofail(). See parse_escape() for what's
117 * supported after '%'.
119 * Sends a QMP message to QEMU and leaves the response in the stream.
121 void qtest_qmp_send(QTestState *s, const char *fmt, ...)
122 GCC_FMT_ATTR(2, 3);
125 * qtest_qmp_send_raw:
126 * @s: #QTestState instance to operate on.
127 * @fmt...: text to send, formatted like sprintf()
129 * Sends text to the QMP monitor verbatim. Need not be valid JSON;
130 * this is useful for negative tests.
132 void qtest_qmp_send_raw(QTestState *s, const char *fmt, ...)
133 GCC_FMT_ATTR(2, 3);
136 * qtest_vqmp_fds:
137 * @s: #QTestState instance to operate on.
138 * @fds: array of file descriptors
139 * @fds_num: number of elements in @fds
140 * @fmt: QMP message to send to QEMU, formatted like
141 * qobject_from_jsonf_nofail(). See parse_escape() for what's
142 * supported after '%'.
143 * @ap: QMP message arguments
145 * Sends a QMP message to QEMU with fds and returns the response.
147 QDict *qtest_vqmp_fds(QTestState *s, int *fds, size_t fds_num,
148 const char *fmt, va_list ap)
149 GCC_FMT_ATTR(4, 0);
152 * qtest_vqmp:
153 * @s: #QTestState instance to operate on.
154 * @fmt: QMP message to send to QEMU, formatted like
155 * qobject_from_jsonf_nofail(). See parse_escape() for what's
156 * supported after '%'.
157 * @ap: QMP message arguments
159 * Sends a QMP message to QEMU and returns the response.
161 QDict *qtest_vqmp(QTestState *s, const char *fmt, va_list ap)
162 GCC_FMT_ATTR(2, 0);
165 * qtest_qmp_vsend_fds:
166 * @s: #QTestState instance to operate on.
167 * @fds: array of file descriptors
168 * @fds_num: number of elements in @fds
169 * @fmt: QMP message to send to QEMU, formatted like
170 * qobject_from_jsonf_nofail(). See parse_escape() for what's
171 * supported after '%'.
172 * @ap: QMP message arguments
174 * Sends a QMP message to QEMU and leaves the response in the stream.
176 void qtest_qmp_vsend_fds(QTestState *s, int *fds, size_t fds_num,
177 const char *fmt, va_list ap)
178 GCC_FMT_ATTR(4, 0);
181 * qtest_qmp_vsend:
182 * @s: #QTestState instance to operate on.
183 * @fmt: QMP message to send to QEMU, formatted like
184 * qobject_from_jsonf_nofail(). See parse_escape() for what's
185 * supported after '%'.
186 * @ap: QMP message arguments
188 * Sends a QMP message to QEMU and leaves the response in the stream.
190 void qtest_qmp_vsend(QTestState *s, const char *fmt, va_list ap)
191 GCC_FMT_ATTR(2, 0);
194 * qtest_receive:
195 * @s: #QTestState instance to operate on.
197 * Reads a QMP message from QEMU and returns the response.
199 QDict *qtest_qmp_receive(QTestState *s);
202 * qtest_qmp_eventwait:
203 * @s: #QTestState instance to operate on.
204 * @s: #event event to wait for.
206 * Continuously polls for QMP responses until it receives the desired event.
208 void qtest_qmp_eventwait(QTestState *s, const char *event);
211 * qtest_qmp_eventwait_ref:
212 * @s: #QTestState instance to operate on.
213 * @s: #event event to wait for.
215 * Continuously polls for QMP responses until it receives the desired event.
216 * Returns a copy of the event for further investigation.
218 QDict *qtest_qmp_eventwait_ref(QTestState *s, const char *event);
221 * qtest_qmp_receive_success:
222 * @s: #QTestState instance to operate on
223 * @event_cb: Event callback
224 * @opaque: Argument for @event_cb
226 * Poll QMP messages until a command success response is received.
227 * If @event_cb, call it for each event received, passing @opaque,
228 * the event's name and data.
229 * Return the success response's "return" member.
231 QDict *qtest_qmp_receive_success(QTestState *s,
232 void (*event_cb)(void *opaque,
233 const char *name,
234 QDict *data),
235 void *opaque);
238 * qtest_hmp:
239 * @s: #QTestState instance to operate on.
240 * @fmt...: HMP command to send to QEMU, formats arguments like sprintf().
242 * Send HMP command to QEMU via QMP's human-monitor-command.
243 * QMP events are discarded.
245 * Returns: the command's output. The caller should g_free() it.
247 char *qtest_hmp(QTestState *s, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
250 * qtest_hmpv:
251 * @s: #QTestState instance to operate on.
252 * @fmt: HMP command to send to QEMU, formats arguments like vsprintf().
253 * @ap: HMP command arguments
255 * Send HMP command to QEMU via QMP's human-monitor-command.
256 * QMP events are discarded.
258 * Returns: the command's output. The caller should g_free() it.
260 char *qtest_vhmp(QTestState *s, const char *fmt, va_list ap)
261 GCC_FMT_ATTR(2, 0);
263 void qtest_module_load(QTestState *s, const char *prefix, const char *libname);
266 * qtest_get_irq:
267 * @s: #QTestState instance to operate on.
268 * @num: Interrupt to observe.
270 * Returns: The level of the @num interrupt.
272 bool qtest_get_irq(QTestState *s, int num);
275 * qtest_irq_intercept_in:
276 * @s: #QTestState instance to operate on.
277 * @string: QOM path of a device.
279 * Associate qtest irqs with the GPIO-in pins of the device
280 * whose path is specified by @string.
282 void qtest_irq_intercept_in(QTestState *s, const char *string);
285 * qtest_irq_intercept_out:
286 * @s: #QTestState instance to operate on.
287 * @string: QOM path of a device.
289 * Associate qtest irqs with the GPIO-out pins of the device
290 * whose path is specified by @string.
292 void qtest_irq_intercept_out(QTestState *s, const char *string);
295 * qtest_set_irq_in:
296 * @s: QTestState instance to operate on.
297 * @string: QOM path of a device
298 * @name: IRQ name
299 * @irq: IRQ number
300 * @level: IRQ level
302 * Force given device/irq GPIO-in pin to the given level.
304 void qtest_set_irq_in(QTestState *s, const char *string, const char *name,
305 int irq, int level);
308 * qtest_outb:
309 * @s: #QTestState instance to operate on.
310 * @addr: I/O port to write to.
311 * @value: Value being written.
313 * Write an 8-bit value to an I/O port.
315 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value);
318 * qtest_outw:
319 * @s: #QTestState instance to operate on.
320 * @addr: I/O port to write to.
321 * @value: Value being written.
323 * Write a 16-bit value to an I/O port.
325 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value);
328 * qtest_outl:
329 * @s: #QTestState instance to operate on.
330 * @addr: I/O port to write to.
331 * @value: Value being written.
333 * Write a 32-bit value to an I/O port.
335 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value);
338 * qtest_inb:
339 * @s: #QTestState instance to operate on.
340 * @addr: I/O port to read from.
342 * Returns an 8-bit value from an I/O port.
344 uint8_t qtest_inb(QTestState *s, uint16_t addr);
347 * qtest_inw:
348 * @s: #QTestState instance to operate on.
349 * @addr: I/O port to read from.
351 * Returns a 16-bit value from an I/O port.
353 uint16_t qtest_inw(QTestState *s, uint16_t addr);
356 * qtest_inl:
357 * @s: #QTestState instance to operate on.
358 * @addr: I/O port to read from.
360 * Returns a 32-bit value from an I/O port.
362 uint32_t qtest_inl(QTestState *s, uint16_t addr);
365 * qtest_writeb:
366 * @s: #QTestState instance to operate on.
367 * @addr: Guest address to write to.
368 * @value: Value being written.
370 * Writes an 8-bit value to memory.
372 void qtest_writeb(QTestState *s, uint64_t addr, uint8_t value);
375 * qtest_writew:
376 * @s: #QTestState instance to operate on.
377 * @addr: Guest address to write to.
378 * @value: Value being written.
380 * Writes a 16-bit value to memory.
382 void qtest_writew(QTestState *s, uint64_t addr, uint16_t value);
385 * qtest_writel:
386 * @s: #QTestState instance to operate on.
387 * @addr: Guest address to write to.
388 * @value: Value being written.
390 * Writes a 32-bit value to memory.
392 void qtest_writel(QTestState *s, uint64_t addr, uint32_t value);
395 * qtest_writeq:
396 * @s: #QTestState instance to operate on.
397 * @addr: Guest address to write to.
398 * @value: Value being written.
400 * Writes a 64-bit value to memory.
402 void qtest_writeq(QTestState *s, uint64_t addr, uint64_t value);
405 * qtest_readb:
406 * @s: #QTestState instance to operate on.
407 * @addr: Guest address to read from.
409 * Reads an 8-bit value from memory.
411 * Returns: Value read.
413 uint8_t qtest_readb(QTestState *s, uint64_t addr);
416 * qtest_readw:
417 * @s: #QTestState instance to operate on.
418 * @addr: Guest address to read from.
420 * Reads a 16-bit value from memory.
422 * Returns: Value read.
424 uint16_t qtest_readw(QTestState *s, uint64_t addr);
427 * qtest_readl:
428 * @s: #QTestState instance to operate on.
429 * @addr: Guest address to read from.
431 * Reads a 32-bit value from memory.
433 * Returns: Value read.
435 uint32_t qtest_readl(QTestState *s, uint64_t addr);
438 * qtest_readq:
439 * @s: #QTestState instance to operate on.
440 * @addr: Guest address to read from.
442 * Reads a 64-bit value from memory.
444 * Returns: Value read.
446 uint64_t qtest_readq(QTestState *s, uint64_t addr);
449 * qtest_memread:
450 * @s: #QTestState instance to operate on.
451 * @addr: Guest address to read from.
452 * @data: Pointer to where memory contents will be stored.
453 * @size: Number of bytes to read.
455 * Read guest memory into a buffer.
457 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size);
460 * qtest_rtas_call:
461 * @s: #QTestState instance to operate on.
462 * @name: name of the command to call.
463 * @nargs: Number of args.
464 * @args: Guest address to read args from.
465 * @nret: Number of return value.
466 * @ret: Guest address to write return values to.
468 * Call an RTAS function
470 uint64_t qtest_rtas_call(QTestState *s, const char *name,
471 uint32_t nargs, uint64_t args,
472 uint32_t nret, uint64_t ret);
475 * qtest_bufread:
476 * @s: #QTestState instance to operate on.
477 * @addr: Guest address to read from.
478 * @data: Pointer to where memory contents will be stored.
479 * @size: Number of bytes to read.
481 * Read guest memory into a buffer and receive using a base64 encoding.
483 void qtest_bufread(QTestState *s, uint64_t addr, void *data, size_t size);
486 * qtest_memwrite:
487 * @s: #QTestState instance to operate on.
488 * @addr: Guest address to write to.
489 * @data: Pointer to the bytes that will be written to guest memory.
490 * @size: Number of bytes to write.
492 * Write a buffer to guest memory.
494 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size);
497 * qtest_bufwrite:
498 * @s: #QTestState instance to operate on.
499 * @addr: Guest address to write to.
500 * @data: Pointer to the bytes that will be written to guest memory.
501 * @size: Number of bytes to write.
503 * Write a buffer to guest memory and transmit using a base64 encoding.
505 void qtest_bufwrite(QTestState *s, uint64_t addr,
506 const void *data, size_t size);
509 * qtest_memset:
510 * @s: #QTestState instance to operate on.
511 * @addr: Guest address to write to.
512 * @patt: Byte pattern to fill the guest memory region with.
513 * @size: Number of bytes to write.
515 * Write a pattern to guest memory.
517 void qtest_memset(QTestState *s, uint64_t addr, uint8_t patt, size_t size);
520 * qtest_clock_step_next:
521 * @s: #QTestState instance to operate on.
523 * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
525 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
527 int64_t qtest_clock_step_next(QTestState *s);
530 * qtest_clock_step:
531 * @s: QTestState instance to operate on.
532 * @step: Number of nanoseconds to advance the clock by.
534 * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
536 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
538 int64_t qtest_clock_step(QTestState *s, int64_t step);
541 * qtest_clock_set:
542 * @s: QTestState instance to operate on.
543 * @val: Nanoseconds value to advance the clock to.
545 * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
547 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
549 int64_t qtest_clock_set(QTestState *s, int64_t val);
552 * qtest_big_endian:
553 * @s: QTestState instance to operate on.
555 * Returns: True if the architecture under test has a big endian configuration.
557 bool qtest_big_endian(QTestState *s);
560 * qtest_get_arch:
562 * Returns: The architecture for the QEMU executable under test.
564 const char *qtest_get_arch(void);
567 * qtest_add_func:
568 * @str: Test case path.
569 * @fn: Test case function
571 * Add a GTester testcase with the given name and function.
572 * The path is prefixed with the architecture under test, as
573 * returned by qtest_get_arch().
575 void qtest_add_func(const char *str, void (*fn)(void));
578 * qtest_add_data_func:
579 * @str: Test case path.
580 * @data: Test case data
581 * @fn: Test case function
583 * Add a GTester testcase with the given name, data and function.
584 * The path is prefixed with the architecture under test, as
585 * returned by qtest_get_arch().
587 void qtest_add_data_func(const char *str, const void *data,
588 void (*fn)(const void *));
591 * qtest_add_data_func_full:
592 * @str: Test case path.
593 * @data: Test case data
594 * @fn: Test case function
595 * @data_free_func: GDestroyNotify for data
597 * Add a GTester testcase with the given name, data and function.
598 * The path is prefixed with the architecture under test, as
599 * returned by qtest_get_arch().
601 * @data is passed to @data_free_func() on test completion.
603 void qtest_add_data_func_full(const char *str, void *data,
604 void (*fn)(const void *),
605 GDestroyNotify data_free_func);
608 * qtest_add:
609 * @testpath: Test case path
610 * @Fixture: Fixture type
611 * @tdata: Test case data
612 * @fsetup: Test case setup function
613 * @ftest: Test case function
614 * @fteardown: Test case teardown function
616 * Add a GTester testcase with the given name, data and functions.
617 * The path is prefixed with the architecture under test, as
618 * returned by qtest_get_arch().
620 #define qtest_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
621 do { \
622 char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \
623 g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \
624 g_free(path); \
625 } while (0)
627 void qtest_add_abrt_handler(GHookFunc fn, const void *data);
630 * qtest_qmp_assert_success:
631 * @qts: QTestState instance to operate on
632 * @fmt...: QMP message to send to qemu, formatted like
633 * qobject_from_jsonf_nofail(). See parse_escape() for what's
634 * supported after '%'.
636 * Sends a QMP message to QEMU and asserts that a 'return' key is present in
637 * the response.
639 void qtest_qmp_assert_success(QTestState *qts, const char *fmt, ...)
640 GCC_FMT_ATTR(2, 3);
642 QDict *qmp_fd_receive(int fd);
643 void qmp_fd_vsend_fds(int fd, int *fds, size_t fds_num,
644 const char *fmt, va_list ap) GCC_FMT_ATTR(4, 0);
645 void qmp_fd_vsend(int fd, const char *fmt, va_list ap) GCC_FMT_ATTR(2, 0);
646 void qmp_fd_send(int fd, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
647 void qmp_fd_send_raw(int fd, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
648 void qmp_fd_vsend_raw(int fd, const char *fmt, va_list ap) GCC_FMT_ATTR(2, 0);
649 QDict *qmp_fdv(int fd, const char *fmt, va_list ap) GCC_FMT_ATTR(2, 0);
650 QDict *qmp_fd(int fd, const char *fmt, ...) GCC_FMT_ATTR(2, 3);
653 * qtest_cb_for_every_machine:
654 * @cb: Pointer to the callback function
655 * @skip_old_versioned: true if versioned old machine types should be skipped
657 * Call a callback function for every name of all available machines.
659 void qtest_cb_for_every_machine(void (*cb)(const char *machine),
660 bool skip_old_versioned);
663 * qtest_qmp_device_add_qdict:
664 * @qts: QTestState instance to operate on
665 * @drv: Name of the device that should be added
666 * @arguments: QDict with properties for the device to intialize
668 * Generic hot-plugging test via the device_add QMP command with properties
669 * supplied in form of QDict. Use NULL for empty properties list.
671 void qtest_qmp_device_add_qdict(QTestState *qts, const char *drv,
672 const QDict *arguments);
675 * qtest_qmp_device_add:
676 * @qts: QTestState instance to operate on
677 * @driver: Name of the device that should be added
678 * @id: Identification string
679 * @fmt...: QMP message to send to qemu, formatted like
680 * qobject_from_jsonf_nofail(). See parse_escape() for what's
681 * supported after '%'.
683 * Generic hot-plugging test via the device_add QMP command.
685 void qtest_qmp_device_add(QTestState *qts, const char *driver, const char *id,
686 const char *fmt, ...) GCC_FMT_ATTR(4, 5);
689 * qtest_qmp_device_del:
690 * @qts: QTestState instance to operate on
691 * @id: Identification string
693 * Generic hot-unplugging test via the device_del QMP command.
695 void qtest_qmp_device_del(QTestState *qts, const char *id);
698 * qmp_rsp_is_err:
699 * @rsp: QMP response to check for error
701 * Test @rsp for error and discard @rsp.
702 * Returns 'true' if there is error in @rsp and 'false' otherwise.
704 bool qmp_rsp_is_err(QDict *rsp);
707 * qmp_assert_error_class:
708 * @rsp: QMP response to check for error
709 * @class: an error class
711 * Assert the response has the given error class and discard @rsp.
713 void qmp_assert_error_class(QDict *rsp, const char *class);
716 * qtest_probe_child:
717 * @s: QTestState instance to operate on.
719 * Returns: true if the child is still alive.
721 bool qtest_probe_child(QTestState *s);
724 * qtest_set_expected_status:
725 * @s: QTestState instance to operate on.
726 * @status: an expected exit status.
728 * Set expected exit status of the child.
730 void qtest_set_expected_status(QTestState *s, int status);
732 #endif