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