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