Diff for /qemu/qapi-schema-guest.json between versions 1.1.1.1 and 1.1.1.2

version 1.1.1.1, 2018/04/24 18:56:29 version 1.1.1.2, 2018/04/24 19:34:52
Line 1 Line 1
 # *-*- Mode: Python -*-*  # *-*- Mode: Python -*-*
   
 ##  ##
   #
   # Echo back a unique integer value, and prepend to response a
   # leading sentinel byte (0xFF) the client can check scan for.
   #
   # This is used by clients talking to the guest agent over the
   # wire to ensure the stream is in sync and doesn't contain stale
   # data from previous client. It must be issued upon initial
   # connection, and after any client-side timeouts (including
   # timeouts on receiving a response to this command).
   #
   # After issuing this request, all guest agent responses should be
   # ignored until the response containing the unique integer value
   # the client passed in is returned. Receival of the 0xFF sentinel
   # byte must be handled as an indication that the client's
   # lexer/tokenizer/parser state should be flushed/reset in
   # preparation for reliably receiving the subsequent response. As
   # an optimization, clients may opt to ignore all data until a
   # sentinel value is receiving to avoid unnecessary processing of
   # stale data.
   #
   # Similarly, clients should also precede this *request*
   # with a 0xFF byte to make sure the guest agent flushes any
   # partially read JSON data from a previous client connection.
   #
   # @id: randomly generated 64-bit integer
   #
   # Returns: The unique integer id passed in by the client
   #
   # Since: 1.1
   # ##
   { 'command': 'guest-sync-delimited'
     'data':    { 'id': 'int' },
     'returns': 'int' }
   
   ##
 # @guest-sync:  # @guest-sync:
 #  #
 # Echo back a unique integer value  # Echo back a unique integer value
Line 13 Line 48
 # partially-delivered JSON text in such a way that this response  # partially-delivered JSON text in such a way that this response
 # can be obtained.  # can be obtained.
 #  #
 # Such clients should also preceed this command  # In cases where a partial stale response was previously
 # with a 0xFF byte to make such the guest agent flushes any  # received by the client, this cannot always be done reliably.
   # One particular scenario being if qemu-ga responses are fed
   # character-by-character into a JSON parser. In these situations,
   # using guest-sync-delimited may be optimal.
   #
   # For clients that fetch responses line by line and convert them
   # to JSON objects, guest-sync should be sufficient, but note that
   # in cases where the channel is dirty some attempts at parsing the
   # response may result in a parser error.
   #
   # Such clients should also precede this command
   # with a 0xFF byte to make sure the guest agent flushes any
 # partially read JSON data from a previous session.  # partially read JSON data from a previous session.
 #  #
 # @id: randomly generated 64-bit integer  # @id: randomly generated 64-bit integer
Line 37 Line 83
 { 'command': 'guest-ping' }  { 'command': 'guest-ping' }
   
 ##  ##
   # @GuestAgentCommandInfo:
   #
   # Information about guest agent commands.
   #
   # @name: name of the command
   #
   # @enabled: whether command is currently enabled by guest admin
   #
   # Since 1.1.0
   ##
   { 'type': 'GuestAgentCommandInfo',
     'data': { 'name': 'str', 'enabled': 'bool' } }
   
   ##
   # @GuestAgentInfo
   #
   # Information about guest agent.
   #
   # @version: guest agent version
   #
   # @supported_commands: Information about guest agent commands
   #
   # Since 0.15.0
   ##
   { 'type': 'GuestAgentInfo',
     'data': { 'version': 'str',
               'supported_commands': ['GuestAgentCommandInfo'] } }
   ##
 # @guest-info:  # @guest-info:
 #  #
 # Get some information about the guest agent.  # Get some information about the guest agent.
 #  #
   # Returns: @GuestAgentInfo
   #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'type': 'GuestAgentInfo', 'data': {'version': 'str'} }  
 { 'command': 'guest-info',  { 'command': 'guest-info',
   'returns': 'GuestAgentInfo' }    'returns': 'GuestAgentInfo' }
   
Line 51 Line 126
 # @guest-shutdown:  # @guest-shutdown:
 #  #
 # Initiate guest-activated shutdown. Note: this is an asynchronous  # Initiate guest-activated shutdown. Note: this is an asynchronous
 # shutdown request, with no guaruntee of successful shutdown. Errors  # shutdown request, with no guarantee of successful shutdown.
 # will be logged to guest's syslog.  
 #  #
 # @mode: #optional "halt", "powerdown" (default), or "reboot"  # @mode: #optional "halt", "powerdown" (default), or "reboot"
 #  #
 # Returns: Nothing on success  # This command does NOT return a response on success. Success condition
   # is indicated by the VM exiting with a zero exit status or, when
   # running with --no-shutdown, by issuing the query-status QMP command
   # to confirm the VM status is "shutdown".
 #  #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' } }  { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
     'success-response': 'no' }
   
 ##  ##
 # @guest-file-open:  # @guest-file-open:
Line 94 Line 172
   'data': { 'handle': 'int' } }    'data': { 'handle': 'int' } }
   
 ##  ##
   # @GuestFileRead
   #
   # Result of guest agent file-read operation
   #
   # @count: number of bytes read (note: count is *before*
   #         base64-encoding is applied)
   #
   # @buf-b64: base64-encoded bytes read
   #
   # @eof: whether EOF was encountered during read operation.
   #
   # Since: 0.15.0
   ##
   { 'type': 'GuestFileRead',
     'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
   
   ##
 # @guest-file-read:  # @guest-file-read:
 #  #
 # Read from an open file in the guest. Data will be base64-encoded  # Read from an open file in the guest. Data will be base64-encoded
Line 102 Line 197
 #  #
 # @count: #optional maximum number of bytes to read (default is 4KB)  # @count: #optional maximum number of bytes to read (default is 4KB)
 #  #
 # Returns: GuestFileRead on success. Note: count is number of bytes read  # Returns: @GuestFileRead on success.
 #          *before* base64 encoding bytes read.  
 #  #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'type': 'GuestFileRead',  
   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }  
   
 { 'command': 'guest-file-read',  { 'command': 'guest-file-read',
   'data':    { 'handle': 'int', '*count': 'int' },    'data':    { 'handle': 'int', '*count': 'int' },
   'returns': 'GuestFileRead' }    'returns': 'GuestFileRead' }
   
 ##  ##
   # @GuestFileWrite
   #
   # Result of guest agent file-write operation
   #
   # @count: number of bytes written (note: count is actual bytes
   #         written, after base64-decoding of provided buffer)
   #
   # @eof: whether EOF was encountered during write operation.
   #
   # Since: 0.15.0
   ##
   { 'type': 'GuestFileWrite',
     'data': { 'count': 'int', 'eof': 'bool' } }
   
   ##
 # @guest-file-write:  # @guest-file-write:
 #  #
 # Write to an open file in the guest.  # Write to an open file in the guest.
Line 126 Line 232
 # @count: #optional bytes to write (actual bytes, after base64-decode),  # @count: #optional bytes to write (actual bytes, after base64-decode),
 #         default is all content in buf-b64 buffer after base64 decoding  #         default is all content in buf-b64 buffer after base64 decoding
 #  #
 # Returns: GuestFileWrite on success. Note: count is the number of bytes  # Returns: @GuestFileWrite on success.
 #          base64-decoded bytes written  
 #  #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'type': 'GuestFileWrite',  
   'data': { 'count': 'int', 'eof': 'bool' } }  
 { 'command': 'guest-file-write',  { 'command': 'guest-file-write',
   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },    'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
   'returns': 'GuestFileWrite' }    'returns': 'GuestFileWrite' }
   
   
   ##
   # @GuestFileSeek
   #
   # Result of guest agent file-seek operation
   #
   # @position: current file position
   #
   # @eof: whether EOF was encountered during file seek
   #
   # Since: 0.15.0
   ##
   { 'type': 'GuestFileSeek',
     'data': { 'position': 'int', 'eof': 'bool' } }
   
 ##  ##
 # @guest-file-seek:  # @guest-file-seek:
 #  #
Line 150 Line 268
 #  #
 # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()  # @whence: SEEK_SET, SEEK_CUR, or SEEK_END, as with fseek()
 #  #
 # Returns: GuestFileSeek on success.  # Returns: @GuestFileSeek on success.
 #  #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'type': 'GuestFileSeek',  
   'data': { 'position': 'int', 'eof': 'bool' } }  
   
 { 'command': 'guest-file-seek',  { 'command': 'guest-file-seek',
   'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },    'data':    { 'handle': 'int', 'offset': 'int', 'whence': 'int' },
   'returns': 'GuestFileSeek' }    'returns': 'GuestFileSeek' }
Line 176 Line 291
   'data': { 'handle': 'int' } }    'data': { 'handle': 'int' } }
   
 ##  ##
   # @GuestFsFreezeStatus
   #
   # An enumation of filesystem freeze states
   #
   # @thawed: filesystems thawed/unfrozen
   #
   # @frozen: all non-network guest filesystems frozen
   #
   # Since: 0.15.0
   ##
   { 'enum': 'GuestFsfreezeStatus',
     'data': [ 'thawed', 'frozen' ] }
   
   ##
 # @guest-fsfreeze-status:  # @guest-fsfreeze-status:
 #  #
 # Get guest fsfreeze state. error state indicates failure to thaw 1 or more  # Get guest fsfreeze state. error state indicates
 # previously frozen filesystems, or failure to open a previously cached  
 # filesytem (filesystem unmounted/directory changes, etc).  
 #  #
 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)  # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined below)
 #  #
   # Note: This may fail to properly report the current state as a result of
   # some other guest processes having issued an fs freeze/thaw.
   #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'enum': 'GuestFsfreezeStatus',  
   'data': [ 'thawed', 'frozen', 'error' ] }  
 { 'command': 'guest-fsfreeze-status',  { 'command': 'guest-fsfreeze-status',
   'returns': 'GuestFsfreezeStatus' }    'returns': 'GuestFsfreezeStatus' }
   
 ##  ##
 # @guest-fsfreeze-freeze:  # @guest-fsfreeze-freeze:
 #  #
 # Sync and freeze all non-network guest filesystems  # Sync and freeze all freezable, local guest filesystems
 #  #
 # Returns: Number of file systems frozen on success  # Returns: Number of file systems currently frozen. On error, all filesystems
   # will be thawed.
 #  #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
Line 206 Line 335
 ##  ##
 # @guest-fsfreeze-thaw:  # @guest-fsfreeze-thaw:
 #  #
 # Unfreeze frozen guest fileystems  # Unfreeze all frozen guest filesystems
   #
   # Returns: Number of file systems thawed by this call
 #  #
 # Returns: Number of file systems thawed  # Note: if return value does not match the previous call to
 #          If error, -1 (unknown error) or -errno  #       guest-fsfreeze-freeze, this likely means some freezable
   #       filesystems were unfrozen before this call, and that the
   #       filesystem state may have changed before issuing this
   #       command.
 #  #
 # Since: 0.15.0  # Since: 0.15.0
 ##  ##
 { 'command': 'guest-fsfreeze-thaw',  { 'command': 'guest-fsfreeze-thaw',
   'returns': 'int' }    'returns': 'int' }
   
   ##
   # @guest-suspend-disk
   #
   # Suspend guest to disk.
   #
   # This command tries to execute the scripts provided by the pm-utils package.
   # If it's not available, the suspend operation will be performed by manually
   # writing to a sysfs file.
   #
   # For the best results it's strongly recommended to have the pm-utils
   # package installed in the guest.
   #
   # This command does NOT return a response on success. There is a high chance
   # the command succeeded if the VM exits with a zero exit status or, when
   # running with --no-shutdown, by issuing the query-status QMP command to
   # to confirm the VM status is "shutdown". However, the VM could also exit
   # (or set its status to "shutdown") due to other reasons.
   #
   # The following errors may be returned:
   #          If suspend to disk is not supported, Unsupported
   #
   # Notes: It's strongly recommended to issue the guest-sync command before
   #        sending commands when the guest resumes
   #
   # Since: 1.1
   ##
   { 'command': 'guest-suspend-disk', 'success-response': 'no' }
   
   ##
   # @guest-suspend-ram
   #
   # Suspend guest to ram.
   #
   # This command tries to execute the scripts provided by the pm-utils package.
   # If it's not available, the suspend operation will be performed by manually
   # writing to a sysfs file.
   #
   # For the best results it's strongly recommended to have the pm-utils
   # package installed in the guest.
   #
   # IMPORTANT: guest-suspend-ram requires QEMU to support the 'system_wakeup'
   # command.  Thus, it's *required* to query QEMU for the presence of the
   # 'system_wakeup' command before issuing guest-suspend-ram.
   #
   # This command does NOT return a response on success. There are two options
   # to check for success:
   #   1. Wait for the SUSPEND QMP event from QEMU
   #   2. Issue the query-status QMP command to confirm the VM status is
   #      "suspended"
   #
   # The following errors may be returned:
   #          If suspend to ram is not supported, Unsupported
   #
   # Notes: It's strongly recommended to issue the guest-sync command before
   #        sending commands when the guest resumes
   #
   # Since: 1.1
   ##
   { 'command': 'guest-suspend-ram', 'success-response': 'no' }
   
   ##
   # @guest-suspend-hybrid
   #
   # Save guest state to disk and suspend to ram.
   #
   # This command requires the pm-utils package to be installed in the guest.
   #
   # IMPORTANT: guest-suspend-hybrid requires QEMU to support the 'system_wakeup'
   # command.  Thus, it's *required* to query QEMU for the presence of the
   # 'system_wakeup' command before issuing guest-suspend-hybrid.
   #
   # This command does NOT return a response on success. There are two options
   # to check for success:
   #   1. Wait for the SUSPEND QMP event from QEMU
   #   2. Issue the query-status QMP command to confirm the VM status is
   #      "suspended"
   #
   # The following errors may be returned:
   #          If hybrid suspend is not supported, Unsupported
   #
   # Notes: It's strongly recommended to issue the guest-sync command before
   #        sending commands when the guest resumes
   #
   # Since: 1.1
   ##
   { 'command': 'guest-suspend-hybrid', 'success-response': 'no' }
   
   ##
   # @GuestIpAddressType:
   #
   # An enumeration of supported IP address types
   #
   # @ipv4: IP version 4
   #
   # @ipv6: IP version 6
   #
   # Since: 1.1
   ##
   { 'enum': 'GuestIpAddressType',
     'data': [ 'ipv4', 'ipv6' ] }
   
   ##
   # @GuestIpAddress:
   #
   # @ip-address: IP address
   #
   # @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6)
   #
   # @prefix: Network prefix length of @ip-address
   #
   # Since: 1.1
   ##
   { 'type': 'GuestIpAddress',
     'data': {'ip-address': 'str',
              'ip-address-type': 'GuestIpAddressType',
              'prefix': 'int'} }
   
   ##
   # @GuestNetworkInterface:
   #
   # @name: The name of interface for which info are being delivered
   #
   # @hardware-address: Hardware address of @name
   #
   # @ip-addresses: List of addresses assigned to @name
   #
   # Since: 1.1
   ##
   { 'type': 'GuestNetworkInterface',
     'data': {'name': 'str',
              '*hardware-address': 'str',
              '*ip-addresses': ['GuestIpAddress'] } }
   
   ##
   # @guest-network-get-interfaces:
   #
   # Get list of guest IP addresses, MAC addresses
   # and netmasks.
   #
   # Returns: List of GuestNetworkInfo on success.
   #
   # Since: 1.1
   ##
   { 'command': 'guest-network-get-interfaces',
     'returns': ['GuestNetworkInterface'] }

Removed from v.1.1.1.1  
changed lines
  Added in v.1.1.1.2


unix.superglobalmegacorp.com