qmp: add ACPI_DEVICE_OST event handling
[qemu.git] / docs / qmp / 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 BLOCK_IMAGE_CORRUPTED
32 ---------------------
33
34 Emitted when a disk image is being marked corrupt.
35
36 Data:
37
38 - "device": Device name (json-string)
39 - "msg":    Informative message (e.g., reason for the corruption) (json-string)
40 - "offset": If the corruption resulted from an image access, this is the access
41             offset into the image (json-int)
42 - "size":   If the corruption resulted from an image access, this is the access
43             size (json-int)
44
45 Example:
46
47 { "event": "BLOCK_IMAGE_CORRUPTED",
48     "data": { "device": "ide0-hd0",
49         "msg": "Prevented active L1 table overwrite", "offset": 196608,
50         "size": 65536 },
51     "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
52
53 BLOCK_IO_ERROR
54 --------------
55
56 Emitted when a disk I/O error occurs.
57
58 Data:
59
60 - "device": device name (json-string)
61 - "operation": I/O operation (json-string, "read" or "write")
62 - "action": action that has been taken, it's one of the following (json-string):
63     "ignore": error has been ignored
64     "report": error has been reported to the device
65     "stop": error caused VM to be stopped
66
67 Example:
68
69 { "event": "BLOCK_IO_ERROR",
70     "data": { "device": "ide0-hd1",
71               "operation": "write",
72               "action": "stop" },
73     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
74
75 Note: If action is "stop", a STOP event will eventually follow the
76 BLOCK_IO_ERROR event.
77
78 BLOCK_JOB_CANCELLED
79 -------------------
80
81 Emitted when a block job has been cancelled.
82
83 Data:
84
85 - "type":     Job type (json-string; "stream" for image streaming
86                                      "commit" for block commit)
87 - "device":   Device name (json-string)
88 - "len":      Maximum progress value (json-int)
89 - "offset":   Current progress value (json-int)
90               On success this is equal to len.
91               On failure this is less than len.
92 - "speed":    Rate limit, bytes per second (json-int)
93
94 Example:
95
96 { "event": "BLOCK_JOB_CANCELLED",
97      "data": { "type": "stream", "device": "virtio-disk0",
98                "len": 10737418240, "offset": 134217728,
99                "speed": 0 },
100      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
101
102 BLOCK_JOB_COMPLETED
103 -------------------
104
105 Emitted when a block job has completed.
106
107 Data:
108
109 - "type":     Job type (json-string; "stream" for image streaming
110                                      "commit" for block commit)
111 - "device":   Device name (json-string)
112 - "len":      Maximum progress value (json-int)
113 - "offset":   Current progress value (json-int)
114               On success this is equal to len.
115               On failure this is less than len.
116 - "speed":    Rate limit, bytes per second (json-int)
117 - "error":    Error message (json-string, optional)
118               Only present on failure.  This field contains a human-readable
119               error message.  There are no semantics other than that streaming
120               has failed and clients should not try to interpret the error
121               string.
122
123 Example:
124
125 { "event": "BLOCK_JOB_COMPLETED",
126      "data": { "type": "stream", "device": "virtio-disk0",
127                "len": 10737418240, "offset": 10737418240,
128                "speed": 0 },
129      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
130
131 BLOCK_JOB_ERROR
132 ---------------
133
134 Emitted when a block job encounters an error.
135
136 Data:
137
138 - "device": device name (json-string)
139 - "operation": I/O operation (json-string, "read" or "write")
140 - "action": action that has been taken, it's one of the following (json-string):
141     "ignore": error has been ignored, the job may fail later
142     "report": error will be reported and the job canceled
143     "stop": error caused job to be paused
144
145 Example:
146
147 { "event": "BLOCK_JOB_ERROR",
148     "data": { "device": "ide0-hd1",
149               "operation": "write",
150               "action": "stop" },
151     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
152
153 BLOCK_JOB_READY
154 ---------------
155
156 Emitted when a block job is ready to complete.
157
158 Data:
159
160 - "device": device name (json-string)
161
162 Example:
163
164 { "event": "BLOCK_JOB_READY",
165     "data": { "device": "ide0-hd1" },
166     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
167
168 Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
169 event.
170
171 DEVICE_DELETED
172 --------------
173
174 Emitted whenever the device removal completion is acknowledged
175 by the guest.
176 At this point, it's safe to reuse the specified device ID.
177 Device removal can be initiated by the guest or by HMP/QMP commands.
178
179 Data:
180
181 - "device": device name (json-string, optional)
182 - "path": device path (json-string)
183
184 { "event": "DEVICE_DELETED",
185   "data": { "device": "virtio-net-pci-0",
186             "path": "/machine/peripheral/virtio-net-pci-0" },
187   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
188
189 DEVICE_TRAY_MOVED
190 -----------------
191
192 It's emitted whenever the tray of a removable device is moved by the guest
193 or by HMP/QMP commands.
194
195 Data:
196
197 - "device": device name (json-string)
198 - "tray-open": true if the tray has been opened or false if it has been closed
199                (json-bool)
200
201 { "event": "DEVICE_TRAY_MOVED",
202   "data": { "device": "ide1-cd0",
203             "tray-open": true
204   },
205   "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
206
207 GUEST_PANICKED
208 --------------
209
210 Emitted when guest OS panic is detected.
211
212 Data:
213
214 - "action": Action that has been taken (json-string, currently always "pause").
215
216 Example:
217
218 { "event": "GUEST_PANICKED",
219      "data": { "action": "pause" } }
220
221 NIC_RX_FILTER_CHANGED
222 ---------------------
223
224 The event is emitted once until the query command is executed,
225 the first event will always be emitted.
226
227 Data:
228
229 - "name": net client name (json-string)
230 - "path": device path (json-string)
231
232 { "event": "NIC_RX_FILTER_CHANGED",
233   "data": { "name": "vnet0",
234             "path": "/machine/peripheral/vnet0/virtio-backend" },
235   "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
236 }
237
238 QUORUM_FAILURE
239 --------------
240
241 Emitted by the Quorum block driver if it fails to establish a quorum.
242
243 Data:
244
245 - "reference":    device name if defined else node name.
246 - "sector-num":   Number of the first sector of the failed read operation.
247 - "sector-count": Failed read operation sector count.
248
249 Example:
250
251 { "event": "QUORUM_FAILURE",
252      "data": { "reference": "usr1", "sector-num": 345435, "sector-count": 5 },
253      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
254
255 QUORUM_REPORT_BAD
256 -----------------
257
258 Emitted to report a corruption of a Quorum file.
259
260 Data:
261
262 - "error":        Error message (json-string, optional)
263                   Only present on failure.  This field contains a human-readable
264                   error message.  There are no semantics other than that the
265                   block layer reported an error and clients should not try to
266                   interpret the error string.
267 - "node-name":    The graph node name of the block driver state.
268 - "sector-num":   Number of the first sector of the failed read operation.
269 - "sector-count": Failed read operation sector count.
270
271 Example:
272
273 { "event": "QUORUM_REPORT_BAD",
274      "data": { "node-name": "1.raw", "sector-num": 345435, "sector-count": 5 },
275      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
276
277 RESET
278 -----
279
280 Emitted when the Virtual Machine is reseted.
281
282 Data: None.
283
284 Example:
285
286 { "event": "RESET",
287     "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
288
289 RESUME
290 ------
291
292 Emitted when the Virtual Machine resumes execution.
293
294 Data: None.
295
296 Example:
297
298 { "event": "RESUME",
299     "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
300
301 RTC_CHANGE
302 ----------
303
304 Emitted when the guest changes the RTC time.
305
306 Data:
307
308 - "offset": Offset between base RTC clock (as specified by -rtc base), and
309 new RTC clock value (json-number)
310
311 Example:
312
313 { "event": "RTC_CHANGE",
314     "data": { "offset": 78 },
315     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
316
317 SHUTDOWN
318 --------
319
320 Emitted when the Virtual Machine is powered down.
321
322 Data: None.
323
324 Example:
325
326 { "event": "SHUTDOWN",
327     "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
328
329 Note: If the command-line option "-no-shutdown" has been specified, a STOP
330 event will eventually follow the SHUTDOWN event.
331
332 SPICE_CONNECTED, SPICE_DISCONNECTED
333 -----------------------------------
334
335 Emitted when a SPICE client connects or disconnects.
336
337 Data:
338
339 - "server": Server information (json-object)
340   - "host": IP address (json-string)
341   - "port": port number (json-string)
342   - "family": address family (json-string, "ipv4" or "ipv6")
343 - "client": Client information (json-object)
344   - "host": IP address (json-string)
345   - "port": port number (json-string)
346   - "family": address family (json-string, "ipv4" or "ipv6")
347
348 Example:
349
350 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
351   "event": "SPICE_CONNECTED",
352   "data": {
353     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
354     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
355 }}
356
357 SPICE_INITIALIZED
358 -----------------
359
360 Emitted after initial handshake and authentication takes place (if any)
361 and the SPICE channel is up'n'running
362
363 Data:
364
365 - "server": Server information (json-object)
366   - "host": IP address (json-string)
367   - "port": port number (json-string)
368   - "family": address family (json-string, "ipv4" or "ipv6")
369   - "auth": authentication method (json-string, optional)
370 - "client": Client information (json-object)
371   - "host": IP address (json-string)
372   - "port": port number (json-string)
373   - "family": address family (json-string, "ipv4" or "ipv6")
374   - "connection-id": spice connection id.  All channels with the same id
375                      belong to the same spice session (json-int)
376   - "channel-type": channel type.  "1" is the main control channel, filter for
377                     this one if you want track spice sessions only (json-int)
378   - "channel-id": channel id.  Usually "0", might be different needed when
379                   multiple channels of the same type exist, such as multiple
380                   display channels in a multihead setup (json-int)
381   - "tls": whevener the channel is encrypted (json-bool)
382
383 Example:
384
385 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
386   "event": "SPICE_INITIALIZED",
387   "data": {"server": {"auth": "spice", "port": "5921",
388                       "family": "ipv4", "host": "127.0.0.1"},
389            "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
390                       "connection-id": 1804289383, "host": "127.0.0.1",
391                       "channel-id": 0, "tls": true}
392 }}
393
394 STOP
395 ----
396
397 Emitted when the Virtual Machine is stopped.
398
399 Data: None.
400
401 Example:
402
403 { "event": "STOP",
404     "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
405
406 SUSPEND
407 -------
408
409 Emitted when guest enters S3 state.
410
411 Data: None.
412
413 Example:
414
415 { "event": "SUSPEND",
416      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
417
418 SUSPEND_DISK
419 ------------
420
421 Emitted when the guest makes a request to enter S4 state.
422
423 Data: None.
424
425 Example:
426
427 { "event": "SUSPEND_DISK",
428      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
429
430 Note: QEMU shuts down when entering S4 state.
431
432 VNC_CONNECTED
433 -------------
434
435 Emitted when a VNC client establishes a connection.
436
437 Data:
438
439 - "server": Server information (json-object)
440   - "host": IP address (json-string)
441   - "service": port number (json-string)
442   - "family": address family (json-string, "ipv4" or "ipv6")
443   - "auth": authentication method (json-string, optional)
444 - "client": Client information (json-object)
445   - "host": IP address (json-string)
446   - "service": port number (json-string)
447   - "family": address family (json-string, "ipv4" or "ipv6")
448
449 Example:
450
451 { "event": "VNC_CONNECTED",
452     "data": {
453         "server": { "auth": "sasl", "family": "ipv4",
454                     "service": "5901", "host": "0.0.0.0" },
455         "client": { "family": "ipv4", "service": "58425",
456                     "host": "127.0.0.1" } },
457     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
458
459
460 Note: This event is emitted before any authentication takes place, thus
461 the authentication ID is not provided.
462
463 VNC_DISCONNECTED
464 ----------------
465
466 Emitted when the connection is closed.
467
468 Data:
469
470 - "server": Server information (json-object)
471   - "host": IP address (json-string)
472   - "service": 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   - "service": port number (json-string)
478   - "family": address family (json-string, "ipv4" or "ipv6")
479   - "x509_dname": TLS dname (json-string, optional)
480   - "sasl_username": SASL username (json-string, optional)
481
482 Example:
483
484 { "event": "VNC_DISCONNECTED",
485     "data": {
486         "server": { "auth": "sasl", "family": "ipv4",
487                     "service": "5901", "host": "0.0.0.0" },
488         "client": { "family": "ipv4", "service": "58425",
489                     "host": "127.0.0.1", "sasl_username": "luiz" } },
490     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
491
492 VNC_INITIALIZED
493 ---------------
494
495 Emitted after authentication takes place (if any) and the VNC session is
496 made active.
497
498 Data:
499
500 - "server": Server information (json-object)
501   - "host": IP address (json-string)
502   - "service": port number (json-string)
503   - "family": address family (json-string, "ipv4" or "ipv6")
504   - "auth": authentication method (json-string, optional)
505 - "client": Client information (json-object)
506   - "host": IP address (json-string)
507   - "service": port number (json-string)
508   - "family": address family (json-string, "ipv4" or "ipv6")
509   - "x509_dname": TLS dname (json-string, optional)
510   - "sasl_username": SASL username (json-string, optional)
511
512 Example:
513
514 { "event": "VNC_INITIALIZED",
515     "data": {
516         "server": { "auth": "sasl", "family": "ipv4",
517                     "service": "5901", "host": "0.0.0.0"},
518         "client": { "family": "ipv4", "service": "46089",
519                     "host": "127.0.0.1", "sasl_username": "luiz" } },
520         "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
521
522 WAKEUP
523 ------
524
525 Emitted when the guest has woken up from S3 and is running.
526
527 Data: None.
528
529 Example:
530
531 { "event": "WAKEUP",
532      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
533
534 WATCHDOG
535 --------
536
537 Emitted when the watchdog device's timer is expired.
538
539 Data:
540
541 - "action": Action that has been taken, it's one of the following (json-string):
542             "reset", "shutdown", "poweroff", "pause", "debug", or "none"
543
544 Example:
545
546 { "event": "WATCHDOG",
547      "data": { "action": "reset" },
548      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
549
550 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
551 followed respectively by the RESET, SHUTDOWN, or STOP events.