qapi2texi: Fix up output around #optional
[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: #optional 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: #optional "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: #optional 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: #optional 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: #optional 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
430 #
431 # Returns: Number of file systems currently frozen. On error, all filesystems
432 # will be thawed.
433 #
434 # Since: 0.15.0
435 ##
436 { 'command': 'guest-fsfreeze-freeze',
437   'returns': 'int' }
438
439 ##
440 # @guest-fsfreeze-freeze-list:
441 #
442 # Sync and freeze specified guest filesystems
443 #
444 # @mountpoints: #optional an array of mountpoints of filesystems to be frozen.
445 #               If omitted, every mounted filesystem is frozen.
446 #
447 # Returns: Number of file systems currently frozen. On error, all filesystems
448 # will be thawed.
449 #
450 # Since: 2.2
451 ##
452 { 'command': 'guest-fsfreeze-freeze-list',
453   'data':    { '*mountpoints': ['str'] },
454   'returns': 'int' }
455
456 ##
457 # @guest-fsfreeze-thaw:
458 #
459 # Unfreeze all frozen guest filesystems
460 #
461 # Returns: Number of file systems thawed by this call
462 #
463 # Note: if return value does not match the previous call to
464 #       guest-fsfreeze-freeze, this likely means some freezable
465 #       filesystems were unfrozen before this call, and that the
466 #       filesystem state may have changed before issuing this
467 #       command.
468 #
469 # Since: 0.15.0
470 ##
471 { 'command': 'guest-fsfreeze-thaw',
472   'returns': 'int' }
473
474 ##
475 # @GuestFilesystemTrimResult:
476 #
477 # @path: path that was trimmed
478 # @error: an error message when trim failed
479 # @trimmed: bytes trimmed for this path
480 # @minimum: reported effective minimum for this path
481 #
482 # Since: 2.4
483 ##
484 { 'struct': 'GuestFilesystemTrimResult',
485   'data': {'path': 'str',
486            '*trimmed': 'int', '*minimum': 'int', '*error': 'str'} }
487
488 ##
489 # @GuestFilesystemTrimResponse:
490 #
491 # @paths: list of @GuestFilesystemTrimResult per path that was trimmed
492 #
493 # Since: 2.4
494 ##
495 { 'struct': 'GuestFilesystemTrimResponse',
496   'data': {'paths': ['GuestFilesystemTrimResult']} }
497
498 ##
499 # @guest-fstrim:
500 #
501 # Discard (or "trim") blocks which are not in use by the filesystem.
502 #
503 # @minimum:
504 #       Minimum contiguous free range to discard, in bytes. Free ranges
505 #       smaller than this may be ignored (this is a hint and the guest
506 #       may not respect it).  By increasing this value, the fstrim
507 #       operation will complete more quickly for filesystems with badly
508 #       fragmented free space, although not all blocks will be discarded.
509 #       The default value is zero, meaning "discard every free block".
510 #
511 # Returns: A @GuestFilesystemTrimResponse which contains the
512 #          status of all trimmed paths. (since 2.4)
513 #
514 # Since: 1.2
515 ##
516 { 'command': 'guest-fstrim',
517   'data': { '*minimum': 'int' },
518   'returns': 'GuestFilesystemTrimResponse' }
519
520 ##
521 # @guest-suspend-disk:
522 #
523 # Suspend guest to disk.
524 #
525 # This command tries to execute the scripts provided by the pm-utils package.
526 # If it's not available, the suspend operation will be performed by manually
527 # writing to a sysfs file.
528 #
529 # For the best results it's strongly recommended to have the pm-utils
530 # package installed in the guest.
531 #
532 # This command does NOT return a response on success. There is a high chance
533 # the command succeeded if the VM exits with a zero exit status or, when
534 # running with --no-shutdown, by issuing the query-status QMP command to
535 # to confirm the VM status is "shutdown". However, the VM could also exit
536 # (or set its status to "shutdown") due to other reasons.
537 #
538 # The following errors may be returned:
539 #          If suspend to disk is not supported, Unsupported
540 #
541 # Notes: It's strongly recommended to issue the guest-sync command before
542 #        sending commands when the guest resumes
543 #
544 # Since: 1.1
545 ##
546 { 'command': 'guest-suspend-disk', 'success-response': false }
547
548 ##
549 # @guest-suspend-ram:
550 #
551 # Suspend guest to ram.
552 #
553 # This command tries to execute the scripts provided by the pm-utils package.
554 # If it's not available, the suspend operation will be performed by manually
555 # writing to a sysfs file.
556 #
557 # For the best results it's strongly recommended to have the pm-utils
558 # package installed in the guest.
559 #
560 # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
561 # command.  Thus, it's *required* to query QEMU for the presence of the
562 # 'system_wakeup' command before issuing guest-suspend-ram.
563 #
564 # This command does NOT return a response on success. There are two options
565 # to check for success:
566 #   1. Wait for the SUSPEND QMP event from QEMU
567 #   2. Issue the query-status QMP command to confirm the VM status is
568 #      "suspended"
569 #
570 # The following errors may be returned:
571 #          If suspend to ram is not supported, Unsupported
572 #
573 # Notes: It's strongly recommended to issue the guest-sync command before
574 #        sending commands when the guest resumes
575 #
576 # Since: 1.1
577 ##
578 { 'command': 'guest-suspend-ram', 'success-response': false }
579
580 ##
581 # @guest-suspend-hybrid:
582 #
583 # Save guest state to disk and suspend to ram.
584 #
585 # This command requires the pm-utils package to be installed in the guest.
586 #
587 # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
588 # command.  Thus, it's *required* to query QEMU for the presence of the
589 # 'system_wakeup' command before issuing guest-suspend-hybrid.
590 #
591 # This command does NOT return a response on success. There are two options
592 # to check for success:
593 #   1. Wait for the SUSPEND QMP event from QEMU
594 #   2. Issue the query-status QMP command to confirm the VM status is
595 #      "suspended"
596 #
597 # The following errors may be returned:
598 #          If hybrid suspend is not supported, Unsupported
599 #
600 # Notes: It's strongly recommended to issue the guest-sync command before
601 #        sending commands when the guest resumes
602 #
603 # Since: 1.1
604 ##
605 { 'command': 'guest-suspend-hybrid', 'success-response': false }
606
607 ##
608 # @GuestIpAddressType:
609 #
610 # An enumeration of supported IP address types
611 #
612 # @ipv4: IP version 4
613 #
614 # @ipv6: IP version 6
615 #
616 # Since: 1.1
617 ##
618 { 'enum': 'GuestIpAddressType',
619   'data': [ 'ipv4', 'ipv6' ] }
620
621 ##
622 # @GuestIpAddress:
623 #
624 # @ip-address: IP address
625 #
626 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
627 #
628 # @prefix: Network prefix length of @ip-address
629 #
630 # Since: 1.1
631 ##
632 { 'struct': 'GuestIpAddress',
633   'data': {'ip-address': 'str',
634            'ip-address-type': 'GuestIpAddressType',
635            'prefix': 'int'} }
636
637 ##
638 # @GuestNetworkInterface:
639 #
640 # @name: The name of interface for which info are being delivered
641 #
642 # @hardware-address: Hardware address of @name
643 #
644 # @ip-addresses: List of addresses assigned to @name
645 #
646 # Since: 1.1
647 ##
648 { 'struct': 'GuestNetworkInterface',
649   'data': {'name': 'str',
650            '*hardware-address': 'str',
651            '*ip-addresses': ['GuestIpAddress'] } }
652
653 ##
654 # @guest-network-get-interfaces:
655 #
656 # Get list of guest IP addresses, MAC addresses
657 # and netmasks.
658 #
659 # Returns: List of GuestNetworkInfo on success.
660 #
661 # Since: 1.1
662 ##
663 { 'command': 'guest-network-get-interfaces',
664   'returns': ['GuestNetworkInterface'] }
665
666 ##
667 # @GuestLogicalProcessor:
668 #
669 # @logical-id: Arbitrary guest-specific unique identifier of the VCPU.
670 #
671 # @online: Whether the VCPU is enabled.
672 #
673 # @can-offline: #optional Whether offlining the VCPU is possible. This member
674 #               is always filled in by the guest agent when the structure is
675 #               returned, and always ignored on input (hence it can be omitted
676 #               then).
677 #
678 # Since: 1.5
679 ##
680 { 'struct': 'GuestLogicalProcessor',
681   'data': {'logical-id': 'int',
682            'online': 'bool',
683            '*can-offline': 'bool'} }
684
685 ##
686 # @guest-get-vcpus:
687 #
688 # Retrieve the list of the guest's logical processors.
689 #
690 # This is a read-only operation.
691 #
692 # Returns: The list of all VCPUs the guest knows about. Each VCPU is put on the
693 # list exactly once, but their order is unspecified.
694 #
695 # Since: 1.5
696 ##
697 { 'command': 'guest-get-vcpus',
698   'returns': ['GuestLogicalProcessor'] }
699
700 ##
701 # @guest-set-vcpus:
702 #
703 # Attempt to reconfigure (currently: enable/disable) logical processors inside
704 # the guest.
705 #
706 # The input list is processed node by node in order. In each node @logical-id
707 # is used to look up the guest VCPU, for which @online specifies the requested
708 # state. The set of distinct @logical-id's is only required to be a subset of
709 # the guest-supported identifiers. There's no restriction on list length or on
710 # repeating the same @logical-id (with possibly different @online field).
711 # Preferably the input list should describe a modified subset of
712 # @guest-get-vcpus' return value.
713 #
714 # Returns: The length of the initial sublist that has been successfully
715 #          processed. The guest agent maximizes this value. Possible cases:
716 #
717 #          - 0:              if the @vcpus list was empty on input. Guest state
718 #                            has not been changed. Otherwise,
719 #          - Error:          processing the first node of @vcpus failed for the
720 #                            reason returned. Guest state has not been changed.
721 #                            Otherwise,
722 #          - < length(@vcpus): more than zero initial nodes have been processed,
723 #                            but not the entire @vcpus list. Guest state has
724 #                            changed accordingly. To retrieve the error
725 #                            (assuming it persists), repeat the call with the
726 #                            successfully processed initial sublist removed.
727 #                            Otherwise,
728 #          - length(@vcpus): call successful.
729 #
730 # Since: 1.5
731 ##
732 { 'command': 'guest-set-vcpus',
733   'data':    {'vcpus': ['GuestLogicalProcessor'] },
734   'returns': 'int' }
735
736 ##
737 # @GuestDiskBusType:
738 #
739 # An enumeration of bus type of disks
740 #
741 # @ide: IDE disks
742 # @fdc: floppy disks
743 # @scsi: SCSI disks
744 # @virtio: virtio disks
745 # @xen: Xen disks
746 # @usb: USB disks
747 # @uml: UML disks
748 # @sata: SATA disks
749 # @sd: SD cards
750 # @unknown: Unknown bus type
751 # @ieee1394: Win IEEE 1394 bus type
752 # @ssa: Win SSA bus type
753 # @fibre: Win fiber channel bus type
754 # @raid: Win RAID bus type
755 # @iscsi: Win iScsi bus type
756 # @sas: Win serial-attaches SCSI bus type
757 # @mmc: Win multimedia card (MMC) bus type
758 # @virtual: Win virtual bus type
759 # @file-backed virtual: Win file-backed bus type
760 #
761 # Since: 2.2; 'Unknown' and all entries below since 2.4
762 ##
763 { 'enum': 'GuestDiskBusType',
764   'data': [ 'ide', 'fdc', 'scsi', 'virtio', 'xen', 'usb', 'uml', 'sata',
765             'sd', 'unknown', 'ieee1394', 'ssa', 'fibre', 'raid', 'iscsi',
766             'sas', 'mmc', 'virtual', 'file-backed-virtual' ] }
767
768
769 ##
770 # @GuestPCIAddress:
771 #
772 # @domain: domain id
773 # @bus: bus id
774 # @slot: slot id
775 # @function: function id
776 #
777 # Since: 2.2
778 ##
779 { 'struct': 'GuestPCIAddress',
780   'data': {'domain': 'int', 'bus': 'int',
781            'slot': 'int', 'function': 'int'} }
782
783 ##
784 # @GuestDiskAddress:
785 #
786 # @pci-controller: controller's PCI address
787 # @bus-type: bus type
788 # @bus: bus id
789 # @target: target id
790 # @unit: unit id
791 #
792 # Since: 2.2
793 ##
794 { 'struct': 'GuestDiskAddress',
795   'data': {'pci-controller': 'GuestPCIAddress',
796            'bus-type': 'GuestDiskBusType',
797            'bus': 'int', 'target': 'int', 'unit': 'int'} }
798
799 ##
800 # @GuestFilesystemInfo:
801 #
802 # @name: disk name
803 # @mountpoint: mount point path
804 # @type: file system type string
805 # @disk: an array of disk hardware information that the volume lies on,
806 #        which may be empty if the disk type is not supported
807 #
808 # Since: 2.2
809 ##
810 { 'struct': 'GuestFilesystemInfo',
811   'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str',
812            'disk': ['GuestDiskAddress']} }
813
814 ##
815 # @guest-get-fsinfo:
816 #
817 # Returns: The list of filesystems information mounted in the guest.
818 #          The returned mountpoints may be specified to
819 #          @guest-fsfreeze-freeze-list.
820 #          Network filesystems (such as CIFS and NFS) are not listed.
821 #
822 # Since: 2.2
823 ##
824 { 'command': 'guest-get-fsinfo',
825   'returns': ['GuestFilesystemInfo'] }
826
827 ##
828 # @guest-set-user-password:
829 #
830 # @username: the user account whose password to change
831 # @password: the new password entry string, base64 encoded
832 # @crypted: true if password is already crypt()d, false if raw
833 #
834 # If the @crypted flag is true, it is the caller's responsibility
835 # to ensure the correct crypt() encryption scheme is used. This
836 # command does not attempt to interpret or report on the encryption
837 # scheme. Refer to the documentation of the guest operating system
838 # in question to determine what is supported.
839 #
840 # Not all guest operating systems will support use of the
841 # @crypted flag, as they may require the clear-text password
842 #
843 # The @password parameter must always be base64 encoded before
844 # transmission, even if already crypt()d, to ensure it is 8-bit
845 # safe when passed as JSON.
846 #
847 # Returns: Nothing on success.
848 #
849 # Since: 2.3
850 ##
851 { 'command': 'guest-set-user-password',
852   'data': { 'username': 'str', 'password': 'str', 'crypted': 'bool' } }
853
854 ##
855 # @GuestMemoryBlock:
856 #
857 # @phys-index: Arbitrary guest-specific unique identifier of the MEMORY BLOCK.
858 #
859 # @online: Whether the MEMORY BLOCK is enabled in guest.
860 #
861 # @can-offline: #optional Whether offlining the MEMORY BLOCK is possible.
862 #               This member is always filled in by the guest agent when the
863 #               structure is returned, and always ignored on input (hence it
864 #               can be omitted then).
865 #
866 # Since: 2.3
867 ##
868 { 'struct': 'GuestMemoryBlock',
869   'data': {'phys-index': 'uint64',
870            'online': 'bool',
871            '*can-offline': 'bool'} }
872
873 ##
874 # @guest-get-memory-blocks:
875 #
876 # Retrieve the list of the guest's memory blocks.
877 #
878 # This is a read-only operation.
879 #
880 # Returns: The list of all memory blocks the guest knows about.
881 # Each memory block is put on the list exactly once, but their order
882 # is unspecified.
883 #
884 # Since: 2.3
885 ##
886 { 'command': 'guest-get-memory-blocks',
887   'returns': ['GuestMemoryBlock'] }
888
889 ##
890 # @GuestMemoryBlockResponseType:
891 #
892 # An enumeration of memory block operation result.
893 #
894 # @success: the operation of online/offline memory block is successful.
895 # @not-found: can't find the corresponding memoryXXX directory in sysfs.
896 # @operation-not-supported: for some old kernels, it does not support
897 #                           online or offline memory block.
898 # @operation-failed: the operation of online/offline memory block fails,
899 #                    because of some errors happen.
900 #
901 # Since: 2.3
902 ##
903 { 'enum': 'GuestMemoryBlockResponseType',
904   'data': ['success', 'not-found', 'operation-not-supported',
905            'operation-failed'] }
906
907 ##
908 # @GuestMemoryBlockResponse:
909 #
910 # @phys-index: same with the 'phys-index' member of @GuestMemoryBlock.
911 #
912 # @response: the result of memory block operation.
913 #
914 # @error-code: #optional the error number.
915 #               When memory block operation fails, we assign the value of
916 #               'errno' to this member, it indicates what goes wrong.
917 #               When the operation succeeds, it will be omitted.
918 #
919 # Since: 2.3
920 ##
921 { 'struct': 'GuestMemoryBlockResponse',
922   'data': { 'phys-index': 'uint64',
923             'response': 'GuestMemoryBlockResponseType',
924             '*error-code': 'int' }}
925
926 ##
927 # @guest-set-memory-blocks:
928 #
929 # Attempt to reconfigure (currently: enable/disable) state of memory blocks
930 # inside the guest.
931 #
932 # The input list is processed node by node in order. In each node @phys-index
933 # is used to look up the guest MEMORY BLOCK, for which @online specifies the
934 # requested state. The set of distinct @phys-index's is only required to be a
935 # subset of the guest-supported identifiers. There's no restriction on list
936 # length or on repeating the same @phys-index (with possibly different @online
937 # field).
938 # Preferably the input list should describe a modified subset of
939 # @guest-get-memory-blocks' return value.
940 #
941 # Returns: The operation results, it is a list of @GuestMemoryBlockResponse,
942 #          which is corresponding to the input list.
943 #
944 #          Note: it will return NULL if the @mem-blks list was empty on input,
945 #          or there is an error, and in this case, guest state will not be
946 #          changed.
947 #
948 # Since: 2.3
949 ##
950 { 'command': 'guest-set-memory-blocks',
951   'data':    {'mem-blks': ['GuestMemoryBlock'] },
952   'returns': ['GuestMemoryBlockResponse'] }
953
954 ##
955 # @GuestMemoryBlockInfo:
956 #
957 # @size: the size (in bytes) of the guest memory blocks,
958 #        which are the minimal units of memory block online/offline
959 #        operations (also called Logical Memory Hotplug).
960 #
961 # Since: 2.3
962 ##
963 { 'struct': 'GuestMemoryBlockInfo',
964   'data': {'size': 'uint64'} }
965
966 ##
967 # @guest-get-memory-block-info:
968 #
969 # Get information relating to guest memory blocks.
970 #
971 # Returns: @GuestMemoryBlockInfo
972 #
973 # Since: 2.3
974 ##
975 { 'command': 'guest-get-memory-block-info',
976   'returns': 'GuestMemoryBlockInfo' }
977
978 ##
979 # @GuestExecStatus:
980 #
981 # @exited: true if process has already terminated.
982 # @exitcode: #optional process exit code if it was normally terminated.
983 # @signal: #optional signal number (linux) or unhandled exception code
984 #       (windows) if the process was abnormally terminated.
985 # @out-data: #optional base64-encoded stdout of the process
986 # @err-data: #optional base64-encoded stderr of the process
987 #       Note: @out-data and @err-data are present only
988 #       if 'capture-output' was specified for 'guest-exec'
989 # @out-truncated: #optional true if stdout was not fully captured
990 #       due to size limitation.
991 # @err-truncated: #optional true if stderr was not fully captured
992 #       due to size limitation.
993 #
994 # Since: 2.5
995 ##
996 { 'struct': 'GuestExecStatus',
997   'data': { 'exited': 'bool', '*exitcode': 'int', '*signal': 'int',
998             '*out-data': 'str', '*err-data': 'str',
999             '*out-truncated': 'bool', '*err-truncated': 'bool' }}
1000 ##
1001 # @guest-exec-status:
1002 #
1003 # Check status of process associated with PID retrieved via guest-exec.
1004 # Reap the process and associated metadata if it has exited.
1005 #
1006 # @pid: pid returned from guest-exec
1007 #
1008 # Returns: GuestExecStatus on success.
1009 #
1010 # Since: 2.5
1011 ##
1012 { 'command': 'guest-exec-status',
1013   'data':    { 'pid': 'int' },
1014   'returns': 'GuestExecStatus' }
1015
1016 ##
1017 # @GuestExec:
1018 # @pid: pid of child process in guest OS
1019 #
1020 # Since: 2.5
1021 ##
1022 { 'struct': 'GuestExec',
1023   'data': { 'pid': 'int'} }
1024
1025 ##
1026 # @guest-exec:
1027 #
1028 # Execute a command in the guest
1029 #
1030 # @path: path or executable name to execute
1031 # @arg: #optional argument list to pass to executable
1032 # @env: #optional environment variables to pass to executable
1033 # @input-data: #optional data to be passed to process stdin (base64 encoded)
1034 # @capture-output: #optional bool flag to enable capture of
1035 #                  stdout/stderr of running process. defaults to false.
1036 #
1037 # Returns: PID on success.
1038 #
1039 # Since: 2.5
1040 ##
1041 { 'command': 'guest-exec',
1042   'data':    { 'path': 'str', '*arg': ['str'], '*env': ['str'],
1043                '*input-data': 'str', '*capture-output': 'bool' },
1044   'returns': 'GuestExec' }