qapi event: convert SUSPEND
[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": the VM is going to stop because of the error
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 RTC_CHANGE
278 ----------
279
280 Emitted when the guest changes the RTC time.
281
282 Data:
283
284 - "offset": Offset between base RTC clock (as specified by -rtc base), and
285 new RTC clock value (json-number)
286
287 Example:
288
289 { "event": "RTC_CHANGE",
290     "data": { "offset": 78 },
291     "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
292
293 SPICE_CONNECTED, SPICE_DISCONNECTED
294 -----------------------------------
295
296 Emitted when a SPICE client connects or disconnects.
297
298 Data:
299
300 - "server": Server information (json-object)
301   - "host": IP address (json-string)
302   - "port": port number (json-string)
303   - "family": address family (json-string, "ipv4" or "ipv6")
304 - "client": Client information (json-object)
305   - "host": IP address (json-string)
306   - "port": port number (json-string)
307   - "family": address family (json-string, "ipv4" or "ipv6")
308
309 Example:
310
311 { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
312   "event": "SPICE_CONNECTED",
313   "data": {
314     "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
315     "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
316 }}
317
318 SPICE_INITIALIZED
319 -----------------
320
321 Emitted after initial handshake and authentication takes place (if any)
322 and the SPICE channel is up'n'running
323
324 Data:
325
326 - "server": Server information (json-object)
327   - "host": IP address (json-string)
328   - "port": port number (json-string)
329   - "family": address family (json-string, "ipv4" or "ipv6")
330   - "auth": authentication method (json-string, optional)
331 - "client": Client information (json-object)
332   - "host": IP address (json-string)
333   - "port": port number (json-string)
334   - "family": address family (json-string, "ipv4" or "ipv6")
335   - "connection-id": spice connection id.  All channels with the same id
336                      belong to the same spice session (json-int)
337   - "channel-type": channel type.  "1" is the main control channel, filter for
338                     this one if you want track spice sessions only (json-int)
339   - "channel-id": channel id.  Usually "0", might be different needed when
340                   multiple channels of the same type exist, such as multiple
341                   display channels in a multihead setup (json-int)
342   - "tls": whevener the channel is encrypted (json-bool)
343
344 Example:
345
346 { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
347   "event": "SPICE_INITIALIZED",
348   "data": {"server": {"auth": "spice", "port": "5921",
349                       "family": "ipv4", "host": "127.0.0.1"},
350            "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
351                       "connection-id": 1804289383, "host": "127.0.0.1",
352                       "channel-id": 0, "tls": true}
353 }}
354
355 SUSPEND_DISK
356 ------------
357
358 Emitted when the guest makes a request to enter S4 state.
359
360 Data: None.
361
362 Example:
363
364 { "event": "SUSPEND_DISK",
365      "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
366
367 Note: QEMU shuts down when entering S4 state.
368
369 VNC_CONNECTED
370 -------------
371
372 Emitted when a VNC client establishes a connection.
373
374 Data:
375
376 - "server": Server information (json-object)
377   - "host": IP address (json-string)
378   - "service": port number (json-string)
379   - "family": address family (json-string, "ipv4" or "ipv6")
380   - "auth": authentication method (json-string, optional)
381 - "client": Client information (json-object)
382   - "host": IP address (json-string)
383   - "service": port number (json-string)
384   - "family": address family (json-string, "ipv4" or "ipv6")
385
386 Example:
387
388 { "event": "VNC_CONNECTED",
389     "data": {
390         "server": { "auth": "sasl", "family": "ipv4",
391                     "service": "5901", "host": "0.0.0.0" },
392         "client": { "family": "ipv4", "service": "58425",
393                     "host": "127.0.0.1" } },
394     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
395
396
397 Note: This event is emitted before any authentication takes place, thus
398 the authentication ID is not provided.
399
400 VNC_DISCONNECTED
401 ----------------
402
403 Emitted when the connection is closed.
404
405 Data:
406
407 - "server": Server information (json-object)
408   - "host": IP address (json-string)
409   - "service": port number (json-string)
410   - "family": address family (json-string, "ipv4" or "ipv6")
411   - "auth": authentication method (json-string, optional)
412 - "client": Client information (json-object)
413   - "host": IP address (json-string)
414   - "service": port number (json-string)
415   - "family": address family (json-string, "ipv4" or "ipv6")
416   - "x509_dname": TLS dname (json-string, optional)
417   - "sasl_username": SASL username (json-string, optional)
418
419 Example:
420
421 { "event": "VNC_DISCONNECTED",
422     "data": {
423         "server": { "auth": "sasl", "family": "ipv4",
424                     "service": "5901", "host": "0.0.0.0" },
425         "client": { "family": "ipv4", "service": "58425",
426                     "host": "127.0.0.1", "sasl_username": "luiz" } },
427     "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
428
429 VNC_INITIALIZED
430 ---------------
431
432 Emitted after authentication takes place (if any) and the VNC session is
433 made active.
434
435 Data:
436
437 - "server": Server information (json-object)
438   - "host": IP address (json-string)
439   - "service": port number (json-string)
440   - "family": address family (json-string, "ipv4" or "ipv6")
441   - "auth": authentication method (json-string, optional)
442 - "client": Client information (json-object)
443   - "host": IP address (json-string)
444   - "service": port number (json-string)
445   - "family": address family (json-string, "ipv4" or "ipv6")
446   - "x509_dname": TLS dname (json-string, optional)
447   - "sasl_username": SASL username (json-string, optional)
448
449 Example:
450
451 { "event": "VNC_INITIALIZED",
452     "data": {
453         "server": { "auth": "sasl", "family": "ipv4",
454                     "service": "5901", "host": "0.0.0.0"},
455         "client": { "family": "ipv4", "service": "46089",
456                     "host": "127.0.0.1", "sasl_username": "luiz" } },
457         "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
458
459 WAKEUP
460 ------
461
462 Emitted when the guest has woken up from S3 and is running.
463
464 Data: None.
465
466 Example:
467
468 { "event": "WAKEUP",
469      "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
470
471 WATCHDOG
472 --------
473
474 Emitted when the watchdog device's timer is expired.
475
476 Data:
477
478 - "action": Action that has been taken, it's one of the following (json-string):
479             "reset", "shutdown", "poweroff", "pause", "debug", or "none"
480
481 Example:
482
483 { "event": "WATCHDOG",
484      "data": { "action": "reset" },
485      "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
486
487 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
488 followed respectively by the RESET, SHUTDOWN, or STOP events.