target-arm/neon_helper: Remove obsolete FIXME comment
[qemu/pbrook.git] / qapi-schema-guest.json
blobed0eb698c63f431089fc9dbcf7b44ce491f3f548
1 # *-*- Mode: Python -*-*
3 ##
5 # Echo back a unique integer value, and prepend to response a
6 # leading sentinel byte (0xFF) the client can check scan for.
8 # This is used by clients talking to the guest agent over the
9 # wire to ensure the stream is in sync and doesn't contain stale
10 # data from previous client. It must be issued upon initial
11 # connection, and after any client-side timeouts (including
12 # timeouts on receiving a response to this command).
14 # After issuing this request, all guest agent responses should be
15 # ignored until the response containing the unique integer value
16 # the client passed in is returned. Receival of the 0xFF sentinel
17 # byte must be handled as an indication that the client's
18 # lexer/tokenizer/parser state should be flushed/reset in
19 # preparation for reliably receiving the subsequent response. As
20 # an optimization, clients may opt to ignore all data until a
21 # sentinel value is receiving to avoid unnecessary processing of
22 # stale data.
24 # Similarly, clients should also precede this *request*
25 # with a 0xFF byte to make sure the guest agent flushes any
26 # partially read JSON data from a previous client connection.
28 # @id: randomly generated 64-bit integer
30 # Returns: The unique integer id passed in by the client
32 # Since: 1.1
33 # ##
34 { 'command': 'guest-sync-delimited'
35   'data':    { 'id': 'int' },
36   'returns': 'int' }
39 # @guest-sync:
41 # Echo back a unique integer value
43 # This is used by clients talking to the guest agent over the
44 # wire to ensure the stream is in sync and doesn't contain stale
45 # data from previous client. All guest agent responses should be
46 # ignored until the provided unique integer value is returned,
47 # and it is up to the client to handle stale whole or
48 # partially-delivered JSON text in such a way that this response
49 # can be obtained.
51 # In cases where a partial stale response was previously
52 # received by the client, this cannot always be done reliably.
53 # One particular scenario being if qemu-ga responses are fed
54 # character-by-character into a JSON parser. In these situations,
55 # using guest-sync-delimited may be optimal.
57 # For clients that fetch responses line by line and convert them
58 # to JSON objects, guest-sync should be sufficient, but note that
59 # in cases where the channel is dirty some attempts at parsing the
60 # response may result in a parser error.
62 # Such clients should also precede this command
63 # with a 0xFF byte to make sure the guest agent flushes any
64 # partially read JSON data from a previous session.
66 # @id: randomly generated 64-bit integer
68 # Returns: The unique integer id passed in by the client
70 # Since: 0.15.0
72 { 'command': 'guest-sync'
73   'data':    { 'id': 'int' },
74   'returns': 'int' }
77 # @guest-ping:
79 # Ping the guest agent, a non-error return implies success
81 # Since: 0.15.0
83 { 'command': 'guest-ping' }
86 # @GuestAgentCommandInfo:
88 # Information about guest agent commands.
90 # @name: name of the command
92 # @enabled: whether command is currently enabled by guest admin
94 # Since 1.1.0
96 { 'type': 'GuestAgentCommandInfo',
97   'data': { 'name': 'str', 'enabled': 'bool' } }
100 # @GuestAgentInfo
102 # Information about guest agent.
104 # @version: guest agent version
106 # @supported_commands: Information about guest agent commands
108 # Since 0.15.0
110 { 'type': 'GuestAgentInfo',
111   'data': { 'version': 'str',
112             'supported_commands': ['GuestAgentCommandInfo'] } }
114 # @guest-info:
116 # Get some information about the guest agent.
118 # Returns: @GuestAgentInfo
120 # Since: 0.15.0
122 { 'command': 'guest-info',
123   'returns': 'GuestAgentInfo' }
126 # @guest-shutdown:
128 # Initiate guest-activated shutdown. Note: this is an asynchronous
129 # shutdown request, with no guarantee of successful shutdown.
131 # @mode: #optional "halt", "powerdown" (default), or "reboot"
133 # This command does NOT return a response on success. Success condition
134 # is indicated by the VM exiting with a zero exit status or, when
135 # running with --no-shutdown, by issuing the query-status QMP command
136 # to confirm the VM status is "shutdown".
138 # Since: 0.15.0
140 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
141   'success-response': 'no' }
144 # @guest-file-open:
146 # Open a file in the guest and retrieve a file handle for it
148 # @filepath: Full path to the file in the guest to open.
150 # @mode: #optional open mode, as per fopen(), "r" is the default.
152 # Returns: Guest file handle on success.
154 # Since: 0.15.0
156 { 'command': 'guest-file-open',
157   'data':    { 'path': 'str', '*mode': 'str' },
158   'returns': 'int' }
161 # @guest-file-close:
163 # Close an open file in the guest
165 # @handle: filehandle returned by guest-file-open
167 # Returns: Nothing on success.
169 # Since: 0.15.0
171 { 'command': 'guest-file-close',
172   'data': { 'handle': 'int' } }
175 # @GuestFileRead
177 # Result of guest agent file-read operation
179 # @count: number of bytes read (note: count is *before*
180 #         base64-encoding is applied)
182 # @buf-b64: base64-encoded bytes read
184 # @eof: whether EOF was encountered during read operation.
186 # Since: 0.15.0
188 { 'type': 'GuestFileRead',
189   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
192 # @guest-file-read:
194 # Read from an open file in the guest. Data will be base64-encoded
196 # @handle: filehandle returned by guest-file-open
198 # @count: #optional maximum number of bytes to read (default is 4KB)
200 # Returns: @GuestFileRead on success.
202 # Since: 0.15.0
204 { 'command': 'guest-file-read',
205   'data':    { 'handle': 'int', '*count': 'int' },
206   'returns': 'GuestFileRead' }
209 # @GuestFileWrite
211 # Result of guest agent file-write operation
213 # @count: number of bytes written (note: count is actual bytes
214 #         written, after base64-decoding of provided buffer)
216 # @eof: whether EOF was encountered during write operation.
218 # Since: 0.15.0
220 { 'type': 'GuestFileWrite',
221   'data': { 'count': 'int', 'eof': 'bool' } }
224 # @guest-file-write:
226 # Write to an open file in the guest.
228 # @handle: filehandle returned by guest-file-open
230 # @buf-b64: base64-encoded string representing data to be written
232 # @count: #optional bytes to write (actual bytes, after base64-decode),
233 #         default is all content in buf-b64 buffer after base64 decoding
235 # Returns: @GuestFileWrite on success.
237 # Since: 0.15.0
239 { 'command': 'guest-file-write',
240   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
241   'returns': 'GuestFileWrite' }
245 # @GuestFileSeek
247 # Result of guest agent file-seek operation
249 # @position: current file position
251 # @eof: whether EOF was encountered during file seek
253 # Since: 0.15.0
255 { 'type': 'GuestFileSeek',
256   'data': { 'position': 'int', 'eof': 'bool' } }
259 # @guest-file-seek:
261 # Seek to a position in the file, as with fseek(), and return the
262 # current file position afterward. Also encapsulates ftell()'s
263 # functionality, just Set offset=0, whence=SEEK_CUR.
265 # @handle: filehandle returned by guest-file-open
267 # @offset: bytes to skip over in the file stream
269 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
271 # Returns: @GuestFileSeek on success.
273 # Since: 0.15.0
275 { 'command': 'guest-file-seek',
276   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
277   'returns': 'GuestFileSeek' }
280 # @guest-file-flush:
282 # Write file changes bufferred in userspace to disk/kernel buffers
284 # @handle: filehandle returned by guest-file-open
286 # Returns: Nothing on success.
288 # Since: 0.15.0
290 { 'command': 'guest-file-flush',
291   'data': { 'handle': 'int' } }
294 # @GuestFsFreezeStatus
296 # An enumeration of filesystem freeze states
298 # @thawed: filesystems thawed/unfrozen
300 # @frozen: all non-network guest filesystems frozen
302 # Since: 0.15.0
304 { 'enum': 'GuestFsfreezeStatus',
305   'data': [ 'thawed', 'frozen' ] }
308 # @guest-fsfreeze-status:
310 # Get guest fsfreeze state. error state indicates
312 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
314 # Note: This may fail to properly report the current state as a result of
315 # some other guest processes having issued an fs freeze/thaw.
317 # Since: 0.15.0
319 { 'command': 'guest-fsfreeze-status',
320   'returns': 'GuestFsfreezeStatus' }
323 # @guest-fsfreeze-freeze:
325 # Sync and freeze all freezable, local guest filesystems
327 # Returns: Number of file systems currently frozen. On error, all filesystems
328 # will be thawed.
330 # Since: 0.15.0
332 { 'command': 'guest-fsfreeze-freeze',
333   'returns': 'int' }
336 # @guest-fsfreeze-thaw:
338 # Unfreeze all frozen guest filesystems
340 # Returns: Number of file systems thawed by this call
342 # Note: if return value does not match the previous call to
343 #       guest-fsfreeze-freeze, this likely means some freezable
344 #       filesystems were unfrozen before this call, and that the
345 #       filesystem state may have changed before issuing this
346 #       command.
348 # Since: 0.15.0
350 { 'command': 'guest-fsfreeze-thaw',
351   'returns': 'int' }
354 # @guest-fstrim:
356 # Discard (or "trim") blocks which are not in use by the filesystem.
358 # @minimum:
359 #       Minimum contiguous free range to discard, in bytes. Free ranges
360 #       smaller than this may be ignored (this is a hint and the guest
361 #       may not respect it).  By increasing this value, the fstrim
362 #       operation will complete more quickly for filesystems with badly
363 #       fragmented free space, although not all blocks will be discarded.
364 #       The default value is zero, meaning "discard every free block".
366 # Returns: Nothing.
368 # Since: 1.2
370 { 'command': 'guest-fstrim',
371   'data': { '*minimum': 'int' } }
374 # @guest-suspend-disk
376 # Suspend guest to disk.
378 # This command tries to execute the scripts provided by the pm-utils package.
379 # If it's not available, the suspend operation will be performed by manually
380 # writing to a sysfs file.
382 # For the best results it's strongly recommended to have the pm-utils
383 # package installed in the guest.
385 # This command does NOT return a response on success. There is a high chance
386 # the command succeeded if the VM exits with a zero exit status or, when
387 # running with --no-shutdown, by issuing the query-status QMP command to
388 # to confirm the VM status is "shutdown". However, the VM could also exit
389 # (or set its status to "shutdown") due to other reasons.
391 # The following errors may be returned:
392 #          If suspend to disk is not supported, Unsupported
394 # Notes: It's strongly recommended to issue the guest-sync command before
395 #        sending commands when the guest resumes
397 # Since: 1.1
399 { 'command': 'guest-suspend-disk', 'success-response': 'no' }
402 # @guest-suspend-ram
404 # Suspend guest to ram.
406 # This command tries to execute the scripts provided by the pm-utils package.
407 # If it's not available, the suspend operation will be performed by manually
408 # writing to a sysfs file.
410 # For the best results it's strongly recommended to have the pm-utils
411 # package installed in the guest.
413 # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
414 # command.  Thus, it's *required* to query QEMU for the presence of the
415 # 'system_wakeup' command before issuing guest-suspend-ram.
417 # This command does NOT return a response on success. There are two options
418 # to check for success:
419 #   1. Wait for the SUSPEND QMP event from QEMU
420 #   2. Issue the query-status QMP command to confirm the VM status is
421 #      "suspended"
423 # The following errors may be returned:
424 #          If suspend to ram is not supported, Unsupported
426 # Notes: It's strongly recommended to issue the guest-sync command before
427 #        sending commands when the guest resumes
429 # Since: 1.1
431 { 'command': 'guest-suspend-ram', 'success-response': 'no' }
434 # @guest-suspend-hybrid
436 # Save guest state to disk and suspend to ram.
438 # This command requires the pm-utils package to be installed in the guest.
440 # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
441 # command.  Thus, it's *required* to query QEMU for the presence of the
442 # 'system_wakeup' command before issuing guest-suspend-hybrid.
444 # This command does NOT return a response on success. There are two options
445 # to check for success:
446 #   1. Wait for the SUSPEND QMP event from QEMU
447 #   2. Issue the query-status QMP command to confirm the VM status is
448 #      "suspended"
450 # The following errors may be returned:
451 #          If hybrid suspend is not supported, Unsupported
453 # Notes: It's strongly recommended to issue the guest-sync command before
454 #        sending commands when the guest resumes
456 # Since: 1.1
458 { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
461 # @GuestIpAddressType:
463 # An enumeration of supported IP address types
465 # @ipv4: IP version 4
467 # @ipv6: IP version 6
469 # Since: 1.1
471 { 'enum': 'GuestIpAddressType',
472   'data': [ 'ipv4', 'ipv6' ] }
475 # @GuestIpAddress:
477 # @ip-address: IP address
479 # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
481 # @prefix: Network prefix length of @ip-address
483 # Since: 1.1
485 { 'type': 'GuestIpAddress',
486   'data': {'ip-address': 'str',
487            'ip-address-type': 'GuestIpAddressType',
488            'prefix': 'int'} }
491 # @GuestNetworkInterface:
493 # @name: The name of interface for which info are being delivered
495 # @hardware-address: Hardware address of @name
497 # @ip-addresses: List of addresses assigned to @name
499 # Since: 1.1
501 { 'type': 'GuestNetworkInterface',
502   'data': {'name': 'str',
503            '*hardware-address': 'str',
504            '*ip-addresses': ['GuestIpAddress'] } }
507 # @guest-network-get-interfaces:
509 # Get list of guest IP addresses, MAC addresses
510 # and netmasks.
512 # Returns: List of GuestNetworkInfo on success.
514 # Since: 1.1
516 { 'command': 'guest-network-get-interfaces',
517   'returns': ['GuestNetworkInterface'] }