hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / docs / qmp-events.txt
1                    QEMU Machine Protocol Events
2                    ============================
3
4 ACPI_DEVICE_OST
5 ---------------
6
7 Emitted when guest executes ACPI _OST method.
8
9  - data: ACPIOSTInfo type as described in qapi-schema.json
10
11 { "event": "ACPI_DEVICE_OST",
12      "data": { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0 } }
13
14 BALLOON_CHANGE
15 --------------
16
17 Emitted when the guest changes the actual BALLOON level. This
18 value is equivalent to the 'actual' field return by the
19 'query-balloon' command
20
21 Data:
22
23 - "actual": actual level of the guest memory balloon in bytes (json-number)
24
25 Example:
26
27 { "event": "BALLOON_CHANGE",
28     "data": { "actual": 944766976 },
29     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
30
31 Note: this event is rate-limited.
32
33 BLOCK_IMAGE_CORRUPTED
34 ---------------------
35
36 Emitted when a disk image is being marked corrupt. The image can be
37 identified by its device or node name. The 'device' field is always
38 present for compatibility reasons, but it can be empty ("") if the
39 image does not have a device name associated.
40
41 Data:
42
43 - "device":    Device name (json-string)
44 - "node-name": Node name (json-string, optional)
45 - "msg":       Informative message (e.g., reason for the corruption)
46                (json-string)
47 - "offset":    If the corruption resulted from an image access, this
48                is the host's access offset into the image
49                (json-int, optional)
50 - "size":      If the corruption resulted from an image access, this
51                is the access size (json-int, optional)
52
53 Example:
54
55 { "event": "BLOCK_IMAGE_CORRUPTED",
56     "data": { "device": "ide0-hd0", "node-name": "node0",
57         "msg": "Prevented active L1 table overwrite", "offset": 196608,
58         "size": 65536 },
59     "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
60
61 BLOCK_IO_ERROR
62 --------------
63
64 Emitted when a disk I/O error occurs.
65
66 Data:
67
68 - "device": device name. This is always present for compatibility
69             reasons, but it can be empty ("") if the image does not
70             have a device name associated. (json-string)
71 - "node-name": node name. Note that errors may be reported for the root node
72                that is directly attached to a guest device rather than for the
73                node where the error occurred. (json-string)
74 - "operation": I/O operation (json-string, "read" or "write")
75 - "action": action that has been taken, it's one of the following (json-string):
76     "ignore": error has been ignored
77     "report": error has been reported to the device
78     "stop": the VM is going to stop because of the error
79
80 Example:
81
82 { "event": "BLOCK_IO_ERROR",
83     "data": { "device": "ide0-hd1",
84               "node-name": "#block212",
85               "operation": "write",
86               "action": "stop" },
87     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
88
89 Note: If action is "stop", a STOP event will eventually follow the
90 BLOCK_IO_ERROR event.
91
92 BLOCK_JOB_CANCELLED
93 -------------------
94
95 Emitted when a block job has been cancelled.
96
97 Data:
98
99 - "type":     Job type (json-string; "stream" for image streaming
100                                      "commit" for block commit)
101 - "device":   Job identifier. Originally the device name but other
102               values are allowed since QEMU 2.7 (json-string)
103 - "len":      Maximum progress value (json-int)
104 - "offset":   Current progress value (json-int)
105               On success this is equal to len.
106               On failure this is less than len.
107 - "speed":    Rate limit, bytes per second (json-int)
108
109 Example:
110
111 { "event": "BLOCK_JOB_CANCELLED",
112      "data": { "type": "stream", "device": "virtio-disk0",
113                "len": 10737418240, "offset": 134217728,
114                "speed": 0 },
115      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
116
117 BLOCK_JOB_COMPLETED
118 -------------------
119
120 Emitted when a block job has completed.
121
122 Data:
123
124 - "type":     Job type (json-string; "stream" for image streaming
125                                      "commit" for block commit)
126 - "device":   Job identifier. Originally the device name but other
127               values are allowed since QEMU 2.7 (json-string)
128 - "len":      Maximum progress value (json-int)
129 - "offset":   Current progress value (json-int)
130               On success this is equal to len.
131               On failure this is less than len.
132 - "speed":    Rate limit, bytes per second (json-int)
133 - "error":    Error message (json-string, optional)
134               Only present on failure.  This field contains a human-readable
135               error message.  There are no semantics other than that streaming
136               has failed and clients should not try to interpret the error
137               string.
138
139 Example:
140
141 { "event": "BLOCK_JOB_COMPLETED",
142      "data": { "type": "stream", "device": "virtio-disk0",
143                "len": 10737418240, "offset": 10737418240,
144                "speed": 0 },
145      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
146
147 BLOCK_JOB_ERROR
148 ---------------
149
150 Emitted when a block job encounters an error.
151
152 Data:
153
154 - "device": Job identifier. Originally the device name but other
155             values are allowed since QEMU 2.7 (json-string)
156 - "operation": I/O operation (json-string, "read" or "write")
157 - "action": action that has been taken, it's one of the following (json-string):
158     "ignore": error has been ignored, the job may fail later
159     "report": error will be reported and the job canceled
160     "stop": error caused job to be paused
161
162 Example:
163
164 { "event": "BLOCK_JOB_ERROR",
165     "data": { "device": "ide0-hd1",
166               "operation": "write",
167               "action": "stop" },
168     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
169
170 BLOCK_JOB_READY
171 ---------------
172
173 Emitted when a block job is ready to complete.
174
175 Data:
176
177 - "type":     Job type (json-string; "stream" for image streaming
178                                      "commit" for block commit)
179 - "device":   Job identifier. Originally the device name but other
180               values are allowed since QEMU 2.7 (json-string)
181 - "len":      Maximum progress value (json-int)
182 - "offset":   Current progress value (json-int)
183               On success this is equal to len.
184               On failure this is less than len.
185 - "speed":    Rate limit, bytes per second (json-int)
186
187 Example:
188
189 { "event": "BLOCK_JOB_READY",
190     "data": { "device": "drive0", "type": "mirror", "speed": 0,
191               "len": 2097152, "offset": 2097152 }
192     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
193
194 Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
195 event.
196
197 DEVICE_DELETED
198 --------------
199
200 Emitted whenever the device removal completion is acknowledged
201 by the guest.
202 At this point, it's safe to reuse the specified device ID.
203 Device removal can be initiated by the guest or by HMP/QMP commands.
204
205 Data:
206
207 - "device": device name (json-string, optional)
208 - "path": device path (json-string)
209
210 { "event": "DEVICE_DELETED",
211   "data": { "device": "virtio-net-pci-0",
212             "path": "/machine/peripheral/virtio-net-pci-0" },
213   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
214
215 DEVICE_TRAY_MOVED
216 -----------------
217
218 It's emitted whenever the tray of a removable device is moved by the guest
219 or by HMP/QMP commands.
220
221 Data:
222
223 - "device": Block device name. This is always present for compatibility
224             reasons, but it can be empty ("") if the image does not have a
225             device name associated. (json-string)
226 - "id": The name or QOM path of the guest device (json-string)
227 - "tray-open": true if the tray has been opened or false if it has been closed
228                (json-bool)
229
230 { "event": "DEVICE_TRAY_MOVED",
231   "data": { "device": "ide1-cd0",
232             "id": "/machine/unattached/device[22]",
233             "tray-open": true
234   },
235   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
236
237 DUMP_COMPLETED
238 --------------
239
240 Emitted when the guest has finished one memory dump.
241
242 Data:
243
244 - "result": DumpQueryResult type described in qapi-schema.json
245 - "error": Error message when dump failed. This is only a
246   human-readable string provided when dump failed. It should not be
247   parsed in any way (json-string, optional)
248
249 Example:
250
251 { "event": "DUMP_COMPLETED",
252   "data": {"result": {"total": 1090650112, "status": "completed",
253                       "completed": 1090650112} } }
254
255 GUEST_PANICKED
256 --------------
257
258 Emitted when guest OS panic is detected.
259
260 Data:
261
262 - "action": Action that has been taken (json-string, currently always "pause").
263
264 Example:
265
266 { "event": "GUEST_PANICKED",
267      "data": { "action": "pause" } }
268
269 MEM_UNPLUG_ERROR
270 --------------------
271 Emitted when memory hot unplug error occurs.
272
273 Data:
274
275 - "device": device name (json-string)
276 - "msg": Informative message (e.g., reason for the error) (json-string)
277
278 Example:
279
280 { "event": "MEM_UNPLUG_ERROR"
281   "data": { "device": "dimm1",
282             "msg": "acpi: device unplug for unsupported device"
283   },
284   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
285
286 NIC_RX_FILTER_CHANGED
287 ---------------------
288
289 The event is emitted once until the query command is executed,
290 the first event will always be emitted.
291
292 Data:
293
294 - "name": net client name (json-string)
295 - "path": device path (json-string)
296
297 { "event": "NIC_RX_FILTER_CHANGED",
298   "data": { "name": "vnet0",
299             "path": "/machine/peripheral/vnet0/virtio-backend" },
300   "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
301 }
302
303 POWERDOWN
304 ---------
305
306 Emitted when the Virtual Machine is powered down through the power
307 control system, such as via ACPI.
308
309 Data: None.
310
311 Example:
312
313 { "event": "POWERDOWN",
314     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
315
316 QUORUM_FAILURE
317 --------------
318
319 Emitted by the Quorum block driver if it fails to establish a quorum.
320
321 Data:
322
323 - "reference":     device name if defined else node name.
324 - "sector-num":    Number of the first sector of the failed read operation.
325 - "sectors-count": Failed read operation sector count.
326
327 Example:
328
329 { "event": "QUORUM_FAILURE",
330      "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
331      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
332
333 Note: this event is rate-limited.
334
335 QUORUM_REPORT_BAD
336 -----------------
337
338 Emitted to report a corruption of a Quorum file.
339
340 Data:
341
342 - "type":          Quorum operation type
343 - "error":         Error message (json-string, optional)
344                    Only present on failure.  This field contains a human-readable
345                    error message.  There are no semantics other than that the
346                    block layer reported an error and clients should not try to
347                    interpret the error string.
348 - "node-name":     The graph node name of the block driver state.
349 - "sector-num":    Number of the first sector of the failed read operation.
350 - "sectors-count": Failed read operation sector count.
351
352 Example:
353
354 Read operation:
355 { "event": "QUORUM_REPORT_BAD",
356      "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
357                "type": "read" },
358      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
359
360 Flush operation:
361 { "event": "QUORUM_REPORT_BAD",
362      "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
363                "type": "flush", "error": "Broken pipe" },
364      "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
365
366 Note: this event is rate-limited.
367
368 RESET
369 -----
370
371 Emitted when the Virtual Machine is reset.
372
373 Data: None.
374
375 Example:
376
377 { "event": "RESET",
378     "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
379
380 RESUME
381 ------
382
383 Emitted when the Virtual Machine resumes execution.
384
385 Data: None.
386
387 Example:
388
389 { "event": "RESUME",
390     "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
391
392 RTC_CHANGE
393 ----------
394
395 Emitted when the guest changes the RTC time.
396
397 Data:
398
399 - "offset": Offset between base RTC clock (as specified by -rtc base), and
400 new RTC clock value (json-number)
401
402 Example:
403
404 { "event": "RTC_CHANGE",
405     "data": { "offset": 78 },
406     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
407
408 Note: this event is rate-limited.
409
410 SHUTDOWN
411 --------
412
413 Emitted when the Virtual Machine has shut down, indicating that qemu
414 is about to exit.
415
416 Data: None.
417
418 Example:
419
420 { "event": "SHUTDOWN",
421     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
422
423 Note: If the command-line option "-no-shutdown" has been specified, a STOP
424 event will eventually follow the SHUTDOWN event.
425
426 SPICE_CONNECTED
427 ---------------
428
429 Emitted when a SPICE client connects.
430
431 Data:
432
433 - "server": Server information (json-object)
434   - "host": IP address (json-string)
435   - "port": port number (json-string)
436   - "family": address family (json-string, "ipv4" or "ipv6")
437 - "client": Client information (json-object)
438   - "host": IP address (json-string)
439   - "port": port number (json-string)
440   - "family": address family (json-string, "ipv4" or "ipv6")
441
442 Example:
443
444 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
445   "event": "SPICE_CONNECTED",
446   "data": {
447     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
448     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
449 }}
450
451 SPICE_DISCONNECTED
452 ------------------
453
454 Emitted when a SPICE client disconnects.
455
456 Data:
457
458 - "server": Server information (json-object)
459   - "host": IP address (json-string)
460   - "port": port number (json-string)
461   - "family": address family (json-string, "ipv4" or "ipv6")
462 - "client": Client information (json-object)
463   - "host": IP address (json-string)
464   - "port": port number (json-string)
465   - "family": address family (json-string, "ipv4" or "ipv6")
466
467 Example:
468
469 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
470   "event": "SPICE_DISCONNECTED",
471   "data": {
472     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
473     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
474 }}
475
476 SPICE_INITIALIZED
477 -----------------
478
479 Emitted after initial handshake and authentication takes place (if any)
480 and the SPICE channel is up and running
481
482 Data:
483
484 - "server": Server information (json-object)
485   - "host": IP address (json-string)
486   - "port": port number (json-string)
487   - "family": address family (json-string, "ipv4" or "ipv6")
488   - "auth": authentication method (json-string, optional)
489 - "client": Client information (json-object)
490   - "host": IP address (json-string)
491   - "port": port number (json-string)
492   - "family": address family (json-string, "ipv4" or "ipv6")
493   - "connection-id": spice connection id.  All channels with the same id
494                      belong to the same spice session (json-int)
495   - "channel-type": channel type.  "1" is the main control channel, filter for
496                     this one if you want track spice sessions only (json-int)
497   - "channel-id": channel id.  Usually "0", might be different needed when
498                   multiple channels of the same type exist, such as multiple
499                   display channels in a multihead setup (json-int)
500   - "tls": whevener the channel is encrypted (json-bool)
501
502 Example:
503
504 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
505   "event": "SPICE_INITIALIZED",
506   "data": {"server": {"auth": "spice", "port": "5921",
507                       "family": "ipv4", "host": "127.0.0.1"},
508            "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
509                       "connection-id": 1804289383, "host": "127.0.0.1",
510                       "channel-id": 0, "tls": true}
511 }}
512
513 SPICE_MIGRATE_COMPLETED
514 -----------------------
515
516 Emitted when SPICE migration has completed
517
518 Data: None.
519
520 Example:
521
522 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
523   "event": "SPICE_MIGRATE_COMPLETED" }
524
525 MIGRATION
526 ---------
527
528 Emitted when a migration event happens
529
530 Data: None.
531
532  - "status": migration status
533      See MigrationStatus in ~/qapi-schema.json for possible values
534
535 Example:
536
537 {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
538  "event": "MIGRATION", "data": {"status": "completed"}}
539
540 MIGRATION_PASS
541 --------------
542
543 Emitted from the source side of a migration at the start of each pass
544 (when it syncs the dirty bitmap)
545
546 Data: None.
547
548   - "pass": An incrementing count (starting at 1 on the first pass)
549
550 Example:
551 {"timestamp": {"seconds": 1449669631, "microseconds": 239225},
552  "event": "MIGRATION_PASS", "data": {"pass": 2}}
553
554 STOP
555 ----
556
557 Emitted when the Virtual Machine is stopped.
558
559 Data: None.
560
561 Example:
562
563 { "event": "STOP",
564     "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
565
566 SUSPEND
567 -------
568
569 Emitted when guest enters S3 state.
570
571 Data: None.
572
573 Example:
574
575 { "event": "SUSPEND",
576      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
577
578 SUSPEND_DISK
579 ------------
580
581 Emitted when the guest makes a request to enter S4 state.
582
583 Data: None.
584
585 Example:
586
587 { "event": "SUSPEND_DISK",
588      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
589
590 Note: QEMU shuts down when entering S4 state.
591
592 VNC_CONNECTED
593 -------------
594
595 Emitted when a VNC client establishes a connection.
596
597 Data:
598
599 - "server": Server information (json-object)
600   - "host": IP address (json-string)
601   - "service": port number (json-string)
602   - "family": address family (json-string, "ipv4" or "ipv6")
603   - "auth": authentication method (json-string, optional)
604 - "client": Client information (json-object)
605   - "host": IP address (json-string)
606   - "service": port number (json-string)
607   - "family": address family (json-string, "ipv4" or "ipv6")
608
609 Example:
610
611 { "event": "VNC_CONNECTED",
612     "data": {
613         "server": { "auth": "sasl", "family": "ipv4",
614                     "service": "5901", "host": "0.0.0.0" },
615         "client": { "family": "ipv4", "service": "58425",
616                     "host": "127.0.0.1" } },
617     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
618
619
620 Note: This event is emitted before any authentication takes place, thus
621 the authentication ID is not provided.
622
623 VNC_DISCONNECTED
624 ----------------
625
626 Emitted when the connection is closed.
627
628 Data:
629
630 - "server": Server information (json-object)
631   - "host": IP address (json-string)
632   - "service": port number (json-string)
633   - "family": address family (json-string, "ipv4" or "ipv6")
634   - "auth": authentication method (json-string, optional)
635 - "client": Client information (json-object)
636   - "host": IP address (json-string)
637   - "service": port number (json-string)
638   - "family": address family (json-string, "ipv4" or "ipv6")
639   - "x509_dname": TLS dname (json-string, optional)
640   - "sasl_username": SASL username (json-string, optional)
641
642 Example:
643
644 { "event": "VNC_DISCONNECTED",
645     "data": {
646         "server": { "auth": "sasl", "family": "ipv4",
647                     "service": "5901", "host": "0.0.0.0" },
648         "client": { "family": "ipv4", "service": "58425",
649                     "host": "127.0.0.1", "sasl_username": "luiz" } },
650     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
651
652 VNC_INITIALIZED
653 ---------------
654
655 Emitted after authentication takes place (if any) and the VNC session is
656 made active.
657
658 Data:
659
660 - "server": Server information (json-object)
661   - "host": IP address (json-string)
662   - "service": port number (json-string)
663   - "family": address family (json-string, "ipv4" or "ipv6")
664   - "auth": authentication method (json-string, optional)
665 - "client": Client information (json-object)
666   - "host": IP address (json-string)
667   - "service": port number (json-string)
668   - "family": address family (json-string, "ipv4" or "ipv6")
669   - "x509_dname": TLS dname (json-string, optional)
670   - "sasl_username": SASL username (json-string, optional)
671
672 Example:
673
674 { "event": "VNC_INITIALIZED",
675     "data": {
676         "server": { "auth": "sasl", "family": "ipv4",
677                     "service": "5901", "host": "0.0.0.0"},
678         "client": { "family": "ipv4", "service": "46089",
679                     "host": "127.0.0.1", "sasl_username": "luiz" } },
680         "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
681
682 VSERPORT_CHANGE
683 ---------------
684
685 Emitted when the guest opens or closes a virtio-serial port.
686
687 Data:
688
689 - "id": device identifier of the virtio-serial port (json-string)
690 - "open": true if the guest has opened the virtio-serial port (json-bool)
691
692 Example:
693
694 { "event": "VSERPORT_CHANGE",
695     "data": { "id": "channel0", "open": true },
696     "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
697
698 Note: this event is rate-limited separately for each "id".
699
700 WAKEUP
701 ------
702
703 Emitted when the guest has woken up from S3 and is running.
704
705 Data: None.
706
707 Example:
708
709 { "event": "WAKEUP",
710      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
711
712 WATCHDOG
713 --------
714
715 Emitted when the watchdog device's timer is expired.
716
717 Data:
718
719 - "action": Action that has been taken, it's one of the following (json-string):
720             "reset", "shutdown", "poweroff", "pause", "debug", or "none"
721
722 Example:
723
724 { "event": "WATCHDOG",
725      "data": { "action": "reset" },
726      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
727
728 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
729 followed respectively by the RESET, SHUTDOWN, or STOP events.
730
731 Note: this event is rate-limited.