Merge remote-tracking branch 'remotes/vivier2/tags/trivial-branch-for-5.2-pull-reques...
[qemu.git] / qga / qapi-schema.json
1 # *-*- Mode: Python -*-*
2 # vim: filetype=python
3
4 ##
5 #
6 # General note concerning the use of guest agent interfaces:
7 #
8 # "unsupported" is a higher-level error than the errors that individual
9 # commands might document. The caller should always be prepared to receive
10 # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn't
11 # document any failure mode at all.
12 #
13 ##
14
15 { 'pragma': { 'doc-required': true } }
16
17 # Whitelists to permit QAPI rule violations; think twice before you
18 # add to them!
19 { 'pragma': {
20     # Commands allowed to return a non-dictionary:
21     'returns-whitelist': [
22         'guest-file-open',
23         'guest-fsfreeze-freeze',
24         'guest-fsfreeze-freeze-list',
25         'guest-fsfreeze-status',
26         'guest-fsfreeze-thaw',
27         'guest-get-time',
28         'guest-set-vcpus',
29         'guest-sync',
30         'guest-sync-delimited' ] } }
31
32 ##
33 # @guest-sync-delimited:
34 #
35 # Echo back a unique integer value, and prepend to response a
36 # leading sentinel byte (0xFF) the client can check scan for.
37 #
38 # This is used by clients talking to the guest agent over the
39 # wire to ensure the stream is in sync and doesn't contain stale
40 # data from previous client. It must be issued upon initial
41 # connection, and after any client-side timeouts (including
42 # timeouts on receiving a response to this command).
43 #
44 # After issuing this request, all guest agent responses should be
45 # ignored until the response containing the unique integer value
46 # the client passed in is returned. Receival of the 0xFF sentinel
47 # byte must be handled as an indication that the client's
48 # lexer/tokenizer/parser state should be flushed/reset in
49 # preparation for reliably receiving the subsequent response. As
50 # an optimization, clients may opt to ignore all data until a
51 # sentinel value is receiving to avoid unnecessary processing of
52 # stale data.
53 #
54 # Similarly, clients should also precede this *request*
55 # with a 0xFF byte to make sure the guest agent flushes any
56 # partially read JSON data from a previous client connection.
57 #
58 # @id: randomly generated 64-bit integer
59 #
60 # Returns: The unique integer id passed in by the client
61 #
62 # Since: 1.1
63 ##
64 { 'command': 'guest-sync-delimited',
65   'data':    { 'id': 'int' },
66   'returns': 'int' }
67
68 ##
69 # @guest-sync:
70 #
71 # Echo back a unique integer value
72 #
73 # This is used by clients talking to the guest agent over the
74 # wire to ensure the stream is in sync and doesn't contain stale
75 # data from previous client. All guest agent responses should be
76 # ignored until the provided unique integer value is returned,
77 # and it is up to the client to handle stale whole or
78 # partially-delivered JSON text in such a way that this response
79 # can be obtained.
80 #
81 # In cases where a partial stale response was previously
82 # received by the client, this cannot always be done reliably.
83 # One particular scenario being if qemu-ga responses are fed
84 # character-by-character into a JSON parser. In these situations,
85 # using guest-sync-delimited may be optimal.
86 #
87 # For clients that fetch responses line by line and convert them
88 # to JSON objects, guest-sync should be sufficient, but note that
89 # in cases where the channel is dirty some attempts at parsing the
90 # response may result in a parser error.
91 #
92 # Such clients should also precede this command
93 # with a 0xFF byte to make sure the guest agent flushes any
94 # partially read JSON data from a previous session.
95 #
96 # @id: randomly generated 64-bit integer
97 #
98 # Returns: The unique integer id passed in by the client
99 #
100 # Since: 0.15.0
101 ##
102 { 'command': 'guest-sync',
103   'data':    { 'id': 'int' },
104   'returns': 'int' }
105
106 ##
107 # @guest-ping:
108 #
109 # Ping the guest agent, a non-error return implies success
110 #
111 # Since: 0.15.0
112 ##
113 { 'command': 'guest-ping' }
114
115 ##
116 # @guest-get-time:
117 #
118 # Get the information about guest's System Time relative to
119 # the Epoch of 1970-01-01 in UTC.
120 #
121 # Returns: Time in nanoseconds.
122 #
123 # Since: 1.5
124 ##
125 { 'command': 'guest-get-time',
126   'returns': 'int' }
127
128 ##
129 # @guest-set-time:
130 #
131 # Set guest time.
132 #
133 # When a guest is paused or migrated to a file then loaded
134 # from that file, the guest OS has no idea that there
135 # was a big gap in the time. Depending on how long the
136 # gap was, NTP might not be able to resynchronize the
137 # guest.
138 #
139 # This command tries to set guest's System Time to the
140 # given value, then sets the Hardware Clock (RTC) to the
141 # current System Time. This will make it easier for a guest
142 # to resynchronize without waiting for NTP. If no @time is
143 # specified, then the time to set is read from RTC. However,
144 # this may not be supported on all platforms (i.e. Windows).
145 # If that's the case users are advised to always pass a
146 # value.
147 #
148 # @time: time of nanoseconds, relative to the Epoch
149 #        of 1970-01-01 in UTC.
150 #
151 # Returns: Nothing on success.
152 #
153 # Since: 1.5
154 ##
155 { 'command': 'guest-set-time',
156   'data': { '*time': 'int' } }
157
158 ##
159 # @GuestAgentCommandInfo:
160 #
161 # Information about guest agent commands.
162 #
163 # @name: name of the command
164 #
165 # @enabled: whether command is currently enabled by guest admin
166 #
167 # @success-response: whether command returns a response on success
168 #                    (since 1.7)
169 #
170 # Since: 1.1.0
171 ##
172 { 'struct': 'GuestAgentCommandInfo',
173   'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } }
174
175 ##
176 # @GuestAgentInfo:
177 #
178 # Information about guest agent.
179 #
180 # @version: guest agent version
181 #
182 # @supported_commands: Information about guest agent commands
183 #
184 # Since: 0.15.0
185 ##
186 { 'struct': 'GuestAgentInfo',
187   'data': { 'version': 'str',
188             'supported_commands': ['GuestAgentCommandInfo'] } }
189 ##
190 # @guest-info:
191 #
192 # Get some information about the guest agent.
193 #
194 # Returns: @GuestAgentInfo
195 #
196 # Since: 0.15.0
197 ##
198 { 'command': 'guest-info',
199   'returns': 'GuestAgentInfo' }
200
201 ##
202 # @guest-shutdown:
203 #
204 # Initiate guest-activated shutdown. Note: this is an asynchronous
205 # shutdown request, with no guarantee of successful shutdown.
206 #
207 # @mode: "halt", "powerdown" (default), or "reboot"
208 #
209 # This command does NOT return a response on success. Success condition
210 # is indicated by the VM exiting with a zero exit status or, when
211 # running with --no-shutdown, by issuing the query-status QMP command
212 # to confirm the VM status is "shutdown".
213 #
214 # Since: 0.15.0
215 ##
216 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
217   'success-response': false }
218
219 ##
220 # @guest-file-open:
221 #
222 # Open a file in the guest and retrieve a file handle for it
223 #
224 # @path: Full path to the file in the guest to open.
225 #
226 # @mode: open mode, as per fopen(), "r" is the default.
227 #
228 # Returns: Guest file handle on success.
229 #
230 # Since: 0.15.0
231 ##
232 { 'command': 'guest-file-open',
233   'data':    { 'path': 'str', '*mode': 'str' },
234   'returns': 'int' }
235
236 ##
237 # @guest-file-close:
238 #
239 # Close an open file in the guest
240 #
241 # @handle: filehandle returned by guest-file-open
242 #
243 # Returns: Nothing on success.
244 #
245 # Since: 0.15.0
246 ##
247 { 'command': 'guest-file-close',
248   'data': { 'handle': 'int' } }
249
250 ##
251 # @GuestFileRead:
252 #
253 # Result of guest agent file-read operation
254 #
255 # @count: number of bytes read (note: count is *before*
256 #         base64-encoding is applied)
257 #
258 # @buf-b64: base64-encoded bytes read
259 #
260 # @eof: whether EOF was encountered during read operation.
261 #
262 # Since: 0.15.0
263 ##
264 { 'struct': 'GuestFileRead',
265   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
266
267 ##
268 # @guest-file-read:
269 #
270 # Read from an open file in the guest. Data will be base64-encoded.
271 # As this command is just for limited, ad-hoc debugging, such as log
272 # file access, the number of bytes to read is limited to 48 MB.
273 #
274 # @handle: filehandle returned by guest-file-open
275 #
276 # @count: maximum number of bytes to read (default is 4KB, maximum is 48MB)
277 #
278 # Returns: @GuestFileRead on success.
279 #
280 # Since: 0.15.0
281 ##
282 { 'command': 'guest-file-read',
283   'data':    { 'handle': 'int', '*count': 'int' },
284   'returns': 'GuestFileRead' }
285
286 ##
287 # @GuestFileWrite:
288 #
289 # Result of guest agent file-write operation
290 #
291 # @count: number of bytes written (note: count is actual bytes
292 #         written, after base64-decoding of provided buffer)
293 #
294 # @eof: whether EOF was encountered during write operation.
295 #
296 # Since: 0.15.0
297 ##
298 { 'struct': 'GuestFileWrite',
299   'data': { 'count': 'int', 'eof': 'bool' } }
300
301 ##
302 # @guest-file-write:
303 #
304 # Write to an open file in the guest.
305 #
306 # @handle: filehandle returned by guest-file-open
307 #
308 # @buf-b64: base64-encoded string representing data to be written
309 #
310 # @count: bytes to write (actual bytes, after base64-decode),
311 #         default is all content in buf-b64 buffer after base64 decoding
312 #
313 # Returns: @GuestFileWrite on success.
314 #
315 # Since: 0.15.0
316 ##
317 { 'command': 'guest-file-write',
318   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
319   'returns': 'GuestFileWrite' }
320
321
322 ##
323 # @GuestFileSeek:
324 #
325 # Result of guest agent file-seek operation
326 #
327 # @position: current file position
328 #
329 # @eof: whether EOF was encountered during file seek
330 #
331 # Since: 0.15.0
332 ##
333 { 'struct': 'GuestFileSeek',
334   'data': { 'position': 'int', 'eof': 'bool' } }
335
336 ##
337 # @QGASeek:
338 #
339 # Symbolic names for use in @guest-file-seek
340 #
341 # @set: Set to the specified offset (same effect as 'whence':0)
342 # @cur: Add offset to the current location (same effect as 'whence':1)
343 # @end: Add offset to the end of the file (same effect as 'whence':2)
344 #
345 # Since: 2.6
346 ##
347 { 'enum': 'QGASeek', 'data': [ 'set', 'cur', 'end' ] }
348
349 ##
350 # @GuestFileWhence:
351 #
352 # Controls the meaning of offset to @guest-file-seek.
353 #
354 # @value: Integral value (0 for set, 1 for cur, 2 for end), available
355 #         for historical reasons, and might differ from the host's or
356 #         guest's SEEK_* values (since: 0.15)
357 # @name: Symbolic name, and preferred interface
358 #
359 # Since: 2.6
360 ##
361 { 'alternate': 'GuestFileWhence',
362   'data': { 'value': 'int', 'name': 'QGASeek' } }
363
364 ##
365 # @guest-file-seek:
366 #
367 # Seek to a position in the file, as with fseek(), and return the
368 # current file position afterward. Also encapsulates ftell()'s
369 # functionality, with offset=0 and whence=1.
370 #
371 # @handle: filehandle returned by guest-file-open
372 #
373 # @offset: bytes to skip over in the file stream
374 #
375 # @whence: Symbolic or numeric code for interpreting offset
376 #
377 # Returns: @GuestFileSeek on success.
378 #
379 # Since: 0.15.0
380 ##
381 { 'command': 'guest-file-seek',
382   'data':    { 'handle': 'int', 'offset': 'int',
383                'whence': 'GuestFileWhence' },
384   'returns': 'GuestFileSeek' }
385
386 ##
387 # @guest-file-flush:
388 #
389 # Write file changes bufferred in userspace to disk/kernel buffers
390 #
391 # @handle: filehandle returned by guest-file-open
392 #
393 # Returns: Nothing on success.
394 #
395 # Since: 0.15.0
396 ##
397 { 'command': 'guest-file-flush',
398   'data': { 'handle': 'int' } }
399
400 ##
401 # @GuestFsfreezeStatus:
402 #
403 # An enumeration of filesystem freeze states
404 #
405 # @thawed: filesystems thawed/unfrozen
406 #
407 # @frozen: all non-network guest filesystems frozen
408 #
409 # Since: 0.15.0
410 ##
411 { 'enum': 'GuestFsfreezeStatus',
412   'data': [ 'thawed', 'frozen' ] }
413
414 ##
415 # @guest-fsfreeze-status:
416 #
417 # Get guest fsfreeze state. error state indicates
418 #
419 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
420 #
421 # Note: This may fail to properly report the current state as a result of
422 #       some other guest processes having issued an fs freeze/thaw.
423 #
424 # Since: 0.15.0
425 ##
426 { 'command': 'guest-fsfreeze-status',
427   'returns': 'GuestFsfreezeStatus' }
428
429 ##
430 # @guest-fsfreeze-freeze:
431 #
432 # Sync and freeze all freezable, local guest filesystems. If this
433 # command succeeded, you may call @guest-fsfreeze-thaw later to
434 # unfreeze.
435 #
436 # Note: On Windows, the command is implemented with the help of a
437 #       Volume Shadow-copy Service DLL helper. The frozen state is limited
438 #       for up to 10 seconds by VSS.
439 #
440 # Returns: Number of file systems currently frozen. On error, all filesystems
441 #          will be thawed. If no filesystems are frozen as a result of this call,
442 #          then @guest-fsfreeze-status will remain "thawed" and calling
443 #          @guest-fsfreeze-thaw is not necessary.
444 #
445 # Since: 0.15.0
446 ##
447 { 'command': 'guest-fsfreeze-freeze',
448   'returns': 'int' }
449
450 ##
451 # @guest-fsfreeze-freeze-list:
452 #
453 # Sync and freeze specified guest filesystems.
454 # See also @guest-fsfreeze-freeze.
455 #
456 # @mountpoints: an array of mountpoints of filesystems to be frozen.
457 #               If omitted, every mounted filesystem is frozen.
458 #               Invalid mount points are ignored.
459 #
460 # Returns: Number of file systems currently frozen. On error, all filesystems
461 #          will be thawed.
462 #
463 # Since: 2.2
464 ##
465 { 'command': 'guest-fsfreeze-freeze-list',
466   'data':    { '*mountpoints': ['str'] },
467   'returns': 'int' }
468
469 ##
470 # @guest-fsfreeze-thaw:
471 #
472 # Unfreeze all frozen guest filesystems
473 #
474 # Returns: Number of file systems thawed by this call
475 #
476 # Note: if return value does not match the previous call to
477 #       guest-fsfreeze-freeze, this likely means some freezable
478 #       filesystems were unfrozen before this call, and that the
479 #       filesystem state may have changed before issuing this
480 #       command.
481 #
482 # Since: 0.15.0
483 ##
484 { 'command': 'guest-fsfreeze-thaw',
485   'returns': 'int' }
486
487 ##
488 # @GuestFilesystemTrimResult:
489 #
490 # @path: path that was trimmed
491 # @error: an error message when trim failed
492 # @trimmed: bytes trimmed for this path
493 # @minimum: reported effective minimum for this path
494 #
495 # Since: 2.4
496 ##
497 { 'struct': 'GuestFilesystemTrimResult',
498   'data': {'path': 'str',
499            '*trimmed': 'int', '*minimum': 'int', '*error': 'str'} }
500
501 ##
502 # @GuestFilesystemTrimResponse:
503 #
504 # @paths: list of @GuestFilesystemTrimResult per path that was trimmed
505 #
506 # Since: 2.4
507 ##
508 { 'struct': 'GuestFilesystemTrimResponse',
509   'data': {'paths': ['GuestFilesystemTrimResult']} }
510
511 ##
512 # @guest-fstrim:
513 #
514 # Discard (or "trim") blocks which are not in use by the filesystem.
515 #
516 # @minimum: Minimum contiguous free range to discard, in bytes. Free ranges
517 #           smaller than this may be ignored (this is a hint and the guest
518 #           may not respect it).  By increasing this value, the fstrim
519 #           operation will complete more quickly for filesystems with badly
520 #           fragmented free space, although not all blocks will be discarded.
521 #           The default value is zero, meaning "discard every free block".
522 #
523 # Returns: A @GuestFilesystemTrimResponse which contains the
524 #          status of all trimmed paths. (since 2.4)
525 #
526 # Since: 1.2
527 ##
528 { 'command': 'guest-fstrim',
529   'data': { '*minimum': 'int' },
530   'returns': 'GuestFilesystemTrimResponse' }
531
532 ##
533 # @guest-suspend-disk:
534 #
535 # Suspend guest to disk.
536 #
537 # This command attempts to suspend the guest using three strategies, in this
538 # order:
539 #
540 # - systemd hibernate
541 # - pm-utils (via pm-hibernate)
542 # - manual write into sysfs
543 #
544 # This command does NOT return a response on success. There is a high chance
545 # the command succeeded if the VM exits with a zero exit status or, when
546 # running with --no-shutdown, by issuing the query-status QMP command to
547 # to confirm the VM status is "shutdown". However, the VM could also exit
548 # (or set its status to "shutdown") due to other reasons.
549 #
550 # The following errors may be returned:
551 #
552 # - If suspend to disk is not supported, Unsupported
553 #
554 # Notes: It's strongly recommended to issue the guest-sync command before
555 #        sending commands when the guest resumes
556 #
557 # Since: 1.1
558 ##
559 { 'command': 'guest-suspend-disk', 'success-response': false }
560
561 ##
562 # @guest-suspend-ram:
563 #
564 # Suspend guest to ram.
565 #
566 # This command attempts to suspend the guest using three strategies, in this
567 # order:
568 #
569 # - systemd suspend
570 # - pm-utils (via pm-suspend)
571 # - manual write into sysfs
572 #
573 # IMPORTANT: guest-suspend-ram requires working wakeup support in
574 # QEMU. You should check QMP command query-current-machine returns
575 # wakeup-suspend-support: true before issuing this command. Failure in
576 # doing so can result in a suspended guest that QEMU will not be able to
577 # awaken, forcing the user to power cycle the guest to bring it back.
578 #
579 # This command does NOT return a response on success. There are two options
580 # to check for success:
581 #
582 # 1. Wait for the SUSPEND QMP event from QEMU
583 # 2. Issue the query-status QMP command to confirm the VM status is
584 #    "suspended"
585 #
586 # The following errors may be returned:
587 #
588 # - If suspend to ram is not supported, Unsupported
589 #
590 # Notes: It's strongly recommended to issue the guest-sync command before
591 #        sending commands when the guest resumes
592 #
593 # Since: 1.1
594 ##
595 { 'command': 'guest-suspend-ram', 'success-response': false }
596
597 ##
598 # @guest-suspend-hybrid:
599 #
600 # Save guest state to disk and suspend to ram.
601 #
602 # This command attempts to suspend the guest by executing, in this order:
603 #
604 # - systemd hybrid-sleep
605 # - pm-utils (via pm-suspend-hybrid)
606 #
607 # IMPORTANT: guest-suspend-hybrid requires working wakeup support in
608 # QEMU. You should check QMP command query-current-machine returns
609 # wakeup-suspend-support: true before issuing this command. Failure in
610 # doing so can result in a suspended guest that QEMU will not be able to
611 # awaken, forcing the user to power cycle the guest to bring it back.
612 #
613 # This command does NOT return a response on success. There are two options
614 # to check for success:
615 #
616 # 1. Wait for the SUSPEND QMP event from QEMU
617 # 2. Issue the query-status QMP command to confirm the VM status is
618 #    "suspended"
619 #
620 # The following errors may be returned:
621 #
622 # - If hybrid suspend is not supported, Unsupported
623 #
624 # Notes: It's strongly recommended to issue the guest-sync command before
625 #        sending commands when the guest resumes
626 #
627 # Since: 1.1
628 ##
629 { 'command': 'guest-suspend-hybrid', 'success-response': false }
630
631 ##
632 # @GuestIpAddressType:
633 #
634 # An enumeration of supported IP address types
635 #
636 # @ipv4: IP version 4
637 #
638 # @ipv6: IP version 6
639 #
640 # Since: 1.1
641 ##
642 { 'enum': 'GuestIpAddressType',
643   'data': [ 'ipv4', 'ipv6' ] }
644
645 ##
646 # @GuestIpAddress:
647 #
648 # @ip-address: IP address
649 #
650 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
651 #
652 # @prefix: Network prefix length of @ip-address
653 #
654 # Since: 1.1
655 ##
656 { 'struct': 'GuestIpAddress',
657   'data': {'ip-address': 'str',
658            'ip-address-type': 'GuestIpAddressType',
659            'prefix': 'int'} }
660
661 ##
662 # @GuestNetworkInterfaceStat:
663 #
664 # @rx-bytes: total bytes received
665 #
666 # @rx-packets: total packets received
667 #
668 # @rx-errs: bad packets received
669 #
670 # @rx-dropped: receiver dropped packets
671 #
672 # @tx-bytes: total bytes transmitted
673 #
674 # @tx-packets: total packets transmitted
675 #
676 # @tx-errs: packet transmit problems
677 #
678 # @tx-dropped: dropped packets transmitted
679 #
680 # Since: 2.11
681 ##
682 { 'struct': 'GuestNetworkInterfaceStat',
683   'data': {'rx-bytes': 'uint64',
684             'rx-packets': 'uint64',
685             'rx-errs': 'uint64',
686             'rx-dropped': 'uint64',
687             'tx-bytes': 'uint64',
688             'tx-packets': 'uint64',
689             'tx-errs': 'uint64',
690             'tx-dropped': 'uint64'
691            } }
692
693 ##
694 # @GuestNetworkInterface:
695 #
696 # @name: The name of interface for which info are being delivered
697 #
698 # @hardware-address: Hardware address of @name
699 #
700 # @ip-addresses: List of addresses assigned to @name
701 #
702 # @statistics: various statistic counters related to @name
703 #              (since 2.11)
704 #
705 # Since: 1.1
706 ##
707 { 'struct': 'GuestNetworkInterface',
708   'data': {'name': 'str',
709            '*hardware-address': 'str',
710            '*ip-addresses': ['GuestIpAddress'],
711            '*statistics': 'GuestNetworkInterfaceStat' } }
712
713 ##
714 # @guest-network-get-interfaces:
715 #
716 # Get list of guest IP addresses, MAC addresses
717 # and netmasks.
718 #
719 # Returns: List of GuestNetworkInfo on success.
720 #
721 # Since: 1.1
722 ##
723 { 'command': 'guest-network-get-interfaces',
724   'returns': ['GuestNetworkInterface'] }
725
726 ##
727 # @GuestLogicalProcessor:
728 #
729 # @logical-id: Arbitrary guest-specific unique identifier of the VCPU.
730 #
731 # @online: Whether the VCPU is enabled.
732 #
733 # @can-offline: Whether offlining the VCPU is possible. This member
734 #               is always filled in by the guest agent when the structure is
735 #               returned, and always ignored on input (hence it can be omitted
736 #               then).
737 #
738 # Since: 1.5
739 ##
740 { 'struct': 'GuestLogicalProcessor',
741   'data': {'logical-id': 'int',
742            'online': 'bool',
743            '*can-offline': 'bool'} }
744
745 ##
746 # @guest-get-vcpus:
747 #
748 # Retrieve the list of the guest's logical processors.
749 #
750 # This is a read-only operation.
751 #
752 # Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
753 #          list exactly once, but their order is unspecified.
754 #
755 # Since: 1.5
756 ##
757 { 'command': 'guest-get-vcpus',
758   'returns': ['GuestLogicalProcessor'] }
759
760 ##
761 # @guest-set-vcpus:
762 #
763 # Attempt to reconfigure (currently: enable/disable) logical processors inside
764 # the guest.
765 #
766 # The input list is processed node by node in order. In each node @logical-id
767 # is used to look up the guest VCPU, for which @online specifies the requested
768 # state. The set of distinct @logical-id's is only required to be a subset of
769 # the guest-supported identifiers. There's no restriction on list length or on
770 # repeating the same @logical-id (with possibly different @online field).
771 # Preferably the input list should describe a modified subset of
772 # @guest-get-vcpus' return value.
773 #
774 # Returns: The length of the initial sublist that has been successfully
775 #          processed. The guest agent maximizes this value. Possible cases:
776 #
777 #          - 0:
778 #            if the @vcpus list was empty on input. Guest state
779 #            has not been changed. Otherwise,
780 #          - Error:
781 #            processing the first node of @vcpus failed for the
782 #            reason returned. Guest state has not been changed.
783 #            Otherwise,
784 #          - < length(@vcpus):
785 #            more than zero initial nodes have been processed,
786 #            but not the entire @vcpus list. Guest state has
787 #            changed accordingly. To retrieve the error
788 #            (assuming it persists), repeat the call with the
789 #            successfully processed initial sublist removed.
790 #            Otherwise,
791 #          - length(@vcpus):
792 #            call successful.
793 #
794 # Since: 1.5
795 ##
796 { 'command': 'guest-set-vcpus',
797   'data':    {'vcpus': ['GuestLogicalProcessor'] },
798   'returns': 'int' }
799
800 ##
801 # @GuestDiskBusType:
802 #
803 # An enumeration of bus type of disks
804 #
805 # @ide: IDE disks
806 # @fdc: floppy disks
807 # @scsi: SCSI disks
808 # @virtio: virtio disks
809 # @xen: Xen disks
810 # @usb: USB disks
811 # @uml: UML disks
812 # @sata: SATA disks
813 # @sd: SD cards
814 # @unknown: Unknown bus type
815 # @ieee1394: Win IEEE 1394 bus type
816 # @ssa: Win SSA bus type
817 # @fibre: Win fiber channel bus type
818 # @raid: Win RAID bus type
819 # @iscsi: Win iScsi bus type
820 # @sas: Win serial-attaches SCSI bus type
821 # @mmc: Win multimedia card (MMC) bus type
822 # @virtual: Win virtual bus type
823 # @file-backed-virtual: Win file-backed bus type
824 #
825 # Since: 2.2; 'Unknown' and all entries below since 2.4
826 ##
827 { 'enum': 'GuestDiskBusType',
828   'data': [ 'ide', 'fdc', 'scsi', 'virtio', 'xen', 'usb', 'uml', 'sata',
829             'sd', 'unknown', 'ieee1394', 'ssa', 'fibre', 'raid', 'iscsi',
830             'sas', 'mmc', 'virtual', 'file-backed-virtual' ] }
831
832
833 ##
834 # @GuestPCIAddress:
835 #
836 # @domain: domain id
837 # @bus: bus id
838 # @slot: slot id
839 # @function: function id
840 #
841 # Since: 2.2
842 ##
843 { 'struct': 'GuestPCIAddress',
844   'data': {'domain': 'int', 'bus': 'int',
845            'slot': 'int', 'function': 'int'} }
846
847 ##
848 # @GuestDiskAddress:
849 #
850 # @pci-controller: controller's PCI address (fields are set to -1 if invalid)
851 # @bus-type: bus type
852 # @bus: bus id
853 # @target: target id
854 # @unit: unit id
855 # @serial: serial number (since: 3.1)
856 # @dev: device node (POSIX) or device UNC (Windows) (since: 3.1)
857 #
858 # Since: 2.2
859 ##
860 { 'struct': 'GuestDiskAddress',
861   'data': {'pci-controller': 'GuestPCIAddress',
862            'bus-type': 'GuestDiskBusType',
863            'bus': 'int', 'target': 'int', 'unit': 'int',
864            '*serial': 'str', '*dev': 'str'} }
865
866 ##
867 # @GuestFilesystemInfo:
868 #
869 # @name: disk name
870 # @mountpoint: mount point path
871 # @type: file system type string
872 # @used-bytes: file system used bytes (since 3.0)
873 # @total-bytes: non-root file system total bytes (since 3.0)
874 # @disk: an array of disk hardware information that the volume lies on,
875 #        which may be empty if the disk type is not supported
876 #
877 # Since: 2.2
878 ##
879 { 'struct': 'GuestFilesystemInfo',
880   'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
881            '*used-bytes': 'uint64', '*total-bytes': 'uint64',
882            'disk': ['GuestDiskAddress']} }
883
884 ##
885 # @guest-get-fsinfo:
886 #
887 # Returns: The list of filesystems information mounted in the guest.
888 #          The returned mountpoints may be specified to
889 #          @guest-fsfreeze-freeze-list.
890 #          Network filesystems (such as CIFS and NFS) are not listed.
891 #
892 # Since: 2.2
893 ##
894 { 'command': 'guest-get-fsinfo',
895   'returns': ['GuestFilesystemInfo'] }
896
897 ##
898 # @guest-set-user-password:
899 #
900 # @username: the user account whose password to change
901 # @password: the new password entry string, base64 encoded
902 # @crypted: true if password is already crypt()d, false if raw
903 #
904 # If the @crypted flag is true, it is the caller's responsibility
905 # to ensure the correct crypt() encryption scheme is used. This
906 # command does not attempt to interpret or report on the encryption
907 # scheme. Refer to the documentation of the guest operating system
908 # in question to determine what is supported.
909 #
910 # Not all guest operating systems will support use of the
911 # @crypted flag, as they may require the clear-text password
912 #
913 # The @password parameter must always be base64 encoded before
914 # transmission, even if already crypt()d, to ensure it is 8-bit
915 # safe when passed as JSON.
916 #
917 # Returns: Nothing on success.
918 #
919 # Since: 2.3
920 ##
921 { 'command': 'guest-set-user-password',
922   'data': { 'username': 'str', 'password': 'str', 'crypted': 'bool' } }
923
924 ##
925 # @GuestMemoryBlock:
926 #
927 # @phys-index: Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
928 #
929 # @online: Whether the MEMORY BLOCK is enabled in guest.
930 #
931 # @can-offline: Whether offlining the MEMORY BLOCK is possible.
932 #               This member is always filled in by the guest agent when the
933 #               structure is returned, and always ignored on input (hence it
934 #               can be omitted then).
935 #
936 # Since: 2.3
937 ##
938 { 'struct': 'GuestMemoryBlock',
939   'data': {'phys-index': 'uint64',
940            'online': 'bool',
941            '*can-offline': 'bool'} }
942
943 ##
944 # @guest-get-memory-blocks:
945 #
946 # Retrieve the list of the guest's memory blocks.
947 #
948 # This is a read-only operation.
949 #
950 # Returns: The list of all memory blocks the guest knows about.
951 #          Each memory block is put on the list exactly once, but their order
952 #          is unspecified.
953 #
954 # Since: 2.3
955 ##
956 { 'command': 'guest-get-memory-blocks',
957   'returns': ['GuestMemoryBlock'] }
958
959 ##
960 # @GuestMemoryBlockResponseType:
961 #
962 # An enumeration of memory block operation result.
963 #
964 # @success: the operation of online/offline memory block is successful.
965 # @not-found: can't find the corresponding memoryXXX directory in sysfs.
966 # @operation-not-supported: for some old kernels, it does not support
967 #                           online or offline memory block.
968 # @operation-failed: the operation of online/offline memory block fails,
969 #                    because of some errors happen.
970 #
971 # Since: 2.3
972 ##
973 { 'enum': 'GuestMemoryBlockResponseType',
974   'data': ['success', 'not-found', 'operation-not-supported',
975            'operation-failed'] }
976
977 ##
978 # @GuestMemoryBlockResponse:
979 #
980 # @phys-index: same with the 'phys-index' member of @GuestMemoryBlock.
981 #
982 # @response: the result of memory block operation.
983 #
984 # @error-code: the error number.
985 #              When memory block operation fails, we assign the value of
986 #              'errno' to this member, it indicates what goes wrong.
987 #              When the operation succeeds, it will be omitted.
988 #
989 # Since: 2.3
990 ##
991 { 'struct': 'GuestMemoryBlockResponse',
992   'data': { 'phys-index': 'uint64',
993             'response': 'GuestMemoryBlockResponseType',
994             '*error-code': 'int' }}
995
996 ##
997 # @guest-set-memory-blocks:
998 #
999 # Attempt to reconfigure (currently: enable/disable) state of memory blocks
1000 # inside the guest.
1001 #
1002 # The input list is processed node by node in order. In each node @phys-index
1003 # is used to look up the guest MEMORY BLOCK, for which @online specifies the
1004 # requested state. The set of distinct @phys-index's is only required to be a
1005 # subset of the guest-supported identifiers. There's no restriction on list
1006 # length or on repeating the same @phys-index (with possibly different @online
1007 # field).
1008 # Preferably the input list should describe a modified subset of
1009 # @guest-get-memory-blocks' return value.
1010 #
1011 # Returns: The operation results, it is a list of @GuestMemoryBlockResponse,
1012 #          which is corresponding to the input list.
1013 #
1014 #          Note: it will return NULL if the @mem-blks list was empty on input,
1015 #          or there is an error, and in this case, guest state will not be
1016 #          changed.
1017 #
1018 # Since: 2.3
1019 ##
1020 { 'command': 'guest-set-memory-blocks',
1021   'data':    {'mem-blks': ['GuestMemoryBlock'] },
1022   'returns': ['GuestMemoryBlockResponse'] }
1023
1024 ##
1025 # @GuestMemoryBlockInfo:
1026 #
1027 # @size: the size (in bytes) of the guest memory blocks,
1028 #        which are the minimal units of memory block online/offline
1029 #        operations (also called Logical Memory Hotplug).
1030 #
1031 # Since: 2.3
1032 ##
1033 { 'struct': 'GuestMemoryBlockInfo',
1034   'data': {'size': 'uint64'} }
1035
1036 ##
1037 # @guest-get-memory-block-info:
1038 #
1039 # Get information relating to guest memory blocks.
1040 #
1041 # Returns: @GuestMemoryBlockInfo
1042 #
1043 # Since: 2.3
1044 ##
1045 { 'command': 'guest-get-memory-block-info',
1046   'returns': 'GuestMemoryBlockInfo' }
1047
1048 ##
1049 # @GuestExecStatus:
1050 #
1051 # @exited: true if process has already terminated.
1052 # @exitcode: process exit code if it was normally terminated.
1053 # @signal: signal number (linux) or unhandled exception code
1054 #          (windows) if the process was abnormally terminated.
1055 # @out-data: base64-encoded stdout of the process
1056 # @err-data: base64-encoded stderr of the process
1057 #            Note: @out-data and @err-data are present only
1058 #            if 'capture-output' was specified for 'guest-exec'
1059 # @out-truncated: true if stdout was not fully captured
1060 #                 due to size limitation.
1061 # @err-truncated: true if stderr was not fully captured
1062 #                 due to size limitation.
1063 #
1064 # Since: 2.5
1065 ##
1066 { 'struct': 'GuestExecStatus',
1067   'data': { 'exited': 'bool', '*exitcode': 'int', '*signal': 'int',
1068             '*out-data': 'str', '*err-data': 'str',
1069             '*out-truncated': 'bool', '*err-truncated': 'bool' }}
1070 ##
1071 # @guest-exec-status:
1072 #
1073 # Check status of process associated with PID retrieved via guest-exec.
1074 # Reap the process and associated metadata if it has exited.
1075 #
1076 # @pid: pid returned from guest-exec
1077 #
1078 # Returns: GuestExecStatus on success.
1079 #
1080 # Since: 2.5
1081 ##
1082 { 'command': 'guest-exec-status',
1083   'data':    { 'pid': 'int' },
1084   'returns': 'GuestExecStatus' }
1085
1086 ##
1087 # @GuestExec:
1088 # @pid: pid of child process in guest OS
1089 #
1090 # Since: 2.5
1091 ##
1092 { 'struct': 'GuestExec',
1093   'data': { 'pid': 'int'} }
1094
1095 ##
1096 # @guest-exec:
1097 #
1098 # Execute a command in the guest
1099 #
1100 # @path: path or executable name to execute
1101 # @arg: argument list to pass to executable
1102 # @env: environment variables to pass to executable
1103 # @input-data: data to be passed to process stdin (base64 encoded)
1104 # @capture-output: bool flag to enable capture of
1105 #                  stdout/stderr of running process. defaults to false.
1106 #
1107 # Returns: PID on success.
1108 #
1109 # Since: 2.5
1110 ##
1111 { 'command': 'guest-exec',
1112   'data':    { 'path': 'str', '*arg': ['str'], '*env': ['str'],
1113                '*input-data': 'str', '*capture-output': 'bool' },
1114   'returns': 'GuestExec' }
1115
1116
1117 ##
1118 # @GuestHostName:
1119 # @host-name: Fully qualified domain name of the guest OS
1120 #
1121 # Since: 2.10
1122 ##
1123 { 'struct': 'GuestHostName',
1124   'data':   { 'host-name': 'str' } }
1125
1126 ##
1127 # @guest-get-host-name:
1128 #
1129 # Return a name for the machine.
1130 #
1131 # The returned name is not necessarily a fully-qualified domain name, or even
1132 # present in DNS or some other name service at all. It need not even be unique
1133 # on your local network or site, but usually it is.
1134 #
1135 # Returns: the host name of the machine on success
1136 #
1137 # Since: 2.10
1138 ##
1139 { 'command': 'guest-get-host-name',
1140   'returns': 'GuestHostName' }
1141
1142
1143 ##
1144 # @GuestUser:
1145 # @user: Username
1146 # @domain: Logon domain (windows only)
1147 # @login-time: Time of login of this user on the computer. If multiple
1148 #              instances of the user are logged in, the earliest login time is
1149 #              reported. The value is in fractional seconds since epoch time.
1150 #
1151 # Since: 2.10
1152 ##
1153 { 'struct': 'GuestUser',
1154   'data': { 'user': 'str', 'login-time': 'number', '*domain': 'str' } }
1155
1156 ##
1157 # @guest-get-users:
1158 # Retrieves a list of currently active users on the VM.
1159 #
1160 # Returns: A unique list of users.
1161 #
1162 # Since: 2.10
1163 ##
1164 { 'command': 'guest-get-users',
1165   'returns': ['GuestUser'] }
1166
1167 ##
1168 # @GuestTimezone:
1169 #
1170 # @zone: Timezone name. These values may differ depending on guest/OS and
1171 #        should only be used for informational purposes.
1172 # @offset: Offset to UTC in seconds, negative numbers for time zones west of
1173 #          GMT, positive numbers for east
1174 #
1175 # Since: 2.10
1176 ##
1177 { 'struct': 'GuestTimezone',
1178   'data':   { '*zone': 'str', 'offset': 'int' } }
1179
1180 ##
1181 # @guest-get-timezone:
1182 #
1183 # Retrieves the timezone information from the guest.
1184 #
1185 # Returns: A GuestTimezone dictionary.
1186 #
1187 # Since: 2.10
1188 ##
1189 { 'command': 'guest-get-timezone',
1190   'returns': 'GuestTimezone' }
1191
1192 ##
1193 # @GuestOSInfo:
1194 #
1195 # @kernel-release:
1196 # * POSIX: release field returned by uname(2)
1197 # * Windows: build number of the OS
1198 # @kernel-version:
1199 # * POSIX: version field returned by uname(2)
1200 # * Windows: version number of the OS
1201 # @machine:
1202 # * POSIX: machine field returned by uname(2)
1203 # * Windows: one of x86, x86_64, arm, ia64
1204 # @id:
1205 # * POSIX: as defined by os-release(5)
1206 # * Windows: contains string "mswindows"
1207 # @name:
1208 # * POSIX: as defined by os-release(5)
1209 # * Windows: contains string "Microsoft Windows"
1210 # @pretty-name:
1211 # * POSIX: as defined by os-release(5)
1212 # * Windows: product name, e.g. "Microsoft Windows 10 Enterprise"
1213 # @version:
1214 # * POSIX: as defined by os-release(5)
1215 # * Windows: long version string, e.g. "Microsoft Windows Server 2008"
1216 # @version-id:
1217 # * POSIX: as defined by os-release(5)
1218 # * Windows: short version identifier, e.g. "7" or "20012r2"
1219 # @variant:
1220 # * POSIX: as defined by os-release(5)
1221 # * Windows: contains string "server" or "client"
1222 # @variant-id:
1223 # * POSIX: as defined by os-release(5)
1224 # * Windows: contains string "server" or "client"
1225 #
1226 # Notes:
1227 #
1228 # On POSIX systems the fields @id, @name, @pretty-name, @version, @version-id,
1229 # @variant and @variant-id follow the definition specified in os-release(5).
1230 # Refer to the manual page for exact description of the fields. Their values
1231 # are taken from the os-release file. If the file is not present in the system,
1232 # or the values are not present in the file, the fields are not included.
1233 #
1234 # On Windows the values are filled from information gathered from the system.
1235 #
1236 # Since: 2.10
1237 ##
1238 { 'struct': 'GuestOSInfo',
1239   'data': {
1240       '*kernel-release': 'str', '*kernel-version': 'str',
1241       '*machine': 'str', '*id': 'str', '*name': 'str',
1242       '*pretty-name': 'str', '*version': 'str', '*version-id': 'str',
1243       '*variant': 'str', '*variant-id': 'str' } }
1244
1245 ##
1246 # @guest-get-osinfo:
1247 #
1248 # Retrieve guest operating system information
1249 #
1250 # Returns: @GuestOSInfo
1251 #
1252 # Since: 2.10
1253 ##
1254 { 'command': 'guest-get-osinfo',
1255   'returns': 'GuestOSInfo' }