xref: /qemu/tests/qtest/libqtest.h (revision 145f12ea885c8fcfbe2d0ac5230630f071b5a9fb)
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 "qapi/qmp/qobject.h"
21 #include "qapi/qmp/qdict.h"
22 #include "qapi/qmp/qlist.h"
23 #include "libqmp.h"
24 
25 typedef struct QTestState QTestState;
26 
27 /**
28  * qtest_initf:
29  * @fmt: Format for creating other arguments to pass to QEMU, formatted
30  * like sprintf().
31  *
32  * Convenience wrapper around qtest_init().
33  *
34  * Returns: #QTestState instance.
35  */
36 QTestState *qtest_initf(const char *fmt, ...) G_GNUC_PRINTF(1, 2);
37 
38 /**
39  * qtest_vinitf:
40  * @fmt: Format for creating other arguments to pass to QEMU, formatted
41  * like vsprintf().
42  * @ap: Format arguments.
43  *
44  * Convenience wrapper around qtest_init().
45  *
46  * Returns: #QTestState instance.
47  */
48 QTestState *qtest_vinitf(const char *fmt, va_list ap) G_GNUC_PRINTF(1, 0);
49 
50 /**
51  * qtest_init:
52  * @extra_args: other arguments to pass to QEMU.  CAUTION: these
53  * arguments are subject to word splitting and shell evaluation.
54  *
55  * Returns: #QTestState instance.
56  */
57 QTestState *qtest_init(const char *extra_args);
58 
59 /**
60  * qtest_init_with_env:
61  * @var: Environment variable from where to take the QEMU binary
62  * @extra_args: Other arguments to pass to QEMU.  CAUTION: these
63  * arguments are subject to word splitting and shell evaluation.
64  *
65  * Like qtest_init(), but use a different environment variable for the
66  * QEMU binary.
67  *
68  * Returns: #QTestState instance.
69  */
70 QTestState *qtest_init_with_env(const char *var, const char *extra_args);
71 
72 /**
73  * qtest_init_with_env_and_capabilities:
74  * @var: Environment variable from where to take the QEMU binary
75  * @extra_args: Other arguments to pass to QEMU.  CAUTION: these
76  * arguments are subject to word splitting and shell evaluation.
77  * @capabilities: list of QMP capabilities (strings) to enable
78  *
79  * Like qtest_init_with_env(), but enable specified capabilities during
80  * hadshake.
81  *
82  * Returns: #QTestState instance.
83  */
84 QTestState *qtest_init_with_env_and_capabilities(const char *var,
85                                                  const char *extra_args,
86                                                  QList *capabilities);
87 
88 /**
89  * qtest_init_without_qmp_handshake:
90  * @extra_args: other arguments to pass to QEMU.  CAUTION: these
91  * arguments are subject to word splitting and shell evaluation.
92  *
93  * Returns: #QTestState instance.
94  */
95 QTestState *qtest_init_without_qmp_handshake(const char *extra_args);
96 
97 /**
98  * qtest_init_with_serial:
99  * @extra_args: other arguments to pass to QEMU.  CAUTION: these
100  * arguments are subject to word splitting and shell evaluation.
101  * @sock_fd: pointer to store the socket file descriptor for
102  * connection with serial.
103  *
104  * Returns: #QTestState instance.
105  */
106 QTestState *qtest_init_with_serial(const char *extra_args, int *sock_fd);
107 
108 /**
109  * qtest_system_reset:
110  * @s: #QTestState instance to operate on.
111  *
112  * Send a "system_reset" command to the QEMU under test, and wait for
113  * the reset to complete before returning.
114  */
115 void qtest_system_reset(QTestState *s);
116 
117 /**
118  * qtest_system_reset_nowait:
119  * @s: #QTestState instance to operate on.
120  *
121  * Send a "system_reset" command to the QEMU under test, but do not
122  * wait for the reset to complete before returning. The caller is
123  * responsible for waiting for either the RESET event or some other
124  * event of interest to them before proceeding.
125  *
126  * This function should only be used if you're specifically testing
127  * for some other event; in that case you can't use qtest_system_reset()
128  * because it will read and discard any other QMP events that arrive
129  * before the RESET event.
130  */
131 void qtest_system_reset_nowait(QTestState *s);
132 
133 /**
134  * qtest_wait_qemu:
135  * @s: #QTestState instance to operate on.
136  *
137  * Wait for the QEMU process to terminate. It is safe to call this function
138  * multiple times.
139  */
140 void qtest_wait_qemu(QTestState *s);
141 
142 /**
143  * qtest_kill_qemu:
144  * @s: #QTestState instance to operate on.
145  *
146  * Kill the QEMU process and wait for it to terminate. It is safe to call this
147  * function multiple times. Normally qtest_quit() is used instead because it
148  * also frees QTestState. Use qtest_kill_qemu() when you just want to kill QEMU
149  * and qtest_quit() will be called later.
150  */
151 void qtest_kill_qemu(QTestState *s);
152 
153 /**
154  * qtest_quit:
155  * @s: #QTestState instance to operate on.
156  *
157  * Shut down the QEMU process associated to @s.
158  */
159 void qtest_quit(QTestState *s);
160 
161 #ifndef _WIN32
162 /**
163  * qtest_qmp_fds:
164  * @s: #QTestState instance to operate on.
165  * @fds: array of file descriptors
166  * @fds_num: number of elements in @fds
167  * @fmt: QMP message to send to qemu, formatted like
168  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
169  * supported after '%'.
170  *
171  * Sends a QMP message to QEMU with fds and returns the response.
172  */
173 QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num,
174                      const char *fmt, ...)
175     G_GNUC_PRINTF(4, 5);
176 #endif /* _WIN32 */
177 
178 /**
179  * qtest_qmp:
180  * @s: #QTestState instance to operate on.
181  * @fmt: QMP message to send to qemu, formatted like
182  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
183  * supported after '%'.
184  *
185  * Sends a QMP message to QEMU and returns the response.
186  */
187 QDict *qtest_qmp(QTestState *s, const char *fmt, ...)
188     G_GNUC_PRINTF(2, 3);
189 
190 /**
191  * qtest_qmp_send:
192  * @s: #QTestState instance to operate on.
193  * @fmt: QMP message to send to qemu, formatted like
194  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
195  * supported after '%'.
196  *
197  * Sends a QMP message to QEMU and leaves the response in the stream.
198  */
199 void qtest_qmp_send(QTestState *s, const char *fmt, ...)
200     G_GNUC_PRINTF(2, 3);
201 
202 /**
203  * qtest_qmp_send_raw:
204  * @s: #QTestState instance to operate on.
205  * @fmt: text to send, formatted like sprintf()
206  *
207  * Sends text to the QMP monitor verbatim.  Need not be valid JSON;
208  * this is useful for negative tests.
209  */
210 void qtest_qmp_send_raw(QTestState *s, const char *fmt, ...)
211     G_GNUC_PRINTF(2, 3);
212 
213 /**
214  * qtest_socket_server:
215  * @socket_path: the UNIX domain socket path
216  *
217  * Create and return a listen socket file descriptor, or abort on failure.
218  */
219 int qtest_socket_server(const char *socket_path);
220 
221 #ifndef _WIN32
222 /**
223  * qtest_vqmp_fds:
224  * @s: #QTestState instance to operate on.
225  * @fds: array of file descriptors
226  * @fds_num: number of elements in @fds
227  * @fmt: QMP message to send to QEMU, formatted like
228  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
229  * supported after '%'.
230  * @ap: QMP message arguments
231  *
232  * Sends a QMP message to QEMU with fds and returns the response.
233  */
234 QDict *qtest_vqmp_fds(QTestState *s, int *fds, size_t fds_num,
235                       const char *fmt, va_list ap)
236     G_GNUC_PRINTF(4, 0);
237 #endif /* _WIN32 */
238 
239 /**
240  * qtest_vqmp:
241  * @s: #QTestState instance to operate on.
242  * @fmt: QMP message to send to QEMU, formatted like
243  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
244  * supported after '%'.
245  * @ap: QMP message arguments
246  *
247  * Sends a QMP message to QEMU and returns the response.
248  */
249 QDict *qtest_vqmp(QTestState *s, const char *fmt, va_list ap)
250     G_GNUC_PRINTF(2, 0);
251 
252 #ifndef _WIN32
253 /**
254  * qtest_qmp_vsend_fds:
255  * @s: #QTestState instance to operate on.
256  * @fds: array of file descriptors
257  * @fds_num: number of elements in @fds
258  * @fmt: QMP message to send to QEMU, formatted like
259  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
260  * supported after '%'.
261  * @ap: QMP message arguments
262  *
263  * Sends a QMP message to QEMU and leaves the response in the stream.
264  */
265 void qtest_qmp_vsend_fds(QTestState *s, int *fds, size_t fds_num,
266                          const char *fmt, va_list ap)
267     G_GNUC_PRINTF(4, 0);
268 #endif /* _WIN32 */
269 
270 /**
271  * qtest_qmp_vsend:
272  * @s: #QTestState instance to operate on.
273  * @fmt: QMP message to send to QEMU, formatted like
274  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
275  * supported after '%'.
276  * @ap: QMP message arguments
277  *
278  * Sends a QMP message to QEMU and leaves the response in the stream.
279  */
280 void qtest_qmp_vsend(QTestState *s, const char *fmt, va_list ap)
281     G_GNUC_PRINTF(2, 0);
282 
283 /**
284  * qtest_qmp_receive_dict:
285  * @s: #QTestState instance to operate on.
286  *
287  * Reads a QMP message from QEMU and returns the response.
288  */
289 QDict *qtest_qmp_receive_dict(QTestState *s);
290 
291 /**
292  * qtest_qmp_receive:
293  * @s: #QTestState instance to operate on.
294  *
295  * Reads a QMP message from QEMU and returns the response.
296  *
297  * If a callback is registered with qtest_qmp_set_event_callback,
298  * it will be invoked for every event seen, otherwise events
299  * will be buffered until a call to one of the qtest_qmp_eventwait
300  * family of functions.
301  */
302 QDict *qtest_qmp_receive(QTestState *s);
303 
304 /*
305  * QTestQMPEventCallback:
306  * @s: #QTestState instance event was received on
307  * @name: name of the event type
308  * @event: #QDict for the event details
309  * @opaque: opaque data from time of callback registration
310  *
311  * This callback will be invoked whenever an event is received.
312  * If the callback returns true the event will be consumed,
313  * otherwise it will be put on the list of pending events.
314  * Pending events can be later handled by calling either
315  * qtest_qmp_eventwait or qtest_qmp_eventwait_ref.
316  *
317  * Return: true to consume the event, false to let it be queued
318  */
319 typedef bool (*QTestQMPEventCallback)(QTestState *s, const char *name,
320                                       QDict *event, void *opaque);
321 
322 /**
323  * qtest_qmp_set_event_callback:
324  * @s: #QTestSTate instance to operate on
325  * @cb: callback to invoke for events
326  * @opaque: data to pass to @cb
327  *
328  * Register a callback to be invoked whenever an event arrives
329  */
330 void qtest_qmp_set_event_callback(QTestState *s,
331                                   QTestQMPEventCallback cb, void *opaque);
332 
333 /**
334  * qtest_qmp_eventwait:
335  * @s: #QTestState instance to operate on.
336  * @event: event to wait for.
337  *
338  * Continuously polls for QMP responses until it receives the desired event.
339  *
340  * Any callback registered with qtest_qmp_set_event_callback will
341  * be invoked for every event seen.
342  */
343 void qtest_qmp_eventwait(QTestState *s, const char *event);
344 
345 /**
346  * qtest_qmp_eventwait_ref:
347  * @s: #QTestState instance to operate on.
348  * @event: event to wait for.
349  *
350  * Continuously polls for QMP responses until it receives the desired event.
351  *
352  * Any callback registered with qtest_qmp_set_event_callback will
353  * be invoked for every event seen.
354  *
355  * Returns a copy of the event for further investigation.
356  */
357 QDict *qtest_qmp_eventwait_ref(QTestState *s, const char *event);
358 
359 /**
360  * qtest_qmp_event_ref:
361  * @s: #QTestState instance to operate on.
362  * @event: event to return.
363  *
364  * Removes non-matching events from the buffer that was set by
365  * qtest_qmp_receive, until an event bearing the given name is found,
366  * and returns it.
367  * If no event matches, clears the buffer and returns NULL.
368  *
369  */
370 QDict *qtest_qmp_event_ref(QTestState *s, const char *event);
371 
372 /**
373  * qtest_hmp:
374  * @s: #QTestState instance to operate on.
375  * @fmt: HMP command to send to QEMU, formats arguments like sprintf().
376  *
377  * Send HMP command to QEMU via QMP's human-monitor-command.
378  * QMP events are discarded.
379  *
380  * Returns: the command's output.  The caller should g_free() it.
381  */
382 char *qtest_hmp(QTestState *s, const char *fmt, ...) G_GNUC_PRINTF(2, 3);
383 
384 /**
385  * qtest_vhmp:
386  * @s: #QTestState instance to operate on.
387  * @fmt: HMP command to send to QEMU, formats arguments like vsprintf().
388  * @ap: HMP command arguments
389  *
390  * Send HMP command to QEMU via QMP's human-monitor-command.
391  * QMP events are discarded.
392  *
393  * Returns: the command's output.  The caller should g_free() it.
394  */
395 char *qtest_vhmp(QTestState *s, const char *fmt, va_list ap)
396     G_GNUC_PRINTF(2, 0);
397 
398 void qtest_module_load(QTestState *s, const char *prefix, const char *libname);
399 
400 /**
401  * qtest_get_irq:
402  * @s: #QTestState instance to operate on.
403  * @num: Interrupt to observe.
404  *
405  * Returns: The level of the @num interrupt.
406  */
407 bool qtest_get_irq(QTestState *s, int num);
408 
409 /**
410  * qtest_irq_intercept_in:
411  * @s: #QTestState instance to operate on.
412  * @string: QOM path of a device.
413  *
414  * Associate qtest irqs with the GPIO-in pins of the device
415  * whose path is specified by @string.
416  */
417 void qtest_irq_intercept_in(QTestState *s, const char *string);
418 
419 /**
420  * qtest_irq_intercept_out:
421  * @s: #QTestState instance to operate on.
422  * @string: QOM path of a device.
423  *
424  * Associate qtest irqs with the GPIO-out pins of the device
425  * whose path is specified by @string.
426  */
427 void qtest_irq_intercept_out(QTestState *s, const char *string);
428 
429 /**
430  * qtest_irq_intercept_out_named:
431  * @s: #QTestState instance to operate on.
432  * @qom_path: QOM path of a device.
433  * @name: Name of the GPIO out pin
434  *
435  * Associate a qtest irq with the named GPIO-out pin of the device
436  * whose path is specified by @string and whose name is @name.
437  */
438 void qtest_irq_intercept_out_named(QTestState *s, const char *qom_path, const char *name);
439 
440 /**
441  * qtest_set_irq_in:
442  * @s: QTestState instance to operate on.
443  * @string: QOM path of a device
444  * @name: IRQ name
445  * @irq: IRQ number
446  * @level: IRQ level
447  *
448  * Force given device/irq GPIO-in pin to the given level.
449  */
450 void qtest_set_irq_in(QTestState *s, const char *string, const char *name,
451                       int irq, int level);
452 
453 /**
454  * qtest_outb:
455  * @s: #QTestState instance to operate on.
456  * @addr: I/O port to write to.
457  * @value: Value being written.
458  *
459  * Write an 8-bit value to an I/O port.
460  */
461 void qtest_outb(QTestState *s, uint16_t addr, uint8_t value);
462 
463 /**
464  * qtest_outw:
465  * @s: #QTestState instance to operate on.
466  * @addr: I/O port to write to.
467  * @value: Value being written.
468  *
469  * Write a 16-bit value to an I/O port.
470  */
471 void qtest_outw(QTestState *s, uint16_t addr, uint16_t value);
472 
473 /**
474  * qtest_outl:
475  * @s: #QTestState instance to operate on.
476  * @addr: I/O port to write to.
477  * @value: Value being written.
478  *
479  * Write a 32-bit value to an I/O port.
480  */
481 void qtest_outl(QTestState *s, uint16_t addr, uint32_t value);
482 
483 /**
484  * qtest_inb:
485  * @s: #QTestState instance to operate on.
486  * @addr: I/O port to read from.
487  *
488  * Returns an 8-bit value from an I/O port.
489  */
490 uint8_t qtest_inb(QTestState *s, uint16_t addr);
491 
492 /**
493  * qtest_inw:
494  * @s: #QTestState instance to operate on.
495  * @addr: I/O port to read from.
496  *
497  * Returns a 16-bit value from an I/O port.
498  */
499 uint16_t qtest_inw(QTestState *s, uint16_t addr);
500 
501 /**
502  * qtest_inl:
503  * @s: #QTestState instance to operate on.
504  * @addr: I/O port to read from.
505  *
506  * Returns a 32-bit value from an I/O port.
507  */
508 uint32_t qtest_inl(QTestState *s, uint16_t addr);
509 
510 /**
511  * qtest_writeb:
512  * @s: #QTestState instance to operate on.
513  * @addr: Guest address to write to.
514  * @value: Value being written.
515  *
516  * Writes an 8-bit value to memory.
517  */
518 void qtest_writeb(QTestState *s, uint64_t addr, uint8_t value);
519 
520 /**
521  * qtest_writew:
522  * @s: #QTestState instance to operate on.
523  * @addr: Guest address to write to.
524  * @value: Value being written.
525  *
526  * Writes a 16-bit value to memory.
527  */
528 void qtest_writew(QTestState *s, uint64_t addr, uint16_t value);
529 
530 /**
531  * qtest_writel:
532  * @s: #QTestState instance to operate on.
533  * @addr: Guest address to write to.
534  * @value: Value being written.
535  *
536  * Writes a 32-bit value to memory.
537  */
538 void qtest_writel(QTestState *s, uint64_t addr, uint32_t value);
539 
540 /**
541  * qtest_writeq:
542  * @s: #QTestState instance to operate on.
543  * @addr: Guest address to write to.
544  * @value: Value being written.
545  *
546  * Writes a 64-bit value to memory.
547  */
548 void qtest_writeq(QTestState *s, uint64_t addr, uint64_t value);
549 
550 /**
551  * qtest_readb:
552  * @s: #QTestState instance to operate on.
553  * @addr: Guest address to read from.
554  *
555  * Reads an 8-bit value from memory.
556  *
557  * Returns: Value read.
558  */
559 uint8_t qtest_readb(QTestState *s, uint64_t addr);
560 
561 /**
562  * qtest_readw:
563  * @s: #QTestState instance to operate on.
564  * @addr: Guest address to read from.
565  *
566  * Reads a 16-bit value from memory.
567  *
568  * Returns: Value read.
569  */
570 uint16_t qtest_readw(QTestState *s, uint64_t addr);
571 
572 /**
573  * qtest_readl:
574  * @s: #QTestState instance to operate on.
575  * @addr: Guest address to read from.
576  *
577  * Reads a 32-bit value from memory.
578  *
579  * Returns: Value read.
580  */
581 uint32_t qtest_readl(QTestState *s, uint64_t addr);
582 
583 /**
584  * qtest_readq:
585  * @s: #QTestState instance to operate on.
586  * @addr: Guest address to read from.
587  *
588  * Reads a 64-bit value from memory.
589  *
590  * Returns: Value read.
591  */
592 uint64_t qtest_readq(QTestState *s, uint64_t addr);
593 
594 /**
595  * qtest_memread:
596  * @s: #QTestState instance to operate on.
597  * @addr: Guest address to read from.
598  * @data: Pointer to where memory contents will be stored.
599  * @size: Number of bytes to read.
600  *
601  * Read guest memory into a buffer.
602  */
603 void qtest_memread(QTestState *s, uint64_t addr, void *data, size_t size);
604 
605 /**
606  * qtest_rtas_call:
607  * @s: #QTestState instance to operate on.
608  * @name: name of the command to call.
609  * @nargs: Number of args.
610  * @args: Guest address to read args from.
611  * @nret: Number of return value.
612  * @ret: Guest address to write return values to.
613  *
614  * Call an RTAS function
615  */
616 uint64_t qtest_rtas_call(QTestState *s, const char *name,
617                          uint32_t nargs, uint64_t args,
618                          uint32_t nret, uint64_t ret);
619 
620 /**
621  * qtest_csr_call:
622  * @s: #QTestState instance to operate on.
623  * @name: name of the command to call.
624  * @cpu: hart number.
625  * @csr: CSR number.
626  * @val: Value for reading/writing.
627  *
628  * Call an RISC-V CSR read/write function
629  */
630 uint64_t qtest_csr_call(QTestState *s, const char *name,
631                          uint64_t cpu, int csr,
632                          uint64_t *val);
633 
634 /**
635  * qtest_bufread:
636  * @s: #QTestState instance to operate on.
637  * @addr: Guest address to read from.
638  * @data: Pointer to where memory contents will be stored.
639  * @size: Number of bytes to read.
640  *
641  * Read guest memory into a buffer and receive using a base64 encoding.
642  */
643 void qtest_bufread(QTestState *s, uint64_t addr, void *data, size_t size);
644 
645 /**
646  * qtest_memwrite:
647  * @s: #QTestState instance to operate on.
648  * @addr: Guest address to write to.
649  * @data: Pointer to the bytes that will be written to guest memory.
650  * @size: Number of bytes to write.
651  *
652  * Write a buffer to guest memory.
653  */
654 void qtest_memwrite(QTestState *s, uint64_t addr, const void *data, size_t size);
655 
656 /**
657  * qtest_bufwrite:
658  * @s: #QTestState instance to operate on.
659  * @addr: Guest address to write to.
660  * @data: Pointer to the bytes that will be written to guest memory.
661  * @size: Number of bytes to write.
662  *
663  * Write a buffer to guest memory and transmit using a base64 encoding.
664  */
665 void qtest_bufwrite(QTestState *s, uint64_t addr,
666                     const void *data, size_t size);
667 
668 /**
669  * qtest_memset:
670  * @s: #QTestState instance to operate on.
671  * @addr: Guest address to write to.
672  * @patt: Byte pattern to fill the guest memory region with.
673  * @size: Number of bytes to write.
674  *
675  * Write a pattern to guest memory.
676  */
677 void qtest_memset(QTestState *s, uint64_t addr, uint8_t patt, size_t size);
678 
679 /**
680  * qtest_clock_step_next:
681  * @s: #QTestState instance to operate on.
682  *
683  * Advance the QEMU_CLOCK_VIRTUAL to the next deadline.
684  *
685  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
686  */
687 int64_t qtest_clock_step_next(QTestState *s);
688 
689 /**
690  * qtest_clock_step:
691  * @s: QTestState instance to operate on.
692  * @step: Number of nanoseconds to advance the clock by.
693  *
694  * Advance the QEMU_CLOCK_VIRTUAL by @step nanoseconds.
695  *
696  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
697  */
698 int64_t qtest_clock_step(QTestState *s, int64_t step);
699 
700 /**
701  * qtest_clock_set:
702  * @s: QTestState instance to operate on.
703  * @val: Nanoseconds value to advance the clock to.
704  *
705  * Advance the QEMU_CLOCK_VIRTUAL to @val nanoseconds since the VM was launched.
706  *
707  * Returns: The current value of the QEMU_CLOCK_VIRTUAL in nanoseconds.
708  */
709 int64_t qtest_clock_set(QTestState *s, int64_t val);
710 
711 /**
712  * qtest_big_endian:
713  * @s: QTestState instance to operate on.
714  *
715  * Returns: True if the architecture under test has a big endian configuration.
716  */
717 bool qtest_big_endian(QTestState *s);
718 
719 /**
720  * qtest_get_arch:
721  *
722  * Returns: The architecture for the QEMU executable under test.
723  */
724 const char *qtest_get_arch(void);
725 
726 /**
727  * qtest_has_accel:
728  * @accel_name: Accelerator name to check for.
729  *
730  * Returns: true if the accelerator is built in.
731  */
732 bool qtest_has_accel(const char *accel_name);
733 
734 /**
735  * qtest_add_func:
736  * @str: Test case path.
737  * @fn: Test case function
738  *
739  * Add a GTester testcase with the given name and function.
740  * The path is prefixed with the architecture under test, as
741  * returned by qtest_get_arch().
742  */
743 void qtest_add_func(const char *str, void (*fn)(void));
744 
745 /**
746  * qtest_add_data_func:
747  * @str: Test case path.
748  * @data: Test case data
749  * @fn: Test case function
750  *
751  * Add a GTester testcase with the given name, data and function.
752  * The path is prefixed with the architecture under test, as
753  * returned by qtest_get_arch().
754  */
755 void qtest_add_data_func(const char *str, const void *data,
756                          void (*fn)(const void *));
757 
758 /**
759  * qtest_add_data_func_full:
760  * @str: Test case path.
761  * @data: Test case data
762  * @fn: Test case function
763  * @data_free_func: GDestroyNotify for data
764  *
765  * Add a GTester testcase with the given name, data and function.
766  * The path is prefixed with the architecture under test, as
767  * returned by qtest_get_arch().
768  *
769  * @data is passed to @data_free_func() on test completion.
770  */
771 void qtest_add_data_func_full(const char *str, void *data,
772                               void (*fn)(const void *),
773                               GDestroyNotify data_free_func);
774 
775 /**
776  * qtest_add:
777  * @testpath: Test case path
778  * @Fixture: Fixture type
779  * @tdata: Test case data
780  * @fsetup: Test case setup function
781  * @ftest: Test case function
782  * @fteardown: Test case teardown function
783  *
784  * Add a GTester testcase with the given name, data and functions.
785  * The path is prefixed with the architecture under test, as
786  * returned by qtest_get_arch().
787  */
788 #define qtest_add(testpath, Fixture, tdata, fsetup, ftest, fteardown) \
789     do { \
790         char *path = g_strdup_printf("/%s/%s", qtest_get_arch(), testpath); \
791         g_test_add(path, Fixture, tdata, fsetup, ftest, fteardown); \
792         g_free(path); \
793     } while (0)
794 
795 /**
796  * qtest_add_abrt_handler:
797  * @fn: Handler function
798  * @data: Argument that is passed to the handler
799  *
800  * Add a handler function that is invoked on SIGABRT. This can be used to
801  * terminate processes and perform other cleanup. The handler can be removed
802  * with qtest_remove_abrt_handler().
803  */
804 void qtest_add_abrt_handler(GHookFunc fn, const void *data);
805 
806 /**
807  * qtest_remove_abrt_handler:
808  * @data: Argument previously passed to qtest_add_abrt_handler()
809  *
810  * Remove an abrt handler that was previously added with
811  * qtest_add_abrt_handler().
812  */
813 void qtest_remove_abrt_handler(void *data);
814 
815 /**
816  * qtest_vqmp_assert_success_ref:
817  * @qts: QTestState instance to operate on
818  * @fmt: QMP message to send to qemu, formatted like
819  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
820  * supported after '%'.
821  * @args: variable arguments for @fmt
822  *
823  * Sends a QMP message to QEMU, asserts that a 'return' key is present in
824  * the response, and returns the response.
825  */
826 QDict *qtest_vqmp_assert_success_ref(QTestState *qts,
827                                      const char *fmt, va_list args)
828     G_GNUC_PRINTF(2, 0);
829 
830 /**
831  * qtest_vqmp_assert_success:
832  * @qts: QTestState instance to operate on
833  * @fmt: QMP message to send to qemu, formatted like
834  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
835  * supported after '%'.
836  * @args: variable arguments for @fmt
837  *
838  * Sends a QMP message to QEMU and asserts that a 'return' key is present in
839  * the response.
840  */
841 void qtest_vqmp_assert_success(QTestState *qts,
842                                const char *fmt, va_list args)
843     G_GNUC_PRINTF(2, 0);
844 
845 #ifndef _WIN32
846 /**
847  * qtest_vqmp_fds_assert_success_ref:
848  * @qts: QTestState instance to operate on
849  * @fds: the file descriptors to send
850  * @nfds: number of @fds to send
851  * @fmt: QMP message to send to qemu, formatted like
852  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
853  * supported after '%'.
854  * @args: variable arguments for @fmt
855  *
856  * Sends a QMP message with file descriptors to QEMU,
857  * asserts that a 'return' key is present in the response,
858  * and returns the response.
859  */
860 QDict *qtest_vqmp_fds_assert_success_ref(QTestState *qts, int *fds, size_t nfds,
861                                          const char *fmt, va_list args)
862     G_GNUC_PRINTF(4, 0);
863 
864 /**
865  * qtest_vqmp_fds_assert_success:
866  * @qts: QTestState instance to operate on
867  * @fds: the file descriptors to send
868  * @nfds: number of @fds to send
869  * @fmt: QMP message to send to qemu, formatted like
870  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
871  * supported after '%'.
872  * @args: variable arguments for @fmt
873  *
874  * Sends a QMP message with file descriptors to QEMU and
875  * asserts that a 'return' key is present in the response.
876  */
877 void qtest_vqmp_fds_assert_success(QTestState *qts, int *fds, size_t nfds,
878                                    const char *fmt, va_list args)
879     G_GNUC_PRINTF(4, 0);
880 #endif /* !_WIN32 */
881 
882 /**
883  * qtest_qmp_assert_failure_ref:
884  * @qts: QTestState instance to operate on
885  * @fmt: QMP message to send to qemu, formatted like
886  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
887  * supported after '%'.
888  *
889  * Sends a QMP message to QEMU, asserts that an 'error' key is present in
890  * the response, and returns the response.
891  */
892 QDict *qtest_qmp_assert_failure_ref(QTestState *qts, const char *fmt, ...)
893     G_GNUC_PRINTF(2, 3);
894 
895 /**
896  * qtest_vqmp_assert_failure_ref:
897  * @qts: QTestState instance to operate on
898  * @fmt: QMP message to send to qemu, formatted like
899  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
900  * supported after '%'.
901  * @args: variable arguments for @fmt
902  *
903  * Sends a QMP message to QEMU, asserts that an 'error' key is present in
904  * the response, and returns the response.
905  */
906 QDict *qtest_vqmp_assert_failure_ref(QTestState *qts,
907                                      const char *fmt, va_list args)
908     G_GNUC_PRINTF(2, 0);
909 
910 /**
911  * qtest_qmp_assert_success_ref:
912  * @qts: QTestState instance to operate on
913  * @fmt: QMP message to send to qemu, formatted like
914  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
915  * supported after '%'.
916  *
917  * Sends a QMP message to QEMU, asserts that a 'return' key is present in
918  * the response, and returns the response.
919  */
920 QDict *qtest_qmp_assert_success_ref(QTestState *qts, const char *fmt, ...)
921     G_GNUC_PRINTF(2, 3);
922 
923 /**
924  * qtest_qmp_assert_success:
925  * @qts: QTestState instance to operate on
926  * @fmt: QMP message to send to qemu, formatted like
927  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
928  * supported after '%'.
929  *
930  * Sends a QMP message to QEMU and asserts that a 'return' key is present in
931  * the response.
932  */
933 void qtest_qmp_assert_success(QTestState *qts, const char *fmt, ...)
934     G_GNUC_PRINTF(2, 3);
935 
936 #ifndef _WIN32
937 /**
938  * qtest_qmp_fds_assert_success_ref:
939  * @qts: QTestState instance to operate on
940  * @fds: the file descriptors to send
941  * @nfds: number of @fds to send
942  * @fmt: QMP message to send to qemu, formatted like
943  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
944  * supported after '%'.
945  *
946  * Sends a QMP message with file descriptors to QEMU,
947  * asserts that a 'return' key is present in the response,
948  * and returns the response.
949  */
950 QDict *qtest_qmp_fds_assert_success_ref(QTestState *qts, int *fds, size_t nfds,
951                                         const char *fmt, ...)
952     G_GNUC_PRINTF(4, 5);
953 
954 /**
955  * qtest_qmp_fds_assert_success:
956  * @qts: QTestState instance to operate on
957  * @fds: the file descriptors to send
958  * @nfds: number of @fds to send
959  * @fmt: QMP message to send to qemu, formatted like
960  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
961  * supported after '%'.
962  *
963  * Sends a QMP message with file descriptors to QEMU and
964  * asserts that a 'return' key is present in the response.
965  */
966 void qtest_qmp_fds_assert_success(QTestState *qts, int *fds, size_t nfds,
967                                   const char *fmt, ...)
968     G_GNUC_PRINTF(4, 5);
969 #endif /* !_WIN32 */
970 
971 /**
972  * qtest_cb_for_every_machine:
973  * @cb: Pointer to the callback function
974  * @skip_old_versioned: true if versioned old machine types should be skipped
975  *
976  *  Call a callback function for every name of all available machines.
977  */
978 void qtest_cb_for_every_machine(void (*cb)(const char *machine),
979                                 bool skip_old_versioned);
980 
981 /**
982  * qtest_resolve_machine_alias:
983  * @var: Environment variable from where to take the QEMU binary
984  * @alias: The alias to resolve
985  *
986  * Returns: the machine type corresponding to the alias if any,
987  * otherwise NULL.
988  */
989 char *qtest_resolve_machine_alias(const char *var, const char *alias);
990 
991 /**
992  * qtest_has_machine:
993  * @machine: The machine to look for
994  *
995  * Returns: true if the machine is available in the target binary.
996  */
997 bool qtest_has_machine(const char *machine);
998 
999 /**
1000  * qtest_has_machine_with_env:
1001  * @var: Environment variable from where to take the QEMU binary
1002  * @machine: The machine to look for
1003  *
1004  * Returns: true if the machine is available in the specified binary.
1005  */
1006 bool qtest_has_machine_with_env(const char *var, const char *machine);
1007 
1008 /**
1009  * qtest_has_cpu_model:
1010  * @cpu: The cpu to look for
1011  *
1012  * Returns: true if the cpu is available in the target binary.
1013  */
1014 bool qtest_has_cpu_model(const char *cpu);
1015 
1016 /**
1017  * qtest_has_device:
1018  * @device: The device to look for
1019  *
1020  * Returns: true if the device is available in the target binary.
1021  */
1022 bool qtest_has_device(const char *device);
1023 
1024 /**
1025  * qtest_qmp_device_add_qdict:
1026  * @qts: QTestState instance to operate on
1027  * @drv: Name of the device that should be added
1028  * @arguments: QDict with properties for the device to initialize
1029  *
1030  * Generic hot-plugging test via the device_add QMP command with properties
1031  * supplied in form of QDict. Use NULL for empty properties list.
1032  */
1033 void qtest_qmp_device_add_qdict(QTestState *qts, const char *drv,
1034                                 const QDict *arguments);
1035 
1036 /**
1037  * qtest_qmp_device_add:
1038  * @qts: QTestState instance to operate on
1039  * @driver: Name of the device that should be added
1040  * @id: Identification string
1041  * @fmt: QMP message to send to qemu, formatted like
1042  * qobject_from_jsonf_nofail().  See parse_interpolation() for what's
1043  * supported after '%'.
1044  *
1045  * Generic hot-plugging test via the device_add QMP command.
1046  */
1047 void qtest_qmp_device_add(QTestState *qts, const char *driver, const char *id,
1048                           const char *fmt, ...) G_GNUC_PRINTF(4, 5);
1049 
1050 /**
1051  * qtest_qmp_add_client:
1052  * @qts: QTestState instance to operate on
1053  * @protocol: the protocol to add to
1054  * @fd: the client file-descriptor
1055  *
1056  * Call QMP ``getfd`` (on Windows ``get-win32-socket``) followed by
1057  * ``add_client`` with the given @fd.
1058  */
1059 void qtest_qmp_add_client(QTestState *qts, const char *protocol, int fd);
1060 
1061 /**
1062  * qtest_qmp_device_del_send:
1063  * @qts: QTestState instance to operate on
1064  * @id: Identification string
1065  *
1066  * Generic hot-unplugging test via the device_del QMP command.
1067  */
1068 void qtest_qmp_device_del_send(QTestState *qts, const char *id);
1069 
1070 /**
1071  * qtest_qmp_device_del:
1072  * @qts: QTestState instance to operate on
1073  * @id: Identification string
1074  *
1075  * Generic hot-unplugging test via the device_del QMP command.
1076  * Waiting for command completion event.
1077  */
1078 void qtest_qmp_device_del(QTestState *qts, const char *id);
1079 
1080 /**
1081  * qtest_probe_child:
1082  * @s: QTestState instance to operate on.
1083  *
1084  * Returns: true if the child is still alive.
1085  */
1086 bool qtest_probe_child(QTestState *s);
1087 
1088 /**
1089  * qtest_set_expected_status:
1090  * @s: QTestState instance to operate on.
1091  * @status: an expected exit status.
1092  *
1093  * Set expected exit status of the child.
1094  */
1095 void qtest_set_expected_status(QTestState *s, int status);
1096 
1097 QTestState *qtest_inproc_init(QTestState **s, bool log, const char* arch,
1098                     void (*send)(void*, const char*));
1099 
1100 void qtest_client_inproc_recv(void *opaque, const char *str);
1101 
1102 /**
1103  * qtest_qom_set_bool:
1104  * @s: QTestState instance to operate on.
1105  * @path: Path to the property being set.
1106  * @property: Property being set.
1107  * @value: Value to set the property.
1108  *
1109  * Set the property with passed in value.
1110  */
1111 void qtest_qom_set_bool(QTestState *s, const char *path, const char *property,
1112                          bool value);
1113 
1114 /**
1115  * qtest_qom_get_bool:
1116  * @s: QTestState instance to operate on.
1117  * @path: Path to the property being retrieved.
1118  * @property: Property from where the value is being retrieved.
1119  *
1120  * Returns: Value retrieved from property.
1121  */
1122 bool qtest_qom_get_bool(QTestState *s, const char *path, const char *property);
1123 
1124 /**
1125  * qtest_pid:
1126  * @s: QTestState instance to operate on.
1127  *
1128  * Returns: the PID of the QEMU process, or <= 0
1129  */
1130 pid_t qtest_pid(QTestState *s);
1131 
1132 /**
1133  * have_qemu_img:
1134  *
1135  * Returns: true if "qemu-img" is available.
1136  */
1137 bool have_qemu_img(void);
1138 
1139 /**
1140  * mkimg:
1141  * @file: File name of the image that should be created
1142  * @fmt: Format, e.g. "qcow2" or "raw"
1143  * @size_mb: Size of the image in megabytes
1144  *
1145  * Create a disk image with qemu-img. Note that the QTEST_QEMU_IMG
1146  * environment variable must point to the qemu-img file.
1147  *
1148  * Returns: true if the image has been created successfully.
1149  */
1150 bool mkimg(const char *file, const char *fmt, unsigned size_mb);
1151 
1152 #endif
1153