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
)
194 * qtest_qmp_receive_dict:
195 * @s: #QTestState instance to operate on.
197 * Reads a QMP message from QEMU and returns the response.
199 QDict
*qtest_qmp_receive_dict(QTestState
*s
);
203 * @s: #QTestState instance to operate on.
205 * Reads a QMP message from QEMU and returns the response.
206 * Buffers all the events received meanwhile, until a
207 * call to qtest_qmp_eventwait
209 QDict
*qtest_qmp_receive(QTestState
*s
);
212 * qtest_qmp_eventwait:
213 * @s: #QTestState instance to operate on.
214 * @event: event to wait for.
216 * Continuously polls for QMP responses until it receives the desired event.
218 void qtest_qmp_eventwait(QTestState
*s
, const char *event
);
221 * qtest_qmp_eventwait_ref:
222 * @s: #QTestState instance to operate on.
223 * @event: event to wait for.
225 * Continuously polls for QMP responses until it receives the desired event.
226 * Returns a copy of the event for further investigation.
228 QDict
*qtest_qmp_eventwait_ref(QTestState
*s
, const char *event
);
231 * qtest_qmp_event_ref:
232 * @s: #QTestState instance to operate on.
233 * @event: event to return.
235 * Removes non-matching events from the buffer that was set by
236 * qtest_qmp_receive, until an event bearing the given name is found,
238 * If no event matches, clears the buffer and returns NULL.
241 QDict
*qtest_qmp_event_ref(QTestState
*s
, const char *event
);
245 * @s: #QTestState instance to operate on.
246 * @fmt: HMP command to send to QEMU, formats arguments like sprintf().
248 * Send HMP command to QEMU via QMP's human-monitor-command.
249 * QMP events are discarded.
251 * Returns: the command's output. The caller should g_free() it.
253 char *qtest_hmp(QTestState
*s
, const char *fmt
, ...) GCC_FMT_ATTR(2, 3);
257 * @s: #QTestState instance to operate on.
258 * @fmt: HMP command to send to QEMU, formats arguments like vsprintf().
259 * @ap: HMP command arguments
261 * Send HMP command to QEMU via QMP's human-monitor-command.
262 * QMP events are discarded.
264 * Returns: the command's output. The caller should g_free() it.
266 char *qtest_vhmp(QTestState
*s
, const char *fmt
, va_list ap
)
269 void qtest_module_load(QTestState
*s
, const char *prefix
, const char *libname
);
273 * @s: #QTestState instance to operate on.
274 * @num: Interrupt to observe.
276 * Returns: The level of the @num interrupt.
278 bool qtest_get_irq(QTestState
*s
, int num
);
281 * qtest_irq_intercept_in:
282 * @s: #QTestState instance to operate on.
283 * @string: QOM path of a device.
285 * Associate qtest irqs with the GPIO-in pins of the device
286 * whose path is specified by @string.
288 void qtest_irq_intercept_in(QTestState
*s
, const char *string
);
291 * qtest_irq_intercept_out:
292 * @s: #QTestState instance to operate on.
293 * @string: QOM path of a device.
295 * Associate qtest irqs with the GPIO-out pins of the device
296 * whose path is specified by @string.
298 void qtest_irq_intercept_out(QTestState
*s
, const char *string
);
302 * @s: QTestState instance to operate on.
303 * @string: QOM path of a device
308 * Force given device/irq GPIO-in pin to the given level.
310 void qtest_set_irq_in(QTestState
*s
, const char *string
, const char *name
,
315 * @s: #QTestState instance to operate on.
316 * @addr: I/O port to write to.
317 * @value: Value being written.
319 * Write an 8-bit value to an I/O port.
321 void qtest_outb(QTestState
*s
, uint16_t addr
, uint8_t value
);
325 * @s: #QTestState instance to operate on.
326 * @addr: I/O port to write to.
327 * @value: Value being written.
329 * Write a 16-bit value to an I/O port.
331 void qtest_outw(QTestState
*s
, uint16_t addr
, uint16_t value
);
335 * @s: #QTestState instance to operate on.
336 * @addr: I/O port to write to.
337 * @value: Value being written.
339 * Write a 32-bit value to an I/O port.
341 void qtest_outl(QTestState
*s
, uint16_t addr
, uint32_t value
);
345 * @s: #QTestState instance to operate on.
346 * @addr: I/O port to read from.
348 * Returns an 8-bit value from an I/O port.
350 uint8_t qtest_inb(QTestState
*s
, uint16_t addr
);
354 * @s: #QTestState instance to operate on.
355 * @addr: I/O port to read from.
357 * Returns a 16-bit value from an I/O port.
359 uint16_t qtest_inw(QTestState
*s
, uint16_t addr
);
363 * @s: #QTestState instance to operate on.
364 * @addr: I/O port to read from.
366 * Returns a 32-bit value from an I/O port.
368 uint32_t qtest_inl(QTestState
*s
, uint16_t addr
);
372 * @s: #QTestState instance to operate on.
373 * @addr: Guest address to write to.
374 * @value: Value being written.
376 * Writes an 8-bit value to memory.
378 void qtest_writeb(QTestState
*s
, uint64_t addr
, uint8_t value
);
382 * @s: #QTestState instance to operate on.
383 * @addr: Guest address to write to.
384 * @value: Value being written.
386 * Writes a 16-bit value to memory.
388 void qtest_writew(QTestState
*s
, uint64_t addr
, uint16_t value
);
392 * @s: #QTestState instance to operate on.
393 * @addr: Guest address to write to.
394 * @value: Value being written.
396 * Writes a 32-bit value to memory.
398 void qtest_writel(QTestState
*s
, uint64_t addr
, uint32_t value
);
402 * @s: #QTestState instance to operate on.
403 * @addr: Guest address to write to.
404 * @value: Value being written.
406 * Writes a 64-bit value to memory.
408 void qtest_writeq(QTestState
*s
, uint64_t addr
, uint64_t value
);
412 * @s: #QTestState instance to operate on.
413 * @addr: Guest address to read from.
415 * Reads an 8-bit value from memory.
417 * Returns: Value read.
419 uint8_t qtest_readb(QTestState
*s
, uint64_t addr
);
423 * @s: #QTestState instance to operate on.
424 * @addr: Guest address to read from.
426 * Reads a 16-bit value from memory.
428 * Returns: Value read.
430 uint16_t qtest_readw(QTestState
*s
, uint64_t addr
);
434 * @s: #QTestState instance to operate on.
435 * @addr: Guest address to read from.
437 * Reads a 32-bit value from memory.
439 * Returns: Value read.
441 uint32_t qtest_readl(QTestState
*s
, uint64_t addr
);
445 * @s: #QTestState instance to operate on.
446 * @addr: Guest address to read from.
448 * Reads a 64-bit value from memory.
450 * Returns: Value read.
452 uint64_t qtest_readq(QTestState
*s
, uint64_t addr
);
456 * @s: #QTestState instance to operate on.
457 * @addr: Guest address to read from.
458 * @data: Pointer to where memory contents will be stored.
459 * @size: Number of bytes to read.
461 * Read guest memory into a buffer.
463 void qtest_memread(QTestState
*s
, uint64_t addr
, void *data
, size_t size
);
467 * @s: #QTestState instance to operate on.
468 * @name: name of the command to call.
469 * @nargs: Number of args.
470 * @args: Guest address to read args from.
471 * @nret: Number of return value.
472 * @ret: Guest address to write return values to.
474 * Call an RTAS function
476 uint64_t qtest_rtas_call(QTestState
*s
, const char *name
,
477 uint32_t nargs
, uint64_t args
,
478 uint32_t nret
, uint64_t ret
);
482 * @s: #QTestState instance to operate on.
483 * @addr: Guest address to read from.
484 * @data: Pointer to where memory contents will be stored.
485 * @size: Number of bytes to read.
487 * Read guest memory into a buffer and receive using a base64 encoding.
489 void qtest_bufread(QTestState
*s
, uint64_t addr
, void *data
, size_t size
);
493 * @s: #QTestState instance to operate on.
494 * @addr: Guest address to write to.
495 * @data: Pointer to the bytes that will be written to guest memory.
496 * @size: Number of bytes to write.
498 * Write a buffer to guest memory.
500 void qtest_memwrite(QTestState
*s
, uint64_t addr
, const void *data
, size_t size
);
504 * @s: #QTestState instance to operate on.
505 * @addr: Guest address to write to.
506 * @data: Pointer to the bytes that will be written to guest memory.
507 * @size: Number of bytes to write.
509 * Write a buffer to guest memory and transmit using a base64 encoding.
511 void qtest_bufwrite(QTestState
*s
, uint64_t addr
,
512 const void *data
, size_t size
);
516 * @s: #QTestState instance to operate on.
517 * @addr: Guest address to write to.
518 * @patt: Byte pattern to fill the guest memory region with.
519 * @size: Number of bytes to write.
521 * Write a pattern to guest memory.
523 void qtest_memset(QTestState
*s
, uint64_t addr
, uint8_t patt
, size_t size
);
526 * qtest_clock_step_next:
527 * @s: #QTestState instance to operate on.
529 * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
531 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
533 int64_t qtest_clock_step_next(QTestState
*s
);
537 * @s: QTestState instance to operate on.
538 * @step: Number of nanoseconds to advance the clock by.
540 * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
542 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
544 int64_t qtest_clock_step(QTestState
*s
, int64_t step
);
548 * @s: QTestState instance to operate on.
549 * @val: Nanoseconds value to advance the clock to.
551 * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
553 * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
555 int64_t qtest_clock_set(QTestState
*s
, int64_t val
);
559 * @s: QTestState instance to operate on.
561 * Returns: True if the architecture under test has a big endian configuration.
563 bool qtest_big_endian(QTestState
*s
);
568 * Returns: The architecture for the QEMU executable under test.
570 const char *qtest_get_arch(void);
574 * @str: Test case path.
575 * @fn: Test case function
577 * Add a GTester testcase with the given name and function.
578 * The path is prefixed with the architecture under test, as
579 * returned by qtest_get_arch().
581 void qtest_add_func(const char *str
, void (*fn
)(void));
584 * qtest_add_data_func:
585 * @str: Test case path.
586 * @data: Test case data
587 * @fn: Test case function
589 * Add a GTester testcase with the given name, data and function.
590 * The path is prefixed with the architecture under test, as
591 * returned by qtest_get_arch().
593 void qtest_add_data_func(const char *str
, const void *data
,
594 void (*fn
)(const void *));
597 * qtest_add_data_func_full:
598 * @str: Test case path.
599 * @data: Test case data
600 * @fn: Test case function
601 * @data_free_func: GDestroyNotify for data
603 * Add a GTester testcase with the given name, data and function.
604 * The path is prefixed with the architecture under test, as
605 * returned by qtest_get_arch().
607 * @data is passed to @data_free_func() on test completion.
609 void qtest_add_data_func_full(const char *str
, void *data
,
610 void (*fn
)(const void *),
611 GDestroyNotify data_free_func
);
615 * @testpath: Test case path
616 * @Fixture: Fixture type
617 * @tdata: Test case data
618 * @fsetup: Test case setup function
619 * @ftest: Test case function
620 * @fteardown: Test case teardown function
622 * Add a GTester testcase with the given name, data and functions.
623 * The path is prefixed with the architecture under test, as
624 * returned by qtest_get_arch().
626 #define qtest_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
628 char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \
629 g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \
633 void qtest_add_abrt_handler(GHookFunc fn
, const void *data
);
636 * qtest_qmp_assert_success:
637 * @qts: QTestState instance to operate on
638 * @fmt: QMP message to send to qemu, formatted like
639 * qobject_from_jsonf_nofail(). See parse_escape() for what's
640 * supported after '%'.
642 * Sends a QMP message to QEMU and asserts that a 'return' key is present in
645 void qtest_qmp_assert_success(QTestState
*qts
, const char *fmt
, ...)
648 QDict
*qmp_fd_receive(int fd
);
649 void qmp_fd_vsend_fds(int fd
, int *fds
, size_t fds_num
,
650 const char *fmt
, va_list ap
) GCC_FMT_ATTR(4, 0);
651 void qmp_fd_vsend(int fd
, const char *fmt
, va_list ap
) GCC_FMT_ATTR(2, 0);
652 void qmp_fd_send(int fd
, const char *fmt
, ...) GCC_FMT_ATTR(2, 3);
653 void qmp_fd_send_raw(int fd
, const char *fmt
, ...) GCC_FMT_ATTR(2, 3);
654 void qmp_fd_vsend_raw(int fd
, const char *fmt
, va_list ap
) GCC_FMT_ATTR(2, 0);
655 QDict
*qmp_fdv(int fd
, const char *fmt
, va_list ap
) GCC_FMT_ATTR(2, 0);
656 QDict
*qmp_fd(int fd
, const char *fmt
, ...) GCC_FMT_ATTR(2, 3);
659 * qtest_cb_for_every_machine:
660 * @cb: Pointer to the callback function
661 * @skip_old_versioned: true if versioned old machine types should be skipped
663 * Call a callback function for every name of all available machines.
665 void qtest_cb_for_every_machine(void (*cb
)(const char *machine
),
666 bool skip_old_versioned
);
669 * qtest_qmp_device_add_qdict:
670 * @qts: QTestState instance to operate on
671 * @drv: Name of the device that should be added
672 * @arguments: QDict with properties for the device to intialize
674 * Generic hot-plugging test via the device_add QMP command with properties
675 * supplied in form of QDict. Use NULL for empty properties list.
677 void qtest_qmp_device_add_qdict(QTestState
*qts
, const char *drv
,
678 const QDict
*arguments
);
681 * qtest_qmp_device_add:
682 * @qts: QTestState instance to operate on
683 * @driver: Name of the device that should be added
684 * @id: Identification string
685 * @fmt: QMP message to send to qemu, formatted like
686 * qobject_from_jsonf_nofail(). See parse_escape() for what's
687 * supported after '%'.
689 * Generic hot-plugging test via the device_add QMP command.
691 void qtest_qmp_device_add(QTestState
*qts
, const char *driver
, const char *id
,
692 const char *fmt
, ...) GCC_FMT_ATTR(4, 5);
695 * qtest_qmp_device_del:
696 * @qts: QTestState instance to operate on
697 * @id: Identification string
699 * Generic hot-unplugging test via the device_del QMP command.
701 void qtest_qmp_device_del(QTestState
*qts
, const char *id
);
705 * @rsp: QMP response to check for error
707 * Test @rsp for error and discard @rsp.
708 * Returns 'true' if there is error in @rsp and 'false' otherwise.
710 bool qmp_rsp_is_err(QDict
*rsp
);
713 * qmp_expect_error_and_unref:
714 * @rsp: QMP response to check for error
715 * @class: an error class
717 * Assert the response has the given error class and discard @rsp.
719 void qmp_expect_error_and_unref(QDict
*rsp
, const char *class);
723 * @s: QTestState instance to operate on.
725 * Returns: true if the child is still alive.
727 bool qtest_probe_child(QTestState
*s
);
730 * qtest_set_expected_status:
731 * @s: QTestState instance to operate on.
732 * @status: an expected exit status.
734 * Set expected exit status of the child.
736 void qtest_set_expected_status(QTestState
*s
, int status
);
738 QTestState
*qtest_inproc_init(QTestState
**s
, bool log
, const char* arch
,
739 void (*send
)(void*, const char*));
741 void qtest_client_inproc_recv(void *opaque
, const char *str
);