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