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