s390x/sclpconsole-lm: Fix hanging SCLP line mode console
[qemu.git] / qga / qapi-schema.json
1 # *-*- Mode: Python -*-*
2
3 ##
4 #
5 # General note concerning the use of guest agent interfaces:
6 #
7 # "unsupported" is a higher-level error than the errors that individual
8 # commands might document. The caller should always be prepared to receive
9 # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't
10 # document any failure mode at all.
11 #
12 ##
13
14 ##
15 #
16 # Echo back a unique integer value, and prepend to response a
17 # leading sentinel byte (0xFF) the client can check scan for.
18 #
19 # This is used by clients talking to the guest agent over the
20 # wire to ensure the stream is in sync and doesn't contain stale
21 # data from previous client. It must be issued upon initial
22 # connection, and after any client-side timeouts (including
23 # timeouts on receiving a response to this command).
24 #
25 # After issuing this request, all guest agent responses should be
26 # ignored until the response containing the unique integer value
27 # the client passed in is returned. Receival of the 0xFF sentinel
28 # byte must be handled as an indication that the client's
29 # lexer/tokenizer/parser state should be flushed/reset in
30 # preparation for reliably receiving the subsequent response. As
31 # an optimization, clients may opt to ignore all data until a
32 # sentinel value is receiving to avoid unnecessary processing of
33 # stale data.
34 #
35 # Similarly, clients should also precede this *request*
36 # with a 0xFF byte to make sure the guest agent flushes any
37 # partially read JSON data from a previous client connection.
38 #
39 # @id: randomly generated 64-bit integer
40 #
41 # Returns: The unique integer id passed in by the client
42 #
43 # Since: 1.1
44 # ##
45 { 'command': 'guest-sync-delimited',
46   'data':    { 'id': 'int' },
47   'returns': 'int' }
48
49 ##
50 # @guest-sync:
51 #
52 # Echo back a unique integer value
53 #
54 # This is used by clients talking to the guest agent over the
55 # wire to ensure the stream is in sync and doesn't contain stale
56 # data from previous client. All guest agent responses should be
57 # ignored until the provided unique integer value is returned,
58 # and it is up to the client to handle stale whole or
59 # partially-delivered JSON text in such a way that this response
60 # can be obtained.
61 #
62 # In cases where a partial stale response was previously
63 # received by the client, this cannot always be done reliably.
64 # One particular scenario being if qemu-ga responses are fed
65 # character-by-character into a JSON parser. In these situations,
66 # using guest-sync-delimited may be optimal.
67 #
68 # For clients that fetch responses line by line and convert them
69 # to JSON objects, guest-sync should be sufficient, but note that
70 # in cases where the channel is dirty some attempts at parsing the
71 # response may result in a parser error.
72 #
73 # Such clients should also precede this command
74 # with a 0xFF byte to make sure the guest agent flushes any
75 # partially read JSON data from a previous session.
76 #
77 # @id: randomly generated 64-bit integer
78 #
79 # Returns: The unique integer id passed in by the client
80 #
81 # Since: 0.15.0
82 ##
83 { 'command': 'guest-sync',
84   'data':    { 'id': 'int' },
85   'returns': 'int' }
86
87 ##
88 # @guest-ping:
89 #
90 # Ping the guest agent, a non-error return implies success
91 #
92 # Since: 0.15.0
93 ##
94 { 'command': 'guest-ping' }
95
96 ##
97 # @guest-get-time:
98 #
99 # Get the information about guest's System Time relative to
100 # the Epoch of 1970-01-01 in UTC.
101 #
102 # Returns: Time in nanoseconds.
103 #
104 # Since 1.5
105 ##
106 { 'command': 'guest-get-time',
107   'returns': 'int' }
108
109 ##
110 # @guest-set-time:
111 #
112 # Set guest time.
113 #
114 # When a guest is paused or migrated to a file then loaded
115 # from that file, the guest OS has no idea that there
116 # was a big gap in the time. Depending on how long the
117 # gap was, NTP might not be able to resynchronize the
118 # guest.
119 #
120 # This command tries to set guest's System Time to the
121 # given value, then sets the Hardware Clock (RTC) to the
122 # current System Time. This will make it easier for a guest
123 # to resynchronize without waiting for NTP. If no @time is
124 # specified, then the time to set is read from RTC.
125 #
126 # @time: #optional time of nanoseconds, relative to the Epoch
127 #        of 1970-01-01 in UTC.
128 #
129 # Returns: Nothing on success.
130 #
131 # Since: 1.5
132 ##
133 { 'command': 'guest-set-time',
134   'data': { '*time': 'int' } }
135
136 ##
137 # @GuestAgentCommandInfo:
138 #
139 # Information about guest agent commands.
140 #
141 # @name: name of the command
142 #
143 # @enabled: whether command is currently enabled by guest admin
144 #
145 # @success-response: whether command returns a response on success
146 #                    (since 1.7)
147 #
148 # Since 1.1.0
149 ##
150 { 'type': 'GuestAgentCommandInfo',
151   'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } }
152
153 ##
154 # @GuestAgentInfo
155 #
156 # Information about guest agent.
157 #
158 # @version: guest agent version
159 #
160 # @supported_commands: Information about guest agent commands
161 #
162 # Since 0.15.0
163 ##
164 { 'type': 'GuestAgentInfo',
165   'data': { 'version': 'str',
166             'supported_commands': ['GuestAgentCommandInfo'] } }
167 ##
168 # @guest-info:
169 #
170 # Get some information about the guest agent.
171 #
172 # Returns: @GuestAgentInfo
173 #
174 # Since: 0.15.0
175 ##
176 { 'command': 'guest-info',
177   'returns': 'GuestAgentInfo' }
178
179 ##
180 # @guest-shutdown:
181 #
182 # Initiate guest-activated shutdown. Note: this is an asynchronous
183 # shutdown request, with no guarantee of successful shutdown.
184 #
185 # @mode: #optional "halt", "powerdown" (default), or "reboot"
186 #
187 # This command does NOT return a response on success. Success condition
188 # is indicated by the VM exiting with a zero exit status or, when
189 # running with --no-shutdown, by issuing the query-status QMP command
190 # to confirm the VM status is "shutdown".
191 #
192 # Since: 0.15.0
193 ##
194 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
195   'success-response': 'no' }
196
197 ##
198 # @guest-file-open:
199 #
200 # Open a file in the guest and retrieve a file handle for it
201 #
202 # @filepath: Full path to the file in the guest to open.
203 #
204 # @mode: #optional open mode, as per fopen(), "r" is the default.
205 #
206 # Returns: Guest file handle on success.
207 #
208 # Since: 0.15.0
209 ##
210 { 'command': 'guest-file-open',
211   'data':    { 'path': 'str', '*mode': 'str' },
212   'returns': 'int' }
213
214 ##
215 # @guest-file-close:
216 #
217 # Close an open file in the guest
218 #
219 # @handle: filehandle returned by guest-file-open
220 #
221 # Returns: Nothing on success.
222 #
223 # Since: 0.15.0
224 ##
225 { 'command': 'guest-file-close',
226   'data': { 'handle': 'int' } }
227
228 ##
229 # @GuestFileRead
230 #
231 # Result of guest agent file-read operation
232 #
233 # @count: number of bytes read (note: count is *before*
234 #         base64-encoding is applied)
235 #
236 # @buf-b64: base64-encoded bytes read
237 #
238 # @eof: whether EOF was encountered during read operation.
239 #
240 # Since: 0.15.0
241 ##
242 { 'type': 'GuestFileRead',
243   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
244
245 ##
246 # @guest-file-read:
247 #
248 # Read from an open file in the guest. Data will be base64-encoded
249 #
250 # @handle: filehandle returned by guest-file-open
251 #
252 # @count: #optional maximum number of bytes to read (default is 4KB)
253 #
254 # Returns: @GuestFileRead on success.
255 #
256 # Since: 0.15.0
257 ##
258 { 'command': 'guest-file-read',
259   'data':    { 'handle': 'int', '*count': 'int' },
260   'returns': 'GuestFileRead' }
261
262 ##
263 # @GuestFileWrite
264 #
265 # Result of guest agent file-write operation
266 #
267 # @count: number of bytes written (note: count is actual bytes
268 #         written, after base64-decoding of provided buffer)
269 #
270 # @eof: whether EOF was encountered during write operation.
271 #
272 # Since: 0.15.0
273 ##
274 { 'type': 'GuestFileWrite',
275   'data': { 'count': 'int', 'eof': 'bool' } }
276
277 ##
278 # @guest-file-write:
279 #
280 # Write to an open file in the guest.
281 #
282 # @handle: filehandle returned by guest-file-open
283 #
284 # @buf-b64: base64-encoded string representing data to be written
285 #
286 # @count: #optional bytes to write (actual bytes, after base64-decode),
287 #         default is all content in buf-b64 buffer after base64 decoding
288 #
289 # Returns: @GuestFileWrite on success.
290 #
291 # Since: 0.15.0
292 ##
293 { 'command': 'guest-file-write',
294   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
295   'returns': 'GuestFileWrite' }
296
297
298 ##
299 # @GuestFileSeek
300 #
301 # Result of guest agent file-seek operation
302 #
303 # @position: current file position
304 #
305 # @eof: whether EOF was encountered during file seek
306 #
307 # Since: 0.15.0
308 ##
309 { 'type': 'GuestFileSeek',
310   'data': { 'position': 'int', 'eof': 'bool' } }
311
312 ##
313 # @guest-file-seek:
314 #
315 # Seek to a position in the file, as with fseek(), and return the
316 # current file position afterward. Also encapsulates ftell()'s
317 # functionality, just Set offset=0, whence=SEEK_CUR.
318 #
319 # @handle: filehandle returned by guest-file-open
320 #
321 # @offset: bytes to skip over in the file stream
322 #
323 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
324 #
325 # Returns: @GuestFileSeek on success.
326 #
327 # Since: 0.15.0
328 ##
329 { 'command': 'guest-file-seek',
330   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
331   'returns': 'GuestFileSeek' }
332
333 ##
334 # @guest-file-flush:
335 #
336 # Write file changes bufferred in userspace to disk/kernel buffers
337 #
338 # @handle: filehandle returned by guest-file-open
339 #
340 # Returns: Nothing on success.
341 #
342 # Since: 0.15.0
343 ##
344 { 'command': 'guest-file-flush',
345   'data': { 'handle': 'int' } }
346
347 ##
348 # @GuestFsFreezeStatus
349 #
350 # An enumeration of filesystem freeze states
351 #
352 # @thawed: filesystems thawed/unfrozen
353 #
354 # @frozen: all non-network guest filesystems frozen
355 #
356 # Since: 0.15.0
357 ##
358 { 'enum': 'GuestFsfreezeStatus',
359   'data': [ 'thawed', 'frozen' ] }
360
361 ##
362 # @guest-fsfreeze-status:
363 #
364 # Get guest fsfreeze state. error state indicates
365 #
366 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
367 #
368 # Note: This may fail to properly report the current state as a result of
369 # some other guest processes having issued an fs freeze/thaw.
370 #
371 # Since: 0.15.0
372 ##
373 { 'command': 'guest-fsfreeze-status',
374   'returns': 'GuestFsfreezeStatus' }
375
376 ##
377 # @guest-fsfreeze-freeze:
378 #
379 # Sync and freeze all freezable, local guest filesystems
380 #
381 # Returns: Number of file systems currently frozen. On error, all filesystems
382 # will be thawed.
383 #
384 # Since: 0.15.0
385 ##
386 { 'command': 'guest-fsfreeze-freeze',
387   'returns': 'int' }
388
389 ##
390 # @guest-fsfreeze-freeze-list:
391 #
392 # Sync and freeze specified guest filesystems
393 #
394 # @mountpoints: #optional an array of mountpoints of filesystems to be frozen.
395 #               If omitted, every mounted filesystem is frozen.
396 #
397 # Returns: Number of file systems currently frozen. On error, all filesystems
398 # will be thawed.
399 #
400 # Since: 2.2
401 ##
402 { 'command': 'guest-fsfreeze-freeze-list',
403   'data':    { '*mountpoints': ['str'] },
404   'returns': 'int' }
405
406 ##
407 # @guest-fsfreeze-thaw:
408 #
409 # Unfreeze all frozen guest filesystems
410 #
411 # Returns: Number of file systems thawed by this call
412 #
413 # Note: if return value does not match the previous call to
414 #       guest-fsfreeze-freeze, this likely means some freezable
415 #       filesystems were unfrozen before this call, and that the
416 #       filesystem state may have changed before issuing this
417 #       command.
418 #
419 # Since: 0.15.0
420 ##
421 { 'command': 'guest-fsfreeze-thaw',
422   'returns': 'int' }
423
424 ##
425 # @guest-fstrim:
426 #
427 # Discard (or "trim") blocks which are not in use by the filesystem.
428 #
429 # @minimum:
430 #       Minimum contiguous free range to discard, in bytes. Free ranges
431 #       smaller than this may be ignored (this is a hint and the guest
432 #       may not respect it).  By increasing this value, the fstrim
433 #       operation will complete more quickly for filesystems with badly
434 #       fragmented free space, although not all blocks will be discarded.
435 #       The default value is zero, meaning "discard every free block".
436 #
437 # Returns: Nothing.
438 #
439 # Since: 1.2
440 ##
441 { 'command': 'guest-fstrim',
442   'data': { '*minimum': 'int' } }
443
444 ##
445 # @guest-suspend-disk
446 #
447 # Suspend guest to disk.
448 #
449 # This command tries to execute the scripts provided by the pm-utils package.
450 # If it's not available, the suspend operation will be performed by manually
451 # writing to a sysfs file.
452 #
453 # For the best results it's strongly recommended to have the pm-utils
454 # package installed in the guest.
455 #
456 # This command does NOT return a response on success. There is a high chance
457 # the command succeeded if the VM exits with a zero exit status or, when
458 # running with --no-shutdown, by issuing the query-status QMP command to
459 # to confirm the VM status is "shutdown". However, the VM could also exit
460 # (or set its status to "shutdown") due to other reasons.
461 #
462 # The following errors may be returned:
463 #          If suspend to disk is not supported, Unsupported
464 #
465 # Notes: It's strongly recommended to issue the guest-sync command before
466 #        sending commands when the guest resumes
467 #
468 # Since: 1.1
469 ##
470 { 'command': 'guest-suspend-disk', 'success-response': 'no' }
471
472 ##
473 # @guest-suspend-ram
474 #
475 # Suspend guest to ram.
476 #
477 # This command tries to execute the scripts provided by the pm-utils package.
478 # If it's not available, the suspend operation will be performed by manually
479 # writing to a sysfs file.
480 #
481 # For the best results it's strongly recommended to have the pm-utils
482 # package installed in the guest.
483 #
484 # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
485 # command.  Thus, it's *required* to query QEMU for the presence of the
486 # 'system_wakeup' command before issuing guest-suspend-ram.
487 #
488 # This command does NOT return a response on success. There are two options
489 # to check for success:
490 #   1. Wait for the SUSPEND QMP event from QEMU
491 #   2. Issue the query-status QMP command to confirm the VM status is
492 #      "suspended"
493 #
494 # The following errors may be returned:
495 #          If suspend to ram is not supported, Unsupported
496 #
497 # Notes: It's strongly recommended to issue the guest-sync command before
498 #        sending commands when the guest resumes
499 #
500 # Since: 1.1
501 ##
502 { 'command': 'guest-suspend-ram', 'success-response': 'no' }
503
504 ##
505 # @guest-suspend-hybrid
506 #
507 # Save guest state to disk and suspend to ram.
508 #
509 # This command requires the pm-utils package to be installed in the guest.
510 #
511 # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
512 # command.  Thus, it's *required* to query QEMU for the presence of the
513 # 'system_wakeup' command before issuing guest-suspend-hybrid.
514 #
515 # This command does NOT return a response on success. There are two options
516 # to check for success:
517 #   1. Wait for the SUSPEND QMP event from QEMU
518 #   2. Issue the query-status QMP command to confirm the VM status is
519 #      "suspended"
520 #
521 # The following errors may be returned:
522 #          If hybrid suspend is not supported, Unsupported
523 #
524 # Notes: It's strongly recommended to issue the guest-sync command before
525 #        sending commands when the guest resumes
526 #
527 # Since: 1.1
528 ##
529 { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
530
531 ##
532 # @GuestIpAddressType:
533 #
534 # An enumeration of supported IP address types
535 #
536 # @ipv4: IP version 4
537 #
538 # @ipv6: IP version 6
539 #
540 # Since: 1.1
541 ##
542 { 'enum': 'GuestIpAddressType',
543   'data': [ 'ipv4', 'ipv6' ] }
544
545 ##
546 # @GuestIpAddress:
547 #
548 # @ip-address: IP address
549 #
550 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
551 #
552 # @prefix: Network prefix length of @ip-address
553 #
554 # Since: 1.1
555 ##
556 { 'type': 'GuestIpAddress',
557   'data': {'ip-address': 'str',
558            'ip-address-type': 'GuestIpAddressType',
559            'prefix': 'int'} }
560
561 ##
562 # @GuestNetworkInterface:
563 #
564 # @name: The name of interface for which info are being delivered
565 #
566 # @hardware-address: Hardware address of @name
567 #
568 # @ip-addresses: List of addresses assigned to @name
569 #
570 # Since: 1.1
571 ##
572 { 'type': 'GuestNetworkInterface',
573   'data': {'name': 'str',
574            '*hardware-address': 'str',
575            '*ip-addresses': ['GuestIpAddress'] } }
576
577 ##
578 # @guest-network-get-interfaces:
579 #
580 # Get list of guest IP addresses, MAC addresses
581 # and netmasks.
582 #
583 # Returns: List of GuestNetworkInfo on success.
584 #
585 # Since: 1.1
586 ##
587 { 'command': 'guest-network-get-interfaces',
588   'returns': ['GuestNetworkInterface'] }
589
590 ##
591 # @GuestLogicalProcessor:
592 #
593 # @logical-id: Arbitrary guest-specific unique identifier of the VCPU.
594 #
595 # @online: Whether the VCPU is enabled.
596 #
597 # @can-offline: #optional Whether offlining the VCPU is possible. This member
598 #               is always filled in by the guest agent when the structure is
599 #               returned, and always ignored on input (hence it can be omitted
600 #               then).
601 #
602 # Since: 1.5
603 ##
604 { 'type': 'GuestLogicalProcessor',
605   'data': {'logical-id': 'int',
606            'online': 'bool',
607            '*can-offline': 'bool'} }
608
609 ##
610 # @guest-get-vcpus:
611 #
612 # Retrieve the list of the guest's logical processors.
613 #
614 # This is a read-only operation.
615 #
616 # Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
617 # list exactly once, but their order is unspecified.
618 #
619 # Since: 1.5
620 ##
621 { 'command': 'guest-get-vcpus',
622   'returns': ['GuestLogicalProcessor'] }
623
624 ##
625 # @guest-set-vcpus:
626 #
627 # Attempt to reconfigure (currently: enable/disable) logical processors inside
628 # the guest.
629 #
630 # The input list is processed node by node in order. In each node @logical-id
631 # is used to look up the guest VCPU, for which @online specifies the requested
632 # state. The set of distinct @logical-id's is only required to be a subset of
633 # the guest-supported identifiers. There's no restriction on list length or on
634 # repeating the same @logical-id (with possibly different @online field).
635 # Preferably the input list should describe a modified subset of
636 # @guest-get-vcpus' return value.
637 #
638 # Returns: The length of the initial sublist that has been successfully
639 #          processed. The guest agent maximizes this value. Possible cases:
640 #
641 #          0:                if the @vcpus list was empty on input. Guest state
642 #                            has not been changed. Otherwise,
643 #
644 #          Error:            processing the first node of @vcpus failed for the
645 #                            reason returned. Guest state has not been changed.
646 #                            Otherwise,
647 #
648 #          < length(@vcpus): more than zero initial nodes have been processed,
649 #                            but not the entire @vcpus list. Guest state has
650 #                            changed accordingly. To retrieve the error
651 #                            (assuming it persists), repeat the call with the
652 #                            successfully processed initial sublist removed.
653 #                            Otherwise,
654 #
655 #          length(@vcpus):   call successful.
656 #
657 # Since: 1.5
658 ##
659 { 'command': 'guest-set-vcpus',
660   'data':    {'vcpus': ['GuestLogicalProcessor'] },
661   'returns': 'int' }
662
663 ##
664 # @GuestDiskBusType
665 #
666 # An enumeration of bus type of disks
667 #
668 # @ide: IDE disks
669 # @fdc: floppy disks
670 # @scsi: SCSI disks
671 # @virtio: virtio disks
672 # @xen: Xen disks
673 # @usb: USB disks
674 # @uml: UML disks
675 # @sata: SATA disks
676 # @sd: SD cards
677 #
678 # Since: 2.2
679 ##
680 { 'enum': 'GuestDiskBusType',
681   'data': [ 'ide', 'fdc', 'scsi', 'virtio', 'xen', 'usb', 'uml', 'sata',
682             'sd' ] }
683
684 ##
685 # @GuestPCIAddress:
686 #
687 # @domain: domain id
688 # @bus: bus id
689 # @slot: slot id
690 # @function: function id
691 #
692 # Since: 2.2
693 ##
694 { 'type': 'GuestPCIAddress',
695   'data': {'domain': 'int', 'bus': 'int',
696            'slot': 'int', 'function': 'int'} }
697
698 ##
699 # @GuestDiskAddress:
700 #
701 # @pci-controller: controller's PCI address
702 # @type: bus type
703 # @bus: bus id
704 # @target: target id
705 # @unit: unit id
706 #
707 # Since: 2.2
708 ##
709 { 'type': 'GuestDiskAddress',
710   'data': {'pci-controller': 'GuestPCIAddress',
711            'bus-type': 'GuestDiskBusType',
712            'bus': 'int', 'target': 'int', 'unit': 'int'} }
713
714 ##
715 # @GuestFilesystemInfo
716 #
717 # @name: disk name
718 # @mountpoint: mount point path
719 # @type: file system type string
720 # @disk: an array of disk hardware information that the volume lies on,
721 #        which may be empty if the disk type is not supported
722 #
723 # Since: 2.2
724 ##
725 { 'type': 'GuestFilesystemInfo',
726   'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
727            'disk': ['GuestDiskAddress']} }
728
729 ##
730 # @guest-get-fsinfo:
731 #
732 # Returns: The list of filesystems information mounted in the guest.
733 #          The returned mountpoints may be specified to
734 #          @guest-fsfreeze-freeze-list.
735 #          Network filesystems (such as CIFS and NFS) are not listed.
736 #
737 # Since: 2.2
738 ##
739 { 'command': 'guest-get-fsinfo',
740   'returns': ['GuestFilesystemInfo'] }