4 * Copyright IBM, Corp. 2012
5 * Copyright Red Hat, Inc. 2012
6 * Copyright SUSE LINUX Products GmbH 2013
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.
20 #include "qapi/qmp/qobject.h"
21 #include "qapi/qmp/qdict.h"
23 typedef struct QTestState QTestState
;
27 * @fmt...: Format for creating other arguments to pass to QEMU, formatted
30 * Convenience wrapper around qtest_init().
32 * Returns: #QTestState instance.
34 QTestState
*qtest_initf(const char *fmt
, ...) GCC_FMT_ATTR(1, 2);
38 * @fmt: Format for creating other arguments to pass to QEMU, formatted
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);
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
);
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
);
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
);
79 * @s: #QTestState instance to operate on.
81 * Shut down the QEMU process associated to @s.
83 void qtest_quit(QTestState
*s
);
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
,
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
, ...)
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
, ...)
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
, ...)
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
)
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
)
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
)
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
)
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
,
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);
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
)
263 void qtest_module_load(QTestState
*s
, const char *prefix
, const char *libname
);
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
);
296 * @s: QTestState instance to operate on.
297 * @string: QOM path of a device
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
,
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
562 * Returns: The architecture for the QEMU executable under test.
564 const char *qtest_get_arch(void);
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
);
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) \
622 char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \
623 g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \
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
639 void qtest_qmp_assert_success(QTestState
*qts
, const char *fmt
, ...)
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
);
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);
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
);